Use externally managed secrets

Use scope.mkSecretRef when another system creates the Kubernetes Secret. Kix does not render or update the Secret data, but it validates the keys your package expects and waits for them before applying dependent resources.

This guide assumes the external system creates the Secret in the workload’s namespace.

Declare the Secret reference

Add a reference to the package’s returned parts and list every key the package will consume:

      credentials = scope.mkSecretRef {
        name = "billing-api-credentials";
        keys = [ "api-key" ];
      };

View source on GitHub ↗

The example expects Secret/billing-api-credentials in the package namespace. scope.mkSecretRef emits an import marker rather than a Secret manifest.

Keep the reference in the build function’s returned attrset, as shown by the credentials part above. A reference used only in a let binding is not collected into the cluster artifact.

Consume declared keys

Use the same out helpers available on a Kix-managed Secret:

      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 {
                BILLING_API_KEY = "api-key";
              };
            }
          ];
        };
      };

View source on GitHub ↗

out.mkEnv validates api-key during evaluation and adds the dependency edge from the Deployment to the import marker.

Check the wiring

Evaluate the cluster before connecting to Kubernetes:

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

Inspect the graph when you need to confirm the deploy ordering:

Run in kix-examples/

❱ kix graph how-to-platform-secrets --format tree Show output

CustomResourceDefinition/activations.kix.run
└── Activation/how-to-platform-secrets-mfddk0f9lxki
CustomResourceDefinition/packageinstances.kix.run
├── PackageInstance/secret-ref-external-example-billing-api-credentials@secret-examples (import)
│   └── Deployment/external-example@secret-examples
│       └── PackageInstance/external-example@secret-examples
│           └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── PackageInstance/managed-example@secret-examples
│   └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── PackageInstance/external-example@secret-examples
│   └── Activation/how-to-platform-secrets-mfddk0f9lxki
└── PackageInstance/platform-dns@kube-system (import)
    └── Activation/how-to-platform-secrets-mfddk0f9lxki
Namespace/kube-system
└── PackageInstance/platform-dns@kube-system (import)
    └── Activation/how-to-platform-secrets-mfddk0f9lxki
Namespace/secret-examples
├── Secret/managed-example-credentials@secret-examples
│   └── Deployment/managed-example@secret-examples
│       └── PackageInstance/managed-example@secret-examples
│           └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── PackageInstance/secret-ref-external-example-billing-api-credentials@secret-examples (import)
│   └── Deployment/external-example@secret-examples
│       └── PackageInstance/external-example@secret-examples
│           └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── PackageInstance/managed-example@secret-examples
│   └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── PackageInstance/external-example@secret-examples
│   └── Activation/how-to-platform-secrets-mfddk0f9lxki
├── Deployment/managed-example@secret-examples
│   └── PackageInstance/managed-example@secret-examples
│       └── Activation/how-to-platform-secrets-mfddk0f9lxki
└── Deployment/external-example@secret-examples
    └── PackageInstance/external-example@secret-examples
        └── Activation/how-to-platform-secrets-mfddk0f9lxki
12 resources, 19 dependencies

The secret-ref-external-example-billing-api-credentials import appears before Deployment/external-example.

Verify the external Secret

Confirm that the provider has created the Secret in the expected namespace:

❱ kubectl get secret billing-api-credentials -n secret-examples

During kix deploy, Kix checks that the Secret exists and contains the declared keys before applying the dependent Deployment. A missing Secret or key fails that deploy wave rather than starting the workload with an invalid reference.