Tanka supports CLI completion for bash, zsh and fish.
-
Terminal window
# Install
tkcomplete
-
# Uninstall
tkcomplete--remove
-
As tanka is its own completion handler, it needs to hook into your shell’s
-configuration file (.bashrc, etc).
-
When using other shells than bash, Tanka relies on a Bash compatibility
-mode. It enables this automatically when installing, but please make sure no
-other completion (e.g. OhMyZsh) interferes with this, or your completion might
-not work properly.
-It sometimes depends on the order the completions are being loaded, so try
-putting Tanka before or after the others.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/config/index.html b/pr-preview/pr-1127/config/index.html
deleted file mode 100644
index 4e7dc78ce..000000000
--- a/pr-preview/pr-1127/config/index.html
+++ /dev/null
@@ -1,65 +0,0 @@
- Configuration Reference | Grafana Tanka
-
- Skip to content
Tanka supports two different ways of computing differences between the local
-configuration and the live cluster state: Either nativekubectl diff -f -
-is used, which gives the best possible results, but is only possible for
-clusters with
-server-side diff
-support (Kubernetes 1.13+).
-
When this is not available, Tanka falls back to subset mode.
-
You can specify the diff-strategy to use on the command line as well:
-
Terminal window
# native
tkdiff--diff-strategy=native.
-
# validate: Like native but with a server-side validation
tkdiff--diff-strategy=validate.
-
# server-side
tkdiff--diff-strategy=server.
-
# subset
tkdiff--diff-strategy=subset.
-
Native
-
The native diff mode is recommended, because it uses kubectl diff underneath,
-which sends the objects to the Kubernetes API server and computes the
-differences over there.
-
This has the huge benefit that all possible changes by webhooks and other
-internal components of Kubernetes can be encountered as well.
-
However, this is a fairly new feature and only available on Kubernetes 1.13 or
-later. Only the API server (master nodes) needs to have that
-version, worker nodes do not matter.
-
There is a
-known issue
-with kubectl diff, which affects ports configured to use both TCP and UDP.
-
Server-side diffs
-
There are two additional modes which extend native: validate and server.
-While all kubectl diff commands are sent to the API server, these two
-methods take advantage of an additional server-side diff mode (which uses the
-kubectl diff --server-side flag, complementing the
-server-side apply mode).
-
Since a plain server diff often produces cruft, and wouldn’t be representative
-of a client-side apply, the validate method allows the server-side diff to
-check that all models are valid server-side, but still displays the native
-diff output to the user.
-
Subset
-
If native diffing is not supported by your cluster, Tanka provides subset diff
-as a fallback method.
-
Subset diff only compares fields present in the local configuration and
-ignores all other fields. When you remove a field locally, you will see no
-differences.
-
This is required, because Kubernetes adds dynamic fields to the state during
-runtime, which we cannot know of on the client side. To produce a somewhat
-usable output, we can effectively only compare what we already know about.
-
If this is a problem for you, consider switching to native mode.
-
External diff utilities
-
You can use external diff utilities by setting the environment variable
-KUBECTL_EXTERNAL_DIFF. If you want to use a GUI or interactive diff utility
-you must also set KUBECTL_INTERACTIVE_DIFF=1 to prevent Tanka from capturing
-stdout.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/directory-structure/index.html b/pr-preview/pr-1127/directory-structure/index.html
deleted file mode 100644
index 3f86a9a3d..000000000
--- a/pr-preview/pr-1127/directory-structure/index.html
+++ /dev/null
@@ -1,128 +0,0 @@
- Directory structure | Grafana Tanka
-
- Skip to content
Like other programming languages, Jsonnet needs an entrypoint into the
-evaluation, something to begin with. main.jsonnet is exactly this: The very
-first file being evaluated, importing or directly specifying everything required
-for this specific environment.
-
Root and Base
-
When talking about directories, Tanka uses the following terms:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Term
Description
Identifier file
rootDir
The root of your project
jsonnetfile.json or tkrc.yaml
baseDir
The directory of the current environment
main.jsonnet
-
Regardless what subdirectory of the project you are in, Tanka will always be
-able to identify both directories, by searching for the identifier files in the
-parent directories.
-Tanka needs these for correctly setting up the import paths.
-
This is similar to how git always works, by looking for the .git directory.
-
Libraries
-
Tanka relies heavily on code-reuse, so libraries are a natural thing. Roughly
-spoken, they can be imported from two paths:
jb records all external packages installed in a file called
-jsonnetfile.json. This file is the source of truth about what should be
-included in vendor/. However, it should only include what is really directly
-required, all recursive dependencies will be handled just fine.
-
jsonnetfile.lock.json is generated on every run of jsonnet-bundler, including
-a list of packages that must be included in vendor/, along with the exact
-version and a sha256 hash of the package contents.
-
Both files should be checked into source control: The jsonnetfile.json
-specifies what you need and the jsonnetfile.lock.json is important to make
-sure that subsequent jb install invocations always do the exact same thing.
-
\ No newline at end of file
diff --git a/pr-preview/pr-1127/env-vars/index.html b/pr-preview/pr-1127/env-vars/index.html
deleted file mode 100644
index 2cd407995..000000000
--- a/pr-preview/pr-1127/env-vars/index.html
+++ /dev/null
@@ -1,72 +0,0 @@
- Environment variables | Grafana Tanka
-
- Skip to content
Description: Path to the jb tool executable
-Default: $PATH/jb
-
TANKA_KUBECTL_PATH
-
Description: Path to the kubectl tool executable
-Default: $PATH/kubectl
-
TANKA_KUBECTL_TRACE
-
Description: Print all calls to kubectl
-Default: false
-
TANKA_HELM_PATH
-
Description: Path to the helm executable
-Default: $PATH/helm
-
TANKA_KUSTOMIZE_PATH
-
Description: Path to the kustomize executable
-Default: $PATH/kustomize
-
TANKA_PAGER
-
Description: Pager to use when displaying output. Set to an empty string to disable paging.
-Default: $PAGER
-
PAGER
-
Description: Pager to use when displaying output. Only used if TANKA_PAGER is not set. Set to an empty string to disable paging.
-Default: less --RAW-CONTROL-CHARS --quit-if-one-screen --no-init
\ No newline at end of file
diff --git a/pr-preview/pr-1127/exporting/index.html b/pr-preview/pr-1127/exporting/index.html
deleted file mode 100644
index e61751419..000000000
--- a/pr-preview/pr-1127/exporting/index.html
+++ /dev/null
@@ -1,125 +0,0 @@
- Exporting as YAML | Grafana Tanka
-
- Skip to content
You can also use a different file extension by providing --extension='yml', for example.
-
Multiple environments
-
Tanka can also export multiple inline environments, as showcased in Use case: consistent inline
-environments. This follows the same
-principles as describe before with the addition that you can also refer to Environment specific data through the env
-keyword.
-
For example an export might refer to data from the Environment spec:
When exporting a large amount of environments, jsonnet evaluation can become a bottleneck. To speed up the process, Tanka provides a few optional features.
-
Partial export (in a GitOps context)
-
Given multiple environments, one may want to only export the environments that were modified since the last export. This is enabled by passing both the --merge-strategy=replace-envs flags.
-
When these flags are passed, Tanka will:
-
-
Delete the manifests that were previously exported by the environments that are being exported. This is done by looking at the manifest.json file that is generated by Tanka when exporting. The related entries are also removed from the manifest.json file.
-
Generate the manifests for the targeted environments into the output directory.
-
Add in the new manifests entries into the manifest.json file and re-export it.
-
-
Finding out which environments to export
-
Tanka provides the tk tool importers command to figure out which main.jsonnet need to be re-exported based on what files were modified in a workspace.
-
If, for example, the lib/my-lib/main.libsonnet file was modified, you could run the command like this to find which files to export:
Note that deleted environments need special consideration when doing this.
-The tk tool importers utility only works with existing files so deleting an environment will result in stale manifest.json entries and moving an environment will result in manifest conflicts.
-In order to correctly handle deleted environments, they need to be passed to the export command:
Read this blog post for more information about memory ballasts.
-
For large environments that load lots of data into memory on evaluation, a memory ballast can dramatically improve performance. This feature is exposed through the --mem-ballast-size-bytes flag on the export command.
-
Anecdotally (Grafana Labs), environments that took around a minute to load were able to load in around 45 secs with a ballast of 5GB (--mem-ballast-size-bytes=5368709120). Decreasing the ballast size resulted in negative impact on performance, and increasing it more did not result in any noticeable impact.
-
Caching
-
Tanka can also cache the results of the export. This is useful if you often export the same files and want to avoid recomputing them. The cache key is calculated from the main file and all of its transitive imports, so any change to any file possibly used in an environment will invalidate the cache.
-
This is configured by two flags:
-
-
--cache-path: The local filesystem path where the cache will be stored. The cache is a flat directory of json files (one per environment).
-
--cache-envs: If exporting multiple environments, this flag can be used to specify, with regexes, which environments to cache. If not specified, all environments are cached.
-
-
Notes:
-
-
Using the cache might be slower than evaluating jsonnet directy. It is only recommended for environments that are very CPU intensive to evaluate.
-
To use object storage, you can point the --cache-path to a FUSE mount, such as s3fs
-
\ No newline at end of file
diff --git a/pr-preview/pr-1127/faq/index.html b/pr-preview/pr-1127/faq/index.html
deleted file mode 100644
index 651d9d200..000000000
--- a/pr-preview/pr-1127/faq/index.html
+++ /dev/null
@@ -1,88 +0,0 @@
- Frequently asked questions | Grafana Tanka
-
- Skip to content
Jsonnet is a data templating language, originally created by Google.
-
It is a superset of JSON, which adds common structures from full programming
-languages to data modeling. Because it being a superset of JSON and ultimately
-always compiling to JSON, it is guaranteed that the output will be valid JSON
-(or YAML).
-
By allowing functions and imports, rich abstraction is possible, even across
-project boundaries.
Tanka aims to be a fully compatible, drop-in replacement for the main workflow
-of ksonnet (show, diff, apply).
-
In general, both tools are very similar when it comes to how they handle Jsonnet
-and apply to a Kubernetes cluster.
-
However, ksonnet included a rich code generator for establishing a CLI based
-workflow for editing Kubernetes objects. It also used to manage dependencies
-itself and had a lot of concepts for different levels of abstractions. When
-designing Tanka, we felt these add more complexity for the user than they
-provide additional value. To keep Tanka as minimal as possible, these are not
-available and are not likely to be ever added.
-
What about kubecfg ?
-
Tanka development has started at the time when kubecfg was a part of
-already-deprecated ksonnet project. Although these projects are similar, Tanka
-aims to provide continuity for ksonnet users, whereas kubecfg is (according
-to the project’s README.md)
-really just a thin Kubernetes-specific wrapper around jsonnet evaluation.
-
Why not Helm?
-
Helm relies heavily on string templating.yaml files. We feel this is the
-wrong way to approach the absence of abstractions inside of yaml, because the
-templating part of the application has no idea of the structure and syntax of
-yaml.
-
This makes debugging very hard. Furthermore, helm is not able to provide an
-adequate solution for edge cases. If I wanted to set some parameters that are
-not already implemented by the Chart, I have no choice but to modify the Chart
-first.
-
Jsonnet on the other hand got you covered by supporting mixing (patching,
-deep-merging) objects on top of the libraries output if required.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/favicon.svg b/pr-preview/pr-1127/favicon.svg
deleted file mode 100644
index 1997f7a0f..000000000
--- a/pr-preview/pr-1127/favicon.svg
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-
diff --git a/pr-preview/pr-1127/formatting/index.html b/pr-preview/pr-1127/formatting/index.html
deleted file mode 100644
index 43d8c37fb..000000000
--- a/pr-preview/pr-1127/formatting/index.html
+++ /dev/null
@@ -1,58 +0,0 @@
- Formatting | Grafana Tanka
-
- Skip to content
Tanka can automatically delete resources from your cluster once you remove them
-from Jsonnet.
-
-
To accomplish this, it appends the tanka.dev/environment: <hash> label to each created
-resource. This is used to identify those which are missing from the local state in the
-future.
-
-
Because the label causes a diff for every single object in your cluster and
-not everybody wants this, it needs to be explicitly enabled. To do so, add the
-following field to your spec.json:
-
{
"spec": {
"injectLabels": true,
}
}
-
Once added, run a tk apply, make sure the label is actually added and confirm
-by typing yes.
-
From now on, you can use tk prune to remove old resources from your cluster.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/helm/index.html b/pr-preview/pr-1127/helm/index.html
deleted file mode 100644
index 131fd3d21..000000000
--- a/pr-preview/pr-1127/helm/index.html
+++ /dev/null
@@ -1,166 +0,0 @@
- Helm support | Grafana Tanka
-
- Skip to content
// Equivalent to: --api-versions v1 --api-versions apps/v1
apiVersions: ['v1', 'apps/v1']
// Equivalent to: --kube-version v1.20.0
kubeVersion: 'v1.20.0'
// Equivalent to: --no-hooks
noHooks: true,
}
-
Tanka will install Custom Resource Definitions (CRDs) automatically, if the
-Helm Chart requires them and ships them in crds/. This is equivalent to helm template --include-crds. This can be disabled using includeCrds: false:
Tanka, like Jsonnet, is hermetic. It always yields the same
-resources when the project is
-strictly self-contained.
-
Helm however keeps Charts and repository configuration somewhere around
-~/.config/helm, which violates above requirement.
-
To comply with this requirement, Tanka expects Helm Charts to be found inside the
-bounds of a project. This means, you MUST put your Charts somewhere next to
-the file that calls helm.template(), so that it can be referred to using a
-relative path.
-
Vendor Location
-
Where to actually put them inside the project is up to you, but keep in mind you
-need to refer to them using relative paths.
-
We recommend always writing libraries that wrap the actual Helm Chart, so the
-consumer does not need to be aware of it. Whether you put these into your local lib/ directory or
-publish and vendor them into the vendor/ directory is up to you.
-
A library usually looks like this:
-
Directory/
-
jsonnetfile.json
main.libsonnet
-
When adopting Helm inside it, we recommend vendoring at the top level, as such:
-
Directory/
-
jsonnetfile.json
main.libsonnet
Directorycharts
<someChart>
-
This way, you can refer to the charts as ./charts/<someChart> from inside
-main.libsonnet. By keeping the chart as close to the consumer as possible, the
-library is kept portable.
-
Charttool
-
Helm does not make vendoring incredibly easy by itself. helm pull provides the
-required plumbing, but it does not record its actions in a reproducible manner.
-
Therefore, Tanka ships a special utility at tk tool charts, which automates
-helm pull:
-
Terminal window
# Create a chartfile.yaml in the current directory, e.g. in lib/myLibrary
tktoolchartsinit
-
# Install the MySQL chart at version 1.6.7 from the stable repository
tktoolchartsaddstable/mysql@1.6.7
-
Adding charts
-
To add a chart, use the following:
-
Terminal window
tktoolchartsadd<repo>/<name>@<version>
-
This will also call tk tool charts vendor, so that the charts/ directory is updated.
-
Adding repositories
-
By default, the stable repository is automatically set up for you. If you wish
-to add another repository, you can use the add-repo command:
If you wish to install multiple versions of the same chart, you can write them to a specific directory.
-You can do so with a :<directory> suffix in the add command, or by modifying the chartfile manually.
-
Terminal window
tktoolchartsaddstable/mysql@1.6.7:1.6.7
tktoolchartsaddstable/mysql@1.6.8:1.6.8
-
The resulting chartfile will look like this:
-
version: 1
directory: charts
repositories:
- name: stable
url: https://charts.helm.sh/stable
requires:
- chart: stable/mysql
directory: 1.6.7
version: 1.6.7
- chart: stable/mysql
directory: 1.6.8
version: 1.6.8
-
Install charts from chartfile
-
To install charts from an existing chartfile, use the following:
-
Terminal window
tktoolchartsvendor
-
Optionally, you can also pass the --prune flag to remove vendored charts that are no longer in the chartfile.
-
OCI Registry Support
-
Tanka supports pulling charts from OCI registries. To use one, the chart name must be split into two parts: the registry and the chart name.
-
As example, if you wanted to pull the oci://public.ecr.aws/karpenter/karpenter:v0.27.3 image, your chartfile would look like this:
-
version: 1
directory: charts
repositories:
- name: karpenter
url: oci://public.ecr.aws/karpenter
requires:
- chart: karpenter/karpenter
directory: v0.27.3
version: v0.27.3
-
Registry login is not supported yet.
-
Troubleshooting
-
Helm executable missing
-
Helm support in Tanka requires the helm binary installed on your system and
-available on the $PATH. If Helm is not installed, you will see this error message:
-
evaluating jsonnet: RUNTIME ERROR: Expanding Helm Chart: exec: "helm": executable file not found in $PATH
-
To solve this, you need to install Helm.
-If you cannot install it system-wide, you can point Tanka at your executable
-using TANKA_HELM_PATH
-
opts.calledFrom unset
-
This occurs, when Tanka was not told where it helm.template() was invoked
-from. This most likely means you didn’t call new(std.thisFile) when importing tanka-util:
-
local tanka =import"github.com/grafana/jsonnet-libs/tanka-util/main.libsonnet";
local helm = tanka.helm.new(std.thisFile);
↑ This is important
-
Failed to find Chart
-
helmTemplate: Failed to find a Chart at 'stable/grafana': No such file or directory.
helmTemplate: Failed to find a Chart at '/home/user/stuff/tanka/environments/default/grafana': No such file or directory.
-
Tanka failed to locate your Helm chart on the filesystem. It looked at the
-relative path you provided in helm.template(), starting from the directory of
-the file you called helm.template() from.
-
Please check there is actually a valid Helm chart at this place. Referring to
-charts as <repo>/<name> is disallowed by design.
-
Two resources share the same name
-
To make customization easier, helm.template() returns the resources not as the
-list it receives from Helm, but instead converts this into an object.
-
For the indexing key it uses kind_name by default. In some rare cases, this
-might not be enough to distinguish between two resources, namely when the same
-resource exists in two namespaces.
-
To handle this, pass a custom name format, e.g. to also include the namespace:
Inline environments is the practice of defining the environment’s config inline
-for evaluation at runtime as opposed to configuring it statically in
-spec.json.
-
The general take away is:
-
-
spec.json will no longer be used
-
main.jsonnet is expected to render a tanka.dev/Environment object
-
this object is expected to hold Kubernetes objects at .data
-
-
Converting to an inline environment
-
Converting a traditional spec.json environment into an inline environment is quite
-straight forward. Based on the example from Using Jsonnet:
-
The directory structure:
-
Directoryenvironments
-
Directorydefault# default environment
-
main.jsonnet# main file
spec.json# environment’s config
jsonnetfile.json
Directorylib/# libraries
…
Directoryvendor/# external libraries
…
-
The original files look like this:
-
main.jsonnet
{
some_deployment: {/* ... */ },
some_service: {/* ... */ },
}
-
spec.json
{
"apiVersion": "tanka.dev/v1alpha1",
"kind": "Environment",
"metadata": {
"name": "default"
},
"spec": {
"apiServer": "https://127.0.0.1:6443",
"namespace": "monitoring"
}
}
-
Converting is as simple as bringing in the spec.json into main.jsonnet and
-moving the original main.jsonnet scope into the data: element.
-
main.jsonnet
{
apiVersion:'tanka.dev/v1alpha1',
kind:'Environment',
metadata: {
name:'default',
},
spec: {
apiServer:'https://127.0.0.1:6443',
namespace:'monitoring',
},
data: { // original main.jsonnet data
some_deployment: {/* ... */ },
some_service: {/* ... */ },
},
}
-
Use case: variable apiServer
-
Even though the apiServer directive is originally meant to prevent that the
-manifests don’t get accidentally applied to the wrong Kubernetes cluster, there
-is a valid use case for making the apiServer variable: Local test clusters.
-
Instead of modifying spec.json each time, with inline environments it is
-possible to leverage powerful jsonnet concepts, for example with top level
-arguments:
-
environments/minikube-test-setup/main.jsonnet
function(apiServer) {
apiVersion:'tanka.dev/v1alpha1',
kind:'Environment',
metadata: {
name:'minikube-test-setup',
},
spec: {
apiServer: apiServer,
namespace:'monitoring',
},
data: { /* ... */ },
}
-
Applying this to a local Kubernetes cluster can be done like this:
Similarly this can be used to configure any part of the Environment object, like
-namespace:, metadata.labels, …
-
Use case: consistent inline environments
-
It is possible to define multiple inline environments in a single jsonnet. This
-enables an operator to generate consistent Tanka environments for multiple
-Kubernetes clusters.
-
We can define a Tanka environment once and then repeat that for a set of
-clusters as shown in this example:
Inline environments cannot use import "tk" anymore as
-this information was populated before jsonnet evaluation by the existence of
-spec.json.
-
tk env
-
The different tk env subcommands are heavily based on the spec.json
-approach. tk env list will continue to work as expected, tk env (add|remove|set) will only work for spec.json based environments.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/install/index.html b/pr-preview/pr-1127/install/index.html
deleted file mode 100644
index f32ff5159..000000000
--- a/pr-preview/pr-1127/install/index.html
+++ /dev/null
@@ -1,74 +0,0 @@
- Installation | Grafana Tanka
-
- Skip to content
Tanka is distributed as a single binary called tk. It already includes the Jsonnet compiler, but requires some tools to be available:
-
-
kubectl: Tanka
-uses kubectl to communicate to your cluster. This means kubectl must be
-available somewhere on your $PATH. If you ever have worked with Kubernetes
-before, this should be the case anyways.
-
diff: To compute differences, standard UNIX diff(1) is required.
-
(recommended) jb: #Jsonnet Bundler, the Jsonnet package
-manager
On macOS, Jsonnet Bundler is best installed using brew:
Terminal window
brewinstalljsonnet-bundler
This downloads the most recent version of Jsonnet Bundler and installs it.
-Also, Jsonnet Bundler is automatically kept up to date as part of brew upgrade.
Jsonnet is a superset of JSON, it treats any JSON as valid Jsonnet. Because many
-systems can be told to output their data in JSON format, this provides a pretty
-good interface between those.
-
For example, your build tooling like make could acquire secrets from systems such as
-Vault, etc. and write that into secrets.json.
-
local secrets =import"secrets.json";
-
{
foo: secrets.myPassword,
}
-
-
External variables
-
Another way of passing values from the outside are external variables, which are specified like so:
-
Terminal window
# strings
tkshow.--ext-strhello=world
-
# any Jsonnet snippet
tkshow.--ext-codefoo=4--ext-codebar='[ 1, 3 ]'
-
They can be accessed using std.extVar and the name given to them on the command line:
-
{
foo: std.extVar('foo'), // 4, integer
bar: std.extVar('bar'), // [ 1, 3 ], array
}
-
-
Top Level Arguments
-
Usually with Tanka, your main.jsonnet holds an object at the top level (most
-outer type in the generated JSON):
-
main.jsonnet
{
/* your resources */
}
-
Another type of Jsonnet that naturally accepts parameters is the function.
-When the Jsonnet compiler finds a function at the top level, it invokes it and
-allows passing parameter values from the command line:
-
// Actual output (object) returned by function, which is taking parameters and default values
function(who, msg="Hello %s!") {
hello: msg % who
}
-
Here, who needs a value while msg has a default. This can be invoked like so:
-
Terminal window
tkshow.--tla-strwho=John
\ No newline at end of file
diff --git a/pr-preview/pr-1127/jsonnet/main/index.html b/pr-preview/pr-1127/jsonnet/main/index.html
deleted file mode 100644
index 62ff9dbd5..000000000
--- a/pr-preview/pr-1127/jsonnet/main/index.html
+++ /dev/null
@@ -1,86 +0,0 @@
- main.jsonnet | Grafana Tanka
-
- Skip to content
The most important file is called main.jsonnet, because this is where Tanka
-invokes the Jsonnet compiler. Every single line of Jsonnet, including
-imports, functions and whatnot is then evaluated until a single, very big JSON
-object is left.
-This object is returned to Tanka and includes all of your Kubernetes manifests
-somewhere in it, most probably deeply nested.
-
But as kubectl expects a yaml stream, and not a nested tree, Tanka needs to
-extract your objects first. To do this, it traverses the tree until it finds
-something that looks like a Kubernetes manifest. An object is considered valid
-when it has both, kind and apiVersion set.
-
To ensure Tanka can find your manifests, the output of your Jsonnet needs to
-have one of the following structures:
-
Deeply nested object (Recommended)
-
Most commonly used is a single big object that includes all manifests as
-leaf-nodes.
-
How deeply encapsulated the actual object is does not matter, Tanka will
-traverse down until it finds something that is valid.
-
{
"prometheus": {
"service": {
// Service nested one level
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "promSvc"
}
},
"deployment": {
"apiVersion": "apps/v1", // apiVersion ..
"kind": "Deployment", // .. and kind are required to identify an object.
"metadata": {
"name": "prom"
}
}
},
"web": {
"nginx": {
"deployment": {
// Deployment nested two levels
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "nginx"
}
}
}
}
}
-
Using this technique has the big benefit that it is self-documenting, as the
-nesting of keys can be used to logically group related manifests, for example by
-application.
-
An encapsulation level of zero is also possible, which means nothing else than
-regular object like it could be obtained from kubectl show -o json:
-
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "foo"
}
}
-
Array
-
Using an array of objects is also fine:
-
[
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "promSvc"
}
},
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "prom"
}
}
]
-
List type
-
Users of kubectl might have had contact with a type called List. It is not
-part of the official Kubernetes API but rather a pseudo-type introduced by
-kubectl for dealing with multiple objects at once. Thus, Tanka does not
-support it out of the box.
-
To take full advantage of Tankas features, you can manually flatten it:
-
local list = {
apiVersion:"v1",
kind:"List",
items: [
{
apiVersion:"v1",
kind:"Service",
/* ... */
}
/* ... */
]
};
-
# expose the `items` array on the top level:
list.items
\ No newline at end of file
diff --git a/pr-preview/pr-1127/jsonnet/native/index.html b/pr-preview/pr-1127/jsonnet/native/index.html
deleted file mode 100644
index b13454ddb..000000000
--- a/pr-preview/pr-1127/jsonnet/native/index.html
+++ /dev/null
@@ -1,124 +0,0 @@
- Native Functions | Grafana Tanka
-
- Skip to content
parseYaml wraps yaml.Unmarshal to convert a string of yaml document(s) into
-a set of dicts. If yaml only contains a single document, a single value array
-will be returned.
-
Examples
-
{
yaml: std.native('parseYaml')(|||
---
foo: bar
---
bar: baz
|||),
}
-
Evaluating with Tanka results in the JSON:
-
{
"yaml": [
{
"foo": "bar"
},
{
"bar": "baz"
}
]
}
-
manifestJsonFromJson
-
Signature
-
manifestJsonFromJson(string json, int indent) string
-
manifestJsonFromJson reserializes JSON and allows to change the indentation.
Jsonnet is the data templating language Tanka uses for
-expressing what shall be deployed to your Kubernetes cluster. Understanding
-Jsonnet is crucial to using Tanka effectively.
-
This page covers the Jsonnet language itself. For more information on how to
-use Jsonnet with Kubernetes, see the tutorial. There’s
-also the official Jsonnet tutorial
-that provides a more detailed review of language features.
-
Syntax
-
Being a superset of JSON, the syntax is very similar:
-
// Line comment
/* Block comment */
-
// a local variable (not exported)
local greeting ="hello world!";
-
// the exported/returned object
{
foo:"bar", // string
bar:5, // int
baz:false, // bool
list: [1,2,3], // array
// object
dict: {
nested: greeting, // using the local
},
hidden:: "incognito!"// an unexported field
}
-
Abstraction
-
Jsonnet has rich abstraction features, which makes it interesting for
-configuring Kubernetes, as it allows to keep configurations concise, yet
-readable.
Just as other languages, Jsonnet allows code to be imported from other files:
-
local secret =import"./secret.libsonnet";
-
The exported object (the only non-local one) of secret.libsonnet is now
-available as a local variable called secret.
-
When using Tanka, it is also possible to directly import .json files, as if
-they were a .libsonnet.
-
Make sure to also take a look at the libraries documentation to learn how to use import and re-use code.
-The documentation on Tanka import paths and vendoring are useful to understand how imports work in Tanka’s context.
-
Merging
-
Deep merging allows you to change parts of an object without touching all of it.
-Consider the following example:
-
local secret = {
kind: Secret,
metadata: {
name:"mySecret",
namespace:"default", // need to change that
},
data: {
foo: std.base64("foo")
}
};
-
To change the namespace only, we can use the special merge key +: like so:
-
// define the patch:
local patch = {
metadata+: {
namespace:"myApp"
}
}
-
The difference between : and +: is that the former replaces the original
-data at that key, while the latter applies the new object as a patch on top,
-meaning that values will be updated if possible but all other stay like they
-are.
-To merge those two, just add (+) the patch to the original:
-
secret + patch
-
The output of this is the following JSON object:
-
{
"kind": "Secret",
"metadata": {
"name": "mySecret",
"namespace": "myApp"
},
"data": {
"foo": "Zm9vCg=="
}
}
-
Functions
-
Jsonnet supports functions, similar to how Python does. They can be defined in
-two different ways:
-
localadd(x,y) = x + y;
local mul = (function(x, y) x * y);
-
Objects can have methods:
-
{
greet(who):"hello "+ who,
}
-
Default values, keyword-args and more examples can be found at
-jsonnet.org.
-
Standard library
-
The Jsonnet standard library includes many helper methods ranging from object
-and array mutation, over string utils to computation helpers.
When migrating from ksonnet, this error might occur, because Tanka does not
-provide the global __ksonnet variable, nor does it strictly have the concept
-of components.
-You will need to use the plain Jsonnet import feature instead. Note that this
-requires your code to be inside of one of the
-import paths.
-
Evaluating jsonnet: RUNTIME ERROR: couldn't open import "k.libsonnet": no match locally or in the Jsonnet library paths
-
This error can occur when the k8s-libsonnet kubernetes libraries are missing in the
-import paths. While k8s-libsonnet used to magically include them, Tanka follows a
-more explicit approach and requires you to install them using jb:
It installs the k8s-libsonnet library (in vendor/github.com/jsonnet-libs/k8s-libsonnet/1.21/).
-You can replace the 1.21 matching the Kubernetes version you want to run against.
-
-
-
It makes an alias for libraries importing k.libsonnet directly. See
-Aliasing for the alias rationale.
-
-
-
Unexpected diff if the same port number is used for UDP and TCP
-
A long-standing bug in kubectl
-results in an incorrect diff output if the same port number is used multiple
-times in differently named ports, which commonly happens if a port is specified
-using both protocols, tcp and udp. Nevertheless, tk apply will still work
-correctly.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/kustomize/index.html b/pr-preview/pr-1127/kustomize/index.html
deleted file mode 100644
index f5aabccdf..000000000
--- a/pr-preview/pr-1127/kustomize/index.html
+++ /dev/null
@@ -1,107 +0,0 @@
- Kustomize support | Grafana Tanka
-
- Skip to content
Above can be manipulated in the same way as
-any other Jsonnet data.
-
Working with Kustomize
-
Tanka, like Jsonnet, is hermetic. It always yields the same resources when
-the project is strictly self-contained.
-
Kustomize however has the ability to pull
-resources
-from different sources at runtime, which violates above requirement. This is
-also apparent in the example above.
-
-
Troubleshooting
-
Kustomize executable missing
-
Kustomize support in Tanka requires the kustomize binary installed on your
-system and available on the $PATH. If Kustomize is not installed, you will see
-this error message:
-
evaluating jsonnet: RUNTIME ERROR: Expanding Kustomize: exec: "kustomize": executable file not found in $PATH
-
To solve this, you need to
-install Kustomize.
-If you cannot install it system-wide, you can point Tanka at your executable
-using TANKA_KUSTOMIZE_PATH
-
opts.calledFrom unset
-
This occurs, when Tanka was not told where it kustomize.build() was invoked
-from. This most likely means you didn’t call new(std.thisFile) when importing tanka-util:
-
local tanka =import"github.com/grafana/jsonnet-libs/tanka-util/main.libsonnet";
local kustomize = tanka.kustomize.new(std.thisFile);
↑ This is important
-
Failed to find kustomization
-
Error: unable to find one of 'kustomization.yaml', 'kustomization.yml' or 'Kustomization' in directory '/home/user/stuff/tanka/environments/default/flux2'
-
Tanka failed to locate your kustomization on the filesystem. It looked at the
-relative path you provided in kustomize.build(), starting from the directory
-of the file you called kustomize.build() from.
-
Please check there is actually a valid kustomization at this place.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/libraries/import-paths/index.html b/pr-preview/pr-1127/libraries/import-paths/index.html
deleted file mode 100644
index 11b4f3402..000000000
--- a/pr-preview/pr-1127/libraries/import-paths/index.html
+++ /dev/null
@@ -1,88 +0,0 @@
- Import paths | Grafana Tanka
-
- Skip to content
Publishing is as easy as committing and pushing to a git remote.
-GitHub is recommended, as it is most common and supports
-faster installing using http archives.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/libraries/overriding/index.html b/pr-preview/pr-1127/libraries/overriding/index.html
deleted file mode 100644
index 2faff2903..000000000
--- a/pr-preview/pr-1127/libraries/overriding/index.html
+++ /dev/null
@@ -1,96 +0,0 @@
- Overriding vendor | Grafana Tanka
-
- Skip to content
The vendor directory is immutable in its nature. You can’t and should never
-modify any files inside of it, jb will revert those changes on the next run anyway.
-
Nevertheless, it can sometimes become required to add changes there, e.g. if an
-upstream library contains a bug that needs to be fixed immediately, without
-waiting for the upstream maintainer to review it.
-
Shadowing
-
Because import paths are ranked in Tanka, you can use
-a technique called shadowing: By putting a file with the exact same name in a
-higher ranked path, Tanka will prefer that file instead of the original in
-vendor, which has the lowest possible rank of 1.
-
For example, if /vendor/foo/bar.libsonnet contained an error, you could create
-/lib/foo/bar.libsonnet and fix it there.
-
-
-
Per environment
-
Another common case is overriding the entire vendor bundle per environment.
-
This is handy, when you for example want to test a change of an upstream
-library which is used in many environments (including prod) in a single one,
-without affecting all the others.
-
For this, Tanka lets you have a separate vendor, jsonnetfile.json and
-jsonnetfile.lock.json per environment. To do so:
-
Create tkrc.yaml
-
Tanka normally uses the jsonnetfile.json from your project to find its root.
-As we are going to create another one of that down the tree in the next step, we
-need another marker for <rootDir>.
-
For that, create an empty file called tkrc.yaml in your project’s root,
-alongside the original jsonnetfile.json.
-
-
Add a vendor to your environment
-
In your environments folder (e.g. /environments/default):
-
Terminal window
# init jsonnet bundler (creates jsonnetfile.json)
jbinit
-
# install the updated dependency
jbinstallgithub.com/foo/bar@v2
-
\ No newline at end of file
diff --git a/pr-preview/pr-1127/namespaces/index.html b/pr-preview/pr-1127/namespaces/index.html
deleted file mode 100644
index f308b015f..000000000
--- a/pr-preview/pr-1127/namespaces/index.html
+++ /dev/null
@@ -1,96 +0,0 @@
- Namespaces | Grafana Tanka
-
- Skip to content
When using Tanka, namespaces are handled slightly different compared to
-kubectl, because environments offer more granular control than contexts used
-by kubectl.
-
Default namespaces
-
In the spec.json of each environment, you can set the
-spec.namespace field, which is the default namespace. The default namespace is
-set for every resource that does not have a namespace set from Jsonnet.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Scenario
Action
1.
Your resource lacks namespace information (metadata.namespace) unset or ""
Tanka sets metadata.namespace to the value of spec.namespace in spec.json
2.
Your resource already has namespace information
Tanka does nothing, accepting the explicit namespace
-
While we recommend keeping environments limited to a single namespace, there are
-legit cases where it’s handy to have them span multiple namespaces, for example:
-
-
Some other piece of software (Operators, etc) require resources to be in a specific namespace
-
A rarely changing “base” environment holding resources deployed for many clusters in the same way
-
etc.
-
-
Cluster-wide resources
-
Some resources in Kubernetes are cluster-wide, meaning they don’t belong to a single namespace at all.
-
Tanka will make an attempt to not add namespaces to known cluster-wide types.
-It does this with a short list of types in the source code.
-
Tanka cannot feasibly maintain this list for all known custom resource types. In those cases, resources will have namespaces added to their manifests,
-and kubectl should happily apply them as non-namespaced resources.
-
If this presents a problem for your workflow, you can override this behavior
-per-resource, by setting the tanka.dev/namespaced annotation to "false"
-(must be of string type):
When a project becomes bigger over time and includes a lot of Kubernetes
-objects, it may become required to operate on only a subset of them (e.g. apply
-only a part of an application).
-
Tanka helps you with this, by allowing you to limit the used objects on the
-command line using the --target flag. Say you are deploying an nginx
-instance with a special nginx.conf and want to apply the ConfigMap first:
-
Terminal window
# show the ConfigMap
tkshow-tconfigmap/nginx.
-
# all good? apply!
tkapply-tconfigmap/nginx.
-
# and apply everything else:
tkapply.
-
The syntax of the --target / -t flag is --target=<kind>/<name>. If
-multiple objects match this pattern, all of them are used.
-
The --target / -t flag can be specified multiple times, to work with
-multiple objects.
-
Regular Expressions
-
The argument passed to the --target flag is interpreted as a
-RE2 regular expression.
-
This allows you to use all sorts of wildcards and other advanced matching
-functionality to select Kubernetes objects:
-
Terminal window
# show all deployments
tkshow.-t'deployment/.*'
-
# show all objects named "loki"
tkshow.-t'.*/loki'
-
Gotchas
-
When using regular expressions, there are some things to watch out for:
-
Line Anchors
-
Tanka automatically surrounds your regular expression with line anchors:
-
^<your expression>$
-
For example, --target 'deployment/.*' becomes ^deployment/.*$.
-
Quoting
-
Regular expressions may consist of characters that have special meanings in
-shell. Always make sure to properly quote your regular expression using single
-quotes.
-
Terminal window
# shell attempts to match the wildcard itself:
zsh-5.4.2$tkshow.-tdeployment/.*
zsh:nomatchesfound:deployment/.*
-
# properly quoted:
zsh-5.4.2$tkshow.-t'deployment/.*'
---
apiVersion:apps/v1
kind:Deployment
# ...
-
Excluding
-
Sometimes it may be desirably to exclude a single object, instead of including all others.
-
To do so, prepend the regular expression with an exclamation mark (!), like so:
Tanka supports
-server-side apply,
-which requires at least Kubernetes 1.16+, and was promoted to stable status in 1.22.
-
To enable server-side diff in tanka, add the following field to spec.json:
-
{
"spec": {
"applyStrategy": "server",
}
}
-
This also has the effect of changing the default diff strategy
-to server, but this can be overridden via command line flags or spec.json.
-
While server-side apply doesn’t have any effect on the resources being applied
-and is intended to be a general in-place upgrade to client-side apply, there are
-differences in how fields are managed that can make converting existing cluster
-resources a non-trival change.
-
Identifying and fixing these changes are beyond the scope of this guide, but
-many can be found before an apply by using the validate or server
-diff strategy.
-
Field conflicts
-
As part of the changes, you may encounter error messages which
-recommend the use of the --force-conflicts flag. Using tk apply --force
-in server-side mode will enable that flag for kubectl instead of
-kubectl --force, which no longer has any effect in server-side mode.
\ No newline at end of file
diff --git a/pr-preview/pr-1127/sitemap-0.xml b/pr-preview/pr-1127/sitemap-0.xml
deleted file mode 100644
index fcf649fef..000000000
--- a/pr-preview/pr-1127/sitemap-0.xml
+++ /dev/null
@@ -1 +0,0 @@
-https://tanka.dev/pr-preview/pr-1127/https://tanka.dev/pr-preview/pr-1127/completion/https://tanka.dev/pr-preview/pr-1127/config/https://tanka.dev/pr-preview/pr-1127/diff-strategy/https://tanka.dev/pr-preview/pr-1127/directory-structure/https://tanka.dev/pr-preview/pr-1127/env-vars/https://tanka.dev/pr-preview/pr-1127/exporting/https://tanka.dev/pr-preview/pr-1127/faq/https://tanka.dev/pr-preview/pr-1127/formatting/https://tanka.dev/pr-preview/pr-1127/garbage-collection/https://tanka.dev/pr-preview/pr-1127/helm/https://tanka.dev/pr-preview/pr-1127/inline-environments/https://tanka.dev/pr-preview/pr-1127/install/https://tanka.dev/pr-preview/pr-1127/jsonnet/injecting-values/https://tanka.dev/pr-preview/pr-1127/jsonnet/main/https://tanka.dev/pr-preview/pr-1127/jsonnet/native/https://tanka.dev/pr-preview/pr-1127/jsonnet/overview/https://tanka.dev/pr-preview/pr-1127/known-issues/https://tanka.dev/pr-preview/pr-1127/kustomize/https://tanka.dev/pr-preview/pr-1127/libraries/import-paths/https://tanka.dev/pr-preview/pr-1127/libraries/install-publish/https://tanka.dev/pr-preview/pr-1127/libraries/overriding/https://tanka.dev/pr-preview/pr-1127/namespaces/https://tanka.dev/pr-preview/pr-1127/output-filtering/https://tanka.dev/pr-preview/pr-1127/server-side-apply/https://tanka.dev/pr-preview/pr-1127/tutorial/abstraction/https://tanka.dev/pr-preview/pr-1127/tutorial/environments/https://tanka.dev/pr-preview/pr-1127/tutorial/jsonnet/https://tanka.dev/pr-preview/pr-1127/tutorial/k-lib/https://tanka.dev/pr-preview/pr-1127/tutorial/overview/https://tanka.dev/pr-preview/pr-1127/tutorial/parameters/https://tanka.dev/pr-preview/pr-1127/tutorial/refresher/
\ No newline at end of file
diff --git a/pr-preview/pr-1127/sitemap-index.xml b/pr-preview/pr-1127/sitemap-index.xml
deleted file mode 100644
index 71a315083..000000000
--- a/pr-preview/pr-1127/sitemap-index.xml
+++ /dev/null
@@ -1 +0,0 @@
-https://tanka.dev/pr-preview/pr-1127/sitemap-0.xml
\ No newline at end of file
diff --git a/pr-preview/pr-1127/tutorial/abstraction/index.html b/pr-preview/pr-1127/tutorial/abstraction/index.html
deleted file mode 100644
index 3e57d390a..000000000
--- a/pr-preview/pr-1127/tutorial/abstraction/index.html
+++ /dev/null
@@ -1,90 +0,0 @@
- Abstraction | Grafana Tanka
-
- Skip to content
While we won’t need to touch the resource definitions directly that frequently
-anymore now that our deployments definitions are parametrized, the
-main.jsonnet file is still very long and hard to read. Especially because of
-all the brackets, it’s even worse than yaml at the moment.
-
Splitting it up
-
Let’s start cleaning this up by separating logical pieces into distinct files:
-
-
main.jsonnet: Still our main file, importing the other files
-
grafana.libsonnet: Deployment and Service for the Grafana instance
-
prometheus.libsonnet: Deployment and Service for the Prometheus server
-
-
-
/environments/default/grafana.libsonnet
{
new(name, port)::{
deployment: {
apiVersion:'apps/v1',
kind:'Deployment',
metadata: {
name: name,
},
spec: {
selector: {
matchLabels: {
name: name,
},
},
template: {
metadata: {
labels: {
name: name,
},
},
spec: {
containers: [
{
image:'grafana/grafana',
name: name,
ports: [{
containerPort: port,
name:'ui',
}],
},
],
},
},
},
},
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name: name,
},
name: name,
},
spec: {
ports: [{
name:'%s-ui'% name,
port: port,
targetPort: port,
}],
selector: {
name: name,
},
type:'NodePort',
},
},
}
}
-
The file should contain an object with the same function that was defined under the grafana in /environments/default/main.jsonnet, but called new instead of grafana.
-Do the same for /environments/default/prometheus.libsonnet as well.
-
/environments/default/main.jsonnet
local grafana =import"grafana.libsonnet";
local prometheus =import"prometheus.libsonnet";
-
{
grafana: grafana.new("grafana", 3000),
prometheus: prometheus.new("prometheus", 9090),
}
-
Helper utilities
-
While main.jsonnet is now short and very readable, the other two files are not
-really an improvement over regular yaml, mostly because they are still full of
-boilerplate.
-
Let’s use functions to create some useful helpers to reduce the amount of
-repetition. For that, we create a new file called kubernetes.libsonnet, which
-will hold our Kubernetes utilities.
-
A Deployment constructor
-
Creating a Deployment requires some mandatory information and a lot of
-boilerplate. A function that creates one could look like this:
-
/environments/default/kubernetes.libsonnet
{
deployment: {
new(name, containers):: {
apiVersion:"apps/v1",
kind:"Deployment",
metadata: {
name: name,
},
spec: {
selector: { matchLabels: {
name: name,
}},
template: {
metadata: { labels: {
name: name,
}},
spec: { containers: containers }
}
}
}
}
}
-
Invoking this function will substitute all the variables with the respective
-passed function parameters and return the assembled object.
-
Let’s simplify our grafana.libsonnet a bit:
-
local k =import"kubernetes.libsonnet";
-
{
new(name, port):: {
deployment: k.deployment.new(name, [{
image: 'grafana/grafana',
name: name,
ports: [{
containerPort: port,
name: 'ui',
}],
}]),
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name: name,
},
name: name,
},
spec: {
ports: [{
name:'%s-ui'% name,
port: port,
targetPort: port,
}],
selector: {
name: name,
},
type:'NodePort',
},
},
}
}
-
This drastically simplified the creation of the Deployment, because we do not
-need to remember how exactly a Deployment is structured anymore. Just use
-our helper and you are good to go.
-
\ No newline at end of file
diff --git a/pr-preview/pr-1127/tutorial/environments/index.html b/pr-preview/pr-1127/tutorial/environments/index.html
deleted file mode 100644
index 6a86ba596..000000000
--- a/pr-preview/pr-1127/tutorial/environments/index.html
+++ /dev/null
@@ -1,118 +0,0 @@
- Environments | Grafana Tanka
-
- Skip to content
At this point, our configuration is already flexible and concise, but not
-really reusable. Let’s take a look at Tanka’s third buzzword as well: Environments.
-
These days, the same piece of software is usually deployed many times inside a
-single organization. This could be dev, testing and prod environments, but
-also regions (europe, us, asia) or individual customers (foo-corp,
-bar-gmbh, baz-inc).
-
Most of the application however is exactly the same across those environments …
-usually only configuration, scaling or small details are different after all.
-YAML (and thus kubectl) provides us only one solution here: Duplicating the
-directory, changing the details, maintaining both. But what if you have 32
-environments? Correct! Then you have to maintain 32 directories of YAML. And we can all
-imagine the nightmare of these files drifting apart from each other.
-
But again, Jsonnet can be the solution: By extracting the actual objects
-into a library, you can import them in as many environments as you need!
-
Creating a library
-
A library is nothing special, just a folder of .libsonnet files somewhere in the import paths:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Path
Description
/lib
Custom, user-created libraries only for this project.
/vendor
External libraries installed using Jsonnet-bundler
-
So for our purpose /lib fits best, as we are only creating it for our current
-project. Let’s set one up:
-
Terminal window
mkdirlib/prom-grafana# a folder for our prom-grafana library
cdlib/prom-grafana
-
# inside lib/prom-grafana:
touchprom-grafana.libsonnet# library file that will be imported
touchconfig.libsonnet# _config and images
-
For documentation purposes it is handy to have a separate file for parameters and used images:
-
config.libsonnet
{
// +:: is important (we don't want to override the
So far we have only used the environments/default environment. Let’s create some real ones:
-
Terminal window
tkenvaddenvironments/prom-grafana/dev--namespace=prom-grafana-dev# one for dev ...
tkenvaddenvironments/prom-grafana/prod--namespace=prom-grafana-prod# and one for prod
-
-
All that’s left now is importing the library and configuring it. For dev, the defaults defined in /lib/prom-grafana/config.libsonnet should be sufficient, so we do not override anything:
-
/environments/prom-grafana/dev
import"prom-grafana/prom-grafana.libsonnet"
-
For prod however, it is a bad idea to rely on latest for the images .. let’s
-add some proper tags:
-
/environments/prom-grafana/prod
(import"prom-grafana/prom-grafana.libsonnet") +
{
// again, we only want to patch, not replace, thus +::
_images+:: {
// we update this one entirely, so we can replace this one (:)
promgrafana: {
prometheus:"prom/prometheus:v2.14",
grafana:"grafana/grafana:6.5.2"
}
}
}
-
Patching
-
The above works well for libraries we control ourselves, but what when another
-team wrote the library, it was installed using jb from GitHub or you can’t
-change it easily?
-
Here comes the already familiar +: (or +::) syntax into play. It allows to
-partially override values of an object. Let’s say we wanted to add some labels to the Prometheus Deployment, but our _config params don’t allow us to. We can still do this in our main.jsonnet:
-
(import"prom-grafana/prom-grafana.libsonnet") +
{
promgrafana+: {
prometheus+: {
deployment+: {
metadata+: {
labels+: {
foo:"bar"
}
}
}
}
}
}
-
By using the +: operator all the time and only foo: "bar" uses “:”, we only
-override the value of "foo", while leaving the rest of the object like it was.
The most powerful piece of Tanka is the Jsonnet data templating
-language. Jsonnet is a superset of JSON, adding variables,
-functions, patching (deep merging), arithmetic, conditionals and many more to
-it.
-
It has a lot in common with more real programming languages such as JavaScript
-than with markup languages, still it is tailored specifically to representing
-data and configuration. As opposed to JSON (and YAML) it is a language meant for
-humans, not for computers.
-
Creating a new project
-
To get started with Tanka and Jsonnet, let’s initiate a new project, in which we will install both Prometheus and Grafana into our Kubernetes cluster:
-
Terminal window
mkdirprom-grafana && cdprom-grafana# create a new folder for the project and change to it
tkinit# initiate a new project
-
This gives us the following directory structure:
-
Directoryenvironments
-
Directorydefaultdefault environment
-
main.jsonnetmain file (important!)
spec.jsonenvironment’s config
jsonnetfile.json
Directorylib/libraries
…
Directoryvendor/external libraries
…
-
For the moment, we only really care about the environments/default folder. The
-purpose of the other directories will be explained later in this guide (mostly
-related to libraries).
-
Environments
-
When using Tanka, you apply configuration for an Environment to a
-Kubernetes cluster. An Environment is some logical group of pieces that form
-an application stack.
-
Grafana Labs for example runs Loki,
-Cortex and of course
-Grafana for our Grafana
-Cloud hosted offering. For each of these, we have a
-separate environment. Furthermore, we like to see changes to our code in
-separate dev setups to make sure they are all good for production usage – so
-we have dev and prod environments for each app as well, as prod
-environments usually require other configuration (secrets, scale, etc) than
-dev. This roughly leaves us with the following:
There is no limit in Environment complexity, create as many as you need to model
-your own requirements. Grafana Labs for example also has all of these multiplied per
-high-availability region.
-
To get started, a single environment is enough. Lets use the automatically
-created environnments/default for that.
-
Defining Resources
-
While kubectl loads all .yaml files in a certain folder, Tanka has a single
-file that serves as the canonical source for all contents of an environment,
-called main.jsonnet. This is just like Go has the main.go or C++ the
-main.cpp.
-
Similar to JSON, each .jsonnet file holds a single object. The one returned by
-main.jsonnet will hold all of your Kubernetes resources:
-
main.jsonnet
{
"some_deployment": { /* ... */ },
"some_service": { /* ... */ }
}
-
They may be deeply nested, Tanka extracts everything that looks like a
-Kubernetes resource automatically.
-
So let’s rewrite the previous .yaml to
-very basic .jsonnet:
-
/environments/default/main.jsonnet
{
// Grafana
grafana: {
deployment: {
apiVersion:'apps/v1',
kind:'Deployment',
metadata: {
name:'grafana',
},
spec: {
selector: {
matchLabels: {
name:'grafana',
},
},
template: {
metadata: {
labels: {
name:'grafana',
},
},
spec: {
containers: [
{
image:'grafana/grafana',
name:'grafana',
ports: [{
containerPort:3000,
name:'ui',
}],
},
],
},
},
},
},
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name:'grafana',
},
name:'grafana',
},
spec: {
ports: [{
name:'grafana-ui',
port:3000,
targetPort:3000,
}],
selector: {
name:'grafana',
},
type:'NodePort',
},
},
},
-
// Prometheus
prometheus: {
deployment: {
apiVersion:'apps/v1',
kind:'Deployment',
metadata: {
name:'prometheus',
},
spec: {
minReadySeconds:10,
replicas:1,
revisionHistoryLimit:10,
selector: {
matchLabels: {
name:'prometheus',
},
},
template: {
metadata: {
labels: {
name:'prometheus',
},
},
spec: {
containers: [
{
image:'prom/prometheus',
imagePullPolicy:'IfNotPresent',
name:'prometheus',
ports: [
{
containerPort:9090,
name:'api',
},
],
},
],
},
},
},
},
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name:'prometheus',
},
name:'prometheus',
},
spec: {
ports: [
{
name:'prometheus-api',
port:9090,
targetPort:9090,
},
],
selector: {
name:'prometheus',
},
},
},
},
}
-
At the moment, this is even more verbose because we have effectively converted
-YAML to JSON, which requires more characters by design.
-
But Jsonnet opens up enough possibilities to improve this a lot, which will be
-covered in the next sections.
-
Taking a look at the generated resources
-
So far so good, but can we make sure Tanka correctly finds our resources? We
-can! By running tk show you can see the good old yaml, just as kubectl
-receives it:
-
/prom-grafana $
# run from the project root:
tkshowenvironments/default
-
Output
apiVersion: apps/v1
kind: Deployment
metadata:
name: grafana
spec:
selector:
# ...
-
Spend some time here and try to identify resources from the output in the
-.jsonnet source.
-
-
Connecting to the cluster
-
The YAML looks as expected? Let’s apply it to the cluster. To do so, Tanka needs
-some additional configuration.
-
While kubectl uses a $KUBECONFIG environment variable and a file in the home
-directory to store the currently selected cluster, Tanka takes a more explicit
-approach:
-
Each environment has a file called spec.json, which includes the information
-to select a cluster:
-
{
"apiVersion": "tanka.dev/v1alpha1",
"kind": "Environment",
"metadata": {
"name": "default"
},
"spec": {
"apiServer": "https://127.0.0.1:6443", // cluster to use
"namespace": "monitoring"// default namespace for all created resources
}
}
-
You still have to setup a cluster in $KUBECONFIG that matches this IP – Tanka
-will automatically find and use it. This also means that all of your kubectl
-clusters just work.
-
This allows us to make sure that you will never accidentally apply to the wrong
-cluster.
-
-
Verifying the changes
-
Before applying to the cluster, Tanka gives you a chance to check that your
-changes actually behave as expected: tk diff works just like git diff – you
-see what will be changed.
As you can see, it shows everything as to-be created .. just as we’d expect,
-since we are using a blank namespace.
-
-
Applying to the cluster
-
Once it’s all looking good, tk apply serves the exact same purpose as kubectl apply:
-
/prom-grafana $
tkapplyenvironments/default
-
Applying to namespace 'monitoring' of cluster 'default' at 'https://127.0.0.1:6443' using context 'default'.
Please type 'yes' to confirm: yes
deployment.apps/grafana created
deployment.apps/prometheus created
service/grafana created
service/prometheus created
-
It shows you the diff first and the chosen cluster once more and requires
-interactive approval (type yes).
-
After that, kubectl is used to apply to the cluster. By piping to
-kubectl Tanka makes sure it behaves exactly as you would expect it. No
-edge-cases of differing Kubernetes client implementations should ever occur.
The last section has shown that using a library for creating Kubernetes objects
-can drastically simplify the code you need to write. However, there is a huge
-amount of different kinds of objects and the Kubernetes API is evolving (and
-thus changing) quite rapidly.
-
Writing and maintaining such a library could be a full-time job on it’s own.
-Luckily, it is possible to generate such a library from the Kubernetes OpenAPI
-specification! Even better, it has already been done for you.
As k8s-libsonnet has broken compatibility in a few places with ksonnet-lib (for good
-reason), we have instrumented the widely used ksonnet-util library with a
-compatibility layer to improve the developer and user experience:
-https://github.com/grafana/jsonnet-libs/tree/master/ksonnet-util
-
If you do not have any strong reasons against it, just adopt the wrapper as
-well, it will ease your work. Many of the original ksonnet-util enhancements
-have already made their way into k8s-libsonnet.
Like every other external library, k8s-libsonnet can be installed using
-jsonnet-bundler.
-However, Tanka already did this for you during project
-creation (tk init):
Because of how jb works, the library can be imported as
-github.com/jsonnet-libs/k8s-libsonnet/1.21/main.libsonnet. Most external
-libraries (including our wrapper) expect it as a simple k.libsonnet (without
-the package prefix).
-
To support both, Tanka automatically created an alias file for you:
-/lib/k.libsonnet that just imports the actual library, exposing it under this
-alternative name as well.
-
-
Using it
-
First we need to import it in main.jsonnet:
-
local k = import "kubernetes.libsonnet";
local k = import "github.com/grafana/jsonnet-libs/ksonnet-util/kausal.libsonnet";
local grafana = import "grafana.libsonnet";
local prometheus = import "prometheus.libsonnet";
{ /* ... */ }
-
-
Now that we have installed the correct version, let’s use it in
-/environments/default/grafana.libsonnet instead of our own helper:
-
/environments/default/grafana.libsonnet
local k =import"github.com/grafana/jsonnet-libs/ksonnet-util/kausal.libsonnet";
Now that creating the individual objects does not take more than 5 lines, we can
-merge it all back into a single file (main.jsonnet) and take a look at the
-whole picture:
-
local k =import"github.com/grafana/jsonnet-libs/ksonnet-util/kausal.libsonnet";
-
{
local deployment = k.apps.v1.deployment,
local container = k.core.v1.container,
local port = k.core.v1.containerPort,
local service = k.core.v1.service,
-
prometheus: {
deployment: deployment.new(
name="prometheus", replicas=1,
containers=[
container.new("prometheus", "prom/prometheus")
+ container.withPorts([port.new("api", 9090)]),
],
),
service: k.util.serviceFor(self.deployment),
},
grafana: {
deployment: deployment.new(
name="grafana", replicas=1,
containers=[
container.new("grafana", "grafana/grafana")
+ container.withPorts([port.new("ui", 3000)]),
],
),
service:
k.util.serviceFor(self.deployment)
+ service.mixin.spec.withType("NodePort"),
},
}
-
That’s a pretty big improvement, considering how verbose and error-prone it was
-before!
-
Bonus: Config object
-
While this is already a huge improvement, we can do a bit more. There is still some repetition in the main.jsonnet file.
-The most straightforward way to address this is by creating a hidden object that holds all actual values in a single place to be consumed by the actual resources.
-
Luckily, Jsonnet has the key:: "value" stanza for private fields. Such are only available during compiling and will be removed from the actual output.
-
Such an object could look like this:
-
{
_config:: {
grafana: {
port:3000,
name:"grafana",
},
prometheus: {
port:9090,
name:"prometheus"
}
}
}
-
We can then replace hardcoded values with a reference to this object:
-
local k =import"github.com/grafana/jsonnet-libs/ksonnet-util/kausal.libsonnet";
Welcome to the Tanka tutorial!
-The following sections will explain how to deploy an example stack,
-(Grafana and
-Prometheus), to Kubernetes. We will also deal with parameters, differences between dev and prod and how to stop worrying and love libraries.
Deploying using Tanka worked well, but it did not really improve the situation
-in terms of maintainability and readability.
-
To do so, the following sections will explore some ways Jsonnet provides us with.
-
Functions parameters
-
Defining our deployment in a single block is not the best solution.
-Luckily with Jsonnet we can split our configuration into smaller, self-contained chunks.
-
Let’s start by creating a new function in main.jsonnet responsible for creating a Grafana deployment:
-
environments/default/main.jsonnet
localgrafana() = {
deployment: {
apiVersion:'apps/v1',
kind:'Deployment',
metadata: {
name:'grafana',
},
spec: {
selector: {
matchLabels: {
name:'grafana',
},
},
template: {
metadata: {
labels: {
name:'grafana',
},
},
spec: {
containers: [
{
image:'grafana/grafana',
name:'grafana',
ports: [{
containerPort:3000,
name:'ui',
}],
},
],
},
},
},
},
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name:'grafana',
},
name:'grafana',
},
spec: {
ports: [{
name:'grafana-ui',
port:3000,
targetPort:3000,
}],
selector: {
name:'grafana',
},
type:'NodePort',
},
},
};
-
and let’s use it in our main configuration:
-
environments/default/main.jsonnet
localgrafana() = {
# ...
};
-
{
grafana: {
# ...
},
grafana:grafana(),
prometheus:#...
};
-
We can then replace hardcoded values by adding parameters to our function:
-
environments/default/main.jsonnet
localgrafana() = {
localgrafana(name, port) = {
deployment: {
apiVersion:'apps/v1',
kind:'Deployment',
metadata: {
name:'grafana',
name: name,
},
spec: {
selector: {
matchLabels: {
name:'grafana',
name: name,
},
},
template: {
metadata: {
labels: {
name:'grafana',
name: name,
},
},
spec: {
containers: [
{
image:'grafana/grafana',
name:'grafana',
name: name,
ports: [{
containerPort:3000,
containerPort: port,
name:'ui',
}],
},
],
},
},
},
},
service: {
apiVersion:'v1',
kind:'Service',
metadata: {
labels: {
name:'grafana',
name: name,
},
name:'grafana',
name: name,
},
spec: {
ports: [{
name:'grafana-ui',
port:3000,
targetPort:3000,
name:'%s-ui'% name, // printf-style formatting
port: port,
targetPort: port,
}],
selector: {
name:'grafana',
name: name,
},
type:'NodePort',
},
},
};
-
and update the usage accordingly:
-
environments/default/main.jsonnet
localgrafana(name, port) = {
# ...
};
-
{
grafana:grafana(),
grafana:grafana('grafana', 3000),
prometheus:#...
};
-
-
Now we do not only have a single place to change tunables, but also won’t suffer
-from mismatching labels and selectors anymore, as they are defined in a single
-place and all changed at once.
-
\ No newline at end of file
diff --git a/pr-preview/pr-1127/tutorial/refresher/index.html b/pr-preview/pr-1127/tutorial/refresher/index.html
deleted file mode 100644
index 3aa9ff315..000000000
--- a/pr-preview/pr-1127/tutorial/refresher/index.html
+++ /dev/null
@@ -1,101 +0,0 @@
- Refresher on deploying | Grafana Tanka
-
- Skip to content
To understand how Tanka works, it is important to know what steps are required
-for the task of deploying Grafana and Prometheus to Kubernetes:
-
-
Prometheus
-
-
A Deployment must be created, to run the prom/prometheus image
-
Also a Service is needed for Grafana to be able to connect port 9090 of
-Prometheus.
-
-
-
Grafana
-
-
Another Deployment is required for the Grafana server.
-
To connect to the web interface, we will be using a Service of type
-NodePort.
-
-
-
-
Before taking a look how Tanka can help doing so, let’s recall how to do it with
-plain kubectl.
-
Writing the yaml
-
kubectl expects the resources it should create in .yaml format.
-For Grafana:
-
grafana.yaml
# Grafana server Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: grafana
spec:
selector:
matchLabels:
name: grafana
template:
metadata:
labels:
name: grafana
spec:
containers:
- image: grafana/grafana
name: grafana
ports:
- containerPort: 3000
name: ui
---
# Grafana UI Service NodePort
apiVersion: v1
kind: Service
metadata:
labels:
name: grafana
name: grafana
spec:
ports:
- name: grafana-ui
port: 3000
targetPort: 3000
selector:
name: grafana
type: NodePort
-
and for Prometheus:
-
prometheus.yaml
# Prometheus server Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: prometheus
spec:
selector:
matchLabels:
name: prometheus
template:
metadata:
labels:
name: prometheus
spec:
containers:
- image: prom/prometheus
name: prometheus
ports:
- containerPort: 9090
name: api
---
# Prometheus API Service
apiVersion: v1
kind: Service
metadata:
labels:
name: prometheus
name: prometheus
spec:
ports:
- name: prometheus-api
port: 9090
targetPort: 9090
selector:
name: prometheus
-
That’s pretty verbose, right?
-
Even worse, there are labels and matchers (e.g. prometheus) that need to be
-exactly the same scattered across the file. It’s a nightmare to debug and
-furthermore harms readability a lot.
-
Deploying to the cluster
-
To actually apply those resources, copy them into .yaml files and use:
-
Terminal window
kubectlapply-fprometheus.yaml-fgrafana.yaml
-
deployment.apps/grafana created
deployment.apps/prometheus created
service/grafana created
service/prometheus created
-
Checking it worked
-
So far so good, but can we tell it actually did what we wanted? Let’s test that
-Grafana can connect to Prometheus!
-
Terminal window
# Temporarily forward Grafana to localhost
kubectlport-forwarddeployments/grafana8080:3000
-
Now go to http://localhost:8080 in your browser and login using admin:admin.
-Then navigate to Connections > Data sources > Add new data source, choose
-Prometheus as type and enter http://prometheus:9090 as URL. Hit
-Save & Test which should yield a big green bar telling you everything is good.
-
Cool! This worked out well for this small example, but the .yaml files are
-hard to read and maintain. Especially when you need to deploy this exact same
-thing in dev and prod your choices are very limited.
-
Let’s explore how Tanka can help us here in the next section!
-
Cleaning up
-
Let’s remove everything we created to start fresh with Jsonnet in the next section:
