Skip to main content

Hybrid sites

In hybrid mode, one Orchestrate install is the control plane, in your cloud or ours, and keeps the console, the catalog, projects, policy and the audit log. A site is a customer location that runs a site agent. The site does the work that touches sensitive data and sends back only redacted metadata.

 customer premises (site)                    control plane
site agent ── HTTPS, mutual TLS, outbound ──▶ site gateway ── console, API, audit
├─ Kubernetes API (its own namespace)
├─ tool hosts you allow
├─ documents (read-only)
└─ local state: identity, outbox, index, tool results

What a site can run​

WorkWhat it does at the site
Document indexingIndexes files under the site's data folder into a knowledge base.
Tool callsHTTP calls to hosts on the site's allow list.
Model deploymentsA model served in the site's own namespace.
Code agent runtimesA code agent served in the site's own namespace.
Remove a workloadTakes down something the site deployed.

The site agent touches only objects it created and labelled. It never changes anything else in the cluster.

Coming

Running whole agent runs at a site, with a site-local orchestration worker and Model Gateway, is the next step on the same channel. Today the agent runs in the control plane and the site does the work listed above.

Security model​

  • Outbound only. The site agent opens no port: no Service, and a NetworkPolicy that denies all inbound traffic. It connects out to the control plane's site gateway, to its own Kubernetes API, and to the tool hosts its operator allowed. It works through a customer proxy.
  • Enrollment. An organization admin creates the site and issues a single-use, short-lived token, shown once. The site agent generates its own key at the site and receives a client certificate signed by the install's site CA. The private key never leaves the site.
  • Identity. The gateway checks the client certificate against the site CA, then finds the site by the certificate's fingerprint. Nothing in a request body or header says which site it is.
  • Rotation. The agent renews its certificate when a third of its life is left (certificates last 30 days by default), or when an admin chooses Rotate certificate. The old certificate stays valid for 10 minutes.
  • Revocation. Immediate and final: the gateway refuses the site, open tokens stop working, and queued work is cancelled.
  • Server identity. The agent checks the gateway against the site CA it was installed with, never the system trust store.
  • Tool credentials never travel to the site. A tool call names a file in the site's own credentials Secret.

Data residency and redaction​

  • Placement. A project admin can place a project on a site. While it is placed, the control plane refuses document uploads, model deploys and code agent deploys for that project, naming the site, and the project's site work can go to that site only.
  • Redaction on both sides. Results, traces, usage and heartbeats are cut down to an allow list: counters, sizes, SHA-256 digests, Kubernetes names and fixed values. The agent redacts before it sends, and the gateway redacts again on receipt and counts anything it dropped. A dropped key degrades the site's health.
  • What stays at the site. Document text, file names, tool responses and run payloads stay in the agent's local storage. A tool result comes back as site://<site>/<work> with its status, size and digest.
  • Error text isn't sent, only error codes, unless both the site's operator (agent.uploadErrorText in the site chart) and the organization admin (Upload scrubbed error text on the site) opt in. Then a scrubbed, shortened first line is sent. The control plane can't turn it on alone.

Offline tolerance​

  • Work is delivered at least once. A site asks for work, and a lease of 10 minutes, extended by every heartbeat, holds it. A lease that runs out puts the work back for the same site. The agent never runs the same item twice: it sends the stored result again.
  • When the link drops, running work carries on. Results and events wait in the agent's outbox and are sent in order when the gateway answers.
  • After an agent restart, work that can safely run again does. An interrupted tool call is reported as failed, never repeated, because it may already have written to a customer system.
  • Health is shown as online, degraded (a backlog, the link was down, Kubernetes or the data folder unavailable, a certificate near expiry, redaction drops), offline (no heartbeat for three intervals), pending or revoked.

Set up​

The control plane​

Your operator turns on the site gateway:

orchestrate-values.yaml
hybrid:
gateway:
enabled: true
hosts: [sites.orchestrate.example.com]
publicUrl: https://sites.orchestrate.example.com:8443
service:
type: LoadBalancer
Requires network setup

A site outside the control plane's cluster needs a TCP load balancer and a DNS name for the gateway that it can reach, which is network setup outside the chart. Without publicUrl, only sites inside the same cluster can enroll.

TLS must end in the gateway pod, because the client certificate is the credential. Expose it with a TCP load balancer, never an HTTP ingress, which would end the TLS connection and lose the certificate. The site CA is generated once and kept, or you bring your own in hybrid.gateway.ca.

A site​

  1. Open Sites, choose Add site, and give it an id and a name. You need to be an admin of the site's organization.

  2. Choose Issue enrollment token, with a lifetime of 1 hour, 24 hours or 7 days. The console shows the token once, with the Helm command to install the site agent and the site CA certificate.

  3. At the site, run the command against the site's own cluster. vois-orchestrate/charts/vois-site is the site chart inside the Orchestrate chart from your release bundle, and the site's registry needs the site agent image from the bundle:

    helm upgrade --install vois-site vois-orchestrate/charts/vois-site \
    --namespace vois-site --create-namespace \
    --set image.registry=<site registry> \
    --set controlPlane.url=https://sites.orchestrate.example.com:8443 \
    --set-file controlPlane.ca=site-ca.crt \
    --set enrollment.token=<token>

    Optional settings: where the documents are (data.existingClaim, data.hostPath or data.configMap), the tool hosts it may call (agent.toolAllowedHosts), a credentials Secret (credentials.existingSecret), a proxy (extraEnv), and a stricter egress policy (networkPolicy.restrictEgress).

  4. The site shows online once the agent has enrolled, with its capabilities and version.

Then place projects on it under Projects placed on this site, and dispatch work under Dispatch work. Work queues until the site takes it, so a site that is offline picks it up when it reconnects.

Who can do what​

ActionWho
See sites and their workAnyone in the site's organization
Create, rotate, revoke or delete a site; issue or revoke tokens; change its settingsAn admin of the site's organization
Dispatch or cancel work for a projectA developer or admin of the project
Place a project on a siteAn admin of the project
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →