> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crossplane Guide

> Validate one Crossplane managed resource through Cloud Adapter before composing a platform API.

Crossplane providers continuously reconcile desired state by calling cloud APIs. Compatibility depends on the provider family, provider version, managed resource, endpoint configuration, and every operation used by reconciliation and deletion.

Do not begin with a Composition. First prove one managed resource in an isolated control plane.

## Choose and pin the provider

Record:

* the provider package and version;
* the managed resource kind and API version;
* the controller image digest;
* how that provider version configures a custom endpoint;
* which origin identity the controller uses;
* the deletion policy and target resource owner.

Endpoint fields differ between provider families and versions. Use the provider's published schema for the installed version rather than copying a `ProviderConfig` from another family.

## Start with one bounded resource

Choose a resource with a small lifecycle, such as one object or bucket only when its full create, observe, update, and delete operations are documented for the selected target. Give it a unique external name and no production dependencies.

Apply the provider configuration and one managed resource, then observe:

```bash theme={null}
kubectl get managed
kubectl describe <kind> <name>
kubectl get events --sort-by=.lastTimestamp
```

Record the `Ready` and `Synced` conditions, reason, message, observed generation, external name, and controller request identifiers. A healthy provider pod does not prove the managed resource reconciled.

## Verify the reconcile loop

Test each phase separately:

1. **Observe absent:** controller confirms the target resource does not exist.
2. **Create:** controller issues the documented create operation.
3. **Observe present:** controller reads back identity and late-initialized fields.
4. **No-op reconcile:** a second pass does not mutate the target.
5. **Update:** change one supported mutable field and observe convergence.
6. **Drift:** make one controlled target-side change and observe correction or reporting.
7. **Delete:** remove the managed resource and verify the configured deletion policy.

Inspect native target state after every mutation. Reconciliation retries can repeat uncertain writes, so test operation idempotency and bound controller concurrency before using shared resources.

## Composition comes later

A Composition introduces multiple managed resources, dependency ordering, patches, readiness checks, connection details, and rollback questions. Add it only after every underlying resource has its own passing lifecycle fixture and cleanup evidence.

## Common failure boundaries

| Symptom                      | Check                                                                      |
| ---------------------------- | -------------------------------------------------------------------------- |
| Provider unhealthy           | Package pull, RBAC, controller configuration, or Kubernetes runtime.       |
| Cannot connect               | Adapter DNS, TLS, network policy, or endpoint schema.                      |
| Authentication failure       | Origin-side provider identity and signing settings.                        |
| Permission denied downstream | Adapter target identity and target resource policy.                        |
| Repeated create              | Observe/read fidelity, external-name mapping, or an uncertain prior write. |
| Stuck deleting               | Delete operation coverage, finalizer, retention, or target dependency.     |

Compare the exact operations with the service catalog and use [diagnostic response headers](/cloud-adapter/debugging/response-headers) where the provider exposes them.