Readme.md 10.8 KB
Newer Older
Ulf Seltmann's avatar
Ulf Seltmann committed
1
2
3
4
5
6
7
8
9
10
# deployer

A tool simplifying image building and deploying utilising docker, kubectl and helm.
The tool tailors the commands according to the [Workflow of University Library of Leipzig] for creating official docker images and deploying to alpha- staging- and production environments.

# Usage

The tool is bundled with docker, kubectl and helm into a docker image itself. You can use it like this:

```
Ulf Seltmann's avatar
Ulf Seltmann committed
11
docker run --rm --volume $PWD:/app ubleipzig/deployer:latest deployer build --build-arg http_proxy=http://proxy.example.com:3128 --output image.tar.gz
Ulf Seltmann's avatar
Ulf Seltmann committed
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
```
_the working directory inside the container is `/app`, so make sure to bind local files there._

## deployer build

This command builds an image from local context. You can set multiple `--build-arg` options mainly used for providing proxy-environment variables such as `HTTP_PROXY`, `http_proxy`, ...

The
See [Advanced Configuration] for more information.

```
$ deployer build --build-arg http_proxy=http://proxy.example.com:3128 --output image.tar.gz
```
_builds image and saves it to file `image.tar.gz`_

## deployer publish

This command publishes an image provided as `tar.gz`-file to [Docker-Hub]. The credentials are provided as file content of dockers config-file located by default under `~/.docker/config.json`

```
$ deployer publish --docker-config "$(cat ~/.docker/config.json)" --input image.tar.gz --name example/image --tag latest --tag 1.0 --tag 1
```
_publishes the image from `image.tar.gz` to [Docker-Hub] as *example/image:latest*, *example/image:1.0* and *example/image:1*_

## deployer deploy

This command deploys a helm-chart to a kubernetes cluster. The credentials are provided by the cluster-admin as well as the namespace and the service-account.

```
$ deployer deploy \
	--namespace example_namespace \
	--cluster-url https://k8s-cluster.example.com:6443 \
	--certificate-authority "$base64_encoded_cacert" \
	--token "$base64_encoded_bearer_token" \
	--name example-staging \
Ulf Seltmann's avatar
Ulf Seltmann committed
47
	--charts ./helmcharts
Ulf Seltmann's avatar
Ulf Seltmann committed
48
49
50
51
52
53
54
```
*deploys helm-charts found at `./helmcharts` to namespace *example_namespace**

Depending on existing deployment with the same name either an installation or an upgrade is performed.

Upgrades always recreate the pods. If the image is pulled depends on `imagePullPolicy` of the container specs.

Ulf Seltmann's avatar
Ulf Seltmann committed
55
56
57
58
59
60
61
62
63
64
## deployer undeploy

This command undeploys a deployment from a kubernetes cluster. The credentials are provided by the cluster-admin as well as the namespace and the service-account.

```
$ deployer undeploy \
	--namespace example_namespace \
	--cluster-url https://k8s-cluster.example.com:6443 \
	--certificate-authority "$base64_encoded_cacert" \
	--token "$base64_encoded_bearer_token" \
Ulf Seltmann's avatar
Ulf Seltmann committed
65
	--name example-staging
Ulf Seltmann's avatar
Ulf Seltmann committed
66
67
68
```
*undeploys deployment named *example-staging* from  namespace *example_namespace**

Ulf Seltmann's avatar
Ulf Seltmann committed
69
70
71
72
73
74
75
76
77
78
79
80
81
## deployer add-repo

This command adds a public repository of helm-charts to choose from. The credentials are provided by the cluster-admin as well as the namespace and the service-account.

```
$ deployer deploy \
	--namespace example_namespace \
	--cluster-url https://k8s-cluster.example.com:6443 \
	--certificate-authority "$base64_encoded_cacert" \
	--token "$base64_encoded_bearer_token" \
	--name incubator \
	--repo-url https://kubernetes-charts-incubator.storage.googleapis.com/
```
Ulf Seltmann's avatar
Ulf Seltmann committed
82
*adds the* incubator *repository with the url https://kubernetes-charts-incubator.storage.googleapis.com/*
Ulf Seltmann's avatar
Ulf Seltmann committed
83
84
85

