mirror of
https://github.com/ansible-collections/kubernetes.core.git
synced 2026-03-26 21:33:02 +00:00
fb80d973c4
Doc: add example of using kubectl connection plugin SUMMARY Currently documentation for collection don't include any examples of using kubenrenes.core.kubectl connection plugin and it's hard to start using that plugin. ISSUE TYPE Docs Pull Request COMPONENT NAME kubenrenes.core.kubectl connection plugin ADDITIONAL INFORMATION This PR was inspired by #288 and based on feedback on that PR and my own experience. Thanks @tpo for his try and @geerlingguy for his Ansible for DevOps book Reviewed-by: Bikouo Aubin Reviewed-by: Sandra McCann <samccann@redhat.com> Reviewed-by: Mike Graves <mgraves@redhat.com> Reviewed-by: Yuriy Novostavskiy Reviewed-by: purdzan
460 lines
19 KiB
ReStructuredText
460 lines
19 KiB
ReStructuredText
.. _kubernetes.core.kubectl_connection:
|
|
|
|
|
|
***********************
|
|
kubernetes.core.kubectl
|
|
***********************
|
|
|
|
**Execute tasks in pods running on Kubernetes.**
|
|
|
|
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
Synopsis
|
|
--------
|
|
- Use the kubectl exec command to run tasks in, or put/fetch files to, pods running on the Kubernetes container platform.
|
|
|
|
|
|
|
|
Requirements
|
|
------------
|
|
The below requirements are needed on the local Ansible controller node that executes this connection.
|
|
|
|
- kubectl (go binary)
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="1">Parameter</th>
|
|
<th>Choices/<font color="blue">Defaults</font></th>
|
|
<th>Configuration</th>
|
|
<th width="100%">Comments</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>ca_cert</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_SSL_CA_CERT</div>
|
|
<div>var: ansible_kubectl_ssl_ca_cert</div>
|
|
<div>var: ansible_kubectl_ca_cert</div>
|
|
</td>
|
|
<td>
|
|
<div>Path to a CA certificate used to authenticate with the API.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: kubectl_ssl_ca_cert</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>client_cert</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_CERT_FILE</div>
|
|
<div>var: ansible_kubectl_cert_file</div>
|
|
<div>var: ansible_kubectl_client_cert</div>
|
|
</td>
|
|
<td>
|
|
<div>Path to a certificate used to authenticate with the API.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: kubectl_cert_file</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>client_key</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_KEY_FILE</div>
|
|
<div>var: ansible_kubectl_key_file</div>
|
|
<div>var: ansible_kubectl_client_key</div>
|
|
</td>
|
|
<td>
|
|
<div>Path to a key file used to authenticate with the API.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: kubectl_key_file</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_container</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_CONTAINER</div>
|
|
<div>var: ansible_kubectl_container</div>
|
|
</td>
|
|
<td>
|
|
<div>Container name.</div>
|
|
<div>Required when a pod contains more than one container.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_context</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_CONTEXT</div>
|
|
<div>var: ansible_kubectl_context</div>
|
|
</td>
|
|
<td>
|
|
<div>The name of a context found in the K8s config file.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_extra_args</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_EXTRA_ARGS</div>
|
|
<div>var: ansible_kubectl_extra_args</div>
|
|
</td>
|
|
<td>
|
|
<div>Extra arguments to pass to the kubectl command line.</div>
|
|
<div>Please be aware that this passes information directly on the command line and it could expose sensitive data.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_host</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_HOST</div>
|
|
<div>env:K8S_AUTH_SERVER</div>
|
|
<div>var: ansible_kubectl_host</div>
|
|
<div>var: ansible_kubectl_server</div>
|
|
</td>
|
|
<td>
|
|
<div>URL for accessing the API.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_kubeconfig</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_KUBECONFIG</div>
|
|
<div>var: ansible_kubectl_kubeconfig</div>
|
|
<div>var: ansible_kubectl_config</div>
|
|
</td>
|
|
<td>
|
|
<div>Path to a kubectl config file. Defaults to <em>~/.kube/config</em></div>
|
|
<div>The configuration can be provided as dictionary. Added in version 2.4.0.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_local_env_vars</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
<div style="font-style: italic; font-size: small; color: darkgreen">added in 3.1.0</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">{}</div>
|
|
</td>
|
|
<td>
|
|
<div>var: ansible_kubectl_local_env_vars</div>
|
|
</td>
|
|
<td>
|
|
<div>Local enviromantal variable to be passed locally to the kubectl command line.</div>
|
|
<div>Please be aware that this passes information directly on the command line and it could expose sensitive data.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_namespace</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_NAMESPACE</div>
|
|
<div>var: ansible_kubectl_namespace</div>
|
|
</td>
|
|
<td>
|
|
<div>The namespace of the pod</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_password</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_PASSWORD</div>
|
|
<div>var: ansible_kubectl_password</div>
|
|
</td>
|
|
<td>
|
|
<div>Provide a password for authenticating with the API.</div>
|
|
<div>Please be aware that this passes information directly on the command line and it could expose sensitive data. We recommend using the file based authentication options instead.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_pod</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_POD</div>
|
|
<div>var: ansible_kubectl_pod</div>
|
|
</td>
|
|
<td>
|
|
<div>Pod name.</div>
|
|
<div>Required when the host name does not match pod name.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_token</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_TOKEN</div>
|
|
<div>env:K8S_AUTH_API_KEY</div>
|
|
<div>var: ansible_kubectl_token</div>
|
|
<div>var: ansible_kubectl_api_key</div>
|
|
</td>
|
|
<td>
|
|
<div>API authentication bearer token.</div>
|
|
<div>Please be aware that this passes information directly on the command line and it could expose sensitive data. We recommend using the file based authentication options instead.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>kubectl_username</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_USERNAME</div>
|
|
<div>var: ansible_kubectl_username</div>
|
|
<div>var: ansible_kubectl_user</div>
|
|
</td>
|
|
<td>
|
|
<div>Provide a username for authenticating with the API.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>validate_certs</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">-</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">""</div>
|
|
</td>
|
|
<td>
|
|
<div>env:K8S_AUTH_VERIFY_SSL</div>
|
|
<div>var: ansible_kubectl_verify_ssl</div>
|
|
<div>var: ansible_kubectl_validate_certs</div>
|
|
</td>
|
|
<td>
|
|
<div>Whether or not to verify the API server's SSL certificate. Defaults to <em>true</em>.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: kubectl_verify_ssl</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/>
|
|
|
|
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: Run a command in a pod using local kubectl with kubeconfig file ~/.kube/config
|
|
hosts: localhost
|
|
gather_facts: no
|
|
vars:
|
|
ansible_connection: kubernetes.core.kubectl
|
|
ansible_kubectl_namespace: my-namespace
|
|
ansible_kubectl_pod: my-pod
|
|
ansible_kubectl_container: my-container
|
|
tasks:
|
|
# be aware that the command is executed as the user that started the container
|
|
# and requires python to be installed in the image
|
|
- name: Run a command in a pod
|
|
ansible.builtin.command: echo "Hello, World!"
|
|
|
|
- name: Run a command in a pod using local kubectl with inventory variables
|
|
# Example inventory:
|
|
# k8s:
|
|
# hosts:
|
|
# foo.example.com:
|
|
# ansible_connection: kubernetes.core.kubectl
|
|
# ansible_kubectl_kubeconfig: /root/.kube/foo.example.com.config
|
|
# ansible_kubectl_pod: my-foo-pod
|
|
# ansible_kubectl_container: my-foo-container
|
|
# ansible_kubectl_namespace: my-foo-namespace
|
|
# bar.example.com:
|
|
# ansible_connection: kubernetes.core.kubectl
|
|
# ansible_kubectl_kubeconfig: /root/.kube/bar.example.com.config
|
|
# ansible_kubectl_pod: my-bar-pod
|
|
# ansible_kubectl_container: my-bar-container
|
|
# ansible_kubectl_namespace: my-bar-namespace
|
|
hosts: k8s
|
|
gather_facts: no
|
|
tasks:
|
|
# be aware that the command is executed as the user that started the container
|
|
# and requires python to be installed in the image
|
|
- name: Run a command in a pod
|
|
ansible.builtin.command: echo "Hello, World!"
|
|
|
|
- name: Run a command in a pod using dynamic inventory
|
|
hosts: localhost
|
|
gather_facts: no
|
|
vars:
|
|
kubeconfig: /root/.kube/config
|
|
namespace: my-namespace
|
|
my_app: my-app
|
|
tasks:
|
|
- name: Get My App pod info based on label
|
|
kubernetes.core.k8s_info:
|
|
kubeconfig: "{{ kubeconfig }}"
|
|
namespace: "{{ namespace }}"
|
|
kind: Pod
|
|
label_selectors: app.kubernetes.io/name = "{{ my_app }}"
|
|
register: my_app_pod
|
|
|
|
- name: Get My App pod name
|
|
ansible.builtin.set_fact:
|
|
my_app_pod_name: "{{ my_app_pod.resources[0].metadata.name }}"
|
|
|
|
- name: Add My App pod to inventory
|
|
ansible.builtin.add_host:
|
|
name: "{{ my_app_pod_name }}"
|
|
ansible_connection: kubernetes.core.kubectl
|
|
ansible_kubectl_kubeconfig: "{{ kubeconfig }}"
|
|
ansible_kubectl_pod: "{{ my_app_pod_name }}"
|
|
ansible_kubectl_namespace: "{{ namespace }}"
|
|
|
|
- name: Run a command in My App pod
|
|
# be aware that the command is executed as the user that started the container
|
|
# and requires python to be installed in the image
|
|
ansible.builtin.command: echo "Hello, World!"
|
|
delegate_to: "{{ my_app_pod_name }}"
|
|
|
|
|
|
|
|
|
|
Status
|
|
------
|
|
|
|
|
|
Authors
|
|
~~~~~~~
|
|
|
|
- xuxinkun (@xuxinkun)
|
|
|
|
|
|
.. hint::
|
|
Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.
|