سناریوی رخداد

کیتی از یک رجیستری محلی و سه امتناع مدل

A kit from a local registry, three refusals

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

تیم پلتفرم نخستین کیت نسخه v3 خود را می‌نویسد؛ یک ورک‌لود شل (shell) با یک هاست مجاز، و آن را به رجیستری اختصاصی تیم push می‌کند. در داده‌های ثبت‌شده، یک رجیستری محلی روی localhost:15000 شبیه‌ساز آن است. سپس سه دستور پشت سر هم شکست می‌خورند: دستور sbx kit inspect روی مرجع pushشده اعلام می‌کند کیت قابل نصب نیست، چون منبع آن در فهرست مجاز (allowlist) قرار ندارد. دستور sbx kit inspect روی دایرکتوری سورس تلاش می‌کند آن را بیلد کند، اما با خطای خروجی‌گیر (exporter) متوقف می‌شود. دستور sbx kit validate روی همان دایرکتوری می‌گوید کیت از نوع سورس v3 است و مسیر بارگذاری (load path) هیچ بیلدر کیتی ندارد. یکی از مهندسان نتیجه می‌گیرد که کیت‌های v3 در این نسخه کار نمی‌کنند و پیشنهاد می‌دهد کیت به‌شکل یک میکسین (mixin) نسخه v2 بازنویسی شود.

شما این سه شکست، لاگ‌های بیلد دو فرآیند push با دو بیلدر متفاوت، و خروجی validate را برای یک میکسین v2 از همان ساختار درختی در اختیار دارید.

نسخه
sbx v0.47.0
مدل
none; shell commands inside the sandbox
سخت‌افزار
one Mac with the microVM runtime

شواهد

inspect-of-the-source-directory.txt
title: sbx kit inspect on the v3 source directory
source: manuals/docker-sandboxes-101/capture/out/28-kit-inspect-source.txt
lang: console
note: Read which exporter failed and for which driver.
---
$ sbx kit inspect ./fixtures/kits/hello-kit --json
   → build kit ./fixtures/kits/hello-kit (sbx-kit-src:kit-<id>)
error: build kit ./fixtures/kits/hello-kit: exit status 1 ERROR: failed to build: OCI exporter is not supported for the docker driver. Switch to a different driver, or turn on the containerd image store, and try again. Learn more at https://docs.docker.com/go/build-exporters/
[exit 1]
the-driver-that-worked.txt
title: the start of the build with a docker-container builder
source: manuals/docker-sandboxes-101/capture/out/28-buildx.txt
lines: 1-16
lang: console
note: Read the driver on the second line and the frontend version on the descriptor line.
---
$ docker buildx build --progress=plain -f fixtures/kits/hello-kit/kit.yaml --builder m101-builder -t m101-registry:5000/m101/hello-kit:v1 --push fixtures/kits/hello-kit
#0 building with "m101-builder" instance using docker-container driver
#1 [internal] booting buildkit
#1 pulling image moby/buildkit:buildx-stable-1 done
#1 creating container buildx_buildkit_m101-builder0 done
#1 DONE <dur>
#2 [internal] load build definition from kit.yaml
#2 DONE <dur>
#3 resolve image config for docker-image://docker.io/docker/sandbox-kit:3
#3 DONE <dur>
#4 docker-image://docker.io/docker/sandbox-kit:3@sha256:<digest>
#4 DONE <dur>
#5 [internal] load kit descriptor kit.yaml · sandbox-kit 3.0.0-m.8 (129be2ff)
#5 DONE <dur>
#6 [kit] inline build block
#6 DONE <dur>
the-refused-inspect.txt
title: the two settings that the refused inspect suggests, and its exit code
source: manuals/docker-sandboxes-101/capture/out/28-kit-inspect.txt
lines: 3-5
lang: console
note: The error line above these two is cut; it says the kit's source is not in the allowlist and names the current value docker.io/.
---
  try: sbx settings set kit.allowedSources '["docker.io/","localhost:15000/m101/"]'
   or: sbx settings set kit.allowedSources '["*"]'
