internet/kubernetes.core
3
0
Fork 0
mirror of https://github.com/ansible-collections/kubernetes.core.git synced 2026-03-26 21:33:02 +00:00
Code Issues Projects Releases Wiki Activity

Issue #2, Issue #5: Migrate doc_fragments, fix missing types in docs.

Browse Source
This commit is contained in:
Jeff Geerling
2020-01-30 15:28:30 -06:00
parent 48b4c3be54
commit 49fe926bb4
15 changed files with 268 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
plugins/doc_fragments/__init__.py Normal file
View File

86
plugins/doc_fragments/k8s_auth_options.py Normal file
View File

@@ -0,0 +1,86 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Red Hat | Ansible
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# Options for authenticating with the API.
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
options:
host:
description:
- Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
type: str
api_key:
description:
- Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
type: str
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.
type: path
context:
description:
- The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
type: str
username:
description:
- 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 C(k8s_auth) module, as that might do what you need.
type: str
password:
description:
- Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment
variable.
- Please read the description of the C(username) option for a discussion of when this option is applicable.
type: str
client_cert:
description:
- Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment
variable.
type: path
aliases: [ cert_file ]
client_key:
description:
- Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment
variable.
type: path
aliases: [ key_file ]
ca_cert:
description:
- 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.
type: path
aliases: [ ssl_ca_cert ]
validate_certs:
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
aliases: [ verify_ssl ]
proxy:
description:
- 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).
version_added: "2.9"
type: str
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"
- "To avoid SSL certificate validation errors when C(validate_certs) is I(True), the full
certificate chain for the API server must be provided via C(ca_cert) or in the
kubeconfig file."
'''

48
plugins/doc_fragments/k8s_name_options.py Normal file
View File

@@ -0,0 +1,48 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Red Hat | Ansible
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# Options for selecting or identifying a specific K8s object
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
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.
type: str
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.
type: str
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.
type: str
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.
type: str
'''

32
plugins/doc_fragments/k8s_resource_options.py Normal file
View File

@@ -0,0 +1,32 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Red Hat | Ansible
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# Options for providing an object configuration
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
options:
resource_definition:
description:
- "Provide a valid YAML definition (either as a string, list, or dict) 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 or objects 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, including vaulted files, 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.
type: path
'''

42
plugins/doc_fragments/k8s_scale_options.py Normal file
View File

@@ -0,0 +1,42 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Red Hat | Ansible
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# Options used by scale modules.
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
options:
replicas:
description:
- The desired number of replicas.
type: int
current_replicas:
description:
- For Deployment, ReplicaSet, Replication Controller, only scale, if the number of existing replicas
matches. In the case of a Job, update parallelism only if the current parallelism value matches.
type: int
resource_version:
description:
- Only attempt to scale, if the current object version matches.
type: str
wait:
description:
- For Deployment, ReplicaSet, Replication Controller, wait for the status value of I(ready_replicas) to change
to the number of I(replicas). In the case of a Job, this option is ignored.
type: bool
default: yes
wait_timeout:
description:
- When C(wait) is I(True), the number of seconds to wait for the I(ready_replicas) status to equal I(replicas).
If the status is not reached within the allotted time, an error will result. In the case of a Job, this option
is ignored.
type: int
default: 20
'''

30
plugins/doc_fragments/k8s_state_options.py Normal file
View File

