kubernetes.core.k8s_info 模块 – 描述 Kubernetes (K8s) 对象

注意

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

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

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

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

概要

  • 使用 Kubernetes Python 客户端对 K8s 对象执行读取操作。

  • 访问全范围的 K8s API。

  • 使用配置文件、证书、密码或令牌进行身份验证。

  • 支持检查模式。

  • 在 Ansible 2.9 之前，此模块名为 k8s_facts。用法没有改变。

注意

此模块有一个对应的动作插件。

别名：helm, helm_info, helm_plugin, helm_plugin_info, helm_repository, k8s, k8s_cluster_info, k8s_cp, k8s_drain, k8s_exec, k8s_json_patch, k8s_log, k8s_rollback, k8s_scale, k8s_service

要求

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

  • python >= 3.9

  • kubernetes >= 24.2.0

  • PyYAML >= 3.11

参数

参数

注释

api_key

字符串

用于向 API 进行身份验证的令牌。也可以通过 K8S_AUTH_API_KEY 环境变量指定。

api_version

别名：api, version

字符串

用于指定 API 版本。

用于创建、删除或发现对象，而无需提供完整的资源定义。

与 kind、name 和 namespace 结合使用以标识特定对象。

如果提供了资源定义，则来自resource_definition的 apiVersion 值将覆盖此选项。

默认： "v1"

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 环境变量指定。

field_selectors

列表 / 元素=字符串

用于筛选结果的字段选择器列表

默认： []

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

列表 / 元素=字符串

用于筛选结果的标签选择器列表

默认： []

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 身份验证）时，令牌由 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

字符串

表示所需用户代理的字符串，例如 foo/1.0。

也可以通过 K8S_AUTH_PROXY_HEADERS_USER_AGENT 环境指定。

username

字符串

提供用于与 API 进行身份验证的用户名。也可以通过 K8S_AUTH_USERNAME 环境变量指定。

请注意，这仅适用于配置为使用 HTTP 基本身份验证的集群。如果您的集群具有不同的身份验证形式（例如 OpenShift 中的 OAuth2），则此选项将无法按预期工作，您应该查看 community.okd.k8s_auth 模块，因为它可能会满足您的需求。

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 中的每种资源类型都是特定的。

请参阅给定资源的 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: Get an existing Service object
  kubernetes.core.k8s_info:
    api_version: v1
    kind: Service
    name: web
    namespace: testing
  register: web_service

- name: Get a list of all service objects
  kubernetes.core.k8s_info:
    api_version: v1
    kind: Service
    namespace: testing
  register: service_list

- name: Get a list of all pods from any namespace
  kubernetes.core.k8s_info:
    kind: Pod
  register: pod_list

- name: Search for all Pods labelled app=web
  kubernetes.core.k8s_info:
    kind: Pod
    label_selectors:
      - app = web
      - tier in (dev, test)

- name: Using vars while using label_selectors
  kubernetes.core.k8s_info:
    kind: Pod
    label_selectors:
      - "app = {{ app_label_web }}"
  vars:
    app_label_web: web

- name: Search for all running pods
  kubernetes.core.k8s_info:
    kind: Pod
    field_selectors:
      - status.phase=Running

- name: List custom objects created using CRD
  kubernetes.core.k8s_info:
    kind: MyCustomObject
    api_version: "stable.example.com/v1"

- name: Wait till the Object is created
  kubernetes.core.k8s_info:
    kind: Pod
    wait: yes
    name: pod-not-yet-created
    namespace: default
    wait_sleep: 10
    wait_timeout: 360

返回值

通用返回值在 此处记录，以下是此模块独有的字段

键

描述

api_found

布尔值

指定的 api_version 和 kind 是否已成功映射到目标集群上的现有 API。

添加版本 1.2.0。

返回：始终

resources

复杂

存在的对象

返回：成功

api_version

字符串

此对象表示的版本化架构。

返回：成功

kind

字符串

表示此对象表示的 REST 资源。

返回：成功

metadata

字典

标准对象元数据。包括名称、命名空间、注释、标签等。

返回：成功

spec

字典

对象的特定属性。将根据 api_version 和 kind 而有所不同。

返回：成功

status

字典

对象当前状态的详细信息。

返回：成功

作者

  • Will Thames (@willthames)