[exit 1]
validate-on-the-v2-mixin.txt
title: sbx kit validate on the v2 mixin
source: manuals/docker-sandboxes-101/capture/out/12-validate.txt
lang: console
note: The same command, a different kit generation.
---
$ sbx kit validate ./fixtures/kits/hello-mixin
VALID: ./fixtures/kits/hello-mixin (directory)
[exit 0]
validate-on-the-v3-directory.txt
title: sbx kit validate on the v3 source kit
source: manuals/docker-sandboxes-101/capture/out/13-kit-v3-validate.txt
lang: console
note: The error names the generation and the missing builder.
---
$ sbx kit validate ./fixtures/kits/hello-kit
error: kit ./fixtures/kits/hello-kit is a v3 source kit and this load path has no kit builder configured; artifact validation failed
[exit 1]
what-the-container-driver-exported.txt
title: the export and push steps of the docker-container build
source: manuals/docker-sandboxes-101/capture/out/28-buildx.txt
lines: 29-38
lang: console
note: Count the manifests that the exporter wrote.
---
#13 exporting to image
#13 exporting layers done
#13 exporting manifest sha256:<digest> done
#13 exporting config sha256:<digest> done
#13 exporting attestation manifest sha256:<digest> done
#13 exporting manifest list sha256:<digest> done
#13 pushing manifest for m101-registry:5000/m101/hello-kit:v1@sha256:<digest> done
#13 DONE <dur>
View build details: <url>
[exit 0]
what-the-default-driver-exported.txt
title: the same build with the default driver of the host daemon
source: manuals/docker-sandboxes-101/capture/out/28-buildx-docker-driver.txt
lang: console
note: Compare the export steps with the other build.
---
$ docker buildx build --progress=plain -f fixtures/kits/hello-kit/kit.yaml -t localhost:15000/m101/hello-kit:docker-driver --push fixtures/kits/hello-kit
#0 building with "desktop-linux" instance using docker driver
#1 [internal] load build definition from kit.yaml
#1 DONE <dur>
#2 resolve image config for docker-image://docker.io/docker/sandbox-kit:3
#2 DONE <dur>
#3 docker-image://docker.io/docker/sandbox-kit:3@sha256:<digest>
#3 CACHED
#4 [internal] load kit descriptor kit.yaml · sandbox-kit 3.0.0-m.8 (129be2ff)
#4 DONE <dur>
#5 [kit] inline build block
#5 CACHED
#6 [internal] load metadata for docker.io/docker/sandbox-templates:shell
#6 DONE <dur>
#7 [internal] load .dockerignore
#7 DONE <dur>
#8 [1/2] FROM docker.io/docker/sandbox-templates:shell
#8 DONE <dur>
#9 [internal] load build context
#9 DONE <dur>
#10 [2/2] COPY HELLO.md /home/agent/HELLO.md
#10 CACHED
#11 [kit] stage sources /usr/share/sandbox/kit/kit
#11 CACHED
#12 exporting to image
#12 exporting layers done
#12 writing image sha256:<digest> done
#12 naming to localhost:15000/m101/hello-kit:docker-driver done
#12 DONE <dur>
#13 pushing localhost:15000/m101/hello-kit:docker-driver with docker
#13 DONE <dur>
View build details: <url>
[exit 0]

