reconcile.remote

reconcile.remote: wires a remote HTTP endpoint as the reconciler for a CRD. Instead of running logic inside the runtime binary, Orkestra POSTs a PreparedRequest to the declared endpoint after every watch event. The external service returns a RemoteReconcileResult; Orkestra applies the result and manages the full operator lifecycle on its behalf — informer, queue, workers, backoff, health, RBAC.

Use this when reconcile logic lives in a separate service (e.g. a sidecar, a mesh-external API, or a language runtime that Orkestra does not host).

Wire format

operatorBox:
  reconcile:
    default: false
    remote:
      endpoint: "https://my-reconciler.internal/reconcile"
      protocol: http
      timeout: 30s
      args:
        logLevel: "{{ .spec.logLevel }}"
        environment: "{{ .spec.environment }}"
      payload:
        object:
          exclude:
            - metadata.managedFields
            - metadata.annotations
        children:
          enabled: true
          exclude:
            - metadata.managedFields
      managedResources:
        - group: apps
          plural: deployments
        - group: ""
          plural: services
      auth:
        secretRef:
          name: my-reconciler-token
          key: token
        header: "Authorization"

Fields

reconcile.remote:

payload: fields

auth: fields

Prerequisites

reconcile.remote: requires default: false. Without it the validator rejects the config.

operatorBox:
  reconcile:
    default: false   # required
    remote:
      endpoint: "..."

RBAC

Orkestra generates RBAC rules for managedResources and auth.secretRef automatically:

• Each entry in managedResources produces a get/list/watch/create/update/patch/delete rule for that resource group.
• Static auth.secretRef.name values are scoped to resourceNames: in the generated ClusterRole.
• Template auth.secretRef.name values (those containing {{) produce an unscoped secrets: get rule since the name is not known at build time.

simulate

Remote reconcilers cannot be simulated. ork simulate prints a note and skips any CRD that declares reconcile.remote:.

  note: remote reconciler — skipping (dispatches to an external endpoint at runtime)

PreparedRequest shape

The payload Orkestra POSTs to endpoint is a JSON-encoded request body:

{
  "key":      "default/my-webapp",
  "gvk":      { "Group": "myorg.io", "Version": "v1", "Kind": "MyKind" },
  "object":   { ... },
  "args":     { "logLevel": "info", "environment": "production" },
  "prepared": { ... }
}

RemoteReconcileResult shape

The endpoint must respond with 200 OK and a JSON body:

{
  "result":       "ok",
  "requeueAfter": "",
  "error":        "",
  "status":       { "phase": "Ready" },
  "resources": [
    {
      "type":   "deployment",
      "fields": { "name": "my-webapp", "image": "nginx:latest", "replicas": 2, "port": 8080 }
    },
    {
      "type":   "service",
      "fields": { "name": "my-webapp-svc", "port": 80, "targetPort": 8080 }
    }
  ]
}

Intent form

The intent form lets the reconciler return a named type and a flat field map. Orkestra constructs the full Kubernetes object. Optionally set forceConflict to control SSA field ownership for that resource.

{ "type": "deployment", "fields": { "name": "my-app", "image": "nginx:latest", "replicas": 2 }, "forceConflict": true }

Supported types:

For built-in types (deployment, service, etc.) the kind field is inferred from type — omit it. For custom, kind must be set in fields since there is no single Kubernetes kind to infer.

Full object form

When more control is needed, return a complete Kubernetes object:

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": { "name": "my-app" },
  "spec": { ... }
}

The type must still be declared in managedResources.