Skip to main content
Help us improve Python packaging – donate today!

An interface for automating blue-green deployments using Kubernetes

Project Description

.. 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`` 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>`_

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

Arguments
---------
::

positional arguments:
{publish,rollback,build,push}
command_args

optional arguments:
-h, --help: show this help message and exit
-e ENV_FILE, --env-file ENV_FILE: .env file for the options below and application vars in the configs
-c CLUSTER_NAME, --cluster-name CLUSTER_NAME: unique name of the cluster
-z CLUSTER_ZONE, --cluster-zone CLUSTER_ZONE: zone name of the cluster location
-m DOCKER_MACHINE_NAME, --docker-machine-name DOCKER_MACHINE_NAME: name of the docker machine if applicable
--docker-build-args DOCKER_BUILD_ARGS arguments supplied to docker build command separated with spaces
-i IMAGE_NAME, --image-name IMAGE_NAME: name of the container image to build using docker
-s SERVICE_NAME, --service-name SERVICE_NAME: name of the main service intended to serve clients
--service-config SERVICE_CONFIG: config of the main service
--service-timeout SERVICE_TIMEOUT timeout secs to wait for healthy state or return an error
--deployment-config DEPLOYMENT_CONFIG config of the deployment containing the main service pods
--deployment-timeout DEPLOYMENT_TIMEOUT timeout secs to wait for healthy state or return an error
-x CONTEXT, --context CONTEXT: docker context path used to build the container image
-d DOCKERFILE, --dockerfile DOCKERFILE: Dockerfile path
--smoke-service-config SMOKE_SERVICE_CONFIG config of the smoke service lb exposed for health checks
--smoke-tests-command SMOKE_TESTS_COMMAND: shell command to run health checks against the smoke service
--db-migrations-job-config-seed DB_MIGRATIONS_JOB_CONFIG_SEED: job config to populate the database with initial data
--db-migrations-job-timeout DB_MIGRATIONS_JOB_TIMEOUT timeout secs to wait for healthy state or return an error
--db-migrations-status-command DB_MIGRATIONS_STATUS_COMMAND: shell command executed on any of the running deployment pods to return the current migrations status
--db-migrations-apply-command DB_MIGRATIONS_APPLY_COMMAND: shell command executed on any of the running deployment pods to apply the latest migrations generated in the current image
--db-migrations-rollback-command DB_MIGRATIONS_ROLLBACK_COMMAND: shell command executed on any of the running deployment pods with the migrations status command stdout as argument - retrieved before applying migrations, to perform a rollback to that state
--kops-state-store KOPS_STATE_STORE: aws cluster state storage bucket name
--container-registry CONTAINER_REGISTRY: container registry alias or implementation class

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

Release history Release notifications

This version
History Node

0.0.14

History Node

0.0.13

History Node

0.0.12

History Node

0.0.11

History Node

0.0.10

History Node

0.0.9.2

History Node

0.0.9.1

History Node

0.0.9

History Node

0.0.8

History Node

0.0.7

History Node

0.0.6

History Node

0.0.5

History Node

0.0.4

History Node

0.0.3

History Node

0.0.2.2

History Node

0.0.2.1

History Node

0.0.2

History Node

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
bg-kube-0.0.14.tar.gz (13.0 kB) Copy SHA256 hash SHA256 Source None Feb 12, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page