There are currently 2 different types of configuration available with this template.
- "Bare cluster" - Talos that comes with Cilium installed in the cluster.
- "Flux cluster" - Add-on to the "Bare cluster" to deploy an opinionated implementation of Flux using GitHub as GitOps provider and sops to manage secrets.
Each configuration will allow you to activate Renovate which will help manage dependencies via pull requests.
-
Download the latest stable release of Talos from their GitHub releases. You will want to grab either
metal-amd64.iso
ormetal-rpi_generic-arm64.raw.xz
depending on your system. -
Take note of the OS drive serial numbers you will need them later on.
-
Flash the iso or raw file to a USB drive and boot to Talos on your nodes with it.
-
Continue on to π Getting Started
Once you have installed Talos on your nodes, there are six stages to getting a Flux-managed cluster up and runnning.
Note
For all stages below the commands MUST be ran on your personal workstation within your repository directory
-
Create a new public repository by clicking the big green "Use this template" button at the top of this page.
-
Clone your new repo to you local workstation and
cd
into it. -
Continue on to π± Stage 2
You have two different options for setting up your local workstation.
- First option is using a
devcontainer
which requires you to have Docker and VSCode installed. This method is the fastest to get going because all the required CLI tools are provided for you in my devcontainer image. - The second option is setting up the CLI tools directly on your workstation.
-
Start Docker and open your repository in VSCode. There will be a pop-up asking you to use the
devcontainer
, click the button to start using it. -
Continue on to π§ Stage 3
-
Install the most recent version of task, see the installation docs for other supported platforms.
# Homebrew brew install go-task # or, Arch pacman -S --noconfirm go-task && ln -sf /usr/bin/go-task /usr/local/bin/task
-
Install the most recent version of direnv, see the installation docs for other supported platforms.
# Homebrew brew install direnv # or, Arch pacman -S --noconfirm direnv
π After
direnv
is installed be sure to hook it into your preferred shell and then runtask workstation:direnv
-
Install the additional required CLI tools
π Not using Homebrew or ArchLinux? Try using the generic Linux task below, if that fails check out the Brewfile/Archfile for what CLI tools needed and install them.
# Homebrew task workstation:brew # or, Arch with yay/paru task workstation:arch # or, Generic Linux (YMMV, this pulls binaires in to ./bin) task workstation:generic-linux
-
Setup a Python virual environment by running the following task command.
π This commands requires Python 3.11 to be installed.
task workstation:venv
-
Continue on to π§ Stage 3
Note
The config.sample.yaml file contain necessary information that is vital to the bootstrap process.
-
Generate the
config.yaml
from the config.sample.yaml configuration file.task init
π Using SOPS with Age allows us to encrypt secrets and use them with Flux.
-
Create a Age private / public key (this file is gitignored)
task sops:age-keygen
-
Fill out the appropriate vars in
config.yaml
-
Complete filling out the rest of the
config.yaml
configuration file. -
Once done run the following command which will verify and generate all the files needed to continue.
task configure
-
Push you changes to git
π Verify all the
*.sops.yaml
and*.sops.yaml
files under./kubernetes
directory is encrypted with SOPSgit add -A git commit -m "Initial commit :rocket:" git push
-
Continue on to β‘ Stage 4
-
Create Talos Secrets
task talos:gensecret task talos:genconfig
-
Apply Talos Config
task talos:apply
-
Boostrap Talos and get kubeconfig
task talos:bootstrap task talos:kubeconfig node=$master_node_ip_address
-
Install Cilium and kubelet-csr-approver into the cluster
task talos:apply-extras
-
The
kubeconfig
for interacting with your cluster should have been created in the root of your repository. -
Verify the nodes are online
π If this command fails you likely haven't configured
direnv
as mentioned previously in the guide.kubectl get nodes -o wide # NAME STATUS ROLES AGE VERSION # k8s-0 Ready control-plane,etcd,master 1h v1.29.1 # k8s-1 Ready worker 1h v1.29.1
-
Continue on to πΉ Stage 6
Important
Skip this stage if you have disabled Flux in the config.yaml
-
Verify Flux can be installed
flux check --pre # βΊ checking prerequisites # β kubectl 1.27.3 >=1.18.0-0 # β Kubernetes 1.27.3 k3s1 >=1.16.0-0 # β prerequisites checks passed
-
Install Flux and sync the cluster to the Git repository
task flux:bootstrap # namespace/flux-system configured # customresourcedefinition.apiextensions.k8s.io/alerts.notification.toolkit.fluxcd.io created # ...
-
Verify Flux components are running in the cluster
kubectl -n flux-system get pods -o wide # NAME READY STATUS RESTARTS AGE # helm-controller-5bbd94c75-89sb4 1/1 Running 0 1h # kustomize-controller-7b67b6b77d-nqc67 1/1 Running 0 1h # notification-controller-7c46575844-k4bvr 1/1 Running 0 1h # source-controller-7d6875bcb4-zqw9f 1/1 Running 0 1h
Renovate is a tool that automates dependency management. It is designed to scan your repository around the clock and open PRs for out-of-date dependencies it finds. Common dependencies it can discover are Helm charts, container images, GitHub Actions, Ansible roles... even Flux itself! Merging a PR will cause Flux to apply the update to your cluster.
To enable Renovate, click the 'Configure' button over at their Github app page and select your repository. Renovate creates a "Dependency Dashboard" as an issue in your repository, giving an overview of the status of all updates. The dashboard has interactive checkboxes that let you do things like advance scheduling or reattempt update PRs you closed without merging.
The base Renovate configuration in your repository can be viewed at .github/renovate.json5. By default it is scheduled to be active with PRs every weekend, but you can change the schedule to anything you want, or remove it if you want Renovate to open PRs right away.
Below is a general guide on trying to debug an issue with an resource or application. For example, if a workload/resource is not showing up or a pod has started but in a CrashLoopBackOff
or Pending
state.
-
Start by checking all Flux Kustomizations & Git Repository & OCI Repository and verify they are healthy.
flux get sources oci -A flux get sources git -A flux get ks -A
-
Then check all the Flux Helm Releases and verify they are healthy.
flux get hr -A
-
Then check the if the pod is present.
kubectl -n <namespace> get pods -o wide
-
Then check the logs of the pod if its there.
kubectl -n <namespace> logs <pod-name> -f # or stern -n <namespace> <fuzzy-name>
-
If a resource exists try to describe it to see what problems it might have.
kubectl -n <namespace> describe <resource> <name>
-
Check the namespace events
kubectl -n <namespace> get events --sort-by='.metadata.creationTimestamp'
Resolving problems that you have could take some tweaking of your YAML manifests in order to get things working, other times it could be a external factor like permissions on NFS. If you are unable to figure out your problem see the help section below.