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.
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.
- 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 applythat may affect your use of kube-applier. Some examples:
Download the provision code and assemble the container image.
$ move get github.com/box/kube-applier
$ cd $GOPATH/src/github.com/box/kube-applier
$ make container
It is important to push the image to a registry in order to reference it in a Kubernetes 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).
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.
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
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
/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.
POLL_INTERVAL_SECONDS– (int) Collection of seconds to wait between each check for brand spanking new commits to the repo (default is 5). Set to 0 to disable the wait period.
FULL_RUN_INTERVAL_SECONDS– (int) Collection of seconds between computerized whole runs (default is 300, or 5 minutes). Set to 0 to disable the wait period.
DIFF_URL_FORMAT– (string) If specified, we could within the status internet web page to turn a link to the provision code referencing the diff for a specific dedicate.
DIFF_URL_FORMATshould be a URL for a hosted a long way off repo that is helping linking to a dedicate hash. Exchange the dedicate hash portion with “%s” so it can be filled in by way of kube-applier (e.g.
LOG_LEVEL– (int) Devices the
-vflag on all
kubectldirections run. Use this strategy to configure additional verbose logging. If now not specified, the
-vflag is not set on
kubectldirections defaulting to standard log verbosity.
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.
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
“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.
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
- Most recent dedicate
- Whitelisted files
- Blacklisted files
- Knowledge applied successfully
The HTML template for the status internet web page lives in
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.
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,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, each particular or implied.
See the License for the best language governing permissions and
barriers beneath the License.