Налаштування постачальника облікових даних образів в kubelet

СТАН ФУНКЦІОНАЛУ: Kubernetes v1.26 [stable]

Починаючи з Kubernetes v1.20, kubelet може динамічно отримувати облікові дані для реєстру образів контейнерів за допомогою використання втулків. Kubelet та втулок спілкуються через stdio (stdin, stdout та stderr), використовуючи версійні API Kubernetes. Ці втулки дозволяють kubelet запитувати облікові дані для реєстру контейнерів динамічно, на відміну від зберігання статичних облікових даних на диску. Наприклад, втулок може звертатися до локального сервера метаданих, щоб отримати облікові дані з обмеженим терміном дії для образу, який завантажується kubelet.

Ви можете бути зацікавлені у використанні цієї можливості, якщо будь-яке з нижче перерахованих тверджень є правдивим:

  • Потрібні виклики API до служби хмарного постачальника для отримання інформації для автентифікації реєстру.
  • Облікові дані мають короткий термін дії, і потрібно часто запитувати нові облікові дані.
  • Зберігання облікових даних реєстру на диску або в imagePullSecrets неприпустиме.

Цей посібник демонструє, як налаштувати механізм втулка постачальника облікових даних зображення kubelet.

Токен службового облікового запису для витягування образів

СТАН ФУНКЦІОНАЛУ: Kubernetes v1.33 [alpha] (стандартно увімкнено: false)

Починаючи з Kubernetes v1.33, kubelet можна налаштувати так, щоб надсилати токен службового облікового запису, привʼязаного до того podʼу, для якого виконується отримання образу, до втулка постачальника облікових даних.

Це дозволить втулку обміняти токен на облікові дані для доступу до реєстру образів.

Щоб увімкнути цю можливість, в kubelet має бути увімкнено функціональну можливість KubeletServiceAccountTokenForCredentialProviders, а у файлі CredentialProviderConfig для втулка має бути задано поле tokenAttributes.

Поле tokenAttributes містить інформацію про токен службового облікового запису, який буде передано втулку, включаючи цільову аудиторію для токена і те, чи вимагає втулок, щоб pod мав службовий обліковий запис.

Використання облікових даних службового облікового запису може забезпечити наступні варіанти використання:

  • Уникнення необхідності використання ідентифікатора на основі kubelet/node для отримання образів з реєстру.
  • Дозволити робочим навантаженням отримувати образи на основі їхніх власних ідентифікаторів часу виконання без довготривалих/стійких секретів.

Перш ніж ви розпочнете

  • Вам потрібен кластер Kubernetes з вузлами, які підтримують втулки постачальника облікових даних kubelet. Ця підтримка доступна у Kubernetes 1.33; Kubernetes v1.24 та v1.25 мали це як бета-функцію, яка є типово увімкненою.
  • Якщо ви налаштовуєте втулок постачальника облікових даних, якому потрібен токен службового облікового запису, вам потрібен кластер Kubernetes з вузлами під керуванням Kubernetes v1.33 або новішої версії та ввімкненим на kubelet функціоналом KubeletServiceAccountTokenForCredentialProviders.
  • Робоча реалізація втулка постачальника облікових даних. Ви можете створити власний втулок або використовувати той що, наданий хмарним постачальником.
Версія вашого Kubernetes сервера має бути не старішою ніж v1.26.

Для перевірки версії введіть kubectl version.

Встановлення втулків на вузлах

Втулок постачальника облікових даних — це виконавчий бінарний файл, який kubelet буде використовувати. Переконайтеся, що бінарний файл втулка існує на кожному вузлі вашого кластера і зберігається в відомій теці. Ця тека буде потрібна пізніше при налаштуванні прапорців kubelet.

Налаштування Kubelet

Для використання цієї функції kubelet очікує встановлення двох прапорців:

  • --image-credential-provider-config — шлях до файлу конфігурації втулка постачальника облікових даних.
  • --image-credential-provider-bin-dir — шлях до теки, де знаходяться бінарні файли втулка постачальника облікових даних.

Налаштування постачальника облікових даних kubelet

Файл конфігурації, переданий в --image-credential-provider-config, зчитується kubelet для визначення, які виконавчі втулки слід викликати для яких образів контейнерів. Нижче наведено приклад файлу конфігурації, який ви, можливо, будете використовувати, якщо використовуєте втулок, оснований на ECR:

