Grafana Tanka

Tanka projects are organized around environments and dependency management files. The core structure typically includes:

• environments/: Contains environment-specific configurations.
• lib/: Local libraries specific to the project.
• vendor/: External libraries installed via jb (jsonnet-bundler).
• jsonnetfile.json: Defines direct dependencies.
• jsonnetfile.lock.json: Contains exact versions and SHA256 hashes of all dependencies.

Note: The vendor/ directory can be added to .gitignore as long as jsonnetfile.lock.json is committed to source control.

Tanka is designed as a fully compatible, drop-in replacement for the core ksonnet workflow, specifically the show, diff, and apply commands.

Unlike ksonnet, Tanka does not include:

• A rich code generator for CLI-based editing of Kubernetes objects.
• Built-in dependency management.
• Complex abstraction layers.

Tanka prioritizes being a minimal tool, so these features are intentionally omitted and are not planned for future addition.

Tanka uses Jsonnet instead of Helm's string-based YAML templating.

Key differences include:

• Structure Awareness: Helm uses string templating which is unaware of YAML syntax, making debugging difficult. Tanka uses Jsonnet, which is a superset of JSON and understands data structures.
• Extensibility: Helm charts often require modification to support new parameters. Tanka/Jsonnet allows you to use mixing (patching and deep-merging) to apply changes on top of library outputs without modifying the original source.

You can reduce boilerplate in your service definitions by creating a kubernetes.libsonnet file containing constructor functions for standard Kubernetes resources like Deployment and Service. This allows you to focus on the specific configuration (like container images and ports) rather than the structural requirements of the Kubernetes API.

// /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 }
        }
      }
    }
  }
}

Tanka invokes the Jsonnet compiler on a file named main.jsonnet. The compiler evaluates the code into a single JSON object. Because kubectl expects a YAML stream of individual manifests rather than a single nested tree, Tanka traverses the resulting JSON object to find valid Kubernetes manifests.

An object is identified as a valid Kubernetes manifest if it contains both apiVersion and kind keys.

Acceptance tests for Tanka cover end-to-end use cases, such as creating a new Tanka environment and pushing it to an ephemeral Kubernetes cluster.

To run these tests, you must have the Dagger CLI >= 0.11 installed. The command must be executed from the root directory of the project.

make acceptance-tests

Tanka uses jb (jsonnet-bundler) to manage external libraries in the vendor/ directory.

• jsonnetfile.json: The source of truth for direct dependencies. It should only include packages that are directly required by your project; recursive dependencies are handled automatically.
• jsonnetfile.lock.json: Automatically generated on every run of jsonnet-bundler. It contains the exact versions and sha256 hashes of all packages in vendor/ to ensure reproducible builds.

Best Practice: Both jsonnetfile.json and jsonnetfile.lock.json must be checked into source control to ensure jb install produces identical environments across different machines.

You can use Jsonnet top-level arguments to make environment configuration (like apiServer or namespace) dynamic. This is useful for local test clusters where the API server address changes.

Define your main.jsonnet as a function that accepts these arguments, then pass the values using the --tla-str flag with the tk CLI.

// 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: { /* ... */ },
}

tk apply --tla-str apiServer=https://127.0.0.1:4758 environments/minikube-test-setup