Deployments

Deployments are running instances of templates. Each deployment has a unique name, runs in a Kubernetes namespace, and is managed by the UserDeployment operator.

Deployment Operations

List Deployments

GET /api/deployments

Returns all deployments for the authenticated user. Results are filtered by the current team context if a team is selected. Authentication: Required (session or API key with deployments:read scope) Query Parameters:

string

Filter by team ID

Response:

string

Unique deployment name

string

Deployment status: Pending, Provisioning, Ready, Error, Deleting

string

Template name used for this deployment

string

Visibility: public or internal

array

Array of ingress endpoints

string

Error message if status is Error

boolean

Whether the deployment can be deleted

Example:

curl -X GET "https://your-domain.com/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "name": "abc123xyz7",
    "status": "Ready",
    "template": "nginx",
    "visibility": "public",
    "ingresses": [
      {
        "id": "nginx",
        "name": "nginx",
        "host": "abc123xyz7.yourdomain.com",
        "url": "https://abc123xyz7.yourdomain.com"
      }
    ],
    "canDelete": true
  }
]

Create Deployment

POST /api/deployments

Create a new deployment from a template. The deployment is provisioned via the UserDeployment Kubernetes operator. Authentication: Required (deployments:write scope) Request Body:

string

required

Template name to deploy (e.g., “nginx”, “postgres”)

object

Environment variables as key-value pairs

string

Deployment visibility: public or internal (default: public)

Response: 201 Created

string

Generated deployment name

string

Initial status (typically Pending)

string

Template name

string

Deployment visibility

Example:

curl -X POST "https://your-domain.com/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "nginx",
    "envVars": {
      "PORT": "8080"
    },
    "visibility": "public"
  }'

Tier Limits: Deployment creation is subject to tier limits when billing is enabled:

Free: 1 deployment
Business: 10 deployments
Enterprise: Unlimited

If the limit is reached, the API returns 403 Forbidden.

Get Deployment Status

GET /api/deployments/status?name={deploymentName}

Get the current status of a deployment, including ingress endpoints if ready. Query Parameters:

string

required

Deployment name

Response:

string

Current status

boolean

Whether the deployment is ready to receive traffic

boolean

Whether the deployment can be deleted

boolean

Whether a new deployment request is allowed

array

Array of ingress endpoints (only when ready)

string

Additional status information or error message

Example:

curl -X GET "https://your-domain.com/api/deployments/status?name=abc123xyz7" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "Ready",
  "deploymentReady": true,
  "allowDelete": true,
  "allowRequest": false,
  "ingresses": [
    {
      "id": "nginx",
      "name": "nginx",
      "host": "abc123xyz7.yourdomain.com",
      "url": "https://abc123xyz7.yourdomain.com"
    }
  ]
}

Delete Deployment

POST /api/deployments/delete

Delete a deployment. This marks the UserDeployment CR’s desiredState as deleted, and the operator handles cleanup via finalizers. Authentication: Required (deployments:write scope) Request Body:

string

required

Name of the deployment to delete

Response: Redirects to deployments page (for form POST) or returns JSON success Example:

curl -X POST "https://your-domain.com/api/deployments/delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_name": "abc123xyz7"}'

Notes:

The API verifies deployment ownership before deletion
Deployment secrets are automatically cleaned up
Kubernetes resources are removed by the operator
Deletion is recorded in billing events

Restart Deployment

POST /api/deployments/restart

Restart all pods in a deployment by adding a restart annotation. Request Body:

string

required

Name of the deployment to restart

Response: 200 OK Example:

curl -X POST "https://your-domain.com/api/deployments/restart" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_name": "abc123xyz7"}'

Deploy Raw Image

POST /api/deployments/deploy-image

Deploy a raw container image without requiring a pre-existing template. Useful for custom images or CI/CD pipelines. Request Body:

string

required

Container image (e.g., nginx:latest, myregistry.com/app:v1.2.3)

string

Custom deployment name (auto-generated if not provided)

integer

Port the container listens on (default: 8080)

object

Environment variables as key-value pairs

string

Visibility: public or internal (default: public)

Response: 201 Created Example:

curl -X POST "https://your-domain.com/api/deployments/deploy-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "myapp:v1.0.0",
    "containerPort": 3000,
    "envVars": {
      "NODE_ENV": "production",
      "PORT": "3000"
    }
  }'

Get Deployment Configuration

GET /api/deployments/config?name={deploymentName}

Retrieve the configuration for a deployment, including environment variables. Query Parameters:

string

required

Deployment name

Response:

object

Key-value pairs of environment variables

Update Deployment Configuration

PUT /api/deployments/config

Update environment variables for a deployment. This triggers a pod restart. Request Body:

