Skip to content
kix /docs
Install the CLI

How-to guide Debug dependency wiring

Wire cross-namespace dependencies explicitly

Use an explicit deps entry when a package consumes an instance in another namespace. The wiring remains visible beside the consuming instance, and the package still receives the dependency through its build argument.

Kix fills a package argument from the consumer’s own namespace. It uses an instance in another namespace only when the cluster definition names it this way, or when the provider’s package serves the whole cluster (an operator, an ingress controller, or a certificate issuer, for example). When the only match for a required argument is in another namespace, the error prints the deps line to add.

This guide assumes the package already declares the dependency by naming it in a build function, such as { backend, ... }: ....

Accept ref in the cluster module

Section titled “Accept ref in the cluster module”

Define the module that contains the instances as a function with a ref argument:

cluster.nix
modules = [
  (
    { ref, ... }:
    {
      # Namespace and instance configuration goes here.
    }
  )
];

ref mirrors the instances.<namespace>.<name> tree. Each leaf identifies one package instance.

Wire the dependency

Section titled “Wire the dependency”

Set deps.<argument-name> on the consuming instance. This tested example wires an application gateway to a backend in the platform namespace:

tutorials/08-namespace-deps/cluster.nix
          gateway = {
            package = reverseProxyPackage;
            # Explicit cross-namespace wiring keeps the boundary
            # crossing visible at the call site.
            deps.backend = ref.platform.backend;
          };

View source on GitHub ↗

The left side, deps.backend, matches the package’s backend build argument. The right side, ref.platform.backend, selects the exact provider instance.

Add the provider instance under the referenced namespace as usual:

cluster.nix
instances.platform.backend = {
  package = packages.echo-server;
  config.message = "Hello from the platform backend";
};

Check the wiring

Section titled “Check the wiring”

Evaluate the cluster:

kix-examples/ 
❱ kix check 08-namespace-deps
 TOOL       RESULT  DETAILS                      
 eval       pass    16 manifests evaluated       
 scorecard  pass    0 errors, 9 warnings, 1 info

A missing reference fails module evaluation. If the package declares another required build argument without a matching deps entry or resolvable provider, dependency resolution names the missing argument.