concourse-k0sctl

It's a container image which instruments k0sctl, a CLI to manage k0s Kubernetes clusters. The image currently is publicly available on Docker Hub as omegasquad82/k0sctl-handler. This project aims to provide a simple, configurable Concourse pipeline example, but it is neither production ready nor currently intended to be run in security sensitive settings. It may improve over time. Feedback, ideas and any other contribution is welcome.

containerimage

The image built with the Dockerfile is based on Alpine Linux 3.16.x and the buildx ci workflow has been prepared to build it both for linux/amd64 and linux/arm64 targets. Currently there is a lack in smoke testing during the build and testing unfortunately done via the pipeline template. Until this has been corrected it still occasionally breaks during tinkering.

security

Both pipeline and containerimage are being built in my free time and are a fun project. In contrary to what the above states it is imperative that you never leak any private key data you handle. This product encrypts the files created with k0sctl backup. This feature cannot be turned off at this point in time.

It is required that you generate, and provide via pipeline vars, a cluster.gpg_pair with the exact same Name and Mail, but no Comment, values you're providing to the pipeline as cluster.name and cluster.email.

These values will be used to both en- and later decrypt the backup password as well as sign all commits to the backup git repository during relevant Jobs. Please review this document for more information about commit signature verification.

praise

My gratitude to @rstacruz as I'm heavily relying on their cheat sheets for both bash and markdown during my day to day work.

inventory

Please see the Dependency Dashboard for a full inventory of automatically maintained versions for Github Actions, Dockerfile and Packages.

Alpine

package
bash
coreutils
curl
git
gnupg
grep
mtr
openssl

Github

package
k0sctl

scripts

common.sh

A few functions used either in the image or the pipeline or both.

k0sctl-handler.sh

It is the main glue between the pipeline and the CLI. It has several environment parameters, listed in the order of appearance:

Name	Description	Default
K0SCTL_CMD_NAME	The action to perform.	version
DISABLE_TELEMETRY	Pipeline's no_telemetry	false
K0SCTL_SSH_KEY	private SSH key content
K0SCTL_SSH_TYPE	the key's file name	id_ed25519
K0SCTL_CFG_PATH	to k0sctl config spec	config/k0sctl.yaml
K0SCTL_DIR_LOG	to store k0sctl's log	auditlog
K0SCTL_DIR_BAK	to place backups into.	backup
K0SCTL_DIR_RES	from where to restore	restore
K0SCTL_GPG_KEY	to decrypt backup password
K0SCTL_ENC_CIPHER	openssl cipher for backups	chacha20
K0SCTL_PREFIX_BAK	Prefix of backup archives	k0s_backup
K0SCTL_SUFFIX_LOG	Final logfile's suffix	log
K0SCTL_LOG_PATH	k0sctl default log path	~/.cache/k0sctl/k0sctl.log
K0SCTL_SUFFIX_BAK	Suffix of backup archives	tar.gz

Pipeline

You'll find it's specification in pipeline.yml.

Variables

An example parametrization is in var-example.yml.

path	concourse resource type	description
email	pcfseceng/email-resource	email alerting parameters
timer.ping	time	when to execute traceroutes
timer.backup	time	when to execute backups

k0sctl

Below the k0sctl parameter structure you'll find:

path	concourse type	description
config	git	place to fetch k0sctl configuration
backup	git	to backup/restore the cluster state
cluster._key	string	private SSH key
cluster.gpg_pair	string	private GPG key
cluster.mail	string	committer's email address for backups
cluster.name	string	email alert subject preamble
flags.no_telemetry	boolean	wether k0sctl should call home

Jobs

ping

It will periodically traceroute using mtr any valid IPv4 address present in the files retrieved by config/*.yaml glob.

init

It initializes the backup git repository with an encrypted secret.gpg file that contains a password to safely store the backups. An existing backup branch will be overwritten on subsequent builds.

install

This Job calls k0sctl apply with configuration from the config repository under it's default path k0sctl.yaml (configurable). If a non-empty k0sctl_backup_latest file exists in the backup repository, it will be decrypted with openssl enc handed over to k0sctl, which will restore the cluster's state if and only if it is a new installation.

uninstall

Destroys the cluster by calling k0sctl reset.

backup

Calls k0sctl backup and encrypts it's output archive with openssl enc and the encrypted file will be saved in the backup git repository. A symlink will be created to easily access it during the restore operation.

---