community.kubernetes.k8s_auth – Authenticate to Kubernetes clusters which require an explicit login step

Note

This plugin is part of the community.kubernetes collection (version 1.2.1).

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

To use it in a playbook, specify: community.kubernetes.k8s_auth.

Synopsis

  • This module handles authenticating to Kubernetes clusters requiring explicit authentication procedures, meaning ones where a client logs in (obtains an authentication token), performs API operations using said token and then logs out (revokes the token). An example of a Kubernetes distribution requiring this module is OpenShift.
  • On the other hand a popular configuration for username+password authentication is one utilizing HTTP Basic Auth, which does not involve any additional login/logout steps (instead login credentials can be attached to each and every API call performed) and as such is handled directly by the k8s module (and other resource–specific modules) by utilizing the host, username and password parameters. Please consult your preferred module’s documentation for more details.

Note

This module has a corresponding action plugin.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.7
  • urllib3
  • requests
  • requests-oauthlib

Parameters

Parameter Choices/Defaults Comments
api_key
string
When state is set to absent, this specifies the token to revoke.
ca_cert
path
Path to a CA certificate file used to verify connection to the API server. The full certificate chain must be provided to avoid certificate validation errors.

aliases: ssl_ca_cert
host
string / required
Provide a URL for accessing the API server.
password
string
Provide a password for authenticating with the API server.
state
string
    Choices:
  • present
  • absent
If set to present connect to the API server using the URL specified in host and attempt to log in.
If set to absent attempt to log out by revoking the authentication token specified in api_key.
username
string
Provide a username for authenticating with the API server.
validate_certs
boolean
    Choices:
  • no
  • yes
Whether or not to verify the API server's SSL certificates.

aliases: verify_ssl

Examples

- hosts: localhost
  module_defaults:
    group/k8s:
      host: https://k8s.example.com/
      ca_cert: ca.pem
  tasks:
  - block:
    # It's good practice to store login credentials in a secure vault and not
    # directly in playbooks.
    - include_vars: k8s_passwords.yml

    - name: Log in (obtain access token)
      community.kubernetes.k8s_auth:
        username: admin
        password: "{{ k8s_admin_password }}"
      register: k8s_auth_results

    # Previous task provides the token/api_key, while all other parameters
    # are taken from module_defaults
    - name: Get a list of all pods from any namespace
      community.kubernetes.k8s_info:
        api_key: "{{ k8s_auth_results.k8s_auth.api_key }}"
        kind: Pod
      register: pod_list

    always:
    - name: If login succeeded, try to log out (revoke access token)
      when: k8s_auth_results.k8s_auth.api_key is defined
      community.kubernetes.k8s_auth:
        state: absent
        api_key: "{{ k8s_auth_results.k8s_auth.api_key }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
k8s_auth
complex
success
Kubernetes authentication facts.

api_key
string
success
Authentication token.

ca_cert
string
success
Path to a CA certificate file used to verify connection to the API server.

host
string
success
URL for accessing the API server.

username
string
success
Username for authenticating with the API server.

validate_certs
boolean
success
Whether or not to verify the API server's SSL certificates.



Authors

  • KubeVirt Team (@kubevirt)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/kubernetes/k8s_auth_module.html