kubernetes.core.k8s 模块 – 管理 Kubernetes (K8s) 对象

注意

此模块是 kubernetes.core 集合 (版本 5.0.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install kubernetes.core。您需要其他要求才能使用此模块，有关详细信息，请参阅要求。

要在 playbook 中使用它，请指定：kubernetes.core.k8s。

概要 

使用 Kubernetes Python 客户端对 K8s 对象执行 CRUD 操作。
从源文件或内联传递对象定义。有关读取文件以及使用 Jinja 模板或 vault 加密文件的示例，请参见示例。
访问全面的 K8s API。
使用 kubernetes.core.k8s_info 模块获取有关 kind 类型对象的项目列表
使用配置文件、证书、密码或令牌进行身份验证。
支持检查模式。

注意

此模块具有相应的 action 插件。

要求 

执行此模块的主机需要以下要求。

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 结合使用以识别特定对象。如果提供了 resource definition，则来自 resource_definition 的 apiVersion 值将覆盖此选项。默认值： `"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 路径	用于向 API 进行身份验证的 CA 证书的路径。必须提供完整的证书链以避免证书验证错误。也可以通过 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 布尔值	如果设置为 `yes`，并且 state 为 `present`，则将替换现有对象。选项 `false` ← (默认值) `true`
generate_name 字符串 kubernetes.core 2.3.0 中添加	用于指定对象名称的基础，服务器将自动添加随机字符以生成唯一名称。当state未设置为`present`或apply设置为`yes`时，此选项将被忽略。如果提供了资源定义，则来自resource_definition的metadata.generateName值将覆盖此选项。如果提供了资源定义且包含metadata.name，则此选项将被忽略。与`name`互斥。
hidden_fields 列表 / 元素=字符串 kubernetes.core 2.5.0 中添加	隐藏结果中与此选项匹配的字段例如`hidden_fields=[metadata.managedFields]` 仅支持不引用列表项的字段定义（因此`spec.containers[0]`将不起作用）
host 字符串	提供用于访问API的URL。也可以通过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来标识特定对象。如果提供了资源定义，则来自resource_definition的kind值将覆盖此选项。
kubeconfig 任意	现有Kubernetes配置文件的路径。如果没有提供，并且没有提供其他连接选项，Kubernetes客户端将尝试从~/.kube/config加载默认配置文件。也可以通过K8S_AUTH_KUBECONFIG环境变量指定。可以使用分隔符“;” (Windows平台) 或 “:” (其他平台) 提供多个Kubernetes配置文件。 Kubernetes配置可以作为字典提供。此功能需要python kubernetes客户端版本>= 17.17.0。在2.2.0版本中添加。
label_selectors 列表 / 元素=字符串 kubernetes.core 2.2.0版本中添加	用于过滤的筛选器（标签查询）。
merge_type 列表 / 元素=字符串	是否使用特定类型覆盖默认的补丁合并方法。默认情况下，通常会使用策略性合并。例如，自定义资源定义通常无法通过通常的策略性合并进行更新。如果您看到“不支持战略合并补丁格式”，则可能需要使用`merge`。参见 https://kubernetes.ac.cn/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment 如果给出了多个`merge_type`，则将按顺序尝试这些merge_type。默认为`['strategic-merge', 'merge']`，这非常适合在结合了自定义资源和内置资源的资源类型上使用相同的参数。与`apply`互斥。 merge_type=json已在4.0.0版本中移除。请改用kubernetes.core.k8s_json_patch。选项 `"merge"` `"strategic-merge"`
name 字符串	用于指定对象名称。用于创建、删除或发现对象，无需提供完整的资源定义。结合api_version、kind和namespace来标识特定对象。如果提供了资源定义，则来自resource_definition的metadata.name值将覆盖此选项。
namespace 字符串	用于指定对象命名空间。在不提供完整资源定义的情况下创建、删除或发现对象时很有用。结合api_version、kind和name来标识特定对象。如果提供了资源定义，则来自resource_definition的metadata.namespace值将覆盖此选项。
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 布尔值	是否保存kube config刷新令牌。也可以通过K8S_AUTH_PERSIST_CONFIG环境变量指定。当k8s上下文使用具有刷新令牌的用户凭据（如oidc或gke/gcloud auth）时，令牌将由k8s python客户端库刷新，但默认情况下不会保存。因此，旧的刷新令牌可能会过期，并且下一次身份验证可能会失败。将此标志设置为true将告诉k8s python客户端将新的刷新令牌保存到kube config文件。默认为false。请注意，当前版本的k8s python客户端库尚不支持将此标志设置为True。 k8s python库的此修复程序位于：https://github.com/kubernetes-client/python-base/pull/169 选项 `false` `true`
proxy 字符串	用于连接的HTTP代理的URL。也可以通过K8S_AUTH_PROXY环境变量指定。请注意，此模块不会从环境中获取典型的代理设置（例如HTTP_PROXY）。
proxy_headers 字典 kubernetes.core 2.0.0 中添加	用于HTTP代理的Header。文档可在以下位置找到 https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html?highlight=proxy_headers#urllib3.util.make_headers。
basic_auth 字符串	用于基本身份验证标头的冒号分隔的用户名:密码。也可以通过K8S_AUTH_PROXY_HEADERS_BASIC_AUTH环境变量指定。
proxy_basic_auth 字符串	用于代理基本身份验证标头的冒号分隔的用户名:密码。也可以通过K8S_AUTH_PROXY_HEADERS_PROXY_BASIC_AUTH环境变量指定。
user_agent 字符串	表示您想要的user-agent的字符串，例如foo/1.0。也可以通过K8S_AUTH_PROXY_HEADERS_USER_AGENT环境变量指定。
resource_definition 别名：definition, inline 字符串	在创建或更新时，提供对象的有效YAML定义（作为字符串、列表或字典）。注意：kind、api_version、name和namespace将被提供的resource_definition中找到的相应值覆盖。
server_side_apply 字典 kubernetes.core 2.3.0 中添加	设置此选项后，apply将在服务器而不是客户端运行。如果`apply`未设置或设置为False，则将被忽略。此选项需要“kubernetes >= 19.15.0”。
field_manager 字符串 / 必需	用于跟踪字段所有权的管理器名称。
force_conflicts 布尔值	冲突是一种特殊的状态错误，当服务器端应用操作尝试更改另一个用户也声明要管理的字段时发生。设置为True时，服务器端应用将强制针对冲突进行更改。选项 `false` ← (默认值) `true`
src 路径	提供包含要创建或更新的对象或对象的有效YAML定义的文件的路径。与resource_definition互斥。注意：kind、api_version、name和namespace将被从src文件中读取的配置中找到的相应值覆盖。从本地文件系统读取。要从Ansible控制器的文件系统读取，包括保管库文件，请使用文件查找插件或模板查找插件，结合from_yaml过滤器，并将结果传递给resource_definition。请参见下面的示例。可用于创建资源的清单文件的URL。在2.4.0版本中添加。在kubernetes.core.k8s模块的情况下与template互斥。
state 字符串	确定是否应创建、修补或删除对象。设置为`present`时，如果对象尚不存在，则将创建对象。如果设置为`absent`，则将删除现有对象。如果设置为`present`，如果现有对象的属性与使用resource_definition或src指定的属性不同，则将修补现有对象。 `patched`状态是应用了给定补丁的现有资源。如果资源不存在，则静默跳过它（不引发错误）。选项 `"absent"` `"present"` ← (默认) `"patched"`
template 任意	在创建或更新时，提供对象的有效YAML模板定义文件。值可以作为字符串或字典提供。此参数接受多个模板文件。在2.0.0版本中添加。与`src`和`resource_definition`互斥。模板文件需要存在于Ansible控制器的文件系统上。可以使用字典指定其他参数。有效的附加参数 - `newline_sequence` (str): 指定用于模板文件的换行符序列。有效选项是“\n”、“\r”、“\r\n”。默认值“\n”。 `block_start_string` (str): 标记块开始的字符串。默认值“{%”。 `block_end_string` (str): 标记块结束的字符串。默认值“%}”。 `variable_start_string` (str): 标记打印语句开始的字符串。默认值“{{”。 `variable_end_string` (str): 标记打印语句结束的字符串。默认值“}}”。 `trim_blocks` (bool): 确定何时应从块中删除换行符。设置为`yes`时，将删除块后的第一个换行符（块，而不是变量标记！）。默认值为true。 `lstrip_blocks` (bool): 确定何时应去除前导空格和制表符。设置为`yes`时，将从一行开头到块的前导空格和制表符被去除。此功能需要Jinja 2.7或更高版本。默认值为false。
username 字符串	提供用于通过API进行身份验证的用户名。也可以通过K8S_AUTH_USERNAME环境变量指定。请注意，此功能仅适用于配置为使用 HTTP 基本身份验证的集群。如果您的集群使用其他身份验证方式（例如 OpenShift 中的 OAuth2），则此选项将无法按预期工作，您应该查看 community.okd.k8s_auth 模块，因为它可能满足您的需求。
validate 字典	如何（如果可以）根据 Kubernetes 模式验证资源定义。需要 kubernetes-validate python 模块。
fail_on_error 布尔值	是否在验证错误时失败。选项 `false` `true`
strict 布尔值	传递意外属性时是否失败选项 `false` `true` ← (默认)
version 字符串	要验证的 Kubernetes 版本。默认为 Kubernetes 服务器版本
validate_certs 别名：verify_ssl 布尔值	是否验证 API 服务器的 SSL 证书。也可以通过 K8S_AUTH_VERIFY_SSL 环境变量指定。选项 `false` `true`
wait 布尔值	是否等待某些资源类型达到所需状态。默认情况下，一旦 Kubernetes 接收到请求，模块就会退出。已为 `state=present` 的 `Deployment`、`DaemonSet` 和 `Pod` 以及 `state=absent` 的所有资源类型实现。对于没有实现的资源类型，除非设置了 `wait_condition`，否则 `wait` 会立即返回。选项 `false` ← (默认值) `true`
wait_condition 字典	指定要等待的状态的自定义条件。如果 `wait` 未设置或设置为 False，则忽略。
reason 字符串	所需条件中 reason 字段的值例如，如果 `Deployment` 已暂停，则 `Progressing` `type` 将具有 `DeploymentPaused` 原因。条件中可能的原因特定于 Kubernetes 中的每种资源类型。请参阅给定资源的状态字段的 API 文档以查看可能的选项。
status 字符串	所需条件中 status 字段的值。例如，如果 `Deployment` 已暂停，则 `Progressing` `type` 将具有 `Unknown` 状态。选项 `"True"` ← (默认) `"False"` `"Unknown"`
type 字符串	要等待的条件类型。例如，`Pod` 资源将设置 `Ready` 条件（以及其他条件）。如果您正在指定 `wait_condition`，则需要此参数。如果留空，则将忽略 `wait_condition` 字段。条件的可能类型特定于 Kubernetes 中的每种资源类型。请参阅给定资源的状态字段的 API 文档以查看可能的选项。
wait_sleep 整数	检查之间休眠的秒数。默认值： `5`
wait_timeout 整数	等待资源达到所需状态的秒数。如果 `wait` 未设置，则忽略。默认值： `120`

注释 

注意

当 validate_certs 为 True 时，为避免 SSL 证书验证错误，必须通过 ca_cert 或 kubeconfig 文件提供 API 服务器的完整证书链。

示例 

- 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` 为 true 时示例： `48`
error 复杂的	尝试创建/删除对象时的错误。已返回：错误
items 列表 / 元素=字符串	仅当将多个 yaml 文档传递给 src 或 resource_definition 时返回已返回：当 resource_definition 或 src 包含对象列表时
kind 字符串	表示此对象所代表的 REST 资源。已返回：成功
metadata 复杂的	标准对象元数据。包括名称、命名空间、注释、标签等。已返回：成功
spec 复杂的	对象的特定属性。将根据api_version 和 kind 而有所不同。已返回：成功
status 复杂的	对象的当前状态详细信息。已返回：成功

作者

Chris Houseknecht (@chouseknecht)
Fabian von Feilitzsch (@fabianvf)