From now on charts located in this repository can be deployed by using the `--charts` option and providing the chart prefixed by `incubator/`.

Ulf Seltmann's avatar
Ulf Seltmann committed
86
87
# Advanced Configuration

Ulf Seltmann's avatar
Ulf Seltmann committed
88
89
## docker init

Ulf Seltmann's avatar
Ulf Seltmann committed
90
91
92
93
94
95
* `--docker-config`: sets the content of the file `~/.docker/config.json` which is used by docker to authenticate to the registry. This can contain multiple registry-servers and there credentials. Which registry is used depends on the image name.
* `--cluster-url`: sets the url to the kube-apiserver. This URL is provided by the k8s-admin.
* `--certificate-authority`: sets the certificate-authority certificate as base64-encoded string. This string is provided by the k8s-admin
* `--token`: sets the bearer token of the service-account as bas64-encoded string. This string is provided by the k8s-admin.
* `--namespace`: sets the k8s-namespace where the deployment is located. This string is provided by the k8s-admin.
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
96
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
97

Ulf Seltmann's avatar
Ulf Seltmann committed
98
99
## docker build

Ulf Seltmann's avatar
Ulf Seltmann committed
100
* `--docker-config`: sets the content of the file `~/.docker/config.json` which is used by docker to authenticate to the registry. This can contain multiple registry-servers and there credentials. Which registry is used depends on the image name.
Ulf Seltmann's avatar
Ulf Seltmann committed
101
* `--build-arg`: used to provide build-arguments do `docker build`-command. This is mainly used for `HTTP_PROXY`/`http_proxy`: When you specify `--build-arg HTTP_PROXY=...` the tool adds the build argument `--build-arg http_proxy=...` as well, so lower-case proxy-variables are provided automatically. Nevertheless can you use this option to provide your own build-arguments within the `Dockerfile`
Ulf Seltmann's avatar
Ulf Seltmann committed
102
* `--output`: sets the filepath to the file where the built image is saved. If omitted the image is not saved to a file. Also the script trys to import an eventually existing file prior to building in order to make usage of its layers as build-cache.
103
* `--build-context`: sets the build-context for `docker build` to a custom path. If omitted the path where the command is invoked is used.
Ulf Seltmann's avatar
Ulf Seltmann committed
104
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
105
* `--image-name`: sets the image name in the local docker-registry. Can be useful for following builds to build upon existing builds
106
* `--docker-file`: sets the path to the Dockerfile
Ulf Seltmann's avatar
Ulf Seltmann committed
107
108
* `--pull`: tells docker to always pull newer images before building
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
109
110
111

## docker publish

112
* `--input`: sets the filepath to the file from where the image is loaded
Ulf Seltmann's avatar
Ulf Seltmann committed
113
114
* `--docker-config`: sets the content of the file `~/.docker/config.json` which is used by docker to authenticate to the registry. This can contain multiple registry-servers and there credentials. Which registry is used depends on the image name.
* `--name`: sets the name of the image. If you do not wish to publish to [Docker-Hub], you have to specify a server, e.g. `registry.example.com/my-image`. **Be aware that you need to provide credentials in your docker-config if the registry requires authentication.
115
* `--tag`: sets the tags of the image. Provide multiple `--tag`-options if you wish to tag an image with multiple tags.
Ulf Seltmann's avatar
Ulf Seltmann committed
116
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
117
* `--image-name`: specifys the image name in the local docker-registry to publish
Ulf Seltmann's avatar
Ulf Seltmann committed
118
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
119
120
121
122
123
124
125

## docker deploy

