Skip to content
This repository has been archived by the owner on Feb 9, 2021. It is now read-only.

Commit

Permalink
Merge pull request #30 from KyleMartin901/documentation/readme
Browse files Browse the repository at this point in the history 
Update README links to fluxcd
  • Loading branch information
@stefanprodan
stefanprodan authored Aug 13, 2019
2 parents f9bd0da + df12f8c commit 0c5f0ec
Showing 1 changed file with 63 additions and 61 deletions.
124 changes: 63 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,26 @@

**What is GitOps?**

GitOps is a way to do Continuous Delivery, it works by using Git as a source of truth for declarative infrastructure and workloads.
GitOps is a way to do Continuous Delivery, it works by using Git as a source of truth for declarative infrastructure and workloads.
For Kubernetes this means using `git push` instead of `kubectl create/apply` or `helm install/upgrade`.

In a traditional CICD pipeline, CD is an implementation extension powered by the
continuous integration tooling to promote build artifacts to production.
In the GitOps pipeline model, any change to production must be committed in source control
(preferable via a pull request) prior to being applied on the cluster.
This way rollback and audit logs are provided by Git.
If the entire production state is under version control and described in a single Git repository, when disaster strikes,
In a traditional CICD pipeline, CD is an implementation extension powered by the
continuous integration tooling to promote build artifacts to production.
In the GitOps pipeline model, any change to production must be committed in source control
(preferable via a pull request) prior to being applied on the cluster.
This way rollback and audit logs are provided by Git.
If the entire production state is under version control and described in a single Git repository, when disaster strikes,
the whole infrastructure can be quickly restored from that repository.

