Home

Awesome

kube-applier

Project Status Build Status

kube-applier is a service that enables continuous deployment of Kubernetes objects by applying declarative configuration files from a Git repository to a Kubernetes cluster.

kube-applier runs as a Pod in your cluster and watches the Git repo to ensure that the cluster objects are up-to-date with their associated spec files (JSON or YAML) in the repo.

At a specified interval, kube-applier performs a "full run", issuing kubectl apply commands for all JSON and YAML files within the repo.

When a new commit to the repo occurs, kube-applier performs a "quick run", issuing apply commands only for files that have changed since the last run.

Quick runs and full runs are handled separately and concurrently.

kube-applier serves a status page and provides metrics for monitoring.

Requirements

Setup

Download the source code and build the container image.

$ go get github.com/box/kube-applier
$ cd $GOPATH/src/github.com/box/kube-applier
$ make container

You will need to push the image to a registry in order to reference it in a Kubernetes container spec.

Usage

Container Spec

We suggest running kube-applier as a Deployment (see demo/ for example YAML files). We only support running one replica at a time at this point, so there may be a gap in application if the node serving the replica goes hard down until it is rescheduled onto another node.

IMPORTANT: The Pod containing the kube-applier container must be spawned in a namespace that has write permissions on all namespaces in the API Server (e.g. kube-system).

Environment Variables

Required:

Optional:

NOTE The blacklist and whitelist files support line comments. A single line gets ignored if the first non-blank character is # in that line.

Mounting the Git Repository

There are two ways to mount the Git repository into the kube-applier container.

1. Git-sync sidecar container

Git-sync keeps a local directory up to date with a remote repo. The local directory resides in a shared emptyDir volume that is mounted in both the git-sync and kube-applier containers.

Reference the git-sync repo for setup and usage.

2. Host-mounted volume

Mount a Git repository from a host directory. This can be useful when you want kube-applier to apply changes to an object without checking the modified spec file into a remote repo.

"volumes": [
   {
      "hostPath": {
         "path": <path-to-host-directory>
      },
      "name": "repo-volume"
   }
   ...
]

What happens if the contents of the local Git repo change in the middle of a kube-applier run?

If there are changes to files in the $REPO_PATH directory during a kube-applier run, those changes may or may not be reflected in that run, depending on the timing of the changes.

Given that the $REPO_PATH directory is a Git repo or located within one, it is likely that the majority of changes will be associated with a Git commit. Thus, a change in the middle of a run will likely update the HEAD commit hash, which will immediately trigger another run upon completion of the current run (regardless of whether or not any of the changes were effective in the current run). However, changes that are not associated with a new Git commit will not trigger a run.

If I remove a configuration file, will kube-applier remove the associated Kubernetes object?

No. If a file is removed from the $REPO_PATH directory, kube-applier will no longer apply the file, but kube-applier WILL NOT delete the cluster object(s) described by the file. These objects must be manually cleaned up using kubectl delete.

"Force Run" Feature

In rare cases, you may wish to trigger a kube-applier run without checking in a commit or waiting for the next scheduled run (e.g. some of your files failed to apply because of some background condition in the cluster, and you have fixed it since the last run). This can be accomplished with the "Force Run" button on the status page, which starts a run immediately if no run is currently in progress, or queues a run to start upon completion of the current run. Only one run may sit in the queue at any given time.

Monitoring

Status UI

screenshot

kube-applier hosts a status page on a webserver, served at the service endpoint URL. The status page displays information about the most recent apply run, including:

The HTML template for the status page lives in templates/status.html, and static/ holds additional assets.

Metrics

kube-applier uses Prometheus for metrics. Metrics are hosted on the webserver at /metrics (status UI is the index page). In addition to the Prometheus default metrics, the following custom metrics are included:

The Prometheus HTTP API (also see the Go library) can be used for querying the metrics server.

Development

All contributions are welcome to this project. Please review our contributing guidelines.

Some suggestions for running kube-applier locally for development:

Testing

See our contributing guidelines.

Support

Need to contact us directly? Email oss@box.com and be sure to include the name of this project in the subject.

Copyright and License

Copyright 2016 Box, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.