تنظیمات عمومی (GLOBAL SETTINGS)

unqualified-search-registries

آرایه‌ای از رجیستری‌های host[:port] که به ترتیب هنگام دریافت (pull) یک ایمیج بدون نام کامل (unqualified) امتحان می‌شوند.

credential-helpers

آرایه‌ای از برنامه‌های کمکی گواهی اعتبارسنجی پیش‌فرض که به عنوان مخازن خارجی گواهی استفاده می‌شوند. توجه داشته باشید که "containers-auth.json" یک مقدار رزروشده برای استفاده از فایل‌های احراز هویت طبق مشخصات containers-auth.json(5) است. در صورت مشخص نشدن هیچ مقداری، برنامه‌های کمکی روی ["containers-auth.json"] تنظیم می‌شوند.

additional-layer-store-auth-helper

رشته‌ای حاوی نام باینری کمکی. این گزینه ارسال اطلاعات اعتبارسنجی رجیستری به یک «مخزن لایه اضافی» (Additional Layer Store) را هر بار که ایمیجی با پروتکل انتقال docker:// خوانده می‌شود، امکان‌پذیر می‌سازد تا بتواند به رجیستری‌های خصوصی دسترسی پیدا کند. برای جزئیات بیشتر به بخش «فعال‌سازی دسترسی Additional Layer Store به رجیستری‌های خصوصی» در زیر مراجعه فرمایید.

تنظیمات دارای فضای نام [[registry]]

بخش عمده پیکربندی به صورت آرایه‌ای از جدول‌های TOML از نوع [[registry]] نمایش داده می‌شود؛ بنابراین تنظیمات ممکن است در میان رجیستری‌های مختلف و همچنین در میان فضاهای نام/مخازن مختلف درون یک رجیستری متفاوت باشد.

انتخاب جدول TOML از نوع [[registry]]

بر اساس نام یک ایمیج، یک جدول TOML از نوع [[registry]] بر مبنای فیلد prefix آن انتخاب می‌شود.

prefix: پیشوندی از نام ایمیج مشخص‌شده توسط کاربر، به یکی از قالب‌های زیر:
- host[:port]
- host[:port]/namespace[/_namespace_…]
- host[:port]/namespace[/_namespace_…]/repo
- host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
- [*.]host

نام ایمیج ارائه‌شده توسط کاربر باید با prefix مشخص‌شده شروع شود (و با جداکننده مناسب ادامه یابد) تا یک جدول TOML از نوع [[registry]] خاص در نظر گرفته شود؛ (تنها) جدول TOML با طولانی‌ترین تطابق استفاده خواهد شد. این مقدار همچنین می‌تواند شامل زیردامنه‌های عمومی با نویسه ستاره (wildcard) در قالب *.example.com باشد. نویسه ستاره فقط باید در ابتدا و مطابق با قالب‌های فوق قرار گیرد. موارد دیگر کار نخواهند کرد؛ برای مثال، *.example.com معتبر است اما example.*.com، *.example.com/foo و *.example.com:5000/foo/bar:baz معتبر نیستند. توجه داشته باشید که * با هر تعداد زیردامنه دلخواه تطابق دارد؛ بنابراین *.example.com با bar.example.com، foo.bar.example.com و غیره مطابقت خواهد داشت.

به عنوان یک حالت خاص، فیلد prefix می‌تواند حذف شود؛ در این صورت، مقدار پیش‌فرض آن برابر با مقدار فیلد location (که در زیر توضیح داده شده) خواهد بود.

تنظیمات به ازای هر فضای نام (Per-namespace settings)

insecure

مقدار true یا false. به طور پیش‌فرض، موتورهای اجرای کانتینر هنگام بازیابی ایمیج‌ها از یک رجیستری به TLS نیاز دارند. اگر insecure برابر با true تنظیم شود، اتصالات HTTP رمزنگاری‌نشده و همچنین اتصالات TLS با گواهینامه‌های غیرقابل اعتماد مجاز خواهند بود.

blocked

مقدار true یا false. اگر true باشد، دریافت (pull) ایمیج‌های دارای نام منطبق ممنوع است.

بازتوزیع و آینه‌سازی رجیستری‌ها (Remapping and mirroring registries)

ارجاع ایمیج مشخص‌شده توسط کاربر در وهله اول یک نام ایمیج «منطقی» است که همواره برای نام‌گذاری ایمیج استفاده می‌شود. به طور پیش‌فرض، ارجاع ایمیج مستقیماً رجیستری و مخزن مورد استفاده را نیز تعیین می‌کند، اما گزینه‌های زیر می‌توانند برای هدایت دسترسی‌های زیرین به سرورها یا مکان‌های رجیستری دیگر استفاده شوند (برای مثال جهت پشتیبانی از پیکربندی‌های بدون دسترسی به اینترنت بدون نیاز به تغییر فایل‌های Dockerfile، یا افزودن افزونگی و پایداری).

location

همان قالب فیلد prefix را می‌پذیرد و مکان فیزیکی فضای نام ریشه‌گرفته از prefix را مشخص می‌کند.

به طور پیش‌فرض، این مقدار برابر با prefix است (که در این حالت می‌توان prefix را حذف کرد و جدول TOML از نوع [[registry]] فقط location را مشخص کند).

مثال: با فرض

prefix = "example.com/foo"
location = "internal-registry-for-example.com/bar"

درخواست‌ها برای ایمیج example.com/foo/myimage:latest در عمل با ایمیج internal-registry-for-example.com/bar/myimage:latest کار خواهند کرد.

در صورتی که prefix شامل نویسه ستاره در قالب "*.example.com" برای تطبیق زیردامنه باشد، مکان می‌تواند خالی باشد. در چنین حالتی، تطبیق پیشوند انجام می‌شود اما هیچ بازنویسی ارجاعی صورت نخواهد گرفت. رشته اولیه ایمیج درخواست‌شده دست‌نخورده استفاده می‌شود، اما سایر تنظیمات مانند insecure / blocked / mirrors بر روی ایمیج‌های منطبق اعمال خواهد شد.

مثال: با فرض

prefix = "*.example.com"

درخواست‌ها برای ایمیج blah.example.com/foo/myimage:latest همان‌طور که هستند استفاده می‌شوند، اما تنظیمات دیگری مانند insecure/blocked/mirrors بر روی ایمیج‌های منطبق اعمال خواهند شد.

mirror

آرایه‌ای از جدول‌های TOML که آینه‌های (احتمالاً جزئی) را برای فضای نام ریشه‌گرفته از prefix (یعنی جدول TOML جاری [[registry]]) مشخص می‌کند.

آینه‌ها به ترتیب مشخص‌شده مورد آزمایش قرار می‌گیرند؛ نخستین آینه‌ای که قابل اتصال باشد و ایمیج را در بر داشته باشد استفاده خواهد شد (و اگر هیچ‌یک از آینه‌ها حاوی ایمیج نباشند، مکان اصلی مشخص‌شده در فیلد registry.location، یا ارجاع دست‌نخورده مشخص‌شده توسط کاربر، به عنوان آخرین گزینه امتحان می‌شود). اگر واکشی لایه‌های باینری (blob) بعداً روی منبع انتخاب‌شده با شکست روبرو شود، منابع باقی‌مانده به طور خودکار امتحان می‌شوند (به بخش جایگزینی آینه در سطح Blob در زیر مراجعه فرمایید).

هر جدول TOML در آرایه mirror می‌تواند شامل فیلدهای زیر باشد: - location: همان معنای مشخص‌شده در جدول TOML از نوع [[registry]] - insecure: همان معنای مشخص‌شده در جدول TOML از نوع [[registry]] - pull-from-mirror: مقادیر all، digest-only یا tag-only. در حالت "digest-only"، آینه‌ها فقط برای دریافت بر اساس هش (digest) استفاده خواهند شد. دریافت ایمیج‌ها بر اساس تگ بسته به اینکه از چه نقطه‌ای ایمیج دریافت شود می‌تواند ایمیج‌های متفاوتی حاصل کند. محدود کردن آینه‌ها به دریافت بر اساس هش از این مشکل جلوگیری می‌کند. در حالت "tag-only"، آینه‌ها فقط برای دریافت بر اساس تگ استفاده خواهند شد. برای یک آینه به‌روزتر و پرهزینه‌تر که کمتر احتمال ناهماهنگی در تغییر تگ‌ها دارد، نباید بی‌دلیل برای ارجاعات بر اساس هش استفاده شود. حالت پیش‌فرض "all" است (یا خالی رها شود)، که در آن آینه‌ها هم برای دریافت با هش و هم با تگ استفاده می‌شوند، مگر اینکه گزینه mirror-by-digest-only برای رجیستری اصلی تنظیم شده باشد. توجه داشته باشید که این تنظیم به ازای هر آینه تنها زمانی مجاز است که mirror-by-digest-only برای رجیستری اصلی تنظیم نشده باشد.

