نام (NAME)

oci-hooks - دایرکتوری‌های پیکربندی قلاب‌های (hooks) مبتنی بر OCI

خلاصه دستور (SYNOPSIS)

/usr/share/containers/oci/hooks.d/*.json

توضیحات (DESCRIPTION)

روشی را برای کاربران فراهم می‌کند تا قلاب‌های مد نظر برای کانتینرهای «ابتکار کانتینر باز» (Open Container Initiative) را به گونه‌ای پیکربندی کنند که فقط برای کانتینرهایی که به عملکرد آن‌ها نیاز دارند و تنها در مراحلی که مورد نیاز هستند اجرا شوند.

دایرکتوری‌ها (DIRECTORIES)

قلاب‌ها با استفاده از فایل‌های JSON (با پسوند .json) در مجموعه‌ای از دایرکتوری‌های قلاب پیکربندی می‌شوند. دایرکتوری پیش‌فرض /usr/share/containers/oci/hooks.d است، اما ابزارهایی که این ساختار را مصرف می‌کنند ممکن است این پیش‌فرض را تغییر دهند، دایرکتوری‌های اضافی را در بر گیرند یا روش‌هایی را برای تنظیم دایرکتوری‌های پیکربندی در اختیار فراخواننده‌های خود قرار دهند.

اگر چندین دایرکتوری پیکربندی شده باشند، نام یک فایل JSON در یک دایرکتوری با اولویت بالاتر، ورودی‌های دارای همان نام فایل در دایرکتوری‌های با اولویت پایین‌تر را می‌پوشاند (mask می‌کند). به عنوان مثال، اگر یک ابزار مصرف‌کننده قلاب‌ها را در /etc/containers/oci/hooks.d و /usr/share/containers/oci/hooks.d (به ترتیب کاهش اولویت) جستجو کند، آنگاه تعریف قلاب در /etc/containers/oci/hooks.d/01-my-hook.json هر تعریفی در /usr/share/containers/oci/hooks.d/01-my-hook.json را پوشش خواهد داد.

ابزارهایی که از این ساختار استفاده می‌کنند همچنین می‌توانند دایرکتوری‌های قلاب را برای تغییرات تحت نظر بگیرند؛ در این صورت، بدون نیاز به راه‌اندازی مجدد یا ارسال سیگنال، متوجه افزوده‌شدن، تغییرات و حذف فایل‌های JSON خواهند شد. هنگامی که ابزار چندین دایرکتوری قلاب را نظارت می‌کند، تقدم و اولویت بحث‌شده در پاراگراف پیشین همچنان اعمال می‌شود. به عنوان مثال، اگر یک ابزار مصرف‌کننده قلاب‌ها را در /etc/containers/oci/hooks.d و /usr/share/containers/oci/hooks.d (به ترتیب اولویت کاهشی) بررسی کند، نوشتن تعریف جدید یک قلاب در /etc/containers/oci/hooks.d/01-my-hook.json قلابی را که قبلاً از /usr/share/containers/oci/hooks.d/01-my-hook.json بارگذاری شده بود پنهان می‌کند. تغییرات بعدی روی /usr/share/containers/oci/hooks.d/01-my-hook.json تا زمانی که /etc/containers/oci/hooks.d/01-my-hook.json وجود دارد هیچ تأثیری بر ابزار نخواهد داشت. حذف /etc/containers/oci/hooks.d/01-my-hook.json سبب بارگذاری مجدد قلاب از /usr/share/containers/oci/hooks.d/01-my-hook.json خواهد شد.

قلاب‌ها به ترتیبی تزریق می‌شوند که از مرتب‌سازی نام فایل‌های JSON، پس از تبدیل به حروف کوچک و بر اساس کدهای یونیکد آن‌ها، به دست می‌آید. برای نمونه، یک قلاب منطبق تعریف‌شده در 01-my-hook.json پیش از قلاب‌های منطبق تعریف‌شده در 02-another-hook.json و 01-UPPERCASE.json تزریق خواهد شد. اکیداً توصیه می‌شود که ترتیب مرتب‌سازی را با تکیه بر یک پیشوند کاملاً اسکی (مانند 01/02 در بالا) واضح و بدون ابهام سازید.

هر فایل JSON باید حاوی شیئی مطابق با یکی از طرح‌واره‌های (schemas) زیر باشد.

طرح‌واره قلاب ۱.۰.۰ (1.0.0 Hook Schema)

version (رشته الزامی)
نسخه تعریف قلاب را تعیین می‌کند. برای نسخه این طرح‌واره، مقدار باید 1.0.0 باشد.

hook (شیء الزامی)
قلاب مورد نظر برای تزریق، همراه با طرح‌واره ورودی قلاب تعریف‌شده توسط مشخصات زمان اجرای OCI نسخه 1.0.2.

when (شیء الزامی)
شرایطی که تحت آن قلاب تزریق می‌شود. ویژگی‌های زیر می‌توانند مشخص شوند و حداقل یکی از آن‌ها باید تعیین گردد:

always (بولی اختیاری)
اگر برابر با true تنظیم شود، این شرط منطبق می‌گردد.
annotations (شیء اختیاری)
اگر تمام جفت‌های کلید/مقدار annotations با یک جفت کلید/مقدار از یادداشت‌های پیکربندی‌شده مطابقت داشته باشند، این شرط برقرار است.
هر دو کلیدها و مقادیر باید عبارات باقاعده گسترده POSIX باشند.
commands (آرایه‌ای اختیاری از رشته‌ها)
اگر مقدار پیکربندی‌شده process.args[0] با یک ورودی مطابقت داشته باشد، این شرط برقرار می‌شود.
ورودی‌ها باید عبارات باقاعده گسترده POSIX باشند.
hasBindMounts (بولی اختیاری)
اگر hasBindMounts برابر با true باشد و فراخواننده درخواست اتصالات متصل‌شونده (bind mounts) میزبان به کانتینر را داده باشد، این شرط برقرار است.

stages (آرایه‌ای الزامی از رشته‌ها)
مراحلی که قلاب باید در طول آن‌ها تزریق شود. ورودی‌ها باید از مراحل قلاب مشخصات زمان اجرای OCI نسخه 1.0.2 یا از مراحل توسعه‌یافته پشتیبانی‌شده توسط مصرف‌کننده بسته انتخاب شوند.

اگر تمام شرایط تعیین‌شده در when برقرار باشند، آنگاه hook باید در مراحلی که در stages مشخص شده‌اند تزریق گردد.

طرح‌واره قلاب ۰.۱.۰ (0.1.0 Hook Schema)

hook (رشته الزامی)
مقدار path را در قلاب تزریق‌شده مشخص می‌کند.

arguments (آرایه‌ای اختیاری از رشته‌ها)
آرگومان‌های اضافی برای ارسال به قلاب. آرگومان‌های args قلاب تزریق‌شده در واقع همان hook به همراه arguments اضافه شده است.

stages (آرایه‌ای الزامی از رشته‌ها)
مراحلی که قلاب باید تزریق شود. stage یک مترادف مجاز برای این ویژگی است، اما نباید همزمان هر دوی stages و stage را تعیین کنید. ورودی‌ها باید از مراحل قلاب مشخصات زمان اجرای OCI نسخه 1.0.2 یا مراحل توسعه پشتیبانی‌شده توسط مصرف‌کننده بسته انتخاب شوند.

cmds (آرایه‌ای اختیاری از رشته‌ها)
اگر مقدار پیکربندی‌شده process.args[0] با یک ورودی تطابق داشته باشد، قلاب باید تزریق شود. cmd مترادفی مجاز برای این مشخصه است، اما نباید هر دوی cmds و cmd را با هم تنظیم کنید. ورودی‌ها باید عبارات باقاعده گسترده POSIX باشند.

annotations (آرایه‌ای اختیاری از رشته‌ها)
اگر یک ورودی annotations با مقداری از یادداشت‌های پیکربندی‌شده مطابقت داشته باشد، قلاب باید تزریق شود. annotation مترادفی مجاز برای این ویژگی است، اما نباید همزمان annotations و annotation را با هم مشخص نمایید. ورودی‌ها باید عبارات باقاعده تعمیم‌یافته POSIX باشند.

hasbindmounts (بولی اختیاری)
اگر hasBindMounts برابر با true باشد و فراخواننده درخواست اتصالات بایند میزبان به کانتینر را داده باشد، قلاب باید تزریق شود.

مثال‌ها (EXAMPLES)

طرح‌واره قلاب ۱.۰.۰

پیکربندی زیر قلاب oci-systemd-hook را در مراحل پیش از شروع (pre-start) و پس از توقف (post-stop) تزریق می‌کند، در صورتی که process.args[0] به /init یا /systemd ختم شود:

$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
  },
  "when": {
    "commands": [".*/init$" , ".*/systemd$"]
  },
  "stages": ["prestart", "poststop"]
}

