Use aliases and default aliases

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:

{
  meta = {
    version = "1.0.0";
    defaultAliases = [ "storage" ];
  };

  build = { ... }: {
    # Package resources.
  };
}

A consumer declares the alias as its build argument:

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

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

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

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:

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

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:

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 eligible instance has the requested name or alias, Kix reports an ambiguous dependency. Wire that consumer directly with deps.<name> = ref.<namespace>.<instance> instead of adding another alias. This records the choice at the consumer, where the dependency is easiest to understand.

The explicit entry does not clear the ambiguity by itself. Kix first runs a dependency-resolution pass while constructing the cluster graph. That pass cannot use ref overrides because the cluster fixpoint is still being built. It therefore reports the ambiguity before reading the consumer’s deps.

To satisfy the first pass, leave exactly one of the providers with the contested name or default alias. Give every other provider a unique alias:

instances.nginx-system = {
  public = {
    package = packages.ingress-nginx;
    aliases = [ "ingressNginxPublic" ];
  };

  # Keeps the package's default `ingressNginx` alias, so phase 1 resolves.
  private = {
    package = packages.ingress-nginx;
  };
};

The aliases prevent the early ambiguity. The consumer’s deps.ingressNginx = ref.nginx-system.public remains the authoritative choice of controller.