This repository has been archived by the owner on Nov 1, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
/
README.md
executable file
·358 lines (285 loc) · 27.4 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
# Flux
Flux is a tool that automatically ensures that the state of a cluster matches the config in git.
It uses an operator in the cluster to trigger deployments inside Kubernetes, which means you don't need a separate CD tool.
It monitors all relevant image repositories, detects new images, triggers deployments and updates the desired running
configuration based on that (and a configurable policy).
## Introduction
This chart bootstraps a [Flux](https://github.com/fluxcd/flux) deployment on
a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
## Prerequisites
Kubernetes >= v1.11
# Git repo
- One repo containing cluster config (i.e., Kubernetes YAMLs)
- Example of a test repo: https://github.com/fluxcd/flux-get-started
## Installation
We put together a simple [Get Started
tutorial](https://fluxcd.io/legacy/flux/tutorials/get-started-helm/) which takes about 5-10 minutes to follow.
You will have a fully working Flux installation deploying workloads to your cluster.
## Installing Flux using Helm
The [configuration](#configuration) section lists all the parameters that can be configured during installation.
### Installing the Chart
Add the Flux repo:
```sh
helm repo add fluxcd https://charts.fluxcd.io
```
#### Install the chart with the release name `flux`
1. Create the flux namespace:
```sh
kubectl create namespace flux
```
1. **Optional** Create and store a deploy key in a Kubernetes secret:
At startup Flux generates a SSH key pair and stores the private key in a Kubernetes secret.
Flux will log the public key at startup and you will then need to add the public key as a
deploy key on your GitHub repository (see below). However, this can be onerous if you're
deploying Flux to multiple clusters from the same repository or installing Flux multiple
times.
If you wish to supply your own deploy key instead, you'll need to create the Kubernetes
secret yourself. You can then set the name and data key of your secret when you start Flux
using Helm in the next step.
> **Note:** Don't check these key files into your Git repository!
```sh
# 1. Generate a SSH key named identity:
ssh-keygen -q -N "" -f ./identity
# 2. Create a Kubernetes secret:
kubectl -n flux create secret generic flux-ssh --from-file=./identity
# 2a. The SSH key will be stored in a data key matching the file name.
# Set the `git.secretDataKey` value to change the data key if
# you want to use a different source file.
# 3. Don't check this key into your Git repository!
# To delete the private key after you've created the secret above:
rm ./identity
# 4. Add the contents of ./identity.pub as a deployment key with write access in your
# Git repo
# 5. Set the git.secretName and git.secretDataKey fields when you call Helm below!
```
1. Replace `fluxcd/flux-get-started` with your own git repository and run helm install:
```sh
helm upgrade -i flux fluxcd/flux \
--set git.url=git@github.com:fluxcd/flux-get-started \
--namespace flux
```
> **Note:** if you've defined your own deploy key secret you must set the secret name and
(optionally) data key as Helm values.
```sh
helm upgrade -i flux fluxcd/flux \
--set git.url=git@github.com:fluxcd/flux-get-started \
--set git.secretName=flux-ssh \
--set git.secretDataKey=deploy-key \
--namespace flux
```
1. Setup Git deploy
> **Note:** this not required if you created your own deploy key or if you're
[using git over HTTPS](#flux-with-git-over-https) as described below.
If you haven't supplied your own deploy key, Flux generates an SSH key and logs the public
key at startup. You can obtain the SSH public key by installing
[fluxctl](https://fluxcd.io/legacy/flux/references/fluxctl/) and running:
```sh
fluxctl identity --k8s-fwd-ns flux
```
In order to sync your cluster state with GitHub you need to copy the
public key and create a deploy key with access on your GitHub
repository. Go to _Settings > Deploy keys_ click on _Add deploy key_,
paste the Flux public key and click _Add key_. If you want Flux to
have write access to your repo, check _Allow write access_; if you
have set `git.readonly=true`, you can leave this box unchecked.
#### Flux with git over HTTPS
By setting the `env.secretName`, all key/value pairs in this secret will
be defined in the Flux container as environment variables. This can be
utilized in combination with Kubernetes feature of [using environment
variables inside of your config](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config)
to securely provide the HTTPS credentials which then can be used in the
`git.url`.
1. Create a personal access token to be used as the `GIT_AUTHKEY`:
- [GitHub](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line)
- [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
- [BitBucket](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
1. Create a secret with your `GIT_AUTHUSER` (the username the token belongs
to) and the `GIT_AUTHKEY` you created in the first step:
```sh
kubectl create secret generic flux-git-auth --namespace flux --from-literal=GIT_AUTHUSER=<username> --from-literal=GIT_AUTHKEY=<token>
```
1. Install Flux:
```sh
helm upgrade -i flux fluxcd/flux \
--set git.url='https://$(GIT_AUTHUSER):$(GIT_AUTHKEY)@github.com/fluxcd/flux-get-started.git' \
--set env.secretName=flux-git-auth \
--namespace flux
```
#### Flux with a private git host
When using a private git host, setting the `ssh.known_hosts` variable
is required for enabling successful key matches because `StrictHostKeyChecking`
is enabled during Flux git daemon operations.
By setting the `ssh.known_hosts` variable, a configmap will be created
called `flux-ssh-config` which in turn will be mounted into a volume named
`sshdir` at `/root/.ssh/known_hosts`.
1. Get the `ssh.known_hosts` keys by running the following command:
```sh
ssh-keyscan <your_git_host_domain>
```
To prevent a potential man-in-the-middle attack, one should
verify the ssh keys acquired through the `ssh-keyscan` match expectations
using an alternate mechanism.
1. Install Flux:
- Using a string for setting `known_hosts`
```sh
YOUR_GIT_HOST=your_git_host.example.com
YOUR_GIT_USER=your_git_user
KNOWN_HOSTS='domain ssh-rsa line1
domain ecdsa-sha2-line2
domain ssh-ed25519 line3'
helm upgrade -i flux fluxcd/flux \
--set git.url="git@${YOUR_GIT_HOST}:${YOUR_GIT_USER}/flux-get-started" \
--set-string ssh.known_hosts="${KNOWN_HOSTS}" \
--namespace flux
```
- Using a file for setting `known_hosts`
Copy `known_hosts` keys into a temporary file `/tmp/flux_known_hosts`
```sh
YOUR_GIT_HOST=your_git_host.example.com
YOUR_GIT_USER=your_git_user
helm upgrade -i flux fluxcd/flux \
--set git.url="git@${YOUR_GIT_HOST}:${YOUR_GIT_USER}/flux-get-started" \
--set-file ssh.known_hosts=/tmp/flux_known_hosts \
--namespace flux
```
#### Connect Flux to a Weave Cloud instance
```sh
helm upgrade -i flux fluxcd/flux \
--set git.url=git@github.com:fluxcd/flux-get-started \
--set token=YOUR_WEAVE_CLOUD_SERVICE_TOKEN \
--namespace flux
```
### Uninstalling the Chart
To uninstall/delete the `flux` deployment:
```sh
helm delete flux
```
The command removes all the Kubernetes components associated with the chart and deletes the release.
You should also remove the deploy key from your GitHub repository.
### Configuration
The following tables lists the configurable parameters of the Flux chart and their default values.
| Parameter | Default | Description
| ----------------------------------------------- | ---------------------------------------------------- | ---
| `image.repository` | `docker.io/fluxcd/flux` | Image repository
| `image.tag` | `<VERSION>` | Image tag
| `replicaCount` | `1` | Number of Flux pods to deploy, more than one is not desirable.
| `image.pullPolicy` | `IfNotPresent` | Image pull policy
| `image.pullSecret` | `None` | Image pull secret
| `logFormat` | `fmt` | Log format (fmt or json)
| `resources.requests.cpu` | `50m` | CPU resource requests for the Flux deployment
| `resources.requests.memory` | `64Mi` | Memory resource requests for the Flux deployment
| `resources.limits` | `None` | CPU/memory resource limits for the Flux deployment
| `nodeSelector` | `{}` | Node Selector properties for the Flux deployment
| `tolerations` | `[]` | Tolerations properties for the Flux deployment
| `affinity` | `{}` | Affinity properties for the Flux deployment
| `extraVolumeMounts` | `[]` | Extra volumes mounts
| `extraVolumes` | `[]` | Extra volumes
| `dnsPolicy` | `` | Pod DNS policy
| `dnsConfig` | `` | Pod DNS config
| `token` | `None` | Weave Cloud service token
| `extraEnvs` | `[]` | Extra environment variables for the Flux pod(s)
| `extraEnvsFrom` | `[]` | Extra environment variables from a list of sources for the Flux pod(s)
| `env.secretName` | `` | Name of the secret that contains environment variables which should be defined in the Flux container (using `envFrom`)
| `rbac.create` | `true` | If `true`, create and use RBAC resources
| `rbac.pspEnabled` | `false` | If `true`, create and use a restricted pod security policy for Flux pod(s)
| `allowedNamespaces` | `[]` | Allow flux to manage resources in the specified namespaces. The namespace flux is deployed in will always be included
| `defaultNamespace` | `""` | The namespace flux should use for resources where a namespace is not specified. If none is provided here, the default namespace in kubeconfig is used
| `serviceAccount.create` | `true` | If `true`, create a new service account
| `serviceAccount.name` | `flux` | Service account to be used
| `serviceAccount.annotations` | `` | Additional Service Account annotations
| `clusterRole.create` | `true` | If `false`, Flux will be restricted to the namespaces given in `allowedNamespaces` and the namespace where it is deployed
| `service.type` | `ClusterIP` | Service type to be used (exposing the Flux API outside of the cluster is not advised)
| `service.createClusterIP` | `true` | If `false` and service type is `ClusterIP` the service will still be created, but without IP address (a.k.a. headless service).
| `service.port` | `3030` | Service port to be used
| `sync.state` | `git` | Where to keep sync state; either a tag in the upstream repo (`git`), or as an annotation on the SSH secret (`secret`)
| `sync.timeout` | `None` | Duration after which sync operations time out (defaults to `1m`)
| `sync.interval` | `<git.pollInterval>` | Controls how often Flux will apply what’s in git, to the cluster, absent new commits (defaults to `git.pollInterval`)
| `git.url` | `None` | URL of git repo with Kubernetes manifests
| `git.readonly` | `false` | If `true`, the git repo will be considered read-only, Flux will not attempt to write to it
| `git.branch` | `master` | Branch of git repo to use for Kubernetes manifests
| `git.path` | `None` | One or more paths within git repo to locate Kubernetes manifests (relative path(s))
| `git.user` | `Weave Flux` | Username to use as git committer
| `git.email` | `support@weave.works` | Email to use as git committer
| `git.setAuthor` | `false` | If set, the author of git commits will reflect the user who initiated the commit and will differ from the git committer.
| `git.signingKey` | `None` | If set, commits will be signed with this GPG key
| `git.verifySignatures` | `false` | If set, the signatures of the sync tag and commits will be verified
| `git.verifySignaturesMode` | `` | If set, takes precendence over verifySignatures and sets which strategy to use for signature verification (one of "all", "none", "first-parent")
| `git.label` | `flux-sync` | Label to keep track of sync progress, used to tag the Git branch
| `git.ciSkip` | `false` | Append "[ci skip]" to commit messages so that CI will skip builds
| `git.pollInterval` | `5m` | Period at which to poll git repo for new commits
| `git.timeout` | `20s` | Duration after which git operations time out
| `git.secretName` | `None` | Kubernetes secret with the SSH private key. Superseded by `helmOperator.git.secretName` if set.
| `git.secretDataKey` | `identity` | The data key in the Kubernetes secret with the SSH private key. Superseded by `helmOperator.git.secretDataKey` if set. Flux will read the SSH private key from this data key in the Kubernetes secret optionally set by the `git.secretName` value above.
| `git.secret.enabled` | `false` | If set and a `.gitsecret` directory exist in the root of the git repository, Flux will execute a `git secret reveal -f` in the working clone before performing any operations
| `git.config.enabled` | `false` | Mount `$HOME/.gitconfig` via Secret into the Flux and HelmOperator Pods, allowing for custom global Git configuration
| `git.config.secretName` | `Computed` | Kubernetes secret with the global Git configuration
| `git.config.data` | `None` | Global Git configuration per [git-config](https://git-scm.com/docs/git-config)
| `podLabels` | `{}` | Additional labels for the Flux pod
| `gpgKeys.secretName` | `None` | Kubernetes secret with GPG keys the Flux daemon should import
| `gpgKeys.configMapName` | `None` | Kubernetes config map with public GPG keys the Flux daemon should import
| `sops.enabled` | `false` | If `true` SOPS support will be enabled
| `ssh.known_hosts` | `None` | The contents of an SSH `known_hosts` file, if you need to supply host key(s)
| `ssh.secret.annotations` | `{}` | Additional secret annotations
| `registry.automationInterval` | `5m` | Period at which to check for updated images
| `registry.rps` | `200` | Maximum registry requests per second per host
| `registry.burst` | `125` | Maximum number of warmer connections to remote and memcache
| `registry.trace` | `false` | Output trace of image registry requests to log
| `registry.insecureHosts` | `None` | Use HTTP rather than HTTPS for the image registry domains
| `registry.cacheExpiry` | `None` | Duration to keep cached image info (deprecated)
| `registry.disableScanning` | `false` | Disable registry scanning completely. Flux will be deployed without memcached
| `registry.excludeImage` | `None` | Do not scan images that match these glob expressions; if empty, 'k8s.gcr.io/*' images are excluded
| `registry.includeImage` | `None` | Scan only images that match these glob expressions; if empty, all images are included
| `registry.useTimestampLabels` | `None` | Allow usage of (RFC3339) timestamp labels from (canonical) image refs that match these glob expressions; if empty, 'index.docker.io/{weaveworks,fluxcd}/*' images are allowed
| `registry.ecr.region` | `None` | Restrict ECR scanning to these AWS regions; if empty, only the cluster's region will be scanned
| `registry.ecr.includeId` | `None` | Restrict ECR scanning to these AWS account IDs; if empty, all account IDs that aren't excluded may be scanned
| `registry.ecr.excludeId` | `602401143452` | Do not scan ECR for images in these AWS account IDs; the default is to exclude the EKS system account
| `registry.ecr.require` | `false` | Refuse to start if the AWS API is not available
| `registry.acr.enabled` | `false` | Mount `azure.json` via HostPath into the Flux Pod, enabling Flux to use AKS's service principal for ACR authentication
| `registry.acr.hostPath` | `/etc/kubernetes/azure.json` | Alternative location of `azure.json` on the host
| `registry.acr.secretName` | `None` | Secret to mount instead of a hostPath
| `registry.dockercfg.enabled` | `false` | Mount `config.json` via Secret into the Flux Pod, enabling Flux to use a custom docker config file
| `registry.dockercfg.secretName` | `None` | Kubernetes secret with the docker config.json, mounted on `/dockercfg/`
| `registry.dockercfg.configFileName` | `/dockercfg/config.json` | Path to the custom docker config.json
| `memcached.enabled` | `true` | Create a memcached deployment and service. When set to `false` you must set an external memcached service.
| `memcached.hostnameOverride` | `None` | Override the hostname to the memcached service. Useful when using memcached deployed separately from this chart.
| `memcached.verbose` | `false` | Enable request logging in memcached
| `memcached.maxItemSize` | `5m` | Maximum size for one item
| `memcached.maxMemory` | `128` | Maximum memory to use, in megabytes
| `memcached.pullSecret` | `None` | Image pull secret
| `memcached.repository` | `memcached` | Image repository
| `memcached.resources` | `None` | CPU/memory resource requests/limits for memcached
| `memcached.securityContext` | [See values.yaml][memcached-reference] | Container security context for memcached
| `memcached.nodeSelector` | `{}` | Node Selector properties for the memcached deployment
| `memcached.tolerations` | `[]` | Tolerations properties for the memcached deployment
| `memcached.priorityClassName` | `""` | The name of the priority class to assign to the memcached pod.
| `kube.externalConfig` | `false` | If enabled, no kubeconfig and env var pointing to the kubeconfig will be created. You need to provide both on your own.
| `kube.config` | [See values.yaml][kubeconfig-ref] | Override for kubectl default config in the Flux pod(s).
| `priorityClassName` | `""` | Set priority class for Flux
| `prometheus.enabled` | `false` | If enabled, adds prometheus annotations to Flux and helmOperator pod(s)
| `prometheus.serviceMonitor.create` | `false` | Set to true if using the Prometheus Operator
| `prometheus.serviceMonitor.interval` | `` | Interval at which metrics should be scraped
| `prometheus.serviceMonitor.namespace` | `` | The namespace where the ServiceMonitor is deployed
| `prometheus.serviceMonitor.additionalLabels` | `{}` | Additional labels to add to the ServiceMonitor
| `syncGarbageCollection.enabled` | `false` | If enabled, fluxd will delete resources that it created, but are no longer present in git (see [garbage collection](https://fluxcd.io/legacy/flux/references/garbagecollection/))
| `syncGarbageCollection.dry` | `false` | If enabled, fluxd won't delete any resources, but log the garbage collection output (see [garbage collection](https://fluxcd.io/legacy/flux/references/garbagecollection/))
| `manifestGeneration` | `false` | If enabled, fluxd will look for `.flux.yaml` and run Kustomize or other manifest generators
| `hostAliases` | `{}` | Additional hostAliases to add to the Flux pod(s). See <https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/>
| `dashboards.enabled` | `false` | If enabled, flux will create a configmap with a dashboard in json that's going to be picked up by grafana (see [sidecar.dashboards.enabled](https://github.com/helm/charts/tree/master/stable/grafana#configuration)). Also remember to set `prometheus.enabled=true` to expose the metrics.
| `dashboards.namespace` | `` | The namespace where the dashboard is deployed, defaults to the installation namespace
| `dashboards.nameprefix` | `flux-dashboards` | The prefix of the generated configmaps
[memcached-ref]: https://github.com/fluxcd/flux/blob/master/chart/flux/values.yaml#L201-L204
[kubeconfig-ref]: https://github.com/fluxcd/flux/blob/master/chart/flux/values.yaml#L232-L244
Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example:
```sh
helm upgrade -i flux fluxcd/flux \
--set git.url=git@github.com:stefanprodan/k8s-podinfo \
--set git.path="deploy/auto-scaling\,deploy/local-storage" \
--namespace flux \
fluxcd/flux
```
### Upgrade
Update Flux version with:
```sh
helm upgrade --reuse-values flux fluxcd/flux \
--set image.tag=1.17.1
```