نام (NAME)

containers-registries.d - دایرکتوری پیکربندی برای مخازن مختلف رجیستری کانتینر

توضیحات (DESCRIPTION)

دایرکتوری پیکربندی رجیستری‌ها شامل تنظیمات مربوط به رجیستری‌های گوناگون (سرورهای نگهداری ایمیج‌های دوردست کانتینر) و محتوای ذخیره‌شده در آن‌ها است؛ به گونه‌ای که نیازی به ارائه مکرر این تنظیمات در گزینه‌های خط فرمان برای تک‌تک دستورات نباشد و بتواند بین تمامی کاربران containers/image به اشتراک گذاشته شود.

به‌طور پیش‌فرض، پیکربندی registries.d می‌تواند توسط ارائه‌دهنده سیستم در مسیر /usr/share/containers/registries.d/ فراهم شود، توسط مدیر سیستم در مسیر /etc/containers/registries.d/ بازنویسی گردد، و به ازای هر کاربر در مسیر $XDG_CONFIG_HOME/containers/registries.d/ (یا $HOME/.config/containers/registries.d/ در صورت تنظیم نشدن $XDG_CONFIG_HOME) سفارشی‌سازی شود.

دایرکتوری‌های الحاقی ویژه حالت‌های با ریشه (rootful) و بدون ریشه (rootless) نیز در صورت امکان مورد بررسی قرار می‌گیرند:

/usr/share/containers/registries.rootful.d/ (شناسه کاربر UID == 0)
/usr/share/containers/registries.rootless.d/ (شناسه کاربر UID > 0)
/usr/share/containers/registries.rootless.d/<UID>/ (شناسه کاربر UID > 0)
/etc/containers/registries.rootful.d/ (شناسه کاربر UID == 0)
/etc/containers/registries.rootless.d/ (شناسه کاربر UID > 0)
/etc/containers/registries.rootless.d/<UID>/ (شناسه کاربر UID > 0)

تنها فایل‌های با پسوند .yaml خوانده می‌شوند. برنامه‌ها ممکن است امکان استفاده از یک دایرکتوری دیگر را نیز فراهم کنند (برای مثال از طریق بازنویسی صریح).

ساختار دایرکتوری (DIRECTORY STRUCTURE)

این دایرکتوری می‌تواند شامل هر تعداد فایل با پسوند .yaml باشد که هر کدام از قالب YAML پیروی می‌کنند. به‌جز پسوند اجباری، نام فایل‌ها اهمیتی ندارد.

محتوای این فایل‌ها با یکدیگر ادغام می‌شوند؛ به منظور داشتن رفتاری کاملاً مشخص و شفاف، در میان تمام فایل‌ها تنها یک بخش پیکربندی می‌تواند یک فضای نام مشخص در یک رجیستری را توصیف کند (به‌ویژه در میان تمامی فایل‌ها حداکثر یک بخش default-docker می‌تواند وجود داشته باشد و حداکثر یک نمونه از هر کلید در زیر بخش docker مجاز است؛ این بخش‌ها در ادامه توضیح داده شده‌اند).

بنابراین، وجود دو پیکربندی متناقض برای یک رجیستری یا دامنه کاری (scope) واحد ممنوع است؛ همچنین تقسیم پیکربندی یک رجیستری یا دامنه منفرد در بیش از یک فایل نیز ممنوع می‌باشد (حتی اگر از نظر معنایی با هم تناقضی نداشته باشند).

رجیستری‌ها، دامنه‌ها و ترتیب جستجو (REGISTRIES, SCOPES AND SEARCH ORDER)

هر فایل YAML باید شامل یک «نگاشت YAML» (جفت‌های کلید-مقدار) باشد. دو کلید سطح بالا (top-level) تعریف شده‌اند:

•: کلید default-docker یک بخش پیکربندی (مطابق مستندات زیر) برای رجیستری‌های پیاده‌سازی‌کننده "Docker Registry HTTP API V2" است.

این کلید اختیاری است.

•: کلید docker یک نگاشت است که رجیستری‌های منفرد پیاده‌سازی‌کننده "Docker Registry HTTP API V2"، یا فضاهای نام و ایمیج‌های منفرد درون این رجیستری‌ها را به عنوان کلید استفاده می‌کند؛ مقدار اختصاص‌یافته به هر یک از این کلیدها یک بخش پیکربندی است.

این کلید اختیاری است.

دامنه‌هایی که با ایمیج‌های منفرد تطابق دارند، ارجاعات نام‌گذاری‌شده داکر به صورت کامل و بسط‌یافته هستند، چه با استفاده از تگ یا شناسه یکتای هش (digest). برای مثال، docker.io/library/busybox:latest (و نه busybox:latest).

دامنه‌های عمومی‌تر، پیشوندهای دامنه‌های مربوط به ایمیج منفرد هستند و یک مخزن (با حذف برچسب یا شناسه هش)، یک فضای نام مخزن، یا یک میزبان رجیستری (و پورت آن در صورت تفاوت با پیش‌فرض) را مشخص می‌کنند.

توجه داشته باشید که اگر به یک رجیستری از طریق پیکربندی hostname+port دسترسی پیدا شود، نام میزبان بدون پورت به عنوان دامنه والد استفاده نمی‌شود.

