# Handle server-side-apply conflicts safely

A server-side apply conflict means Kix is trying to change a field owned by
another field manager. Identify that manager and decide who should own the
field before forcing a deployment.

The example below starts with a Kix-managed Deployment. A separate manager
named `autoscaler` then takes ownership of `spec.replicas` and changes it from
two to three.

## Reproduce the conflict without changing the cluster

Run a reconciled API-server dry run:

<Command {...conflict} />

`--reconcile` makes Kix check every resource even when the activation itself
has not changed. `--dry-run` asks the API server to validate the apply without
persisting it.

Read the conflict message closely. It identifies three things:

* the resource, `Deployment/legacy-web@takeover`;
* the other field manager, `autoscaler`;
* the overlapping field, `.spec.replicas`.

By default, the run stops after this conflict and ends with `1 failed, 4
cancelled`. The cancelled resources have not been checked. To find conflicts
on the remaining resources, run the dry run again with `--on-error continue`:

<Command
  commands={[
  "kix deploy how-to-adoption-takeover --reconcile --dry-run -y --on-error continue",
]}
  cwd="kix-examples/"
/>

This still skips resources that depend on a failed resource, but continues
checking independent branches of the dependency graph.

## Inspect the other manager

Fetch the resource with its managed fields:

<Command
  commands={[
  "kubectl get deployment legacy-web -n takeover -o yaml --show-managed-fields",
]}
/>

Find the named manager under `metadata.managedFields`, then determine what owns
it. Common managers include an operator, an autoscaler, `kubectl`, Helm, and
another deployment system.

Also inspect the current field value and the Kix definition. A conflict is not
evidence that the other value is wrong.

## Choose the field owner

If the other controller should continue managing the field, change the Kix
package or its configuration so it no longer emits that field. When the
package cannot omit it, because the field is required on create or the whole
object comes from upstream, declare the field as ceded on the resource:

```nix
scope.mkResource {
  # ...
  ownership.cede = [ "spec.replicas" ];
}
```

Kix stamps the paths as `kix.run/cede-fields`. When a later apply conflicts
only on those paths, deploy retries without them and the other manager keeps
the field; a conflict anywhere else still fails. See
[Cede fields to a controller](/docs/v0.1/how-to/adopt-existing-resources/cede-fields-to-a-controller/).
Choose one manager either way, rather than letting both repeatedly take
ownership from each other.

If Kix should manage the field, first disable or reconfigure the other manager
for this resource. Otherwise the conflict will return after both systems
reconcile again.

## Preview the ownership transfer

Once Kix is the intended owner, add `--force-conflicts` to the same dry run:

<Command {...forcePreview} />

This confirms that the API server accepts the transfer while still writing
nothing. Review the rest of the plan before continuing.

## Apply the resolution

Run the reconciled deployment with the same flag:

<Command {...resolve} />

The successful apply transfers the overlapping field to the `kix` field
manager and restores the replica count from the Kix definition.

Return to ordinary deployments after resolving the conflict. Keeping
`--force-conflicts` in routine commands can hide a new ownership dispute that
needs a separate decision.

:::note[Use it for a migration]
See [Take ownership of kubectl-managed resources](/docs/v0.1/how-to/adopt-existing-resources/take-ownership-of-kubectl-managed-resources/)
for the full first-deployment checklist, including selector preservation and a
backup of the live object.
:::