From 2301603eb1fcadfd47300e192b27c90c9c6f9322 Mon Sep 17 00:00:00 2001 From: Eamon Keane Date: Thu, 29 Mar 2018 18:30:14 +0100 Subject: [PATCH] updated documentation --- README.md | 51 +++++++++++++-------- kubernetes/kubernetes-yaml/rbac-tiller.yaml | 4 +- 2 files changed, 35 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 3f81a5b..553932c 100644 --- a/README.md +++ b/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 and the following tutorial from Bitnami is useful also . ## 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: . @@ -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. diff --git a/kubernetes/kubernetes-yaml/rbac-tiller.yaml b/kubernetes/kubernetes-yaml/rbac-tiller.yaml index 2d883bf..cc232ac 100644 --- a/kubernetes/kubernetes-yaml/rbac-tiller.yaml +++ b/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