[tomba7]

Part of #5

What was changed

Added docs/crd-conventions.md, a proposal for how the cloud.temporal.io custom resources map to the Temporal Cloud Ops APIs

Why?

We need a standard way to shape and name CRD fields, and a written record of the styles we agree on, so every CRD follows the same rules. Issue #5 raised the first two questions: whether to flatten the request spec, and whether to clean up inconsistent upstream field names. The rest comes from my analysis of the Cloud Ops API and protos. This doc is a starting point for further discussion, not a final decision.

Checklist

1. Closes

2. How was this tested:

3. Any docs updates needed?

[jaypipes]

I recommend actually that we standardize on spec.displayName as the name of a mutable, optional string name for those resources that support it. spec.name and metadata.name are too easily confused, IMHO. spec.displayName (again, only for those resources that support a mutable, optional name) makes it more obvious that this is different from an immutable string name identifier.

[jaypipes]

For Kinds that don't have a unique string name and only have a generated ID that is returned in the HTTP response from the Temporal Cloud API (e.g. ConnectivityRule), we will want to ensure that there is a status.id field that is filled in upon successful creation of the resource.

A warning, though: the problem with this type of API behaviour is that it wreaks havoc on GitOps-driven declarative configuration systems and existing resource adoption. Since the identifier field that is used to look up a specific resource (in this example, that would be the ConnectivityRuleId field) does not exist in the CRD's Spec field, the GitOps operator will simply call kubectl apply on the Kubernetes manifest representing the desired state of the ConnectivityRule.

For the initial reconcile loop, Temporal Resource Operator will attempt to determine if the resource already exists. However, TRO has no way of looking up the ConnectivityRule because it doesn't have the status.id field set (yet). So, it will attempt to create a new ConnectivityRule with the contents of the spec fields.

If there is already a ConnectivityRule that exists with that same configuration settings, a 409 Conflict will be returned by the Temporal Cloud API and the CR will be marked as Stalled/Failed. The user will inspect the CR's status.conditions and see the reason for the stall/failure. So while the GitOps operator won't take any actions (because the spec of the ConnectivityRule in the Kubernetes manifest in the Git repo doesn't change), the user will have no way to remedy the situation because a Kubernetes manifest in a Git repository doesn't contain status fields. And thus the resource will become essentially stuck.

[jaypipes]

Obviously this will need expanding when we get to that stage :) Good to focus on spec for the time being, though.

[jaypipes]

I would recommend going with a slightly different structure:

status:
  # Cloud reference
  cloud:
    id: payments-prod.a1b2c
    resourceVersion: "4"
  # Progress
  observedGeneration: 1
  conditions:
    - type: Reconciling
      status: "False"
      reason: ReconcileSucceeded
      observedGeneration: 1
      lastTransitionTime: "2026-10-08T10:05:00Z"
  # Observed state
  observed:
    state: Active
    activeRegion: aws-us-west-2
    endpoints:
      grpcAddress: payments-prod.a1b2c.tmprl.cloud:7233
    replicas:
      - id: replica-1
        region: aws-us-west-2
        isPrimary: true
        state: Active
    limits:
      actionsPerSecondLimit: 400
    createdTime: "2026-10-08T10:00:00Z"
    lastModifiedTime: "2026-10-08T10:05:00Z"

That way, we can have a common core.temporal.io/v1 StatusCloud struct containing the common id and resourceVersion fields in all HTTP responses from Temporal Cloud API and then add StatusCloud as a field to the existing core.temporal.io/v1 StatusBase struct.

Also, we can have a nice, clean status.observed field that contains essentially the rest of the response fields from the Temporal Cloud API call.

[jaypipes]

merging this. we can fix up after the rename.