diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml new file mode 100644 index 00000000..969d8d86 --- /dev/null +++ b/docs/docsite/extra-docs.yml @@ -0,0 +1,5 @@ +--- +sections: + - title: Scenario Guide + toctree: + - scenario_guide diff --git a/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst b/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst new file mode 100644 index 00000000..e5bcfb8d --- /dev/null +++ b/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst @@ -0,0 +1,51 @@ +.. _ansible_collections.kubernetes.core.docsite.k8s_ansible_intro: + +************************************** +Introduction to Ansible for Kubernetes +************************************** + +.. contents:: + :local: + +Introduction +============ + +The `kubernetes.core collection `_ offers several modules and plugins for orchestrating Kubernetes. + +Requirements +============ + +To use the modules, you'll need the following: + +- Ansible 2.9.17 or latest installed +- `Kubernetes Python client `_ installed on the host that will execute the modules. + + +Installation +============ + +The Kubernetes modules are part of the Ansible Kubernetes collection. + +To install the collection, run the following: + +.. code-block:: bash + + $ ansible-galaxy collection install kubernetes.core + + +Authenticating with the API +=========================== + +By default the Kubernetes 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. + +Reporting an issue +================== + +- If you find a bug or have a suggestion regarding modules or plugins, please file issues at `Ansible Kubernetes collection `_. +- If you find a bug regarding Kubernetes Python client, please file issues at `Kubernetes Client issues `_. +- If you find a bug regarding Kubectl binary, please file issues at `Kubectl issue tracker `_ +- If you find a bug regarding Helm binary, please file issues at `Helm issue tracker `_. diff --git a/docs/docsite/rst/kubernetes_scenarios/k8s_inventory.rst b/docs/docsite/rst/kubernetes_scenarios/k8s_inventory.rst new file mode 100644 index 00000000..e7f4da9c --- /dev/null +++ b/docs/docsite/rst/kubernetes_scenarios/k8s_inventory.rst @@ -0,0 +1,88 @@ +.. _ansible_collections.kubernetes.core.docsite.k8s_ansible_inventory: + +***************************************** +Using Kubernetes dynamic inventory plugin +***************************************** + +.. contents:: + :local: + +Kubernetes dynamic inventory plugin +=================================== + + +The best way to interact with your Pods is to use the Kubernetes dynamic inventory plugin, which queries Kubernetes APIs using ``kubectl`` command line available on controller node and tells Ansible what Pods can be managed. + +Requirements +------------ + +To use the Kubernetes dynamic inventory plugins, you must install `Kubernetes Python client `_, `kubectl `_ on your control node (the host running Ansible). + +.. code-block:: bash + + $ pip install kubernetes + +Please refer to Kubernetes official documentation for `installing kubectl `_ on the given operating systems. + +To use this Kubernetes dynamic inventory plugin, you need to enable it first by specifying the following in the ``ansible.cfg`` file: + +.. code-block:: ini + + [inventory] + enable_plugins = kubernetes.core.k8s + +Then, create a file that ends in ``.k8s.yml`` or ``.k8s.yaml`` in your working directory. + +The ``kubernetes.core.k8s`` inventory plugin takes in the same authentication information as any other Kubernetes modules. + +Here's an example of a valid inventory file: + +.. code-block:: yaml + + plugin: kubernetes.core.k8s + +Executing ``ansible-inventory --list -i .k8s.yml`` will create a list of Pods that are ready to be configured using Ansible. + +You can also provide the namespace to gather information about specific pods from the given namespace. For example, to gather information about Pods under the ``test`` namespace you will specify the ``namespaces`` parameter: + +.. code-block:: yaml + + plugin: kubernetes.core.k8s + connections: + - namespaces: + - test + +Using vaulted configuration files +================================= + +Since the inventory configuration file contains Kubernetes related sensitive information in plain text, a security risk, you may want to +encrypt your entire inventory configuration file. + +You can encrypt a valid inventory configuration file as follows: + +.. code-block:: bash + + $ ansible-vault encrypt .k8s.yml + New Vault password: + Confirm New Vault password: + Encryption successful + + $ echo "MySuperSecretPassw0rd!" > /path/to/vault_password_file + +And you can use this vaulted inventory configuration file using: + +.. code-block:: bash + + $ ansible-inventory -i .k8s.yml --list --vault-password-file=/path/to/vault_password_file + + +.. seealso:: + + `Kubernetes Python client - Issue Tracker `_ + The issue tracker for Kubernetes Python client + `Kubectl installation `_ + Installation guide for installing Kubectl + :ref:`working_with_playbooks` + An introduction to playbooks + :ref:`playbooks_vault` + Using Vault in playbooks diff --git a/docs/docsite/rst/kubernetes_scenarios/k8s_scenarios.rst b/docs/docsite/rst/kubernetes_scenarios/k8s_scenarios.rst new file mode 100644 index 00000000..df5eb57d --- /dev/null +++ b/docs/docsite/rst/kubernetes_scenarios/k8s_scenarios.rst @@ -0,0 +1,12 @@ +.. _ansible_collections.kubernetes.core.docsite.k8s_scenarios: + +******************************** +Ansible for Kubernetes Scenarios +******************************** + +These scenarios teach you how to accomplish common Kubernetes tasks using Ansible. To get started, please select the task you want to accomplish. + +.. toctree:: + :maxdepth: 1 + + scenario_k8s_object \ No newline at end of file diff --git a/docs/docsite/rst/kubernetes_scenarios/scenario_k8s_object.rst b/docs/docsite/rst/kubernetes_scenarios/scenario_k8s_object.rst new file mode 100644 index 00000000..6475245c --- /dev/null +++ b/docs/docsite/rst/kubernetes_scenarios/scenario_k8s_object.rst @@ -0,0 +1,175 @@ +.. _ansible_collections.kubernetes.core.docsite.k8s_object_template: + +******************* +Creating K8S object +******************* + +.. contents:: + :local: + +Introduction +============ + +This guide will show you how to utilize Ansible to create Kubernetes objects such as Pods, Deployments, and Secrets. + +Scenario Requirements +===================== + +* Software + + * Ansible 2.9.17 or later must be installed + + * The Python module ``kubernetes`` must be installed on the Ansible controller (or Target host if not executing against localhost) + + * Kubernetes Cluster + + * Kubectl binary installed on the Ansible controller + + +* Access / Credentials + + * Kubeconfig configured with the given Kubernetes cluster + + +Assumptions +=========== + +- User has required level of authorization to create, delete and update resources on the given Kubernetes cluster. + +Caveats +======= + +- community.kubernetes 2.0.0 has been renamed to `kubernetes.core `_ + +Example Description +=================== + +In this use case / example, we will create a Pod in the given Kubernetes Cluster. The following Ansible playbook showcases the basic parameters that are needed for this. + +.. code:: yaml + + --- + - hosts: localhost + collections: + - kubernetes.core + tasks: + - name: Create a pod + k8s: + state: present + definition: + apiVersion: v1 + kind: Pod + metadata: + name: "utilitypod-1" + namespace: default + labels: + app: galaxy + spec: + containers: + - name: utilitypod + image: busybox + +Since Ansible utilizes the Kubernetes API to perform actions, in this use case we will be connecting directly to the Kubernetes cluster. + +To begin, there are a few bits of information we will need. Here you are using Kubeconfig which is pre-configured in your machine. The Kubeconfig is generally located at ``~/.kube/config``. It is highly recommended to store sensitive information such as password, user certificates in a more secure fashion using :ref:`ansible-vault` or using `Ansible Tower credentials `_. + +Now you need to supply the information about the Pod which will be created. Using ``definition`` parameter of the ``kubernetes.core.k8s`` module, you specify `PodTemplate `_. This PodTemplate is identical to what you provide to the ``kubectl`` command. + +What to expect +-------------- + +- You will see a bit of JSON output after this playbook completes. This output shows various parameters that are returned from the module and from cluster about the newly created Pod. + +.. code:: json + + { + "changed": true, + "method": "create", + "result": { + "apiVersion": "v1", + "kind": "Pod", + "metadata": { + "creationTimestamp": "2020-10-03T15:36:25Z", + "labels": { + "app": "galaxy" + }, + "name": "utilitypod-1", + "namespace": "default", + "resourceVersion": "4511073", + "selfLink": "/api/v1/namespaces/default/pods/utilitypod-1", + "uid": "c7dec819-09df-4efd-9d78-67cf010b4f4e" + }, + "spec": { + "containers": [{ + "image": "busybox", + "imagePullPolicy": "Always", + "name": "utilitypod", + "resources": {}, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "volumeMounts": [{ + "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount", + "name": "default-token-6j842", + "readOnly": true + }] + }], + "dnsPolicy": "ClusterFirst", + "enableServiceLinks": true, + "priority": 0, + "restartPolicy": "Always", + "schedulerName": "default-scheduler", + "securityContext": {}, + "serviceAccount": "default", + "serviceAccountName": "default", + "terminationGracePeriodSeconds": 30, + "tolerations": [{ + "effect": "NoExecute", + "key": "node.kubernetes.io/not-ready", + "operator": "Exists", + "tolerationSeconds": 300 + }, + { + "effect": "NoExecute", + "key": "node.kubernetes.io/unreachable", + "operator": "Exists", + "tolerationSeconds": 300 + } + ], + "volumes": [{ + "name": "default-token-6j842", + "secret": { + "defaultMode": 420, + "secretName": "default-token-6j842" + } + }] + }, + "status": { + "phase": "Pending", + "qosClass": "BestEffort" + } + } + } + +- In the above example, 'changed' is ``True`` which notifies that the Pod creation started on the given cluster. This can take some time depending on your environment. + + +Troubleshooting +--------------- + +Things to inspect + +- Check if the values provided for username and password are correct +- Check if the Kubeconfig is populated with correct values + +.. seealso:: + + `Kubernetes Python client `_ + The GitHub Page of Kubernetes Python client + `Kubernetes Python client - Issue Tracker `_ + The issue tracker for Kubernetes Python client + `Kubectl installation `_ + Installation guide for installing Kubectl + :ref:`working_with_playbooks` + An introduction to playbooks + :ref:`playbooks_vault` + Using Vault in playbooks diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst new file mode 100644 index 00000000..c0fbaecc --- /dev/null +++ b/docs/docsite/rst/scenario_guide.rst @@ -0,0 +1,18 @@ +.. _ansible_collections.kubernetes.core.docsite.scenario_guide: + +Kubernetes Guide +================ + +Welcome to the Ansible for Kubernetes Guide! + +The purpose of this guide is to teach you everything you need to know about using Ansible with Kubernetes. + +To get started, please select one of the following topics. + +.. toctree:: + :maxdepth: 1 + + kubernetes_scenarios/k8s_intro + kubernetes_scenarios/k8s_inventory + kubernetes_scenarios/k8s_scenarios + diff --git a/plugins/modules/k8s_json_patch.py b/plugins/modules/k8s_json_patch.py index 45db2ccd..6db98811 100644 --- a/plugins/modules/k8s_json_patch.py +++ b/plugins/modules/k8s_json_patch.py @@ -15,7 +15,7 @@ short_description: Apply JSON patch operations to existing objects description: - This module is used to apply RFC 6902 JSON patch operations only. - - Use the M(k8s) module for strategic merge or JSON merge operations. + - Use the M(kubernetes.core.k8s) module for strategic merge or JSON merge operations. - The jsonpatch library is required for check mode. version_added: 2.0.0