diff --git a/README.md b/README.md index e7180893ceb6f04ad5ea353aa3ff7c53c65e1fe5..50d6ce6226c0a7cabe78b3f0b81ea798ac7d7935 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Make sure you also [deploy Helm](https://clouddocs.web.cern.ch/containers/tutori ## Flux Overview Flux has two main components: -* *Flux* itself, which is responsible of syncing with the remote git +* *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 @@ -36,31 +36,35 @@ see what goes in these resources. ## Structure and Releases The structure of this repo is as follows: -* **chart**: the umbrella chart. These is where all the default configuration +* **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), +* **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 +* **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 does not about handling Kubernetes Secret resources, that's handled by the +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 populates the Kubernetes Secrets). +stored in the helm yaml files (that often populate the Kubernetes Secrets). -The sensitive yaml content should be stored in a separate Secret object to be -created explicitly, previously to deploying Flux. We recommend using the -[barbican secrets](https://gitlab.cern.ch/helm/plugins/barbican) plugin to encrypt -the files under the *secrets* directory. +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. -You'll need to source the project that should hold the encryption key. +We recommend using the [barbican secrets](https://gitlab.cern.ch/helm/plugins/barbican) +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. ```bash export OS_TOKEN=$(openstack token issue -c id -f value) ``` @@ -104,7 +108,7 @@ $ helm install fluxcd/flux --namespace flux --name flux --version 1.0.0 \ ``` The files *helm-operator-values.yaml* and *flux-values.yaml* contain the -configuration for each of the component. You can change these as you want. +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: ``` @@ -129,10 +133,10 @@ helm-operator 1 Mon Jan 20 23:04:32 2020 DEPLOYED 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 + 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 + 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. @@ -141,7 +145,7 @@ deployed. 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 -right now, try: +immediately, try: ```bash $ export FLUX_FORWARD_NAMESPACE=flux $ fluxctl sync @@ -150,15 +154,18 @@ $ 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 +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: +To restrict the deployment in this cluster to a single release, pass the +allowed namespace parameter when deploying the helm operator: ```bash -helm install fluxcd/helm-operator --namespace flux --name helm-operator --values helm-operator-values.yaml --set allowNamespace=stg +$ 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? @@ -168,8 +175,8 @@ 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, is a good way to perform upgrades by redeploying the full setup and +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 -alternatives to achieve high availability. +possible alternatives to achieve high availability.