Template Text Files with Parameters

Pass parameters to ConfigMap data

The team behind ksonnet is stepping back from the project. As a result, work on ksonnet will end and the GitHub repositories will be archived. You can read more about our decision here.

Overview

Templating text files allows customizing configuration files across ksonnet environments.

This page provides a series of examples to show how to template text files stored in a ConfigMap.

Prerequisites

  • You should have a working ksonnet application. Knowledge of components and ConfigMaps are helpful but not required.

Import a Text File with importstr

A text file can be imported into a component by the built-in Jsonnet function, importstr.

This loads the file as UTF-8 encoded string.

Create a text file that can be stored in a ConfigMap.

config.txt
1
ksonnet.is=okay

In your ksonnet application, create a component that imports the text file using the importstr function. Pass the path of the configuration file in quotes.

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": importstr "config.txt",
  },
}

The components/ directory should contain the following files at this point.

├── components
│   ├── config.txt
│   ├── example.jsonnet
│   └── params.libsonnet

Generating the manifest shows the text file was successfully imported.

$ ks show default
---
apiVersion: v1
data:
  config-file: |
    ksonnet.is=okay
kind: ConfigMap
metadata:
  labels:
    ksonnet.io/component: example
  name: example

Block Text and String Formatting

Another method is to use a text block and place the contents of the text file directly inside the component.

Embedding the text within the component can be done by a text block using ||| as delimiters.

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": |||
      ksonnet.is=okay
    |||
  },
}

String formatting in a text block can be done through substitution using the %s for string.

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": |||
      ksonnet.is=%s
    ||| % "good",
  },
}
Note: To pass an integer or float instead, use the %g operator.

Multiple arguments for string formatting can be passed with the elements in an array.

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  apiVersion: "v1",
  kind: "configMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": |||
      ksonnet.is=%s
      ksonnet.isalso=%s
    ||| % ["good", "interesting"],
  },
}

Text Templating with importstr

String formatting can be used in conjunction with importstr.

In config.txt, create a key called adjective for string formatting.

config.txt
1
ksonnet.is=%(adjective)s

In the component, create a local variable called config_file that stores the import of config.txt. Jsonnet does not allow computed imports so a variable is needed rather than importing directly.

Create a key-value pair where the key is the name from config.txt and the value is a string to be substituted.

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
local config_file = importstr "config.txt";

{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": config_file % {
      "adjective": "fun",
    },
  },
}

Generating the manifest shows the ConfigMap contains the string defined in our component.

$ ks show default
---
apiVersion: v1
data:
  config: |
    ksonnet.is=fun
kind: ConfigMap
metadata:
  labels:
    ksonnet.io/component: example
  name: example

Text Templating with Paramters

Create a params variable that accesses the ksonnet parameters set for the example component then change the substitution to use params as shown below:

example.jsonnet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
local params = std.extVar("__ksonnet/params").components["example"];
local config_file = importstr "config.txt";

{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "example",
  },
  data: {
    "config": config_file % params,
  },
}

Set a new paramter with the form:ks param set <component> <param> <value>.

In this case, config.txt is expecting a key called adjective so we can set this using ksonnet:

$ ks param set example adjective amazing
$ ks param list
COMPONENT PARAM     VALUE
========= =====     =====
example   adjective 'amazing'
$ ks show default
---
apiVersion: v1
data:
  config: |
    ksonnet.is=amazing
kind: ConfigMap
metadata:
  labels:
    ksonnet.io/component: example
  name: example
Last updated on: September 20, 2018