Skip to content
kix docs

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

Section titled “Create the Secret”

Add the Secret to the package’s returned parts:

how-to/platform/managed-secret-app.nix (L15–L21)
      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. 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 (L25–L42)
      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:

Run in kix-examples/ 
❱ kix check how-to-platform-secrets
 TOOL         RESULT  DETAILS                                                       
 eval         pass    12 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 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.