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 资源此参数将针对其他资源类型被静默忽略需要对象的完整定义才能生成哈希值 - 这意味着，删除使用 append_hash 创建的对象，只有在使用 state=absent 传递相同对象时才能工作（或者，只需使用包含生成的哈希值和 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 字符串	用于控制如何删除依赖对象。如果未指定，将使用对象类型的默认策略。这在不同对象类型之间可能会有所不同。选项 `“前台”` `“后台”` `“孤儿”`
强制布尔值	如果设置为`yes`，并且状态为`present`，则将替换现有对象。选项 `false` ← (默认) `true`
主机字符串	提供用于访问 API 的 URL。也可以通过 K8S_AUTH_HOST 环境变量指定。
模拟组列表 / 元素=字符串 kubernetes.core 2.3.0 中添加	要为操作模拟的组。也可以通过 K8S_AUTH_IMPERSONATE_GROUPS 环境变量指定。例如：Group1,Group2
模拟用户字符串 kubernetes.core 2.3.0 中添加	要为操作模拟的用户名。也可以通过 K8S_AUTH_IMPERSONATE_USER 环境变量指定。
种类字符串	用于指定对象模型。用于创建、删除或发现对象，无需提供完整的资源定义。与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` 参见 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_types 默认为`['strategic-merge', 'merge']`，这非常适合在结合了自定义资源和内置资源的资源种类上使用相同的参数。与`apply` 互斥 merge_type=json 已在 4.0.0 版本中删除。请改用 kubernetes.core.k8s_json_patch。选项 `“合并”` `“策略性合并”`
名称字符串	用于指定对象名称。用于创建、删除或发现对象，无需提供完整的资源定义。与api_version、kind 和namespace 结合使用以标识特定对象。如果提供了资源定义，则来自resource_definition 的metadata.name 值将覆盖此选项。
命名空间字符串	用于指定对象命名空间。在不提供完整资源定义的情况下创建、删除或发现对象时很有用。与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”
密码字符串	提供用于使用 API 进行身份验证的密码。也可以通过 K8S_AUTH_PASSWORD 环境变量指定。请阅读`username` 选项的说明，了解此选项何时适用。
持久化配置布尔值	是否保存 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`
代理字符串	用于连接的 HTTP 代理的 URL。也可以通过 K8S_AUTH_PROXY 环境变量指定。请注意，此模块不会从环境中获取典型的代理设置（例如 HTTP_PROXY）。
代理头字典 kubernetes.core 2.0.0 中添加	用于 HTTP 代理的头。文档可以在这里找到 https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html?highlight=proxy_headers#urllib3.util.make_headers。
基本认证字符串	用于基本身份验证头的冒号分隔的用户名：密码。也可以通过 K8S_AUTH_PROXY_HEADERS_BASIC_AUTH 环境变量指定。
代理基本认证字符串	用于代理基本身份验证头的冒号分隔的用户名：密码。也可以通过 K8S_AUTH_PROXY_HEADERS_PROXY_BASIC_AUTH 环境变量指定。
用户代理字符串	表示所需用户代理的字符串，例如 foo/1.0。也可以通过 K8S_AUTH_PROXY_HEADERS_USER_AGENT 环境变量指定。
resource_definition 别名：definition、inline 字符串	在创建或更新时，提供对象的有效 YAML 定义（作为字符串、列表或字典）。注意：kind、api_version、name 和namespace 将被提供的resource_definition 中找到的相应值覆盖。
源路径	提供包含要创建或更新的对象或对象的有效 YAML 定义的文件的路径。与resource_definition 互斥。注意：kind、api_version、name 和namespace 将被从src 文件中读取的配置中找到的相应值覆盖。从本地文件系统读取。要从 Ansible 控制器的文件系统读取，包括保管库文件，请使用文件查找插件或模板查找插件，结合 from_yaml 过滤器，并将结果传递给resource_definition。请参见下面的示例。可用于创建资源的清单文件的 URL。在 2.4.0 版本中添加。在 kubernetes.core.k8s 模块的情况下与template 互斥。
状态字符串	确定是否应该创建、修补或删除对象。当设置为`present`时，如果对象不存在，则将创建该对象。如果设置为`absent`，则将删除现有对象。如果设置为`present`，如果现有对象的属性与使用resource_definition 或src 指定的属性不同，则将修补现有对象。 `patched` 状态是已应用给定补丁的现有资源。如果资源不存在，则静默跳过它（不引发错误）。选项 `“不存在”` `"present"` ← (默认) `“已修补”`
模板任意在 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。
用户名字符串	提供用于使用 API 进行身份验证的用户名。也可以通过 K8S_AUTH_USERNAME 环境变量指定。请注意，这仅适用于配置为使用 HTTP 基本身份验证的集群。如果您的集群采用不同的身份验证方式（例如 OpenShift 中的 OAuth2），此选项将无法按预期工作，您应该查看 community.okd.k8s_auth 模块，因为它可能会满足您的需求。
验证字典	如何（如果适用）根据 Kubernetes 模式验证资源定义。需要 kubernetes-validate python 模块
错误时失败布尔值	是否在验证错误时失败。选项 `false` `true`
严格布尔值	传递意外属性时是否失败选项 `false` `true` ← (默认)
版本字符串	要验证的 Kubernetes 版本。默认为 Kubernetes 服务器版本
validate_certs 别名：verify_ssl 布尔值	是否验证 API 服务器的 SSL 证书。也可以通过 K8S_AUTH_VERIFY_SSL 环境变量指定。选项 `false` `true`
等待布尔值	是否等待某些资源种类最终处于所需状态。默认情况下，一旦 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` status。选项 `"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 包含对象列表时
种类字符串	表示此对象表示的 REST 资源。返回：成功
metadata 复杂类型	标准对象元数据。包括名称、命名空间、注释、标签等。返回：成功
spec 复杂类型	对象的特定属性。将根据 api_version 和 kind 而有所不同。返回：成功
status 复杂类型	对象的当前状态详细信息。返回：成功

作者

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