kit-deployer

[DEPRECATED] Thanks for using this package, but we will no longer support it.

Use this service to deploy files to multiple Kubernetes clusters. You just have to organize your manifest files into directories that match the names of your clusters (the name defined in your kubeconfig files). Then you just provide a directory of kubeconfig files and the kit-deployer will asynchronously send all manifests up to their corresponding clusters.

There is also support for namespaces. Simply provide a directory with namespaces that are grouped into folders that match the name of the kubeconfig cluster you want them deployed to.

The kit-deployer service was designed to work for a CI type service like Codeship where it can be run as a docker image as part of your automated workflow. However, you can also use it as an npm module or as a CLI tool directly.

Use as Docker Image

docker run quay.io/invision/kit-deployer --help

We recommend using kit components with Codeship's Docker Infrastructure, however you are free to run this tool however way you wish. Anything that has Docker can run this image.

Using as CLI

You can run the ./src/deployer --help to see how it works.

Note this method requires node and was tested on version 5.5.0.

Using as npm module

Use npm to install kit-deployer:

$ npm install kit-deployer --save

Then require it and use it like so:

var Deployer = require("kit-deployer").Deployer;
 
var options = {
    sha: "c6350f4c2709708b8f784408a440030e704b2b9a",
    dryRun: true,
    diff: true,
    github: {
        token: "<OAUTH_TOKEN_HERE>",
        user: "chesleybrown",
        repo: "my-app"
    }
};
 
var deployer = new Deployer(options);
 
// setup logging of events
deployer.on("info", function(message) {
    console.log(message);
});
deployer.on("warn", function(message) {
    console.log(message);
});
deployer.on("error", function(message) {
    console.log(message);
});
deployer.on("fatal", function(message) {
    console.log(message);
});
deployer.on("status", function(status) {
    console.log(status);
});
deployer.on("progress", function(progress) {
    console.log(progress);
});
 
deployer
    .deploy("/configs/**/kubeconfig", "/manifests", "/namespaces")
    .then(console.log)
    .catch(console.error)
    .done();

Note this method requires node and was tested on version 5.5.0.

Progress

The progress event emits whenever a cluster was successfully deployed to or failed deploying. It will tell you how many clusters are left, how many had issues being deployed to and what these clusters were. This is what the object looks like. Information is purposely made redundant for easier logging where needed.

{
  "percent": 0.5,
  "clusters": {
    "total": 4,
    "completed": 2,
    "found": [
      "cluster-1",
      "cluster-2",
      "cluster-3",
      "cluster-4"
    ],
    "remaining": [
      "cluster-2",
      "cluster-3"
    ],
    "successful": [
      "cluster-1",
      "cluster-2"
    ],
    "failed": []
  }
}

Namespaces

To create a Namespace within a given cluster, simply provide the namespace files within a directory matching the name of the cluster. So if you had a cluster called my-cluster, you could place the following contents into a file called ./namespaces/my-cluster/example-namespace.yaml.

apiVersion: v1
kind: Namespace
metadata:
  name: example

Manifests

All manifest files should be placed into directories corresponding to the name of the cluster + namespace they are for. So for example, if you wanted to deploy manifests to a cluster called my-cluster, you could place all the manifest files into ./manifests/my-cluster/**/*.yaml.

Reserved Labels

The following labels are dynamically generated and managed by kit for all manifests. They should not be manually set and if they are an error will be thrown halting the deploy.

• id
• strategy

Required Labels

The following labels must be set on Deployment manifests and on the labels for the pod template within the Deployment manifest.

• name

Supported Types

Currently we only properly support the following types to be used as manifests. Any other type used will not be deployed and will display a warning:

• Deployment
• Job
• Secret
• Service
• DaemonSet
• PersistentVolumeClaim

Order of Deploys (beta)

NOTE: this feature is a work in progress and may not function correctly

By default, all manifests are deployed to a given cluster at the same time. If however you require manifests to be deployed in a specific order you can utilize the "dependency-selector". By specifying a manifest with dependencies on other resources, the deployer will only deploy that manifest once those other services are fully available on the cluster.

You can specify dependencies using a metadata annotation called kit-deployer/dependency-selector. It should be a valid label selector. For example:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: proxy-deployment
  annotations:
    kit-deployer/dependency-selector: database=mongo,env=prod

Supported Dependency Types

Currently we only properly support the following types to be used as dependencies:

• Deployment
• Job
• Secret
• Service

Manifest backup

With BACKUP_ENABLED set to true each manifest will be backed up to the specified S3 bucket with the path /AWS_BUCKET/cluster-name/manifest after the manifest has been deployed. By default files can be backed up as yaml or json format - yaml is the default.

Expected environment variables

The following environment variables are used by this service.

Contributing

See the Contributing guide for steps on how to contribute to this project.