Модуль kubernetes.core.k8s — Управление объектами Kubernetes (K8s)

Примечание

Этот модуль входит в коллекцию kubernetes.core (версия 3.2.0).

Вы, возможно, уже установили эту коллекцию, если используете пакет ansible. Она не входит в ansible-core. Чтобы проверить установку, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install kubernetes.core. Для использования этого модуля необходимы дополнительные требования, см. Требования для получения подробностей.

Для использования в playbook укажите: kubernetes.core.k8s.

Описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения

Описание

Используйте клиент Kubernetes Python для выполнения операций CRUD с объектами K8s.
Передайте определение объекта из исходного файла или встройте его. В примерах показано чтение файлов и использование шаблонов Jinja или файлов с вайл-шифрованием.
Доступ ко всему спектру API K8s.
Используйте модуль kubernetes.core.k8s_info для получения списка элементов об объекте типа kind.
Авторизуйтесь с помощью файла конфигурации, сертификатов, пароля или токена.
Поддерживает режим проверки.

Примечание

Этот модуль имеет соответствующий плагин действий.

Требования

Ниже приведены требования к хосту, на котором выполняется этот модуль.

python >= 3.9
kubernetes >= 24.2.0
PyYAML >= 3.11
jsonpatch

Параметры

Параметр	Комментарии
api_key строка	Токен, используемый для аутентификации с API. Также может быть указан через переменную среды K8S_AUTH_API_KEY.
api_version псевдонимы: api, version строка	Используется для указания версии API. Используется для создания, удаления или поиска объекта без предоставления полного определения ресурса. Используется в сочетании с kind, name и namespace для идентификации конкретного объекта. Если предоставлено определение ресурса, значение apiVersion из resource_definition переопределит этот параметр. По умолчанию: `"v1"`
append_hash логическое	Добавлять ли хэш к имени ресурса для целей неизменяемости Применяется только к ресурсам ConfigMap и Secret Параметр будет проигнорирован для других типов ресурсов Для генерации хэша необходимо полное определение объекта — это означает, что удаление объекта, созданного с append_hash, будет работать только в том случае, если тот же объект передается со значением state=absent (или просто используйте state=absent с именем, включающим сгенерированный хэш и append_hash=no) Варианты: `false` ← (по умолчанию) `true`
apply логическое	`apply` сравнивает желаемое определение ресурса с ранее предоставленным определением ресурса, игнорируя свойства, которые автоматически генерируются `apply` работает лучше с сервисами, чем ‘force=yes’ исключает `merge_type` Варианты: `false` ← (по умолчанию) `true`
ca_cert псевдонимы: ssl_ca_cert путь	Путь к сертификату CA, используемому для аутентификации с API. Для избежания ошибок проверки сертификатов необходимо предоставить цепочку сертификатов. Также может быть указан через переменную среды K8S_AUTH_SSL_CA_CERT.
client_cert псевдонимы: cert_file путь	Путь к сертификату, используемому для аутентификации с API. Также может быть указан через переменную среды K8S_AUTH_CERT_FILE.
client_key псевдонимы: key_file путь	Путь к файлу ключа, используемому для аутентификации с API. Также может быть указан через переменную среды K8S_AUTH_KEY_FILE.
context строка	Имя контекста, найденного в файле конфигурации. Также может быть указано через переменную среды K8S_AUTH_CONTEXT.
continue_on_error логическое добавлен в kubernetes.core 2.0.0	Продолжать ли при ошибках создания/удаления, когда определено несколько ресурсов. Это не влияет на этап валидации, который контролируется параметром `validate.fail_on_error`. Варианты: `false` ← (по умолчанию) `true`
delete_all псевдонимы: all логическое добавлен в kubernetes.core 2.5.0	Когда этот параметр установлен в true и state=absent, модуль удалит все ресурсы указанного типа ресурса в запрошенном пространстве имен. Игнорируется, когда `state` не установлен в absent или когда предоставлен один из (src), `name` или `resource_definition`. Необходим параметр `kind`. Этот параметр может использоваться с `label_selectors`, чтобы ограничить ресурсы, которые будут удалены. Варианты: `false` ← (по умолчанию) `true`
delete_options словарь добавлен в kubernetes.core 1.2.0	Настройка поведения при удалении объекта. Используется только при state=absent.
gracePeriodSeconds целое число	Указывает, сколько секунд ожидать перед принудительным завершением. Реализовано только для ресурсов Pod. Если не указано, будет использоваться стандартный интервал ожидания для типа объекта.
preconditions словарь	Указывает условие, которое должно быть выполнено для продолжения удаления.
resourceVersion строка	Указывает версию ресурса целевого объекта.
uid строка	Указывает UID целевого объекта.
propagationPolicy строка	Используется для управления тем, как удаляются зависимые объекты. Если не указано, будет использоваться политика по умолчанию для типа объекта. Она может варьироваться в зависимости от типа объекта. Варианты: `"Foreground"` `"Background"` `"Orphan"`

