Upgrading the OPA

The latest agent versions are available in the agent GitHub repository. Follow the instructions below to upgrade the agent based on your deployment method.

Terraform

Bump the version tag on the superblocks_agent_image variable in your agent's Terraform file.

AWS ECS Fargate

superblocks_agent_image = "ghcr.io/superblocksteam/agent:<VERSION>"

Google Cloud Run

superblocks_agent_image = "gcr.io/superblocks-registry/superblocks/agent:<VERSION>"

Helm

Fetch the latest chart.

helm repo update

Redeploy the chart.

helm upgrade -i -n superblocks superblocks-agent superblocks/superblocks-agent \
  --create-namespace \
  -f values.yaml \
  --set superblocks.agentKey="<YOUR_AGENT_KEY>" \

Docker

Download the agent's latest Docker Compose file and redeploy. To specify a version, set SUPERBLOCKS_DOCKER_AGENT_TAG. Otherwise the latest version is used by default.

curl -s https://raw.githubusercontent.com/superblocksteam/agent/main/docker/v2.compose.yaml | \
SUPERBLOCKS_AGENT_KEY="<YOUR_AGENT_KEY>" \
SUPERBLOCKS_AGENT_HOST_URL="<YOUR_AGENT_URL>" \
SUPERBLOCKS_DOCKER_AGENT_TAG="<VERSION>" \
docker compose -p superblocks -f - up

Upgrading from version 0.x.x to 1.x.x

Agent version 1.x.x is a major upgrade that enables support for Control Blocks. To upgrade from version 0.x.x to 1.x.x, follow the instructions below.

Terraform

Delete your old deployment and deploy the latest Superblocks Terraform module for AWS or Google Cloud. Note, the version is now "~>1.0".

For the Terraform AWS ECS Fargate deployment, also see the changes in the migration guide here and update any affected variables.

ECS standalone task

If you manage your agent as a standalone ECS task (not using the Superblocks Terraform module), edit the task definition JSON directly so the image is ghcr.io/superblocksteam/agent:latest or the latest version of agent v1.x.x (see releases). Replace your existing environment variables with the ones below:

Environment variables

environment: [
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_LOG_LEVEL", 
    "value" : "info" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_HTTP_PORT",
    "value" : "<CONTAINER_PORT>" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_GRPC_MSG_RES_MAX",
    "value" : "100000000" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_GRPC_MSG_REQ_MAX", 
    "value" : "30000000" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_URL", 
    "value" : https://api.superblocks.com 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_TIMEOUT",
    "value" : "10000000000" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_OTEL_COLLECTOR_HTTP_URL", 
    "value" : https://traces.intake.superblocks.com:443/v1/traces 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_EMITTER_REMOTE_INTAKE", 
    "value" : https://logs.intake.superblocks.com 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_INTAKE_METADATA_URL", 
    "value" : https://metadata.intake.superblocks.com 
  },
  { 
    "name" : "SUPERBLOCKS_AGENT_KEY", 
    "value" : "<YOUR_AGENT_KEY>" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_KEY",
    "value" : "<YOUR_AGENT_KEY>" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_FILE_SERVER_URL",
    "value" : http://127.0.0.1:8020/v2/files 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_AGENT_HOST_URL", 
    "value" : "<YOUR_AGENT_URL>" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_AGENT_TAGS", 
    "value" : "profile:<VALUE>" 
  },
  { 
    "name" : "SUPERBLOCKS_ORCHESTRATOR_DATA_DOMAIN", 
    "value" : "app.superblocks.com"  
  },
  {
    "name" : "SUPERBLOCKS_ORCHESTRATOR_HANDLE_CORS",
    "value" : "true" 
  },
  {
    "name" : "SUPERBLOCKS_ORCHESTRATOR_QUOTAS_DEFAULT_API_TIMEOUT", 
    "value": "600000"
  }
]

info

Be sure to update the following variables with your values:

• SUPERBLOCKS_ORCHESTRATOR_HTTP_PORT
• SUPERBLOCKS_AGENT_KEY and SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_KEY
• SUPERBLOCKS_ORCHESTRATOR_AGENT_HOST_URL
• SUPERBLOCKS_ORCHESTRATOR_AGENT_TAGS

If using the Superblocks EU instance, also update SUPERBLOCKS_ORCHESTRATOR_DATA_DOMAIN to use eu.superblocks.com.

In addition, set your ALB target group's health check path to /health.

Helm

Ensure your Helm chart matches the v2 Helm chart configuration. Follow the migration guide here for changes from the v1 chart.

Docker

Use the v2 Docker Compose file and redeploy.

Once deployed, you can check the agent is running at https://<AGENT_HOST_URL>/health.

Upgrading from version < 0.69.0

Agent version 0.69.0 introduced a single container architecture, making it simpler to manage and scale. Specifically, the agent now runs as one container image, ghcr.io/superblocksteam/agent. The following containers used in versions < 0.69.0 have been removed:

• ghcr.io/superblocksteam/agent-controller
• ghcr.io/superblocksteam/agent-worker
• ghcr.io/superblocksteam/agent-worker-python

If upgrading from a version below 0.69.0, be sure your agent configuration no longer references these containers and removes any autoscaling associated with them. Your agent configuration should match the latest Docker Compose file or Helm chart, depending on your deployment method.