Skip to content
kix /docs
Install the CLI

How-to guide Platform capabilities

Use Kix-managed secrets

Create a Secret as part of a package and consume its declared keys without spelling references directly.

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

Section titled “Create the Secret”

Add the Secret to the package’s returned parts:

how-to/platform/managed-secret-app.nix
      credentials = scope.mkSecret {
        name = "${scope.instanceName}-credentials";
        stringData = {
          username = "demo";
          password = "development-only";
        };
      };

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

Section titled “Add the values to a workload”

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

how-to/platform/managed-secret-app.nix
      deployment = scope.mkDeployment {
        name = scope.instanceName;
        spec = {
          replicas = 1;
          selector.matchLabels = scope.selectorLabels;
          template.spec.containers = [
            {
              name = "app";
              image = "busybox:1.36";
              command = [ "sh" "-c" "sleep 3600" ];
              env = self.credentials.out.mkEnv {
                APP_USERNAME = "username";
                APP_PASSWORD = "password";
              };
            }
          ];
        };
      };

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

Section titled “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.