apiVersion: kubelet.config.k8s.io/v1
kind: CredentialProviderConfig
# providers — це список допоміжних втулків постачальників облікових даних, які будуть активовані
# kubelet. Одному образу може відповідати декілька постачальників, в такому випадку облікові дані
# від усіх постачальників будуть повернуті kubelet. Якщо для одного образу є кілька
# постачальників, результати будуть обʼєднані. Якщо постачальники повертають ключі автентифікації,
# що перекриваються, використовується значення від постачальника, який знаходиться раніше в цьому
# списку.
providers:
  # name — це обовʼязкове імʼя постачальника облікових даних. Воно повинно відповідати імені
  # виконавчого файлу постачальника, яке бачить kubelet. Виконавчий файл повинен знаходитися в
  # теці bin kubelet (встановлено за допомогою прапорця --image-credential-provider-bin-dir).
  - name: ecr-credential-provider
    # matchImages - обовʼязковий список рядків, які використовуються для порівняння з образами, щоб
    # визначити, чи потрібно викликати цього постачальника. Якщо один із рядків відповідає
    # запитаному образу від kubelet, втулок буде викликаний і отримає шанс надати облікові дані.
    # Очікується, що образи містять домен реєстру та URL-шлях.
    #
    # Кожний запис в matchImages — це шаблон, який може необовʼязково містити порт та шлях.
    # Можна використовувати шаблони для домену, але не для порту або шляху. Шаблони підтримуються
    # як піддомени, наприклад, '*.k8s.io' або 'k8s.*.io', так і верхніх рівнів доменів, наприклад,
    # 'k8s.*'. Підтримується також частковий збіг піддоменів, наприклад, 'app*.k8s.io'. Кожен
    # шаблон може відповідати лише одному сегменту піддомену, тому `*.io` **не** відповідає
    # `*.k8s.io`.
    #
    # Збіг існує між образами та matchImage, коли виконуються всі наведені нижче умови:
    # - Обидва мають однакову кількість частин домену і кожна частина має збіг.
    # - URL-шлях matchImages повинен бути префіксом URL-шляху цільового образу.
    # - Якщо matchImages містить порт, то порт також повинен мати збіг в образі.
    # Приклади значент matchImages:
    # - 123456789.dkr.ecr.us-east-1.amazonaws.com
    # - *.azurecr.io
    # - gcr.io
    # - *.*.registry.io
    # - registry.io:8080/path
    matchImages:
      - "*.dkr.ecr.*.amazonaws.com"
      - "*.dkr.ecr.*.amazonaws.com.cn"
      - "*.dkr.ecr-fips.*.amazonaws.com"
      - "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
      - "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
    # defaultCacheDuration — це типовий час, протягом якої втулок буде кешувати облікові дані у памʼяті,
    # якщо тривалість кешу не надана у відповіді втулку. Це поле є обовʼязковим.
    defaultCacheDuration: "12h"
    # Вхідна версія CredentialProviderRequest є обовʼязковою. Відповідь CredentialProviderResponse
    # ПОВИННА використовувати ту ж версію кодування, що й вхідна. Поточні підтримувані значення:
    # - credentialprovider.kubelet.k8s.io/v1
    apiVersion: credentialprovider.kubelet.k8s.io/v1
    # Аргументи, що перндаються команді під час її виконання.
    # +optional
    # args:
    #   - --example-argument
    # Env визначає додаткові змінні середовища, які слід надати процесу. Ці
    # змінні обʼєднуються з оточенням хоста, а також змінними, які використовує client-go
    # для передачі аргументів до втулка.
    # +optional
    env:
      - name: AWS_PROFILE
        value: example_profile

    # tokenAttributes - конфігурація токену службового облікового запису, який буде передано втулку.
    # За допомогою цього поля постачальник облікових даних погоджується на використання токенів службових облікових записів для отримання образів.
    # якщо це поле встановлено без увімкненої функціональної можливості `KubeletServiceAccountTokenForCredentialProviders`, # kubelet не зможе запуститися з помилкою конфігурації.
    # +optional
    tokenAttributes:
      # serviceAccountTokenAudience — це очікувана аудиторія для спроєцьованих токенів службових облікових запісів.
      # +required
      serviceAccountTokenAudience: "<audience for the token>"
      # requireServiceAccount вказує чи вимагає втулок, щоб pod мав службовий обліковий запис.
      # Якщов становлено true, kubelet буде викликати втулок тільки якщо pod має службовий обліковий запис.
      # Якщо встановлено false, kubelet буде викликати втулок навіть, тоді, коли pod не має службового облікового запису
      # та не вклбчатиме токен у CredentialProviderRequest. Це корисно для втулків,
      # які використовуються для отримання образів для podʼів без службових облікових записів (напр., статичні podʼи).
      # +required
      requireServiceAccount: true
      # requiredServiceAccountAnnotationKeys є переліком ключів анотацій потрібних для втулків
      # та які мають бути присутні в службових облікових записах.
      # Ключі визначені в переліку будуть отримані з відповідного службового облікового запису та  передані
      # до втулку як частина CredentialProviderRequest. Якщо будь-яких з ключів, з цього переліку
      # не знаходиться в службового обліковому записі, kubelet не викликатиме втулок та поверне помилку.
      # Це поле є опціональним та може бути пустим. Втулки можуть використовувати це поле для отримання додаткової інформації,
      # потрібної для отримання облікових даних або для дозволу робочому навантаженю використовувати токен службового облікового запису для отримання образів.
      # Якщо це не пусте значення, requireServiceAccount має бути рівним true.
      # Ключі визначені в цьому переліку мають бути унікальними та не перетинатись з ключами визначених в
      #  переліку optionalServiceAccountAnnotationKeys.
      # +optional
      requiredServiceAccountAnnotationKeys:
      - "example.com/required-annotation-key-1"
      - "example.com/required-annotation-key-2"
      # optionalServiceAccountAnnotationKeys це перелік ключів анотації потрібні для втулку
      # та наявність яких в службового обліковому записі є опціональною.
      # Ключі визначені в цьому переліку будуть отримані з відповідного службового облікового запису та передані
      # втулку як частина CredentialProviderRequest. Перевірка наявності анотацій та їх значень покладається на втулок
      # Це поле є опціональним і може бути порожнім.
      # Втулки можуть використовувати це поле для отримання додаткової інформації для отримання облікових даних.
      # Ключі визначені в цьому переліку мають бути унікальними та не перетинатись з ключами з перелку
      # requiredServiceAccountAnnotationKeys.
      # +optional
      optionalServiceAccountAnnotationKeys:
      - "example.com/optional-annotation-key-1"
      - "example.com/optional-annotation-key-2"