mirror-by-digest-only

مقدار true یا false. اگر true باشد، آینه‌ها تنها زمانی در حین دریافت استفاده می‌شوند که ارجاع ایمیج شامل یک هش (digest) باشد. توجه داشته باشید که اگر همه آینه‌ها روی digest-only تنظیم شوند، ایمیج‌های دارای تگ تنها از رجیستری اصلی استفاده خواهند کرد. اگر همه آینه‌ها روی tag-only تنظیم شوند، ایمیج‌های دارای هش تنها از رجیستری اصلی استفاده خواهند کرد.

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

جایگزینی آینه در سطح Blob (Blob-level mirror fallback)

پس از انتخاب منبع دریافت بر اساس در دسترس بودن مانیفست، دریافت بلوک‌های داده منفرد یا همان لایه‌ها (blobs) ممکن است همچنان با شکست مواجه شود. هنگامی که واکشی یک لایه با یک خطای گذرا (مانند خطای سرور HTTP 5xx یا وقفه زمانی شبکه)، خطای BLOB_UNKNOWN، یا خطای HTTP 429 پس از تلاش‌های مجدد توکار با شکست روبرو شود، منابع پیکربندی‌شده باقی‌مانده به ترتیب آزمایش می‌شوند. در صورت یافتن یک منبع فعال، از آن برای دریافت لایه‌های بعدی در همان عملیات pull استفاده می‌شود.

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

این جایگزینی یا تلاش مجدد افزون بر تلاش مجدد در سطح فراخواننده (مانند بسته retry در containers-common یا تلاش‌های مجدد در kubelet) کار می‌کند. واکشی یک لایه ممکن است پیش از جابجایی یک بار روی همان منبع مجدداً امتحان شود، و فراخواننده ممکن است علاوه بر آن، کل عملیات دریافت را نیز دوباره تکرار کند.

نکته: تغییر مسیر و آینه‌ها در حال حاضر تنها هنگام خواندن یک ایمیج منفرد پردازش می‌شوند، نه هنگام ارسال (push) به یک رجیستری یا انجام هر نوع جستجو/وارسی دیگر در رجیستری. این وضعیت ممکن است در آینده تغییر کند.

نام مستعار برای نام‌های کوتاه (Short-Name Aliasing)

استفاده از رجیستری‌های جستجوی بدون نام کامل (unqualified-search) متضمن ابهام است، زیرا مشخص نیست که یک ایمیج داده‌شده با نام کوتاه از کدام رجیستری باید دریافت شود.

همان‌طور که در یادداشت انتهای این صفحه راهنما اشاره شده است، استفاده از نام‌های کوتاه در معرض خطر تصاحب فضاهای نام رجیستری (namespace squatting) قرار دارد. اگر رجیستری‌های جستجو روی ["registry1.com", "registry2.com"] تنظیم شده باشند، یک مهاجم ممکن است فضای نامی در registry1.com را به تصرف درآورد به طوری که یک ایمیج به جای منبع مورد نظر در registry2.com، از registry1.com دریافت شود.

در حالی که استفاده همیشگی از ارجاعات کامل ایمیج به شدت توصیه می‌شود، ممکن است تغییر پیاده‌سازی‌های موجود که از نام‌های کوتاه استفاده می‌کنند آسان نباشد. برای دور زدن ابهام مذکور، می‌توان اصطلاحاً «نام‌های مستعار کوتاه» (short-name aliases) را پیکربندی کرد که به ارجاع کامل ایمیج اشاره می‌کنند.

