Adds k8s_common.py (#22899)

docs/docsite/rst/guide_kubernetes.rst

@@ -0,0 +1,56 @@
+Getting Started with Kubernetes and OpenShift
+=============================================
+
+Modules for interacting with the Kubernetes (K8s) and OpenShift API are under development, and can be used in preview mode. To use them, review the requirements, and then follow the installation and use instructions.
+
+Requirements
+------------
+
+To use the modules, you'll need the following:
+
+- Run Ansible from source. For assistance, view `running from source <./intro_installation.html/#running-from-source>`_
+- `OpenShift Rest Client <https://github.com/openshift/openshift-restclient-python>`_ installed on the host that will execute the modules
+
+
+Installation and use
+--------------------
+
+The individual modules, as of this writing, are not part of the Ansible repository, but they can be accessed by installing the role, `ansible.kubernetes-modules <https://galaxy.ansible.com/ansible/kubernetes-modules/>`_, and including it in a playbook.
+
+To install, run the following:
+
+.. code-block:: bash
+
+    $ ansible-galaxy install ansible.kubernetes-modules
+
+Next, include it in a playbook, as follows:
+
+.. code-block:: bash
+
+    ---
+    - hosts: localhost
+      remote_user: root
+      roles:
+        - role: ansible.kubernetes-modules
+        - role: hello-world
+
+Because the role is referenced, ``hello-world`` is able to access the modules, and use them to deploy an application.
+
+The modules are found in the ``library`` folder of the role. Each includes full documentation for parameters and the returned data structure. However, not all modules include examples, only those where `testing data <https://github.com/openshift/openshift-restclient-python/tree/master/openshift/ansiblegen/examples>`_ has been created.
+
+Authenticating with the API
+---------------------------
+
+By default the OpenShift Rest Client will look for ``~/.kube/config``, and if found, connect using the active context. You can override the location of the file using the``kubeconfig`` parameter, and the context, using the ``context`` parameter.
+
+Basic authentication is also supported using the ``username`` and ``password`` options. You can override the URL using the ``host`` parameter. Certificate authentication works through the ``ssl_ca_cert``, ``cert_file``, and ``key_file`` parameters, and for token authentication, use the ``api_key`` parameter.
+
+To disable SSL certificate verification, set ``verify_ssl`` to false.
+
+Filing issues
+`````````````
+
+If you find a bug or have a suggestion regarding individual modules or the role, please file issues at `OpenShift Rest Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
+
+There is also a utility module, k8s_common.py, that is part of the `Ansible <https://github.com/ansible/ansible>`_ repo. If you find a bug or have suggestions regarding it, please file issues at `Ansible issues <https://github.com/ansible/ansible/issues>`_.
+

lib/ansible/module_utils/k8s_common.py

@@ -0,0 +1,313 @@
+#
+#  Copyright 2017 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 <http://www.gnu.org/licenses/>.
+
+import copy
+import json
+import os
+
+from ansible.module_utils.basic import AnsibleModule
+
+try:
+    from openshift.helper.ansible import AnsibleModuleHelper, OpenShiftException, ARG_ATTRIBUTES_BLACKLIST
+    HAS_OPENSHIFT = True
+except ImportError as exc:
+    HAS_OPENSHIFT = False
+
+try:
+    import yaml
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+class OpenShiftAnsibleException(Exception):
+    pass
+
+
+class OpenShiftAnsibleModule(AnsibleModule):
+
+    def __init__(self, kind, api_version):
+        self.api_version = api_version
+        self.kind = kind
+        self.argspec_cache = None
+
+        if not HAS_OPENSHIFT:
+            raise OpenShiftAnsibleException(
+                "This module requires the OpenShift Python client. Try `pip install openshift`"
+            )
+
+        if not HAS_YAML:
+            raise OpenShiftAnsibleException(
+                "This module requires PyYAML. Try `pip install PyYAML`"
+            )
+
+        try:
+            self.helper = AnsibleModuleHelper(api_version, kind)
+        except Exception as exc:
+            raise OpenShiftAnsibleException(
+                "Error initializing AnsibleModuleHelper: {}".format(exc)
+            )
+
+        mutually_exclusive = (
+            ('resource_definition', 'src'),
+        )
+
+        AnsibleModule.__init__(self,
+                               argument_spec=self.argspec,
+                               supports_check_mode=True,
+                               mutually_exclusive=mutually_exclusive)
+
+    @property
+    def argspec(self):
+        """
+        Build the module argument spec from the helper.argspec, removing any extra attributes not needed by
+        Ansible.
+
+        :return: dict: a valid Ansible argument spec
+        """
+        if not self.argspec_cache:
+            spec = {}
+            for arg_name, arg_properties in self.helper.argspec.items():
+                spec[arg_name] = {}
+                for option, option_value in arg_properties.items():
+                    if option not in ARG_ATTRIBUTES_BLACKLIST:
+                        if option == 'choices':
+                            if isinstance(option_value, dict):
+                                spec[arg_name]['choices'] = [value for key, value in option_value.items()]
+                            else:
+                                spec[arg_name]['choices'] = option_value
+                        else:
+                            spec[arg_name][option] = option_value
+
+            self.argspec_cache = spec
+        return self.argspec_cache
+
+    def execute_module(self):
+        """
+        Performs basic CRUD operations on the model object. Ends by calling
+        AnsibleModule.fail_json(), if an error is encountered, otherwise
+        AnsibleModule.exit_json() with a dict containing:
+          changed: boolean
+          api_version: the API version
+          <kind>: a dict representing the object's state
+        :return: None
+        """
+
+        if self.params.get('debug'):
+            self.helper.enable_debug(reset_logfile=False)
+            self.helper.log_argspec()
+
+        resource_definition = self.params.get('resource_definition')
+        if self.params.get('src'):
+            resource_definition = self.load_resource_definition(self.params['src'])
+        if resource_definition:
+            resource_params = self.resource_to_parameters(resource_definition)
+            self.params.update(resource_params)
+
+        state = self.params.get('state', None)
+        force = self.params.get('force', False)
+        name = self.params.get('name')
+        namespace = self.params.get('namespace', None)
+        existing = None
+
+        return_attributes = dict(changed=False, api_version=self.api_version)
+        return_attributes[self.helper.base_model_name_snake] = {}
+
+        try:
+            auth_options = {}
+            for key, value in self.helper.argspec.items():
+                if value.get('auth_option') and self.params.get(key) is not None:
+                    auth_options[key] = self.params[key]
+            self.helper.set_client_config(**auth_options)
+        except OpenShiftException as e:
+            self.fail_json(msg='Error loading config', error=str(e))
+
+        if state is None:
+            # This is a list, rollback or ? module with no 'state' param
+            if self.helper.base_model_name_snake.endswith('list'):
+                # For list modules, execute a GET, and exit
+                k8s_obj = self._read(name, namespace)
+                return_attributes[self.kind] = k8s_obj.to_dict()
+                self.exit_json(**return_attributes)
+            elif self.helper.has_method('create'):
+                # For a rollback, execute a POST, and exit
+                k8s_obj = self._create(namespace)
+                return_attributes[self.kind] = k8s_obj.to_dict()
+                return_attributes['changed'] = True
+                self.exit_json(**return_attributes)
+            else:
+                self.fail_json(msg="Missing state parameter. Expected one of: present, absent")
+
+        # CRUD modules
+        try:
+            existing = self.helper.get_object(name, namespace)
+        except OpenShiftException as exc:
+            self.fail_json(msg='Failed to retrieve requested object: {}'.format(exc.message),
+                           error=exc.value.get('status'))
+
+        if state == 'absent':
+            if not existing:
+                # The object already does not exist
+                self.exit_json(**return_attributes)
+            else:
+                # Delete the object
+                if not self.check_mode:
+                    try:
+                        self.helper.delete_object(name, namespace)
+                    except OpenShiftException as exc:
+                        self.fail_json(msg="Failed to delete object: {}".format(exc.message),
+                                       error=exc.value.get('status'))
+                return_attributes['changed'] = True
+                self.exit_json(**return_attributes)
+        else:
+            if not existing:
+                # create new object
+                if self.kind.lower() == 'project':
+                    k8s_obj = self._create_project()
+                else:
+                    k8s_obj = self._create(namespace)
+                return_attributes[self.kind] = k8s_obj.to_dict()
+                return_attributes['changed'] = True
+                self.exit_json(**return_attributes)
+
+            if existing and force:
+                k8s_obj = None
+                request_body = self.helper.request_body_from_params(self.params)
+                if not self.check_mode:
+                    try:
+                        k8s_obj = self.helper.replace_object(name, namespace, body=request_body)
+                    except OpenShiftException as exc:
+                        self.fail_json(msg="Failed to replace object: {}".format(exc.message),
+                                       error=exc.value.get('status'))
+                return_attributes[self.kind] = k8s_obj.to_dict()
+                return_attributes['changed'] = True
+                self.exit_json(**return_attributes)
+
+            # Check if existing object should be patched
+            k8s_obj = copy.deepcopy(existing)
+            try:
+                self.helper.object_from_params(self.params, obj=k8s_obj)
+            except OpenShiftException as exc:
+                self.fail_json(msg="Failed to patch object: {}".format(exc.message))
+            match, diff = self.helper.objects_match(existing, k8s_obj)
+            if match:
+                return_attributes[self.kind] = existing.to_dict()
+                self.exit_json(**return_attributes)
+            else:
+                self.helper.log('Existing:')
+                self.helper.log(json.dumps(existing.to_dict(), indent=4))
+                self.helper.log('\nDifferences:')
+                self.helper.log(json.dumps(diff, indent=4))
+            # Differences exist between the existing obj and requested params
+            if not self.check_mode:
+                try:
+                    k8s_obj = self.helper.patch_object(name, namespace, k8s_obj)
+                except OpenShiftException as exc:
+                    self.fail_json(msg="Failed to patch object: {}".format(exc.message))
+            return_attributes[self.kind] = k8s_obj.to_dict()
+            return_attributes['changed'] = True
+            self.exit_json(**return_attributes)
+
+    def _create(self, namespace):
+        request_body = None
+        k8s_obj = None
+        try:
+            request_body = self.helper.request_body_from_params(self.params)
+        except OpenShiftException as exc:
+            self.fail_json(msg="Failed to create object: {}".format(exc.message))
+        if not self.check_mode:
+            try:
+                k8s_obj = self.helper.create_object(namespace, body=request_body)
+            except OpenShiftException as exc:
+                self.fail_json(msg="Failed to create object: {}".format(exc.message),
+                               error=exc.value.get('status'))
+        return k8s_obj
+
+    def _create_project(self):
+        new_obj = None
+        k8s_obj = None
+        try:
+            new_obj = self.helper.object_from_params(self.params)
+        except OpenShiftException as exc:
+            self.fail_json(msg="Failed to create object: {}".format(exc.message))
+        try:
+            k8s_obj = self.helper.create_project(metadata=new_obj.metadata,
+                                                 display_name=self.params.get('display_name'),
+                                                 description=self.params.get('description'))
+        except OpenShiftException as exc:
+            self.fail_json(msg='Failed to retrieve requested object',
+                           error=exc.value.get('status'))
+        return k8s_obj
+
+    def _read(self, name, namespace):
+        k8s_obj = None
+        try:
+            k8s_obj = self.helper.get_object(name, namespace)
+        except OpenShiftException as exc:
+            self.fail_json(msg='Failed to retrieve requested object',
+                           error=exc.value.get('status'))
+        return k8s_obj
+
+    def load_resource_definition(self, src):
+        """ Load the requested src path """
+        result = None
+        path = os.path.normpath(src)
+        self.helper.log("Reading definition from {}".format(path))
+        if not os.path.exists(path):
+            self.fail_json(msg="Error accessing {}. Does the file exist?".format(path))
+        try:
+            result = yaml.safe_load(open(path, 'r'))
+        except (IOError, yaml.YAMLError) as exc:
+            self.fail_json(msg="Error loading resource_definition: {}".format(exc))
+        return result
+
+    def resource_to_parameters(self, resource):
+        """ Converts a resource definition to module parameters """
+        parameters = {}
+        for key, value in resource.items():
+            if key in ('apiVersion', 'kind', 'status'):
+                continue
+            elif key == 'metadata' and isinstance(value, dict):
+                for meta_key, meta_value in value.items():
+                    if meta_key in ('name', 'namespace', 'labels', 'annotations'):
+                        parameters[meta_key] = meta_value
+            elif key in self.helper.argspec and value is not None:
+                    parameters[key] = value
+            elif isinstance(value, dict):
+                self._add_parameter(value, [key], parameters)
+        self.helper.log("Request to parameters: {}".format(json.dumps(parameters)))
+        return parameters
+
+    def _add_parameter(self, request, path, parameters):
+        for key, value in request.items():
+            if path:
+                param_name = '_'.join(path + [self.helper.attribute_to_snake(key)])
+            else:
+                param_name = self.helper.attribute_to_snake(key)
+            if param_name in self.helper.argspec and value is not None:
+                parameters[param_name] = value
+            elif isinstance(value, dict):
+                continue_path = copy.copy(path) if path else []
+                continue_path.append(self.helper.attribute_to_snake(key))
+                self._add_parameter(value, continue_path, parameters)
+            else:
+                self.fail_json(
+                    msg=("Error parsing resource definition. Encountered {}, which does not map to a module "
+                         "parameter. If this looks like a problem with the module, please open an issue at "
+                         "github.com/openshift/openshift-restclient-python/issues").format(param_name)
+                )