Template Text Files with Parameters

Pass parameters to ConfigMap data

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