kubernetes.core.k8s_service 模块 – 管理 Kubernetes 上的服务

注意

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

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

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

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

概要

  • 使用 Kubernetes Python SDK 管理 Kubernetes 上的服务

注意

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

要求

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

  • python >= 3.9

  • kubernetes >= 24.2.0

参数

参数

注释

api_key

字符串

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

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

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

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']，这非常适合在组合自定义资源和内置资源的资源类型上使用相同的参数。

选项

  • "json"

  • "merge"

  • "strategic-merge"

name

字符串 / 必需

用于指定服务对象名称。

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 选项的说明，以了解何时适用此选项。

persist_config

布尔值

是否保存 kubeconfig 刷新令牌。也可以通过 K8S_AUTH_PERSIST_CONFIG 环境变量指定。

当 k8s 上下文使用带有刷新令牌的用户凭据（如 oidc 或 gke/gcloud 身份验证）时，令牌由 k8s Python 客户端库刷新，但默认情况下不会保存。因此，旧的刷新令牌可能会过期，并且下次身份验证可能会失败。将此标志设置为 true 将告诉 k8s Python 客户端将新的刷新令牌保存到 kubeconfig 文件中。

默认为 false。

请注意，当前版本的 k8s Python 客户端库尚不支持将此标志设置为 True。

此 k8s Python 库的修复程序在此处：https://github.com/kubernetes-client/python-base/pull/169

选项

  • false

  • true

ports

list / elements=dictionary

要公开的端口列表。

https://kubernetes.ac.cn/docs/concepts/services-networking/service/#multi-port-services

proxy

字符串

用于连接的 HTTP 代理的 URL。也可以通过 K8S_AUTH_PROXY 环境变量指定。

请注意，此模块不会从环境中获取典型的代理设置（例如 HTTP_PROXY）。

proxy_headers

dictionary

在 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 中找到的相应值覆盖。

selector

dictionary

标签选择器标识此服务应应用于的对象。

https://kubernetes.ac.cn/docs/concepts/overview/working-with-objects/labels/

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 指定的属性不同，则将修补现有对象。

选项

  • "absent"

  • "present" ← (默认)

type

字符串

指定要创建的服务类型。

请参见 https://kubernetes.ac.cn/docs/concepts/services-networking/service/#publishing-services-service-types

选项

  • "NodePort"

  • "ClusterIP"

  • "LoadBalancer"

  • "ExternalName"

username

字符串

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

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

validate_certs

别名：verify_ssl

布尔值

是否验证 API 服务器的 SSL 证书。也可以通过 K8S_AUTH_VERIFY_SSL 环境变量指定。

选项

  • false

  • true

备注

注意

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

示例

- name: Expose https port with ClusterIP
  kubernetes.core.k8s_service:
    state: present
    name: test-https
    namespace: default
    ports:
    - port: 443
      protocol: TCP
    selector:
      key: special

- name: Expose https port with ClusterIP using spec
  kubernetes.core.k8s_service:
    state: present
    name: test-https
    namespace: default
    inline:
      spec:
        ports:
        - port: 443
          protocol: TCP
        selector:
          key: special

返回值

常见返回值记录在此处，以下是此模块特有的字段

键

描述

result

complex

创建、修补或以其他方式存在的服务对象。在删除的情况下将为空。

返回：成功

api_version

字符串

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

返回：成功

kind

字符串

始终为“Service”。

返回：成功

metadata

complex

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

返回：成功

spec

complex

对象的特定属性。将根据 api_version 和 kind 而变化。

返回：成功

status

complex

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

返回：成功

作者

  • KubeVirt 团队 (@kubevirt)