Reuse one package for multiple instances

An instance is one configured use of a package. Reuse the same package value when you need several copies of a workload with different names, namespaces, or settings.

Define the instances

Assign the same package to more than one entry under instances:

      instances.how-to-app = {
        preview = {
          package = webPackage;
          config = {
            message = "Hello from preview";
            environment = "preview";
          };
        };

        production = {
          package = webPackage;
          config = {
            message = "Hello from production";
            environment = "production";
            replicas = 2;
            healthCheck = {
              enable = true;
              retryFor = 60;
            };
          };
        };
      };

View source on GitHub ↗

Kix evaluates the package separately for preview and production. Each evaluation receives its own:

scope.instanceName and namespace.
Evaluated config values.
self fixpoint containing that instance’s resources.
Dependency bindings.

The package can therefore name resources from scope.instanceName without the two instances colliding.

Override only what differs

Defaults belong in the package options. Instance configuration should contain the values that differ for that deployment.

In the example, preview uses the default replica count and leaves the health check disabled. production uses two replicas and enables its post-deploy probe. Both instances still share the package’s image, resources, mounts, and resource construction.

You can place instances in different namespaces as well:

instances.preview.web = {
  package = webPackage;
  config.environment = "preview";
};

instances.production.web = {
  package = webPackage;
  config.environment = "production";
};

Declare both namespaces under namespaces and wire any cross-namespace dependencies explicitly.

Inspect the instances

List the packages in the example cluster:

Run in kix-examples/

❱ kix list packages --cluster how-to-application
 NAME              VERSION  STATUS                 
 platform-dns      -        import [kube-system]   
 platform-storage  -        import [kube-system]   
 preview           1.0.0    installed [how-to-app] 
 production        1.0.0    installed [how-to-app]

Use inspect to see the resources each instance rendered. It prints the total number of resources, the namespaces, counts by kind, and a resource inventory grouped by namespace.

Run in kix-examples/

❱ kix inspect how-to-application Show output

Cluster: how-to-application
Total resources: 16

Namespaces (3):
  (cluster-scoped) (5 resources)
  how-to-app (10 resources)
  kube-system (1 resources)

Resource kinds:
 Kind                      Count 
 ConfigMap                 3     
 PackageInstance           3     
 CustomResourceDefinition  2     
 Deployment                2     
 Namespace                 2     
 Service                   2     
 Activation                1     
 Job                       1     

Resources:
  (cluster-scoped):
    Activation/how-to-application-gb5d6ry45b5l
    CustomResourceDefinition/activations.kix.run
    CustomResourceDefinition/packageinstances.kix.run
    Namespace/how-to-app
    Namespace/kube-system
  how-to-app:
    ConfigMap/preview
    ConfigMap/production
    ConfigMap/production-health-script
    Deployment/preview
    Deployment/production
    Job/production-health
    PackageInstance/preview
    PackageInstance/production
    Service/preview
    Service/production
  kube-system:
    PackageInstance/platform-dns

Each instance appears under its own name with its own resources. To inspect the dependencies between them, use kix graph; inspect does not report dependency edges.

Changes to one instance’s configuration affect that instance’s rendered resources. They do not create a second copy of the package source.