Karrots Helloworld Example¶

This tutorial will bring up the karrot-helloworld cluster at https://main-karrots-helloworld.<your-domain.com>/karrots.

This is a fully gitops-automated cluster maintained in a single git repo. You will see that pushing changes to that repo automatically updates the running cluster, or through git branching, allows you to quickly bring up new clusters that are functionally equivalent to production. Moreover, you could run the in different regions, AZs or even hosting providers!

Install Karrots Binary¶

brew tap zero-diff/karrots
brew install karrots
karrots --help

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B4D285C0003B4D71
sudo add-apt-repository "deb https://zero-diff.github.io/karrots/debian-repo/ karrots-github main"
sudo apt-get install karrots
karrots --help

Karrots Seed (Create the Gitops Repo)¶

We need to change to the parent directory where we want to create our FluxCD gitops repo.

cd ~/git

From this repo directory, execute the seed command:

karrots seed --directory=karrots_cluster

Karrots will prompt you for a git URL where you want to push your seed repo:

✗ Git URL for your new karrots-cluster gitops seed repo: █it@github.com:<userid>/git.git

Karrots pre-populates the URL with github.com and a repo name that matches the seed directory. You can change this URL to fit your needs, but at the very least you need to change <userid>.

Karrots will the prompt you for a Github access token that has r/w capability. We need this so we can push seed repo changes to remote/origin in your Github account.

✔ Github access token (with r/w permission):

Karrots creates a new directory and populates it using the Karrots-Seed Github repo as a template. Once the karrots-seed command completes, the directory will have the following structure:

clusters/
  all/
    deployments/
    charts/
    helm-releases/
    resources/
  karrots-helloworld/
    deployments/
    charts/
    helm-releases/
    resources/
    karrots.yaml
docs/
karrots.yaml
README.md

This is a gitops-ready repo that contains two important directories that drives cluster automation via Flux/CD.

clusters/all:

This directory contains the services and resources that FluxCD applies to all clusters. The charts and helm-releases directories come populated with everything needed to bring up the base cluster services listed in: Base Services Inventory

clusters/karrots-helloworld:

This directory contains the services and resources that FluxCD applies to the karrots-helloworld cluster. It also contains the starting karrots.yaml file. The seed karrots.yaml file is self-explanatory, so edit the values as they make sense for your hosting provider account and project.

cd clusters/karrots-helloworld
vi karrots.yaml

Karrots Create Cluster¶

Once you have finished editing karrots.yaml, then execute the following command from the karrots-helloworld directory:

karrots create-cluster

Karrots will prompt you for a cluster-name. The default is the <git branch name>—<seed dir name>:

✔ Choose a cluster-name (this is also the cluster's dns hostname): █ain-karrots-helloworld

Karrots will the prompt you for a Github access token that has r/w capability. We need this so we push Gitops setup changes remote/origin in your Github account.

✔ Github access token (with r/w permission):

Karrots will prompt you for a base-64 encoded sealed-secrets public certificate. Since we're not using sealed-secrets, just press enter.

Enter sealed-secret cert (base64 encoded):

Karrots will prompt you for a base-64 encoded sealed-secrets private key. Since we're not using sealed-secrets, just press enter.

Enter sealed-secret key (base64 encoded):

At this point, Karrots will build and process all of the Terraform needed to build your cluster. It will execute that using terraform apply and you will eventually see this prompt:

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

Type yes at this prompt, and Terraform will build your cluster and push a sanitized (no secrets/tokens) state file to the repo's remote/origin.

Behind the scenes, Karrots does the following:

1. Create a tmp directory
2. Populate tmp with Terraform scripts customized to build this cluster
3. Run terraform init in the tmp directory to setup the workspace
4. Run terraform plan in the tmp directory to verify the setup
5. Add, commit and push all changes from the local repo to the remote/origin repo
6. Run terraform apply in the tmp directory to build the cluster
7. Create a sanitized Terraform state file (with no secrets) and push that to the remote/origin
8. Test that the cluster has come up

In about 15 minutes you should have a fully operational Kubernetes cluster with gitops-automation. The cluster will run FluxCD which will bring up the Karrots base services (Ambassador, Istio, etc) and the Karrots Test app. If you visit https://main-karrots-helloworld.<your-domain.com>/karrots. You should see the message:

Welcome to Karrots-HelloWorld version 0.1.0

Push a Change to your New Karrots-HelloWorld Cluster¶

At this point your karrots-helloworld cluster is running with FluxCD gitops automation. In the cluster, FluxCD periodically scans the central git repo, e.g. at Github, to determine if there are differences between the repo and the running cluster. If it detects differences, for example the cluster is one git commit behind the repo, FluxCD will apply those changes to the cluster. In this example step we will push a change to the remote repo to see that the cluster detects the change and updates itself shortly after.

To update the Karrots deployment running in the cluster, you change it's helm-release and then push the change to the remote repo:

vi helm-releases/karrots-helloworld/karrots-helloworld.yaml

In the karrots-helloworld.yaml we will change the Karrots Test release container from v0.1.0 to v0.2.0 by setting image:tag to 0.2.0 . See the note near the bottom of the YAML file.

---
apiVersion: helm.fluxcd.io/v1
kind: HelmRelease
metadata:
  name: karrots-helloworld
  namespace: karrots-helloworld
  labels:
    revision: "1"
  annotations:
    fluxcd.io/automated: "true"
spec:
  releaseName: karrots-helloworld
  chart:
    git: git@github.com:zero-diff/karrots-helloworld
    path: clusters/karrots-helloworld/charts/karrots-helloworld
    version: 1.0.0
  values:
    serviceAccount:
      create: false
    springProfile: dev
    image:
      repository: us.gcr.io/zero-diff-karrots/karrots-helloworld
      tag: 0.1.0 # <-- change this to 0.2.0
    replicaCount: 1

To bring this change live you add, commit and push the change:

git add karrots-helloworld.yaml
git commit -m "Upgrade karrots-helloworld to v0.2.0"
git push origin/main

A few minutes later FluxCD will detect this change and apply it to the cluster. If you visit https://main-karrots-helloworld.<your-domain.com>/karrots. You should now see the message:

Welcome to Karrots-HelloWorld version 0.2.0

Wrapping up: Destroy the Cluster¶

We haven't spent too much money running these clusters for the last few hours, but you may want to bring them down until you're ready to adopt Karrots for real in your software delivery pipeline. From the same karrots-helloworld directory, execute the following command:

karrots destroy-cluster

This command will prompt the same set of questions as when we ran create-cluster and it uses those values to recreate a Terraform state file from our sanitized version.

Behind the scenes, Karrots does the following:

1. Create a tmp directory
2. Populate tmp with Terraform scripts customized to build this cluster
3. Reconstitute the Terraform state file from our sanitized version in the git repo
4. Run terraform init in the tmp directory to setup the workspace
5. Run terraform refresh in the tmp directory to update our reconstituted state file
6. Run terraform destroy in the tmp directory to destroy the cluster

It takes about 15 minutes to destroy all of the cluster resources.