force boolean	Если установлено значение `yes`, и state имеет значение `present`, существующий объект будет заменён. Варианты: `false` ← (по умолчанию) `true`
generate_name string добавлен в kubernetes.core 2.3.0	Используется для указания основы имени объекта, к которому автоматически будут добавлены случайные символы на сервере для генерации уникального имени. Этот параметр игнорируется, когда state не установлен в значение `present` или когда apply установлен в значение `yes`. Если предоставлено определение ресурса, значение metadata.generateName из resource_definition переопределит этот параметр. Если определение ресурса предоставлено и содержит metadata.name, этот параметр игнорируется. Взаимоисключающее с `name`.
hidden_fields список / элементы=строка добавлен в kubernetes.core 2.5.0	Скрыть поля, соответствующие этому параметру, в результате Пример может быть `hidden_fields=[metadata.managedFields]` Поддерживаются только определения полей, которые не ссылаются на элементы списка (например, `spec.containers[0]` не сработает).
host строка	Указывает URL для доступа к API. Также может быть указан через переменную среды K8S_AUTH_HOST.
impersonate_groups список / элементы=строка добавлен в kubernetes.core 2.3.0	Группа(ы) для имитации при выполнении операции. Также может быть указана через переменную среды K8S_AUTH_IMPERSONATE_GROUPS. Пример: Group1,Group2
impersonate_user строка добавлен в kubernetes.core 2.3.0	Имя пользователя для имитации при выполнении операции. Также может быть указан через переменную среды K8S_AUTH_IMPERSONATE_USER.
kind строка	Используется для указания модели объекта. Используется для создания, удаления или поиска объекта без предоставления полного определения ресурса. Используется совместно с api_version, name и namespace для идентификации конкретного объекта. Если предоставлено определение ресурса, значение kind из resource_definition переопределит этот параметр.
kubeconfig любой	Путь к существующему файлу конфигурации Kubernetes. Если не указано и не указаны другие параметры подключения, Kubernetes-клиент попытается загрузить файл конфигурации по умолчанию из ~/.kube/config. Также может быть указан через переменную среды K8S_AUTH_KUBECONFIG. Несколько файлов конфигурации Kubernetes могут быть предоставлены с разделителем «;» для платформы Windows или «:» для других платформ. Конфигурация Kubernetes может быть предоставлена в виде словаря. Эта функция требует версии python kubernetes-клиента >= 17.17.0. Добавлено в версии 2.2.0.
label_selectors список / элементы=строка добавлен в kubernetes.core 2.2.0	Селектор (запрос по меткам) для фильтрации.
merge_type список / элементы=строка	Способ переопределения подхода слияния по умолчанию на определённый тип. По умолчанию обычно используется стратегическое слияние. Например, определения пользовательских ресурсов обычно не обновляются обычным стратегическим слиянием. Возможно, вам потребуется использовать `merge` если вы видите сообщение «стратегический формат слияния патча не поддерживается» См. https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment Если указано несколько `merge_type`, типы слияния будут использоваться по порядку. По умолчанию это `['strategic-merge', 'merge']`, что идеально подходит для использования одних и тех же параметров для типов ресурсов, которые объединяют пользовательские ресурсы и встроенные ресурсы. Взаимоисключающее с `apply` merge_type=json устарело и будет удалено в версии 4.0.0. Пожалуйста, используйте kubernetes.core.k8s_json_patch вместо него. Варианты: `"json"` `"merge"` `"strategic-merge"`
name строка	Используется для указания имени объекта. Используется для создания, удаления или поиска объекта без предоставления полного определения ресурса. Используется совместно с api_version, kind и namespace для идентификации конкретного объекта. Если предоставлено определение ресурса, значение metadata.name из resource_definition переопределит этот параметр.
namespace строка	Используется для указания пространства имён объекта. Полезно при создании, удалении или поиске объекта без предоставления полного определения ресурса. Используется совместно с api_version, kind и name для идентификации конкретного объекта. Если предоставлено определение ресурса, значение metadata.namespace из resource_definition переопределит этот параметр.
no_proxy строка добавлен в kubernetes.core 2.3.0	Список хостов/доменов/IP/CIDR, разделённых запятыми, которые не должны проходить через прокси. Также может быть указан через переменную среды K8S_AUTH_NO_PROXY. Обратите внимание, что этот модуль не подхватывает типичные настройки прокси из среды (например, NO_PROXY). Эта функция требует kubernetes>=19.15.0. При использовании kubernetes-библиотеки версии менее 19.15.0, возникнут ошибки, даже если параметр no_proxy задан правильно. Пример значения: «localhost,.local,.example.com,127.0.0.1,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16»
password строка	Указывает пароль для аутентификации с API. Также может быть указан через переменную среды K8S_AUTH_PASSWORD. Подробнее о применении этого параметра см. описание параметра `username`.

