Stamp multi-environment clusters with mkEnv

Use kix.mkEnv when several environments have the same package layout and differ only in configuration. The generated environments belong to one Kix cluster artifact and deploy together.

Define an environment-aware instance set

Write each instance set as a function that accepts env. Read shared values from env.config and use env.name where the environment name belongs in package configuration:

how-to/composition/multi-env-cluster.nix

  application =
    { env, ... }:
    {
      web = {
        package = packages.echo-server;
        config = {
          message = "Hello from ${env.name}";
          replicas = env.config.replicas;
        };
      };
    };

View source on GitHub ↗

This set is named app when passed to mkEnv. Combining the environment name and set name produces namespaces such as development-app.

Stamp each environment

Call kix.mkEnv once per environment and combine the returned instance trees:

how-to/composition/multi-env-cluster.nix

      instances =
        kix.mkEnv "development" {
          config.replicas = 1;
        } { app = application; }
        // kix.mkEnv "production" {
          config.replicas = 3;
          overrides.app.web.config.message = "Production storefront";
        } { app = application; };

View source on GitHub ↗

The three arguments are:

1. The environment name used as the namespace prefix.
2. Environment configuration, with optional per-instance overrides.
3. Named instance-set functions.

The production call passes replicas = 3 to every instance set through env.config, then overrides the web instance’s message.

Overrides are keyed by <set>.<instance> and recognize only config and parts; other keys such as package or aliases are ignored. parts replaces the instance set’s parts, while config uses a shallow update where each top-level option key replaces the value produced by the instance set. For example, overrides.app.web.config.resources = { limits = ...; } also removes any existing requests. Restate the complete value of each option key you override.

Assign the combined result directly to instances inside the cluster module. Kix creates development-app.web and production-app.web as separate package instances.

Check the generated environments

Evaluate the cluster:

kix-examples/

❱ kix check how-to-multi-env
 TOOL       RESULT  DETAILS                      
 eval       pass    16 manifests evaluated       
 scorecard  pass    0 errors, 2 warnings, 0 info

Build the manifests to confirm that environment configuration reached each Deployment:

kix-examples/ output excerpt offline capture

❱ kix build how-to-multi-env --output json

Show outputHide output · 12 lines

[
  {
    "kind": "Deployment",
    "namespace": "development-app",
    "replicas": 1
  },
  {
    "kind": "Deployment",
    "namespace": "production-app",
    "replicas": 3
  }
]

The output excerpt shows one replica in development-app and three in production-app. Package dependencies that are resolved into the requesting namespace are stamped separately for each environment. Cluster-wide role providers remain shared.

Use separate cluster definitions when environments need independent deploys or materially different package layouts.