Releases & States
Last updated
Last updated
Kerbi's state management system lets you store the values it computes during $ kerbi template
or $ kerbi values
, and then retrieve those values again. Kerbi uses a ConfigMap
, Secret
, or database in your cluster to store the data.
To build an intuitive understanding of state management, see the .
Your goal as a developer using variable-based templating in a modern CD pipeline should be to achieve the following workflow:
Template a new manifest using new values merged onto the last set of values you used
Try applying that new manifest to the Kubernetes cluster
If the apply worked:
Store the values you just used to generate this manifest for next time
Otherwise:
Stop everything, ping devs, etc...
Helm does this for you in one line with:
This is great, but there are some downsides, namely that you are delegating the most critical command in Kubernetes - kubectl apply
- to another tool.
Kerbi, on the other hand, is designed to never run critical operations like kubectl apply
on your behalf. So with Kerbi, you can implement conceptual workflow as follows:
Running kubectl apply
with --dry=run-server
will yield a status code of "0"
if all resources were accepted, and "1"
otherwise. Therefore, the statement that comes after the &&
only gets evaluated if Kubernetes accepted all our resources - what we wanted.
A state is a record that stores the values (aka variables) that were computed during a $ kerbi template
operation, provided a --write state [TAG]
flag is passed.
State records have the following attributes:
tag
- its unique name, which can be anything
message
any human readable note, or perhaps a git commit id
values
the final values computed by template
or values show
default_values
the final default values computed by template
or values show
created_at
an ISO8601 timestamp
You can easily inspect any state with the CLI:
A release is a collection of states. Conceptually, a release also means "one instance of the app".
In a world where a Kubernetes namespace was a reliable boundary for an application's perimeter, we (and probably Helm) would just use namespaces. But this is unfortunately not the case.
A release is identified by its name and its namespace. Unless you pass --namespace [NAME]
, its namespace will automatically be set to its name. Let's build an intuition:
When you run a command like $ kerbi template [RELEASE_NAME]
, Kerbi will look for a ConfigMap
called kerbi-[RELEASE_NAME]-db
in the namespace [RELEASE_NAME]
.
If you pass an explicit namespace, e.g $ kerbi template [RELEASE_NAME] --namespace [NAMESPACE]
then it will look for the ConfigMap
in the namespace [NAMESPACE]
.
Remember you can easily figure out what's where with:
Release names and namespaces are confusing. If you're used to Helm, it's important to highlight the difference. Illustrative pseudocode:
Kerbi can store the compiled values data in a ConfigMap
, a Secret
, or an arbitrary database. **** You can set this behavior either with a flag e.g --backend ConfigMap
or in the global Kerbi config e.g $ kerbi config set state-backend: Secret
.
Only ConfigMap
currently works
Secret and database are not yet finished.
If you use a ConfigMap
or Secret
, you'll need to give Kerbi access your cluster. The examples below show the three different ways to do that.
To use this auth mode:
If you have a ~/.kube/config.yaml
on your machine, then this should work without any further configuration. The following settings are available:
Note that each configuration above can also be passed as a flag in any state touching operation, e.g $ kerbi template --k8s-auth-type in-cluster
.
We can feed the CLI special expressions instead of literals tag. When Kerbi encounters a special keyword, formatted as @<keyword>
, it will attempt to resolve it to a literal tag name. Depending on the keyword, the resolved tag may or may not refer to an existing state tag.
@latest
keywordResolves to the tag of the newest _non_-candidate state (as given by created_at
). Behavior is the same during read and write operations.
Example: $ kerbi state show zebra @latest
@candidate
keywordResolves to the tag of the newest candidate state (as given by created_at
). Behavior is the same during read and write operations.
Example: $ kerbi state retag zebra @candidate 1.2.3
@new-candidate
keywordResolves to a random, free (not yet taken by existing states) tag with a candidate status prefix. Only works for write operations.
Example: $ kerbi values show -f v2.yaml --write-state @new-candidate
. The name of the new state in this case resolved to "[cand]-purple-purse"
@random
keywordResolves to a random, free (not yet taken by existing states) tag without a candidate status prefix. Only works for write operations.
Example: $ kerbi values show -f v2.yaml --write-state @random
. The name of the new state in this case resolved to "spiky-goose"
States have a "candidate" flag to make it possible to implement the conceptual workflow described in the first section. In short, you want a state to be in candidate mode until you know it has been successfully applied to the cluster.
To make Kerbi as simple as possible, there is no special attribute to designate candidacy, only a special prefix [cand]-
. So any state that begins with [cand]-
is treated as a candidate. Conversely, if you want to promote a state to non-candidate and rename it in one go, just:
Because the
To promote a state and keep its name, run:
You can also delete all candidate states with one command:
revision
- the semantic version number of your project ()
Probably what you want in CI/CD if you have a and a remote cluster. You need to supply an access token, a.k.a bearer token: