Use auto-instantiation with `availablePackages`, `optional`, and `autoNamespace`

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

Use auto-instantiation when a cluster has a standard package for a dependency, but should include it only when something needs it. Use an optional instance when you also need to configure that dormant provider.

This guide assumes you already have packages whose required build arguments describe their dependencies.

Declare the dependencies

In the consuming package, make each dependency a required build argument. This application reads values from database and metrics:

  build =
    {
      self,
      database,
      metrics,
      ...
    }:
    {
      configMap = scope.mkResource {
        apiVersion = "v1";
        kind = "ConfigMap";
        name = scope.instanceName;
        data = {
          databaseResource = database.out.name;
          metricsResource = metrics.out.name;
        };
      };

      root = self.configMap;
    };

View source on GitHub ↗

Required arguments create demand. Kix first looks for a matching instance or alias, then consults the cluster’s package catalog.

Add a default package to the catalog

Add the package under the dependency name in availablePackages. Set autoNamespace if auto-instantiated packages should live in a shared namespace:

      # Catalog entries stay absent until a required package argument asks
      # for one. autoNamespace chooses where Kix creates the instance.
      availablePackages.database = {
        package = databasePackage;
      };
      autoNamespace = "platform";

View source on GitHub ↗

When an instance requires database, Kix creates a database instance in platform with the package’s default configuration. Without autoNamespace, Kix creates it in the requesting instance’s namespace. A namespace set on the individual catalog entry takes precedence over autoNamespace.

Keep a configured provider dormant

An availablePackages entry is instantiated with default configuration. When the provider needs cluster-specific configuration, declare a normal instance and set optional = true:

      # This configured instance is dormant until another package requires
      # an argument named `metrics`.
      instances.platform.metrics = {
        package = metricsPackage;
        optional = true;
        config.retentionDays = 14;
      };

View source on GitHub ↗

Kix excludes this instance when nothing depends on metrics. A required metrics argument activates it with the configuration shown above.

Add the consumer

Declare only the package you intend to run directly:

      # applicationPackage requires both `database` and `metrics`. That
      # demand creates the catalog package and activates the optional one.
      instances.apps.api = {
        package = applicationPackage;
      };

View source on GitHub ↗

The package’s required arguments pull both providers into the evaluated cluster. This also works transitively when an activated provider has required dependencies of its own.

Check the result

Evaluate the cluster:

Run in kix-examples/

❱ kix check how-to-auto-instantiation
 TOOL         RESULT  DETAILS                                                       
 eval         pass    13 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, 3 warnings, 0 info

Inspect the dependency graph to confirm where the providers were created:

Run in kix-examples/

❱ kix graph how-to-auto-instantiation --format tree Show output

CustomResourceDefinition/activations.kix.run
└── Activation/how-to-auto-instantiation-hphs01y95xk7
CustomResourceDefinition/packageinstances.kix.run
├── PackageInstance/metrics@platform
│   └── Activation/how-to-auto-instantiation-hphs01y95xk7
├── PackageInstance/database@platform
│   └── Activation/how-to-auto-instantiation-hphs01y95xk7
├── PackageInstance/platform-dns@kube-system (import)
│   └── Activation/how-to-auto-instantiation-hphs01y95xk7
└── PackageInstance/api@apps
    └── Activation/how-to-auto-instantiation-hphs01y95xk7
Namespace/apps
├── ConfigMap/api@apps
│   └── PackageInstance/api@apps
│       └── Activation/how-to-auto-instantiation-hphs01y95xk7
└── PackageInstance/api@apps
    └── Activation/how-to-auto-instantiation-hphs01y95xk7
Namespace/kube-system
└── PackageInstance/platform-dns@kube-system (import)
    └── Activation/how-to-auto-instantiation-hphs01y95xk7
Namespace/platform
├── ConfigMap/metrics@platform
│   ├── ConfigMap/api@apps
│   │   └── PackageInstance/api@apps
│   │       └── Activation/how-to-auto-instantiation-hphs01y95xk7
│   └── PackageInstance/metrics@platform
│       └── Activation/how-to-auto-instantiation-hphs01y95xk7
├── ConfigMap/database@platform
│   ├── ConfigMap/api@apps
│   │   └── PackageInstance/api@apps
│   │       └── Activation/how-to-auto-instantiation-hphs01y95xk7
│   └── PackageInstance/database@platform
│       └── Activation/how-to-auto-instantiation-hphs01y95xk7
├── PackageInstance/metrics@platform
│   └── Activation/how-to-auto-instantiation-hphs01y95xk7
└── PackageInstance/database@platform
    └── Activation/how-to-auto-instantiation-hphs01y95xk7
13 resources, 21 dependencies

The graph contains database@platform, metrics@platform, and api@apps. Both provider ConfigMaps appear before the application ConfigMap that consumes their outputs.