Breaking News

kube-applier is a supplier that permits secure deployment of Kubernetes units by way of 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 units are up-to-date with their similar spec files (JSON or YAML) inside the repo.

At a specified length, kube-applier performs a “whole run”, issuing kubectl apply directions for all JSON and YAML files throughout the repo.

When a brand spanking new come to a decision to the repo occurs, kube-applier performs a “rapid run”, issuing apply directions only for files that have changed given that remaining run.

Speedy runs and full runs are handled one after the other and concurrently.

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


  • Go (1.7+)
  • Docker (17.05+)
  • Kubernetes cluster
    • kube-applier maximum ceaselessly is helping any Kubernetes server unlock, assuming that you are putting in place an appropriate kubectl client in your Dockerfile.
    • The kubectl style specified inside the Dockerfile must be each the identical minor unlock since the cluster API server, or one unlock behind the server (e.g. client 1.3 and server 1.4 is fine, on the other hand client 1.4 and server 1.3 is not).
    • There are a selection of identified problems with kubectl apply that may affect your use of kube-applier. Some examples:
      • Releases previous to no less than one.6.0 are subject many identified issues with using kubectl apply to make use of ThirdPartyResource units.
      • 1.5 and 1.6 releases forward of one.5.8 and 1.6.3 don’t seem to be supported as a result of an issue with namespaces, fastened proper right here.


Download the provision code and assemble the container image.

$ move get
$ cd $GOPATH/src/
$ make container

It is important to push the image to a registry in order to reference it in a Kubernetes container spec.


Container Spec

We propose running kube-applier as a Deployment (see demo/ for example YAML files). We most straightforward support running one copy at a time at this stage, so there may be a gap in software if the node serving the copy goes hard down until it is rescheduled onto every other node.

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

Environment Variables


  • REPO_PATH – (string) Absolute path to the record containing configuration files to be applied.
    It’s going to should be a Git repository or a path
    within of 1. All .json and .yaml files inside this record (and its
    subdirectories) may also be applied, till listed on the blacklist or excluded
    from the whitelist.
  • LISTEN_PORT – (int) Port for the container. This should be the identical port specified inside the container spec.

Not obligatory:

  • SERVER – (string) Care for of the Kubernetes API server. Via default, discovery of the API server is handled by way of kube-proxy. If kube-proxy is not organize, the API server take care of must be specified with this setting variable (which is then written proper right into a kubeconfig file on the backend). Authentication to the API server is handled by way of supplier account tokens. See Getting access to the Cluster for more info.
  • BLACKLIST_PATH – (string) Path to a “blacklist” file which specifies files
    that are meant to now not be applied. This path should be absolute (e.g.
    /k8s/conf/kube_applier_blacklist), now not relative to REPO_PATH (even if
    it is conceivable you can want to check the blacklist file into the repo). The blacklist file
    itself should be a plaintext file, with a file path on each line. Each of
    the ones paths should be relative to REPO_PATH (for example, if REPO_PATH is
    set to /git/repo, and the file to be blacklisted is
    /git/repo/apps/app1.json, the street inside the blacklist file should be
  • WHITELIST_PATH – (string) Path to a “whitelist” file which is used to
    make the applier believe a specific subset of files from the repo.
    Best the files listed inside the whitelist file may also be considered for apply.
    Empty whitelist (or unset env var) means all files in repo are eligible to be applied.
    In case of a file is listed in each and every the whitelist and the blacklist, the file is
    now not applied.
    The environment variable and file itself should formatted the identical as for the blacklist above.

The blacklist and whitelist files support line comments.
A single line gets lost sight of if the main non-blank personality is # in that line.

Mounting the Git Repository

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

1. Git-sync sidecar container

Git-sync keeps an area record up to date with a distant repo. The local record resides in a shared emptyDir amount that is fixed in each and every the git-sync and kube-applier boxes.

Reference the git-sync repo for setup and usage.

2. Host-mounted amount

Mount a Git repository from a host record. This may also be useful when you want kube-applier to make use of changes to an object without checking the modified spec file proper into a distant repo.

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

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

If there are changes to files inside the $REPO_PATH record right through a kube-applier run, those changes would in all probability or is probably not reflected in that run, depending on the timing of the changes.

Given that the $REPO_PATH record is a Git repo or located within of 1, it is most likely that the majority of changes may also be associated with a Git dedicate. Thus, a change all through a run will most likely exchange the HEAD dedicate hash, which is able to instantly reason every other run upon of entirety of the current run (without reference to whether or not or no longer or now not any of the changes had been environment friendly inside the provide run). Alternatively, changes that don’t seem to be associated with a brand spanking new Git dedicate may not reason a run.

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

No. If a file is removed from the $REPO_PATH record, kube-applier is not going to apply the file, on the other hand kube-applier WILL NOT delete the cluster object(s) described by way of the file. The ones units must be manually cleaned up using kubectl delete.

“Pressure Run” Serve as

In unusual cases, it is conceivable you will want to reason a kube-applier run without checking in a dedicate or taking a look ahead to the next scheduled run (e.g. a couple of of your files failed to make use of because of some background scenario inside the cluster, and you have got fastened it given that remaining run). This may also be completed with the “Pressure Run” button on the status internet web page, which starts a run instantly if no run is at the present time in construction, or queues a run to start out out upon of entirety of the current run. Only one run would in all probability take a seat down inside the queue at any given time.


Status UI

kube-applier hosts a status internet web page on a webserver, served at the supplier endpoint URL. The status internet web page displays information about the most recent apply run, in conjunction with:

  • Run Kind
  • Get began and end events
  • Latency
  • Most recent dedicate
  • Whitelisted files
  • Blacklisted files
  • Errors
  • Knowledge applied successfully

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


kube-applier uses Prometheus for metrics. Metrics are hosted on the webserver at /metrics (status UI is the index internet web page). At the side of the Prometheus default metrics, the following custom designed metrics are built-in:

  • run_latency_seconds – A Summary that keeps apply of the sessions of each apply run, tagged with the run type and a boolean for whether or not or no longer or now not the run was a excellent fortune (i.e. no failed apply makes an try).
  • file_apply_count – A Counter for each file that has had an apply attempt over the lifetime of the container, incremented with each apply attempt and tagged by way of the filepath and the result of the attempt.

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


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

Some guidelines for running kube-applier in the community for development:

  • To succeed in kube-applier’s webserver from your browser, you are able to use an apiserver proxy URL.
  • Even though git-sync is actually useful for are living environments, using a host-mounted amount can simplify elementary local usage of kube-applier.


See our contributing guidelines.


Want to contact us in an instant? Email correspondence [email protected] and consider to return with the identify of this project inside the subject.

Copyright and License

Copyright 2016 Box, Inc. All rights reserved.

Licensed beneath the Apache License, Fashion 2.0 (the “License”);
you may not use this file except for in compliance with the License.
You might want to obtain a reproduction of the License at

With the exception of required by way of suitable regulation or agreed to in writing, tool
allocated beneath the License is allocated on an “AS IS” BASIS,
See the License for the best language governing permissions and
barriers beneath the License.

Leave a Reply

Your email address will not be published.

Donate Us