.. _deployment:

Deployments
-----------

A deployment describes how a Docker image is going to be deployed:

 #. The desired number of replicas that should be running
 #. The allowed number of unavailable replicas - used during rolling updates
 #. The strategy for updating container images
 #. Labels to identify the deployment - used by service to attach to the right pods.
 #. Lists environment variables.

Note that this gets the Docker image deployed, but you'll need to create a **service** that becomes
the single endpoint that ties the multiple pods together, and an **ingress** to route requests
based on the URL that the request came in on.

This is an example YAML file for a deployment, which is the suggested way to create a
deployment::

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: tomcat-dev                      # Name of this deployment
    spec:
      replicas: 1                           # Desired number of replicas
      selector:                             # The selector specifies the labels of the
        matchLabels:                        # pods for this replication set
          app: tomcat
          env: dev
      strategy:                             # Indicates the strategy for rolling updates
        type: RollingUpdate
        rollingUpdate:
          maxSurge: 1                       # Max extra nodes while creating updates
          maxUnavailable: 1                 # Max number of nodes that can be down while updating
      minReadySeconds: 5                    # Number of seconds before pod is considered ready
      template:                             # This section describes the pod that will be replicated
        metadata:
          labels:                           # Labels assigned to the pod.  This is useful to find pods by label.
            app: tomcat
            env: dev
        spec:
          containers:
          - name: tomcat                    # A name you give the container for the image.
            image: tomcat:7                 # The Docker image for the container
            ports:
              - containerPort: 8080
            env:                            # Environment variables provided to the container
              - name: DS_URL
                valueFrom:
                  secretKeyRef:             # Here the value is being extracted from secrets.
                    name: tomcat-dev
                    key: url
              - name: DS_USR
                valueFrom:
                  secretKeyRef:
                    name: tomcat-dev
                    key: username
              - name: DS_PWD
                valueFrom:
                  secretKeyRef:
                    name: tomcat-dev
                    key: password


**Note:** The first part of the **spec:** describes the replication strategy.  The second part, **template:**
describes the pod the Docker image will be deployed to.    These two parts are associated
to each other with the **matchLabels** and **labels** section.


Here is an example of a deployment:

.. code-block:: python

    from k9.helper import (
        set_default_namespace,
        create_namespace,
        delete_namespace,
        create_secret,
        delete_secret,
        create_deployment,
        update_deployment_image,
        scale_deployment,
        delete_deployment
    )

    def test_deployments(self):
        try:
            # Create namespace
            set_default_namespace("deployment-unit-test")
            create_namespace()

            # Create secret - you really should query user rather than embed real
            # secrets in your source code.
            secret_name = "tomcat-dev"
            secrets = {
                'url': 'https://some/url',
                'password': 'My1SecretPassword',
                'username': 'postgres'
            }
            create_secret(secret_name, secrets)

            # Create Deployment
            deploy_name = 'tomcat-dev'
            body = read_yaml('../test/tomcat-deploy-dev.yml')
            create_deployment(body)

            # This is an example of updating the deployment to a a later version of
            # Tomcat.  For example, you would run this from Jenkins when building an
            # updated version of your app.
            update_deployment_image(deploy_name, 'tomcat', 'tomcat:8')

            # This is an example of scaling your deployment from 2 to 3 replicas
            spec = {
                'replicas': 3
            }
            scale_deployment(deploy_name, spec)


        finally:
            # This is here to document how you delete these items.
            # Typically, you would not delete this unless you are writing
            # a unit test.
            delete_deployment(deploy_name)
            delete_secret(secret_name)
            delete_namespace()

.. autofunction:: k9.apps.list_deployments
.. autofunction:: k9.apps.deployment_exists
.. autofunction:: k9.apps.get_deployment
.. autofunction:: k9.apps.create_deployment
.. autofunction:: k9.apps.delete_deployment
.. autofunction:: k9.apps.update_deployment_image
.. autofunction:: k9.apps.scale_deployment