Поле providers — це список увімкнених втулків, які використовує kubelet. Кожен запис має кілька обовʼязкових полів:

  • name: назва втулка, яка ПОВИННА відповідати назві виконавчого бінарного файлу, який існує в теці, вказаній у --image-credential-provider-bin-dir.
  • matchImages: список рядків, які використовуються для порівняння образів з метою визначення, чи слід викликати цього постачальника для конкретного образу контейнера. Докладніше про це нижче.
  • defaultCacheDuration: термін, протягом якого kubelet буде кешувати облікові дані в памʼяті, якщо втулок не надав термін кешування.
  • apiVersion: версія API, яку використовуватимуть kubelet і виконавчий втулок під час спілкування.

Кожен постачальник облікових даних також може мати додаткові аргументи та змінні середовища. Перегляньте реалізацію втулків, щоб визначити, який набір аргументів та змінних середовища потрібний для певного втулка.

Якщо ви використовуєте функціональну можливість KubeletServiceAccountTokenForCredentialProviders та налаштовуєте втулок для використання токена службового облікового запису через встановлення поля tokenAttributes, наступні поля є обовʼязковими:

  • serviceAccountTokenAudience: передбачувана аудиторія для спроєцьованого токена службового облікового запису . Це не може бути порожній рядок.
  • requireServiceAccount: чи потребує втулок, щоб pod мав службовий обліковий запис.
    • Якщо — true, kubelet викликатиме втулок коли pod має службовий обліковий запис.
    • Якщо — false, kubelet викликатиме втулок навіть тоді, коли pod не має службового облікового запису та не включатиме токен у CredentialProviderRequest.

Це є корисним для втулків, які використовуються для отримання образів для podʼів без службових облікових записів (напр., статичні podʼи).

Налаштування збігу образів

Поле matchImages для кожного постачальника облікових даних використовується kubelet для визначення того, чи слід викликати втулок для певного образу, що використовується в Podʼі. Кожний запис у matchImages — це шаблон образу, який може опціонально містити порт та шлях. Символи підстановки дозволяють використовувати шаблони для піддоменів, такі як *.k8s.io або k8s.*.io, а також для доменів верхнього рівня, такі як k8s.*. Збіг між імʼям образу та записом matchImage існує тоді, коли виконуються всі умови:

  • Обидва містять однакову кількість частин домену, і кожна частина має збіг.
  • Шлях URL matchImage повинен бути префіксом шляху URL цільового образу.
  • Якщо matchImages містить порт, то порт також повинен мати збіг в образі.

Деякі приклади значень шаблонів matchImages:

  • 123456789.dkr.ecr.us-east-1.amazonaws.com
  • *.azurecr.io
  • gcr.io
  • *.*.registry.io
  • foo.registry.io:8080/path

Що далі

Змінено April 24, 2025 at 5:18 PM PST: sync upstream (03e4e921ba)