مثال زیر در صورت پیکربندی کانتینر برای متصل کردن دایرکتوری‌های میزبان به داخل کانتینر (bind-mount)، قلاب oci-umount --debug را در مرحله پیش از شروع تزریق می‌کند.

$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-umount",
    "args": ["oci-umount", "--debug"],
  },
  "when": {
    "hasBindMounts": true
  },
  "stages": ["prestart"]
}

مثال زیر دستور nvidia-container-runtime-hook prestart را به همراه متغیرهای محیطی مشخص در مرحله پیش از شروع تزریق می‌کند، اگر کانتینر با یک ورودی annotations پیکربندی شده باشد که کلید آن با ^com\.example\.department$ و مقدار آن با .*fluid-dynamics.* مطابقت کند.

$ cat /etc/containers/oci/hooks.d/nvidia.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/sbin/nvidia-container-runtime-hook",
    "args": ["nvidia-container-runtime-hook", "prestart"],
    "env": [
      "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
      "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
    ]
  },
  "when": {
    "annotations": {
      "^com\\.example\\.department$": ".*fluid-dynamics$"
    }
  },
  "stages": ["prestart"]
}

طرح‌واره قلاب ۰.۱.۰

پیکربندی زیر در صورتی که process.args[0] به /init یا /systemd ختم شود، قلاب oci-systemd-hook را در مراحل pre-start و post-stop تزریق می‌نماید:

