kubernetes.core.kubeconfig module – Generate, update, and optionally write Kubernetes kubeconfig files

Note

This module is part of the kubernetes.core collection (version 6.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install kubernetes.core. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: kubernetes.core.kubeconfig.

New in kubernetes.core 6.5.0

Synopsis

• Build, update, and manage Kubernetes kubeconfig files using structured input.

• Supports loading an existing kubeconfig file and merging clusters, users, and contexts.

• Can optionally write the resulting kubeconfig to a destination path.

• Ensures idempotent behavior by only updating files when changes occur.

Requirements

The below requirements are needed on the host that executes this module.

• PyYAML >= 5.1

Parameters

Parameter	Comments
clusters list / elements=dictionary	List of cluster definitions to merge into the kubeconfig. Each cluster is identified by its name. When name matches an existing cluster, the default behavior is merge. See the behavior suboption for replace, keep, and remove. Default: []
behavior string	How to handle merging if a cluster with this name already exists. merge - Update only the specified fields, preserve others (default). replace - Replace the entire cluster definition. keep - Keep existing cluster, skip this entry. remove - Remove the cluster entry entirely. Silently skipped if the entry does not exist. Choices: "merge" ← (default) "replace" "keep" "remove"
cluster dictionary	Cluster configuration details. Not required when behavior is remove.
certificate-authority string	Path to a CA certificate file for validating the API server certificate.
certificate-authority-data string	Base64 encoded CA certificate data. Use this instead of certificate-authority for embedded certificates.
insecure-skip-tls-verify boolean	If true, the server’s certificate will not be validated. Choices: false true
proxy-url string	Optional proxy URL for cluster connections.
server string / required	Kubernetes API server URL (e.g., https://k8s.example.com:6443).
tls-server-name string	Server name to use for server certificate validation.
name string / required	Unique name identifier for the cluster.
contexts list / elements=dictionary	List of context definitions linking users and clusters. Each context is identified by its name. When name matches an existing context, the default behavior is merge. See the behavior suboption for replace, keep, and remove. Default: []
behavior string	How to handle merging if a context with this name already exists. merge - Update only the specified fields, preserve others (default). replace - Replace the entire context definition. keep - Keep existing context, skip this entry. remove - Remove the context entry entirely. Silently skipped if the entry does not exist. Choices: "merge" ← (default) "replace" "keep" "remove"
context dictionary	Context configuration linking cluster and user. Not required when behavior is remove.
cluster string / required	Name of the cluster to use (must match a cluster name in clusters).
namespace string	Default namespace to use for this context. If not specified, defaults to default.
user string / required	Name of the user to authenticate as (must match a user name in users).
name string / required	Unique name identifier for the context.
current_context string	Name of the context to set as current/active. This context will be used by default when using kubectl. Must match one of the context names defined in contexts.
dest string	Destination path where the final kubeconfig should be written. If not specified, the kubeconfig will be saved to path. Allows copying and modifying a kubeconfig to a new location.
path string / required	Path to an existing kubeconfig file to load and merge from. If the file does not exist, a new kubeconfig will be created. This becomes the default destination if dest is not specified.
preferences dictionary	Kubeconfig preferences. Used for client-side settings like color output, default editor, etc. Default: {}
users list / elements=dictionary	List of user authentication configurations. Each user is identified by its name. When name matches an existing user, the default behavior is merge. See the behavior suboption for replace, keep, and remove. Default: []
behavior string	How to handle merging if a user with this name already exists. merge - Update only the specified fields, preserve others (default). replace - Replace the entire user definition. keep - Keep existing user, skip this entry. remove - Remove the user entry entirely. Silently skipped if the entry does not exist. Choices: "merge" ← (default) "replace" "keep" "remove"
name string / required	Unique name identifier for the user.
user dictionary	User authentication configuration. Not required when behavior is remove.
auth-provider dictionary	Authentication provider configuration (e.g., for GCP, Azure).
client-certificate string	Path to client certificate file. Used for certificate-based authentication.
client-certificate-data string	Base64 encoded client certificate. Use instead of client-certificate for embedded certificates.
client-key string	Path to client private key file. Must be provided with client-certificate.
client-key-data string	Base64 encoded client private key. Use instead of client-key for embedded keys.
exec dictionary	Exec-based credential plugin configuration. Used for external authentication providers.
password string	Password for basic authentication.
token string	Bearer token for authentication.
username string	Username for basic authentication.

Notes

Note

• Input data is merged by resource name (cluster, user, context).

• Updates under clusters, users, and contexts are matched by name against the kubeconfig loaded from path.

• For an existing name, each entry’s behavior suboption controls the update.

• The default is merge, which merges nested cluster, user, and context data so unspecified keys are preserved.

• With replace, the previous entry for that name is dropped and only the new definition is used.

• With keep, the existing entry is left unchanged.

• With remove, the existing entry is deleted from the kubeconfig entirely. If no entry with that name exists, the operation is silently skipped.

• This can be used to move kubeconfig files to a different location with different content.

• This module does not validate cluster connectivity or authentication.

• The module supports check_mode and will not write files when enabled.

• The structure follows standard Kubernetes kubeconfig format as defined in the Kubernetes documentation.

• Tokens and sensitive data should be protected using ansible-vault or environment variables.

See Also

See also

Kubernetes kubeconfig documentation

Official Kubernetes documentation for kubeconfig files

kubectl config documentation

kubectl commands for working with kubeconfig files

Examples

# Create a new kubeconfig file with a single cluster
- name: Create basic kubeconfig
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    clusters:
      - name: production-cluster
        cluster:
          server: https://prod.k8s.example.com:6443
          certificate-authority-data: LS0tLS1CRUdJTi...
    users:
      - name: admin-user
        user:
          token: eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9...
    contexts:
      - name: prod-admin
        context:
          cluster: production-cluster
          user: admin-user
          namespace: production
    current_context: prod-admin

- name: Add a second cluster to an existing kubeconfig without touching other entries
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    clusters:
      - name: staging-cluster
        cluster:
          server: https://staging.k8s.example.com:6443
          insecure-skip-tls-verify: true
    users:
      - name: staging-user
        user:
          client-certificate: /path/to/staging.crt
          client-key: /path/to/staging.key
    contexts:
      - name: staging-admin
        context:
          cluster: staging-cluster
          user: staging-user
          namespace: staging

- name: Update only the token for an existing user, preserving all other user fields
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    users:
      - name: admin-user
        behavior: merge
        user:
          token: "{{ new_admin_token }}"

- name: Replace a cluster definition entirely.
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    clusters:
      - name: production-cluster
        behavior: replace
        cluster:
          server: https://new-prod.k8s.example.com:6443
          certificate-authority-data: LS0tLS1CRUdJTi...

- name: Remove a decommissioned cluster, user, and context
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    clusters:
      - name: old-cluster
        behavior: remove
    users:
      - name: old-user
        behavior: remove
    contexts:
      - name: old-context
        behavior: remove

- name: Switch the active context
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    current_context: staging-admin

- name: Copy a kubeconfig to a new location with an additional cluster merged in
  kubernetes.core.kubeconfig:
    path: /home/user/.kube/config
    dest: /home/user/.kube/config-ci
    clusters:
      - name: ci-cluster
        cluster:
          server: https://ci.k8s.example.com:6443
          insecure-skip-tls-verify: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
dest string	The path where the kubeconfig was written. Returned: always Sample: "/home/user/.kube/config"
kubeconfig dictionary	The complete kubeconfig data structure. Returned: always

Authors

• Youssef Khalid Ali (@YoussefKhalidAli)

Collection links

• Issue Tracker
• Repository (Sources)