.. _kubernetes.core.kubeconfig_module: ************************** kubernetes.core.kubeconfig ************************** **Generate, update, and optionally write Kubernetes kubeconfig files** Version added: 6.5.0 .. contents:: :local: :depth: 1 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 ---------- .. raw:: html
Parameter Choices/Defaults Comments
clusters
list / elements=dictionary
Default:
[]
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 V(merge).
See the behavior suboption for V(replace), V(keep), and V(remove).
behavior
string
    Choices:
  • merge ←
  • replace
  • keep
  • remove
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.
cluster
dictionary
Cluster configuration details.
Not required when behavior is V(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
    Choices:
  • no
  • yes
If true, the server's certificate will not be validated.
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
Default:
[]
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 V(merge).
See the behavior suboption for V(replace), V(keep), and V(remove).
behavior
string
    Choices:
  • merge ←
  • replace
  • keep
  • remove
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.
context
dictionary
Context configuration linking cluster and user.
Not required when behavior is V(remove).
cluster
string / required
Name of the cluster to use (must match a cluster name in O(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 O(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 O(contexts).
dest
string
Destination path where the final kubeconfig should be written.
If not specified, the kubeconfig will be saved to O(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 O(dest) is not specified.
preferences
dictionary
Default:
{}
Kubeconfig preferences.
Used for client-side settings like color output, default editor, etc.
users
list / elements=dictionary
Default:
[]
List of user authentication configurations.
Each user is identified by its name.
When name matches an existing user, the default behavior is V(merge).
See the behavior suboption for V(replace), V(keep), and V(remove).
behavior
string
    Choices:
  • merge ←
  • replace
  • keep
  • remove
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.
name
string / required
Unique name identifier for the user.
user
dictionary
User authentication configuration.
Not required when behavior is V(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 O(clusters), O(users), and O(contexts) are matched by ``name`` against the kubeconfig loaded from O(path). - For an existing ``name``, each entry's ``behavior`` suboption controls the update. - The default is V(merge), which merges nested ``cluster``, ``user``, and ``context`` data so unspecified keys are preserved. - With V(replace), the previous entry for that name is dropped and only the new definition is used. - With V(keep), the existing entry is left unchanged. - With V(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 -------- .. seealso:: `Kubernetes kubeconfig documentation `_ Official Kubernetes documentation for kubeconfig files `kubectl config documentation `_ kubectl commands for working with kubeconfig files Examples -------- .. code-block:: yaml # 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: .. raw:: html
Key Returned Description
dest
string
always
The path where the kubeconfig was written.

Sample:
/home/user/.kube/config
kubeconfig
dictionary
always
The complete kubeconfig data structure.


Status ------ Authors ~~~~~~~ - Youssef Khalid Ali (@YoussefKhalidAli)