Handle pre-existing resources

This is a design discussion, not a code task: the issue weighs an AdoptedResource CRD against an resource-operator.temporal.io/adoption-policy annotation for adopt and adopt-or-create. Read the ACK adoption references it links to, and the GitOps trade-offs it describes, before forming a view. Done means a maintainer records which approach is chosen and the adoption semantics are agreed, and only then can implementation start.

One of the first dilemmas builders of Kubernetes operators that interface with cloud APIs must face is how to handle "adoption" of a pre-existing cloud resource by the Kubernetes operator.

There are two primary use cases that resource "adoption" aims to address:

1. Manual adopt operation: this is for when a user is starting to use the Temporal Resource Operator for managing their Temporal Cloud resources but they already have existing Temporal Cloud resources and just want to instruct the Temporal Resource Operator to take ownership of the desired state of the resource.
2. Idempotent adopt-or-create operation: this is for when a user doesn't know (or care) whether the identified Temporal Cloud resource already exists. They want to be able to kubectl apply the custom resource manifest and have the Temporal Resource Operator create the resource if it does not exist OR take ownership of the desired state of the resource if it does exist.

There are generally two solutions to handling pre-existing resources: use a distinct AdoptedResource custom resource OR use annotations on the custom resources.

Use a distinct AdoptedResource custom resource

With this solution, a common AdoptedResource custom resource definition allows the user to explicitly instruct the Temporal Resource Operator to take ownership of a pre-existing Temporal Cloud resource.

The AdoptedResource custom resource definition might look something like this:

apiVersion: cloud.temporal.io/v1alpha1
kind: AdoptedResource
meta:
  name: my-temporal-cloud-namespace
  namespace: temporal-resource-operator
spec:
  # this field contains override values for fields in the actual `cloud.temporal.io.Namespace`
  # custom resource that will be created by Temporal Resource Operator when discovering
  # the pre-existing resource and taking ownership of it.
  kubernetes:
    apiVersion: cloud.temporal.io/v1alpha1
    kind: Namespace
    metadata:
      labels:
        temporal.io/account: "<ACCOUNT_ID>"
  temporal:
    account: "<ACCOUNT_ID>"
    project: "<PROJECT_ID>"
    id: "<RESOURCE_ID>"

And the Temporal Resource Operator would have a reconciler embedded within it that would look for new AdoptedResource CRs, communicate with the Temporal Cloud API to check if the resource with the specified ID exists and create a CR of the Kind specified in the spec.kubernetes.kind field that contains the definition of the pre-existing Temporal Cloud resource.

Benefits:

• The adoption process is explicit and deliberate. The user would call kubectl apply -f <adopted_resource_manifest> to manually bring the resource under the Temporal Resource Operator's ownership.
• Because there is a separate AdoptedResource CRD, the status of the resource adoption operation can be put in the AdoptedResource.Status field, making debugging of the adoption process easier than if the adoption operation log lines are mixed in with log lines for "normal" lifecycle operations.
• Because there is a separate controller that handles CRs of that Kind, we don't need to copy/paste adoption-related code into every controller/$resource subpackage. Note that we could put common adoption-related code into the kube-temporal repository to partially alleviate this concern.

Drawbacks:

• Requires users to know ahead of time that a resource already exists. In a GitOps-based fully-declarative configuration management system, the GitOps controller examines the Git config repo to determine the latest desired state of the environment. Having the AdoptedResource controller create custom resources means that the creation of custom resources handles outside that Git config repo, which means for GitOps-driven systems you would need some script or automation that would essentially do kubectl get <resource> -oyaml > $git_config_repo/$kind/$name.yml && git commit in order for the GitOps controller to have an accurate view of the latest desired state of the system.

Use annotations on the custom resources

This solution uses a couple annotations on the main custom resources managed by Temporal Resource Operator to instruct the operator how to handle a pre-existing resources.

These annotations might look like this:

apiVersion: cloud.temporal.io/v1alpha1
kind: Namespace
meta:
  name: my-temporal-cloud-namespace
  namespace: temporal-resource-operator
  annotations:
    resource-operator.temporal.io/adoption-policy: "adopt-or-create" # or just "adopt"
spec: {}

Temporal Resource Operator would populate the values of the custom resource's Spec field with the latest observed state read from the Temporal Cloud API for that resource.

The resource-operator.temporal.io/adoption-policy annotation would instruct Temporal Resource Operator how to handle pre-existing resources. When the annotation value is adopt, Temporal Resource Operator would expect a Temporal Cloud resource to exist and return an error when it did not. When the annotation value is adopt-or-create, Temporal Resource Operator would create the Temporal Cloud resource as specified in the applied custom resource's Spec if it did not already exist.

Benefits:

• No need for another CRD.

Drawbacks:

• Controllers should generally never update the Spec field of a resource that it manages (by "manages", I'm referring to the controller specifying that resource in the controller-runtime's TypedBuilder.For() method)
• Because the Temporal Resource Operator updates the Spec (desired state) of a resource that it adopts, this can interfere with a GitOps-driven system. In a GitOps-based fully-declarative configuration management system, the GitOps controller examines the Git config repo to determine the latest desired state of the environment. Having the controller update the Spec of custom resources means that the source of desired resource state is now outside that Git config repo, which means for GitOps-driven systems you would need some script or automation that would essentially do kubectl get <resource> -oyaml > $git_config_repo/$kind/$name.yml && git commit in order for the GitOps controller to have an accurate view of the latest desired state of the system.

ACK

ACK originally used the separate AdoptedResource approach but switched to using annotations in late 2024 and into 2025. They totally rewrote the AdoptedResource functionality. Here is the original AdoptedResource proposal. This GH issue from July 2022 is the impetus for using annotations for adoption instead of the separate AdoptedResource CRD. The final Adopt-or-Create feature was merged in April 2025 and the official docs now recommend using annotations.