Add Flux deployment kustomization

docs/tutorials/get-started-kustomize.md

@@ -0,0 +1,161 @@
+# How to bootstrap Flux using Kustomize
+
+This guide shows you how to use Kustomize to bootstrap Flux on a Kubernetes cluster.
+
+## Prerequisites
+
+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
+
+If working on e.g. GKE with RBAC enabled, you will need to add a cluster role binding:
+
+```sh
+kubectl create clusterrolebinding "cluster-admin-$(whoami)" \
+    --clusterrole=cluster-admin \
+    --user="$(gcloud config get-value core/account)"
+```
+
+## Prepare Flux installation 
+
+First you'll need a git repository to store your cluster desired state.
+In our example we are going to use [`fluxcd/flux-get-started`](https://github.com/fluxcd/flux-get-started).
+If you want to use that too, be sure to create a fork of it on GitHub.
+
+Create a directory and add the `flux` namespace definition to it:
+
+```sh
+mkdir fluxcd
+
+cat > fluxcd/namespace.yaml <<EOF
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: flux
+EOF
+```
+
+Create a kustomization file and use the Flux deploy YAMLs as base:
+
+```sh
+cat > fluxcd/kustomization.yaml <<EOF
+namespace: flux
+bases:
+ - github.com/fluxcd/flux//deploy
+patchesStrategicMerge:
+  - patch.yaml
+EOF
+```
+
+> **Note:** If you want to install a specific Flux release,
+> add the version number to the base URL:
+> `github.com/fluxcd/flux//deploy?ref=v1.14.0`
+
+Create a patch file for Flux deployment and set the `--git-url`
+parameter to point to the config repository
+(replace `YOURUSER` with your GitHub username):
+
+```sh
+export GHUSER="YOURUSER"
+cat > fluxcd/patch.yaml <<EOF
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: flux
+spec:
+  template:
+    spec:
+      containers:
+        - name: flux
+          args:
+            - --manifest-generation=true
+            - --memcached-hostname=memcached.flux
+            - --memcached-service=
+            - --ssh-keygen-dir=/var/fluxd/keygen
+            - --git-branch=master
+            - --git-path=namespaces,workloads
+            - --git-user=${GHUSER}
+            - --git-email=${GHUSER}@users.noreply.github.com
+            - --git-url=git@github.com:${GHUSER}/flux-get-started
+EOF
+```
+
+We set `--git-path=namespaces,workloads` to exclude Helm manifests.
+If you want to get started with Helm, please refer to the
+["Get started with Flux using Helm"](get-started-helm.md) tutorial.
+
+## Install Flux with Kustomize
+
+In the next step, deploy Flux to the cluster (you'll need kubectl **1.14** or newer):
+
+```sh
+kubectl apply -k fluxcd
+```
+
+Wait for Flux to start:
+
+```sh
+kubectl -n flux rollout status deployment/flux
+```
+
+## Setup GitHub write access
+
+At startup Flux generates a SSH key and logs the public key. Find
+the SSH public key by installing [fluxctl](../references/fluxctl.md) and
+running:
+
+```sh
+fluxctl identity
+```
+
+In order to sync your cluster state with git you need to copy the
+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 `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.
+
+## Committing a small change
+
+In this example we'll be making a configuration change to a web application
+and display a different message in the UI.
+
+Replace `YOURUSER` in
+`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 `PODINFO_UI_MESSAGE` env var to `Welcome to Flux` and commit the file.
+
+By default, Flux git pull frequency is set to 5 minutes.
+You can tell Flux to sync the changes immediately with:
+
+```sh
+fluxctl sync
+```
+
+## Confirm the change landed
+
+To access our webservice and check out its welcome message, simply
+run:
+
+```sh
+kubectl -n demo port-forward deployment/podinfo 9898:9898 &
+curl localhost:9898
+```
+
+Notice the updated `message` value in the JSON reply.
+
+## Conclusion
+
+As you can see, the actual steps to set up Flux, get our app
+deployed, give Flux access to it and see modifications land are
+very straight-forward and are a quite natural work-flow.
+
+As a next step, you might want to dive deeper into [how to
+control Flux](../references/fluxctl.md), or go through our
+hands-on tutorial about driving Flux, e.g.
+[automations, annotations and locks](driving-flux.md).

docs/tutorials/get-started.md

@@ -32,84 +32,44 @@ extra privileges:
 
 ## Set up Flux
 
-First you'll need a git repository to store your cluster desired state.
-In our example we are going to use [`fluxcd/flux-get-started`](https://github.com/fluxcd/flux-get-started).
-If you want to use that too, be sure to create a fork of it on GitHub.
-
-Create a directory and add the `fluxcd` namespace definition to it:
+Get Flux:
 
 ```sh
-mkdir fluxcd
-
-cat > fluxcd/namespace.yaml <<EOF
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: fluxcd
-EOF
+git clone https://github.com/fluxcd/flux
+cd flux
 ```
 
-Create a kustomization file and use the Flux deploy YAMLs as base:
+Now you can go ahead and edit Flux's deployment manifest. At the very
+least you will have to change the `--git-url` parameter to point to
+the config repository for the workloads you want Flux to deploy for
+you. You are going to need access to this repository.
 
 ```sh
-cat > fluxcd/kustomization.yaml <<EOF
-namespace: fluxcd
-bases:
- - github.com/fluxcd/flux//deploy
-patchesStrategicMerge:
-  - patch.yaml
-EOF
+$EDITOR deploy/flux-deployment.yaml
 ```
 
-> **Note:** If you want to install a specific Flux release,
-> add the version number to the base URL:
-> `github.com/fluxcd/flux//deploy?ref=v1.14.0`
-
-Create a patch file for Flux deployment and set the `--git-url`
-parameter to point to the config repository
-(replace `YOURUSER` with your GitHub username):
-
-```sh
-export GHUSER="YOURUSER"
-cat > fluxcd/patch.yaml <<EOF
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: flux
-spec:
-  template:
-    spec:
-      containers:
-        - name: flux
-          args:
-            - --manifest-generation=true
-            - --memcached-hostname=memcached.fluxcd
-            - --memcached-service=
-            - --ssh-keygen-dir=/var/fluxd/keygen
-            - --git-branch=master
-            - --git-path=namespaces,workloads
-            - --git-user=${GHUSER}
-            - --git-email=${GHUSER}@users.noreply.github.com
-            - --git-url=git@github.com:${GHUSER}/flux-get-started
-EOF
-```
-
-We set `--git-path=namespaces,workloads` to exclude Helm manifests.
-If you want to get started with Helm, please refer to the
-["Get started with Flux using Helm"](get-started-helm.md) tutorial.
+In our example we are going to use [`fluxcd/flux-get-started`](https://github.com/fluxcd/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. After that, set the
+`--git-path` flag to `--git-path=namespaces,workloads`, this is meant
+to exclude Helm manifests. Again, if you want to get started with Helm,
+please refer to the ["Get started with Flux using Helm"](get-started-helm.md)
+tutorial.
 
 ## Deploying Flux to the cluster
 
-In the next step, deploy Flux to the cluster (you'll need kubectl **1.14** or newer):
+In the next step, deploy Flux to the cluster:
 
 ```sh
-kubectl apply -k fluxcd
+kubectl apply -f deploy
 ```
 
-Wait for Flux to start:
+Allow some time for all containers to get up and running. If you're
+impatient, run the following command and see the pod creation
+process.
 
 ```sh
-kubectl -n fluxcd rollout status deployment/flux
+watch kubectl get pods --all-namespaces
 ```
 
 ## Giving write access
@@ -119,7 +79,7 @@ the SSH public key by installing [fluxctl](../references/fluxctl.md) and
 running:
 
 ```sh
-fluxctl --k8s-fwd-ns=fluxcd identity
+fluxctl identity
 ```
 
 In order to sync your cluster state with git you need to copy the
@@ -146,21 +106,23 @@ paste the key there.)
 
 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-get-started` and change the
-`PODINFO_UI_MESSAGE` env var to `Welcome to Flux`.
+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-get-started/blob/master/workloads/podinfo-dep.yaml`
 with your GitHub ID), open the URL in your browser, edit the file,
 change the env var value and commit the file.
 
-By default, Flux git pull frequency is set to 5 minutes.
-You can tell Flux to sync the changes immediately with:
+You can check out the Flux logs with:
 
 ```sh
-fluxctl --k8s-fwd-ns=fluxcd sync
+kubectl -n default logs deployment/flux -f
 ```
 
+The default sync frequency is 5 minutes. This can be tweaked easily.
+By observing the logs you can see when the change landed in in the
+cluster.
+
 ## Confirm the change landed
 
 To access our webservice and check out its welcome message, simply
@@ -171,7 +133,7 @@ kubectl -n demo port-forward deployment/podinfo 9898:9898 &
 curl localhost:9898
 ```
 
-Notice the updated `message` value in the JSON reply.
+Notice the updated `color` value in the JSON reply.
 
 ## Conclusion
 

docs/tutorials/index.rst

@@ -10,3 +10,4 @@ Tutorials
    get-started
    get-started-helm
    driving-flux
+   get-started-kustomize