Merge pull request #1527 from weaveworks/docsup

Use weaveworks/flux-get-started repo in docs

chart/flux/README.md

@@ -14,10 +14,10 @@ a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) p
 
 ### Kubernetes
 
-Kubernetes >= v1.9 is recommended. Kubernetes v1.8 (the first to support
+Kubernetes >= v1.10 is recommended. Kubernetes v1.8 (the first to support
 Custom Resources) appears to have problems with repeated application of
 custom resources (see https://github.com/kubernetes/kubernetes/issues/53379).
-This means fluxd can fail to apply changes to FluxHelmRelease resources.
+This means fluxd can fail to apply changes to HelmRelease resources.
 
 ### Helm
 
@@ -27,24 +27,18 @@ until it can find one.
 
 # Git repo
 
- - One repo containing both desired release state information and Charts
-   themselves.
- - Release state information in the form of Custom Resources manifests is
-   located under a particular path ("releaseconfig" by default; can be
-   overriden).
- - Charts are colocated under another path ("charts" by default; can be
-   overriden). Charts are subdirectories under the charts path.
+ - One repo containing cluster config (i.e., Kubernetes YAMLs) and zero or more git repos containing Charts themselves.
+ - Charts can be co-located with config in the git repo, or be from Helm repositories.
  - Custom Resource namespace reflects where the release should be done.
    Both the Helm release and its corresponding Custom Resource will
    live in this namespace.
- - Example of a test repo: https://github.com/weaveworks/flux-helm-test
+ - Example of a test repo: https://github.com/weaveworks/flux-get-started
 
 ## Installation
 
 We put together a simple [Get Started
 guide](../../site/helm-get-started.md) which takes about 5-10 minutes to follow.
-You will have a fully working Flux installation deploying workloads to your
-cluster.
+You will have a fully working Flux installation deploying workloads to your cluster.
 
 ## Installing Flux using Helm
 
@@ -56,11 +50,13 @@ Add the weaveworks repo:
 helm repo add weaveworks https://weaveworks.github.io/flux
 ```
 
-#### To install the chart with the release name `flux`:
+#### To install the chart with the release name `flux`
+
+Replace `weaveworks/flux-get-started` with your own git repository and run helm install:
 
 ```sh
 $ helm install --name flux \
---set git.url=ssh://[email protected]/weaveworks/flux-example \
+--set [email protected]:weaveworks/flux-get-started \
 --namespace flux \
 weaveworks/flux
 ```
@@ -69,6 +65,7 @@ weaveworks/flux
 
 ```sh
 helm install --name flux \
+--set [email protected]:weaveworks/flux-get-started \
 --set token=YOUR_WEAVE_CLOUD_SERVICE_TOKEN \
 --namespace flux \
 weaveworks/flux
@@ -78,7 +75,7 @@ weaveworks/flux
 
 ```sh
 $ helm install --name flux \
---set git.url=ssh://[email protected]/weaveworks/flux-helm-test \
+--set [email protected]:weaveworks/flux-get-started \
 --set helmOperator.create=true \
 --namespace flux \
 weaveworks/flux
@@ -110,14 +107,15 @@ using an alternate mechanism.
 
     ```sh
     YOUR_GIT_HOST=your_git_host.example.com
+    YOUR_GIT_USER=your_git_user
     KNOWN_HOSTS='domain ssh-rsa line1
     domain ecdsa-sha2-line2
     domain ssh-ed25519 line3'
 
     helm install \
     --name flux \
     --set helmOperator.create=true \
-    --set git.url="ssh://git@${YOUR_GIT_HOST}:weaveworks/flux-helm-test.git" \
+    --set git.url="git@${YOUR_GIT_HOST}:${YOUR_GIT_USER}/flux-get-started" \
     --set-string ssh.known_hosts="${KNOWN_HOSTS}" \
     --namespace flux \
     chart/flux
@@ -129,11 +127,12 @@ using an alternate mechanism.
 
     ```sh
     YOUR_GIT_HOST=your_git_host.example.com
+    YOUR_GIT_USER=your_git_user
 
     helm install \
     --name flux \
     --set helmOperator.create=true \
-    --set git.url="ssh://git@${YOUR_GIT_HOST}:weaveworks/flux-helm-test.git" \
+    --set git.url="git@${YOUR_GIT_HOST}:${YOUR_GIT_USER}/flux-get-started" \
     --set-file ssh.known_hosts=/tmp/flux_known_hosts \
     --namespace flux \
     chart/flux
@@ -209,15 +208,11 @@ The following tables lists the configurable parameters of the Weave Flux chart a
 | `helmOperator.tag` | Helm operator image tag | `<VERSION>`
 | `helmOperator.pullPolicy` | Helm operator image pull policy | `IfNotPresent`
 | `helmOperator.updateChartDeps` | Update dependencies for charts | `true`
+| `helmOperator.git.pollInterval` | Period at which to poll git repo for new commits | `git.pollInterval`
+| `helmOperator.git.timeout` | Duration after which git operations time out | `git.timeout`
 | `helmOperator.chartsSyncInterval` | Interval at which to check for changed charts | `3m`
 | `helmOperator.chartsSyncTimeout` | Timeout when checking for changed charts | `1m`
 | `helmOperator.extraEnvs` | Extra environment variables for the Helm operator pod | `[]`
-| `helmOperator.git.url` | URL of git repo with Helm charts | `git.url`
-| `helmOperator.git.branch` | Branch of git repo to use for Helm charts | `master`
-| `helmOperator.git.chartsPath` | Path within git repo to locate Helm charts (relative path) | `charts`
-| `helmOperator.git.pollInterval` | Period at which to poll git repo for new commits | `git.pollInterval`
-| `helmOperator.git.timeout` | Duration after which git operations time out | `git.timeout`
-| `helmOperator.git.secretName` | Kubernetes secret with the SSH private key | None
 | `helmOperator.logReleaseDiffs` | Helm operator should log the diff when a chart release diverges (possibly insecure) | `false`
 | `helmOperator.tillerNamespace` | Namespace in which the Tiller server can be found | `kube-system`
 | `helmOperator.tls.enable` | Enable TLS for communicating with Tiller | `false`
@@ -232,7 +227,7 @@ Specify each parameter using the `--set key=value[,key=value]` argument to `helm
 
 ```sh
 $ helm upgrade --install --wait flux \
---set git.url=ssh://[email protected]/stefanprodan/podinfo \
+--set [email protected]:stefanprodan/k8s-podinfo \
 --set git.path=deploy/auto-scaling,deploy/local-storage \
 --namespace flux \
 weaveworks/flux
@@ -244,6 +239,6 @@ Update Weave Flux version with:
 
 ```sh
 helm upgrade --reuse-values flux \
---set image.tag=1.7.1 \
+--set image.tag=1.8.1 \
 weaveworks/flux
 ```

site/faq.md

@@ -213,23 +213,13 @@ happen:
  - Flux just hasn't fetched the image metadata yet. This may be the case
    if you've only just started using a particular image in a workload.
  - Flux can't get suitable credentials for the image repository. At
-   present, it looks at `imagePullSecret`s attached to workloads (but
-   not to service accounts; see
-   [weaveworks/flux#1043](https://github.com/weaveworks/flux/issues/1043)),
-   and a Docker config file if you mount one into the fluxd container
+   present, it looks at `imagePullSecret`s attached to workloads,
+   service accounts and a Docker config file if you mount one into the fluxd container
    (see the [command-line usage](./daemon.md)).
  - Flux doesn't know how to obtain registry credentials for ECR. A
    workaround is described in
    [weaveworks/flux#539](https://github.com/weaveworks/flux/issues/539#issuecomment-394588423)
- - Flux doesn't yet understand what to do with image repositories that
-   have images for more than one architecture; see
-   [weaveworks/flux#741](https://github.com/weaveworks/flux/issues/741). At
-   present there's no workaround for this, if you are not in control
-   of the image repository in question (or you are, but you need to
-   have multi-arch manifests).
- - Flux doesn't yet examine `initContainer`s when cataloguing the
-   images used by workloads. See
-   [weaveworks/flux#702](https://github.com/weaveworks/flux/issues/702)
+ - Flux excludes images with no suitable manifest (linux amd64) in manifestlist
  - Flux doesn't yet understand image refs that use digests instead of
    tags; see
    [weaveworks/flux#885](https://github.com/weaveworks/flux/issues/885).
@@ -416,7 +406,7 @@ Flux doesn't delete resources, there is an [issue](https://github.com/weaveworks
 In order to delete a Helm release first remove the file from Git and afterwards run:
 
 ```yaml
-kubectl delete fluxhelmrelease/my-release
+kubectl delete helmrelease/my-release
 ```
 
 The Flux Helm operator will receive the delete event and will purge the Helm release.
@@ -428,22 +418,12 @@ You need to use the `helm delete --purge` option only then Flux will be able rei
 
 ### I've uninstalled Flux and all my Helm releases are gone. Why is that?
 
-On `FluxHelmRelease` CRD deletion, Kubernetes will remove all `FluxHelmRelease` CRs triggering a Helm purge for each release created by Flux.
+On `HelmRelease` CRD deletion, Kubernetes will remove all `HelmRelease` resources triggering a Helm purge for each release created by Flux.
 To avoid this you have to manually delete the Flux Helm Operator with `kubectl -n flux delete deployment/flux-helm-operator` before running `helm delete flux`.
 
 ### I have a dedicated Kubernetes cluster per environment and I want to use the same Git repo for all. How can I do that?
 
 For each cluster create a Git branch in your config repo. When installing Flux set the Git branch using `--set git.branch=cluster-name`
 and set a unique label for each cluster `--set git.label=cluster-name`.
 
-### I have a dedicated Git repo for my Helm charts. How can I point Flux Helm Operator to it?
 
-When installing Flux with Helm you can override the Operator Git settings using `--set helmOperator.git.url=`.
-
-If you are using GitHub you need to create a SSH key for Helm Operator:
-
-* generate a SSH key named identity: `ssh-keygen -q -N "" -f ./identity`
-* create a Kubernetes secret: `kubectl -n flux create secret generic helm-ssh --from-file=./identity`
-* delete the private key: `rm ./identity`
-* add `./identity.pub` as a read-only deployment key in your GitHub repo where the charts are
-* set the secret name with `--set helmOperator.git.secretName=helm-ssh`

site/fluxctl.md

@@ -566,39 +566,41 @@ configured using fluxctl.
 Here's a simple but complete deployment file with annotations:
 
 ```
-apiVersion: extensions/v1beta1
+apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: k8s-mon
-  namespace: admin
+  name: podinfo
+  namespace: demo
+  labels:
+    app: podinfo
   annotations:
     flux.weave.works/automated: "true"
-    flux.weave.works/tag.k8s-mon: glob:master-*
+    flux.weave.works/tag.podinfod: semver:~1.3
 spec:
-  replicas: 1
-  strategy:
-    rollingUpdate:
-      maxUnavailable: 0
-      maxSurge: 50%
+  selector:
+    matchLabels:
+      app: podinfo
   template:
     metadata:
       labels:
-        app: k8s-mon
+        app: podinfo
     spec:
       containers:
-      - name: k8s-mon
-        image: index.docker.io/larktech/k8s-mon:master-c00edf01
-
-      imagePullSecrets:
-      - name: myregistrykey
-
+      - name: podinfod
+        image: stefanprodan/podinfo:1.3.2
+        ports:
+        - containerPort: 9898
+          name: http
+        command:
+        - ./podinfo
+        - --port=9898
 ```
 
 Things to notice:
 
 1. The annotations are made in `metadata.annotations`, not in `spec.template.metadata`.
-2. The `flux.weave.works/tag.`... references the container name `k8s-mon`--this will change based on your container name. If you have multiple containers you would have multiple lines like that.
-3. The value for the `flux.weave.works/tag.`... annotation should includes the filter pattern type, in this case `glob`.
+2. The `flux.weave.works/tag.`... references the container name `podinfod`, this will change based on your container name. If you have multiple containers you would have multiple lines like that.
+3. The value for the `flux.weave.works/tag.`... annotation should includes the filter pattern type, in this case `semver`.
 
 Annotations can also be used to tell Flux to temporarily ignore certain manifests
 using `flux.weave.works/ignore: "true"`. Read more about this in the [FAQ](faq.md#can-i-temporarily-make-flux-ignore-a-deployment).

site/get-started.md

@@ -19,19 +19,6 @@ 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.
 
-When using a cluster in the cloud (e.g. GKE), use nodes with at least 2 CPU's.
-When using nodes with only 1 CPU (like `n1-standard-1`), an upgrade
-may be stuck with not enough CPU resources. This issue usually manifests itself
-in the form of pods hanging in the PENDING state, which looks something like:
-
-```sh
-$ kubectl describe pod/helloworld-... | tail -3
-Events:
-  Type     Reason            Age                From               Message
-  ----     ------            ----               ----               -------
-  Warning  FailedScheduling  3m (x37 over 13m)  default-scheduler  0/2 nodes are available: 2 Insufficient cpu.
-```
-
 ### A Note on GKE with RBAC enabled
 
 > If working on e.g. GKE with RBAC enabled, you will need to add a clusterrolebinding:
@@ -64,7 +51,7 @@ $EDITOR deploy/flux-deployment.yaml
 ```
 
 In our example we are going to use
-[flux-example](https://github.com/weaveworks/flux-example). If you
+[flux-get-started](https://github.com/weaveworks/flux-get-started). If you
 want to use that too, be sure to create a fork of it on Github and
 add the git URL to the config file above.
 
@@ -105,19 +92,19 @@ click on **Add deploy key**, give it a name, check **Allow write
 access**, paste the Flux public key and click **Add key**.
 
 (Or replace `YOURUSER` with your Github ID in this url:
-`https://github.com/YOURUSER/flux-example/settings/keys/new` and
+`https://github.com/YOURUSER/flux-get-started/settings/keys/new` and
 paste the key there.)
 
 ## Committing a small change
 
 In this example we are using a simple example of a webservice and
 change its configuration to use a different message. The easiest
-way is to edit your fork of `flux-example` and change the `msg` argument.
+way is to edit your fork of `flux-get-started` and change the `PODINFO_UI_COLOR` env var to `blue`.
 
 Replace `YOURUSER` in
-`https://github.com/YOURUSER/flux-example/blob/master/helloworld-deploy.yaml`
+`https://github.com/YOURUSER/flux-get-started/blob/master/workloads/podinfo-dep.yaml`
 with your Github ID), open the URL in your browser, edit the file,
-change the argument value and commit the file.
+change the env var value and commit the file.
 
 You can check out the Flux logs with:
 
@@ -135,10 +122,11 @@ To access our webservice and check out its welcome message, simply
 run:
 
 ```sh
-kubectl port-forward deployment/helloworld 8080:80 &
-curl localhost:8080
+kubectl -n demo port-forward deployment/podinfo 9898:9898 &
 ```
 
+Open your browser and navigate to `http://localhost:9898`.
+
 ## Conclusion
 
 As you can see, the actual steps to set up Flux, get our app