# 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`:

```nix title="packages/persistent-volume/default.nix"
{
  meta = {
    version = "1.0.0";
    defaultAliases = [ "storage" ];
  };

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

A consumer declares the alias as its build argument:

```nix title="packages/web/default.nix"
build = { storage, ... }: {
  dataMount = kix.mount.pvc storage { mountPath = "/data"; };
  # Other package resources.
};
```

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

```nix title="cluster.nix"
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:

```nix title="cluster.nix"
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:

```nix title="cluster.nix"
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:

<Command commands={["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:

```nix title="cluster.nix"
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.

:::note[Explanation]
See [Dependency resolution and why explicit deps matter](/docs/v0.1/explanation/dependency-resolution-and-why-explicit-deps-matter/)
for resolution order and ambiguity handling.
:::

:::note[Reference]
See [`aliases`](/docs/v0.1/reference/instance-schema/aliases/) and
[`meta.defaultAliases`](/docs/v0.1/reference/meta/defaultaliases/) for the exact
schemas.
:::