نام‌های مستعار کوتاه را می‌توان در جدول [aliases] به صورت "name"="value" پیکربندی کرد که در آن name در سمت چپ همان نام کوتاه (مانند "image") و value در سمت راست همان ارجاع کامل ایمیج (مانند "registry.com/namespace/image") است. توجه داشته باشید که نه "name" و نه "value" نمی‌توانند شامل تگ یا هش باشند. علاوه بر این، "name" باید یک نام کوتاه باشد و بنابراین نمی‌تواند شامل دامنه رجیستری باشد یا به localhost اشاره کند.

هنگام دریافت با یک نام کوتاه، جدول نام‌های مستعار پیکربندی‌شده برای حل نام کوتاه استفاده می‌شود. اگر یک نام مستعار منطبق پیدا شود، بدون مراجعه به فهرست رجیستری‌های جستجوی بدون نام کامل استفاده خواهد شد. اگر نام مستعار منطبقی یافت نشود، رفتار سیستم از طریق گزینه short-name-mode به گونه‌ای که در زیر توضیح داده شده، کنترل می‌شود.

توجه داشته باشید که تگ‌ها و هش‌ها برای حل نام مستعار از نام کوتاه مشخص‌شده توسط کاربر جدا می‌شوند. بنابراین، "image"، "image:tag" و "image@digest" همگی به یک نام مستعار واحد (یعنی "image") حل می‌شوند. تگ‌ها و هش‌های جداشده بعداً به نام مستعار دریافت‌شده متصل خواهند شد.

همچنین توجه داشته باشید که فایل‌های پیکربندی الحاقی (به containers-registries.conf.d(5) مراجعه کنید) می‌توانند نام‌های مستعار را در ترتیب بارگذاری خاص فایل‌ها بازنویسی کنند. اگر مقدار "value" یک نام مستعار خالی باشد (یعنی "")، نام مستعار حذف خواهد شد. با این حال، یک "name" داده‌شده تنها یک بار می‌تواند در یک فایل پیکربندی منفرد مشخص شود.

نام‌های مستعار کوتاه: حالت‌ها (Modes)

گزینه short-name-mode از سه حالت برای کنترل رفتار تفکیک نام‌های کوتاه پشتیبانی می‌کند:

• enforcing: اگر تنها یک رجیستری جستجوی unqualified تنظیم شده باشد، از همان استفاده می‌شود زیرا ابهامی وجود ندارد. اگر بیش از یک رجیستری وجود داشته باشد و برنامه کاربر در ترمینال در حال اجرا باشد (یعنی stdout و stdin یک TTY باشند)، از کاربر خواسته می‌شود یکی از رجیستری‌های جستجوی مشخص‌شده را انتخاب کند. اگر برنامه در ترمینال اجرا نشود، ابهام قابل حل نیست و منجر به خطا خواهد شد.
• permissive: مانند حالت enforcing رفتار می‌کند اما اگر برنامه در ترمینال در حال اجرا نباشد، منجر به بروز خطا نمی‌شود. در عوض، به استفاده از تمامی رجیستری‌های جستجوی unqualified برمی‌گردد.
• disabled: استفاده از تمام رجیستری‌های جستجوی unqualified بدون درخواست از کاربر.

اگر short-name-mode اصلاً مشخص نشده باشد یا خالی رها شود، به طور پیش‌فرض از حالت permissive استفاده می‌شود. اگر نام کوتاه ارائه‌شده توسط کاربر قبلاً دارای نام مستعار نبوده باشد، حالت‌های enforcing و permissive در صورت درخواست تایید از کاربر، پس از یک دریافت موفقیت‌آمیز، یک نام مستعار جدید ثبت خواهند کرد. توجه داشته باشید که نام مستعار ثبت‌شده در مسیر /var/cache/containers/short-name-aliases.conf برای کاربر ریشه نوشته می‌شود تا تفکیک واضحی بین فایل‌های registries.conf که احتمالاً توسط انسان ویرایش شده‌اند و فایل ماشین‌ساز short-name-aliases.conf وجود داشته باشد. برای کاربران بدون ریشه (rootless) از مسیر $HOME/.cache استفاده می‌شود. اگر یک نام مستعار در فایل registries.conf و همچنین در فایل ماشین‌ساز short-name-aliases.conf مشخص شده باشد، اولویت با فایل short-name-aliases.conf خواهد بود.

نرمال‌سازی ارجاعات docker.io

