Configure a workload

This page shows how to pass configuration to a workload’s containers: environment variables, ConfigMaps and Secrets as variables or files, and credentials for a private container registry.

Compute is in preview, and the v1alpha API can change.

Before you begin

Select a project, install the compute plugin, and get access to Compute. For more information, see Set up your project.
Make sure that you can read the ConfigMaps and Secrets that your workload references. When you apply a workload, Datum checks that you have get permission on each one, and rejects the request if you don’t.

The datumctl compute deploy flags don’t set configuration. Write a workload manifest instead, and apply it with datumctl compute deploy -f FILE or datumctl apply -f FILE, where FILE is the path to your manifest. A flag-based deploy saves its result to workload.yaml, which you can edit as a starting point. Each flag-based deploy overwrites workload.yaml in the current directory, so keep edited manifests under another name.

A flag-based datumctl compute deploy replaces the workload’s whole template and placements with what the flags describe. It removes environment variables, volumes, registry credentials, custom commands, and extra placements that you set in a manifest, and it sets the Instance count to the --min value, which defaults to 1. After you add configuration in a manifest, update the workload with datumctl compute deploy -f FILE.

Set environment variables

To set an environment variable to a fixed value, add it to the container’s env list, as in the following example:

containers:
  - name: api
    image: ghcr.io/example/api:1.4.2
    env:
      - name: LOG_LEVEL
        value: info

Create a ConfigMap or Secret

ConfigMaps hold non-sensitive settings, and Secrets hold sensitive values such as passwords and tokens. Both live in your project, and a workload can reference any ConfigMap or Secret in the same project. To create a ConfigMap and a Secret, follow these steps:

Save the following manifest as api-config.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
data:
  config.yaml: |
    listen: "[::]:8080"
    cache_ttl: 60s
  REGION_LABEL: north-america
---
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
type: Opaque
stringData:
  db-password: PASSWORD

Replace PASSWORD with your database password.

To create the objects, run the following command:
datumctl apply -f api-config.yaml

For more information about Secrets in the portal, see Secrets.

Set a variable from a ConfigMap or Secret key

To set one environment variable from one key, use valueFrom with configMapKeyRef or secretKeyRef. This method works with both runtime classes. The following example sets one variable from a Secret key and one from a ConfigMap key:

env:
  - name: DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: api-secrets
        key: db-password
  - name: REGION_LABEL
    valueFrom:
      configMapKeyRef:
        name: api-config
        key: REGION_LABEL

Set variables from a whole ConfigMap or Secret

On general-purpose workloads, you can turn every key of a ConfigMap or Secret into an environment variable with envFrom. Each entry names exactly one source. The optional prefix is added to each variable name, and must be a valid variable name itself. The following example loads every key from api-config with the prefix APP_, and every key from api-secrets without a prefix:

envFrom:
  - configMapRef:
      name: api-config
    prefix: APP_
  - secretRef:
      name: api-secrets

The unikernel runtime class doesn’t support envFrom. On unikernel workloads, set each variable with valueFrom instead.

Mount a ConfigMap or Secret as files

To mount a ConfigMap or Secret as files, declare a volume in spec.template.spec.volumes, and attach it to a container with volumeAttachments. Each key becomes a file in the mount directory. The following example mounts api-config at /etc/api and api-secrets at /etc/api-secrets:

spec:
  template:
    spec:
      runtime:
        sandbox:
          containers:
            - name: api
              image: ghcr.io/example/api:1.4.2
              volumeAttachments:
                - name: config
                  mountPath: /etc/api
                - name: secrets
                  mountPath: /etc/api-secrets
      volumes:
        - name: config
          configMap:
            name: api-config
        - name: secrets
          secret:
            secretName: api-secrets

Keep the following rules in mind:

A ConfigMap volume uses configMap.name, but a Secret volume uses secret.secretName.
Attach every volume that you declare to at least one container, and give each attachment a mountPath.
To mount only some keys, or to choose file names, add items with a key and a relative path for each file. A path can’t contain ...
To set file permissions, set defaultMode.

ConfigMap and Secret volumes work with both runtime classes.

Apply a configuration change

Running Instances don’t restart when a ConfigMap or Secret changes. To make your app pick up the new values, restart the workload:

datumctl compute restart WORKLOAD_NAME

