Running Kind

Requirements

This project has been configured to run in a Kubernetes (k8s) environment. A decision was made to use KIND for the local k8s environment. Any k8s environment would work after careful setup of your k8s cluster. This section is not going to talk about installing your own k8s environment. Instead, it will focus on using KIND for your k8s environment, setting up your cluster there and deploying and running the project locally. The project also uses Kustomize to help manage k8s configuration files.

To install KIND follow these instructions.

To install the K8s kubectl client follow these instructions.

To install the Kustomize client follow these instructions.

Make sure Docker is running with at least 4 CPUs.

To instll the Vault client follow these instructions.

User Installation

You can run this make command to use brew to install all the software above.

make dev.setup.mac

Image Installation

You can run this make command to use docker pull to download all the images.

make dev.docker

Commands

Run these commands in the order they are presented.

make all

This command builds all the containers for use in the K8s cluster.

$ make all

make kind-up

This command will start the cluster via Docker. It assigns the name ardan-starter-cluster to the cluster and configures the cluster to run as a single Node for simplicity. It also opens all ports for easy development access.

$ make kind-up

kind create cluster \
	--image kindest/node:v1.21.1@sha256:69860bda5563ac81e3c0057d654b5253219618a22ec3a346306239bba8cfa1a6 \
	--name ardan-starter-cluster \
	--config zarf/k8s/kind/kind-config.yaml
kubectl config set-context --current --namespace=sales-system

make kind-down

This command will delete the KIND cluster and everything inside of it.

$ make kind-down

kind delete cluster --name ardan-starter-cluster

make kind-load

This command loads the sales-api and metrics containers into the k8s environment. The zipkin and postgres containers don't need to be loaded since K8s can find them in the Docker registry.

$ make kind-load

kind load docker-image sales-api-amd64:1.0 --name ardan-starter-cluster
kind load docker-image metrics-amd64:1.0 --name ardan-starter-cluster

make kind-apply

This command deploys two PODS into the cluster. One POD is for the Postgres database and the second POD contains the sales-api, metrics and zipkin services.

$ make kind-apply

kustomize build zarf/k8s/kind/database-pod | kubectl apply -f -
kubectl wait --namespace=database-system --timeout=120s --for=condition=Available deployment/database-pod
kustomize build zarf/k8s/kind/sales-pod | kubectl apply -f -

make kind-logs

This command shows the logs from the services running inside the sales-api POD. This will show the current logs and maintain the watch.

$ make kind-logs

kubectl logs -l app=sales --all-containers=true -f --tail=100 | go run app/logfmt/main.go


$ make kind-logs-sales

kubectl logs -l app=sales --all-containers=true -f --tail=100 | go run app/logfmt/main.go -service=SALES-API

make kind-status

The command provides status information about the cluster. It is useful when loading new instances of the services.

$ make kind-status

kubectl get nodes -o wide
kubectl get svc -o wide
kubectl get pods -o wide --watch --all-namespaces

make kind-describe

The command provides detailed information about the services running inside the sales-api pod. Useful for debugging loading issues.

$ make kind-describe

kubectl describe nodes
kubectl describe svc
kubectl describe pod -l app=sales

make kind-update

This command provides a mechanism for building, loading and updating code changes from the sales-api service inside the running k8s environment.

$ make kind-update

-- Builds new docker image for the `sales-api`
kind load docker-image sales-api-amd64:1.0 --name ardan-starter-cluster
kubectl rollout restart deployment sales-pod

Seed Database

You are now ready to test if the system is operational. The sales-api service will migrate and seed the databse on startup. If you want to manually migrate or seed the database, you can use these two commands.

$ make migrate
$ make seed

The call to seed will call migrate first.

Authenticated Requests

Before any requests can be sent you must acquire an auth token. Make a request using HTTP Basic auth with the test user email and password to get the token.

$ curl --user "[email protected]:gophers" http://0.0.0.0:3000/v1/users/token

I suggest putting the resulting token in an environment variable like $TOKEN.

$ export TOKEN="COPY TOKEN STRING FROM LAST CALL"

To make authenticated requests put the token in the Authorization header with the Bearer prefix.

$ curl -H "Authorization: Bearer ${TOKEN}" http://0.0.0.0:3000/v1/users/1/2

Run Load

If you want to run a little load on the service you can use hey.

$ hey -H "Authorization: Bearer ${TOKEN}" -c 100 -n 10000 http://0.0.0.0:3000/v1/users/1/2

View Traces

If you want to see a few of the traces generated.

http://localhost:9411/zipkin/