Complete readme info on secrets

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.