Replace WORKLOAD_NAME with the name of your workload. The restart replaces Instances one at a time in each location. For more information, see Placement and scaling.

Use images from a private registry

To pull an image from a private registry, store the registry credentials in a Secret and reference it in imagePullSecrets. This method works with both runtime classes. To use a private registry, follow these steps:

Save the following manifest as registry-credentials.yaml:
apiVersion: v1 kind: Secret metadata: name: registry-credentials type: kubernetes.io/dockerconfigjson stringData: .dockerconfigjson: | {"auths":{"REGISTRY_HOST":{"username":"REGISTRY_USERNAME","password":"REGISTRY_TOKEN"}}}
Replace the following:
- REGISTRY_HOST: the registry host name, such as ghcr.io. For Docker Hub, use https://index.docker.io/v1/.
- REGISTRY_USERNAME: the user name for the registry.
- REGISTRY_TOKEN: a password or access token with permission to pull the image. Use a read-only token.

To create the Secret, run the following command:

datumctl apply -f registry-credentials.yaml

In your workload manifest, add the Secret to spec.template.spec.runtime.sandbox.imagePullSecrets:

runtime:
  sandbox:
    imagePullSecrets:
      - name: registry-credentials
    containers:
      - name: api
        image: ghcr.io/example/api:1.4.2

To apply the manifest, run the following command:
datumctl compute deploy -f workload.yaml
Replace workload.yaml with your manifest file if it has a different name.

A manifest deploy doesn’t create or remove a public URL. To publish a workload that you manage with manifests, see Publish a workload you manage with manifests.

Complete example

The following manifest combines the settings on this page for a general-purpose workload:

apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
  name: api
spec:
  template:
    spec:
      runtime:
        class: general-purpose
        resources:
          instanceType: datumcloud/d1-standard-2
        sandbox:
          imagePullSecrets:
            - name: registry-credentials
          containers:
            - name: api
              image: ghcr.io/example/api:1.4.2
              args: ["--config", "/etc/api/config.yaml"]
              env:
                - name: LOG_LEVEL
                  value: info
                - name: DATABASE_PASSWORD
                  valueFrom:
                    secretKeyRef:
                      name: api-secrets
                      key: db-password
              envFrom:
                - configMapRef:
                    name: api-config
                  prefix: APP_
              ports:
                - name: http
                  port: 8080
              volumeAttachments:
                - name: config
                  mountPath: /etc/api
      volumes:
        - name: config
          configMap:
            name: api-config
      networkInterfaces:
        - network:
            name: default
  placements:
    - name: us-east
      locations:
        - name: us-east-1
      scaleSettings:
        minReplicas: 1

To use this example on the unikernel class, change runtime.class to unikernel and remove the envFrom entry.

Limits

ConfigMaps and Secrets that a workload references have the following size limits:

256 KiB for each ConfigMap or Secret.
1 MiB in total for all the ConfigMaps and Secrets that a workload references in one location.

If a workload exceeds a limit, Datum accepts the request, but the workload reports ReferencedDataNotReady and its Instances report SourceTooLarge. For other configuration errors, see Manage and troubleshoot workloads.

What’s next

To serve the workload on a public URL, see Publish a workload.
To check status and fix problems, see Manage and troubleshoot workloads.

Documentation

TLDR

Platform

Galactic VPC

ALB

Connectors

Compute

Domains & DNS

Agents

Before you begin

Set environment variables

Create a ConfigMap or Secret

Set a variable from a ConfigMap or Secret key

Set variables from a whole ConfigMap or Secret

Mount a ConfigMap or Secret as files

Apply a configuration change

Use images from a private registry

Complete example

Limits

What’s next

​Before you begin

​Set environment variables

​Create a ConfigMap or Secret

​Set a variable from a ConfigMap or Secret key

​Set variables from a whole ConfigMap or Secret

​Mount a ConfigMap or Secret as files

​Apply a configuration change

​Use images from a private registry

​Complete example

​Limits

​What’s next

Before you begin

Set environment variables

Create a ConfigMap or Secret

Set a variable from a ConfigMap or Secret key

Set variables from a whole ConfigMap or Secret

Mount a ConfigMap or Secret as files

Apply a configuration change

Use images from a private registry

Complete example

Limits

What’s next