local tanka_util = import "github.com/grafana/jsonnet-libs/tanka-util/main.libsonnet"

Package tanka_util provides jsonnet tooling that works well with Grafana Tanka features. This package implements Helm and Kustomize support for Grafana Tanka.

Warning: Functionality required by this library is still experimental and may break.

The helm.template function converts a Helm Chart into a Jsonnet object to be consumed by tools like Tanka. Similarly the kustomize.build function expands Kustomizations.

Helm Charts are required to be available on the local file system and are resolved relative to the file that calls helm.template.

Kustomizations are also resolved relative to the file that calls kustomize.build.

local tanka = import 'github.com/grafana/jsonnet-libs/tanka-util/main.libsonnet';
local helm = tanka.helm.new(std.thisFile);
local kustomize = tanka.kustomize.new(std.thisFile);

{
  // render the Grafana Chart, set namespace to "test"
  grafana: helm.template('grafana', './charts/grafana', {
    values: {
      persistence: { enabled: true },
      plugins: ['grafana-clock-panel'],
    },
    namespace: 'test',
  }),

  // render the Prometheus Kustomize
  // then entrypoint for `kustomize build` will be ./base/prometheus/kustomization.yaml
  prometheus: kustomize.build('./base/prometheus'),
}

For more information on that see https://tanka.dev/helm

The functionality of helm.template is based on the helm template command. Because Jsonnet does not support executing arbitrary command for good reasons, a different way was required.

To work around this, Tanka instead binds special functionality into Jsonnet that provides helm template.

This however means this library and all libraries using this library are not compatible with google/go-jsonnet or google/jsonnet.

Kustomize is build so that each kustomization can pull another kustomization from the internet. Due to this feature it is not feasible to ensure hermetic and reprodicible kustomize builds from within Tanka. Beware of that when using the Kustomize functionality.

• obj environment
  • fn new(name, namespace, apiserver)
  • fn withApiServer(apiserver)
  • fn withApplyStrategy(applyStrategy)
  • fn withData(data)
  • fn withDataMixin(data)
  • fn withInjectLabels(bool)
  • fn withLabels(labels)
  • fn withLabelsMixin(labels)
  • fn withName(name)
  • fn withNamespace(namespace)
  • fn withResourceDefaults(labels)
  • fn withResourceDefaultsMixin(labels)
• obj helm
  • fn new(calledFrom)
  • fn template(name, chart, conf)
• obj k8s
  • fn patchKubernetesObjects(object, patch)
  • fn patchLabels(object, labels)
• obj kustomize
  • fn new(calledFrom)
  • fn build(path, conf)

environment provides a base to create an inline Tanka environment.

new(name, namespace, apiserver)

new initiates an inline Tanka environment

withApiServer(apiserver)

withApiServer sets the Kubernetes cluster this environment should apply to. Must be the full URL, e.g. https://cluster.fqdn:6443

withApplyStrategy(applyStrategy)

withApplyStrategy sets the Kubernetes apply strategy used for this environment. Must be client or server

withData(data)

withData adds the actual Kubernetes resources to the inline environment.

withDataMixin(data)

withDataMixin adds the actual Kubernetes resources to the inline environment. Note: This function appends passed data to existing values

withInjectLabels(bool)

withInjectLabels adds a "tanka.dev/environment" label to each created resource. Required for garbage collection.

withLabels(labels)

withLabels adds arbitrary key:value labels.

withLabelsMixin(labels)

withLabelsMixin adds arbitrary key:value labels. Note: This function appends passed data to existing values

withName(name)

withName sets the environment name.

withNamespace(namespace)

withNamespace sets the default namespace for objects that don't explicitely specify one.

withResourceDefaults(labels)

withResourceDefaults sets defaults for all resources in this environment.

withResourceDefaultsMixin(labels)

withResourceDefaultsMixin sets defaults for all resources in this environment. Note: This function appends passed data to existing values

helm allows the user to consume Helm Charts as plain Jsonnet resources. This implements Helm support for Grafana Tanka.

new(calledFrom)

new initiates the helm object. It must be called before any helm.template call:

// std.thisFile required to correctly resolve local Helm Charts
helm.new(std.thisFile)

template(name, chart, conf)

template expands the Helm Chart to its underlying resources and returns them in an Object, so they can be consumed and modified from within Jsonnet.

This functionality requires Helmraiser support in Jsonnet (e.g. using Grafana Tanka) and also the helm binary installed on your $PATH.

k8s provides common utils to modify Kubernetes objects.

patchKubernetesObjects(object, patch)

patchKubernetesObjects applies patch to all Kubernetes objects it finds in object.

patchLabels(object, labels)

patchLabels finds all Kubernetes objects and adds labels to them.

kustomize allows the user to expand Kustomize manifests into plain Jsonnet resources. This implements Kustomize support for Grafana Tanka.

new(calledFrom)

new initiates the kustomize object. It must be called before any kustomize.build call:

// std.thisFile required to correctly resolve local Kustomize objects
kustomize.new(std.thisFile)

build(path, conf)

build expands the Kustomize object to its underlying resources and returns them in an Object, so they can be consumed and modified from within Jsonnet.

This functionality requires Kustomize support in Jsonnet (e.g. using Grafana Tanka) and also the kustomize binary installed on your $PATH.

path is relative to the file calling this function.