🚀 PhEMA Deployments

Config for GitOps deployments

This repository contains deployment configs for PhEMA deployments. The intention is for each deployment to have all the necessary config in its own directory. For example, phex/dev contains everything necessary to recreate the PhEx development server deployment.

Overview

The main idea is to use GitOps to easily automate deployments. Our software libraries and applications are automatically published to publicly accessibly servers when tags are pushed to their respective repos, which is achieved via their Travis configs (e.g. here). We then describe the desired end state of our deployments using Kubernetes resources and Helm charts in this repository. Finally, we run the Flux agent in a Kubernetes cluster configured to watch a specific path in this repository. Flux will take care of making sure the deployed config matched what is in this repo.

Setup

There are few manual steps to get started. These docs will assume you have a Linux VM already provisioned, with ports 80, 443, and 22 open.

Install Docker

The first step is to install Docker. The Community Edition is sufficient. There are install instructions for many platforms here. The Ubuntu install instructions are here.

Setup Cluster

The next step is to set up the Kubernetes cluster. First, install kubeadm by following the instructions here.

Initialize the cluster:

$ sudo kubeadm init

Then, do what it says at the end of the output, which will be something like:

$ mkdir -p $HOME/.kube
$ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
$ sudo chown $(id -u):$(id -g) $HOME/.kube/config

The output will direct you here and tell you to install a network manager, plugin. To install the weave network manager, run:

$ kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$(kubectl version | base64 | tr -d '\n')"

Install Helm

Next, install Helm by following these instructions. Then configure it:

$ kubectl -n kube-system create sa tiller

$ kubectl create clusterrolebinding tiller-cluster-rule \
    --clusterrole=cluster-admin \
    --serviceaccount=kube-system:tiller

Then install Tiller, the in-cluster Helm agent into the cluster:

$ helm init --skip-refresh --upgrade --service-account tiller --history-max 10

Install Flux

Install Flux using Helm:

$ helm repo add fluxcd https://charts.fluxcd.io

Install the Flux custom resource definitions (CRDs):

kubectl apply -f https://raw.githubusercontent.com/fluxcd/flux/helm-0.10.1/deploy-helm/flux-helm-release-crd.yaml

Finally, install Flux to watch a specific path in this repo:

helm upgrade -i flux \
	--set helmOperator.create=true \
	--set helmOperator.createCRD=false \
	--set git.url=git@github.com:phema/deployments \
	--set git.path="phex/dev" \
	--namespace flux \
	fluxcd/flux

💡 Note the phex/dev value for the git.path parameter. Only resources at that path in this repo will be synchronized to the cluster.

🔐 Install `cert-manager`

If you intend to use cert-manager to generated certificates (recommended), then also install the cert-manager CRDs:

kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml

You can now begin adding Kubernetes resources to the appropriate path in this repo and Flux will deploy them to the cluster.

Troubleshooting

It is highly recommend to install stern for Kubernetes logging.

If you need to completely reset the cluster, you can run:

$ sudo kubeadm reset -f

$ rm -rf $HOME/.kube

PheMA/deployments