Deployments
Deploying integrations as Kubernetes workloads: rollouts and rollbacks.
Deploying an integration runs a version tag of it as its own Kubernetes workload: a Deployment of the generic octo-runtime image with the tag's frozen definition mounted in. One integration can be deployed many times (say, a staging and a production deployment on different tags), and each deployment has its own address, scale, and environment bindings.

What a deploy creates
For each deployment the orchestrator creates resources named octo-dep-{deploymentId} in its namespace, labelled with the deployment and integration ids:
- A ConfigMap holding the frozen definition as
integration.yaml, mounted read-only at/etc/octo/integrations, the runtime image's default config directory. - A Deployment running
octo-runtimeat the requested replica count (minimum 1). The orchestrator injects the runtime-services environment (RUNTIME_SERVICES_MODULE=k8s,OCTO_DEPLOYMENT_ID,ORCHESTRATOR_URL,NATS_URL, the pod's name/namespace via the downward API, and the deployment's display name, tag, and snapshot id) plus your env bindings, andOCTO_TRACINGwhen the deployment is traced. - Services, only for networked integrations (see below): a per-deployment ClusterIP Service, and a stable internal Service
octo-int-{slug}other integrations address. - An Ingress, only when the deployment is exposed externally.
A failed deploy is rolled back completely: partial cluster resources and the database row are removed.
Networked vs. bare workloads
An integration that declares HTTP_PORT (with a numeric default) in its env block has an HTTP source listening on that port. Only those deployments are networked: they get Services, a unique slug, an internal URL, and the option of external exposure. The orchestrator supplies HTTP_PORT (and HTTP_HOST=0.0.0.0, when declared) into the pod, so the listener binds all interfaces; these two variables are managed and cannot be overridden by bindings.
Anything else (a cron-driven job, a queue consumer) runs as a bare workload: pods only, no Service, no URL.
Internal address
Every networked deployment gets a slug, unique among the deployments of its environment: pick one in the deploy dialog or leave it empty to have the orchestrator allocate one from the integration name (orders, orders-001, ...). The slug names the stable internal Service, so other integrations reach the deployment at a constant, replica-balanced address reported as the deployment's internalUrl:
http://octo-int-{slug}.{namespace}:{port}External exposure
Toggling external exposure additionally creates an Ingress at https://{subdomain}.{baseDomain}; the subdomain defaults to the slug and must be unique across integrations. Which controller serves it is the chart's orchestrator.ingressClass; empty (the default) leaves it to whichever IngressClass the cluster marks default. TLS is whatever that domain is set up for: a per-host certificate issued by the configured ClusterIssuer over HTTP-01, a shared pre-issued wildcard when the chart's wildcardTLS is enabled, or none of the chart's doing when something upstream terminates. The public address is reported as externalUrl.
External endpoints require BASE_DOMAIN on the orchestrator (the Helm chart's orchestrator.baseDomain); without it an external deploy is rejected. See Deploying with Helm.
Environment bindings
The deploy dialog lists every env var the tag's definition declares. Each can be bound to a literal value or a cluster secret by name (injected via secretKeyRef, so the value never touches the database). Keys already supplied by the tag's frozen .env resources count as provided. A deploy that leaves a required variable unbound by either is rejected up front instead of letting the pod crash-loop. Full details: Resources and Secrets.
Tracing
Trace this deployment in the deploy and rollout dialogs runs its pods with the runtime's tracer on, recording the flows and blocks each message passes through and every model call made on its behalf, priced with what it cost, for the platform to store and query. See Traces.
Tracing is a troubleshooting tool, not a production setting. It significantly reduces throughput: every traced block is recorded on the flow's own goroutine, and capturing payloads marshals the message once per block. Turn it on for the deployment you are debugging, and turn it off again once you have your answer.
It is a per-deployment setting, off by default, so a staging deployment can be traced while the production deployment of the same integration is not. Deployments that have it on are marked Traced in the deployment lists.
The runtime resolves OCTO_TRACING when it parses its flags, before any config is loaded, so the setting only reaches a pod that starts with it. Changing it on a live deployment goes through a rollout, which replaces the pods. A rollout that does not mention tracing leaves the setting as it was, so a plain version bump never stops a trace you are reading.
Captured bodies and variables are stored as they arrived and are readable by anyone signed in to the platform. Avoid tracing a deployment whose messages carry credentials, or set OCTO_TRACING_BODIES=false as an env binding to record the sequence without payloads.
Platform access
Every deployed integration presents a platform token of its own, and what it may do is what that token carries. Every one of them reaches the stores its pod owns — its key-value namespace, its objects, its agent memory. The deploy and rollout dialogs carry two independent grants under Advanced, both off by default, saying what it reaches besides.
| Grant | What the token additionally opens |
|---|---|
| Builds integrations | Integrations, their resources, versions and dev runs — across the whole installation, not just its own |
| Operates deployments | Deploying, rolling out, scaling and removing deployments — anyone else's included |
Two checkboxes and not a choice: building integrations and operating them are different jobs, and one integration can do both, either, or neither.
Neither grant is scoped to the deployment's own integration. Builds integrations reads and writes every integration here, and Operates deployments acts on every deployment. Grant either only to an integration you would trust with the corresponding role on your own account.
The token an unattended flow uses
This matters most where there is nobody to borrow a credential from. A flow woken by a queue message, a webhook or a Slack event has no person behind it and never will — so the deployment's own token is not a fallback, it is the only credential that flow has.
It is available to the flow as env.PLATFORM_TOKEN, and the runtime keeps it valid. You do not have to obtain it, refresh it, or notice when it changes:
connectors:
- name: octo
type: http-client
settings:
baseURL: ${ORCHESTRATOR_URL}- type: rest
settings:
connector: octo
method: GET
path: /integrations
headers:
Authorization: '"Bearer " + env.PLATFORM_TOKEN'Two things to know about how you reference it:
- Read it through an expression, as
env.PLATFORM_TOKEN. That is what gets you the token that is valid now. - Not as
${PLATFORM_TOKEN}. That spelling is substituted once when the definition is loaded, so it would freeze whatever was valid at startup — and start failing an hour later, silently.
On a runtime that has no platform identity — the editor's Run, dolphin, a local octo run — the variable is an ordinary environment variable and is simply unset unless you set it, so the same definition loads and tests everywhere.
Who may grant it. The token is minted on the authority of whoever is deploying, and iam refuses to lend a deployment more than that person could do themselves. It never inherits: an administrator's deployment is not an administrator, and the grants are what somebody ticked on purpose.
Renewal keeps what was granted. A deployment's token is renewed as what it was minted as, not as what its owner may do now. Taking somebody's operator role away does not quietly change what their running integrations reach — stopping one is what deleting the deployment is for.
Addresses are not access. ORCHESTRATOR_URL and OBSERVABILITY_URL are in every runtime pod. Neither is a boundary: both APIs authorize the token they are presented, and anything on the cluster network could dial either address regardless.
Shared responsibility
Octo's side. The token exists, is scoped to the grants above and nothing more, is renewable however long ago it expired, and is kept valid without your flow doing anything. It is mounted rather than passed in the pod's spec, and it is never written into a log line.
Your side. What the flow does with it. env.PLATFORM_TOKEN is a string like any other once your definition has it, and a flow can put a string anywhere:
- Do not copy it into a message variable. A traced deployment records variables, and traces are readable by anyone signed in to this platform. A token in a variable is a token handed to everybody with an account.
- Do not send it anywhere but this installation. It is a bearer credential: whoever holds it is your deployment, with its grants, until it expires.
- Do not log it, including by logging a whole message that carries it.
- Treat the grants as the blast radius of your definition. An integration with Operates deployments that can be made to act on attacker-chosen input can remove somebody else's deployment. Narrow what the flow will act on, not just what it can reach.
Access is stored on the deployment and, like tracing, is carried through a rollout that does not mention it.
Runners
A runner is which image a deployment's pods run. There are two, and the choice is per deployment.
| Runner | Image | For |
|---|---|---|
standard (the default) | octo-runtime: distroless, one static binary, no shell, nothing writable | Every integration that serves requests, consumes a queue, or runs on a schedule |
agentic | octo-agenticrunner: adds a shell, curl, jq, the standalone octo CLI, dolphin, and a writable /workspace | An integration built to drive the platform: one whose flows run local commands, invoke other flows, or execute a test suite |
A cli-run block in an image with no local programs cannot run anything, and a file connector needs somewhere writable to point at; the platform agent is the first deployment to need both. The agentic runner gets a /workspace volume, an emptyDir capped by the chart that dies with the pod, and whatever CPU and memory limits the chart sets for it. Nothing else about the workload changes: same probes, same ConfigMap, same Services, same rollout.
The agentic runner is privileged, not merely bigger. A pod holding a shell and a runtime it can point at a definition it wrote a moment ago is a general execution environment, so the boundary is the pod, not any allow list inside the flow. Everything that pod holds, including secrets bound to its environment, and everything it can reach on the network, is reachable by anything it runs. Grant it to integrations whose definitions you control.
An installation whose chart does not configure the agentic image does not have that runner, and a deploy asking for it is refused with the setting named rather than quietly downgraded: the standard image would produce a healthy pod whose every command fails with not found. Like the grants above, the runner is stored on the deployment and carried through a rollout that does not mention it.
Status
Deployment status is computed live from the cluster through Kubernetes informers, so reads are cheap and updates are push-based. pending means created, pods not ready yet; running means at least one replica is ready; failed means a pod is in a terminal or crash-looping state, and the response carries the reason (an image or secret problem, say) and per-pod detail.
Each status change is published to NATS and streamed to the browser as SSE (see Event Bus), with a polling fallback when no broker is configured. Individual pod logs stream from GET /deployments/{id}/pods/{pod}/logs (with follow/tail); aggregated, searchable logs across deployments live in the logs view, see Monitoring.
When the cluster and the database disagree
A deployment is a row in integration_deployments and a set of Kubernetes objects named from that row's id. A cluster that went away and came back leaves rows describing workloads it has never had, and since status falls back to the cached value whenever the cluster read fails, those rows keep saying running. A deploy whose rollback failed leaves the opposite: a Deployment with no row.
A sweep runs once at startup and every five minutes after that, and repairs both:
| Found | Done |
|---|---|
| A row whose workload is gone | The row is deleted, along with the internal Service and the deployment's KV entries, the same cleanup Undeploy does. |
| A workload with no row | The workload is deleted. |
| A stored platform-agent id pointing at a deleted row | The id is forgotten, so the admin page offers Deploy rather than a roll-out of nothing. |
A cluster_secrets entry with no key in the cluster | The catalogue entry is dropped. |
Three things it will not do. A key in the cluster's Secret with no catalogue entry is logged and kept, because a catalogue restored from an older backup is exactly when the key is worth saving. A row touched in the last five minutes is left alone, because a deploy writes its row before it calls the API server. And no row is deleted on the strength of the listing alone: the sweep asks again for that one workload by name first, because the listing matches on labels, which anyone with cluster access can edit. The secret sweep also does nothing while the shared octo-secrets Secret does not exist, since it is created by the first secret you store and is briefly absent while an externally managed Secret is recreated.
The sweep deletes rows, so it never guesses. If the cluster cannot be listed (an error, or informer caches that have not loaded) it does nothing at all, because "I could not see the cluster" and "the cluster is empty" are the same empty answer. An orchestrator with no cluster access never sweeps.
Deleting a row is not recoverable: its settings and env bindings go with it. Redeploy from the integration's version list, which still has the tag.
Day-2 operations
| Operation | Endpoint | What it does |
|---|---|---|
| Scale | PATCH /deployments/{id} | Changes the replica count in place; the Service keeps balancing across the new set. |
| Roll out a new version | POST /deployments/{id}/rollout | Upgrades the deployment to a different tag in place. |
| Pin a runtime | POST /deployments/{id}/rollout with runtimeVersion | Keeps the deployment on a runtime release, or "latest" to follow the install again. |
| Test a version | POST /deployments/{id}/testruns | Runs a tag's test suites with the deployment's env on this install's runtime, and optionally rolls out when they pass. |
| Undeploy | DELETE /deployments/{id} | Removes the cluster resources and the record. |
Rolling out a new version
A rollout ships a different tag's frozen definition to a live deployment as a rolling update: the orchestrator rewrites the ConfigMap, stamps a config-hash annotation on the pod template so Kubernetes rolls the pods, and records the new tag. The deployment keeps its identity (id, slug, internal and external URLs, replica count) and its env bindings and tracing setting; pass a replacement binding set, or a tracing flag, to change either during the rollout. Because the same mechanism accepts an older tag, rollback is a rollout to the previous tag.
Two guards apply, mirroring deploy: the target tag's required env vars must still be provided, and a tag that changes whether the integration is networked (adds or removes HTTP_PORT) is rejected, because that would change the Service/Ingress topology, which a rolling update cannot express. Undeploy and redeploy instead.
The new tag, env bindings and tracing setting are recorded in one write once the pods have rolled. If that write fails, the rollout reports the failure even though the pods did roll: they are on the new version and the stored record is behind them until a retry succeeds. Retrying is safe, because a rollout is idempotent, and an omitted env or tracing value on the next rollout is read from that record.
Deploying "Current" from the editor first creates a tag of the working copy, then deploys that tag, so even ad-hoc deploys are pinned to an immutable version.
Moving to a new runtime
A deployment keeps the octo-runtime image it was last rolled out on. After you upgrade the platform, existing deployments run the older runtime until they are rolled out again, and every rollout moves a deployment onto the runtime this install deploys now. A deployment that is behind carries upgradeTo (the newer release) in its API response and an arrow on its runtime pill, and the dashboard lists them all.
Prove the move before you make it with a test run: the orchestrator runs the dolphin suites frozen under a tag (by default the one the deployment runs), with the deployment's env bindings, against the runtime release this install deploys. The run is a Kubernetes Job in the standalone runtime image, which carries dolphin beside the same octo. With rolloutOnPass, a run in which every case passes rolls the deployment onto the tested tag, keeping its env and tracing.
curl -X POST "$ORCHESTRATOR/deployments/$DEPLOYMENT/testruns" \-H "Authorization: Bearer $TOKEN" \-d '{"rolloutOnPass": true}'Poll GET /deployments/{id}/testruns/{runId} for the verdict:
status | Meaning |
|---|---|
running | The Job has not finished. |
passed | Every case passed. When the run asked for a rollout, rolledOutAt says when it happened; a rollout that could not be made (the deployment was rolled out during the run, or the rollout failed) leaves rolledOutAt empty and says why in error. |
failed | A case ran and did not do what it expected. report holds dolphin's JSON report. |
errored | Nothing could be tested: a suite or the config is wrong, or the pod never started. error says which. |
timed_out | The run took longer than five minutes. |
Suites are the .octo/tests/*_test.yaml files an integration's Testing view saves, frozen into each tag like any other file. A tag with none cannot be tested, and starting a run on it returns 422.
In the platform, the dashboard lists every deployment on an older runtime. Each one opens its rollout dialog, and Review upgrades opens the Upgrades page.

Test & roll out in the rollout dialog tests the selected tag and rolls out only on a pass. It uses the deployment's saved env and tracing, so it is unavailable once you edit either in the dialog; roll those changes out directly.

The Upgrades page, in the user menu, lists every deployment on an older runtime with how its suites last went on the new one. Test and Test & upgrade act on one deployment; Test all and Test & upgrade all act on every one that has suites, and the second upgrades each one whose suites pass. Deployments whose version has no suites are called out in their own section, with Upgrade untested as their only option, since an upgrade cannot be checked before it ships.

A failed run shows its report, case by case; an errored or timed-out run shows why it could not test, and the report too when dolphin got far enough to write one. Open in the editor takes you to the integration to fix the suite or the flow. Nothing moves the deployment until you upgrade it, or a Test & upgrade run passes.

From a terminal, octopaas deployments outdated lists them, octopaas deployments test <deployment> --upgrade tests and upgrades one, and octopaas deployments upgrade <deployment> upgrades one without testing. See deployments.
GET /upgrades serves the same view: the runtime this install deploys and, per deployment, the release it runs, upgradeTo, hasSuites and its latest test run. A run older than the deployment's last deploy or rollout is flagged latestRunStale, because the version, env or tracing it tested may have changed since; the Upgrades page shows such a deployment as not tested since the last rollout.
Pinning a runtime
A deployment follows the install's runtime by default: every rollout moves it onto the release the install deploys now. Pin it to keep it on a release instead, for an integration you do not want moved until you have checked it. Pick the runtime beside the version in the deploy or rollout dialog: Latest follows the install, and Pin to lists the release the install deploys and the supported releases no newer than it (GET /runtimes).

Over the API, pass runtimeVersion on a deploy or rollout: a release pins, "latest" unpins, and leaving it out of a rollout keeps the current setting. The pods run the configured runtime image at that release's tag, so the release has to exist in your registry.
A pinned deployment that is behind is still listed on the dashboard and the Upgrades page, marked Pinned, and its suites can still be run against the new runtime. It is never upgraded for you: a test run asking to roll it out is refused, Test & upgrade all tests it without upgrading it, and Move pin to is the manual upgrade, which keeps it pinned at the new release.
Undeploying
Undeploy deletes the Ingress, Deployment, Services, and ConfigMap, then the deployment record. The deployment's entries in the KV store are cleaned up best-effort; a cleanup failure never blocks the undeploy, and orphaned rows are harmless.