داکر هاب docker.io به شیوه خاصی مدیریت می‌شود: در صورتی که هیچ فضای نام خاص دیگری تعریف نشده باشد (برای مثال در docker.io/namespace/image)، هر عملیات push و pull در داخل به طور خودکار با /library نرمال‌سازی می‌شود.

(توجه داشته باشید که این نرمال‌سازی توصیف‌شده دقیقاً منطبق بر رفتار داکر است.)

این بدان معناست که دریافت docker.io/alpine در داخل به docker.io/library/alpine ترجمه می‌شود. دریافت docker.io/user/alpine بازنویسی نخواهد شد زیرا این آدرس از قبل مسیر دوردست صحیح است.

بنابراین، برای بازنگاشت یا آینه‌سازی ایمیج‌های docker.io در فضای نام (ضمنی) /library (یا کل آن فضای نام)، فیلدهای prefix و location در این فایل پیکربندی باید صریحاً شامل آن فضای نام /library باشند؛ برای مثال prefix = "docker.io/library/alpine" و نه prefix = "docker.io/alpine". حالت دوم با مخازن docker.io/alpine/* تطابق می‌یابد اما با ایمیج docker.io/[library/]alpine مطابقت نخواهد داشت.

مثال (EXAMPLE)

unqualified-search-registries = ["example.com"]
[[registry]]
prefix = "example.com/foo"
insecure = false
blocked = false
location = "internal-registry-for-example.com/bar"
[[registry.mirror]]
location = "example-mirror-0.local/mirror-for-foo"
[[registry.mirror]]
location = "example-mirror-1.local/mirrors/foo"
insecure = true
[[registry]]
location = "registry.com"
[[registry.mirror]]
location = "mirror.registry.com"

با توجه به تنظیمات بالا، دریافت ایمیج example.com/foo/image:latest موارد زیر را امتحان می‌کند:

1.

example-mirror-0.local/mirror-for-foo/image:latest

2.

example-mirror-1.local/mirrors/foo/image:latest

3.

internal-registry-for-example.com/bar/image:latest

به ترتیب، و از اولین موردی که بتواند مانیفست را ارائه دهد استفاده خواهد شد. اگر واکشی لایه بعداً روی منبع انتخاب‌شده با شکست مواجه شود، منابع باقی‌مانده مطابق آنچه در بخش جایگزینی آینه در سطح Blob شرح داده شد، امتحان می‌شوند.

توجه داشته باشید که یک آینه تنها با جدول جاری TOML از نوع [[registry]] مرتبط است. با استفاده از مثال بالا، دریافت ایمیج registry.com/image:latest تنها به mirror.registry.com متصل می‌شود و آینه‌های مرتبط با example.com/foo در نظر گرفته نخواهند شد.

فعال‌سازی دسترسی Additional Layer Store به رجیستری‌های خصوصی

گزینه additional-layer-store-auth-helper ارسال اطلاعات اعتبارسنجی رجیستری به یک مخزن لایه اضافی را امکان‌پذیر می‌سازد تا بتواند به رجیستری‌های خصوصی دسترسی پیدا کند.

هنگام دسترسی به یک رجیستری خصوصی از طریق مخزن لایه اضافی، باید یک باینری کمکی ارائه شود. این فایل باینری از طریق گزینه additional-layer-store-auth-helper ثبت می‌شود. هر بار که ایمیجی با پروتکل انتقال docker:// خوانده می‌شود، فایل باینری کمکی مشخص‌شده اجرا می‌شود و اطلاعات اعتبارسنجی رجیستری را از ورودی استاندارد (stdin) در قالب زیر دریافت می‌کند:

{
  "$image_reference": {
    "username": "$username",
    "password": "$password",
    "identityToken": "$identityToken"
  }
}

قالب $image_reference به صورت $repo{:$tag|@$digest} است.

مخازن لایه‌های اضافی می‌توانند از این فایل باینری کمکی برای دسترسی به رجیستری خصوصی استفاده نمایند.

مثال (EXAMPLE)

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

[registries.search]
registries = ['registry1.com', 'registry2.com']
[registries.insecure]
registries = ['registry3.com']
[registries.block]
registries = ['registry.untrusted.com', 'registry.unsafe.com']