updated documentation

README.md

@@ -1,12 +1,14 @@
 ## Laravel 5-5 example ##
 
-**Laravel 5-5 example** is a tutorial application showing how to run and maintain laravel on kubernetes. It will allow you to quickly get a database and SSL-enabled wepage working within 10 minutes which can then be tailored to your requirements.
+**Laravel 5-5 example** is a tutorial application showing how to run and maintain laravel on kubernetes. It will allow you to quickly get a database and SSL-enabled wepage with a database and sticky sessions  working within 10 minutes which can then be tailored to your requirements.
 
 Suggested improvements are welcome as are PRs. There isn't much available online for laravel + kubernetes together, however this presentation is probably the best material <https://www.slideshare.net/WilliamStewart20/kubernetes-laravel-and-kubernetes> and the following tutorial from Bitnami is useful also <https://docs.bitnami.com/kubernetes/how-to/deploy-php-application-kubernetes-helm/>.
 
 ## Prerequisities ##
-This tutorial assumes you have access to a cloud-based cluster with kubernetes v1.9 or higher (e.g. GKE, ACS-engine or AWS - Google Kubernetes Engine's free trial is the easiest to setup and a 3*N1-Standard-1 is sufficient). A domain URL and ability to change DNS A records is also assumed. Nginx-ingress for tls termination is used.
-Helm (`brew install kubernetes-helm` >v2.8.2) and kubectl (`brew install kubectl` >1.9.3) are assumed to be installed and pointing at your cluster. A common pitfall for new users to helm is Role-Based-Access-Control, so if you're new to helm, you should give helm the required access with `kubectl apply -f kubernetes/kubernetes-yaml/rbac-tiller.yaml` and then use `helm init --service-account tiller`.
+This tutorial assumes you have access to a cloud-based cluster with kubernetes v1.9 or higher (e.g. GKE (tested on v1.9.3), ACS-engine or AWS - Google Kubernetes Engine's free trial is the easiest to setup and a 3*N1-Standard-1 is sufficient). A domain URL and ability to change DNS A records is also assumed. Nginx-ingress for tls termination is used.
+Kubectl (`brew install kubectl` >=1.9.3) and helm (`brew install kubernetes-helm` >=2.8.2) is assumed to be installed and pointing at your cluster.
+
+Everything in this tutorial is created in the laravel5 namespace. The namespace can simply be deleted at the end to tidy up. This is a useful approach for a branch-based environment setup.
 
 ## Installation ##
 
@@ -18,6 +20,30 @@ git clone https://github.com/EamonKeane/larvel5-5-example
 cd laravel5-5-example
 ```
 
+* Create laravel5 namespace
+
+```bash
+kubectl create namespace laravel5
+```
+
+* Install the RBAC for helm to create a cluster admin role in the laravel5 namespace
+
+```bash
+kubectl apply -f kubernetes/kubernetes-yaml/rbac-tiller.yaml
+```
+
+* Install helm in the laravel5 namespace
+
+```bash
+helm init --tiller-namespace laravel5 --service-account tiller
+```
+
+* Set the tiller namespace environment variable (to prevent having to use `--tiller-namespace` in all command as it defaults to `kube-system`)
+
+```bash
+export TILLER_NAMESPACE=laravel5
+```
+
 * check that  helm and kubectl are on the right versions on the server and locally
 
 ```bash
@@ -30,7 +56,6 @@ Server: &version.Version{SemVer:"v2.8.2", GitCommit:"a80231648a1473929271764b920
 kubectl version
 Client Version: version.Info{Major:"1", Minor:"9", GitVersion:"v1.9.3", GitCommit:"d2835416544f298c919e2ead3be3d0864b52323b", GitTreeState:"clean", BuildDate:"2018-02-09T21:51:54Z", GoVersion:"go1.9.4", Compiler:"gc", Platform:"darwin/amd64"}
 Server Version: version.Info{Major:"1", Minor:"9+", GitVersion:"v1.9.3-gke.0", GitCommit:"a7b719f7d3463eb5431cf8a3caf5d485827b4210", GitTreeState:"clean", BuildDate:"2018-02-16T18:26:01Z", GoVersion:"go1.9.2b4", Compiler:"gc", Platform:"linux/amd64"}
-
 ```
 
 * Specify your domain:
@@ -45,7 +70,7 @@ MY_URL=laravel2.squareroute.io # change this to your domain
 helm install stable/nginx-ingress --name nginx-ingress --namespace laravel5 --set rbac.create=true,controller.service.externalTrafficPolicy=Local
 ```
 
-* Add your nginx-ingress IP address as a DNS A record pointing to your laravel URL:
+* Add your nginx-ingress IP address (this takes circa 2 minutes to populate `watch kubectl get svc --namespace laravel5`) as a DNS A record pointing to your laravel URL:
 
 ```bash
 INGRESS_IP=$(kubectl get svc --namespace laravel5 --selector=app=nginx-ingress,component=controller -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}');echo ${INGRESS_IP}
@@ -87,21 +112,11 @@ MY_NGINX_REPO=quay.io/eamonkeane/laravel-nginx
 * Build and push the docker images. This tutorial assumes the respositories are publicly accessible.
 
 ```bash
-docker build . -t ${MY_PHP_REPO}:latest -f docker/php-fpm/Dockerfile; docker push {MY_PHP_REPO}:latest
-```
-
-```bash
-docker build . -t ${MY_NGINX_REPO}:latest -f docker/nginx/Dockerfile; docker push {MY_NGINX_REPO}:latest
-```
-
-* Replace the images in the helm chart with the ones you have built:
-
-```bash
-sed -i '' -e "s#quay.io/eamonkeane/laravel#${MY_PHP_REPO}#g" kubernetes/helm/laravel5/values.yaml
+docker build . -t ${MY_PHP_REPO}:latest -f docker/php-fpm/Dockerfile; docker push ${MY_PHP_REPO}:latest
 ```
 
 ```bash
-sed -i '' -e "s#quay.io/eamonkeane/laravel#${MY_NGINX_REPO}#g" kubernetes/helm/laravel5/values.yaml
+docker build . -t ${MY_NGINX_REPO}:latest -f docker/nginx/Dockerfile; docker push ${MY_NGINX_REPO}:latest
 ```
 
 * Replace the URL in the .env with your url. Note the .env is kept in the helm folder for convenience to make the secret as part of this tutorial. If using this for production, make the secrets separately using `kubectl create secret generic ${SECRET_NAME} --from-file=${SECRET_FILE}` or use a tool to encrypt the secrets such as helm secrets: <https://github.com/futuresimple/helm-secrets>.
@@ -144,7 +159,7 @@ The helm chart contains the following features which are relevant to laravel:
 
 * Configuration files (nginx.conf and laravel-site.conf) are kept in the helm folder (helm can't access files outside this folder) and the configmap is updated each time the deployment is triggered.
 
-* Configmap changes to nginx trigger an upgrade of the nginx deployment
+* Configmap changes trigger an upgrade to the deployment
 
 * Session affinity is preserved using the nginx 'sticky session' which adds a cookie to the header to store the session.
 

kubernetes/kubernetes-yaml/rbac-tiller.yaml

@@ -2,7 +2,7 @@ apiVersion: v1
 kind: ServiceAccount
 metadata:
   name: tiller
-  namespace: kube-system
+  namespace: laravel5
 ---
 kind: ClusterRoleBinding
 apiVersion: rbac.authorization.k8s.io/v1beta1
@@ -11,7 +11,7 @@ metadata:
 subjects:
 - kind: ServiceAccount
   name: tiller
-  namespace: kube-system
+  namespace: laravel5
 roleRef:
   kind: ClusterRole
   name: cluster-admin