From 1c391e777a242430e3443dd77101807f16eef988 Mon Sep 17 00:00:00 2001 From: Chris Houseknecht Date: Fri, 22 Dec 2017 17:12:17 -0500 Subject: [PATCH] Improving docs and examples (#34155) * Improving docs and examples * Removes trailing whitespace --- lib/ansible/module_utils/k8s_common.py | 3 +- lib/ansible/modules/clustering/k8s/k8s_raw.py | 31 ++++++++++-- .../clustering/openshift/openshift_raw.py | 49 +++++++++++++------ .../utils/module_docs_fragments/kubernetes.py | 17 +++---- 4 files changed, 69 insertions(+), 31 deletions(-) diff --git a/lib/ansible/module_utils/k8s_common.py b/lib/ansible/module_utils/k8s_common.py index 42c6232da7..900238fa73 100644 --- a/lib/ansible/module_utils/k8s_common.py +++ b/lib/ansible/module_utils/k8s_common.py @@ -77,7 +77,8 @@ ARG_SPEC = { 'description': {}, 'display_name': {}, 'api_version': { - 'aliases': ['api', 'version'] + 'default': 'v1', + 'aliases': ['api', 'version'], }, 'kubeconfig': { 'type': 'path', diff --git a/lib/ansible/modules/clustering/k8s/k8s_raw.py b/lib/ansible/modules/clustering/k8s/k8s_raw.py index 26378e5605..d64d9fc1be 100644 --- a/lib/ansible/modules/clustering/k8s/k8s_raw.py +++ b/lib/ansible/modules/clustering/k8s/k8s_raw.py @@ -24,16 +24,20 @@ version_added: "2.5" author: "Chris Houseknecht (@chouseknecht)" description: - - Use the OpenShift Python client to perform CRUD operations on Kubernetes objects. - - Supports authentication using either a config file, certificates, password or token. + - 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. + - Access to the full range of K8s APIs. + - Authenticate using either a config file, certificates, password or token. + - Supports check mode, and the diff option. extends_documentation_fragment: - kubernetes requirements: - - "python >= 2.7" - - "openshift >= 0.3" - - "PyYAML >= 3.11" + - "python >= 2.7" + - "openshift >= 0.3" + - "PyYAML >= 3.11" ''' EXAMPLES = ''' @@ -93,6 +97,23 @@ EXAMPLES = ''' 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 + k8s_raw: + state: present + src: /testing/deployment.yml + +- name: Read definition file from the Ansible controller file system + k8s_raw: + state: present + definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}" + +- name: Read definition file from the Ansible controller file system after Jinja templating + k8s_raw: + state: present + definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}" ''' RETURN = ''' diff --git a/lib/ansible/modules/clustering/openshift/openshift_raw.py b/lib/ansible/modules/clustering/openshift/openshift_raw.py index a0d75d3787..20cbdfbbdc 100644 --- a/lib/ansible/modules/clustering/openshift/openshift_raw.py +++ b/lib/ansible/modules/clustering/openshift/openshift_raw.py @@ -25,10 +25,24 @@ author: "Chris Houseknecht (@chouseknecht)" description: - Use the OpenShift Python client to perform CRUD operations on OpenShift objects. - - Supports authentication using either a config file, certificates, password or token. + - Pass the object definition from a source file or inline. See examples for reading + files and using Jinja templates. + - Access to the full range of K8s and OpenShift APIs. + - Authenticate using either a config file, certificates, password or token. + - Supports check mode, and the diff option. extends_documentation_fragment: kubernetes +options: + description: + description: + - Use only when creating a project, otherwise ignored. Adds a description to the project + metadata. + display_name: + description: + - Use only when creating a project, otherwise ignored. Adds a display name to the project + metadata. + requirements: - "python >= 2.7" - "openshift >= 0.3" @@ -95,18 +109,6 @@ EXAMPLES = ''' strategy: type: Rolling -- name: Create a Deployment by reading the definition from a file - openshift_raw: - state: present - src: /testing/deployment.yml - -- name: Get the list of all Deployments - openshift_raw: - api_version: v1 - kind: DeploymentConfigList - namespace: testing - register: deployment_list - - name: Remove an existing Deployment openshift_raw: api_version: v1 @@ -117,7 +119,7 @@ EXAMPLES = ''' - name: Create a Secret openshift_raw: - inline: + definition: apiVersion: v1 kind: Secret metadata: @@ -128,13 +130,30 @@ EXAMPLES = ''' username: "{{ 'admin' | b64encode }}" password: "{{ 'foobard' | b64encode }}" -- name: Retrieve the Secret +- name: Retrieve a Secret openshift_raw: api: v1 kind: Secret name: mysecret namespace: testing register: mysecret + +# Passing the object definition from a file + +- name: Create a Deployment by reading the definition from a local file + openshift_raw: + state: present + src: /testing/deployment.yml + +- name: Read definition file from the Ansible controller file system + openshift_raw: + state: present + definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}" + +- name: Read definition file from the Ansible controller file system after Jinja templating + openshift_raw: + state: present + definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}" ''' RETURN = ''' diff --git a/lib/ansible/utils/module_docs_fragments/kubernetes.py b/lib/ansible/utils/module_docs_fragments/kubernetes.py index e970442d82..0792c9cbef 100644 --- a/lib/ansible/utils/module_docs_fragments/kubernetes.py +++ b/lib/ansible/utils/module_docs_fragments/kubernetes.py @@ -46,12 +46,16 @@ options: - "Provide a path to a file containing a valid YAML definition of an object to be created or updated. Mutually exclusive with I(resource_definition). NOTE: I(kind), I(api_version), I(name), and I(namespace) will be overwritten by corresponding values found in the configuration read in from the I(src) file." + - Reads from the local file system. To read from the Ansible controller's file system, use the file lookup + plugin or template lookup plugin, combined with the from_yaml filter, and pass the result to + I(resource_definition). See Examples below. api_version: description: - Use to specify the API version. Use to create, delete, or discover an object without providing a full resource definition. Use in conjunction with I(kind), I(name), and I(namespace) to identify a specific object. If I(resource definition) is provided, the I(apiVersion) from the I(resource_definition) will override this option. + default: v1 aliases: - api - version @@ -73,14 +77,6 @@ options: providing a full resource definition. Use in conjunction with I(api_version), I(kind), and I(name) to identify a specfic object. If I(resource definition) is provided, the I(metadata.namespace) value from the I(resource_definition) will override this option. - description: - description: - - Used only when creating an OpenShift project, otherwise ignored. Adds a description to the project meta - data. - display_name: - description: - - Use only when creating an OpenShift project, otherwise ignored. Adds a display name to the project meta - data. host: description: - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable. @@ -123,6 +119,7 @@ options: type: bool notes: - - "To learn more about the OpenShift Python client and available object models, visit: - https://github.com/openshift/openshift-restclient-python" + - "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" '''