محتوای آموزشی وبلاگ نت‌آرام
می‌خواهید image را از یک Docker Registry دریافت کنید، اما
docker pull با پیام x509: certificate signed by unknown authority متوقف می‌شود. Docker نتوانسته گواهی TLS مقصد را با یک مرجع مورد اعتماد خودش تأیید کند. ممکن است registry از CA خصوصی سازمان استفاده کند، زنجیره گواهی را ناقص بفرستد یا درخواست از پراکسی‌ای عبور کند که گواهی دیگری ارائه می‌دهد.این خطا را با ثبت registry به‌عنوان
insecure-registry پنهان نکنید. باید بفهمیم کدام بخش Docker به کدام گواهی نیاز دارد و سپس فقط CA معتبر و تأییدشده را در محل مناسب قرار دهیم.در مثال‌ها،
registry.example.com:5000 و نام image فرضی‌اند. نام و پورت واقعی، مسیر پروژه و نسخه نرم‌افزار را از مدیر registry بگیرید. به دسترسی مدیریتی روی ماشینی نیاز دارید که Docker daemon واقعاً آنجا اجرا می‌شود؛ اگر Docker روی سرور دیگری یا در Docker Desktop است، تنظیم روی لپ‌تاپ یا کانتینر برنامه لزوماً daemon را تغییر نمی‌دهد.۱. خطا در کدام مرحله رخ می‌دهد؟
فرمان واقعی ناموفق را مشخص کنید:
کد / دستورdocker pull registry.example.com:5000/team/app:test
نشانی را با registry و image مجاز خود جایگزین کنید. اگر در همین pull خطای x509 می‌گیرید، معمولاً Docker daemon در ارتباط با registry به مشکل اعتماد رسیده است. اگر pull موفق است اما داخل Dockerfile هنگام
RUN curl ... خطا دارید، مشکل ممکن است به مخزن CA داخل image ساخت مربوط باشد. Buildx با builder جداگانه هم می‌تواند تنظیم گواهی مستقل داشته باشد.نام context فعلی را ببینید:
کد / دستورdocker context show
اگر از context راه دور استفاده می‌کنید، محل daemon را با مدیر آن تأیید کنید. نسخه و نوع محیط را هم یادداشت کنید:
کد / دستورdocker version
گزارش Docker و خروجی عیب‌یابی را پیش از اشتراک‌گذاری از نام‌های خصوصی و اطلاعات احراز هویت پاک کنید.
۲. نام، پورت و گواهی ارائه‌شده را بررسی کنید
روی همان میزبان daemon، اتصال HTTPS را با نام واقعی آزمایش کنید:
کد / دستورcurl -Iv https://registry.example.com:5000/v2/
اگر پس از برقراری TLS پاسخ HTTP مانند
401 Unauthorized می‌گیرید، ممکن است registry برای مشاهده API ورود بخواهد؛ این پاسخ به معنی خطای گواهی نیست. اگر curl هم خطای گواهی می‌دهد، علت می‌تواند در گواهی سرور، زنجیره یا اعتماد سیستم باشد. موفقیت curl به‌تنهایی تضمین نمی‌کند BuildKit جداگانه همان CA را دارد.تاریخ سیستم را ببینید:
کد / دستورdate -u
ساعت اشتباه می‌تواند اعتبار زمانی گواهی را به‌اشتباه نامعتبر نشان دهد. برای دیدن زنجیره‌ای که سرور ارائه می‌کند:
کد / دستورopenssl s_client -connect registry.example.com:5000 -servername registry.example.com -showcerts </dev/null
در این دستور
کد / دستور-servername نام SNI را به سرور می‌دهد. خروجی ممکن است چند گواهی و پیام بررسی را نشان دهد؛ صرف دیدن گواهی به معنی معتبر بودن نام و زنجیره نیست. بررسی نام، تاریخ، CA و کامل بودن intermediateها را با مدیر registry انجام دهید. برای نسخه OpenSSL که -verify_hostname را پشتیبانی می‌کند:openssl s_client -connect registry.example.com:5000 -servername registry.example.com -verify_hostname registry.example.com -verify_return_error </dev/null
اگر گواهی برای نام دیگری صادر شده یا منقضی است، نصب CA جدید مشکل نام یا تاریخ را حل نمی‌کند؛ گواهی صحیح و معتبر باید روی registry یا پراکسی جلوی آن نصب شود. اگر سرور زنجیره intermediate ناقص می‌فرستد، مدیر همان سرور باید زنجیره مناسب را اصلاح کند.
۳. آیا registry از CA خصوصی استفاده می‌کند؟
اگر مدیر سازمان می‌گوید گواهی registry با CA خصوصی امضا شده، گواهی عمومی CA را از مسیر تأییدشده دریافت کنید؛ کلید خصوصی CA را لازم ندارید و نباید آن را منتقل کنید. برای فایل نمونه:
کد / دستورopenssl x509 -in organization-root-ca.crt -noout -subject -issuer -dates -fingerprint -sha256
اثر انگشت SHA-256 را به‌صورت کامل از یک مسیر مستقل و مورد اعتماد با مدیر سازمان تطبیق دهید. نام فایل یا نام نمایشی گواهی، اثبات هویت آن نیست. قبل از افزودن هر CA، اثر اعتماد به آن را بفهمید؛ CA اشتباه می‌تواند به گواهی‌های نامعتبر اعتبار بدهد.
برای آزمایش موقت همین CA در OpenSSL، پس از تأیید فایل:
کد / دستورopenssl s_client -connect registry.example.com:5000 -servername registry.example.com -verify_hostname registry.example.com -verify_return_error -CAfile organization-root-ca.crt </dev/null
اگر این بار تأیید کامل موفق شد، CA خصوصی یک مسیر احتمالی برای حل مشکل است. در غیر این صورت، زنجیره، نام و تاریخ را دوباره بررسی کنید. پورت و نام باید با registry واقعی شما مطابقت داشته باشند.
۴. نصب محدود CA برای Docker Engine معمولی در Linux
برای Docker Engine بومی Linux که با دسترسی سیستمی اجرا می‌شود، Docker مسیر
/etc/docker/certs.d/ را برای گواهی‌های registry استفاده می‌کند. نام زیرپوشه باید همان نام و پورت استفاده‌شده در آدرس registry باشد. اگر در فرمان registry را بدون پورت آورده‌اید، پوشه را هم بدون پورت بسازید.ابتدا فهرست پوشه فعلی همان registry را ببینید:
کد / دستورsudo ls -la /etc/docker/certs.d/registry.example.com:5000
اگر پوشه وجود ندارد، دستور ls خطا می‌دهد؛ این مورد به‌تنهایی خطرناک نیست. پس از تأیید نام و CA عمومی، پوشه را ایجاد کنید:
کد / دستورsudo mkdir -p /etc/docker/certs.d/registry.example.com:5000
یک نام فایل جدید انتخاب کنید تا گواهی موجود رونویسی نشود. پیش از کپی:
کد / دستورsudo test ! -e /etc/docker/certs.d/registry.example.com:5000/organization-root-ca.crt
بلافاصله بعد از آن
کد / دستورecho $? را بزنید. خروجی صفر یعنی در زمان آزمون فایلی با این نام دیده نشده است؛ اگر خروجی غیرصفر است، ابتدا فایل موجود و اثرانگشت آن را بررسی کنید یا نام تازه‌ای انتخاب کنید. سپس فقط گواهی عمومی CA تأییدشده را نصب کنید:sudo install -m 0644 organization-root-ca.crt /etc/docker/certs.d/registry.example.com:5000/organization-root-ca.crt
پسوند
.crt برای CA مهم است؛ Docker فایل .cert را به‌عنوان گواهی مشتری تلقی می‌کند و ممکن است دنبال کلید خصوصی همراه آن بگردد. این مسیر محل کلید خصوصی CA نیست. اگر registry علاوه بر اعتماد سرور به گواهی مشتری نیاز دارد، آن یک مسئله جداگانه است و زوج گواهی و کلید مشتری باید با روش امن سازمان تنظیم شود.حالا همان
docker pull را دوباره امتحان کنید. اگر هنوز خطا هست، مطمئن شوید مسیر را روی میزبان daemon درست ساخته‌اید، نام و پورت پوشه دقیق‌اند و فایل PEM معتبر است. با docker context show و اثرانگشت CA دوباره تطبیق دهید. بی‌دلیل Docker daemon را restart نکنید؛ راه‌اندازی مجدد ممکن است روی کانتینرهای در حال کار اثر بگذارد.۵. Docker rootless یا Desktop دارید؟
در Docker rootless روی Linux، مسیر CA اختصاصی registry زیر
$XDG_CONFIG_HOME/docker/certs.d است؛ اگر این متغیر تعریف نشده باشد، مسیر معمول ~/.config/docker/certs.d کاربرِ صاحب daemon است. علامت ~ باید به home همان کاربر اشاره کند، نه لزوماً حسابی که با sudo وارد شده است.در Docker Desktop با Linux containers، روش قرار دادن گواهی روی میزبان و انتقال آن به VM با Engine بومی Linux فرق دارد. مستند نسخه Desktop و سیستم‌عامل خود را دنبال کنید؛ ساختن پوشه در یک VM نامرتبط یا کانتینر برنامه کافی نیست. پس از تنظیم، pull واقعی را از همان context دوباره انجام دهید.
۶. اگر خطا فقط هنگام build رخ می‌دهد
ابتدا ببینید خطا در دریافت base image است یا داخل دستور برنامه در مرحله
کد / دستورRUN. اگر builder شما با driver جداگانه مثل docker-container کار می‌کند، BuildKit می‌تواند برای registry گواهی و تنظیم مستقل داشته باشد. برای دیدن builderهای موجود:docker buildx ls
نام builder مورد استفاده و محیط اجرای آن را با فایل build تطبیق دهید. اگر CA باید به خود BuildKit معرفی شود، از راهنمای رسمی پیکربندی گواهی BuildKit استفاده کنید و مراقب باشید ساخت builder تازه روی محیط کاری دیگران اثر نگذارد.
اگر خطا در
RUN curl داخل image است، اعتماد CA داخل همان image و روش ساخت امن آن باید بررسی شود. نصب CA در certs.d daemon خودکار مخزن اعتماد سیستم‌عامل داخل همه imageها را تغییر نمی‌دهد.۷. تأیید نهایی
پس از اصلاح، بدون غیرفعال کردن تأیید TLS، pull یک tag مجاز و مشخص را تکرار کنید. خطای x509 نباید تکرار شود و image باید به‌طور کامل دریافت شود. سپس image را در محیط آزمایشی اجرا یا بررسی کنید. پاسخ
401 بعدی ممکن است صرفاً به ورود registry مربوط باشد و باید جداگانه با روش ورود مجاز حل شود.اگر گواهی عمومی معتبر است ولی فقط یک مقصد خطا می‌دهد، تنظیم زنجیره همان مقصد را اصلاح کنید؛ اگر همه مقصدها مشکل دارند، ساعت، CAهای سیستم یا پراکسی را جداگانه بررسی کنید. این مراحل برای Docker روی سرور مجازی ایران و سرور اختصاصی ایران کاربرد دارند. تفاوت مسیرها و پسوندهای گواهی در مستند رسمی Docker آمده است.
اشتراک‌گذاری:
لینکدینتلگرامایکس
مقاله قبلی
مقاله قبلی وجود ندارد.
مقاله بعدی
دیدگاه‌ها (۰)
دیدگاه‌های تاییدشده و پاسخ‌های تیم نت‌آرام