How-to guide Debug dependency wiring

Use aliases and default aliases

Make a package instance resolvable under a stable dependency name.

Use an alias when a package should satisfy a dependency name that differs from its instance name. Put a reusable default on the package, or set an alias on one instance when the mapping belongs to a particular cluster.

Declare a package default alias

Add meta.defaultAliases when every instance of a package provides the same kind of dependency. A persistent-volume package can advertise itself as storage even when cluster authors choose names such as data or uploads:

1
{
2
  meta = {
3
    version = "1.0.0";
4
    defaultAliases = [ "storage" ];
5
  };
6

7
  build = { ... }: {
8
    # Package resources.
9
  };
10
}

A consumer declares the alias as its build argument:

1
build = { storage, ... }: {
2
  dataMount = kix.mount.pvc storage { mountPath = "/data"; };
3
  # Other package resources.
4
};

The cluster can now give the provider a task-specific instance name:

1
instances.apps.data = {
2
  package = packages.persistent-volume;
3
};

Kix indexes the instance under both data and storage.

Set aliases on one instance

Use the instance’s aliases field when the name applies only in this cluster:

1
instances.apps.redis-primary = {
2
  package = packages.valkey;
3
  aliases = [ "cache" ];
4
};

A package with a required cache build argument can now resolve this instance.

A non-empty instance alias list replaces meta.defaultAliases for that instance. Include any package defaults you still need:

1
aliases = [ "cache" "valkey" ];

Package roles remain available as aliases even when instance aliases replace the defaults.

Check for collisions

Evaluate the cluster after adding an alias:

❱ kix check production

If more than one instance in the consumer’s namespace has the requested name or alias, Kix reports that the dependency matches multiple instances. Wire that consumer to the provider it should use:

1
instances.apps.web = {
2
  package = packages.web;
3
  deps.cache = ref.apps.redis-primary;
4
};

This records the choice at the consumer, where the dependency is easiest to understand.

Aliases can also make two availablePackages entries answer one name. See Choose between catalog packages that answer one name.