Update minikube docs post rename

The docs for setting up minikube were using the namespaces and resource names from elafros instead of knative. The naming changed slightly, e.g. a knative controller is now called `controller` instead of `knative-serving-controller`, so one of the loops had to be broken into 2 statements. Added steps about redeploying pods after setting up GCR secrets b/c there is a chicken and egg problem where the namespaces must exist before you can setup the secrets, but the secrets must exist before the images can be pulled. The PR that enabled `MutatingAdmissionWebhook` by default (kubernetes/minikube#2547) was merged, but the latest minikube (0.28.0) still did not enable this option by default b/c providing any arugments overrides all of the defaults, so we must still set it explicitly. Made it clear in the setting up knative serving docs that the cluster admin binding is required, not just for istio.
knative · Jun 23, 2018 · c9fcbc0 · c9fcbc0
1 parent ce85002
commit c9fcbc0
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 43 deletions.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -99,19 +99,33 @@ Once you reach this point you are ready to do a full build and deploy as describ
 
 ## Starting Knative Serving
 
-Once you've [setup your development environment](#getting-started), stand up `Knative Serving` with:
+Once you've [setup your development environment](#getting-started), stand up
+`Knative Serving` by:
 
-### Deploy Istio
+1. [Making your user a cluster admin](#setup-cluster-admin)
+1. [Deploying istio](#deploy-istio)
+1. [Deploy build](#deploy-build)
+1. [Deploy Knative Serving](#deploy-knative-serving)
+1. [Enable log and metric collection](#enable-log-and-metric-collection)
+
+### Setup cluster admin
+
+Your `$K8S_USER_OVERRIDE` must be a cluster admin to perform
+the setup needed for Knative:
 
 ```shell
 kubectl create clusterrolebinding cluster-admin-binding \
   --clusterrole=cluster-admin \
   --user="${K8S_USER_OVERRIDE}"
+```
 
+### Deploy Istio
+
+```shell
 kubectl apply -f ./third_party/istio-0.8.0/istio.yaml
 ```
 
-Then label namespaces with `istio-injection=enabled`:
+Optionally label namespaces with `istio-injection=enabled`:
 
 ```shell
 kubectl label namespace default istio-injection=enabled

diff --git a/docs/creating-a-kubernetes-cluster.md b/docs/creating-a-kubernetes-cluster.md
@@ -86,37 +86,62 @@ To use a k8s cluster running in GKE:
 1.  [Create a cluster](https://github.com/kubernetes/minikube#quickstart) with
     version 1.10 or greater and your chosen VM driver:
 
-    _Until minikube [enables it by
-    default](https://github.com/kubernetes/minikube/pull/2547),the
-    MutatingAdmissionWebhook plugin must be manually enabled._
+    _Providing any admission control pluins overrides the default set provided
+    by minikube so we must explicitly list all plugins we want enabled._
 
     _Until minikube [makes this the
     default](https://github.com/kubernetes/minikube/issues/1647), the
     certificate controller must be told where to find the cluster CA certs on
     the VM._
 
-For Linux use:
-
-```shell
-minikube start --memory=8192 --cpus=4 \
-  --kubernetes-version=v1.10.4 \
-  --vm-driver=kvm2 \
-  --bootstrapper=kubeadm \
-  --extra-config=controller-manager.cluster-signing-cert-file="/var/lib/localkube/certs/ca.crt" \
-  --extra-config=controller-manager.cluster-signing-key-file="/var/lib/localkube/certs/ca.key" \
-  --extra-config=apiserver.admission-control="DenyEscalatingExec,LimitRanger,NamespaceExists,NamespaceLifecycle,ResourceQuota,ServiceAccount,DefaultStorageClass,MutatingAdmissionWebhook"
-```
-For macOS use:
-
-```shell
-minikube start --memory=8192 --cpus=4 \
-  --kubernetes-version=v1.10.4 \
-  --vm-driver=hyperkit \
-  --bootstrapper=kubeadm \
-  --extra-config=controller-manager.cluster-signing-cert-file="/var/lib/localkube/certs/ca.crt" \
-  --extra-config=controller-manager.cluster-signing-key-file="/var/lib/localkube/certs/ca.key" \
-  --extra-config=apiserver.admission-control="DenyEscalatingExec,LimitRanger,NamespaceExists,NamespaceLifecycle,ResourceQuota,ServiceAccount,DefaultStorageClass,MutatingAdmissionWebhook"
-```
+    For Linux use:
+
+    ```shell
+    minikube start --memory=8192 --cpus=4 \
+    --kubernetes-version=v1.10.4 \
+    --vm-driver=kvm2 \
+    --bootstrapper=kubeadm \
+    --extra-config=controller-manager.cluster-signing-cert-file="/var/lib/localkube/certs/ca.crt" \
+    --extra-config=controller-manager.cluster-signing-key-file="/var/lib/localkube/certs/ca.key" \
+    --extra-config=apiserver.admission-control="DenyEscalatingExec,LimitRanger,NamespaceExists,NamespaceLifecycle,ResourceQuota,ServiceAccount,DefaultStorageClass,MutatingAdmissionWebhook"
+    ```
+    For macOS use:
+
+    ```shell
+    minikube start --memory=8192 --cpus=4 \
+    --kubernetes-version=v1.10.4 \
+    --vm-driver=hyperkit \
+    --bootstrapper=kubeadm \
+    --extra-config=controller-manager.cluster-signing-cert-file="/var/lib/localkube/certs/ca.crt" \
+    --extra-config=controller-manager.cluster-signing-key-file="/var/lib/localkube/certs/ca.key" \
+    --extra-config=apiserver.admission-control="DenyEscalatingExec,LimitRanger,NamespaceExists,NamespaceLifecycle,ResourceQuota,ServiceAccount,DefaultStorageClass,MutatingAdmissionWebhook"
+    ```
+1.  [Configure your shell environment](../DEVELOPMENT.md#environment-setup)
+    to use your minikube cluster:
+
+    ```shell
+    export K8S_CLUSTER_OVERRIDE='minikube'
+    # When using Minikube, the K8s user is your local user.
+    export K8S_USER_OVERRIDE=$USER
+    ```
+
+1.  [Start Knative Serving](../DEVELOPMENT.md#starting-knative-serving).
+
+1.  Setup secrets for accessing an image registry from within your
+    cluster, e.g. [GCR](#minikube-with-gcr).
+
+1.  Recreate the knative pods once your image registry secrets are set up
+    so that the images can be pulled, e.g.:
+
+    ```shell
+    ko delete -f config/controller.yaml
+    ko delete -f config/webhook.yaml
+    ko delete -f config/activator.yaml
+
+    ko apply -f config/controller.yaml
+    ko apply -f config/webhook.yaml
+    ko apply -f config/activator.yaml
+    ```
 
 ### Minikube with GCR
 
@@ -175,12 +200,13 @@ _This is only necessary if you are not using public Knative Serving and Build im
 1.  Create a Kubernetes secret in the `knative-serving-system` and `build-system` namespace:
 
     ```shell
-    for prefix in ela build; do
-      kubectl create secret docker-registry "gcr" \
+    export [email protected]
+    for prefix in knative-serving build; do
+      kubectl create secret docker-registry "${prefix}-gcr" \
         --docker-server=$GCR_DOMAIN \
         --docker-username=_json_key \
         --docker-password="$(cat minikube-gcr-key.json)" \
-        --docker-email=[email protected] \
+        --docker-email=$DOCKER_EMAIL \
         -n "${prefix}-system"
     done
     ```
@@ -192,19 +218,13 @@ _This is only necessary if you are not using public Knative Serving and Build im
     `build-controller` service accounts:
 
     ```shell
-    for prefix in ela build; do
-      kubectl patch serviceaccount "${prefix}-controller" \
-        -p '{"imagePullSecrets": [{"name": "gcr"}]}' \
-        -n "${prefix}-system"
-    done
+    kubectl patch serviceaccount "build-controller" \
+      -p '{"imagePullSecrets": [{"name": "build-gcr"}]}' \
+      -n "build-system"
+    kubectl patch serviceaccount "controller" \
+      -p '{"imagePullSecrets": [{"name": "knative-serving-gcr"}]}' \
+      -n "knative-serving-system"
     ```
-
-1.  Add to your .bashrc:
-    ```shell
-    # When using Minikube, the K8s user is your local user.
-    export K8S_USER_OVERRIDE=$USER
-    ```
-
 Use the same procedure to add imagePullSecrets to service accounts in any
 namespace. Use the `default` service account for pods that do not specify a
 service account.