From a1cd39a71f19938ffccb0dc9d0287a97ba80e8c7 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 17:17:19 -0400 Subject: [PATCH] Update RST documentation files (#1189) (#1190) (cherry picked from commit 470c042690c45fd6f9faf4882f0c06bde78500ce) Co-authored-by: Bianca Henderson --- README.md | 3 +- docs/kubernetes.core.helm_module.rst | 48 + docs/kubernetes.core.helm_plugin_module.rst | 18 + ...ernetes.core.helm_registry_auth_module.rst | 11 +- ...ubernetes.core.k8s_cluster_info_module.rst | 2 +- docs/kubernetes.core.k8s_cp_module.rst | 2 +- docs/kubernetes.core.k8s_drain_module.rst | 2 +- docs/kubernetes.core.k8s_exec_module.rst | 2 +- docs/kubernetes.core.k8s_info_module.rst | 2 +- .../kubernetes.core.k8s_json_patch_module.rst | 2 +- docs/kubernetes.core.k8s_log_module.rst | 2 +- docs/kubernetes.core.k8s_lookup.rst | 153 +++- docs/kubernetes.core.k8s_module.rst | 185 +++- docs/kubernetes.core.k8s_rollback_module.rst | 2 +- docs/kubernetes.core.k8s_scale_module.rst | 2 +- docs/kubernetes.core.k8s_service_module.rst | 2 +- docs/kubernetes.core.k8s_taint_module.rst | 2 +- docs/kubernetes.core.kubeconfig_module.rst | 863 ++++++++++++++++++ docs/kubernetes.core.kustomize_lookup.rst | 2 +- 19 files changed, 1246 insertions(+), 59 deletions(-) create mode 100644 docs/kubernetes.core.kubeconfig_module.rst diff --git a/README.md b/README.md index f9bf9144..79f830d3 100644 --- a/README.md +++ b/README.md @@ -58,13 +58,14 @@ Name | Description [kubernetes.core.k8s_scale](https://github.com/ansible-collections/kubernetes.core/blob/main/docs/kubernetes.core.k8s_scale_module.rst)|Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job. [kubernetes.core.k8s_service](https://github.com/ansible-collections/kubernetes.core/blob/main/docs/kubernetes.core.k8s_service_module.rst)|Manage Services on Kubernetes [kubernetes.core.k8s_taint](https://github.com/ansible-collections/kubernetes.core/blob/main/docs/kubernetes.core.k8s_taint_module.rst)|Taint a node in a Kubernetes/OpenShift cluster +[kubernetes.core.kubeconfig](https://github.com/ansible-collections/kubernetes.core/blob/main/docs/kubernetes.core.kubeconfig_module.rst)|Generate, update, and optionally write Kubernetes kubeconfig files ## Requirements -### Ansible version compatibility +## Ansible version compatibility This collection has been tested against the following Ansible versions: **>=2.16.0**. diff --git a/docs/kubernetes.core.helm_module.rst b/docs/kubernetes.core.helm_module.rst index 92aef3ba..09a6c824 100644 --- a/docs/kubernetes.core.helm_module.rst +++ b/docs/kubernetes.core.helm_module.rst @@ -73,6 +73,7 @@ Parameters
If set, the installation process deletes the installation on failure.
+
With Helm v4 this is translated to the --rollback-on-failure flag, since --atomic was renamed; with Helm v3 the --atomic flag is used. The O(atomic) option works the same way regardless of the installed Helm version.
@@ -254,6 +255,30 @@ Parameters
Helm option to force reinstall, ignore on new install.
+
With Helm v4 this performs a client-side replacement. Helm v4 deprecated --force (split into --force-replace and --force-conflicts) and enables server-side apply by default, so for Helm v4 the module emits --server-side=false --force-replace to preserve the Helm v3 behaviour. With Helm v3 the --force flag is used. The O(force) option works the same way regardless of the installed Helm version.
+
Mutually exclusive with O(server_side) and O(force_conflicts).
+ + + + +
+ force_conflicts + +
+ boolean +
+
added in 6.5.0
+ + + + + +
When server-side apply is enabled (the Helm v4 default), force changes against conflicts instead of failing.
+
Maps to the --force-conflicts flag.
+
This option requires Helm v4, cannot be combined with O(server_side=false), and is mutually exclusive with O(force).
@@ -542,6 +567,29 @@ Parameters
If reset_values is set to True, this is ignored.
+ + +
+ server_side + +
+ string +
+
added in 6.5.0
+ + + + + +
Control Helm v4 server-side apply when installing or upgrading a release.
+
Maps to the --server-side flag, which accepts true, false or auto.
+
This option requires Helm v4 and is mutually exclusive with O(force).
+ +
diff --git a/docs/kubernetes.core.helm_plugin_module.rst b/docs/kubernetes.core.helm_plugin_module.rst index 3bcc4f49..dec753d7 100644 --- a/docs/kubernetes.core.helm_plugin_module.rst +++ b/docs/kubernetes.core.helm_plugin_module.rst @@ -120,6 +120,24 @@ Parameters
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+ + +
+ keyring + +
+ path +
+
added in 6.5.0
+ + + + +
Location of public keys used for verification.
+
Only valid with state=present, which maps to the helm plugin install subcommand.
+
This option requires helm version >= 4.0.0.
+ +
diff --git a/docs/kubernetes.core.helm_registry_auth_module.rst b/docs/kubernetes.core.helm_registry_auth_module.rst index b3047520..1e8b394f 100644 --- a/docs/kubernetes.core.helm_registry_auth_module.rst +++ b/docs/kubernetes.core.helm_registry_auth_module.rst @@ -289,7 +289,9 @@ Common return values are documented `here always -
Full helm command stderr, in case you want to display it or examine the event log. Please be note that helm binnary may print messages to stderr even if the command is successful.
+
Full helm command stderr, in case you want to display it or examine the event log.
+
Please note that the helm binary may print messages to stderr even if the command is successful.
+
On Helm versions earlier than 4.2.1, success messages such as Login Succeeded are printed here; as of Helm 4.2.1 they are printed to stdout (see https://github.com/helm/helm/pull/32056).

Sample:
Login Succeeded\n
@@ -321,14 +323,17 @@ Common return values are documented `here always -
Full helm command stdout, in case you want to display it or examine the event log
+
Full helm command stdout, in case you want to display it or examine the event log.
+
As of Helm 4.2.1 success messages such as Login Succeeded are printed to stdout (see https://github.com/helm/helm/pull/32056). On earlier versions they are printed to stderr.

+
Sample:
+
Login Succeeded\n
- stout_lines + stdout_lines
list diff --git a/docs/kubernetes.core.k8s_cluster_info_module.rst b/docs/kubernetes.core.k8s_cluster_info_module.rst index a0b621d6..580de1ca 100644 --- a/docs/kubernetes.core.k8s_cluster_info_module.rst +++ b/docs/kubernetes.core.k8s_cluster_info_module.rst @@ -416,7 +416,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_cp_module.rst b/docs/kubernetes.core.k8s_cp_module.rst index f74a0eac..3ca9cf9e 100644 --- a/docs/kubernetes.core.k8s_cp_module.rst +++ b/docs/kubernetes.core.k8s_cp_module.rst @@ -571,7 +571,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_drain_module.rst b/docs/kubernetes.core.k8s_drain_module.rst index 995e9113..d9341b9b 100644 --- a/docs/kubernetes.core.k8s_drain_module.rst +++ b/docs/kubernetes.core.k8s_drain_module.rst @@ -627,7 +627,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_exec_module.rst b/docs/kubernetes.core.k8s_exec_module.rst index 49be3421..a46c7f14 100644 --- a/docs/kubernetes.core.k8s_exec_module.rst +++ b/docs/kubernetes.core.k8s_exec_module.rst @@ -481,7 +481,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_info_module.rst b/docs/kubernetes.core.k8s_info_module.rst index c9768004..c0c2c436 100644 --- a/docs/kubernetes.core.k8s_info_module.rst +++ b/docs/kubernetes.core.k8s_info_module.rst @@ -720,7 +720,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_json_patch_module.rst b/docs/kubernetes.core.k8s_json_patch_module.rst index 1a737fc7..1fb6e234 100644 --- a/docs/kubernetes.core.k8s_json_patch_module.rst +++ b/docs/kubernetes.core.k8s_json_patch_module.rst @@ -640,7 +640,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_log_module.rst b/docs/kubernetes.core.k8s_log_module.rst index f2cbe671..da0de88d 100644 --- a/docs/kubernetes.core.k8s_log_module.rst +++ b/docs/kubernetes.core.k8s_log_module.rst @@ -612,7 +612,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_lookup.rst b/docs/kubernetes.core.k8s_lookup.rst index 347a8c05..c8cb00f8 100644 --- a/docs/kubernetes.core.k8s_lookup.rst +++ b/docs/kubernetes.core.k8s_lookup.rst @@ -38,13 +38,13 @@ Parameters - + - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - -
ParameterParameter Choices/Defaults Configuration Comments
+
api_key @@ -61,7 +61,7 @@ Parameters
+
api_version @@ -79,7 +79,7 @@ Parameters
+
ca_cert @@ -97,7 +97,7 @@ Parameters
+
client_cert @@ -115,7 +115,7 @@ Parameters
+
client_key @@ -133,7 +133,7 @@ Parameters
+
cluster_info @@ -150,7 +150,7 @@ Parameters
+
context @@ -167,7 +167,7 @@ Parameters
+
field_selector @@ -184,7 +184,7 @@ Parameters
+
host @@ -201,7 +201,7 @@ Parameters
+
kind @@ -219,7 +219,7 @@ Parameters
+
kubeconfig @@ -236,7 +236,7 @@ Parameters
+
label_selector @@ -253,7 +253,7 @@ Parameters
+
namespace @@ -270,7 +270,26 @@ Parameters
+ +
+ no_proxy + +
+ string +
+ 		+ + +
The comma separated list of hosts/domains/IP/CIDR that shouldn't go through proxy. Can also be specified via K8S_AUTH_NO_PROXY environment variable.
+
Please note that this module does not pick up typical proxy settings from the environment (e.g. NO_PROXY).
+
This feature requires kubernetes>=19.15.0. When kubernetes library is less than 19.15.0, it fails even if no_proxy is set correctly.
+
password @@ -287,7 +306,101 @@ Parameters
+
+ proxy + +
+ string +
+ 		+ + +
The URL of an HTTP proxy to use for the connection. Can also be specified via K8S_AUTH_PROXY environment variable.
+
Please note that this module does not pick up typical proxy settings from the environment (e.g. HTTP_PROXY).
+
+
+ proxy_headers + +
+ dictionary +
+ 		+ + +
The Header used for the HTTP proxy.
+ +
+
+ basic_auth + +
+ string +
+ 		+ + +
Colon-separated username:password for basic authentication header.
+
Can also be specified via K8S_AUTH_PROXY_HEADERS_BASIC_AUTH environment.
+
+
+ proxy_basic_auth + +
+ string +
+ 		+ + +
Colon-separated username:password for proxy basic authentication header.
+
Can also be specified via K8S_AUTH_PROXY_HEADERS_PROXY_BASIC_AUTH environment.
+
+
+ user_agent + +
+ string +
+ 		+ + +
String representing the user-agent you want, such as foo/1.0.
+
Can also be specified via K8S_AUTH_PROXY_HEADERS_USER_AGENT environment.
+
resource_definition @@ -304,7 +417,7 @@ Parameters
+
resource_name @@ -321,7 +434,7 @@ Parameters
+
src @@ -339,7 +452,7 @@ Parameters
+
username @@ -356,7 +469,7 @@ Parameters
+
validate_certs @@ -432,7 +545,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this lookup: +Common return values are documented `here `_, the following are the fields unique to this lookup: .. raw:: html diff --git a/docs/kubernetes.core.k8s_module.rst b/docs/kubernetes.core.k8s_module.rst index de083a9c..43259876 100644 --- a/docs/kubernetes.core.k8s_module.rst +++ b/docs/kubernetes.core.k8s_module.rst @@ -1279,18 +1279,35 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + - - - - - - + + - + + - + + - + + + + + + + + + + + + + +
KeyKey Returned Description
+ +
+ method + +
+ string +
+ 		success +
The method used to deploy the resource.
+
+
Sample:
+
create
+
result @@ -1306,6 +1323,105 @@ Common return values are documented `here
  +
+ api_version + +
+ string +
+ 		when O(resource_definition) or O(src) contains a single object. +
The versioned schema of this representation of an object.
+
+
  +
+ duration + +
+ integer +
+ 		when wait is true +
elapsed time of task in seconds
+
+
Sample:
+
48
+
  +
+ error + +
+ complex +
+ 		error +
error while trying to create/delete the object.
+
+
  +
+ kind + +
+ string +
+ 		when O(resource_definition) or O(src) contains a single object. +
Represents the REST resource this object represents.
+
+
  +
+ metadata + +
+ complex +
+ 		when O(resource_definition) or O(src) contains a single object. +
Standard object metadata. Includes name, namespace, annotations, labels, etc.
+
+
  +
+ results + +
+ complex +
+ 		when O(resource_definition) or O(src) contains a list of objects. +
An array of created, patched, or otherwise present objects.
+
+
  
api_version @@ -1314,7 +1430,7 @@ Common return values are documented `here string 		successwhen O(resource_definition) or O(src) contains a single object.
The versioned schema of this representation of an object.

@@ -1322,6 +1438,7 @@ Common return values are documented `here
  
duration @@ -1340,6 +1457,7 @@ Common return values are documented `here
  
error @@ -1356,21 +1474,6 @@ Common return values are documented `here
  -
- items - -
- list -
- 		when resource_definition or src contains list of objects -
Returned only when multiple yaml documents are passed to src or resource_definition
-
-
 
@@ -1380,7 +1483,7 @@ Common return values are documented `here string 		successwhen O(resource_definition) or O(src) contains a single object.
Represents the REST resource this object represents.

@@ -1388,6 +1491,7 @@ Common return values are documented `here
  
metadata @@ -1396,7 +1500,7 @@ Common return values are documented `here complex 		successwhen O(resource_definition) or O(src) contains a single object.
Standard object metadata. Includes name, namespace, annotations, labels, etc.

@@ -1404,6 +1508,7 @@ Common return values are documented `here
  
spec @@ -1412,7 +1517,7 @@ Common return values are documented `here complex 		successwhen O(resource_definition) or O(src) contains a single object.
Specific attributes of the object. Will vary based on the api_version and kind.

@@ -1420,6 +1525,7 @@ Common return values are documented `here
  
status @@ -1428,7 +1534,40 @@ Common return values are documented `here complex 		successwhen O(resource_definition) or O(src) contains a single object. +
Current status details for the object.
+
+
  +
+ spec + +
+ complex +
+ 		when O(resource_definition) or O(src) contains a single object. +
Specific attributes of the object. Will vary based on the api_version and kind.
+
+
  +
+ status + +
+ complex +
+ 		when O(resource_definition) or O(src) contains a single object.
Current status details for the object.

diff --git a/docs/kubernetes.core.k8s_rollback_module.rst b/docs/kubernetes.core.k8s_rollback_module.rst index f5f29aa5..e0020598 100644 --- a/docs/kubernetes.core.k8s_rollback_module.rst +++ b/docs/kubernetes.core.k8s_rollback_module.rst @@ -503,7 +503,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_scale_module.rst b/docs/kubernetes.core.k8s_scale_module.rst index 101eee81..ffc1b34b 100644 --- a/docs/kubernetes.core.k8s_scale_module.rst +++ b/docs/kubernetes.core.k8s_scale_module.rst @@ -686,7 +686,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_service_module.rst b/docs/kubernetes.core.k8s_service_module.rst index 57ebe6d1..de0b4336 100644 --- a/docs/kubernetes.core.k8s_service_module.rst +++ b/docs/kubernetes.core.k8s_service_module.rst @@ -614,7 +614,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.k8s_taint_module.rst b/docs/kubernetes.core.k8s_taint_module.rst index b3a08974..cd015677 100644 --- a/docs/kubernetes.core.k8s_taint_module.rst +++ b/docs/kubernetes.core.k8s_taint_module.rst @@ -541,7 +541,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html diff --git a/docs/kubernetes.core.kubeconfig_module.rst b/docs/kubernetes.core.kubeconfig_module.rst new file mode 100644 index 00000000..0f792f54 --- /dev/null +++ b/docs/kubernetes.core.kubeconfig_module.rst @@ -0,0 +1,863 @@ +.. _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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ 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 + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ 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) diff --git a/docs/kubernetes.core.kustomize_lookup.rst b/docs/kubernetes.core.kustomize_lookup.rst index 70befc75..bdaeaa76 100644 --- a/docs/kubernetes.core.kustomize_lookup.rst +++ b/docs/kubernetes.core.kustomize_lookup.rst @@ -177,7 +177,7 @@ Examples Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this lookup: +Common return values are documented `here `_, the following are the fields unique to this lookup: .. raw:: html