bg-kube 0.0.10

An interface for automating blue-green deployments using Kubernetes

.. image:: https://img.shields.io/pypi/v/bg-kube.svg
:target: https://pypi.python.org/pypi/bg-kube

.. image:: https://travis-ci.org/stphivos/bg-kube.svg
:target: https://travis-ci.org/stphivos/bg-kube

.. image:: https://codecov.io/github/stphivos/bg-kube/coverage.svg
:target: https://codecov.io/github/stphivos/bg-kube

*******
bg-kube
*******
An interface for automating blue-green deployments on a Kubernetes cluster.

**Please note that this project is in initial development and it's not ready for production use yet.
Use with caution in a test/staging environment.**

Features
========
* Publish/Rollback functions.
* Dynamic variables in YAML configuration files.
* Smoke tests for health checking before promoting a new environment.
* Easily extensible to support multiple cloud providers (other than just GKE and AWS/kops).
* Minimal setup/resources - does not live in the cloud and can be invoked from a CI service like Travis.

Workflow
========
1. Builds and tags a container image from a Dockerfile using ``docker build`` command.
2. Pushes the tagged image to the container registry (GCR and ECR only at this point).
3. Creates a ``Job`` workload for the database migrations (Optional - should be backwards compatible).
4. Creates a ``Deployment`` workload using the new image.
5. Creates a ``Service`` workload for health checking which runs the specified smoke tests command (Optional).
* If the tests were successful, it updates the public ``Service`` workload to point to the new deployment.
* If the tests have failed, the public service remains unaffected.

Installation
============
::

$ pip install bg-kube

Prerequisites
=============

* `Docker <https://docs.docker.com/engine/installation>`_
* `Kubernetes command-line tool <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_

Google Kubernetes Engine
------------
* `Create project <https://console.cloud.google.com/projectcreate>`_
* `Create cluster <https://console.cloud.google.com/kubernetes/add>`_
* `Install SDK <https://cloud.google.com/sdk/downloads>`_
* Login using ``gcloud init``
* Select project using ``gcloud config set project <project-id>``

AWS using kops
--------------
* `Install AWS CLI <http://docs.aws.amazon.com/cli/latest/userguide/installing.html>`_
* `Install kops CLI <https://github.com/kubernetes/kops/blob/master/docs/install.md>`_
* `Setup environment <https://github.com/kubernetes/kops/blob/master/docs/aws.md#setup-your-environment>`_

Minimal configurations example
==============================

Service Config - Public
-----------------------
.. code-block:: yaml

apiVersion: v1
kind: Service
metadata:
annotations:
external-dns.alpha.kubernetes.io/hostname: $DOMAIN_NAME.
labels:
run: $SERVICE_RUN_LABEL
name: $SERVICE_NAME
namespace: default
spec:
ports:
- protocol: TCP
port: $SERVICE_PORT
targetPort: $CONTAINER_PORT
selector:
run: $SERVICE_RUN_LABEL
color: $COLOR
type: pod
type: LoadBalancer


Service Config - Health Checks
------------------------------
.. code-block:: yaml

apiVersion: v1
kind: Service
metadata:
labels:
run: $SERVICE_RUN_LABEL
name: $SMOKE_SERVICE_NAME
namespace: default
spec:
ports:
- protocol: TCP
port: $SERVICE_PORT
targetPort: $CONTAINER_PORT
selector:
run: $SERVICE_RUN_LABEL
color: $COLOR
type: pod
type: LoadBalancer


Deployment Config
-----------------
.. code-block:: yaml

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
labels:
color: $COLOR
run: $SERVICE_RUN_LABEL
name: $DEPLOYMENT_NAME-$COLOR
namespace: default
spec:
replicas: 2
selector:
matchLabels:
color: $COLOR
run: $SERVICE_RUN_LABEL
template:
metadata:
labels:
run: $SERVICE_RUN_LABEL
color: $COLOR
tag: "$TAG"
type: pod
spec:
containers:
- command: ["gunicorn", "django_app.wsgi", "--name", "todoapp", "-b", ":$CONTAINER_PORT"]
env:
- name: ENV
value: $ENV
- name: DB_URL
value: $DB_URL
image: $IMAGE_NAME:$TAG
name: $CONTAINER_NAME
ports:
- containerPort: $CONTAINER_PORT
protocol: TCP

env
---
::

ENV=prod
DB_URL=postgres://user:pass@1.2.3.4:5432/todoapp

IMAGE_NAME=gcr.io/todoapp-12345/todo-api
CONTAINER_PORT=8000
CONTAINER_NAME=cnt-todo-api

PROJECT_NAME=todoapp-12345
CLUSTER_NAME=todoapp-cluster
CLUSTER_ZONE=us-central1-a
DOMAIN_NAME=todoapp.example.com

SERVICE_PORT=80
SERVICE_NAME=svc-todo-api
SERVICE_CONFIG=./config/service.yaml
SERVICE_RUN_LABEL=todo-api

DEPLOYMENT_NAME=dep-todo-api
DEPLOYMENT_CONFIG=./config/deployment.yaml

Publish using
-------------
::

$ bg-kube --env-file .env.prod publish

Future Improvements
===================
* Checks to enforce database migrations are backwards compatible
* Support for more cloud providers
* Better test coverage