archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

k8s: Scenario guides (#72095)

Browse Source 
* Start Kubernetes Scenario guides for users
* K8S inventory scenario guide

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
pull/71530/head
Abhijeet Kasurde 4 years ago committed by GitHub
parent d18901dd4a
commit 02658d7bf8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 346 additions and 57 deletions
Show Stats Download Patch File Download Diff File

69
docs/docsite/rst/scenario_guides/guide_kubernetes.rst
Unescape Escape View File

@ -1,63 +1,18 @@
Kubernetes and OpenShift Guide
==============================
.. _k8s_ansible:
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.
****************
Kubernetes Guide
****************
Requirements
------------
Welcome to the Ansible for Kubernetes Guide!
To use the modules, you'll need the following:
The purpose of this guide is to teach you everything you need to know about using Ansible with Kubernetes.
- Run Ansible from source. For assistance, view :ref:`from_source`.
- `OpenShift Rest Client <https://github.com/openshift/openshift-restclient-python>`_ installed on the host that will execute the modules.
To get started, please select one of the following topics.
.. toctree::
:maxdepth: 1
Installation and use
--------------------
The Kubernetes modules are part of the `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
To install the collection, run the following:
.. code-block:: bash
$ ansible-galaxy collection install community.kubernetes
Next, include it in a playbook, as follows:
.. code-block:: bash
---
- hosts: localhost
tasks:
- name: Create a pod
community.kubernetes.k8s:
state: present
definition:
apiVersion: v1
kind: Pod
metadata:
name: "utilitypod-1"
namespace: default
labels:
app: galaxy
spec:
containers:
- name: utilitypod
image: busybox
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 modules, please file issues at `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
If you find a bug regarding OpenShift client, please file issues at `OpenShift REST Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
kubernetes_scenarios/k8s_intro
kubernetes_scenarios/k8s_inventory
kubernetes_scenarios/k8s_scenarios

50
docs/docsite/rst/scenario_guides/kubernetes_scenarios/k8s_intro.rst
Unescape Escape View File

@ -0,0 +1,50 @@
.. _k8s_ansible_intro:
**************************************
Introduction to Ansible for Kubernetes
**************************************
.. contents::
:local:
Introduction
============
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 :ref:`from_source`.
- `OpenShift Rest Client <https://github.com/openshift/openshift-restclient-python>`_ installed on the host that will execute the modules.
Installation
============
The Kubernetes modules are part of the `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
To install the collection, run the following:
.. code-block:: bash
$ ansible-galaxy collection install community.kubernetes
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.
Reporting an issue
==================
If you find a bug or have a suggestion regarding modules, please file issues at `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
If you find a bug regarding OpenShift client, please file issues at `OpenShift REST Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
If you find a bug regarding Kubectl binary, please file issues at `Kubectl issue tracker <https://github.com/kubernetes/kubectl>`_

95
docs/docsite/rst/scenario_guides/kubernetes_scenarios/k8s_inventory.rst
Unescape Escape View File

@ -0,0 +1,95 @@
.. _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 dynamically 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>`_ and `OpenShift Python client <https://github.com/openshift/openshift-restclient-python>`_
on your control node (the host running Ansible).
.. code-block:: bash
$ pip install kubernetes openshift
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 = community.kubernetes.k8s
Then, create a file that ends in ``.k8s.yml`` or ``.k8s.yaml`` in your working directory.
The ``community.kubernetes.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: community.kubernetes.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: community.kubernetes.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 <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
`OpenShift Python client <https://github.com/openshift/openshift-restclient-python>`_
The GitHub Page of OpenShift Dynamic API client
`OpenShift Python client - Issue Tracker <https://github.com/openshift/openshift-restclient-python/issues>`_
The issue tracker for OpenShift Dynamic API 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

12
docs/docsite/rst/scenario_guides/kubernetes_scenarios/k8s_scenarios.rst
Unescape Escape View File

@ -0,0 +1,12 @@
.. _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

90
docs/docsite/rst/scenario_guides/kubernetes_scenarios/scenario_k8s_object.rst
Unescape Escape View File

@ -0,0 +1,90 @@
.. _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.10 or later must be installed
* The Python modules ``openshift`` and ``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 1.1.0 is going to migrate 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.
.. literalinclude:: task_outputs/Add_a_pod_using_k8s.yaml
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 ``community.kubernetes.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.
.. literalinclude:: task_outputs/Add_a_pod_using_k8s.json
- 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
`OpenShift Python client <https://github.com/openshift/openshift-restclient-python>`_
The GitHub Page of OpenShift Dynamic API client
`OpenShift Python client - Issue Tracker <https://github.com/openshift/openshift-restclient-python/issues>`_
The issue tracker for OpenShift Dynamic API 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

67
docs/docsite/rst/scenario_guides/kubernetes_scenarios/task_outputs/Add_a_pod_using_k8s.json
Unescape Escape View File

@ -0,0 +1,67 @@
{
"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"
}
}
}

20
docs/docsite/rst/scenario_guides/kubernetes_scenarios/task_outputs/Add_a_pod_using_k8s.yaml
Unescape Escape View File

@ -0,0 +1,20 @@
---
- hosts: localhost
collections:
- community.kubernetes
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
Write Preview
Loading…
Cancel
Save