425 lines
17 KiB
ReStructuredText
425 lines
17 KiB
ReStructuredText
.. _community.okd.openshift_auth_module:
|
||
|
||
|
||
****************************
|
||
community.okd.openshift_auth
|
||
****************************
|
||
|
||
**Authenticate to OpenShift clusters which require an explicit login step**
|
||
|
||
|
||
Version added: 0.2.0
|
||
|
||
.. contents::
|
||
:local:
|
||
:depth: 1
|
||
|
||
|
||
Synopsis
|
||
--------
|
||
- This module handles authenticating to OpenShift 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).
|
||
- 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.
|
||
|
||
|
||
|
||
Requirements
|
||
------------
|
||
The below requirements are needed on the host that executes this module.
|
||
|
||
- python >= 3.6
|
||
- urllib3
|
||
- requests
|
||
- requests-oauthlib
|
||
|
||
|
||
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 width="100%">Comments</th>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
||
<b>api_key</b>
|
||
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
</td>
|
||
<td>
|
||
<div>When <code>state</code> is set to <em>absent</em>, this specifies the token to revoke.</div>
|
||
</td>
|
||
</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">path</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
</td>
|
||
<td>
|
||
<div>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.</div>
|
||
<div style="font-size: small; color: darkgreen"><br/>aliases: ssl_ca_cert</div>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
||
<b>host</b>
|
||
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
/ <span style="color: red">required</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
</td>
|
||
<td>
|
||
<div>Provide a URL for accessing the API server.</div>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
||
<b>password</b>
|
||
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
</td>
|
||
<td>
|
||
<div>Provide a password for authenticating with the API server.</div>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
||
<b>state</b>
|
||
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
||
<li><div style="color: blue"><b>present</b> ←</div></li>
|
||
<li>absent</li>
|
||
</ul>
|
||
</td>
|
||
<td>
|
||
<div>If set to <em>present</em> connect to the API server using the URL specified in <code>host</code> and attempt to log in.</div>
|
||
<div>If set to <em>absent</em> attempt to log out by revoking the authentication token specified in <code>api_key</code>.</div>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
||
<b>username</b>
|
||
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
</td>
|
||
<td>
|
||
<div>Provide a username for authenticating with the API server.</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">boolean</span>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
||
<li>no</li>
|
||
<li><div style="color: blue"><b>yes</b> ←</div></li>
|
||
</ul>
|
||
</td>
|
||
<td>
|
||
<div>Whether or not to verify the API server's SSL certificates.</div>
|
||
<div style="font-size: small; color: darkgreen"><br/>aliases: verify_ssl</div>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<br/>
|
||
|
||
|
||
|
||
|
||
Examples
|
||
--------
|
||
|
||
.. code-block:: yaml
|
||
|
||
- 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: openshift_passwords.yml
|
||
|
||
- name: Log in (obtain access token)
|
||
community.okd.openshift_auth:
|
||
username: admin
|
||
password: "{{ openshift_admin_password }}"
|
||
register: openshift_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
|
||
kubernetes.core.k8s_info:
|
||
api_key: "{{ openshift_auth_results.openshift_auth.api_key }}"
|
||
kind: Pod
|
||
register: pod_list
|
||
|
||
always:
|
||
- name: If login succeeded, try to log out (revoke access token)
|
||
when: openshift_auth_results.openshift_auth.api_key is defined
|
||
community.okd.openshift_auth:
|
||
state: absent
|
||
api_key: "{{ openshift_auth_results.openshift_auth.api_key }}"
|
||
|
||
|
||
|
||
Return Values
|
||
-------------
|
||
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module:
|
||
|
||
.. raw:: html
|
||
|
||
<table border=0 cellpadding=0 class="documentation-table">
|
||
<tr>
|
||
<th colspan="2">Key</th>
|
||
<th>Returned</th>
|
||
<th width="100%">Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>k8s_auth</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">complex</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Same as returned openshift_auth. Kept only for backwards compatibility</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>api_key</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Authentication token.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>ca_cert</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Path to a CA certificate file used to verify connection to the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>host</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>URL for accessing the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>username</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Username for authenticating with the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>validate_certs</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">boolean</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Whether or not to verify the API server's SSL certificates.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>openshift_auth</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">complex</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>OpenShift authentication facts.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>api_key</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Authentication token.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>ca_cert</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Path to a CA certificate file used to verify connection to the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>host</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>URL for accessing the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>username</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">string</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Username for authenticating with the API server.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="elbow-placeholder"> </td>
|
||
<td colspan="1">
|
||
<div class="ansibleOptionAnchor" id="return-"></div>
|
||
<b>validate_certs</b>
|
||
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
||
<div style="font-size: small">
|
||
<span style="color: purple">boolean</span>
|
||
</div>
|
||
</td>
|
||
<td>success</td>
|
||
<td>
|
||
<div>Whether or not to verify the API server's SSL certificates.</div>
|
||
<br/>
|
||
</td>
|
||
</tr>
|
||
|
||
</table>
|
||
<br/><br/>
|
||
|
||
|
||
Status
|
||
------
|
||
|
||
|
||
Authors
|
||
~~~~~~~
|
||
|
||
- KubeVirt Team (@kubevirt)
|
||
- Fabian von Feilitzsch (@fabianvf)
|