# Patch package output with overlays

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:

<Snippet {...patchPackageOutput} />

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:

<Command {...check} />

Render the patched resource:

<Command {...patchedConfig} />

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.

:::caution
`partsOverlays` depends on the package's returned part names and shapes. Review
the overlay whenever the package changes.
:::