string

required

Deployment name

object

required

New environment variables (replaces existing)

Response: 200 OK Example:

curl -X PUT "https://your-domain.com/api/deployments/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "abc123xyz7",
    "configData": {
      "PORT": "8080",
      "DEBUG": "true"
    }
  }'

Deployment Logs

Get Deployment Logs

GET /api/deployments/{name}/logs

Retrieve container logs from a deployment. Path Parameters:

string

required

Deployment name

Query Parameters:

string

Service name for multi-service deployments (default: first service)

integer

Number of recent lines to return (default: 100)

boolean

Stream logs in real-time (default: false)

Response:

string

Container logs

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/logs?tail=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Stream Deployment Logs

GET /api/deployments/{name}/logs/stream

Stream container logs in real-time using Server-Sent Events (SSE). Path Parameters:

string

required

Deployment name

Query Parameters:

string

Service name for multi-service deployments

Response: text/event-stream Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/logs/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

Deployment Metrics

Get Deployment Metrics

GET /api/deployments/{name}/metrics

Retrieve CPU and memory metrics for a deployment. Path Parameters:

string

required

Deployment name

Query Parameters:

string

Service name for multi-service deployments

Response:

string

CPU usage in millicores (e.g., “150m”)

string

Memory usage in bytes (e.g., “256Mi”)

string

ISO 8601 timestamp of measurement

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "cpuUsage": "150m",
  "memoryUsage": "256Mi",
  "timestamp": "2024-03-05T10:30:00Z"
}

Deployment History

Get Deployment History

GET /api/deployments/{name}/history

Retrieve deployment revision history (configuration changes, restarts, etc.). Path Parameters:

string

required

Deployment name

Response:

array

Array of revision objects

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Auto-Update Configuration

Get Auto-Update Settings

GET /api/deployments/auto-update?name={deploymentName}

Retrieve auto-update configuration for a deployment. Response:

boolean

Whether auto-update is enabled

string

Update strategy (e.g., “rolling”, “recreate”)

Update Auto-Update Settings

PUT /api/deployments/auto-update

Configure auto-update settings for a deployment. Request Body:

string

required

Deployment name

boolean

required

Enable or disable auto-updates

string

Update strategy: rolling or recreate

Response: 200 OK Example:

curl -X PUT "https://your-domain.com/api/deployments/auto-update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "abc123xyz7",
    "enabled": true,
    "strategy": "rolling"
  }'

Deployment Events

Get Deployment Events

GET /api/deployments/{name}/events

Retrieve Kubernetes events for a deployment (useful for debugging). Path Parameters:

string

required

Deployment name

Response:

array

Array of Kubernetes event objects

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All deployment endpoints may return the following errors:

string

Human-readable error message

Common Error Codes

400 Bad Request - Missing or invalid parameters
403 Forbidden - Deployment limit reached or ownership verification failed
404 Not Found - Deployment does not exist
409 Conflict - Deployment name already exists
500 Internal Server Error - Kubernetes API error or database failure
503 Service Unavailable - Operator not available

Getting Started

Core Concepts

Components

Deployment

API Reference

Deployment Operations

List Deployments

Create Deployment

Get Deployment Status

Delete Deployment

Restart Deployment

Deploy Raw Image

Get Deployment Configuration

Update Deployment Configuration

Deployment Logs

Get Deployment Logs

Stream Deployment Logs

Deployment Metrics

Get Deployment Metrics

Deployment History

Get Deployment History

Auto-Update Configuration

Get Auto-Update Settings

Update Auto-Update Settings

Deployment Events

Get Deployment Events

Error Responses

Common Error Codes

​Deployment Operations

​List Deployments

​Create Deployment

​Get Deployment Status

​Delete Deployment

​Restart Deployment

​Deploy Raw Image

​Get Deployment Configuration

​Update Deployment Configuration

​Deployment Logs

​Get Deployment Logs

​Stream Deployment Logs

​Deployment Metrics

​Get Deployment Metrics

​Deployment History

​Get Deployment History

​Auto-Update Configuration

​Get Auto-Update Settings

​Update Auto-Update Settings

​Deployment Events

​Get Deployment Events

​Error Responses

​Common Error Codes

Deployment Operations

List Deployments

Create Deployment

Get Deployment Status

Delete Deployment

Restart Deployment

Deploy Raw Image

Get Deployment Configuration

Update Deployment Configuration

Deployment Logs

Get Deployment Logs

Stream Deployment Logs

Deployment Metrics

Get Deployment Metrics

Deployment History

Get Deployment History

Auto-Update Configuration

Get Auto-Update Settings

Update Auto-Update Settings

Deployment Events

Get Deployment Events

Error Responses

Common Error Codes