diff --git a/lib/ansible/modules/clustering/k8s.py b/lib/ansible/modules/clustering/k8s.py new file mode 100644 index 0000000000..f145bde171 --- /dev/null +++ b/lib/ansible/modules/clustering/k8s.py @@ -0,0 +1,126 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# (c) 2018, Chris Houseknecht <@chouseknecht> +# 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': ['preview'], + 'supported_by': 'community'} + +DOCUMENTATION = ''' + +module: k8s + +short_description: Manage Kubernetes (K8s) objects + +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. + +extends_documentation_fragment: + - kubernetes + +requirements: + - "python >= 2.7" + - "openshift >= 0.3" + - "PyYAML >= 3.11" +''' + +EXAMPLES = ''' +- name: Create a k8s namespace + k8s: + name: testing + api_version: v1 + kind: Namespace + state: present + +- name: Create a Service object from an inline definition + 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: Create a Service object by reading the definition from a file + k8s: + state: present + src: /testing/service.yml + +- name: Get an existing Service object + k8s: + api_version: v1 + kind: Service + name: web + namespace: testing + register: web_service + +- name: Get a list of all service objects + k8s: + api_version: v1 + kind: ServiceList + namespace: testing + register: service_list + +- name: Remove an existing Service object + k8s: + state: absent + api_version: v1 + kind: Service + namespace: testing + name: web +''' + +RETURN = ''' +result: + description: + - The created, patched, or otherwise present object. Will be empty in the case of a deletion. + returned: success + type: dict +request: + description: + - The object sent to the API. Useful for troubleshooting unexpected differences and 404 errors. + returned: when diff is true + type: dict +diff: + description: + - List of differences found when determining if an existing object will be patched. A copy of the existing object + is updated with the requested options, and the updated object is then compared to the original. If there are + differences, they will appear here. + returned: when diff is true + type: list +''' + +from ansible.module_utils.k8s_common import KubernetesAnsibleModule + + +def main(): + KubernetesAnsibleModule().execute_module() + + +if __name__ == '__main__': + main() diff --git a/lib/ansible/utils/module_docs_fragments/kubernetes.py b/lib/ansible/utils/module_docs_fragments/kubernetes.py new file mode 100644 index 0000000000..e970442d82 --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/kubernetes.py @@ -0,0 +1,128 @@ +# 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." + 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. + 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. + 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. + 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: + - "To learn more about the OpenShift Python client and available object models, visit: + https://github.com/openshift/openshift-restclient-python" +'''