هنگام جستجو برای یافتن پیکربندی قابل اعمال بر روی یک ایمیج کانتینر منفرد، تنها پیکربندی دقیق‌ترین دامنه منطبق استفاده می‌شود؛ و پیکربندی‌های دارای دامنه‌های عمومی‌تر نادیده گرفته می‌شوند. برای مثال، اگر هرگونه پیکربندی برای docker.io/library/busybox وجود داشته باشد، پیکربندی مربوط به docker.io نادیده گرفته خواهد شد (حتی اگر بخشی از پیکربندی برای docker.io تعریف شده باشد و برای docker.io/library/busybox وجود نداشته باشد).

پیش‌فرض‌های توکار (Built-in Defaults)

اگر هیچ بخش docker برای ایمیج کانتینر پیدا نشود و بخش default-docker نیز پیکربندی نشده باشد:

دایرکتوری پیش‌فرض، /var/lib/containers/sigstore برای کاربر ریشه و $HOME/.local/share/containers/sigstore برای کاربر غیرممتاز، جهت خواندن و نوشتن امضاها استفاده خواهد شد.
پیوست‌های Sigstore خوانده یا نوشته نخواهند شد.

بخش‌های پیکربندی منفرد (INDIVIDUAL CONFIGURATION SECTIONS)

یک بخش پیکربندی منفرد برای یک ایمیج کانتینر با استفاده از فرآیند شرح‌داده‌شده در بالا انتخاب می‌شود. بخش پیکربندی یک نگاشت YAML با کلیدهای زیر است:

•: کلید lookaside-staging یک نشانی وب (URL) از فضای ذخیره‌سازی امضا تعیین می‌کند که برای ویرایش آن (افزودن یا حذف امضاها) استفاده می‌شود.

این کلید اختیاری است؛ اگر وجود نداشته باشد، کلید lookaside در زیر استفاده خواهد شد.

•: کلید lookaside یک نشانی وب از فضای ذخیره‌سازی امضا مشخص می‌کند. این URL برای خواندن امضاهای موجود استفاده می‌شود، و اگر lookaside-staging وجود نداشته باشد، برای افزودن یا حذف امضاها نیز به کار می‌رود.

این کلید اختیاری است؛ در صورت عدم وجود، هیچ فضای ذخیره‌سازی امضایی تعریف نمی‌شود (هیچ امضایی همراه ایمیج‌ها بارگیری نمی‌شود، و افزودن امضاهای جدید تنها در صورتی ممکن است که lookaside-staging تعریف شده باشد).

•: کلید use-sigstore-attachments مشخص می‌کند که آیا پیوست‌های ایمیج sigstore (امضاها، تاییدیه‌ها و موارد مشابه) همراه با ایمیج خوانده/نوشته شوند یا خیر. در صورت غیرفعال بودن، با ایمیج‌ها به گونه‌ای رفتار می‌شود که گویی هیچ پیوستی وجود ندارد؛ تلاش‌ها برای نوشتن پیوست با شکست مواجه خواهد شد.

مثال‌ها (EXAMPLES)

استفاده از کانتینرها از منابع گوناگون

مثال زیر نحوه استفاده و اجرای ایمیج‌ها از رجیستری‌ها و فضاهای نام مختلف را نشان می‌دهد:

docker:
    registry.database-supplier.com:
        lookaside: https://lookaside.database-supplier.com
    distribution.great-middleware.org:
        lookaside: https://security-team.great-middleware.org/lookaside
    docker.io/web-framework:
        lookaside: https://lookaside.web-framework.io:8080

توسعه و امضای کانتینرها، مرحله‌بندی امضاها

برای توسعه‌دهندگان در example.com:

بیشتر ایمیج‌های کانتینر با استفاده از سرورهای عمومی که کاربران نیز استفاده می‌کنند، دریافت شوند.
استفاده از یک فضای ذخیره‌سازی امضای جداگانه برای ایمیج‌های کانتینر در یک فضای نام مربوط به بخش توسعه‌دهندگان، همراه با فضای مرحله‌بندی (staging) که پیش از انتشار امضاها استفاده می‌شود.

ایجاد یک استثنای اختصاصی برای یک شاخه منفرد که یک توسعه‌دهنده خاص به صورت محلی بر روی آن کار می‌کند.

docker:
    registry.example.com:
        lookaside: https://registry-lookaside.example.com
    registry.example.com/mydepartment:
        lookaside: https://lookaside.mydepartment.example.com
        lookaside-staging: file:///mnt/mydepartment/lookaside-staging
    registry.example.com/mydepartment/myproject:mybranch:
        lookaside: http://localhost:4242/lookaside
        lookaside-staging: file:///home/useraccount/webroot/lookaside

یک پیش‌فرض عمومی و سراسری

اگر شرکتی محصولات خود را با دامنه‌ای متفاوت و نام میزبان رجیستری متمایز برای هر یک از آن‌ها منتشر کند، همچنان می‌توان از یک سرور ذخیره‌سازی امضای واحد بدون نیاز به فهرست کردن تک‌تک دامنه‌ها استفاده کرد. انتظار می‌رود این حالت به ندرت پیش بیاید و معمولاً تنها برای مرحله‌بندی امضاهای جدید کاربرد دارد.

default-docker:
    lookaside-staging: file:///mnt/company/common-lookaside-staging

نویسندگان (AUTHORS)

Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