To better understand the benefits of this approach to CD and what the differences between GitOps and
To better understand the benefits of this approach to CD and what the differences between GitOps and
Infrastructure-as-Code tools are, head to the Weaveworks website and read [GitOps - What you need to know](https://www.weave.works/technologies/gitops/) article.

In order to apply the GitOps pipeline model to Kubernetes you need three things:
In order to apply the GitOps pipeline model to Kubernetes you need three things:

* a Git repository with your workloads definitions in YAML format, Helm charts and any other Kubernetes custom resource that defines your cluster desired state (I will refer to this as the *config* repository)
* a container registry where your CI system pushes immutable images (no *latest* tags, use *semantic versioning* or git *commit sha*)
* an operator that runs in your cluster and does a two-way synchronization:
* watches the registry for new image releases and based on deployment policies updates the workload definitions with the new image tag and commits the changes to the config repository
* watches the registry for new image releases and based on deployment policies updates the workload definitions with the new image tag and commits the changes to the config repository
* watches for changes in the config repository and applies them to your cluster

I will be using GitHub to host the config repo, Docker Hub as the container registry and Flux as the GitOps Kubernetes Operator.
Expand All @@ -30,16 +30,16 @@ I will be using GitHub to host the config repo, Docker Hub as the container regi

### Install Helm and Tiller

If you don't have Helm CLI installed, on macOS you can use `brew install kubernetes-helm`.
If you don't have Helm CLI installed, on macOS you can use `brew install kubernetes-helm`.

Create a service account and a cluster role binding for Tiller:
Create a service account and a cluster role binding for Tiller:

```bash
kubectl -n kube-system create sa tiller

kubectl create clusterrolebinding tiller-cluster-rule \
--clusterrole=cluster-admin \
--serviceaccount=kube-system:tiller
--serviceaccount=kube-system:tiller
```

Note that on GKE you need to create an admin cluster user for yourself:
Expand All @@ -58,10 +58,10 @@ helm init --skip-refresh --upgrade --service-account tiller

### Install Flux

The first step in automating Helm releases with [Flux](https://github.com/weaveworks/flux) is to create a Git repository with your charts source code.
The first step in automating Helm releases with [Flux](https://github.com/fluxcd/flux) is to create a Git repository with your charts source code.
You can fork this repository and use it as a template for your cluster config.

*If you fork, update the release definitions with your Docker Hub repository and GitHub username located in
*If you fork, update the release definitions with your Docker Hub repository and GitHub username located in
\releases\(dev/stg/prod)\podinfo.yaml in your master branch before proceeding.

Apply the Helm Release CRD:
Expand All @@ -76,8 +76,8 @@ Add the Flux chart repo:
helm repo add fluxcd https://charts.fluxcd.io
```

Install Flux and its Helm Operator by specifying your fork URL
(replace `fluxcd` with your GitHub username):
Install Flux and its Helm Operator by specifying your fork URL
(replace `fluxcd` with your GitHub username):

```bash
helm install --name flux \
Expand All @@ -88,24 +88,24 @@ helm install --name flux \
fluxcd/flux
```

The Flux Helm operator provides an extension to Flux that automates Helm Chart releases for it.
The Flux Helm operator provides an extension to Flux that automates Helm Chart releases for it.
A Chart release is described through a Kubernetes custom resource named HelmRelease.
The Flux daemon synchronizes these resources from git to the cluster,
The Flux daemon synchronizes these resources from git to the cluster,
and the Flux Helm operator makes sure Helm charts are released as specified in the resources.

Note that Flux Helm Operator works with Kubernetes 1.9 or newer.
Note that Flux Helm Operator works with Kubernetes 1.9 or newer.

At startup Flux generates a SSH key and logs the public key.
At startup Flux generates a SSH key and logs the public key.
Find the SSH public key with:

```bash
kubectl -n flux logs deployment/flux | grep identity.pub | cut -d '"' -f2
```

In order to sync your cluster state with Git you need to copy the public key and
In order to sync your cluster state with Git you need to copy the public key and
create a **deploy key** with **write access** on your GitHub repository.

Open GitHub, navigate to your fork, go to _Setting > Deploy keys_ click on _Add deploy key_, check
Open GitHub, navigate to your fork, go to _Setting > Deploy keys_ click on _Add deploy key_, check
_Allow write access_, paste the Flux public key and click _Add key_.

### GitOps pipeline example
Expand All @@ -132,7 +132,7 @@ The config repo has the following structure:
└── podinfo.yaml
```

I will be using [podinfo](https://github.com/stefanprodan/podinfo) to demonstrate a full CI/CD pipeline including promoting releases between environments.
I will be using [podinfo](https://github.com/stefanprodan/podinfo) to demonstrate a full CI/CD pipeline including promoting releases between environments.

I'm assuming the following Git branching model:
* dev branch (feature-ready state)
Expand All @@ -141,7 +141,7 @@ I'm assuming the following Git branching model:

When a PR is merged in the dev or stg branch will produce a immutable container image as in `repo/app:branch-commitsha`.

Inside the *hack* dir you can find a script that simulates the CI process for dev and stg.
Inside the *hack* dir you can find a script that simulates the CI process for dev and stg.
The *ci-mock.sh* script does the following:
* pulls the podinfo source code from GitHub
* generates a random string and modifies the code
Expand All @@ -166,12 +166,12 @@ Step 15/15 : CMD ["./podinfo"]
Successfully built 71bee4549fb2
Successfully tagged stefanprodan/podinfo:dev-kb9lm91e
The push refers to repository [docker.io/stefanprodan/podinfo]
36ced78d2ca2: Pushed
36ced78d2ca2: Pushed
```

Inside the *charts* directory there is a podinfo Helm chart.
Inside the *charts* directory there is a podinfo Helm chart.
Using this chart I want to create a release in the `dev` namespace with the image I've just published to Docker Hub.
Instead of editing the `values.yaml` from the chart source, I create a `HelmRelease` definition (located in /releases/dev/podinfo.yaml):
Instead of editing the `values.yaml` from the chart source, I create a `HelmRelease` definition (located in /releases/dev/podinfo.yaml):

```yaml
apiVersion: flux.weave.works/v1beta1
Expand Down Expand Up @@ -204,50 +204,50 @@ Flux Helm release fields:
The options specified in the HelmRelease `spec.values` will override the ones in `values.yaml` from the chart source.

With the `flux.weave.works` annotations I instruct Flux to automate this release.
When a new tag with the prefix `dev` is pushed to Docker Hub, Flux will update the image field in the yaml file,
will commit and push the change to Git and finally will apply the change on the cluster.
When a new tag with the prefix `dev` is pushed to Docker Hub, Flux will update the image field in the yaml file,
will commit and push the change to Git and finally will apply the change on the cluster.

![gitops-automation](https://github.com/stefanprodan/openfaas-flux/blob/master/docs/screens/flux-helm-image-update.png)

When the `podinfo-dev` HelmRelease object changes inside the cluster,
Kubernetes API will notify the Flux Helm Operator and the operator will perform a Helm release upgrade.
When the `podinfo-dev` HelmRelease object changes inside the cluster,
Kubernetes API will notify the Flux Helm Operator and the operator will perform a Helm release upgrade.

```
$ helm history podinfo-dev

REVISION UPDATED STATUS CHART DESCRIPTION
REVISION UPDATED STATUS CHART DESCRIPTION
1 Fri Jul 20 16:51:52 2018 SUPERSEDED podinfo-0.2.0 Install complete
2 Fri Jul 20 22:18:46 2018 DEPLOYED podinfo-0.2.0 Upgrade complete
```
The Flux Helm Operator reacts to changes in the HelmRelease collection but will also detect changes in the charts source files.
If I make a change to the podinfo chart, the operator will pick that up and run an upgrade.
If I make a change to the podinfo chart, the operator will pick that up and run an upgrade.
![gitops-chart-change](https://github.com/stefanprodan/openfaas-flux/blob/master/docs/screens/flux-helm-chart-update.png)
```
$ helm history podinfo-dev

REVISION UPDATED STATUS CHART DESCRIPTION
REVISION UPDATED STATUS CHART DESCRIPTION
1 Fri Jul 20 16:51:52 2018 SUPERSEDED podinfo-0.2.0 Install complete
2 Fri Jul 20 22:18:46 2018 SUPERSEDED podinfo-0.2.0 Upgrade complete
3 Fri Jul 20 22:39:39 2018 DEPLOYED podinfo-0.2.1 Upgrade complete
```
Now let's assume that I want to promote the code from the `dev` branch into a more stable environment for others to test it.
I would create a release candidate by merging the podinfo code from `dev` into the `stg` branch.
Now let's assume that I want to promote the code from the `dev` branch into a more stable environment for others to test it.
I would create a release candidate by merging the podinfo code from `dev` into the `stg` branch.
The CI would kick in and publish a new image:
```bash
$ cd hack && ./ci-mock.sh -r stefanprodan/podinfo -b stg
Successfully tagged stefanprodan/podinfo:stg-9ij63o4c
The push refers to repository [docker.io/stefanprodan/podinfo]
8f21c3669055: Pushed
8f21c3669055: Pushed
```

Assuming the staging environment has some sort of automated load testing in place,
I want to have a different configuration than dev:
Assuming the staging environment has some sort of automated load testing in place,
I want to have a different configuration than dev:

```yaml
apiVersion: flux.weave.works/v1beta1
Expand All @@ -274,7 +274,7 @@ spec:
memory: 128Mi
```
With Flux Helm releases it's easy to manage different configurations per environment.
With Flux Helm releases it's easy to manage different configurations per environment.
When adding a new option in the chart source make sure it's turned off by default so it will not affect all environments.
If I want to create a new environment, let's say for hotfixes testing, I would do the following:
Expand All @@ -288,7 +288,7 @@ If I want to create a new environment, let's say for hotfixes testing, I would d

For production, instead of tagging the images with the Git commit, I will use [Semantic Versioning](https://semver.org).

Let's assume that I want to promote the code from the `stg` branch into `master` and do a production release.
Let's assume that I want to promote the code from the `stg` branch into `master` and do a production release.
After merging `stg` into `master` via a pull request, I would cut a release by tagging `master` with version `0.4.10`.

When I push the git tag, the CI will publish a new image in the `repo/app:git_tag` format:
Expand All @@ -298,7 +298,7 @@ $ cd hack && ./ci-mock.sh -r stefanprodan/podinfo -v 0.4.10
Successfully built f176482168f8
Successfully tagged stefanprodan/podinfo:0.4.10
```
```

If I want to automate the production deployment based on version tags, I would use `semver` filters instead of `glob`:

Expand Down Expand Up @@ -334,11 +334,11 @@ Successfully tagged stefanprodan/podinfo:0.4.11

### Managing Kubernetes secrets

In order to store secrets safely in a public Git repo you can use the Bitnami [Sealed Secrets controller](https://github.com/bitnami-labs/sealed-secrets)
and encrypt your Kubernetes Secrets into SealedSecrets.
In order to store secrets safely in a public Git repo you can use the Bitnami [Sealed Secrets controller](https://github.com/bitnami-labs/sealed-secrets)
and encrypt your Kubernetes Secrets into SealedSecrets.
The SealedSecret can be decrypted only by the controller running in your cluster.

The Sealed Secrets Helm chart is available on [Helm Hub](https://hub.helm.sh/charts/stable/sealed-secrets),
The Sealed Secrets Helm chart is available on [Helm Hub](https://hub.helm.sh/charts/stable/sealed-secrets),
so I can use the Helm repository instead of a git repo. This is the sealed-secrets controller release:

```yaml
Expand All @@ -361,7 +361,7 @@ spec:
tag: v0.7.0
```

Note that this release is not automated, since this is a critical component I prefer to update it manually.
Note that this release is not automated, since this is a critical component I prefer to update it manually.

Install the kubeseal CLI:

Expand All @@ -370,8 +370,8 @@ wget https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.7.0/kub
sudo install -m 755 kubeseal-darwin-amd64 /usr/local/bin/kubeseal
```

At startup, the sealed-secrets controller generates a RSA key and logs the public key.
Using kubeseal you can save your public key as `pub-cert.pem`,
At startup, the sealed-secrets controller generates a RSA key and logs the public key.
Using kubeseal you can save your public key as `pub-cert.pem`,
the public key can be safely stored in Git, and can be used to encrypt secrets without direct access to the Kubernetes cluster:

```bash
Expand Down Expand Up @@ -405,7 +405,7 @@ spec:
encryptedData:
password: AgAR5nzhX2TkJ.......
user: AgAQDO58WniIV3gTk.......
```
```

Delete the `basic-auth.json` file and push the `pub-cert.pem` and `basic-auth.yaml` to Git:

Expand All @@ -416,8 +416,8 @@ mv basic-auth.yaml /releases/dev/
git commit -a -m "Add basic auth credentials to dev namespace" && git push
```

Flux will apply the sealed secret on your cluster and sealed-secrets controller will then decrypt it into a
Kubernetes secret.
Flux will apply the sealed secret on your cluster and sealed-secrets controller will then decrypt it into a
Kubernetes secret.

![SealedSecrets](https://github.com/fluxcd/helm-operator-get-started/blob/master/diagrams/flux-helm-operator-sealed-secrets.png)

Expand Down Expand Up @@ -477,11 +477,11 @@ spec:

**I'm using SSL between Helm and Tiller. How can I configure Flux to use the certificate?**

When installing Flux, you can supply the CA and client-side certificate using the `helmOperator.tls` options, more details [here](https://github.com/weaveworks/flux/blob/master/chart/flux/README.md#installing-weave-flux-helm-operator-and-helm-with-tls-enabled).
When installing Flux, you can supply the CA and client-side certificate using the `helmOperator.tls` options, more details [here](https://github.com/fluxcd/flux/blob/master/chart/flux/README.md#installing-weave-flux-helm-operator-and-helm-with-tls-enabled).

**I've deleted a `HelmRelease` file from Git. Why is the Helm release still running on my cluster?**

Flux doesn't delete resources, there is an [issue](https://github.com/weaveworks/flux/issues/738) opened about this topic on GitHub.
Flux doesn't delete resources, there is an [issue](https://github.com/fluxcd/flux/issues/738) opened about this topic on GitHub.
In order to delete a Helm release first remove the file from Git and afterwards run:

```yaml
Expand All @@ -494,14 +494,16 @@ The Flux Helm operator will receive the delete event and will purge the Helm rel

For each cluster create a Git branch in your config repo. When installing Flux set the Git branch using `--set git.branch=cluster-name`.

### Getting Help
### <a name="help"></a>Getting Help

If you have any questions about GitOps or Weave Flux:
If you have any questions about Helm Operator and continuous delivery:

- Join the [#gitops](https://kubernetes.slack.com/messages/gitops) Kubernetes slack channel.
- Invite yourself to the [Weave community](https://weaveworks.github.io/community-slack/) slack.
- Ask a question on the [#flux](https://weave-community.slack.com/messages/flux/) slack channel.
- Join the [Weave User Group](https://www.meetup.com/pro/Weave/) and get invited to online talks, hands-on training and meetups in your area.
- Send an email to <a href="mailto:[email protected]">[email protected]</a>
- Read [the Helm Operator docs](https://github.com/fluxcd/flux/tree/master/docs).
- Invite yourself to the <a href="https://slack.cncf.io" target="_blank">CNCF community</a>
slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/)
channel.
- To be part of the conversation about Helm Operator's development, join the
[flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev).
- [File an issue.](https://github.com/fluxcd/flux/issues/new)

Your feedback is always welcome!

0 comments on commit 0c5f0ec

Please sign in to comment.