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
: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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
bg-kube-0.0.14.tar.gz
(13.0 kB
view details)
File details
Details for the file bg-kube-0.0.14.tar.gz
.
File metadata
- Download URL: bg-kube-0.0.14.tar.gz
- Upload date:
- Size: 13.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2cfdd7eba0e5a6c441e6c4104a5f7def6cb780e2948d469db850833a91db57ec |
|
MD5 | 9e3098129905bad10f159fd2a1226d87 |
|
BLAKE2b-256 | 9446afed37550cd272170d951ca121d182eabf8951db9a209df0078693a6e8cb |