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 类型的对象的项目列表。
使用配置文件、证书、密码或令牌进行身份验证。
支持检查模式。

注意

此模块具有相应的操作插件。

要求 

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

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 中的 apiVersion 值将覆盖此选项。默认值： `"v1"`
append_hash 布尔值	是否为了不变性目的，在资源名称后面附加哈希值仅适用于 ConfigMap 和 Secret 资源对于其他资源类型，将静默忽略该参数需要对象的完整定义才能生成哈希值 - 这意味着，只有在传递相同的对象且 state=absent 时，才能删除使用 append_hash 创建的对象（或者，只需使用 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 字符串	用于控制如何删除依赖对象。如果未指定，将使用对象类型的默认策略。这可能因对象类型而异。选项 `"前景"` `"背景"` `"孤立"`
强制布尔值	如果设置为 `yes`，且状态为 `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`，将按顺序尝试合并类型。默认为 `['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 配置刷新令牌。也可以通过 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 字符串	用于连接的 HTTP 代理的 URL。也可以通过 K8S_AUTH_PROXY 环境变量指定。请注意，此模块不会从环境中获取典型的代理设置（例如 HTTP_PROXY）。
proxy_headers 字典在 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 字符串	用于基本身份验证标头的冒号分隔的 username:password。也可以通过 K8S_AUTH_PROXY_HEADERS_BASIC_AUTH 环境指定。
proxy_basic_auth 字符串	用于代理基本身份验证标头的冒号分隔的 username:password。也可以通过 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` 或将其设置为 False，则忽略此选项。此选项需要 “kubernetes >= 19.15.0”。
field_manager 字符串 / 必填	用于跟踪字段所有者的管理器的名称。
force_conflicts 布尔值	当服务器端应用操作尝试更改另一个用户也声称要管理的字段时，会出现冲突这一特殊的错误状态。设置为 True 时，服务器端应用将强制针对冲突进行更改。选项 `false` ← (默认) `true`
src 路径	提供包含要创建或更新的对象的有效 YAML 定义的文件的路径。与 resource_definition 互斥。注意：kind、api_version、name 和 namespace 将被从 src 文件读取的配置中找到的相应值覆盖。从本地文件系统读取。要从 Ansible 控制器的文件系统（包括 vault 文件）读取，请使用 file lookup 插件或 template lookup 插件，并结合 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 schema 验证资源定义。需要 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 收到请求，模块就会退出。针对 `Deployment`, `DaemonSet` 和 `Pod` 的 `state=present` 以及针对所有资源类型的 `state=absent` 实现了此功能。对于没有实现的资源类型，除非设置了 `wait_condition`，否则 `wait` 会立即返回。选项 `false` ← (默认) `true`
wait_condition 字典	指定要等待的状态的自定义条件。如果未设置 `wait` 或设置为 False，则忽略此项。
reason 字符串	所需条件中 reason 字段的值例如，如果 `Deployment` 被暂停，则 `Progressing` `type` 将具有 `DeploymentPaused` 的 reason。条件中的可能 reason 特定于 Kubernetes 中的每个资源类型。请参阅给定资源的 status 字段的 API 文档，以查看可能的选项。
status 字符串	所需条件中 status 字段的值。例如，如果 `Deployment` 被暂停，则 `Progressing` `type` 将具有 `Unknown` 的 status。选项 `"True"` ← (默认) `"False"` `"Unknown"`
type 字符串	要等待的条件类型。例如，`Pod` 资源将设置 `Ready` 条件（以及其他条件）。如果您指定 `wait_condition`，则为必需项。如果留空，则会忽略 `wait_condition` 字段。条件的可能类型特定于 Kubernetes 中的每个资源类型。请参阅给定资源的 status 字段的 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)