Stamp multi-environment clusters with `mkEnv`

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

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:

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

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:

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

View source on GitHub ↗

The three arguments are:

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

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

Overrides use a shallow update: each top-level key replaces the value produced by the instance set. For example, overrides.web.config.resources = { limits = ...; } also removes any existing requests. Restate the complete value of each 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:

Run in kix-examples/

❱ kix check how-to-multi-env
 TOOL         RESULT  DETAILS                                                       
 eval         pass    15 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, 4 warnings, 2 info

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

Run in kix-examples/ Output excerpt

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

[
  {
    "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.