Skip to main content

Deployment Operations Guide

This page covers the deployment workflows that exist in the customer portal today.

The goal is to help platform teams understand what the platform actually supports right now, not to imply a bigger deployment-control plane than the code currently exposes.

The Current Deployment API Surface​

The deployment-operation endpoints are:

  • GET /api/v1/deployments/versions
  • POST /api/v1/deployments/upgrade
  • GET /api/v1/deployments/upgrade/{upgradeID}
  • GET /api/v1/deployments/upgrades

These routes are session-backed enterprise APIs exposed by the customer portal.

What the Upgrade API Can Target​

The upgrade trigger API currently accepts these service values:

  • agent
  • orchestrator
  • customer-portal
  • all

That maps to the real service-target validation in the deployment handler.

Triggering an Upgrade​

Use:

POST /api/v1/deployments/upgrade
Content-Type: application/json

Current request shape:

{
  "service": "all",
  "version": "latest",
  "force_new_deployment": true
}

Notes that matter:

  • service is required and must match one of the supported values above
  • version is accepted in the request shape, but current version selection is still limited
  • force_new_deployment is the explicit control for forcing a rollout

What the Trigger Response Means​

The upgrade trigger returns an upgrade_id plus per-service status entries.

The response includes fields such as:

  • upgrade_id
  • services
  • message
  • estimated_time

The current handler uses 202 Accepted when the rollout has been successfully initiated.

Tracking Upgrade Status​

Use:

GET /api/v1/deployments/upgrade/{upgradeID}

The status response is the main platform-team view for understanding whether a rollout is:

  • PENDING
  • IN_PROGRESS
  • SUCCESS
  • FAILED
  • PARTIAL

That response is built from the recorded deployment upgrade plus live ECS service checks when the upgrade is still running.

Listing Upgrade History​

Use:

GET /api/v1/deployments/upgrades

This is the historical view for:

  • recent upgrades
  • who initiated them
  • how many services were involved
  • whether the result was successful or partial

Versions Endpoint​

Use:

GET /api/v1/deployments/versions

Important caveat:

The current implementation is still a lightweight placeholder. It returns a small version list and explicitly says version selection is still evolving. Do not assume this endpoint is already a fully featured release catalog.

What the Deployment Handler Actually Does​

The current implementation:

  • reads deployment cluster, stack, and region information from the organization record
  • derives the cluster name if needed
  • records the upgrade in deployment_upgrades
  • uses AWS ECS update-service for the targeted services
  • tracks service-level status and overall rollout state

That means this should be treated as an enterprise portal-driven upgrade workflow backed by ECS, not as a generic multi-cloud deployment engine.

Choosing the Right Upgrade Scope​

The service target you choose should match the change you are trying to make.

TargetWhen it is usually appropriate
agentrequest-path or connector-execution changes
orchestratorworkflow, provider, or orchestration-path changes
customer-portalcontrol-plane or portal-experience changes
allcoordinated platform rollout where services need to move together

This is a better operating model than treating every change as an all-services redeploy.

Before starting​

  • verify the correct tenant and environment
  • verify portal session access
  • confirm GET /health is healthy
  • confirm connector and provider health for the tenant

Trigger the upgrade​

  • choose the smallest safe service scope when possible
  • use all only when that matches the actual rollout need
  • capture the returned upgrade_id

Watch the upgrade​

  • poll GET /api/v1/deployments/upgrade/{upgradeID}
  • review any partial or failed service statuses
  • correlate with runtime metrics and logs

Validate after completion​

  • confirm session login still works
  • verify one LLM-provider-backed request path
  • verify one connector-backed path
  • confirm monitoring still reflects the new state

Failure and Partial-Success Handling​

The platform can surface PARTIAL status when some services advance and others fail.

That means platform teams should not treat "upgrade request accepted" as "rollout complete." The safe pattern is:

  1. trigger
  2. watch status
  3. validate real post-upgrade behavior

Recommended Post-Upgrade Validation Matrix​

After the upgrade completes, validate more than the final status field.

At minimum:

  • portal login still works
  • one provider-backed request path works
  • one connector-backed path works
  • monitoring still reflects healthy steady state
  • license, usage, and deployment views are still accessible

That is the kind of validation staff engineers expect in a real enterprise runbook.

Rollback Guidance​

The deployment API does not expose a dedicated rollback endpoint today.

So the right guidance is:

  • use the upgrade-status and upgrade-history views to understand what happened
  • coordinate rollback or corrective deployment through your existing deployment process
  • validate the restored state through the same health, provider, and connector checks
Last updated on