From ad04c1854d6932ad25f57929d3f16ee324ec2f3e Mon Sep 17 00:00:00 2001 From: Chris Houseknecht Date: Sun, 24 Dec 2017 17:50:07 -0500 Subject: [PATCH] Granular K8s doc fragments (#34215) * Makes doc fragment more granular * Fix lint issues --- lib/ansible/modules/clustering/k8s/k8s_raw.py | 5 +- .../clustering/openshift/openshift_raw.py | 6 +- .../module_docs_fragments/k8s_auth_options.py | 71 ++++++++++ .../module_docs_fragments/k8s_name_options.py | 54 ++++++++ .../k8s_resource_options.py | 41 ++++++ .../k8s_state_options.py | 41 ++++++ .../utils/module_docs_fragments/kubernetes.py | 125 ------------------ 7 files changed, 216 insertions(+), 127 deletions(-) create mode 100644 lib/ansible/utils/module_docs_fragments/k8s_auth_options.py create mode 100644 lib/ansible/utils/module_docs_fragments/k8s_name_options.py create mode 100644 lib/ansible/utils/module_docs_fragments/k8s_resource_options.py create mode 100644 lib/ansible/utils/module_docs_fragments/k8s_state_options.py delete mode 100644 lib/ansible/utils/module_docs_fragments/kubernetes.py diff --git a/lib/ansible/modules/clustering/k8s/k8s_raw.py b/lib/ansible/modules/clustering/k8s/k8s_raw.py index 38954511010..cac3e428996 100644 --- a/lib/ansible/modules/clustering/k8s/k8s_raw.py +++ b/lib/ansible/modules/clustering/k8s/k8s_raw.py @@ -32,7 +32,10 @@ description: - Supports check mode, and the diff option. extends_documentation_fragment: - - kubernetes + - k8s_state_options + - k8s_name_options + - k8s_resource_options + - k8s_auth_options requirements: - "python >= 2.7" diff --git a/lib/ansible/modules/clustering/openshift/openshift_raw.py b/lib/ansible/modules/clustering/openshift/openshift_raw.py index 9a8c2955a24..302295e9e08 100644 --- a/lib/ansible/modules/clustering/openshift/openshift_raw.py +++ b/lib/ansible/modules/clustering/openshift/openshift_raw.py @@ -31,7 +31,11 @@ description: - Authenticate using either a config file, certificates, password or token. - Supports check mode, and the diff option. -extends_documentation_fragment: kubernetes +extends_documentation_fragment: + - k8s_state_options + - k8s_name_options + - k8s_resource_options + - k8s_auth_options options: description: diff --git a/lib/ansible/utils/module_docs_fragments/k8s_auth_options.py b/lib/ansible/utils/module_docs_fragments/k8s_auth_options.py new file mode 100644 index 00000000000..4afa1c39ac5 --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/k8s_auth_options.py @@ -0,0 +1,71 @@ +# +# Copyright 2018 Red Hat | Ansible +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# Options for authenticating with the API. + + +class ModuleDocFragment(object): + + DOCUMENTATION = ''' +options: + host: + description: + - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable. + api_key: + description: + - Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable. + kubeconfig: + description: + - 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 I(~/.kube/config.json). Can also be specified via K8S_AUTH_KUBECONFIG environment + variable. + context: + description: + - The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable. + username: + description: + - Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment + variable. + password: + description: + - Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment + variable. + cert_file: + description: + - Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment + variable. + key_file: + description: + - Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_HOST environment + variable. + ssl_ca_cert: + description: + - Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT + environment variable. + verify_ssl: + description: + - "Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL + environment variable." + type: bool + +notes: + - "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" +''' diff --git a/lib/ansible/utils/module_docs_fragments/k8s_name_options.py b/lib/ansible/utils/module_docs_fragments/k8s_name_options.py new file mode 100644 index 00000000000..74e693c3960 --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/k8s_name_options.py @@ -0,0 +1,54 @@ +# +# Copyright 2018 Red Hat | Ansible +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# Options for selecting or identifying a specific K8s object + + +class ModuleDocFragment(object): + + DOCUMENTATION = ''' +options: + 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 + kind: + description: + - Use to specify an object model. Use to create, delete, or discover an object without providing a full + resource definition. Use in conjunction with I(api_version), I(name), and I(namespace) to identify a + specific object. If I(resource definition) is provided, the I(kind) from the I(resource_definition) + will override this option. + name: + description: + - Use to specify an object name. Use to create, delete, or discover an object without providing a full + resource definition. Use in conjunction with I(api_version), I(kind) and I(namespace) to identify a + specific object. If I(resource definition) is provided, the I(metadata.name) value from the + I(resource_definition) will override this option. + namespace: + description: + - Use to specify an object namespace. Useful when creating, deleting, or discovering an object without + 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. +''' diff --git a/lib/ansible/utils/module_docs_fragments/k8s_resource_options.py b/lib/ansible/utils/module_docs_fragments/k8s_resource_options.py new file mode 100644 index 00000000000..8f091a4923f --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/k8s_resource_options.py @@ -0,0 +1,41 @@ +# +# Copyright 2018 Red Hat | Ansible +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# Options for providing an object configuration + + +class ModuleDocFragment(object): + + DOCUMENTATION = ''' +options: + resource_definition: + description: + - "Provide a valid YAML definition for an object when creating or updating. NOTE: I(kind), I(api_version), I(name), + and I(namespace) will be overwritten by corresponding values found in the provided I(resource_definition)." + aliases: + - definition + - inline + src: + description: + - "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. +''' diff --git a/lib/ansible/utils/module_docs_fragments/k8s_state_options.py b/lib/ansible/utils/module_docs_fragments/k8s_state_options.py new file mode 100644 index 00000000000..660d6db98c3 --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/k8s_state_options.py @@ -0,0 +1,41 @@ +# +# Copyright 2018 Red Hat | Ansible +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# Options for specifying object state + + +class ModuleDocFragment(object): + + DOCUMENTATION = ''' +options: + state: + description: + - Determines if an object should be created, patched, or deleted. When set to C(present), an object will be + created, if it does not already exist. If set to C(absent), an existing object will be deleted. If set to + C(present), an existing object will be patched, if its attributes differ from those specified using + I(resource_definition) or I(src). + default: present + choices: + - present + - absent + force: + description: + - If set to C(True), and I(state) is C(present), an existing object will be replaced. + default: false + type: bool +''' diff --git a/lib/ansible/utils/module_docs_fragments/kubernetes.py b/lib/ansible/utils/module_docs_fragments/kubernetes.py deleted file mode 100644 index 0792c9cbef4..00000000000 --- a/lib/ansible/utils/module_docs_fragments/kubernetes.py +++ /dev/null @@ -1,125 +0,0 @@ -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . -# - - -class ModuleDocFragment(object): - - DOCUMENTATION = ''' -options: - state: - description: - - Determines if an object should be created, patched, or deleted. When set to C(present), an object will be - created, if it does not already exist. If set to C(absent), an existing object will be deleted. If set to - C(present), an existing object will be patched, if its attributes differ from those specified using - I(resource_definition) or I(src). - default: present - choices: - - present - - absent - force: - description: - - If set to C(True), and I(state) is C(present), an existing object will be replaced. - default: false - type: bool - resource_definition: - description: - - "Provide a valid YAML definition for an object when creating or updating. NOTE: I(kind), I(api_version), I(name), - and I(namespace) will be overwritten by corresponding values found in the provided I(resource_definition)." - aliases: - - definition - - inline - src: - description: - - "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 - kind: - description: - - Use to specify an object model. Use to create, delete, or discover an object without providing a full - resource definition. Use in conjunction with I(api_version), I(name), and I(namespace) to identify a - specific object. If I(resource definition) is provided, the I(kind) from the I(resource_definition) - will override this option. - name: - description: - - Use to specify an object name. Use to create, delete, or discover an object without providing a full - resource definition. Use in conjunction with I(api_version), I(kind) and I(namespace) to identify a - specific object. If I(resource definition) is provided, the I(metadata.name) value from the - I(resource_definition) will override this option. - namespace: - description: - - Use to specify an object namespace. Useful when creating, deleting, or discovering an object without - 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. - host: - description: - - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable. - api_key: - description: - - Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable. - kubeconfig: - description: - - 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 I(~/.kube/config.json). Can also be specified via K8S_AUTH_KUBECONFIG environment - variable. - context: - description: - - The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable. - username: - description: - - Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment - variable. - password: - description: - - Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment - variable. - cert_file: - description: - - Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment - variable. - key_file: - description: - - Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_HOST environment - variable. - ssl_ca_cert: - description: - - Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT - environment variable. - verify_ssl: - description: - - "Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL - environment variable." - type: bool - -notes: - - "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" -'''