Merge pull request #1753 from dimitropoulos/updates-docs

Updates Docs (wording, typos, formatting)

README.md

@@ -52,8 +52,8 @@ Its major features are:
 - Straight-forward control over the state of deployments in the
   cluster (rollbacks, lock a specific version of a workload, manual
   deployments)
-- Observability: git commits are an audit trail, and you can record
-  e.g., why a given deployment was locked.
+- Observability: git commits are an audit trail, and you can record events that
+  occured, for example: why a given deployment was locked.
 
 ### Relation to Weave Cloud
 

site/annotations-tutorial.md

@@ -93,7 +93,7 @@ weaveworks/flux
 
 > **Note:** In this tutorial we keep things simple, so we deploy Flux into
 the `default` namespace. Normally you would pick a separate namespace for
-it. `fluxctl` has the `k8s-fwd-ns` option for specifying the right
+it. `fluxctl` has the `--k8s-fwd-ns <NAMESPACE>` option for specifying the right
 namespace.
 
 ### Connecting to your git config

site/fluxctl.md

@@ -13,7 +13,7 @@ menu_order: 40
   * [Add an SSH deploy key to the repository](#add-an-ssh-deploy-key-to-the-repository)
     + [1. Allow flux to generate a key for you](#1-allow-flux-to-generate-a-key-for-you)
     + [2. Specify a key to use](#2-specify-a-key-to-use)
-- [What is a Controller](#what-is-a-controller)
+- [What is a Controller?](#what-is-a-controller)
 - [Viewing Controllers](#viewing-controllers)
 - [Inspecting the Version of a Container](#inspecting-the-version-of-a-container)
 - [Releasing a Controller](#releasing-a-controller)
@@ -122,18 +122,6 @@ the public key through fluxctl:
 ```sh
 $ fluxctl identity
 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDCN2ECqUFMR413CURbLBcG41fLY75SfVZCd3LCsJBClVlEcMk4lwXxA3X4jowpv2v4Jw2qqiWKJepBf2UweBLmbWYicHc6yboj5o297//+ov0qGt/uRuexMN7WUx6c93VFGV7Pjd60Yilb6GSF8B39iEVq7GQUC1OZRgQnKZWLSQ==
-0c:de:7d:47:52:cf:87:61:52:db:e3:b8:d8:1a:b5:ac
-+---[RSA 1024]----+
-|            ..=  |
-|             + B |
-|      .     . +.=|
-|     . + .   oo o|
-|      . S . .o.. |
-|           .=.o  |
-|           o =   |
-|            +    |
-|           E     |
-+------[MD5]------+
 ```
 
 Alternatively, you can see the public key in the `flux` log.
@@ -188,13 +176,24 @@ Using an SSH key allows you to maintain control of the repository. You
 can revoke permission for `flux` to access the repository at any time
 by removing the deploy key.
 
-```sh
+```
 fluxctl helps you deploy your code.
 
+Connecting:
+
+  # To a fluxd running in namespace "default" in your current kubectl context
+  fluxctl list-controllers
+
+  # To a fluxd running in namespace "weave" in your current kubectl context
+  fluxctl --k8s-fwd-ns=weave list-controllers
+
+  # To a Weave Cloud instance, with your instance token in $TOKEN
+  fluxctl --token $TOKEN list-controllers
+
 Workflow:
-  fluxctl list-controllers                                           # Which controllers are running?
-  fluxctl list-images --controller=deployment/foo                    # Which images are running/available?
-  fluxctl release --controller=deployment/foo --update-image=bar:v2  # Release new version.
+  fluxctl list-controllers                                                   # Which controllers are running?
+  fluxctl list-images --controller=default:deployment/foo                    # Which images are running/available?
+  fluxctl release --controller=default:deployment/foo --update-image=bar:v2  # Release new version.
 
 Usage:
   fluxctl [command]
@@ -204,24 +203,27 @@ Available Commands:
   deautomate       Turn off automatic deployment for a controller.
   help             Help about any command
   identity         Display SSH public key
-  list-controllers List controllers currently running on the platform.
+  list-controllers List controllers currently running in the cluster.
   list-images      Show the deployed and available images for a controller.
   lock             Lock a controller, so it cannot be deployed.
   policy           Manage policies for a controller.
   release          Release a new version of a controller.
-  save             save controller definitions to local files in platform-native format
+  save             save controller definitions to local files in cluster-native format
+  sync             synchronize the cluster with the git repository, now
   unlock           Unlock a controller, so it can be deployed.
   version          Output the version of fluxctl
 
 Flags:
-  -h, --help           help for fluxctl
-  -t, --token string   Weave Cloud controller token; you can also set the environment variable WEAVE_CLOUD_TOKEN or FLUX_SERVICE_TOKEN
-  -u, --url string     base URL of the flux controller; you can also set the environment variable FLUX_URL (default "https://cloud.weave.works/api/flux")
+  -h, --help                            help for fluxctl
+      --k8s-fwd-labels stringToString   Labels used to select the fluxd pod a port forward should be created for. You can also set the environment variable FLUX_FORWARD_LABELS (default [app=flux])
+      --k8s-fwd-ns string               Namespace in which fluxd is running, for creating a port forward to access the API. No port forward will be created if a URL or token is given. You can also set the environment variable FLUX_FORWARD_NAMESPACE (default "default")
+  -t, --token string                    Weave Cloud authentication token; you can also set the environment variable WEAVE_CLOUD_TOKEN or FLUX_SERVICE_TOKEN
+  -u, --url string                      Base URL of the flux API (defaults to "https://cloud.weave.works/api/flux" if a token is provided); you can also set the environment variable FLUX_URL
 
 Use "fluxctl [command] --help" for more information about a command.
 ```
 
-# What is a Controller
+# What is a Controller?
 
 This term refers to any cluster resource responsible for the creation of
 containers from versioned images - in Kubernetes these are workloads such as
@@ -435,8 +437,8 @@ When building images it is often useful to tag build images by the branch that t
 quay.io/weaveworks/helloworld:master-9a16ff945b9e
 ```
 
-Indicates that the "helloworld" image was built against master
-commit "9a16ff945b9e".
+Indicates that the `helloworld` image was built against master
+commit `9a16ff945b9e`.
 
 When automation is turned on flux will, by default, use whatever
 is the latest image on a given repository. If you want to only
@@ -526,8 +528,10 @@ you must bookend your pattern with `^` and `$`.
 
 `fluxctl` provides the following flags for the message and author customization:
 
-  -m, --message string      message associated with the action
-      --user    string      user who triggered the action
+```
+  -m, --message string      attach a message to the update
+      --user    string      override the user reported as initiating the update
+```
 
 Commit customization
 

site/get-started.md

@@ -20,7 +20,7 @@ takes a couple of minutes to get set up. By the end you will
 have Flux running in your cluster and it will be deploying any
 code changes for you.
 
-_Note:_ If you would like to install Flux using Helm, refer to the
+> **Note:** If you would like to install Flux using Helm, refer to the
 [Helm section](./helm-get-started.md).
 
 ## Prerequisites
@@ -29,8 +29,8 @@ You will need to have Kubernetes set up. For a quick local test,
 you can use `minikube` or `kubeadm`. Any other Kubernetes setup
 will work as well though.
 
-### A Note on GKE with RBAC enabled
-
+> ### A Note on GKE with RBAC enabled
+>
 > If working on e.g. GKE with RBAC enabled, you will need to add a clusterrolebinding:
 >
 > ```sh
@@ -96,8 +96,10 @@ 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**, give it a name, check **Allow write
-access**, paste the Flux public key and click **Add key**.
+click on **Add deploy key**, give it a `Title`, check **Allow write
+access**, paste the Flux public key and click **Add key**.  See the
+(GitHub docs)[https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys]
+for more info on how to manage deploy keys.
 
 (Or replace `YOURUSER` with your Github ID in this url:
 `https://github.com/YOURUSER/flux-get-started/settings/keys/new` and

site/helm-get-started.md

@@ -128,7 +128,7 @@ 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**, give it a name, check **Allow write
+click on **Add deploy key**, give it a `Title`, check **Allow write
 access**, paste the Flux public key and click **Add key**.
 
 (Or replace `YOURUSER` with your Github ID in this url:
@@ -161,7 +161,7 @@ change the `tag:` line to the following:
   values:
     image:
       repository: bitnami/mongodb
-      tag: 4.0.2
+      tag: 4.0.6
 ```
 
 Commit the change to your `master` branch. It will now get

site/helm-integration.md

@@ -15,7 +15,7 @@ menu_order: 90
     + [Authentication for Helm repos](#authentication-for-helm-repos)
       - [Azure ACR repositories](#azure-acr-repositories)
     + [Authentication for Git repos](#authentication-for-git-repos)
-  * [Upgrading images in a HelmRelease using Flux](#upgrading-images-in-a-helmrelease-using-flux)
+  * [Upgrading images in a `HelmRelease` using Flux](#upgrading-images-in-a-helmrelease-using-flux)
     + [Using annotations to control updates to HelmRelease resources](#using-annotations-to-control-updates-to-helmrelease-resources)
 
 # Using Flux with Helm
@@ -113,7 +113,7 @@ two ways.
 ### `.spec.values`
 
 This is a YAML map as you'd put in a file and supply to Helm with `-f
-values.yaml`, but inlined into the HelmRelease manifest. For
+values.yaml`, but inlined into the `HelmRelease` manifest. For
 example,
 
 ```yaml
@@ -134,7 +134,7 @@ spec:
 ### `.spec.valueFileSecrets`
 
 This is a list of secrets (in the same namespace as the
-HelmRelease) from which to take values. The secrets must each
+`HelmRelease`) from which to take values. The secrets must each
 contain an entry for `values.yaml`.
 
 The values are merged in the order given, with later values
@@ -162,7 +162,7 @@ You would create a secret in the cluster by doing this:
 kubectl -n dev create secret generic default-values --from-file=values.yaml
 ```
 
-If you did `kubectl get -n dev default-values` you would get:
+If you did `kubectl get -n dev secret default-values` you would get:
 
 ```yaml
 apiVersion: v1
@@ -187,24 +187,25 @@ metadata:
 spec:
   # chart: ...
   valueFileSecrets:
-  - name: "default-values"
+  - name: default-values
 ```
 
 ## Authentication
 
 At present, per-resource authentication is not implemented. The
 `HelmRelease` definition includes a field `chartPullSecret` for
-attaching a repositories.yaml file, but this is ignored for now.
+attaching a `repositories.yaml` file, but this is ignored for now.
 
-Instead, you need to provide the operator with credentials and keys --
-see the following for how to do this.
+Instead, you need to provide the operator with credentials and keys (see the
+following [Authentication for Heml repos](#authentication-for-helm-repos)
+section for how to do this).
 
 ### Authentication for Helm repos
 
 As a workaround, you can mount a `repositories.yaml` file with
 authentication already configured, into the operator container.
 
-> **Note**: When using a custom `repositories.yaml` the [default](../docker/helm-repositories.yaml)
+> **Note:** When using a custom `repositories.yaml` the [default](../docker/helm-repositories.yaml)
 that ships with the operator is overwritten. This means that for any
 repository you want to make use of you should manually add an entry to
 your `repositories.yaml` file.
@@ -263,21 +264,20 @@ use a chart from git, the Helm Operator needs a key with read-only
 access.
 
 To provide an SSH key, put the key in a secret under the entry
-`"identity"`, and mount it into the operator container as shown in the
-[example
-deployment](../deploy-helm/helm-operator-deployment.yaml). The default
-ssh_config expects an identity file at `/etc/fluxd/ssh/identity`,
-which is where it'll be if you just uncomment the blocks from the
-example.
+`identity`, and mount it into the operator container as shown in the
+[example deployment](../deploy-helm/helm-operator-deployment.yaml).
+The default ssh_config expects an identity file at
+`/etc/fluxd/ssh/identity`, which is where it'll be if you just
+uncomment the blocks from the example.
 
 If you're using more than one repository, you may need to provide more
 than one SSH key. In that case, you can create a secret with an entry
 for each key, and mount that _as well as_ an ssh_config file
 mentioning each key as an `IdentityFile`.
 
-## Upgrading images in a HelmRelease using Flux
+## Upgrading images in a `HelmRelease` using Flux
 
-If the chart you're using in a HelmRelease lets you specify the
+If the chart you're using in a `HelmRelease` lets you specify the
 particular images to run, you will usually be able to update them with
 Flux, the same way you can with Deployments and so on.
 
@@ -324,7 +324,7 @@ values:
     port: 4040
 ```
 
-### Using annotations to control updates to HelmRelease resources
+### Using annotations to control updates to `HelmRelease` resources
 
 You can use the [same annotations](./fluxctl.md#using-annotations) in
 the `HelmRelease` as you would for a Deployment or other workload,

site/helm-operator.md

@@ -35,7 +35,7 @@ helm-operator requires setup and offers customization though a multitude of flag
 
 Generate certificates for Tiller and Flux. This will provide a CA, servercerts for Tiller and client certs for Helm / Weave Flux.
 
-> **Note**: When creating the certificate for Tiller the Common Name should match the hostname you are connecting to from the Helm operator.
+> **Note:** When creating the certificate for Tiller the Common Name should match the hostname you are connecting to from the Helm operator.
 
 The following script can be used for that (requires [cfssl](https://github.com/cloudflare/cfssl)):
 
@@ -174,7 +174,7 @@ First create a new Kubernetes TLS secret for the client certs;
 kubectl create secret tls helm-client --cert=tls/flux-helm-operator.pem --key=./tls/flux-helm-operator-key.pem
 ```
 
-> note: this has to be in the same namespace as the flux-helm-operator is deployed in.
+> **Note:** this has to be in the same namespace as the flux-helm-operator is deployed in.
 
 Deploy Flux with Helm;
 
@@ -191,7 +191,7 @@ helm upgrade --install \
     flux \
     weaveworks/flux
 ```
-> note:
+> **Note:**
 > - include --tls flags for `helm` as in the `helm ls` example, if talking to a tiller with TLS
 > - optionally specify target --namespace
 
@@ -241,4 +241,4 @@ Check the operator logs with:
 kubectl -n weave logs deployment/flux-helm-operator -f
 ```
 
-**Note:** that the above instructions are assuming that Tiller is deployed in the `kube-system` namespace without TLS.
+> **Note:** The above instructions are assuming that Tiller is deployed in the `kube-system` namespace without TLS.

site/introduction.md

@@ -28,7 +28,7 @@ This is a simple, but dramatic improvement on current state of the art.
 
 - All configuration is stored within version control and is inherently
   up to date. At any point anyone could completely recreate the cluster
-  in exactly the same state.
+  in exactly the same state of configuration.
 - Changes to the cluster are immediately visible to all interested
   parties.
 - During a postmortem, the git log provides the perfect history for an
@@ -44,7 +44,7 @@ versions where applicable.
 
 This is really useful for keeping the repository and therefore the
 cluster up to date. It allows separate teams to have their own
-deployment pipelines then Flux is able to see the new image and update
+deployment pipelines since Flux is able to see the new image and update
 the cluster accordingly.
 
 This feature can be disabled and images can be locked to a specific