* `--cluster-url`: sets the url to the kube-apiserver. This URL is provided by the k8s-admin.
* `--certificate-authority`: sets the certificate-authority certificate as base64-encoded string. This string is provided by the k8s-admin
* `--token`: sets the bearer token of the service-account as bas64-encoded string. This string is provided by the k8s-admin.
* `--namespace`: sets the k8s-namespace where the deployment is located. This string is provided by the k8s-admin.
Ulf Seltmann's avatar
Ulf Seltmann committed
126
* `--name`: sets the name of the deployment.
Ulf Seltmann's avatar
Ulf Seltmann committed
127
* `--charts`: sets the path where the helm-charts reside or the public chart e.g. `stable/maridb`.
Ulf Seltmann's avatar
Ulf Seltmann committed
128
* `--values`: overrides the values from `Values.yaml` in the helm-charts with values in the specified YAML file. May be provided multiple times.
Ulf Seltmann's avatar
Ulf Seltmann committed
129
130
* `--set`: overrides the values from `Values.yaml` in the helm-charts. Provide multiple `--set`-options if you want to provide multiple overrides.
* `--set-string`: overrides the values from `Values.yaml` in the helm-charts as string. Provide multiple `--set-string`-options if you want to provide multiple overrides.
131
* `--timeout`: sets the timeout for helm. defaults to `120s` seconds. String has to be a pattern of [GoLang duration](https://golang.org/pkg/time/#ParseDuration). 
Ulf Seltmann's avatar
Ulf Seltmann committed
132
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
133
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
134
135
136
137
138
139
140
141

## docker undeploy

* `--cluster-url`: sets the url to the kube-apiserver. This URL is provided by the k8s-admin.
* `--certificate-authority`: sets the certificate-authority certificate as base64-encoded string. This string is provided by the k8s-admin
* `--token`: sets the bearer token of the service-account as bas64-encoded string. This string is provided by the k8s-admin.
* `--namespace`: sets the k8s-namespace where the deployment is located. This string is provided by the k8s-admin.
* `--name`: sets the name of the deployment.
Ulf Seltmann's avatar
Ulf Seltmann committed
142
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
143
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
144

Ulf Seltmann's avatar
Ulf Seltmann committed
145
146
147
148
149
150
151
152
## docker add-repo

* `--cluster-url`: sets the url to the kube-apiserver. This URL is provided by the k8s-admin.
* `--certificate-authority`: sets the certificate-authority certificate as base64-encoded string. This string is provided by the k8s-admin
* `--token`: sets the bearer token of the service-account as bas64-encoded string. This string is provided by the k8s-admin.
* `--namespace`: sets the k8s-namespace where the deployment is located. This string is provided by the k8s-admin.
* `--name`: sets the name of the repo to add.
* `--repo-url`: sets the repository-url of the repo to add.
Ulf Seltmann's avatar
Ulf Seltmann committed
153
* `--reset`: this ignores eventually existing config-folders of docker, helm and kubectl and removes them.
Ulf Seltmann's avatar
Ulf Seltmann committed
154
* `--debug`: outputs executed commands
Ulf Seltmann's avatar
Ulf Seltmann committed
155

Ulf Seltmann's avatar
Ulf Seltmann committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
# Assumptions

This tool makes a few assumptions in order to simplify  usage respecting the workflow and cluster-configuration principals if University Library Leipzig

## One service account per namespace

Namespaces are used to separate a project deployment from another. Each namespace is unique per project per deployment i.e. *website-alpha*, *website-staging* and *website-production*.

The rights of a service account are bound to a namespace, therefore each namespace has its own service account which is allowed to apply deployments in it.

By this we are able to publish the credentials of uncritical deployments such as *alpha* and *staging* to developers, so they can independently deploy their features. The credentials of critical deployments such as *production* are restricted to maintainers which are held responsible for their deployments.

## Helmchart location

Each project consists of one or more applications which are deployed together in the projects deployment-environment. Each application is responsible for its own components and defines it via helm charts located in the application repository. For consistency this folders should be named `helmchart`.

[Workflow of University Library of Leipzig]: https://git.sc.uni-leipzig.de/ubl/git-test/wikis/home
[Advanced Configuration]: #Advanced-Configuration
[Docker-Hub]: https://hub.docker.com/u/ubleipzig/dashboard/