From 748d40d2444d82cf04ffab28b0197bf70480f19b Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Tue, 13 Apr 2021 11:07:23 +0530 Subject: [PATCH] Added docs for the collection (#83) --- README.md | 39 +- changelogs/fragments/add_docs.yml | 3 + docs/community.okd.k8s_module.rst | 910 +++++++++++ docs/community.okd.oc_connection.rst | 315 ++++ docs/community.okd.openshift_auth_module.rst | 424 ++++++ docs/community.okd.openshift_inventory.rst | 355 +++++ ...community.okd.openshift_process_module.rst | 935 ++++++++++++ docs/community.okd.openshift_route_module.rst | 1352 +++++++++++++++++ 8 files changed, 4323 insertions(+), 10 deletions(-) create mode 100644 changelogs/fragments/add_docs.yml create mode 100644 docs/community.okd.k8s_module.rst create mode 100644 docs/community.okd.oc_connection.rst create mode 100644 docs/community.okd.openshift_auth_module.rst create mode 100644 docs/community.okd.openshift_inventory.rst create mode 100644 docs/community.okd.openshift_process_module.rst create mode 100644 docs/community.okd.openshift_route_module.rst diff --git a/README.md b/README.md index 2e2fde8..b9dbc90 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,40 @@ This repo hosts the `community.okd` Ansible Collection. The collection includes a variety of Ansible content to help automate the management of applications in OKD clusters, as well as the provisioning and maintenance of clusters themselves. + +## Ansible version compatibility + +This collection has been tested against following Ansible versions: **>=2.9**. + +Plugins and modules within a collection may be tested with only specific Ansible versions. +A collection may contain metadata that identifies these versions. +PEP440 is the schema used to describe the versions of Ansible. + + ## Included content Click on the name of a plugin or module to view that content's documentation: - - **Connection Plugins**: - - [oc](https://docs.ansible.com/ansible/2.10/collections/community/general/oc_connection.html) - - **Inventory Plugins**: - - [openshift](https://docs.ansible.com/ansible/2.10/collections/community/kubernetes/openshift_inventory.html) - - **Modules**: - - [k8s](https://docs.ansible.com/ansible/2.10/collections/community/kubernetes/k8s_inventory.html) - - [openshift_auth](https://github.com/ansible-collections/community.okd/blob/main/plugins/modules/openshift_auth.py) - - [openshift_process](https://github.com/ansible-collections/community.okd/blob/main/plugins/modules/openshift_process.py) - - [openshift_route](https://github.com/ansible-collections/community.okd/blob/main/plugins/modules/openshift_route.py) + +### Connection plugins +Name | Description +--- | --- +[community.okd.oc](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.oc_connection.rst)|Execute tasks in pods running on OpenShift. -> **Note**: Some of these documentation links currently link to older module versions. For the latest module documentation, please use `ansible-doc` in the CLI. +### Modules +Name | Description +--- | --- +[community.okd.k8s](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.k8s_module.rst)|Manage OpenShift objects +[community.okd.openshift_auth](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.openshift_auth_module.rst)|Authenticate to OpenShift clusters which require an explicit login step +[community.okd.openshift_process](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.openshift_process_module.rst)|Process an OpenShift template.openshift.io/v1 Template +[community.okd.openshift_route](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.openshift_route_module.rst)|Expose a Service as an OpenShift Route. + +### Inventory plugins +Name | Description +--- | --- +[community.okd.openshift](https://github.com/ansible-collections/community.okd/blob/main/docs/community.okd.openshift_inventory.rst)|OpenShift inventory source + + diff --git a/changelogs/fragments/add_docs.yml b/changelogs/fragments/add_docs.yml new file mode 100644 index 0000000..247a10a --- /dev/null +++ b/changelogs/fragments/add_docs.yml @@ -0,0 +1,3 @@ +--- +minor_changes: +- Added documentation for the ``community.okd`` collection. diff --git a/docs/community.okd.k8s_module.rst b/docs/community.okd.k8s_module.rst new file mode 100644 index 0000000..cc23d06 --- /dev/null +++ b/docs/community.okd.k8s_module.rst @@ -0,0 +1,910 @@ +.. _community.okd.k8s_module: + + +***************** +community.okd.k8s +***************** + +**Manage OpenShift objects** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Use the OpenShift Python client to perform CRUD operations on K8s objects. +- Pass the object definition from a source file or inline. See examples for reading files and using Jinja templates or vault-encrypted files. +- Access to the full range of K8s APIs. +- Use the :ref:`k8s_info ` module to obtain a list of items about an object of type ``kind`` +- Authenticate using either a config file, certificates, password or token. +- Supports check mode. +- Optimized for OKD/OpenShift Kubernetes flavors + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- openshift >= 0.6 +- PyYAML >= 3.11 + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string +
+ 		+ +
Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
+
+
+ api_version + +
+ string +
+ 		+ Default:
"v1"
+ 		+
Use to specify the API version.
+
Use to create, delete, or discover an object without providing a full resource definition.
+
Use in conjunction with kind, name, and namespace to identify a specific object.
+
If resource definition is provided, the apiVersion value from the resource_definition will override this option.
+

aliases: api, version
+
+
+ append_hash + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Whether to append a hash to a resource name for immutability purposes
+
Applies only to ConfigMap and Secret resources
+
The parameter will be silently ignored for other resource kinds
+
The full definition of an object is needed to generate the hash - this means that deleting an object created with append_hash will only work if the same object is passed with state=absent (alternatively, just use state=absent with the name including the generated hash and append_hash=no)
+
+
+ apply + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
apply compares the desired resource definition with the previously supplied resource definition, ignoring properties that are automatically generated
+
apply works better with Services than 'force=yes'
+
mutually exclusive with merge_type
+
+
+ ca_cert + +
+ path +
+ 		+ +
Path to a CA certificate used to authenticate with the API. The full certificate chain must be provided to avoid certificate validation errors. Can also be specified via K8S_AUTH_SSL_CA_CERT environment variable.
+

aliases: ssl_ca_cert
+
+
+ client_cert + +
+ path +
+ 		+ +
Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment variable.
+

aliases: cert_file
+
+
+ client_key + +
+ path +
+ 		+ +
Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment variable.
+

aliases: key_file
+
+
+ context + +
+ string +
+ 		+ +
The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
+
+
+ force + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
If set to yes, and state is present, an existing object will be replaced.
+
+
+ host + +
+ string +
+ 		+ +
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+
+
+ kind + +
+ string +
+ 		+ +
Use to specify an object model.
+
Use to create, delete, or discover an object without providing a full resource definition.
+
Use in conjunction with api_version, name, and namespace to identify a specific object.
+
If resource definition is provided, the kind value from the resource_definition will override this option.
+
+
+ kubeconfig + +
+ path +
+ 		+ +
Path to an existing Kubernetes config file. If not provided, and no other connection options are provided, the openshift client will attempt to load the default configuration file from ~/.kube/config.json. Can also be specified via K8S_AUTH_KUBECONFIG environment variable.
+
+
+ merge_type + +
+ list + / elements=string +
+ 		+
    Choices: +
  • json
    • +
  • merge
    • +
  • strategic-merge
    • +
+ 		+
Whether to override the default patch merge approach with a specific type. By default, the strategic merge will typically be used.
+
For example, Custom Resource Definitions typically aren't updatable by the usual strategic merge. You may want to use merge if you see "strategic merge patch format is not supported"
+ +
Requires openshift >= 0.6.2
+
If more than one merge_type is given, the merge_types will be tried in order
+
If openshift >= 0.6.2, this defaults to ['strategic-merge', 'merge'], which is ideal for using the same parameters on resource kinds that combine Custom Resources and built-in resources. For openshift < 0.6.2, the default is simply strategic-merge.
+
mutually exclusive with apply
+
+
+ name + +
+ string +
+ 		+ +
Use to specify an object name.
+
Use to create, delete, or discover an object without providing a full resource definition.
+
Use in conjunction with api_version, kind and namespace to identify a specific object.
+
If resource definition is provided, the metadata.name value from the resource_definition will override this option.
+
+
+ namespace + +
+ string +
+ 		+ +
Use to specify an object namespace.
+
Useful when creating, deleting, or discovering an object without providing a full resource definition.
+
Use in conjunction with api_version, kind, and name to identify a specific object.
+
If resource definition is provided, the metadata.namespace value from the resource_definition will override this option.
+
+
+ password + +
+ string +
+ 		+ +
Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment variable.
+
Please read the description of the username option for a discussion of when this option is applicable.
+
+
+ persist_config + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to save the kube config refresh tokens. Can also be specified via K8S_AUTH_PERSIST_CONFIG environment variable.
+
When the k8s context is using a user credentials with refresh tokens (like oidc or gke/gcloud auth), the token is refreshed by the k8s python client library but not saved by default. So the old refresh token can expire and the next auth might fail. Setting this flag to true will tell the k8s python client to save the new refresh token to the kube config file.
+
Default to false.
+
Please note that the current version of the k8s python client library does not support setting this flag to True yet.
+
The fix for this k8s python library is here: https://github.com/kubernetes-client/python-base/pull/169
+
+
+ proxy + +
+ string +
+ 		+ +
The URL of an HTTP proxy to use for the connection. Can also be specified via K8S_AUTH_PROXY environment variable.
+
Please note that this module does not pick up typical proxy settings from the environment (e.g. HTTP_PROXY).
+
+
+ resource_definition + +
+ - +
+ 		+ +
Provide a valid YAML definition (either as a string, list, or dict) for an object when creating or updating.
+
NOTE: kind, api_version, name, and namespace will be overwritten by corresponding values found in the provided resource_definition.
+

aliases: definition, inline
+
+
+ src + +
+ path +
+ 		+ +
Provide a path to a file containing a valid YAML definition of an object or objects to be created or updated. Mutually exclusive with resource_definition. NOTE: kind, api_version, name, and namespace will be overwritten by corresponding values found in the configuration read in from the src file.
+
Reads from the local file system. To read from the Ansible controller's file system, including vaulted files, use the file lookup plugin or template lookup plugin, combined with the from_yaml filter, and pass the result to resource_definition. See Examples below.
+
Mutually exclusive with template in case of k8s module.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • absent
    • +
  • present ←
    • +
+ 		+
Determines if an object should be created, patched, or deleted. When set to present, an object will be created, if it does not already exist. If set to absent, an existing object will be deleted. If set to present, an existing object will be patched, if its attributes differ from those specified using resource_definition or src.
+
+
+ username + +
+ string +
+ 		+ +
Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment variable.
+
Please note that this only works with clusters configured to use HTTP Basic Auth. If your cluster has a different form of authentication (e.g. OAuth2 in OpenShift), this option will not work as expected and you should look into the community.okd.k8s_auth module, as that might do what you need.
+
+
+ validate + +
+ dictionary +
+ 		+ +
how (if at all) to validate the resource definition against the kubernetes schema. Requires the kubernetes-validate python module
+
+
+ fail_on_error + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
whether to fail on validation errors.
+
+
+ strict + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
whether to fail when passing unexpected properties
+
+
+ version + +
+ string +
+ 		+ +
version of Kubernetes to validate against. defaults to Kubernetes server version
+
+
+ validate_certs + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.
+

aliases: verify_ssl
+
+
+ wait + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Whether to wait for certain resource kinds to end up in the desired state. By default the module exits once Kubernetes has received the request
+
Implemented for state=present for Deployment, DaemonSet and Pod, and for state=absent for all resource kinds.
+
For resource kinds without an implementation, wait returns immediately unless wait_condition is set.
+
+
+ wait_condition + +
+ dictionary +
+ 		+ +
Specifies a custom condition on the status to wait for. Ignored if wait is not set or is set to False.
+
+
+ reason + +
+ string +
+ 		+ +
The value of the reason field in your desired condition
+
For example, if a Deployment is paused, The Progressing type will have the DeploymentPaused reason.
+
The possible reasons in a condition are specific to each resource type in Kubernetes. See the API documentation of the status field for a given resource to see possible choices.
+
+
+ status + +
+ string +
+ 		+
    Choices: +
  • yes
    • +
  • no
    • +
  • Unknown
    • +
+ Default:
"True"
+ 		+
The value of the status field in your desired condition.
+
For example, if a Deployment is paused, the Progressing type will have the Unknown status.
+
+
+ type + +
+ string +
+ 		+ +
The type of condition to wait for. For example, the Pod resource will set the Ready condition (among others)
+
Required if you are specifying a wait_condition. If left empty, the wait_condition field will be ignored.
+
The possible types for a condition are specific to each resource type in Kubernetes. See the API documentation of the status field for a given resource to see possible choices.
+
+
+ wait_sleep + +
+ integer +
+ 		+ Default:
5
+ 		+
Number of seconds to sleep between checks.
+
+
+ wait_timeout + +
+ integer +
+ 		+ Default:
120
+ 		+
How long in seconds to wait for the resource to end up in the desired state. Ignored if wait is not set.
+
+
+ + +Notes +----- + +.. note:: + - If your OpenShift Python library is not 0.9.0 or newer and you are trying to remove an item from an associative array/dictionary, for example a label or an annotation, you will need to explicitly set the value of the item to be removed to `null`. Simply deleting the entry in the dictionary will not remove it from openshift or kubernetes. + - The OpenShift Python client wraps the K8s Python client, providing full access to all of the APIS and models available on both platforms. For API version details and additional information visit https://github.com/openshift/openshift-restclient-python + - To avoid SSL certificate validation errors when ``validate_certs`` is *True*, the full certificate chain for the API server must be provided via ``ca_cert`` or in the kubeconfig file. + + + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create a k8s namespace + community.okd.k8s: + name: testing + api_version: v1 + kind: Namespace + state: present + + - name: Create a Service object from an inline definition + community.okd.k8s: + state: present + definition: + apiVersion: v1 + kind: Service + metadata: + name: web + namespace: testing + labels: + app: galaxy + service: web + spec: + selector: + app: galaxy + service: web + ports: + - protocol: TCP + targetPort: 8000 + name: port-8000-tcp + port: 8000 + + - name: Remove an existing Service object + community.okd.k8s: + state: absent + api_version: v1 + kind: Service + namespace: testing + name: web + + # Passing the object definition from a file + + - name: Create a Deployment by reading the definition from a local file + community.okd.k8s: + state: present + src: /testing/deployment.yml + + - name: >- + Read definition file from the Ansible controller file system. + If the definition file has been encrypted with Ansible Vault it will automatically be decrypted. + community.okd.k8s: + state: present + definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}" + + - name: Read definition file from the Ansible controller file system after Jinja templating + community.okd.k8s: + state: present + definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}" + + - name: fail on validation errors + community.okd.k8s: + state: present + definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}" + validate: + fail_on_error: yes + + - name: warn on validation errors, check for unexpected properties + community.okd.k8s: + state: present + definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}" + validate: + fail_on_error: no + strict: yes + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ result + +
+ complex +
+ 		success +
The created, patched, or otherwise present object. Will be empty in the case of a deletion.
+
+
  +
+ api_version + +
+ string +
+ 		success +
The versioned schema of this representation of an object.
+
+
  +
+ duration + +
+ integer +
+ 		when wait is true +
elapsed time of task in seconds
+
+
Sample:
+
48
+
  +
+ items + +
+ list +
+ 		when resource_definition or src contains list of objects +
Returned only when multiple yaml documents are passed to src or resource_definition
+
+
  +
+ kind + +
+ string +
+ 		success +
Represents the REST resource this object represents.
+
+
  +
+ metadata + +
+ complex +
+ 		success +
Standard object metadata. Includes name, namespace, annotations, labels, etc.
+
+
  +
+ spec + +
+ complex +
+ 		success +
Specific attributes of the object. Will vary based on the api_version and kind.
+
+
  +
+ status + +
+ complex +
+ 		success +
Current status details for the object.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Chris Houseknecht (@chouseknecht) +- Fabian von Feilitzsch (@fabianvf) diff --git a/docs/community.okd.oc_connection.rst b/docs/community.okd.oc_connection.rst new file mode 100644 index 0000000..14f2477 --- /dev/null +++ b/docs/community.okd.oc_connection.rst @@ -0,0 +1,315 @@ +.. _community.okd.oc_connection: + + +**************** +community.okd.oc +**************** + +**Execute tasks in pods running on OpenShift.** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Use the oc exec command to run tasks in, or put/fetch files to, pods running on the OpenShift container platform. + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this connection. + +- oc (go binary) + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ ca_cert + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_SSL_CA_CERT
+
var: ansible_oc_ssl_ca_cert
+
var: ansible_oc_ca_cert
+ 		+
Path to a CA certificate used to authenticate with the API.
+

aliases: oc_ssl_ca_cert
+
+
+ client_cert + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_CERT_FILE
+
var: ansible_oc_cert_file
+
var: ansible_oc_client_cert
+ 		+
Path to a certificate used to authenticate with the API.
+

aliases: oc_cert_file
+
+
+ client_key + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_KEY_FILE
+
var: ansible_oc_key_file
+
var: ansible_oc_client_key
+ 		+
Path to a key file used to authenticate with the API.
+

aliases: oc_key_file
+
+
+ oc_container + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_CONTAINER
+
var: ansible_oc_container
+ 		+
Container name. Required when a pod contains more than one container.
+
+
+ oc_context + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_CONTEXT
+
var: ansible_oc_context
+ 		+
The name of a context found in the K8s config file.
+
+
+ oc_extra_args + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_EXTRA_ARGS
+
var: ansible_oc_extra_args
+ 		+
Extra arguments to pass to the oc command line.
+
+
+ oc_host + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_HOST
+
env:K8S_AUTH_SERVER
+
var: ansible_oc_host
+
var: ansible_oc_server
+ 		+
URL for accessing the API.
+
+
+ oc_kubeconfig + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_KUBECONFIG
+
var: ansible_oc_kubeconfig
+
var: ansible_oc_config
+ 		+
Path to a oc config file. Defaults to ~/.kube/config
+
+
+ oc_namespace + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_NAMESPACE
+
var: ansible_oc_namespace
+ 		+
The namespace of the pod
+
+
+ oc_pod + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_POD
+
var: ansible_oc_pod
+ 		+
Pod name. Required when the host name does not match pod name.
+
+
+ oc_token + +
+ - +
+ 		+ +
env:K8S_AUTH_TOKEN
+
env:K8S_AUTH_API_KEY
+
var: ansible_oc_token
+
var: ansible_oc_api_key
+ 		+
API authentication bearer token.
+
+
+ validate_certs + +
+ - +
+ 		+ Default:
""
+ 		+
env:K8S_AUTH_VERIFY_SSL
+
var: ansible_oc_verify_ssl
+
var: ansible_oc_validate_certs
+ 		+
Whether or not to verify the API server's SSL certificate. Defaults to true.
+

aliases: oc_verify_ssl
+
+
+ + + + + + + + +Status +------ + + +Authors +~~~~~~~ + +- 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. diff --git a/docs/community.okd.openshift_auth_module.rst b/docs/community.okd.openshift_auth_module.rst new file mode 100644 index 0000000..3b761a7 --- /dev/null +++ b/docs/community.okd.openshift_auth_module.rst @@ -0,0 +1,424 @@ +.. _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 >= 2.7 +- urllib3 +- requests +- requests-oauthlib + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ 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 +-------- + +.. code-block:: yaml+jinja + + - 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 `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ k8s_auth + +
+ complex +
+ 		success +
Same as returned openshift_auth. Kept only for backwards compatibility
+
+
  +
+ 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.
+
+
+
+ openshift_auth + +
+ complex +
+ 		success +
OpenShift 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 +------ + + +Authors +~~~~~~~ + +- KubeVirt Team (@kubevirt) +- Fabian von Feilitzsch (@fabianvf) diff --git a/docs/community.okd.openshift_inventory.rst b/docs/community.okd.openshift_inventory.rst new file mode 100644 index 0000000..54506df --- /dev/null +++ b/docs/community.okd.openshift_inventory.rst @@ -0,0 +1,355 @@ +.. _community.okd.openshift_inventory: + + +*********************** +community.okd.openshift +*********************** + +**OpenShift inventory source** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Fetch containers, services and routes for one or more clusters +- Groups by cluster name, namespace, namespace_services, namespace_pods, namespace_routes, and labels +- Uses openshift.(yml|yaml) YAML configuration file to set parameter values. + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this inventory. + +- python >= 2.7 +- openshift >= 0.6 +- PyYAML >= 3.11 + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ connections + +
+ - +
+ 		+ + +
Optional list of cluster connection settings. If no connections are provided, the default ~/.kube/config and active context will be used, and objects will be returned for all namespaces the active user is authorized to access.
+
+
+ api_key + +
+ - +
+ 		+ + +
Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
+
+
+ ca_cert + +
+ - +
+ 		+ + +
Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT environment variable.
+

aliases: ssl_ca_cert
+
+
+ client_cert + +
+ - +
+ 		+ + +
Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment variable.
+

aliases: cert_file
+
+
+ client_key + +
+ - +
+ 		+ + +
Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment variable.
+

aliases: key_file
+
+
+ context + +
+ - +
+ 		+ + +
The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
+
+
+ host + +
+ - +
+ 		+ + +
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+
+
+ kubeconfig + +
+ - +
+ 		+ + +
Path to an existing Kubernetes config file. If not provided, and no other connection options are provided, the OpenShift client will attempt to load the default configuration file from ~/.kube/config.json. Can also be specified via K8S_AUTH_KUBECONFIG environment variable.
+
+
+ name + +
+ - +
+ 		+ + +
Optional name to assign to the cluster. If not provided, a name is constructed from the server and port.
+
+
+ namespaces + +
+ - +
+ 		+ + +
List of namespaces. If not specified, will fetch all containers for all namespaces user is authorized to access.
+
+
+ password + +
+ - +
+ 		+ + +
Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment variable.
+
+
+ username + +
+ - +
+ 		+ + +
Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment variable.
+
+
+ validate_certs + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+ +
Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.
+

aliases: verify_ssl
+
+
+ plugin + +
+ - + / required +
+ 		+
    Choices: +
  • openshift
    • +
+ 		+ +
token that ensures this is a source file for the 'openshift' plugin.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml+jinja + + # File must be named openshift.yaml or openshift.yml + + # Authenticate with token, and return all pods and services for all namespaces + plugin: community.okd.openshift + connections: + - host: https://192.168.64.4:8443 + api_key: xxxxxxxxxxxxxxxx + verify_ssl: false + + # Use default config (~/.kube/config) file and active context, and return objects for a specific namespace + plugin: community.okd.openshift + connections: + - namespaces: + - testing + + # Use a custom config file, and a specific context. + plugin: community.okd.openshift + connections: + - kubeconfig: /path/to/config + context: 'awx/192-168-64-4:8443/developer' + + + + +Status +------ + + +Authors +~~~~~~~ + +- Chris Houseknecht <@chouseknecht> + + +.. 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. diff --git a/docs/community.okd.openshift_process_module.rst b/docs/community.okd.openshift_process_module.rst new file mode 100644 index 0000000..d4e4106 --- /dev/null +++ b/docs/community.okd.openshift_process_module.rst @@ -0,0 +1,935 @@ +.. _community.okd.openshift_process_module: + + +******************************* +community.okd.openshift_process +******************************* + +**Process an OpenShift template.openshift.io/v1 Template** + + +Version added: 0.3.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Processes a specified OpenShift template with the provided template. +- Templates can be provided inline, from a file, or specified by name and namespace in the cluster. +- Analogous to `oc process`. +- For CRUD operations on Template resources themselves, see the community.okd.k8s module. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- openshift >= 0.11.0 +- PyYAML >= 3.11 + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string +
+ 		+ +
Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
+
+
+ ca_cert + +
+ path +
+ 		+ +
Path to a CA certificate used to authenticate with the API. The full certificate chain must be provided to avoid certificate validation errors. Can also be specified via K8S_AUTH_SSL_CA_CERT environment variable.
+

aliases: ssl_ca_cert
+
+
+ client_cert + +
+ path +
+ 		+ +
Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment variable.
+

aliases: cert_file
+
+
+ client_key + +
+ path +
+ 		+ +
Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment variable.
+

aliases: key_file
+
+
+ context + +
+ string +
+ 		+ +
The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
+
+
+ host + +
+ string +
+ 		+ +
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+
+
+ kubeconfig + +
+ path +
+ 		+ +
Path to an existing Kubernetes config file. If not provided, and no other connection options are provided, the openshift client will attempt to load the default configuration file from ~/.kube/config.json. Can also be specified via K8S_AUTH_KUBECONFIG environment variable.
+
+
+ name + +
+ string +
+ 		+ +
The name of the Template to process.
+
The Template must be present in the cluster.
+
When provided, namespace is required.
+
Mutually exclusive with resource_definition or src
+
+
+ namespace + +
+ string +
+ 		+ +
The namespace that the template can be found in.
+
+
+ namespace_target + +
+ - +
+ 		+ +
The namespace that resources should be created, updated, or deleted in.
+
Only used when state is present or absent.
+
+
+ parameter_file + +
+ string +
+ 		+ +
A path to a file containing template parameter values to override/set values in the Template.
+
Corresponds to the `--param-file` argument to oc process.
+
+
+ parameters + +
+ dictionary +
+ 		+ +
A set of key: value pairs that will be used to set/override values in the Template.
+
Corresponds to the `--param` argument to oc process.
+
+
+ password + +
+ string +
+ 		+ +
Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment variable.
+
Please read the description of the username option for a discussion of when this option is applicable.
+
+
+ persist_config + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to save the kube config refresh tokens. Can also be specified via K8S_AUTH_PERSIST_CONFIG environment variable.
+
When the k8s context is using a user credentials with refresh tokens (like oidc or gke/gcloud auth), the token is refreshed by the k8s python client library but not saved by default. So the old refresh token can expire and the next auth might fail. Setting this flag to true will tell the k8s python client to save the new refresh token to the kube config file.
+
Default to false.
+
Please note that the current version of the k8s python client library does not support setting this flag to True yet.
+
The fix for this k8s python library is here: https://github.com/kubernetes-client/python-base/pull/169
+
+
+ proxy + +
+ string +
+ 		+ +
The URL of an HTTP proxy to use for the connection. Can also be specified via K8S_AUTH_PROXY environment variable.
+
Please note that this module does not pick up typical proxy settings from the environment (e.g. HTTP_PROXY).
+
+
+ resource_definition + +
+ - +
+ 		+ +
Provide a valid YAML definition (either as a string, list, or dict) for an object when creating or updating.
+
NOTE: kind, api_version, name, and namespace will be overwritten by corresponding values found in the provided resource_definition.
+

aliases: definition, inline
+
+
+ src + +
+ path +
+ 		+ +
Provide a path to a file containing a valid YAML definition of an object or objects to be created or updated. Mutually exclusive with resource_definition. NOTE: kind, api_version, name, and namespace will be overwritten by corresponding values found in the configuration read in from the src file.
+
Reads from the local file system. To read from the Ansible controller's file system, including vaulted files, use the file lookup plugin or template lookup plugin, combined with the from_yaml filter, and pass the result to resource_definition. See Examples below.
+
Mutually exclusive with template in case of k8s module.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • absent
    • +
  • present
    • +
  • rendered ←
    • +
+ 		+
Determines what to do with the rendered Template.
+
The state rendered will render the Template based on the provided parameters, and return the rendered objects in the resources field. These can then be referenced in future tasks.
+
The state present will cause the resources in the rendered Template to be created if they do not already exist, and patched if they do.
+
The state absent will delete the resources in the rendered Template.
+
+
+ username + +
+ string +
+ 		+ +
Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment variable.
+
Please note that this only works with clusters configured to use HTTP Basic Auth. If your cluster has a different form of authentication (e.g. OAuth2 in OpenShift), this option will not work as expected and you should look into the community.okd.k8s_auth module, as that might do what you need.
+
+
+ validate_certs + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.
+

aliases: verify_ssl
+
+
+ wait + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Whether to wait for certain resource kinds to end up in the desired state.
+
By default the module exits once Kubernetes has received the request.
+
Implemented for state=present for Deployment, DaemonSet and Pod, and for state=absent for all resource kinds.
+
For resource kinds without an implementation, wait returns immediately unless wait_condition is set.
+
+
+ wait_condition + +
+ dictionary +
+ 		+ +
Specifies a custom condition on the status to wait for.
+
Ignored if wait is not set or is set to False.
+
+
+ reason + +
+ string +
+ 		+ +
The value of the reason field in your desired condition
+
For example, if a Deployment is paused, The Progressing type will have the DeploymentPaused reason.
+
The possible reasons in a condition are specific to each resource type in Kubernetes.
+
See the API documentation of the status field for a given resource to see possible choices.
+
+
+ status + +
+ string +
+ 		+
    Choices: +
  • True ←
    • +
  • False
    • +
  • Unknown
    • +
+ 		+
The value of the status field in your desired condition.
+
For example, if a Deployment is paused, the Progressing type will have the Unknown status.
+
+
+ type + +
+ string +
+ 		+ +
The type of condition to wait for.
+
For example, the Pod resource will set the Ready condition (among others).
+
Required if you are specifying a wait_condition.
+
If left empty, the wait_condition field will be ignored.
+
The possible types for a condition are specific to each resource type in Kubernetes.
+
See the API documentation of the status field for a given resource to see possible choices.
+
+
+ wait_sleep + +
+ integer +
+ 		+ Default:
5
+ 		+
Number of seconds to sleep between checks.
+
+
+ wait_timeout + +
+ integer +
+ 		+ Default:
120
+ 		+
How long in seconds to wait for the resource to end up in the desired state.
+
Ignored if wait is not set.
+
+
+ + +Notes +----- + +.. note:: + - The OpenShift Python client wraps the K8s Python client, providing full access to all of the APIS and models available on both platforms. For API version details and additional information visit https://github.com/openshift/openshift-restclient-python + - To avoid SSL certificate validation errors when ``validate_certs`` is *True*, the full certificate chain for the API server must be provided via ``ca_cert`` or in the kubeconfig file. + + + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Process a template in the cluster + community.okd.openshift_process: + name: nginx-example + namespace: openshift # only needed if using a template already on the server + parameters: + NAMESPACE: openshift + NAME: test123 + state: rendered + register: result + + - name: Create the rendered resources using apply + community.okd.k8s: + namespace: default + definition: '{{ item }}' + wait: yes + apply: yes + loop: '{{ result.resources }}' + + - name: Process a template with parameters from an env file and create the resources + community.okd.openshift_process: + name: nginx-example + namespace: openshift + namespace_target: default + parameter_file: 'files/nginx.env' + state: present + wait: yes + + - name: Process a local template and create the resources + community.okd.openshift_process: + src: files/example-template.yaml + parameter_file: files/example.env + namespace_target: default + state: present + + - name: Process a local template, delete the resources, and wait for them to terminate + community.okd.openshift_process: + src: files/example-template.yaml + parameter_file: files/example.env + namespace_target: default + state: absent + wait: yes + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ resources + +
+ complex +
+ 		on success when state is rendered +
The rendered resources defined in the Template
+
+
  +
+ apiVersion + +
+ string +
+ 		success +
The versioned schema of this representation of an object.
+
+
  +
+ kind + +
+ string +
+ 		success +
Represents the REST resource this object represents.
+
+
  +
+ metadata + +
+ complex +
+ 		success +
Standard object metadata. Includes name, namespace, annotations, labels, etc.
+
+
   +
+ name + +
+ string +
+ 		+
The name of the resource
+
+
   +
+ namespace + +
+ string +
+ 		+
The namespace of the resource
+
+
  +
+ spec + +
+ dictionary +
+ 		success +
Specific attributes of the object. Will vary based on the api_version and kind.
+
+
  +
+ status + +
+ dictionary +
+ 		success +
Current status details for the object.
+
+
   +
+ conditions + +
+ complex +
+ 		+
Array of status conditions for the object. Not guaranteed to be present
+
+
+
+ result + +
+ complex +
+ 		on success when state is present or absent +
The created, patched, or otherwise present object. Will be empty in the case of a deletion.
+
+
  +
+ apiVersion + +
+ string +
+ 		success +
The versioned schema of this representation of an object.
+
+
  +
+ duration + +
+ integer +
+ 		when wait is true +
elapsed time of task in seconds
+
+
Sample:
+
48
+
  +
+ items + +
+ list +
+ 		when resource_definition or src contains list of objects +
Returned only when multiple yaml documents are passed to src or resource_definition
+
+
  +
+ kind + +
+ string +
+ 		success +
Represents the REST resource this object represents.
+
+
  +
+ metadata + +
+ complex +
+ 		success +
Standard object metadata. Includes name, namespace, annotations, labels, etc.
+
+
   +
+ name + +
+ string +
+ 		+
The name of the resource
+
+
   +
+ namespace + +
+ string +
+ 		+
The namespace of the resource
+
+
  +
+ spec + +
+ dictionary +
+ 		success +
Specific attributes of the object. Will vary based on the api_version and kind.
+
+
  +
+ status + +
+ complex +
+ 		success +
Current status details for the object.
+
+
   +
+ conditions + +
+ complex +
+ 		+
Array of status conditions for the object. Not guaranteed to be present
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Fabian von Feilitzsch (@fabianvf) diff --git a/docs/community.okd.openshift_route_module.rst b/docs/community.okd.openshift_route_module.rst new file mode 100644 index 0000000..a28057b --- /dev/null +++ b/docs/community.okd.openshift_route_module.rst @@ -0,0 +1,1352 @@ +.. _community.okd.openshift_route_module: + + +***************************** +community.okd.openshift_route +***************************** + +**Expose a Service as an OpenShift Route.** + + +Version added: 0.3.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Looks up a Service and creates a new Route based on it. +- Analogous to `oc expose` and `oc create route` for creating Routes, but does not support creating Services. +- For creating Services from other resources, see kubernetes.core.k8s_expose + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- openshift >= 0.11.0 +- PyYAML >= 3.11 + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string +
+ 		+ +
Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
+
+
+ ca_cert + +
+ path +
+ 		+ +
Path to a CA certificate used to authenticate with the API. The full certificate chain must be provided to avoid certificate validation errors. Can also be specified via K8S_AUTH_SSL_CA_CERT environment variable.
+

aliases: ssl_ca_cert
+
+
+ client_cert + +
+ path +
+ 		+ +
Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment variable.
+

aliases: cert_file
+
+
+ client_key + +
+ path +
+ 		+ +
Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment variable.
+

aliases: key_file
+
+
+ context + +
+ string +
+ 		+ +
The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
+
+
+ force + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
If set to yes, and state is present, an existing object will be replaced.
+
+
+ host + +
+ string +
+ 		+ +
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+
+
+ hostname + +
+ string +
+ 		+ +
The hostname for the Route.
+
+
+ kubeconfig + +
+ path +
+ 		+ +
Path to an existing Kubernetes config file. If not provided, and no other connection options are provided, the openshift client will attempt to load the default configuration file from ~/.kube/config.json. Can also be specified via K8S_AUTH_KUBECONFIG environment variable.
+
+
+ labels + +
+ dictionary +
+ 		+ +
Specify the labels to apply to the created Route.
+
A set of key: value pairs.
+
+
+ name + +
+ string +
+ 		+ +
The desired name of the Route to be created.
+
Defaults to the value of service
+
+
+ namespace + +
+ string + / required +
+ 		+ +
The namespace of the resource being targeted.
+
The Route will be created in this namespace as well.
+
+
+ password + +
+ string +
+ 		+ +
Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment variable.
+
Please read the description of the username option for a discussion of when this option is applicable.
+
+
+ path + +
+ string +
+ 		+ +
The path for the Route
+
+
+ persist_config + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to save the kube config refresh tokens. Can also be specified via K8S_AUTH_PERSIST_CONFIG environment variable.
+
When the k8s context is using a user credentials with refresh tokens (like oidc or gke/gcloud auth), the token is refreshed by the k8s python client library but not saved by default. So the old refresh token can expire and the next auth might fail. Setting this flag to true will tell the k8s python client to save the new refresh token to the kube config file.
+
Default to false.
+
Please note that the current version of the k8s python client library does not support setting this flag to True yet.
+
The fix for this k8s python library is here: https://github.com/kubernetes-client/python-base/pull/169
+
+
+ port + +
+ string +
+ 		+ +
Name or number of the port the Route will route traffic to.
+
+
+ proxy + +
+ string +
+ 		+ +
The URL of an HTTP proxy to use for the connection. Can also be specified via K8S_AUTH_PROXY environment variable.
+
Please note that this module does not pick up typical proxy settings from the environment (e.g. HTTP_PROXY).
+
+
+ service + +
+ string +
+ 		+ +
The name of the service to expose.
+
Required when state is not absent.
+

aliases: svc
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • absent
    • +
  • present ←
    • +
+ 		+
Determines if an object should be created, patched, or deleted. When set to present, an object will be created, if it does not already exist. If set to absent, an existing object will be deleted. If set to present, an existing object will be patched, if its attributes differ from those specified using resource_definition or src.
+
+
+ termination + +
+ string +
+ 		+
    Choices: +
  • edge
    • +
  • passthrough
    • +
  • reencrypt
    • +
  • insecure ←
    • +
+ 		+
The termination type of the Route.
+
If left empty no termination type will be set, and the route will be insecure.
+
When set to insecure tls will be ignored.
+
+
+ tls + +
+ dictionary +
+ 		+ +
TLS configuration for the newly created route.
+
Only used when termination is set.
+
+
+ ca_certificate + +
+ string +
+ 		+ +
Path to a CA certificate file on the target host.
+
Not supported when termination is set to passthrough.
+
+
+ certificate + +
+ string +
+ 		+ +
Path to a certificate file on the target host.
+
Not supported when termination is set to passthrough.
+
+
+ destination_ca_certificate + +
+ string +
+ 		+ +
Path to a CA certificate file used for securing the connection.
+
Only used when termination is set to reencrypt.
+
Defaults to the Service CA.
+
+
+ insecure_policy + +
+ string +
+ 		+
    Choices: +
  • allow
    • +
  • redirect
    • +
  • disallow ←
    • +
+ 		+
Sets the InsecureEdgeTerminationPolicy for the Route.
+
Not supported when termination is set to reencrypt.
+
When termination is set to passthrough, only redirect is supported.
+
If not provided, insecure traffic will be disallowed.
+
+
+ key + +
+ string +
+ 		+ +
Path to a key file on the target host.
+
Not supported when termination is set to passthrough.
+
+
+ username + +
+ string +
+ 		+ +
Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment variable.
+
Please note that this only works with clusters configured to use HTTP Basic Auth. If your cluster has a different form of authentication (e.g. OAuth2 in OpenShift), this option will not work as expected and you should look into the community.okd.k8s_auth module, as that might do what you need.
+
+
+ validate_certs + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.
+

aliases: verify_ssl
+
+
+ wait + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Whether to wait for certain resource kinds to end up in the desired state.
+
By default the module exits once Kubernetes has received the request.
+
Implemented for state=present for Deployment, DaemonSet and Pod, and for state=absent for all resource kinds.
+
For resource kinds without an implementation, wait returns immediately unless wait_condition is set.
+
+
+ wait_condition + +
+ dictionary +
+ 		+ +
Specifies a custom condition on the status to wait for.
+
Ignored if wait is not set or is set to False.
+
+
+ reason + +
+ string +
+ 		+ +
The value of the reason field in your desired condition
+
For example, if a Deployment is paused, The Progressing type will have the DeploymentPaused reason.
+
The possible reasons in a condition are specific to each resource type in Kubernetes.
+
See the API documentation of the status field for a given resource to see possible choices.
+
+
+ status + +
+ string +
+ 		+
    Choices: +
  • True ←
    • +
  • False
    • +
  • Unknown
    • +
+ 		+
The value of the status field in your desired condition.
+
For example, if a Deployment is paused, the Progressing type will have the Unknown status.
+
+
+ type + +
+ string +
+ 		+ +
The type of condition to wait for.
+
For example, the Pod resource will set the Ready condition (among others).
+
Required if you are specifying a wait_condition.
+
If left empty, the wait_condition field will be ignored.
+
The possible types for a condition are specific to each resource type in Kubernetes.
+
See the API documentation of the status field for a given resource to see possible choices.
+
+
+ wait_sleep + +
+ integer +
+ 		+ Default:
5
+ 		+
Number of seconds to sleep between checks.
+
+
+ wait_timeout + +
+ integer +
+ 		+ Default:
120
+ 		+
How long in seconds to wait for the resource to end up in the desired state.
+
Ignored if wait is not set.
+
+
+ wildcard_policy + +
+ string +
+ 		+
    Choices: +
  • Subdomain
    • +
+ 		+
The wildcard policy for the hostname.
+
Currently only Subdomain is supported.
+
If not provided, the default of None will be used.
+
+
+ + +Notes +----- + +.. note:: + - The OpenShift Python client wraps the K8s Python client, providing full access to all of the APIS and models available on both platforms. For API version details and additional information visit https://github.com/openshift/openshift-restclient-python + - To avoid SSL certificate validation errors when ``validate_certs`` is *True*, the full certificate chain for the API server must be provided via ``ca_cert`` or in the kubeconfig file. + + + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create hello-world deployment + community.okd.k8s: + definition: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: hello-kubernetes + namespace: default + spec: + replicas: 3 + selector: + matchLabels: + app: hello-kubernetes + template: + metadata: + labels: + app: hello-kubernetes + spec: + containers: + - name: hello-kubernetes + image: paulbouwer/hello-kubernetes:1.8 + ports: + - containerPort: 8080 + + - name: Create Service for the hello-world deployment + community.okd.k8s: + definition: + apiVersion: v1 + kind: Service + metadata: + name: hello-kubernetes + namespace: default + spec: + ports: + - port: 80 + targetPort: 8080 + selector: + app: hello-kubernetes + + - name: Expose the insecure hello-world service externally + community.okd.openshift_route: + service: hello-kubernetes + namespace: default + insecure_policy: allow + register: route + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ duration + +
+ integer +
+ 		when wait is true +
elapsed time of task in seconds
+
+
Sample:
+
48
+
+
+ result + +
+ complex +
+ 		success +
The Route object that was created or updated. Will be empty in the case of deletion.
+
+
  +
+ apiVersion + +
+ string +
+ 		success +
The versioned schema of this representation of an object.
+
+
  +
+ kind + +
+ string +
+ 		success +
Represents the REST resource this object represents.
+
+
  +
+ metadata + +
+ complex +
+ 		success +
Standard object metadata. Includes name, namespace, annotations, labels, etc.
+
+
   +
+ name + +
+ string +
+ 		+
The name of the created Route
+
+
   +
+ namespace + +
+ string +
+ 		+
The namespace of the create Route
+
+
  +
+ spec + +
+ complex +
+ 		success +
Specification for the Route
+
+
   +
+ host + +
+ string +
+ 		+
Host is an alias/DNS that points to the service.
+
+
   +
+ path + +
+ string +
+ 		+
Path that the router watches for, to route traffic for to the service.
+
+
   +
+ port + +
+ complex +
+ 		+
Defines a port mapping from a router to an endpoint in the service endpoints.
+
+
    +
+ targetPort + +
+ string +
+ 		+
The target port on pods selected by the service this route points to.
+
+
   +
+ tls + +
+ complex +
+ 		+
Defines config used to secure a route and provide termination.
+
+
    +
+ caCertificate + +
+ string +
+ 		+
Provides the cert authority certificate contents.
+
+
    +
+ certificate + +
+ string +
+ 		+
Provides certificate contents.
+
+
    +
+ destinationCACertificate + +
+ string +
+ 		+
Provides the contents of the ca certificate of the final destination.
+
+
    +
+ insecureEdgeTerminationPolicy + +
+ string +
+ 		+
Indicates the desired behavior for insecure connections to a route.
+
+
    +
+ key + +
+ string +
+ 		+
Provides key file contents.
+
+
    +
+ termination + +
+ string +
+ 		+
Indicates termination type.
+
+
   +
+ to + +
+ complex +
+ 		+
Specifies the target that resolve into endpoints.
+
+
    +
+ kind + +
+ string +
+ 		+
The kind of target that the route is referring to. Currently, only 'Service' is allowed.
+
+
    +
+ name + +
+ string +
+ 		+
Name of the service/target that is being referred to. e.g. name of the service.
+
+
    +
+ weight + +
+ integer +
+ 		+
Specifies the target's relative weight against other target reference objects.
+
+
   +
+ wildcardPolicy + +
+ string +
+ 		+
Wildcard policy if any for the route.
+
+
  +
+ status + +
+ complex +
+ 		success +
Current status details for the Route
+
+
   +
+ ingress + +
+ complex +
+ 		+
List of places where the route may be exposed.
+
+
    +
+ conditions + +
+ complex +
+ 		+
Array of status conditions for the Route ingress.
+
+
     +
+ status + +
+ string +
+ 		+
The status of the condition. Can be True, False, Unknown.
+
+
     +
+ type + +
+ string +
+ 		+
The type of the condition. Currently only 'Ready'.
+
+
    +
+ host + +
+ string +
+ 		+
The host string under which the route is exposed.
+
+
    +
+ routerCanonicalHostname + +
+ string +
+ 		+
The external host name for the router that can be used as a CNAME for the host requested for this route. May not be set.
+
+
    +
+ routerName + +
+ string +
+ 		+
A name chosen by the router to identify itself.
+
+
    +
+ wildcardPolicy + +
+ string +
+ 		+
The wildcard policy that was allowed where this route is exposed.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Fabian von Feilitzsch (@fabianvf)