persist_config boolean	Сохранять ли токен обновления конфигурации kube. Также можно указать через переменную окружения K8S_AUTH_PERSIST_CONFIG. Когда контекст k8s использует учетные данные пользователя с токенами обновления (например, oidc или gke/gcloud auth), токен обновляется библиотекой k8s на Python, но по умолчанию не сохраняется. Поэтому старый токен обновления может истечь, и следующая авторизация может завершиться неудачно. Установка этого флага в значение true сообщит библиотеке k8s на Python о необходимости сохранения нового токена обновления в файл конфигурации kube. По умолчанию значение false. Обратите внимание, что текущая версия библиотеки k8s на Python пока не поддерживает установку этого флага в значение True. Исправление для этой библиотеки k8s на Python находится здесь: https://github.com/kubernetes-client/python-base/pull/169 Варианты: `false` `true`
proxy string	URL HTTP-прокси, который нужно использовать для подключения. Также можно указать через переменную окружения K8S_AUTH_PROXY. Обратите внимание, что этот модуль не подхватывает стандартные настройки прокси из среды (например, HTTP_PROXY).
proxy_headers dictionary добавлен в kubernetes.core 2.0.0	Заголовок, используемый для HTTP-прокси. Документацию можно найти здесь https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html?highlight=proxy_headers#urllib3.util.make_headers.
basic_auth string	Идентификатор пользователя:пароль, разделенные двоеточием, для заголовка базовой аутентификации. Также можно указать через переменную окружения K8S_AUTH_PROXY_HEADERS_BASIC_AUTH.
proxy_basic_auth string	Идентификатор пользователя:пароль, разделенные двоеточием, для заголовка базовой аутентификации прокси. Также можно указать через переменную окружения K8S_AUTH_PROXY_HEADERS_PROXY_BASIC_AUTH.
user_agent string	Строка, представляющая пользователя-агента, например, foo/1.0. Также можно указать через переменную окружения K8S_AUTH_PROXY_HEADERS_USER_AGENT.
resource_definition алиасы: definition, inline string	Укажите валидное определение YAML (в виде строки, списка или словаря) для объекта при создании или обновлении. ПРИМЕЧАНИЕ: kind, api_version, name и namespace будут перезаписаны соответствующими значениями, найденными в предоставленном resource_definition.
server_side_apply dictionary добавлен в kubernetes.core 2.3.0	При установке этого параметра применение выполняется на сервере, а не на клиенте. Игнорируется, если `apply` не установлен или установлен в значение False. Этот параметр требует «kubernetes >= 19.15.0».
field_manager string / обязательно	Имя менеджера, используемого для отслеживания владения полями.
force_conflicts boolean	Конфликт — это специальная ошибка состояния, которая возникает, когда операция Server Side Apply пытается изменить поле, которое другой пользователь также претендует на управление. При установке в значение True серверное применение принудительно применит изменения к конфликтам. Варианты: `false` ← (по умолчанию) `true`
src path	Укажите путь к файлу, содержащему валидное определение YAML объекта или объектов для создания или обновления. Взаимоисключающий с resource_definition. ПРИМЕЧАНИЕ: kind, api_version, name и namespace будут перезаписаны соответствующими значениями, найденными в конфигурации, считанной из файла src. Считывает из локальной файловой системы. Для чтения из файловой системы контроллера Ansible, включая зашифрованные файлы, используйте плагин поиска файлов или плагин поиска шаблонов в сочетании с фильтром from_yaml и передайте результат в resource_definition. См. примеры ниже. URL-адрес файлов манифеста, которые можно использовать для создания ресурса. Добавлено в версии 2.4.0. Взаимоисключающий с template в случае модуля kubernetes.core.k8s.
state string	Определяет, следует ли создавать, вносить изменения или удалять объект. При установке в значение `present`, объект будет создан, если он еще не существует. При установке в значение `absent`, существующий объект будет удален. При установке в значение `present`, существующий объект будет изменен, если его атрибуты отличаются от указанных с помощью resource_definition или src. `patched` состояние — это существующий ресурс, к которому применено данное изменение. Если ресурс не существует, пропустите его без ошибок. Варианты: `"absent"` `"present"` ← (по умолчанию) `"patched"`
template any	Укажите валидный файл шаблона YAML для объекта при создании или обновлении. Значение можно указать в виде строки или словаря. Параметр принимает несколько файлов шаблонов. Добавлено в версии 2.0.0. Взаимоисключающий с `src` и `resource_definition`. Файлы шаблонов должны присутствовать в файловой системе контроллера Ansible. Дополнительные параметры можно указать с помощью словаря. Действительные дополнительные параметры - `newline_sequence` (строка): Укажите последовательность символов новой строки для использования в файлах шаблонов. Действительные значения: “\n”, “\r”, “\r\n”. Значение по умолчанию “\n”. `block_start_string` (строка): Строка, обозначающая начало блока. Значение по умолчанию “{%”. `block_end_string` (строка): Строка, обозначающая конец блока. Значение по умолчанию “%}”. `variable_start_string` (строка): Строка, обозначающая начало оператора вывода. Значение по умолчанию “{{“. `variable_end_string` (строка): Строка, обозначающая конец оператора вывода. Значение по умолчанию “}}”. `trim_blocks` (булево): Определяет, следует ли удалять новые строки из блоков. При установке в значение `yes` первая новая строка после блока удаляется (блок, а не тег переменной!). Значение по умолчанию true. `lstrip_blocks` (булево): Определяет, следует ли удалять начальные пробелы и табуляции. При установке в значение `yes` начальные пробелы и табуляции удаляются из начала строки в блок. Эта функциональность требует Jinja 2.7 или новее. Значение по умолчанию false.

