Skip to content
kix /docs
Install the CLI

How-to guide Adopt existing resources

Add explicit ordering with extraDeps

Order an imported instance after a managed prerequisite when no value connects them.

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
          legacy.legacy-api = {
            package = kix.mkImport {
              kind = "Service";
              apiVersion = "v1";
              out = {
                name = "legacy-api";
                fqdn = "legacy-api.legacy.svc.${config.clusterDomain}";
                port = 8080;
              };
            };
            aliases = [ "legacyApi" ];


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


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

View source on GitHub ↗

The reference has the form ref.<namespace>.<instance>. In extraDeps it stands for that instance’s PackageInstance marker, which is itself ordered after the instance’s resources. The reference does not activate an optional instance; something else must, such as a required dependency.

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:

kix-examples/ 
❱ kix check how-to-adoption
 TOOL       RESULT  DETAILS                       
 eval       pass    21 manifests evaluated        
 scorecard  pass    0 errors, 14 warnings, 2 info

Evaluation fails for a missing namespace or instance in the ref path, for an entry that is neither a resource nor a ref, and for a ref to the import itself, even when the import is optional and inactive. It also fails for a ref to an optional instance that is not active. Fix the entry before inspecting the graph.

Verify the order

Section titled “Verify the order”

Print the dependency tree:

kix-examples/ output excerpt offline capture 
❱ kix graph how-to-adoption --format tree
Show outputHide output · 10 lines 
├── 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)
21 resources, 39 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 applies only to kix.mkImport instances. A managed instance with extraDeps fails evaluation. Package authors set requires or extraDeps on the individual resource that needs the ordering constraint instead.

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.