Docs: Migrate Scenario Guide to collection (ansible-collections#143)

Migrate scenario guide from ansible/ansible repo to
this collection.

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

docs/docsite/extra-docs.yml

@@ -0,0 +1,5 @@
+---
+sections:
+  - title: Scenario Guide
+    toctree:
+      - scenario_guide

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 <https://galaxy.ansible.com/kubernetes/core>`_ 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 <https://pypi.org/project/kubernetes/>`_  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 <https://github.com/ansible-collections/kubernetes.core/issues>`_.
+- If you find a bug regarding Kubernetes Python client, please file issues at `Kubernetes Client issues <https://github.com/kubernetes-client/python/issues>`_.
+- If you find a bug regarding Kubectl binary, please file issues at `Kubectl issue tracker <https://github.com/kubernetes/kubectl/issues>`_
+- If you find a bug regarding Helm binary, please file issues at `Helm issue tracker <https://github.com/helm/helm/issues>`_.

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 <https://github.com/kubernetes-client/python>`_, `kubectl <https://github.com/kubernetes/kubectl>`_ on your control node (the host running Ansible).
+
+.. code-block:: bash
+
+    $ pip install kubernetes
+
+Please refer to Kubernetes official documentation for `installing kubectl <https://kubernetes.io/docs/tasks/tools/install-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 <filename>.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 <filename>.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 <filename>.k8s.yml --list --vault-password-file=/path/to/vault_password_file
+
+
+.. seealso::
+
+    `Kubernetes Python client - Issue Tracker <https://github.com/kubernetes-client/python/issues>`_
+        The issue tracker for Kubernetes Python client
+    `Kubectl installation <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_
+        Installation guide for installing Kubectl
+    :ref:`working_with_playbooks`
+        An introduction to playbooks
+    :ref:`playbooks_vault`
+        Using Vault in playbooks

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

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 <https://github.com/ansible-collections/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 <https://docs.ansible.com/ansible-tower/latest/html/userguide/credentials.html>`_.
+
+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 <https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates>`_. 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 <https://github.com/kubernetes-client/python>`_
+        The GitHub Page of Kubernetes Python client
+    `Kubernetes Python client - Issue Tracker <https://github.com/kubernetes-client/python/issues>`_
+        The issue tracker for Kubernetes Python client
+    `Kubectl installation <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_
+        Installation guide for installing Kubectl
+    :ref:`working_with_playbooks`
+        An introduction to playbooks
+    :ref:`playbooks_vault`
+        Using Vault in playbooks

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
+

plugins/modules/k8s_json_patch.py

@@ -15,7 +15,7 @@
 
 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