логин строка	Укажите логин для аутентификации с API. Также можно указать через переменную среды K8S_AUTH_USERNAME. Обратите внимание, что это работает только с кластерами, настроенными для использования HTTP Basic Auth. Если ваш кластер имеет другой метод аутентификации (например, OAuth2 в OpenShift), этот параметр не будет работать должным образом, и вам следует обратиться к модулю community.okd.k8s_auth, так как он может быть полезен.
валидировать словарь	Как (если вообще) валидировать определение ресурса по схеме Kubernetes. Требуется модуль kubernetes-validate python.
прерывать_при_ошибке_валидации булево	Прерывать выполнение при ошибках валидации. Варианты: `false` `true`
строго булево	Прерывать при передаче неожиданных свойств Варианты: `false` `true` ← (по умолчанию)
версия строка	Версия Kubernetes для валидации. По умолчанию используется версия сервера Kubernetes
проверять_сертификаты алиасы: проверять_ssl булево	Проверять ли сертификаты SSL API-сервера. Можно также указать через переменную среды K8S_AUTH_VERIFY_SSL. Варианты: `false` `true`
ждать булево	Дожидаться, пока определенные типы ресурсов достигнут желаемого состояния. По умолчанию модуль завершает работу после получения запроса Kubernetes. Реализовано для `state=present` для `Deployment`, `DaemonSet` и `Pod`, и для `state=absent` для всех типов ресурсов. Для типов ресурсов без реализации `wait` возвращает результат немедленно, если `wait_condition` не установлено. Варианты: `false` ← (по умолчанию) `true`
условие_ожидания словарь	Указывает пользовательское условие статуса для ожидания. Игнорируется, если `wait` не задан или равен False.
причина строка	Значение поля reason в требуемом условии. Например, если `Deployment` приостановлен, то `Progressing` `type` будет содержать причину `DeploymentPaused`. Возможные причины в условии зависят от типа ресурса в Kubernetes. См. документацию API поля status для заданного ресурса, чтобы увидеть возможные значения.
статус строка	Значение поля status в требуемом условии. Например, если `Deployment` приостановлен, то `Progressing` `type` будет содержать статус `Unknown`. Варианты: `"True"` ← (по умолчанию) `"False"` `"Unknown"`
тип строка	Тип условия для ожидания. Например, для ресурса `Pod` будет установлено условие `Ready` (среди других). Необходимо, если вы указываете `wait_condition`. Если оставлено пустым, поле `wait_condition` будет проигнорировано. Возможные типы условий зависят от типа ресурса в Kubernetes. См. документацию API поля status для заданного ресурса, чтобы увидеть возможные значения.
задержка_ожидания целое	Количество секунд, ожидаемое между проверками. По умолчанию: `5`
таймаут_ожидания целое	Время в секундах, которое нужно подождать, пока ресурс достигнет желаемого состояния. Игнорируется, если `wait` не задан. По умолчанию: `120`

