ConfigMap

A ConfigMap holds named pieces of text: a bootstrap script, a config file, a message of the day. A Workstation or a WorkstationConfig points a scripts[] or files[] entry at one of its keys instead of pasting the content inline.

Use one when the same text belongs on several machines, or when a script has grown long enough that inlining it buries the settings around it. Editing the ConfigMap updates every manifest that references it, rather than each copy separately.

apiVersion: core.ringleader.dev/v1
kind: ConfigMap

It has no status. The content is dereferenced by the control plane when a workstation’s configuration is resolved, so what reaches the machine is an ordinary inline body.

Example

apiVersion: core.ringleader.dev/v1
kind: ConfigMap
metadata:
  name: bootstrap
  namespace: dev
spec:
  data:
    setup.sh: |
      #!/bin/sh
      set -e
      mkdir -p /opt/app
      echo "provisioned by ringleader" > /opt/app/MARKER
    motd: |
      Welcome to the platform team's development box.

Fields

There is nothing else. A ConfigMap is content and a name; every decision about where the content lands lives on the entry that references it.

Three rules are checked at apply:

• A key starts with a letter or digit and otherwise holds letters, digits, ., _ and -.
• A value must be a non-empty string. A non-string value is refused, since this is text, and for binary content a files[] entry’s url is the route. An empty value is refused too: a file referencing it would have no content source at all and a script no body to run, so omit the key instead.
• All the values together stay under 256 KiB.

Referencing one

Replace an entry’s inline content with contentFrom:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: base
  namespace: dev
spec:
  selector:
    matchLabels:
      tier: dev
  scripts:
    - name: bootstrap
      phase: system
      contentFrom:
        configMapRef:
          name: bootstrap
          key: setup.sh
  files:
    - path: /etc/motd
      mode: "0644"
      contentFrom:
        configMapRef:
          name: bootstrap
          key: motd

Rules worth knowing:

• contentFrom is available on scripts[] and files[], and nowhere else.
• Exactly one content source per entry. contentFrom alongside content (or, for a file, contentBase64 or url) is refused at apply rather than silently preferring one of them.
• Same namespace only. There is no cross-namespace reference.
• Everything else on the entry still applies. A file keeps its path, owner, mode and parents; a script keeps its phase, runPolicy, env and timeoutSeconds. Only the body comes from elsewhere.

Ordering and apply

A ConfigMap is applied before the workstation and configuration objects in the same manifest bundle, so you can put the content and the layer that references it in one file and rl apply -f it in a single command.

When a reference cannot be honored

If the named ConfigMap or key does not exist, or the content is not usable, the entry is dropped from the resolved configuration and reported, rather than producing an empty file or an empty script. The workstation says so in its status, and the entry comes back on the next configuration pass once the ConfigMap lands.

A file entry that also declares removeWhenUndeclared is not deleted in that situation: an unresolvable reference marks the configuration partial, and a partial configuration never removes anything. See WorkstationConfig.

Who may author one

A ConfigMap is an owner-scoped kind, like WorkstationConfig and Secret: an ordinary namespace member creates and manages their own, and a namespace admin manages any of them. Reads are open to the namespace.

Because a referenced script runs as root on the machine, the content is only inlined when the ConfigMap’s author has authority over the layer pulling it in. A member’s ConfigMap supplies content to that member’s own layers; an admin’s supplies content to anyone’s. A reference the authority check refuses is dropped and reported, exactly like a missing key.

CLI

rl configmap (alias cm) has the usual verbs, plus a generator:

rl configmap create bootstrap \
    --from-file setup.sh=./setup.sh \
    --from-string motd="Welcome to the dev box"

rl configmap get
rl configmap get bootstrap -o yaml
rl configmap edit bootstrap
rl configmap delete bootstrap

See also

• WorkstationConfig: the scripts[] and files[] entries that reference a ConfigMap.
• Access control: who may author one.