Getting Started with Project Syn

This guide provides an introduction to Project Syn and its various tools. It targets DevOps engineers in charge of large numbers of Kubernetes clusters.

Video

The contents of this guide are available as a video on the VSHN YouTube channel at VSHN.tv.

Why Project Syn?

You are a DevOps engineer in charge of many Kubernetes clusters. You must manually keep them up-to-date, deploy applications in some or all of them, schedule backups, and ensure that all security policies are applied and working. You’re overworked and need urgent help.

To make your job easier, you would need:

  1. A "single point of truth" for your clusters, acting like a "cluster database," including information about each managed cluster: its location, installed applications, settings, and secrets.

  2. An "agent" in each cluster, proactively listening for changes in the central catalog and performing modifications as required.

  3. Finally, a tool to modify the clusters' configuration, updating the clusters' catalog (the Kubernetes objects applied to the cluster).

Project Syn provides the tools to help you manage many Kubernetes clusters from a central location:

  1. Lieutenant keeps the inventory of tenants and clusters, using a set of Git repositories as the storage for configurations and catalogs;

  2. Steward acts as the cluster agent, wrapping Argo CD, who keeps an eye on the clusters' catalog Git repository;

  3. And Commodore serves as the tool used to update a cluster catalog from its configuration.

In this guide, we’re going to focus on Lieutenant and Steward. The second part will focus on Commodore.

Requirements

Before you start, please check the following requirements:

Modify your /etc/hosts file and add the following entry:

127.0.0.1       host.k3d.internal

Launch two new K3s clusters with k3d:

k3d cluster create lieutenant --port "35777:8080@loadbalancer" --image=rancher/k3s:v1.23.8-k3s1

and

k3d cluster create steward  --port "35778:8080@loadbalancer" --image=rancher/k3s:v1.23.8-k3s1

In your GitLab account, create a token with the 'API' scope at gitlab.com/-/profile/personal_access_tokens.

Create the following environment variables. The GITLAB_TOKEN variable contains the value of the token created previously.

export GITLAB_USERNAME=johndoe        # Use your own GitLab username
export GITLAB_ENDPOINT=gitlab.com     # Or your own GitLab instance URL (without the "https://" prefix)
export GITLAB_TOKEN=xxxxxxxxxxxxxxxx

Lieutenant

Lieutenant is the central inventory service for all Project Syn-managed clusters. It consists of an API and an Operator. Lieutenant needs API access to a GitLab server to create and manage Git repositories for clusters and tenants. Lieutenant usually runs in a dedicated Kubernetes cluster, used only to expose its API.

Lieutenant is the central API for all other Project Syn tools. Therefore we will install it first so that all other components can do their job.

Install Lieutenant on the "k3d-lieutenant" cluster with the following command:

curl -fsL https://try.syn.tools/lieutenant | bash

At the end of this procedure, you will have a K3s cluster named "k3d-lieutenant" on your computer, running the Lieutenant API and Operator.

You can explore Lieutenant using kubectl get tenants:

kubectl --context k3d-lieutenant -n lieutenant get tenants

The command above produces output similar to the following:

NAME             DISPLAY NAME         AGE
t-aged-pond-24   Project Syn Tenant   13s

In the context of Project Syn, a "tenant" is an entity to whom clusters are assigned. Tenants could be customers, departments, teams, or any entity owning a cluster.

Project Syn stores cluster-specific configuration values in that tenant’s own configuration Git repository. You should now have a new project in your GitLab account called "Project Syn Tenant."

Steward

Steward is the in-cluster agent of Project Syn. It runs in each cluster associated with a tenant, automatically reacting to changes in the catalog Git repository belonging to that cluster.

Install Steward in K3s with one simple command:

curl -fsL https://try.syn.tools/steward | bash

The installation of Steward happens on the K3s cluster "k3d-steward" via an install URL provided by Lieutenant, using a one-time bootstrap token. The token is valid only once and up to 24 hours after cluster registration.

Once Steward is installed on the K3s cluster "k3d-steward," you can see its pods running, including some whose names start with the argocd- prefix:

NAME                                  READY   STATUS    RESTARTS   AGE
steward-dd5b6f897-wsglm               1/1     Running   0          88s
argocd-redis-6d65dbd578-d2znt         1/1     Running   0          59s
argocd-server-b5f6b5cff-vqq5x         1/1     Running   0          59s
argocd-repo-server-569b975697-647r4   1/1     Running   0          59s
argocd-application-controller-0       1/1     Running   0          57s

At this point, Lieutenant is aware of the new K3s cluster, and we can see that through the kubectl get clusters command:

kubectl --context k3d-lieutenant -n lieutenant get clusters

The command above outputs something similar to this:

NAME                  DISPLAY NAME          TENANT                  AGE
c-long-firefly-9017   Project Syn Cluster   t-autumn-silence-6912   12s

Cluster names have the c- prefix, while tenant names have with t- prefix.

Accessing Argo CD

As you have seen above, Steward wraps Argo CD, a Cloud-Native continuous deployment and integration tool, continuously observing the GitLab repositories for changes.

You can also connect to Argo CD and see its console. Start by exposing the argocd-server deployment:

kubectl --context k3d-steward -n syn expose deployment argocd-server --type=LoadBalancer --port=8080 --name=argocd-server-lb --overrides='{"metadata":{"labels":{"argocd.argoproj.io/instance":null}}}'

Open Argo CD in your browser at localhost:35778. Log in to Argo CD with the username admin and the password returned by this command:

kubectl --context k3d-steward -n syn get secret steward -o json | jq -r .data.token | base64 --decode

After these steps, the local K3s cluster is now Syn enabled, and a Git repository called "Project Syn Cluster" is available in GitLab. It’s worth pointing out that Argo CD hasn’t yet synchronized any changes, and the GitLab repository is empty.

What’s Next?

This guide provided a quick overview of Lieutenant and Steward. If you are interested in knowing more about Project Syn, proceed to the second part to learn about Commodore, the third major component of Project Syn.

Please don’t execute the steps in the following "Cleaning Up" section if you intend to perform the actions of the second part of this guide. We will reuse the clusters in their current state.

Cleaning Up

If you don’t wish to proceed to the second part of this tutorial, you can clean up all generated clusters and GitLab projects using the following steps:

  1. Delete the cluster and tenant objects, removing the GitLab projects at the same time:

    curl -fsL https://try.syn.tools/cleanup | bash

  2. Remove the K3d clusters:

    k3d cluster delete --all