GitOps Getting Started

An example of an application deployment and configuration managed using GitOps and the tool Flux.

The goal is to have a central git repo hosting all the configuration and deployments for an application, including its dependencies. Permissions set in this repo also define who is allowed to update the configuration.

This example has two main components:

• a frontend web application based on wordpress
• a backend MySQL database

It should be enough to give you hints on how to manage your own deployments in the same way.

Pre-Requisites

First get a Kubernetes cluster up and running, check here.

Make sure you also deploy Helm.

Flux Overview

Flux has two main components:

• Flux itself, which is responsible for syncing with the remote git repository. We rely on the Helm integration, so Flux will instantiate in the cluster the HelmRelease custom resources defined in the releases directory
• Helm Operator, which watches for the HelmRelease custom resources and applies them in the cluster - basically by doing helm install/upgrade/...

Check the helm releases defined in this repo under the releases directory to see what goes in these resources.

Structure and Releases

The structure of this repo is as follows:

• chart: The umbrella chart. This is where all the default configuration for the dependencies is stored, inside the values.yaml file. You can also add custom manifests under the templates directory
• namespaces: Flux expects all the required namespaces to be defined here. In this example we have both prod and stg
• releases: The different deployments of the application (staging, production), each with overrides for the configuration as required - completing the default values. These are Flux HelmRelease resources
• secrets: This is a special directory that is not part of standard Flux. In the future it will not be required, but for now it holds the parts of the values yaml definitions that are sensitive (and require encryption to be safely committed to git)

Secrets

This is not about handling Kubernetes Secret resources, that's handled by the different helm charts. This is a solution to handle sensitive information stored in the helm yaml files (that often populate the Kubernetes Secrets).

The sensitive yaml content should be stored in a separate Secret object and should be created prior to deploying Flux. Check the HelmRelease resources under releases and you'll notice their refer to these secrets to fetch additional values.

We recommend using the barbican secrets plugin to encrypt the files under the secrets directory.

You'll need to source the environment for the OpenStack project that should hold the encryption key. Then fetch a token.

export OS_TOKEN=$(openstack token issue -c id -f value)

And then edit and create the resources:

kubectl create -f namespaces/prod.yaml
kubectl create -f namespaces/stg.yaml

helm secrets edit secrets/prod/secrets.yaml
helm secrets edit secrets/stg/secrets.yaml

kubectl secrets apply -f secrets/prod/secrets.yaml
kubectl secrets apply -f secrets/stg/secrets.yaml

Remember that these resources are not managed by Flux. If you need to update any part of the sensitive values yaml data, you need to update them manually by doing:

helm secrets edit secrets/prod/secrets.yaml
helm secrets edit secrets/stg/secrets.yaml

kubectl secrets apply -f secrets/prod/secrets.yaml
kubectl secrets apply -f secrets/stg/secrets.yaml

In the near future there will be better integration of this way of handling sensitive configuration data with Flux.

Deployment

You need to deploy both the helm operator and flux itself:

$ helm install fluxcd/helm-operator --namespace flux --name helm-operator \
  --version 0.4.0 --values helm-operator-values.yaml

$ helm install fluxcd/flux --namespace flux --name flux \
  --values flux-values.yaml \
  --set git.url=https://gitlab.cern.ch/helm/releases/gitops-getting-started

The files helm-operator-values.yaml and flux-values.yaml contain the configuration for each of the components. You can change these as you want.

Check the logs to see the multiple releases are being picked up:

$ kubectl -n flux logs -f deployment.apps/helm-operator
$ kubectl -n flux logs -f deployment.apps/flux

All going well you should see them in helm:

$ helm ls
NAME                        REVISION    UPDATED                     STATUS      CHART                           APP VERSION NAMESPACE
flux                        1           Mon Jan 20 23:04:34 2020    DEPLOYED    flux-1.0.0                      1.17.0      flux     
gitops-getting-started      1           Mon Jan 20 23:17:48 2020    DEPLOYED    gitops-getting-started-0.1.0                prod     
gitops-getting-started-stg  1           Mon Jan 20 23:17:48 2020    DEPLOYED    gitops-getting-started-0.1.0                stg      
helm-operator               1           Mon Jan 20 23:04:32 2020    DEPLOYED    helm-operator-0.4.0             1.0.0-rc5   flux  

FAQ

What's the best practice to update the release values?

It depends which releases you want to affect.

• If you want the change to impact all releases (prod, staging, ...), change the values in the chart/application name/values.yaml file. These are the defaults for all releases
• If you want the change to impact only one release, change the corresponding yaml file in the releases/release-to-be-changed directory

Flux will detect the change and apply it locally on the cluster(s) where it is deployed.

How do i force Flux to sync with the remote repository?

Flux will sync periodically, following the value in the git.pollInterval parameter. If you've set this value conservatively and want to get Flux to sync immediately, try:

$ export FLUX_FORWARD_NAMESPACE=flux
$ fluxctl sync

How do i add custom manifests not part of any existing Helm chart?

You can add these additional manifests in the same way you would do for a normal chart. Put them under charts/application-name/templates and they will be picked up during the installation (and updates). You can use values as usual as well.

How do i restrict the deployment to only one release?

To restrict the deployment in this cluster to a single release, pass the allowed namespace parameter when deploying the helm operator:

$ helm install fluxcd/helm-operator --namespace flux --name helm-operator \
  --values helm-operator-values.yaml \
  --set allowNamespace=stg

Can i deploy the application in multiple clusters?

Absolutely. The repository knows nothing about the clusters the application will be deployed in, which is an advantage as you don't have to set the credentials anywhere outside the cluster(s).

Deploying multiple times in different clusters will also help you reduce blast radius, it's a good way to perform upgrades by redeploying the full setup and gradually moving resources to the new instance, and it's one of the possible alternatives to achieve high availability.