$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "cmds": [".*/init$" , ".*/systemd$"],
  "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
  "stages": ["prestart", "poststop"]
}

مثال زیر در صورتی که کانتینر برای اتصال دایرکتوری‌های میزبان به داخل کانتینر پیکربندی شده باشد، دستور oci-umount --debug را در مرحله پیش از شروع تزریق می‌کند.

$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "hook": "/usr/libexec/oci/hooks.d/oci-umount",
  "arguments": ["--debug"],
  "hasbindmounts": true,
  "stages": ["prestart"]
}

مثال زیر در صورتی که کانتینر با ورودی annotations که مقدار آن با .*fluid-dynamics.* تطابق دارد پیکربندی شده باشد، قلاب nvidia-container-runtime-hook prestart را در مرحله پیش از شروع تزریق می‌کند.

$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
{
  "hook": "/usr/sbin/nvidia-container-runtime-hook",
  "arguments": ["prestart"],
  "annotations: [".*fluid-dynamics.*"],
  "stages": ["prestart"]
}

همچنین ببینید (SEE ALSO)

oci-systemd-hook(1), oci-umount(1), locale(7)

OCI Runtime Specification, 1.0.2, POSIX-platform hooks ⟨https://github.com/opencontainers/runtime-spec/blob/v1.0.2/config.md#posix-platform-hooks⟩
OCI Runtime Specification, 1.0.2, process ⟨https://github.com/opencontainers/runtime-spec/blob/v1.0.2/config.md#process⟩
POSIX extended regular expressions (EREs) ⟨https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04⟩