How-to guide Platform capabilities

Use Kix-managed secrets

Use scope.mkSecret when a package should create and own a Kubernetes Secret. The returned resource includes helpers for environment variables, envFrom, and volumes, with key names checked during evaluation.

This example uses non-sensitive development values. It assumes you already have a local Kix package with a workload.

Create the Secret

Add the Secret to the package’s returned parts:

15
      credentials = scope.mkSecret {
16
        name = "${scope.instanceName}-credentials";
17
        stringData = {
18
          username = "demo";
19
          password = "development-only";
20
        };
21
      };

View source on GitHub ↗

When keys is omitted, Kix derives the declared key list from stringData. A declared key needs a value in stringData unless source names a SOPS file that holds it; the build refuses one with neither. Set type when the workload needs a Kubernetes Secret type other than Opaque.

Always use scope.mkSecret for a Secret managed by Kix. Its out helpers carry dependency information and validate key names.

Add the values to a workload

Use out.mkEnv to map environment-variable names to Secret keys:

25
      deployment = scope.mkDeployment {
26
        name = scope.instanceName;
27
        spec = {
28
          replicas = 1;
29
          selector.matchLabels = scope.selectorLabels;
30
          template.spec.containers = [
31
            {
32
              name = "app";
33
              image = "busybox:1.36";
34
              command = [ "sh" "-c" "sleep 3600" ];
35
              env = self.credentials.out.mkEnv {
36
                APP_USERNAME = "username";
37
                APP_PASSWORD = "password";
38
              };
39
            }
40
          ];
41
        };
42
      };

View source on GitHub ↗

The generated Deployment refers to managed-example-credentials through secretKeyRef. It also depends on the Secret, so Kix applies the Secret before the workload.

For other consumption patterns, use:

secret.out.keyRef "key" for one valueFrom entry.
secret.out.envFrom to expose every key through envFrom.
secret.out.volume "credentials" to create a Secret volume source.

Check the package

Evaluate the example cluster:

kix-examples/

❱ kix check how-to-platform-secrets
 TOOL       RESULT  DETAILS                       
 eval       pass    13 manifests evaluated        
 scorecard  pass    0 errors, 17 warnings, 2 info

If the workload requests a key not declared by the Secret, evaluation fails and lists the available keys. Fix the key name in the workload or add it to the Secret before deploying.