community.okd.k8s 模块 – 管理 OpenShift 对象

注意

此模块是 community.okd 集合 (版本 4.0.0) 的一部分。

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

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

要在 playbook 中使用它，请指定：community.okd.k8s。

概要 

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

注意

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

需求 

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

python >= 3.6
kubernetes >= 12.0.0
PyYAML >= 3.11

参数 

参数	注释
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 资源对于其他资源类型，此参数将被静默忽略需要对象的完整定义才能生成哈希 - 这意味着只有在使用 state=absent 传递相同对象时，才能删除使用 append_hash 创建的对象（或者，只需使用包含生成的哈希和 append_hash=no 的名称以及 state=absent）。选项 `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 布尔值在 community.okd 2.0.0 中添加	定义多个资源时，是否在创建/删除错误时继续。这对由 `validate.fail_on_error` 参数控制的验证步骤没有影响。选项 `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`
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版本中新增。
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配置刷新令牌。也可以通过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 字符串	用于基本身份验证标头的冒号分隔的用户名：密码。也可以通过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中找到的相应值覆盖。
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 任意在 community.okd 2.0.0 中添加	在创建或更新时提供对象的有效YAML模板定义文件。值可以作为字符串或字典提供。与`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` reason。条件中可能的 reason 是 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 an OCP project
  community.okd.k8s:
    state: present
    resource_definition:
      apiVersion: project.openshift.io/v1
      kind: Project
      metadata:
        name: testing

- name: Create a k8s namespace
  community.okd.k8s:
    name: testing
    api_version: v1
    kind: Namespace
    state: present

- name: Create a Service object from an inline definition
  community.okd.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
  community.okd.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
  community.okd.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.
  community.okd.k8s:
    state: present
    definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}"

- name: Read definition file from the Ansible controller file system after Jinja templating
  community.okd.k8s:
    state: present
    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"

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

- name: warn on validation errors, check for unexpected properties
  community.okd.k8s:
    state: present
    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"
    validate:
      fail_on_error: false
      strict: 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)