@@ -0,0 +1,30 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Red Hat | Ansible
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# Options for specifying object state
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
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).
type: str
default: present
choices: [ absent, present ]
force:
description:
- If set to C(yes), and I(state) is C(present), an existing object will be replaced.
type: bool
default: no
'''

5
plugins/module_utils/common.py
View File

@@ -16,6 +16,7 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
from __future__ import absolute_import, division, print_function
__metaclass__ = type
import copy
import json
@@ -122,7 +123,9 @@ AUTH_ARG_SPEC = {
'type': 'path',
'aliases': ['key_file'],
},
'proxy': {},
'proxy': {
'type': 'str',
},
}
# Map kubernetes-client parameters to ansible parameters

1
plugins/module_utils/raw.py
View File

@@ -17,6 +17,7 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
from __future__ import absolute_import, division, print_function
__metaclass__ = type
import copy
from datetime import datetime

1
plugins/module_utils/scale.py
View File

@@ -17,6 +17,7 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
from __future__ import absolute_import, division, print_function
__metaclass__ = type
import copy
import math

18
plugins/modules/_kubernetes.py
View File

@@ -1,18 +0,0 @@
#!/usr/bin/python
# Copyright: (c) 2015, Google Inc. All Rights Reserved.
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['removed'],
'supported_by': 'community'}
from ansible.module_utils.common.removed import removed_module
if __name__ == '__main__':
removed_module(removed_in='2.9')

21
plugins/modules/_oc.py
View File

@@ -1,21 +0,0 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2017, Kenneth D. Evensen <kevensen@redhat.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['removed'],
'supported_by': 'community'
}
from ansible.module_utils.common.removed import removed_module
if __name__ == '__main__':
removed_module(removed_in='2.9')

11
plugins/modules/k8s.py
View File

@@ -80,23 +80,27 @@ options:
description:
- Number of seconds to sleep between checks.
default: 5
type: int
version_added: "2.9"
wait_timeout:
description:
- How long in seconds to wait for the resource to end up in the desired state. Ignored if C(wait) is not set.
default: 120
type: int
version_added: "2.8"
wait_condition:
description:
- Specifies a custom condition on the status to wait for. Ignored if C(wait) is not set or is set to False.
suboptions:
type:
type: str
description:
- The type of condition to wait for. For example, the C(Pod) resource will set the C(Ready) condition (among others)
- Required if you are specifying a C(wait_condition). If left empty, the C(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.
status:
type: str
description:
- The value of the status field in your desired condition.
- For example, if a C(Deployment) is paused, the C(Progressing) C(type) will have the C(Unknown) status.
@@ -104,12 +108,15 @@ options:
- True
- False
- Unknown
default: "True"
reason:
type: str
description:
- The value of the reason field in your desired condition
- For example, if a C(Deployment) is paused, The C(Progressing) c(type) will have the C(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.
type: dict
version_added: "2.8"
validate:
description:
@@ -122,10 +129,12 @@ options:
type: bool
version:
description: version of Kubernetes to validate against. defaults to Kubernetes server version
type: str
strict:
description: whether to fail when passing unexpected properties
default: no
default: True
type: bool
type: dict
version_added: "2.8"
append_hash:
description:

6
plugins/modules/k8s_auth.py
View File

@@ -43,21 +43,26 @@ options:
choices:
- present
- absent
type: str
host:
description:
- Provide a URL for accessing the API server.
required: true
type: str
username:
description:
- Provide a username for authenticating with the API server.
type: str
password:
description:
- Provide a password for authenticating with the API server.
type: str
ca_cert:
description:
- "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 ]
type: path
validate_certs:
description:
- "Whether or not to verify the API server's SSL certificates."
@@ -67,6 +72,7 @@ options:
api_key:
description:
- When C(state) is set to I(absent), this specifies the token to revoke.
type: str
requirements:
- python >= 2.7

6
plugins/modules/k8s_info.py
View File

@@ -39,23 +39,29 @@ options:
aliases:
- api
- version
type: str
kind:
description:
- Use to specify an object model. Use in conjunction with I(api_version), I(name), and I(namespace) to identify a
specific object.
required: yes
type: str
name:
description:
- Use to specify an object name. Use in conjunction with I(api_version), I(kind) and I(namespace) to identify a
specific object.
type: str
namespace:
description:
- Use to specify an object namespace. Use in conjunction with I(api_version), I(kind), and I(name)
to identify a specific object.
type: str
label_selectors:
description: List of label selectors to use to filter results
type: list
field_selectors:
description: List of field selectors to use to filter results
type: list
extends_documentation_fragment:
- k8s_auth_options

2
plugins/modules/k8s_service.py
View File

@@ -50,6 +50,7 @@ options:
choices:
- present
- absent
type: str
force:
description:
- If set to C(True), and I(state) is C(present), an existing object will be replaced.
@@ -91,6 +92,7 @@ options:
- ClusterIP
- LoadBalancer
- ExternalName
type: str
ports:
description:
- A list of ports to expose.