kubernetes.core.kubectl_connection.rst

kubernetes.core.kubectl

Execute tasks in pods running on Kubernetes.

• Synopsis
• Requirements
• Parameters
• Examples
• Status

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

Parameter	Choices/Defaults	Configuration	Comments
ca_cert -	Default: ""	env:K8S_AUTH_SSL_CA_CERT var: ansible_kubectl_ssl_ca_cert var: ansible_kubectl_ca_cert	Path to a CA certificate used to authenticate with the API. aliases: kubectl_ssl_ca_cert
client_cert -	Default: ""	env:K8S_AUTH_CERT_FILE var: ansible_kubectl_cert_file var: ansible_kubectl_client_cert	Path to a certificate used to authenticate with the API. aliases: kubectl_cert_file
client_key -	Default: ""	env:K8S_AUTH_KEY_FILE var: ansible_kubectl_key_file var: ansible_kubectl_client_key	Path to a key file used to authenticate with the API. aliases: kubectl_key_file
kubectl_container -	Default: ""	env:K8S_AUTH_CONTAINER var: ansible_kubectl_container	Container name. Required when a pod contains more than one container.
kubectl_context -	Default: ""	env:K8S_AUTH_CONTEXT var: ansible_kubectl_context	The name of a context found in the K8s config file.
kubectl_extra_args -	Default: ""	env:K8S_AUTH_EXTRA_ARGS var: ansible_kubectl_extra_args	Extra arguments to pass to the kubectl command line. Please be aware that this passes information directly on the command line and it could expose sensitive data.
kubectl_host -	Default: ""	env:K8S_AUTH_HOST env:K8S_AUTH_SERVER var: ansible_kubectl_host var: ansible_kubectl_server	URL for accessing the API.
kubectl_kubeconfig -	Default: ""	env:K8S_AUTH_KUBECONFIG var: ansible_kubectl_kubeconfig var: ansible_kubectl_config	Path to a kubectl config file. Defaults to ~/.kube/config The configuration can be provided as dictionary. Added in version 2.4.0.
kubectl_local_env_vars dictionary added in 3.1.0	Default: {}	var: ansible_kubectl_local_env_vars	Local enviromantal variable to be passed locally to the kubectl command line. Please be aware that this passes information directly on the command line and it could expose sensitive data.
kubectl_namespace -	Default: ""	env:K8S_AUTH_NAMESPACE var: ansible_kubectl_namespace	The namespace of the pod
kubectl_password -	Default: ""	env:K8S_AUTH_PASSWORD var: ansible_kubectl_password	Provide a password for authenticating with the API. 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.
kubectl_pod -	Default: ""	env:K8S_AUTH_POD var: ansible_kubectl_pod	Pod name. Required when the host name does not match pod name.
kubectl_token -		env:K8S_AUTH_TOKEN env:K8S_AUTH_API_KEY var: ansible_kubectl_token var: ansible_kubectl_api_key	API authentication bearer token. 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.
kubectl_username -	Default: ""	env:K8S_AUTH_USERNAME var: ansible_kubectl_username var: ansible_kubectl_user	Provide a username for authenticating with the API.
validate_certs -	Default: ""	env:K8S_AUTH_VERIFY_SSL var: ansible_kubectl_verify_ssl var: ansible_kubectl_validate_certs	Whether or not to verify the API server's SSL certificate. Defaults to true. aliases: kubectl_verify_ssl

Examples

- 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.