kubernetes.core.kubectl connection – Execute tasks in pods running on Kubernetes.

Note

This connection plugin is part of the kubernetes.core collection (version 5.0.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 connection plugin, see Requirements for details.

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

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 controller node that executes this connection.

  • kubectl (go binary)

Parameters

Parameter

Comments

ca_cert

aliases: kubectl_ssl_ca_cert

string

Path to a CA certificate used to authenticate with the API.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_SSL_CA_CERT

  • Variable: ansible_kubectl_ssl_ca_cert

  • Variable: ansible_kubectl_ca_cert

client_cert

aliases: kubectl_cert_file

string

Path to a certificate used to authenticate with the API.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_CERT_FILE

  • Variable: ansible_kubectl_cert_file

  • Variable: ansible_kubectl_client_cert

client_key

aliases: kubectl_key_file

string

Path to a key file used to authenticate with the API.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_KEY_FILE

  • Variable: ansible_kubectl_key_file

  • Variable: ansible_kubectl_client_key

kubectl_container

string

Container name.

Required when a pod contains more than one container.

Default: ""

Configuration:

kubectl_context

string

The name of a context found in the K8s config file.

Default: ""

Configuration:

kubectl_extra_args

string

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.

Default: ""

Configuration:

kubectl_host

string

URL for accessing the API.

Default: ""

Configuration:

kubectl_kubeconfig

string

Path to a kubectl config file. Defaults to ~/.kube/config

The configuration can be provided as dictionary. Added in version 2.4.0.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_KUBECONFIG

  • Variable: ansible_kubectl_kubeconfig

  • Variable: ansible_kubectl_config

kubectl_local_env_vars

dictionary

added in kubernetes.core 3.1.0

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.

Default: {}

Configuration:

  • Variable: ansible_kubectl_local_env_vars

kubectl_namespace

string

The namespace of the pod

Default: ""

Configuration:

kubectl_password

string

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.

Default: ""

Configuration:

kubectl_pod

string

Pod name.

Required when the host name does not match pod name.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_POD

  • Variable: ansible_kubectl_pod

kubectl_token

string

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.

Configuration:

kubectl_username

string

Provide a username for authenticating with the API.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_USERNAME

  • Variable: ansible_kubectl_username

  • Variable: ansible_kubectl_user

validate_certs

aliases: kubectl_verify_ssl

string

Whether or not to verify the API server’s SSL certificate. Defaults to true.

Default: ""

Configuration:

  • Environment variable: K8S_AUTH_VERIFY_SSL

  • Variable: ansible_kubectl_verify_ssl

  • Variable: ansible_kubectl_validate_certs

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 }}"

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.