========
idem-k8s
========

Kubernetes provider for Idem

About
=====

Idem plugin to manage Kubernetes resources

What is POP?
------------

This project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based
implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring
together concepts and wisdom from the history of computing in new ways to solve
modern computing problems.

For more information:

* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__
* `pop-awesome <https://gitlab.com/saltstack/pop/pop-awesome>`__
* `pop-create <https://gitlab.com/saltstack/pop/pop-create/>`__

Getting Started
===============

Prerequisites
-------------

* Python 3.6+
* git *(if installing from source, or contributing to the project)*

Installation
------------

.. note::

   If wanting to contribute to the project, and setup your local development
   environment, see the ``CONTRIBUTING.rst`` document in the source repository
   for this project.

If wanting to use ``idem-k8s``, you can do so by either
installing from PyPI or from source.

Install from PyPI
+++++++++++++++++

.. code-block:: bash

      pip install idem-k8s

Install from source
+++++++++++++++++++

.. code-block:: bash

   # clone repo
   git clone git@<your-project-path>/idem-k8s.git
   cd idem-k8s

   # Setup venv
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .

Development
===========

idem-k8s has built-in auto code generation to extend support for additional kubernetes resources.
Kubernetes resource state file can be auto generated by running the following command :

.. code-block:: bash

   pop-create k8s \
   --directory ~/idem_k8s/autogen/dummy \  # directory in which the generated state files are stored
   -tv \
   -n idem_k8s \
   --resource apps/v1/DaemonSet  # resource for which state files are generated

.. note ::
    the resource argument follows the following format - group/version/kind.

    Please refer - https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#-strong-api-groups-strong
    For eg. to add resource state for Deployment, resource argument will be apps/v1/Deployment

The k8s state auto code generation generates over 90% of code required to support a new kubernetes resource.

Usage
=====

Setup
-----------------

After installation, the k8s Idem execution and state modules will be accessible to the pop `hub`.
In order to use them, we need to set up our credentials.

For more information:

* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__
* `pop hub <https://pop-book.readthedocs.io/en/latest/main/hub.html#>`__

Create a new file called `credentials.yaml` and populate it with credentials.
The `default` profile will be picked up automatically by `idem`.

credentials.yaml:

..  code:: sls

    k8s:
      default:
        kube_config_path: ~/.kube/config
        context: default

Next step is to encrypt the credentials file, and add the encryption key and encrypted file
path to the ENVIRONMENT.

Encrypt the credential file:

.. code:: bash

    Idem encrypt credentials.yaml

This will generate a credentials.yaml.fernet file and a command line output token::

    -AXFSEFSSEjsfdG_lb333kVhCVSCDyOFH4eABCDEFNwI=

Add these to your environment:

.. code:: bash

    export ACCT_KEY="-AXFSEFSSEjsfdG_lb333kVhCVSCDyOFH4eABCDEFNwI="
    export ACCT_FILE=$PWD/credentials.yaml.fernet


You are ready to use idem-k8s!!!


States
--------
Idem states are used to make sure resources are in a desired state.
The desired state of a resource can be specified in sls file.
In Idem-k8s, three states are supported: `present`, `absent`, `describe`

present state
+++++++++++++
`present` state makes sure a resource exists in a desired state. If a resource does
not exist, running `present` will create the resource on the provider. If a resource
exists, running `present` will update the resource on the provider.

absent state
++++++++++++
`absent` state makes sure a resource does not exist. If a resource exits, running
`absent` will delete the resource. If a resource does not exist, running `absent`
is a no-operation.

describe state
++++++++++++++
`describe` state lists all the current resources of the same resource type
in the k8s cluster specified in the credential profile.

States can be accessed by their relative location in `idem-k8s/idem_k8s/states`.
For example, in the state sls yaml file below, k8s deployment state can be created with the `present` function.

k8s_deployment.sls:

.. code:: sls

    nginx-deployment:
      k8s.apps.v1.deployment.present:
      - metadata:
          name: nginx-deployment
          namespace: default
      - spec:
          replicas: 3
          selector:
            match_labels:
              app: nginx
          strategy:
            rolling_update:
              max_surge: 25%
              max_unavailable: 25%
            type: RollingUpdate
          template:
            metadata:
              labels:
                app: nginx
            spec:
              containers:
              - image: nginx:1.14.20
                image_pull_policy: IfNotPresent
                name: nginx
                ports:
                - container_port: 80
                  protocol: TCP
                termination_message_path: /dev/termination-log
                termination_message_policy: File
              restart_policy: Always

The state sls file can be executed with:

.. code:: bash

    idem state $PWD/k8s_deployment.sls

Current Supported Resources
++++++++++++++++++++++++++++

apps.v1
"""""""""""""
daemon_set

deployment

core.v1
"""""""""""""
config_map

namespace

secret

service_account

rbac.v1
"""""""""""""""""""""
cluster_role

cluster_role_binding

storage_k8s_io.v1
"""""""""""""""""""""
storage_class
