diff --git a/README.md b/README.md index 1b34666a7..209b91dec 100644 --- a/README.md +++ b/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 diff --git a/site/annotations-tutorial.md b/site/annotations-tutorial.md index 2ffe0b21f..356bb8321 100644 --- a/site/annotations-tutorial.md +++ b/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 ` option for specifying the right namespace. ### Connecting to your git config diff --git a/site/fluxctl.md b/site/fluxctl.md index 875da86b1..62b3eae32 100644 --- a/site/fluxctl.md +++ b/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 diff --git a/site/get-started.md b/site/get-started.md index 9ec9faec5..c5be68df7 100644 --- a/site/get-started.md +++ b/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 diff --git a/site/helm-get-started.md b/site/helm-get-started.md index 99aa34343..8c6fb5ba8 100644 --- a/site/helm-get-started.md +++ b/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 diff --git a/site/helm-integration.md b/site/helm-integration.md index 53ffd8c80..8a4bffb7f 100644 --- a/site/helm-integration.md +++ b/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, diff --git a/site/helm-operator.md b/site/helm-operator.md index cd0cfd4a1..2dcb93311 100644 --- a/site/helm-operator.md +++ b/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. diff --git a/site/introduction.md b/site/introduction.md index 063dd5d1b..78846012c 100644 --- a/site/introduction.md +++ b/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 diff --git a/site/upgrading-to-1.0.md b/site/upgrading-to-1.0.md index 1d3673689..b16dd21ba 100644 --- a/site/upgrading-to-1.0.md +++ b/site/upgrading-to-1.0.md @@ -87,10 +87,12 @@ In summary, you will need to: First, it will help in a few places to have an old fluxctl around. Download it from GitHub: - curl -o fluxctl_030 https://github.com/weaveworks/flux/releases/download/0.3.0/fluxctl_linux_amd64 - # or if using macOS, - # curl -o fluxctl_030 https://github.com/weaveworks/flux/releases/download/0.3.0/fluxctl_darwin_amd64 - chmod a+x ./fluxctl_030 +```sh +curl -o fluxctl_030 https://github.com/weaveworks/flux/releases/download/0.3.0/fluxctl_linux_amd64 +# or if using macOS, +# curl -o fluxctl_030 https://github.com/weaveworks/flux/releases/download/0.3.0/fluxctl_darwin_amd64 +chmod a+x ./fluxctl_030 +``` The next steps depend on whether you @@ -108,7 +110,9 @@ upgrading). Before making changes, get the config so that it can be consulted later: - ./fluxctl_030 get-config --fingerprint=md5 | tee old-config.yaml +```sh +./fluxctl_030 get-config --fingerprint=md5 | tee old-config.yaml +``` ### Remove old Flux resources @@ -121,8 +125,10 @@ later: Run Weave Cloud’s launch generator to delete the resources in the cluster: - kubectl delete -n kube-system -f \ - https://cloud.weave.works/k8s/flux.yaml?flux-version=0.3.0” +```sh +kubectl delete -n kube-system -f \ + https://cloud.weave.works/k8s/flux.yaml?flux-version=0.3.0” +``` ### Delete deployment keys @@ -133,7 +139,9 @@ pointing Flux at, and delete the key Flux was using. To check you are removing the correct key, get the fingerprint of the key used by Flux with - ./fluxctl_030 get-config --fingerprint=md5 +```sh +./fluxctl_030 get-config --fingerprint=md5 +``` ### Configure and run the new Flux resources @@ -168,7 +176,9 @@ to expose the Flux service. Before making any changes, get the config so that it can be consulted later: - ./fluxctl_030 get-config --fingerprint=md5 | tee old-config.yaml +``` +./fluxctl_030 get-config --fingerprint=md5 | tee old-config.yaml +``` ### Remove old Flux resources @@ -183,8 +193,10 @@ You can delete the Flux resources by referring to the manifest files used to create them. If you don’t have the files on hand, you can try using the example deployment as a stand-in: - git clone --branch 0.3.0 git@github.com:weaveworks/flux flux-0.3.0 - kubectl delete --ignore-not-found -R -f ./flux-0.3.0/deploy +```sh +git clone --branch 0.3.0 git@github.com:weaveworks/flux flux-0.3.0 +kubectl delete --ignore-not-found -R -f ./flux-0.3.0/deploy +``` That’s something of a sledgehammer! But it should cover most cases. @@ -224,21 +236,25 @@ To see the SSH key created by Flux, download the latest fluxctl from [the release page](https://github.com/weaveworks/flux/releases/tag/1.0.1) and run: - fluxctl identity +```sh +fluxctl identity +``` You will need to add this as a deploy key, which is also described in the setup instructions linked above. ## Troubleshooting -### The kubectl delete commands didn’t delete anything +### The `kubectl delete` commands didn’t delete anything It’s possible that the Flux resources are in an unusual namespace or given a different name. As a last resort, you can hunt down the resources by name and delete them. Weave Cloud’s “Explore” tab may help; or use kubectl to look for likely suspects. - kubectl get serviceaccount,service,deployment --all-namespaces +```sh +kubectl get serviceaccount,service,deployment --all-namespaces +``` Have a look for deployments and services with “flux” in the name.