k8s_auth – Authenticate to Kubernetes clusters which require an explicit login step
New in version 2.8.
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 thehost
,username
andpassword
parameters. Please consult your preferred module’s documentation for more details.
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 - | When state is set to absent, this specifies the token to revoke. | |
ca_cert - | 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 - / required | Provide a URL for accessing the API server. | |
password - | Provide a password for authenticating with the API server. | |
state - |
| 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 - | Provide a username for authenticating with the API server. | |
validate_certs boolean |
| 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) 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 k8s_facts: 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 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. |
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- KubeVirt Team (@kubevirt)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/k8s_auth_module.html