سؤال‌ها

  1. سه شکست، یک نتیجه‌گیری. پیش از خواندن لاگ‌های بیلد، خطاها را بر اساس مؤلفه‌ای که پیام را صادر کرده دسته‌بندی کنید.
  2. کدام دستورهای sbx kit کیت v3 را می‌پذیرند و کدام‌یک نمی‌پذیرند؟
  3. دو بیلد انجام‌شده از درایورهای متفاوتی استفاده کردند. هر کدام چه چیزی خروجی دادند و کدام نتیجه واقعاً یک کیت است؟
  4. امتناع مدل ناشی از فهرست مجاز از چه چیزی محافظت می‌کند، و شما کدام‌یک از دو تنظیم پیشنهادی را اعمال می‌کنید؟
  5. پس از رفع این سه علت، کیت چطور به ساندباکس می‌رسد، و راهنما اعتراف می‌کند چه چیزی را در داده‌های خود ثبت نکرده است؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. تفکیک نسل‌های کیت. دستور sbx kit validate میکسین v2 را با وضعیت VALID تأیید می‌کند و دایرکتوری v3 را به دلیل اینکه کیت سورس v3 است و بیلدری ندارد، رد می‌کند. طبق حکم مستندات راهنما درباره‌ی تعارض C13، دستورهای validate، pack، push و pull ابزارهای نسل v1 و v2 هستند. کیت v3 یک ایمیج OCI است که با ابزارهای Docker بیلد و push می‌شود. بنابراین شکست validate نقص نرم‌افزاری نیست؛ این دستور اساساً برای این کیت ساخته نشده است.
  2. بررسی لاگ‌های بیلد برای پیدا کردن درایور. بیلدی که موفق بود روی بیلدر docker-container اجرا شد. مرحله‌ی export آن لایه‌ها، یک مانیفست، یک کانفیگ، یک مانیفست تصدیق (attestation manifest) و یک لیست مانیفست نوشت و سپس مانیفست را push کرد. بیلد دیگر روی درایور docker متعلق به دیمن هاست اجرا شد؛ مرحله‌ی export آن یک ایمیج نوشت، نام‌گذاری کرد و با docker عملیات push را انجام داد؛ بدون لیست مانیفست و بدون attestation. مستندات راهنما پس از آن رجیستری را بررسی کرد: درایور پیش‌فرض یک مانیفست اسکیما 2 داکر (Docker schema 2) بدون حاشیه‌نویسی (annotation) فرستاده بود، و ایمیج فاقد حاشیه‌نویسی توصیف‌گر (descriptor annotation) برای هیچ مصرف‌کننده‌ای کیت به شمار نمی‌آید. فرآیند push دوم در ظاهر موفقیت‌آمیز بود، اما چیزی تولید کرد که هیچ ساندباکسی نمی‌تواند از آن استفاده کند.
  3. تحلیل خطای inspect سورس از همین زاویه. دستور sbx kit inspect روی دایرکتوری سورس تلاش کرد کیت را با دیمن هاست بیلد کند، در حالی که خروجی‌گیر OCI روی درایور docker پشتیبانی نمی‌شود. راه‌حل دقیقاً مانند گام 2 است: استفاده از بیلدر docker-container یا مخزن ایمیج containerd که در پیام خطا به آن اشاره شده است.
  4. بررسی قانون پذیرش. امتناع از پذیرش مرجع pushشده از تنظیم kit.allowedSources ناشی می‌شود؛ مقداری که طبق مستندات تعارض C40، از نسخه v0.34.0 به‌طور پیش‌فرض روی docker.io/ تنظیم شده است. پیام خطا دو مقدار پیشنهاد می‌دهد. باید پیشوند رجیستری localhost:15000/m101/ را اضافه کنید و مقدار * را نگذارید؛ چون خود خطا تأکید می‌کند مجاز کردن هر منبع راه‌دور (Remote) توصیه نمی‌شود. سطر توصیف‌گر در بیلد موفق، فرانت‌اند را 3.0.0-m.8 (یک مایلاستون) معرفی می‌کند؛ بنابراین نسخه پین‌شده‌ی فرانت‌اند نیز باید در تیکت ثبت شود.
  5. اجرا بر اساس مرجع. ورک‌لود v3 با دستورهای sbx run یا sbx create و با قرار دادن مرجع به جای نام ایجنت مصرف می‌شود، و یک ساندباکس نمی‌تواند کیت‌های v3 را با کیت‌های v1 یا v2 ترکیب کند. مستندات راهنما صراحتاً می‌گوید هیچ داده‌ی ثبتی وجود ندارد که اجرای کیت v3 توسط sbx را نشان دهد، زیرا کیت ثبت داده هرگز sbx settings را تغییر نمی‌دهد. هنگام گزارش این موضوع را حتماً قید کنید.
