mirror of https://github.com/ansible/ansible.git
k8s: Migrated scenario guides to collection (#75249)
Kubernetes scenario guides are moved to ``kubernetes.core`` collection. Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>pull/76582/head
Abhijeet Kasurde
3 years ago
committed by
GitHub
parent
ee777567bc
commit
601d66c7e5
@ -0,0 +1,3 @@
|
||||
---
|
||||
minor_changes:
|
||||
- k8s - scenario guides for kubernetes migrated to ``kubernetes.core`` collection.
|
||||
@ -1,18 +0,0 @@
|
||||
.. _k8s_ansible:
|
||||
|
||||
****************
|
||||
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
|
||||
@ -1,50 +0,0 @@
|
||||
.. _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/kubernetes.core>`_.
|
||||
|
||||
To install the collection, run the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy collection install kubernetes.core
|
||||
|
||||
|
||||
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/kubernetes.core>`_.
|
||||
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>`_
|
||||
@ -1,95 +0,0 @@
|
||||
.. _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 = 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 <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
|
||||
@ -1,12 +0,0 @@
|
||||
.. _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
|
||||
@ -1,90 +0,0 @@
|
||||
.. _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 ``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.
|
||||
|
||||
.. 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
|
||||
@ -1,67 +0,0 @@
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
- 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
|
||||
Loading…
Reference in New Issue