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.

Deployment Models

SaaS-Managed Enterprise

In a managed deployment, AxonFlow owns most of the infrastructure operations. Customers still need to understand portal access, organization operations, release coordination, monitoring expectations, and how upgrades affect business workflows.

Self-Managed or In-VPC Enterprise

In self-managed and In-VPC deployments, customers usually control when upgrades are applied and how the environment is monitored. This is where the deployment APIs, post-deployment checks, and support escalation path matter most.

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.

Target	When it is usually appropriate
agent	request-path or connector-execution changes
orchestrator	workflow, provider, or orchestration-path changes
customer-portal	control-plane or portal-experience changes
all	coordinated platform rollout where services need to move together

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

Recommended Upgrade Workflow

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

Controlled Rollout Flow

For a controlled rollout, use this order:

1. confirm portal authentication works
2. confirm the target environment and deployment configuration
3. review available versions
4. trigger the intended upgrade scope
5. monitor service status and health
6. verify business-critical workflows after rollout

In API terms, that usually means:

1. GET /api/v1/deployments/versions
2. POST /api/v1/deployments/upgrade
3. GET /api/v1/deployments/upgrade/{upgradeID}

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. Teams should still have a rollback plan before a production deployment window.

At minimum, decide:

• what version or image set you would restore
• who approves rollback
• which service scopes can roll back independently
• what health and business signals trigger rollback

Then:

• 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

Service-by-Service Thinking

Because the deployment APIs are service-aware, it is worth thinking about the platform in service slices:

• Agent changes affect request enforcement, MCP, and audit entry points
• Orchestrator changes affect provider routing, workflows, approvals, and regulated flows
• Customer portal changes affect portal UX, portal APIs, session auth, and admin workflows

This helps teams localize risk and validate the right surfaces after each rollout.

Enterprise Operations Model

Deployment operations also need an operating rhythm: ownership, weekly checks, change windows, and mode-aware visibility.

This section is the operating guide for teams running AxonFlow Enterprise beyond initial setup.

It is for the teams that actually carry the platform after rollout:

• platform engineers
• SRE and DevOps teams
• security and governance teams
• customer success or internal enablement teams that need dependable operational workflows

What Enterprise Operations Covers

The enterprise operations estate is broader than “is the service up?”

In practice, enterprise platform teams need to manage:

• deployment upgrades
• portal health and session-backed admin workflows
• connector and provider runtime configuration
• usage and license visibility
• monitoring and dashboards
• incident response and escalation

The Core Operational Surfaces

1. Portal health and session-backed APIs

The customer portal is part of day-two operations, not just onboarding.

Key routes include:

• GET /health
• GET /api/v1/auth/session
• GET /api/v1/license/status
• GET /api/v1/usage
• GET /api/v1/usage/summary

2. Deployment operations

Enterprise deployment management currently centers on:

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

These are the current enterprise APIs for tracking and triggering upgrade workflows.

3. Runtime configuration

Platform Teams often need to change live enterprise configuration without redeploying the whole stack.

Key surfaces:

• GET/POST/PUT/DELETE /api/v1/connectors
• POST /api/v1/connectors/{connectorName}/test
• GET/POST/PUT/DELETE /api/v1/llm-providers
• PUT /api/v1/llm-providers/routing

4. Mode-aware visibility

Enterprise deployments do not all expose the same operational data.

The customer portal uses deployment-mode configuration to decide what platform teams can see:

• SaaS mode keeps tenant isolation on and hides node-level platform metrics
• In-VPC mode exposes node usage and platform-wide metrics

That distinction matters for docs, dashboards, and incident workflows.

Start Here Based on What You Need

If you need to...	Start with...
understand the deployment upgrade workflow	Deployment Operations
monitor the enterprise runtime and portal	Monitoring and Observability Setup
understand dashboard availability by deployment mode	Grafana Dashboards Reference
figure out what happens during an incident	Deployment Troubleshooting
understand support and escalation expectations	Support Escalation

What Good Enterprise Operations Looks Like

A healthy enterprise operating model usually has:

• one clear owner for deployment changes
• one clear owner for monitoring and alerting
• a documented rollback and incident workflow
• a way to validate connectors and providers after every major change
• clarity on whether the deployment is SaaS or In-VPC, because that changes what platform teams can inspect directly

Recommended Operating Rhythm

Before a change

• confirm the environment and tenant you are operating on
• review current deployment status
• confirm portal health
• confirm monitoring access

During a change

• track the upgrade through the deployment APIs
• watch runtime health and error rates
• verify one provider-backed path and one connector-backed path

After a change

• confirm deployment completion state
• confirm dashboards and usage views are still sane

Suggested Ownership Model

Enterprise teams usually move faster when ownership is explicit:

• platform engineering owns upgrades and runtime configuration changes
• SRE or operations owns monitoring, alerting, and incident coordination
• security or governance owners review policy and oversight implications

Even if one team plays multiple roles early on, the docs should help readers see those responsibilities clearly.

Weekly and Monthly Operating Tasks

Weekly

• review recent upgrades
• review connector and provider health changes
• review usage shifts and unusual error patterns

Monthly

• review license posture
• review whether current dashboards still answer the right questions
• review whether identity, governance, and connector rollout practices still match actual usage
• confirm no unexpected connector or provider regressions

These repeated operating tasks are where mature enterprises distinguish themselves from teams that only “set it up once.”

Related Docs

• Deployment Overview
• AWS Marketplace Deployment
• CloudFormation Deployment
• Post-Deployment Checklist
• Deployment Testing & Validation
• Deployment Troubleshooting