Примечания

Примечание

Чтобы избежать ошибок валидации сертификатов SSL, когда validate_certs равно True, полная цепочка сертификатов API-сервера должна быть предоставлена через ca_cert или в файле kubeconfig.

Примеры

- name: Create a k8s namespace
  kubernetes.core.k8s:
    name: testing
    api_version: v1
    kind: Namespace
    state: present

- name: Create a Service object from an inline definition
  kubernetes.core.k8s:
    state: present
    definition:
      apiVersion: v1
      kind: Service
      metadata:
        name: web
        namespace: testing
        labels:
          app: galaxy
          service: web
      spec:
        selector:
          app: galaxy
          service: web
        ports:
        - protocol: TCP
          targetPort: 8000
          name: port-8000-tcp
          port: 8000

- name: Remove an existing Service object
  kubernetes.core.k8s:
    state: absent
    api_version: v1
    kind: Service
    namespace: testing
    name: web

# Passing the object definition from a file

- name: Create a Deployment by reading the definition from a local file
  kubernetes.core.k8s:
    state: present
    src: /testing/deployment.yml

- name: >-
    Read definition file from the Ansible controller file system.
    If the definition file has been encrypted with Ansible Vault it will automatically be decrypted.
  kubernetes.core.k8s:
    state: present
    definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}"

