Skip to content
kix docs

Add explicit ordering with `extraDeps`

Use an instance-level extraDeps edge when an imported instance’s marker must follow a managed prerequisite, but no manifest field carries a reference between them.

The example below imports an existing legacy-api Service. Its PackageInstance marker should be recorded only after Kix deploys a managed compatibility contract.

Add the explicit edge

Section titled “Add the explicit edge”

Make the cluster module accept ref, then point the imported instance at the managed prerequisite:

how-to/adoption/cluster.nix (L25–L42)
          legacy.legacy-api = {
            package = kix.mkImport {
              kind = "Service";
              apiVersion = "v1";
              out = {
                name = "legacy-api";
                fqdn = "legacy-api.legacy.svc.cluster.local";
                port = 8080;
              };
            };
            aliases = [ "legacyApi" ];


            extraDeps = [ ref.apps.legacy-api-contract.root ];
          };


          apps.legacy-api-contract.package = contractPackage;

View source on GitHub ↗

The reference has the form ref.<namespace>.<instance>.root. It identifies the managed instance’s PackageInstance marker, which is itself ordered after the instance’s resources.

extraDeps adds an ordering edge to the imported instance’s marker. It does not modify, deploy, or check the imported Kubernetes resource.

Check the cluster

Section titled “Check the cluster”

Evaluate the complete cluster:

Run in kix-examples/ 
❱ kix check how-to-adoption
 TOOL         RESULT  DETAILS                                                       
 eval         pass    20 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, 14 warnings, 4 info

A missing namespace or instance in the ref path fails evaluation. Fix that reference before inspecting the graph.

Verify the order

Section titled “Verify the order”

Print the dependency tree:

Run in kix-examples/ Output excerpt
❱ kix graph how-to-adoption --format tree Show output 
├── PackageInstance/legacy-api@legacy (import)
├── PackageInstance/legacy-api-contract@apps
│   ├── PackageInstance/legacy-api@legacy (import)
├── ConfigMap/legacy-api-contract@apps
│   └── PackageInstance/legacy-api-contract@apps
│       ├── PackageInstance/legacy-api@legacy (import)
├── PackageInstance/legacy-api-contract@apps
│   ├── PackageInstance/legacy-api@legacy (import)
└── PackageInstance/legacy-api@legacy (import)
20 resources, 36 dependencies

The relevant chain is:

  1. ConfigMap/legacy-api-contract@apps is deployed.
  2. PackageInstance/legacy-api-contract@apps records the managed instance.
  3. PackageInstance/legacy-api@legacy records the import.

Use extraDeps only when the ordering relationship has no corresponding manifest value. Reading a dependency’s tracked out value already creates an edge, so adding another one is unnecessary.

At the cluster instance level, extraDeps only affects kix.mkImport markers. Although the option is available on every instance, managed instances ignore it. Package authors should instead set requires or extraDeps on the individual resource that needs the ordering constraint.

This edge does not automatically order packages that consume manually declared import outputs. If a consumer must wait for the same prerequisite, declare that dependency in the consumer as well.