Skip to content
kix /docs
Install the CLI

How-to guide Author packages and clusters

Stamp multi-environment clusters with mkEnv

Create environment-prefixed package instances from one shared definition.

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

Section titled “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}";
          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

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

  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 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

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