نتیجه

سه علت وجود داشت و هیچ‌کدام نقص نسخه منتشرشده نبود. دستورهای کار با دست‌سازه در sbx kit متعلق به ابزارهای v1 و v2 هستند، بنابراین اجرای validate روی دایرکتوری v3 دستور اشتباهی بود. درایور پیش‌فرض بیلد docker نمی‌تواند ایمیج OCI خروجی دهد، در نتیجه خروجی pushشده کیت محسوب نمی‌شود و inspect دایرکتوری سورس هم به همین دلیل شکست می‌خورد؛ در حالی که بیلدر docker-container لیست مانیفست را همراه با حاشیه‌نویسی‌های توصیف‌گر صادر کرد. دیمن نیز کیت‌ها را فقط از پیشوندهای تعریف‌شده در kit.allowedSources می‌پذیرد که پیش‌فرض آن docker.io/ است، پس باید پیشوند رجیستری تیم به آن اضافه شود. با تغییر بیلدر و افزودن پیشوند، کیت از طریق مرجع اجرا می‌شود. بازنویسی کیت به‌شکل میکسین v2 کنار گذاشته می‌شود و تیم ثبت می‌کند که اجرای کیت توسط خودشان نخستین سنجش محسوب می‌شود، زیرا راهنما هیچ موردی ثبت نکرده است.

مسیرهای اشتباه رایج
  • «تنظیم kit.allowedSources روی * تا همه رجیستری‌ها کار کنند.» پیام خطا این گزینه را نام می‌برد اما آن را منع می‌کند. فهرست مجاز تنها سد کنترلی میان یک مرجع تایپ‌شده و کیتی است که یک ساندباکس را کانفیگ می‌کند.
  • «عملیات push با درایور پیش‌فرض موفق شد، پس نسخه داخل رجیستری مشکلی ندارد.» این عملیات ایمیجی بدون حاشیه‌نویسی توصیف‌گر push کرد. مصرف‌کننده آن را یک ایمیج معمولی می‌بیند، نه یک کیت.
  • «کیت را به‌صورت میکسین v2 بازنویسی کنیم چون دستور validate آن را قبول می‌کند.» ابزارهای v2 آن را تأیید کردند چون آن کیت واقعاً v2 بود. کیت v3 به Buildx نیاز دارد، نه فرمتی دیگر.
  • «ساندباکس بیلدر کیت را بسازیم و دوباره validate را اجرا کنیم.» در داده‌های ثبت‌شده، بیلد سورس داخل دیمن هاست اجرا شد و وضعیت بیلدر پس از آن not created بود. مسیر validate همچنان فقط دست‌سازه‌های v1 و v2 را مشخص می‌کند.
درس کلی

وقتی یک پدیده‌ی جدید به سه روش مختلف شکست می‌خورد، پیش از قضاوت درباره‌ی آن، مؤلفه‌ی پشت هر پیام خطا را مشخص کنید. بررسی فرمت، خروجی‌گیر بیلد و فهرست پذیرش، سه سیستم کاملاً مجزا هستند و هرکدام راه‌حل خود را دارند. دستور push که پیام موفقیت‌آمیز بازمی‌گرداند، اثبات این نیست که دست‌سازه ساختار موردنیاز مصرف‌کننده‌اش را دارد. مانیفست را دوباره بخوانید.

کجای دوره آموزش داده می‌شود

صفحه توصیف‌گر هر دو بیلد و امتناع مدل بر اساس فهرست مجاز را ثبت کرده است، صفحه دستورهای کیت ابزارهای v2 و تنظیمات کیت را نشان می‌دهد، و دفتر ثبت تعارض‌ها درباره‌ی تعارض‌های C13 و C40 تصمیم‌گیری کرده است.