- name: >-
    (Alternative) Read definition file from the Ansible controller file system.
    In this case, the definition file contains multiple YAML documents, separated by ---.
    If the definition file has been encrypted with Ansible Vault it will automatically be decrypted.
  kubernetes.core.k8s:
    state: present
    definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml_all }}"

- name: Read definition template file from the Ansible controller file system
  kubernetes.core.k8s:
    state: present
    template: '/testing/deployment.j2'

- name: Read definition template file from the Ansible controller file system that uses custom start/end strings
  kubernetes.core.k8s:
    state: present
    template:
      path: '/testing/deployment.j2'
      variable_start_string: '[['
      variable_end_string: ']]'

- name: Read multiple definition template file from the Ansible controller file system
  kubernetes.core.k8s:
    state: present
    template:
    - path: '/testing/deployment_one.j2'
    - path: '/testing/deployment_two.j2'
      variable_start_string: '[['
      variable_end_string: ']]'

- name: fail on validation errors
  kubernetes.core.k8s:
    state: present
    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"
    validate:
      fail_on_error: yes

- name: warn on validation errors, check for unexpected properties
  kubernetes.core.k8s:
    state: present
    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"
    validate:
      fail_on_error: no
      strict: yes

# Download and apply manifest
- name: Download metrics-server manifest to the cluster.
  ansible.builtin.get_url:
    url: https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
    dest: ~/metrics-server.yaml
    mode: '0664'

- name: Apply metrics-server manifest to the cluster.
  kubernetes.core.k8s:
    state: present
    src: ~/metrics-server.yaml

# Wait for a Deployment to pause before continuing
- name: Pause a Deployment.
  kubernetes.core.k8s:
    definition:
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: example
        namespace: testing
      spec:
        paused: True
    wait: yes
    wait_condition:
      type: Progressing
      status: Unknown
      reason: DeploymentPaused

# Patch existing namespace : add label
- name: add label to existing namespace
  kubernetes.core.k8s:
    state: patched
    kind: Namespace
    name: patch_namespace
    definition:
      metadata:
        labels:
          support: patch

# Create object using generateName
- name: create resource using name generated by the server
  kubernetes.core.k8s:
    state: present
    generate_name: pod-
    definition:
      apiVersion: v1
      kind: Pod
      spec:
        containers:
        - name: py
          image: python:3.7-alpine
          imagePullPolicy: IfNotPresent

# Server side apply
- name: Create configmap using server side apply
  kubernetes.core.k8s:
    namespace: testing
    definition:
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: my-configmap
    apply: yes
    server_side_apply:
      field_manager: ansible

# Delete all Deployment from specified namespace
- name: Delete all Deployment from specified namespace
  kubernetes.core.k8s:
    api_version: apps/v1
    namespace: testing
    kind: Deployment
    delete_all: true

Значения возврата

Общие значения возврата документированы здесь, следующие — поля, уникальные для этого модуля:

Ключ	Описание
result сложное	Созданный, изменённый или в ином случае существующий объект. Будет пустым в случае удаления. Возвращается при: успехе
api_version строка	Версионированная схема этого представления объекта. Возвращается при: успехе
duration целое число	время выполнения задачи в секундах Возвращается при: когда `wait` истинно Пример: `48`
error сложное	ошибка при попытке создания/удаления объекта. Возвращается при: ошибке
items список / элементы=строка	Возвращается только при передаче нескольких yaml-документов в src или resource_definition Возвращается при: когда resource_definition или src содержат список объектов
kind строка	Представляет REST-ресурс, который представляет этот объект. Возвращается при: успехе
metadata сложное	Стандартные метаданные объекта. Включают имя, пространство имён, аннотации, метки и т.д. Возвращается при: успехе
spec сложное	Уникальные атрибуты объекта. Будут различаться в зависимости от api_version и kind. Возвращается при: успехе
status сложное	Текущие данные статуса объекта. Возвращается при: успехе

Авторы

Крис Хаускнект (@chouseknecht)
Фабиан фон Фейлитцш (@fabianvf)

Ссылки на коллекции

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/kubernetes/core/k8s_module.html