Модуль kubernetes.core.k8s – Управление объектами Kubernetes (K8s)
Примечание
Этот модуль входит в коллекцию kubernetes.core (версия 6.4.0).
Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в состав ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.
Чтобы установить её, используйте: ansible-galaxy collection install kubernetes.core. Для использования этого модуля необходимы дополнительные требования. Подробности см. в разделе Требования.
Чтобы использовать его в плейбуке, укажите: kubernetes.core.k8s.
Краткое описание
- Использует клиент Kubernetes для Python для выполнения CRUD-операций с объектами K8s.
- Передайте определение объекта из исходного файла или непосредственно. Примеры чтения файлов, использования шаблонов Jinja и файлов, зашифрованных с помощью vault, см. в разделе примеров.
- Предоставляет доступ ко всему набору API K8s.
- Используйте модуль kubernetes.core.k8s_info, чтобы получить список элементов об объекте типа
kind - Поддерживает аутентификацию с помощью файла конфигурации, сертификатов, пароля или токена.
- Поддерживает режим проверки.
Примечание
Для этого модуля имеется соответствующий плагин действий.
Требования
Перечисленные ниже требования должны быть выполнены на хосте, на котором запускается этот модуль.
- python >= 3.9
- kubernetes >= 24.2.0
- PyYAML >= 3.11
- jsonpatch
Параметры
Параметр | Комментарии |
|---|---|
api_key string | Токен для аутентификации в API. Также можно указать с помощью переменной окружения K8S_AUTH_API_KEY. |
api_version псевдонимы: api, version string | Используется для указания версии API. Используется для создания, удаления или обнаружения объекта без указания полного определения ресурса. Используется вместе с kind, name и namespace для идентификации конкретного объекта. Если указано определение ресурса, значение apiVersion из resource_definition переопределит этот параметр. По умолчанию: |
append_hash boolean | Добавлять ли хеш к имени ресурса для обеспечения неизменяемости Применяется только к ресурсам ConfigMap и Secret Для ресурсов других типов этот параметр будет незаметно проигнорирован Для создания хеша требуется полное определение объекта — это означает, что удаление объекта, созданного с append_hash, будет работать только в том случае, если при state=absent передан тот же объект (в качестве альтернативы используйте state=absent с именем, содержащим сгенерированный хеш, и append_hash=no) Варианты:
|
apply boolean |
Взаимоисключающий параметр с Варианты:
|
ca_cert псевдонимы: ssl_ca_cert path | Путь к сертификату CA, используемому для аутентификации в API. Во избежание ошибок проверки сертификата необходимо предоставить всю цепочку сертификатов. Также можно указать с помощью переменной окружения K8S_AUTH_SSL_CA_CERT. |
client_cert псевдонимы: cert_file path | Путь к сертификату, используемому для аутентификации в API. Также можно указать с помощью переменной окружения K8S_AUTH_CERT_FILE. |
client_key псевдонимы: key_file path | Путь к файлу ключа, используемому для аутентификации в API. Также можно указать с помощью переменной окружения K8S_AUTH_KEY_FILE. |
context string | Имя контекста, указанного в файле конфигурации. Также можно указать с помощью переменной окружения K8S_AUTH_CONTEXT. |
continue_on_error boolean добавлено в kubernetes.core 2.0.0 | Продолжать ли выполнение при ошибках создания или удаления, если определено несколько ресурсов. Не влияет на этап проверки, которым управляет параметр Варианты:
|
delete_all псевдонимы: all boolean добавлено в kubernetes.core 3.0.0 | Если для этого параметра задано значение true и state=absent, модуль удалит все ресурсы указанного типа в запрошенном пространстве имён. Игнорируется, если для Для использования этого параметра требуется параметр Этот параметр можно использовать с Варианты:
|
delete_options dictionary добавлено в kubernetes.core 1.2.0 | Настройка поведения при удалении объекта. Используется только при state=absent. |
|
gracePeriodSeconds integer |
Укажите, сколько секунд ожидать до принудительного завершения. Реализовано только для ресурсов Pod. Если значение не указано, будет использоваться период ожидания по умолчанию для типа объекта. |
|
preconditions dictionary |
Укажите условие, которое должно быть выполнено для продолжения удаления. |
|
resourceVersion string |
Укажите версию целевого объекта. |
|
uid string |
Укажите UID целевого объекта. |
|
propagationPolicy string |
Используется для управления удалением зависимых объектов. Если значение не указано, будет использоваться политика по умолчанию для типа объекта. Она может различаться для разных типов объектов. Варианты:
|
force boolean | Если задано значение Варианты:
|
generate_name string добавлено в kubernetes.core 2.3.0 | Используется для указания основы имени объекта; сервер автоматически добавит случайные символы, чтобы создать уникальное имя. Этот параметр игнорируется, если для state задано значение, отличное от Если указано определение ресурса, значение metadata.generateName из resource_definition переопределит этот параметр. Если указано определение ресурса и оно содержит metadata.name, этот параметр игнорируется. Взаимоисключающий параметр с |
list / elements=string добавлено в kubernetes.core 3.0.0 | Скрывать в результате поля, соответствующие этому параметру Например: |
host string | Укажите URL для доступа к API. Также можно указать с помощью переменной окружения K8S_AUTH_HOST. |
impersonate_groups list / elements=string добавлено в kubernetes.core 2.3.0 | Группа или группы, от имени которых выполняется операция. Также можно указать с помощью переменной окружения K8S_AUTH_IMPERSONATE_GROUPS. Пример: Group1,Group2 |
impersonate_user string добавлено в kubernetes.core 2.3.0 | Имя пользователя, от имени которого выполняется операция. Также можно указать с помощью переменной окружения K8S_AUTH_IMPERSONATE_USER. |
kind string | Используется для указания модели объекта. Используется для создания, удаления или обнаружения объекта без указания полного определения ресурса. Используется вместе с api_version, name и namespace для идентификации конкретного объекта. Если указано определение ресурса, значение kind из resource_definition переопределит этот параметр. |
kubeconfig any | Путь к существующему файлу конфигурации Kubernetes. Если путь не указан и другие параметры подключения также не заданы, клиент Kubernetes попытается загрузить файл конфигурации по умолчанию из ~/.kube/config. Также можно указать с помощью переменной окружения K8S_AUTH_KUBECONFIG. Можно указать несколько файлов конфигурации Kubernetes, разделив их символом «;» в Windows или «:» на других платформах. Конфигурацию Kubernetes можно указать в виде словаря. Для этой возможности требуется версия клиента Python для Kubernetes не ниже 17.17.0. Добавлено в версии 2.2.0. |
label_selectors list / elements=string добавлено в kubernetes.core 2.2.0 | Селектор (запрос по меткам) для фильтрации. |
merge_type list / elements=string | Заменять ли используемый по умолчанию способ объединения исправлений на конкретный тип. По умолчанию обычно используется стратегическое объединение. Например, определения пользовательских ресурсов обычно нельзя обновлять с помощью стандартного стратегического объединения. Если появляется сообщение «формат стратегического объединения исправлений не поддерживается», можно использовать Если указано несколько значений Взаимоисключающий параметр с merge_type=json удалён в версии 4.0.0. Вместо него используйте kubernetes.core.k8s_json_patch. Варианты:
|
name string | Используется для указания имени объекта. Используется для создания, удаления или обнаружения объекта без указания полного определения ресурса. Используется вместе с api_version, kind и namespace для идентификации конкретного объекта. Если указано определение ресурса, значение metadata.name из resource_definition переопределит этот параметр. |
namespace string | Используется для указания пространства имён объекта. Полезно при создании, удалении или обнаружении объекта без указания полного определения ресурса. Используется вместе с api_version, kind и name для идентификации конкретного объекта. Если указано определение ресурса, значение metadata.namespace из resource_definition переопределит этот параметр. |
no_proxy string добавлено в 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 string | Укажите пароль для аутентификации в API. Также можно указать с помощью переменной окружения K8S_AUTH_PASSWORD. В описании параметра |
persist_config boolean | Сохранять ли токены обновления конфигурации kube. Также можно указать с помощью переменной окружения K8S_AUTH_PERSIST_CONFIG. Если в контексте k8s используются учётные данные пользователя с токенами обновления (например, аутентификация oidc или gke/gcloud), токен обновляется клиентской библиотекой Python для k8s, но по умолчанию не сохраняется. В результате срок действия старого токена обновления может истечь, и следующая аутентификация может завершиться ошибкой. Если установить этот флаг в true, клиент Python для k8s сохранит новый токен обновления в файл конфигурации kube. По умолчанию — false. Обратите внимание, что текущая версия клиентской библиотеки Python для k8s пока не поддерживает установку этого флага в True. Исправление для этой библиотеки k8s находится здесь: https://github.com/kubernetes-client/python-base/pull/169 Варианты:
|
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 |
Строка с желаемым значением user-agent, например 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 | Если задан этот параметр, применение выполняется на сервере, а не на клиенте. Игнорируется, если Для этого параметра требуется «kubernetes >= 19.15.0». |
|
field_manager string / обязательный |
Имя менеджера, используемого для отслеживания владения полями. |
|
force_conflicts boolean |
Конфликт — это особая ошибка статуса, возникающая, когда операция Server Side Apply пытается изменить поле, которым также управляет другой пользователь. Если задано значение True, серверное применение принудительно вносит изменения, несмотря на конфликты. Варианты:
|
src path | Укажите путь к файлу с корректным определением YAML одного или нескольких объектов для создания или обновления. Взаимоисключающий параметр с resource_definition. ПРИМЕЧАНИЕ: значения kind, api_version, name и namespace будут перезаписаны соответствующими значениями из конфигурации, прочитанной из файла src. Чтение выполняется из локальной файловой системы. Чтобы прочитать файл из файловой системы контроллера Ansible, включая зашифрованные файлы, используйте плагин поиска file или template вместе с фильтром from_yaml и передайте результат в resource_definition. См. примеры ниже. URL файлов манифестов, которые можно использовать для создания ресурса. Добавлено в версии 2.4.0. Взаимоисключающий параметр с template в случае модуля kubernetes.core.k8s. |
state string | Определяет, следует ли создать, исправить или удалить объект. Если задано значение
Варианты:
|
template any | Укажите корректный файл определения шаблона YAML для объекта, который создаётся или обновляется. Значение можно задать в виде строки или словаря. Параметр поддерживает несколько файлов шаблонов. Добавлено в версии 2.0.0. Несовместимо с Файлы шаблонов должны находиться в файловой системе контроллера Ansible. Дополнительные параметры можно указать с помощью словаря. Допустимые дополнительные параметры —
|
username string | Укажите имя пользователя для аутентификации в API. Также можно задать с помощью переменной окружения K8S_AUTH_USERNAME. Обратите внимание: этот параметр работает только с кластерами, настроенными на использование базовой HTTP-аутентификации. Если в кластере используется другой способ аутентификации (например, OAuth2 в OpenShift), этот параметр не будет работать ожидаемым образом. В таком случае рассмотрите модуль community.okd.k8s_auth — возможно, он подойдёт для вашей задачи. |
validate dictionary | Способ проверки (если она выполняется) определения ресурса на соответствие схеме Kubernetes. Для этого требуется модуль Python kubernetes-validate. |
|
fail_on_error boolean |
Определяет, следует ли завершаться с ошибкой при ошибках проверки. Варианты:
|
|
strict boolean |
Определяет, следует ли завершаться с ошибкой при передаче неожиданных свойств. Варианты:
|
|
version string |
Версия Kubernetes, на соответствие которой выполняется проверка. По умолчанию используется версия сервера Kubernetes. |
validate_certs псевдонимы: verify_ssl boolean | Следует ли проверять SSL-сертификаты API-сервера. Также можно задать с помощью переменной окружения K8S_AUTH_VERIFY_SSL. Варианты:
|
wait boolean | Следует ли ожидать, пока ресурсы определённых типов не перейдут в желаемое состояние. По умолчанию модуль завершает работу, как только Kubernetes получает запрос. Реализовано для Для типов ресурсов без реализации Варианты:
|
wait_condition dictionary | Задаёт пользовательское условие в поле status, которого следует ожидать. Игнорируется, если |
|
reason string |
Значение поля reason в требуемом условии. Например, если Возможные значения reason в условии зависят от типа ресурса Kubernetes. Возможные значения см. в документации API для поля status соответствующего ресурса. |
|
status string |
Значение поля status в требуемом условии. Например, если Варианты:
|
|
type string |
Тип условия, которого следует ожидать. Например, ресурс Обязателен, если задан параметр Если оставить это поле пустым, поле Возможные типы условий зависят от типа ресурса Kubernetes. Возможные значения см. в документации API для поля status соответствующего ресурса. |
wait_sleep integer | Количество секунд ожидания между проверками. По умолчанию: |
wait_timeout integer | Время ожидания перехода ресурса в желаемое состояние, в секундах. Игнорируется, если По умолчанию: |
Примечания
Примечание
- Чтобы избежать ошибок проверки 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
Возвращаемые значения
Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:
Ключ | Описание |
|---|---|
method string | Метод, использованный для развёртывания ресурса. Возвращается: success Пример: |
result complex | Созданный, исправленный или иным образом присутствующий объект. При удалении значение будет пустым. Возвращается: success |
|
api_version string |
Версионированная схема представления объекта. Возвращается: если |
|
duration integer |
Время выполнения задачи в секундах. Возвращается: если Пример: |
|
error complex |
Ошибка при попытке создать или удалить объект. Возвращается: error |
|
kind string |
Указывает REST-ресурс, который представляет этот объект. Возвращается: если |
|
metadata complex |
Стандартные метаданные объекта. Включают имя, пространство имён, аннотации, метки и т. д. Возвращается: если |
|
results complex |
Массив созданных, исправленных или иным образом присутствующих объектов. Возвращается: если |
|
api_version string |
Версионированная схема представления объекта. Возвращается: если |
|
duration integer |
Время выполнения задачи в секундах. Возвращается: если Пример: |
|
error complex |
Ошибка при попытке создать или удалить объект. Возвращается: error |
|
kind string |
Указывает REST-ресурс, который представляет этот объект. Возвращается: если |
|
metadata complex |
Стандартные метаданные объекта. Включают имя, пространство имён, аннотации, метки и т. д. Возвращается: если |
|
spec complex |
Специфические атрибуты объекта. Зависят от значений api_version и kind. Возвращается: если |
|
status complex |
Текущие сведения о состоянии объекта. Возвращается: если |
|
spec complex |
Специфические атрибуты объекта. Зависят от значений api_version и kind. Возвращается: если |
|
status complex |
Текущие сведения о состоянии объекта. Возвращается: если |
Ссылки на коллекцию
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/kubernetes/core/k8s_module.html