AWS Deployment — ECS Express Mode¶

AgentCube connectors deploy on AWS using ECS Express Mode — the recommended approach for container deployments on AWS. A single command provisions the ECS service on Fargate, an Application Load Balancer, auto-scaling, and networking automatically. No separate ALB, target group, or certificate management is required.

Prerequisites¶

• AWS account with permissions to manage ECS, IAM, and Secrets Manager
• AWS CLI installed and configured (aws configure)
• Default VPC with at least two public subnets across two Availability Zones
• A registered domain name (recommended for a stable connector URL)

See Container Images & Specifications for image names, GHCR authentication, and resource requirements.

Step 1: Create the Required IAM Roles¶

ECS Express Mode requires two IAM roles — one for task execution (image pull, logging, secrets) and one that allows ECS to manage the underlying infrastructure (ALB, auto-scaling, networking) on your behalf.

Task Execution Role¶

aws iam create-role \
  --role-name ecsTaskExecutionRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ecs-tasks.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy \
  --role-name ecsTaskExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

Infrastructure Role¶

aws iam create-role \
  --role-name ecsInfrastructureRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ecs.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy \
  --role-name ecsInfrastructureRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonECSInfrastructureRoleforExpressGatewayServices

Step 2: Store Credentials in Secrets Manager¶

Store the Oracle backend password and GitHub Container Registry credentials rather than passing them as plaintext environment variables.

Oracle backend password¶

aws secretsmanager create-secret \
  --name agentcube/essbase-password \
  --secret-string "{password}" \
  --region {region}

GHCR pull credentials¶

ECS requires registry credentials to pull from ghcr.io. Create a GitHub Personal Access Token with read:packages scope, then store it:

aws secretsmanager create-secret \
  --name agentcube/ghcr-credentials \
  --secret-string '{"username":"{github_username}","password":"{github_pat}"}' \
  --region {region}

Note the ARNs returned for both secrets — you will reference them in the next step.

Step 3: Deploy with ECS Express Mode¶

The following single command provisions the ECS service, ALB, HTTPS endpoint, and auto-scaling:

aws ecs create-express-gateway-service \
  --service-name agentcube-essbase \
  --execution-role-arn arn:aws:iam::{account_id}:role/ecsTaskExecutionRole \
  --infrastructure-role-arn arn:aws:iam::{account_id}:role/ecsInfrastructureRole \
  --primary-container \
    image=ghcr.io/caprusai/agentcube-essbase:{version},\
    containerPort=8080,\
    repositoryCredentials={credentialsParameter=arn:aws:secretsmanager:{region}:{account_id}:secret:agentcube/ghcr-credentials},\
    environment=[{name=ESSBASE_SERVER_URL,value=https://{essbase_host}},{name=ESSBASE_USERNAME,value={username}}],\
    secrets=[{name=ESSBASE_PASSWORD,valueFrom=arn:aws:secretsmanager:{region}:{account_id}:secret:agentcube/essbase-password}] \
  --cpu 256 \
  --memory 512 \
  --health-check-path /health \
  --scaling-target minTaskCount=1,maxTaskCount=4 \
  --region {region}

AWS returns a service ARN and a public HTTPS endpoint URL (servicename.ecs.{region}.on.aws). The connector is accessible at that URL within a few minutes.

Step 4: Configure a Custom Domain (Optional)¶

The AWS-provided URL works immediately with HTTPS. To use your own domain:

1. Request an ACM certificate for your domain in the same region:

   aws acm request-certificate \
     --domain-name {connector_hostname} \
     --validation-method DNS \
     --region {region}
   

2. Add the DNS validation records provided by ACM to your DNS provider. Wait until status shows ISSUED:

   aws acm describe-certificate \
     --certificate-arn {certificate_arn} \
     --query 'Certificate.Status' \
     --region {region}
   

3. In the AWS Console, navigate to ECS → Services → agentcube-essbase → Resources → Load Balancer → Listener → Edit. Add your ACM certificate and a Host header condition for your domain.

4. Create a Route 53 alias record pointing to the ALB DNS name:

   aws route53 change-resource-record-sets \
     --hosted-zone-id {hosted_zone_id} \
     --change-batch '{
       "Changes": [{
         "Action": "CREATE",
         "ResourceRecordSet": {
           "Name": "{connector_hostname}",
           "Type": "A",
           "AliasTarget": {
             "HostedZoneId": "{alb_hosted_zone_id}",
             "DNSName": "{alb_dns_name}",
             "EvaluateTargetHealth": true
           }
         }
       }]
     }'
   

Step 5: Verify¶

curl https://{connector_hostname}/health

See Verification for the expected response and full verification checklist.