Concepts
Operations

Operations

An Operation represents an asynchronous action performed on a deployment or other resource. Operations track the progress of deployments, destructions, and other long-running tasks.

What is an Operation?

Operations are created when you perform actions that take time to complete:

  • Creating a deployment
  • Destroying a deployment
  • Syncing DAGs from GitHub
  • Provisioning user

Each operation has:

  • ID - Unique identifier (format: op_...)
  • Type - Operation type (e.g., deployment.create)
  • Status - Current status
  • Progress - Phase and message
  • Resource - Linked resource (deployment, etc.)
  • Timestamps - Requested, started, ended

Operation Statuses

Operations have the following statuses:

  • queued - Operation is queued and waiting to start
  • running - Operation is currently executing
  • succeeded - Operation completed successfully
  • failed - Operation failed
  • canceled - Operation was canceled

Terminal vs Non-Terminal States

Terminal States

These states indicate the operation will not change:

  • succeeded - Operation completed successfully
  • failed - Operation failed
  • canceled - Operation was canceled

Non-Terminal States

These states indicate the operation is still in progress:

  • queued - Waiting to start
  • running - Currently executing

Polling Patterns

Since operations are asynchronous, you need to poll for status updates.

Basic Polling

Poll the operation endpoint until it reaches a terminal state:

# Get operation status
onvera ops get op_660e8400-e29b-41d4-a716-446655440001

CLI Polling

The CLI automatically polls for you:

# Deploy command polls automatically
onvera deploy superset

The CLI polls every 2 seconds and shows progress updates.

API Polling

Using the API, poll the operation endpoint:

# Poll operation status
curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001

Polling interval: Poll every 2-5 seconds. Don't poll too frequently to avoid rate limits.

Operation Progress

Operations include progress information:

  • Phase - Current phase (e.g., provisioning_db, provisioning_infrastructure)
  • Message - Human-readable message describing current state

Example progress:

Phase: provisioning_db
Message: Provisioning database

Operation Types

Common operation types:

  • deployment.create - Creating a deployment
  • deployment.destroy - Destroying a deployment
  • dag_sync.trigger - Syncing DAGs from GitHub
  • app_user.provision - Provisioning a user in an application

Resources vs Operations

Resources

Resources are the entities you manage:

  • Deployments - Application instances
  • Operations - Async actions (also resources themselves)

Operations

Operations track actions on resources:

  • Creating a deployment → deployment.create operation
  • Destroying a deployment → deployment.destroy operation

Key distinction: Resources are the "things" you manage. Operations are the "actions" you perform on them.

Example: Deployment Flow

  1. Create deployment:
onvera deploy superset

Returns:

  • deployment_id: dep_550e8400-e29b-41d4-a716-446655440000
  • operation_id: op_660e8400-e29b-41d4-a716-446655440001
  1. Poll operation:
onvera ops get op_660e8400-e29b-41d4-a716-446655440001

Shows:

  • Status: running
  • Phase: provisioning_db
  • Message: Provisioning database
  1. Continue polling until terminal state:
  • Status: succeeded → Deployment is ready
  • Status: failed → Check error message

Best Practices

  1. Always store the operation_id when creating resources
  2. Poll until terminal state - Don't assume immediate completion
  3. Handle failures gracefully - Check error messages
  4. Respect rate limits - Don't poll too frequently
  5. Use exponential backoff for retries

Related Concepts

DeploymentsAuthentication