How-to guide Adopt existing resources

Patch package output with overlays

Change one instance's built resources with a parts overlay when the package has no suitable option.

Use partsOverlays for a local change that the package does not expose through its typed config options. The overlay runs after the package builds and can replace returned parts for one instance.

Add a parts overlay

This overlay rebuilds one ConfigMap with an adoption annotation while preserving its generated data:

49
            partsOverlays = [
50
              (
51
                scope: _self: base:
52
                let
53
                  patchedConfig = scope.mkResource {
54
                    inherit (base.clientConfig) apiVersion kind name;
55
                    inherit (base.clientConfig.rawManifest) data;
56
                    annotations."example.com/adopted-from" = "legacy-config";
57
                  };
58
                in
59
                {
60
                  clientConfig = patchedConfig;
61
                  root = patchedConfig;
62
                }
63
              )
64
            ];

View source on GitHub ↗

An overlay receives three arguments:

scope contains the resource builders for this instance.
self is the final recursive package result. Name it _self when the overlay does not need it.
base is the package result before this overlay runs.

The example reads the original resource fields from base.clientConfig, creates patchedConfig, then replaces both the named part and root. Updating root is necessary because the original package uses that ConfigMap as its root resource.

Keep the patch as narrow as possible and explicitly preserve every field you need. rawManifest contains only the rendered Kubernetes manifest. Rebuilding a part drops any labels or annotations that the overlay does not copy. It also drops requires and extraDeps, because those ordering edges are not part of the manifest.

Avoid overlaying a workload. Rebuilding a Deployment with the generic scope.mkResource skips the selector and Pod-template labels added by scope.mkDeployment. It also skips the network policies attached by the workload builders. Prefer overlaying a leaf resource, such as the ConfigMap in this example. For broader changes, add a typed option to the package.

Check the result

Evaluate the cluster after adding the overlay:

kix-examples/

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

Render the patched resource:

kix-examples/ output excerpt

❱ kix build how-to-adoption --output json
{
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "legacy-api-client",
    "namespace": "apps",
    "annotations": {
      "example.com/adopted-from": "legacy-config"
    }
  },
  "data": {
    "endpoint": "http://legacy-api.legacy.svc.cluster.local:8080"
  }
}

The output retains the endpoint from the package and adds the example.com/adopted-from annotation.

If several instances need the same change, add a typed option to the package instead. If every package in the cluster needs a policy-driven transform, consider globalPartsOverlays rather than repeating an instance overlay.