Satellite on ECS - ResolveAI

Deploy the Resolve Satellite on AWS ECS Fargate using CloudFormation. The satellite runs in your AWS environment and securely connects to Resolve SaaS to provide alert investigation, monitoring, and integration capabilities.

For Kubernetes-based deployments, see Resolve Satellite.

Architecture

Compute: ECS Fargate (serverless containers)
Networking: Runs in your VPC with configurable subnets and security groups
Storage: Optional EFS volume for Git integration persistence
Secrets: AWS Secrets Manager for credentials
Logging: CloudWatch Logs

Installation

Step 1: Prepare Resources

Gather the following information before deployment. See Resource Setup Reference below for how to create each resource.

Parameter	Description	Example
`IngestTokenSecretArn`	ARN of ingest token secret	`arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/ingest-token-AbCdEf`
`ExecutionRoleArn`	ARN of ECS task execution role	`arn:aws:iam::123456789:role/resolveSatelliteRole`
`TaskRoleArn`	ARN of ECS task role (can be the same as execution role)	`arn:aws:iam::123456789:role/resolveSatelliteRole`
`EcsClusterArn`	ARN of ECS cluster	`arn:aws:ecs:us-east-1:123456789:cluster/my-cluster`
`SecurityGroupId`	Security group ID	`sg-0a1b2c3d`
`SubnetIds`	Comma-separated subnet IDs	`subnet-abc123,subnet-def456`
`VpcId`	VPC ID (only if `EnableGitVolume=true`)	`vpc-12345678`
`SatelliteName`	Name for this satellite	`my-satellite`

At least one integration must be configured for the satellite to appear in the Resolve UI.

Step 2: Deploy with CloudFormation

AWS Console
AWS CLI

Deploy directly from the AWS CloudFormation console by clicking Launch Stack. Fill in the required parameters in the form.

Click Launch Stack above (opens AWS CloudFormation console)
Choose your preferred Region in the top-right corner of the console
Fill in the required parameters from Step 1
Configure the IntegrationsConfig parameter with your integration YAML (see Integrations Configuration for examples)
Click Next through the remaining pages, then Submit

The Launch Stack button uses the latest template version. To deploy a specific version, replace latest in the template URL with a version number (e.g., v1.1.22).

For automated or CI/CD deployments, use the AWS CLI.Download the CloudFormation template:

curl -o satellite.yaml https://resolve-satellite-cloudformation.s3.us-east-2.amazonaws.com/releases/latest/satellite.yaml

To pin a specific version, replace latest with a version number: https://resolve-satellite-cloudformation.s3.us-east-2.amazonaws.com/releases/v1.1.22/satellite.yaml

Deploy the stack:

aws cloudformation deploy \
  --template-file satellite.yaml \
  --stack-name resolve-satellite \
  --region us-east-1 \
  --parameter-overrides \
    IngestTokenSecretArn=arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/ingest-token-AbCdEf \
    ExecutionRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    TaskRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    EcsClusterArn=arn:aws:ecs:us-east-1:123456789:cluster/resolve-satellite-cluster \
    SecurityGroupId=sg-0a1b2c3d \
    SubnetIds=subnet-abc123,subnet-def456 \
    SatelliteName=my-satellite \
    EnableGitVolume=true \
    VpcId=vpc-12345678 \
    IntegrationsConfig="git:
  type: git
  create: true
  connection:
    authConfigs:
      myrepos:
        type: github"

aws cloudformation deploy \
  --template-file satellite.yaml \
  --stack-name resolve-satellite \
  --region us-east-1 \
  --parameter-overrides \
    IngestTokenSecretArn=arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/ingest-token-AbCdEf \
    ExecutionRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    TaskRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    EcsClusterArn=arn:aws:ecs:us-east-1:123456789:cluster/resolve-satellite-cluster \
    SecurityGroupId=sg-0a1b2c3d \
    SubnetIds=subnet-abc123,subnet-def456 \
    SatelliteName=my-satellite \
    EnableGitVolume=true \
    VpcId=vpc-12345678 \
    IntegrationsConfig="git:
  type: git
  create: true
  secretName: arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/git-credentials-XyZ123
  connection:
    authConfigs:
      myrepos:
        type: token
        tokenAuthRemoteURLs:
          - https://github.com/your-org/repo-1.git
          - https://github.com/your-org/repo-2.git"

aws cloudformation deploy \
  --template-file satellite.yaml \
  --stack-name resolve-satellite \
  --region us-east-1 \
  --parameter-overrides \
    IngestTokenSecretArn=arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/ingest-token-AbCdEf \
    ExecutionRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    TaskRoleArn=arn:aws:iam::123456789:role/resolveSatelliteRole \
    EcsClusterArn=arn:aws:ecs:us-east-1:123456789:cluster/resolve-satellite-cluster \
    SecurityGroupId=sg-0a1b2c3d \
    SubnetIds=subnet-abc123,subnet-def456 \
    SatelliteName=my-satellite \
    EnableGitVolume=true \
    VpcId=vpc-12345678 \
    IntegrationsConfig="datadog:
  type: datadog
  create: true
  secretName: arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/datadog-credentials-Abc123
  connection:
    site: datadoghq.com

git:
  type: git
  create: true
  connection:
    authConfigs:
      myrepos:
        type: github"

GitHub App auth does not require a Git credentials secret. After deployment, open your Git integration in the Resolve UI and click Install GitHub App to complete authorization.

Resolve Satellite supports additional integrations including Grafana, Prometheus, Loki, Elasticsearch, Splunk, Kubernetes, AWS CloudWatch, and more. For the full list of integration types and their configuration schemas, see Reference Schema.

Step 3: Monitor Deployment

The deployment typically takes 3-5 minutes.

# Check stack status
aws cloudformation describe-stacks \
  --stack-name resolve-satellite \
  --query 'Stacks[0].StackStatus'

# Get service name from stack outputs
SERVICE_NAME=$(aws cloudformation describe-stacks \
  --stack-name resolve-satellite \
  --query 'Stacks[0].Outputs[?OutputKey==`ServiceName`].OutputValue' \
  --output text)

# Check service status
aws ecs describe-services \
  --cluster resolve-satellite-cluster \
  --services $SERVICE_NAME

Resource Setup Reference

The CloudFormation template does not create the following resources. They must exist before deployment.

1. IAM Role

The satellite needs an IAM role with the ecs-tasks.amazonaws.com trust policy. You can use a single role for both ExecutionRoleArn and TaskRoleArn by combining all required permissions into one role. Trust Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Required Managed Policies:

arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

Required Inline Policies: Secrets Manager access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": ["arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:resolve/satellite/*"]
    }
  ]
}

EFS access (only if using Git integration):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite"],
      "Resource": "arn:aws:elasticfilesystem:REGION:ACCOUNT_ID:file-system/*"
    }
  ]
}

If your organization requires separate permission boundaries, you can create two roles — one for task execution (image pull, secrets, logs) and one for task runtime (EFS access) — and pass them as different ExecutionRoleArn and TaskRoleArn values.

AWS CLI commands to create the role

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

# Attach managed policy
aws iam attach-role-policy \
  --role-name resolveSatelliteRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

# Add Secrets Manager permissions
aws iam put-role-policy \
  --role-name resolveSatelliteRole \
  --policy-name SecretsManagerAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": ["arn:aws:secretsmanager:*:*:secret:resolve/satellite/*"]
    }]
  }'

# Add EFS permissions (only if using Git integration)
aws iam put-role-policy \
  --role-name resolveSatelliteRole \
  --policy-name EFSAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "elasticfilesystem:ClientMount",
        "elasticfilesystem:ClientWrite"
      ],
      "Resource": "arn:aws:elasticfilesystem:*:*:file-system/*"
    }]
  }'

2. AWS Secrets Manager Secrets

A. Ingest Token (Required)

The ingest token authenticates your satellite with Resolve SaaS. Generate it from Resolve UI > Admin > Tokens. Store the token value as a plaintext string — no JSON wrapping required.

aws secretsmanager create-secret \
  --name resolve/satellite/ingest-token \
  --description "Resolve Satellite ingest token" \
  --secret-string 'YOUR_TOKEN_FROM_RESOLVE_UI'

Note the ARN after creation (format: arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:resolve/satellite/ingest-token-XXXXX). You will need it for deployment.

B. Git Integration Credentials (Token Auth Only)

Required only if using Git integration with token-based auth. GitHub App auth does not require a secret — it is configured through the Resolve UI after deployment. Creating a personal access token: see Creating access tokens for step-by-step token setup for each provider (GitHub, GitLab, and others). Then store the credentials in the secret below.

{
  "tokenAuthCredentials": {
    "myrepos": {
      "username": "your-username",
      "token": "your-personal-access-token"
    }
  }
}

aws secretsmanager create-secret \
  --name resolve/satellite/git-credentials \
  --description "Git integration credentials" \
  --secret-string file://git-credentials.json

C. Datadog Integration Credentials (Optional)

Required only if using Datadog integration.

{
  "apiKey": "your-datadog-api-key",
  "appKey": "your-datadog-app-key"
}

aws secretsmanager create-secret \
  --name resolve/satellite/datadog-credentials \
  --description "Datadog integration credentials" \
  --secret-string '{"apiKey":"YOUR_API_KEY","appKey":"YOUR_APP_KEY"}'

3. Network Infrastructure

VPC Requirements

DNS Resolution: Must be enabled (enableDnsSupport: true)
DNS Hostnames: Must be enabled (enableDnsHostnames: true)
Internet Access: Required for communication with Resolve SaaS

# Verify VPC DNS settings
aws ec2 describe-vpc-attribute --vpc-id vpc-xxxxx --attribute enableDnsSupport
aws ec2 describe-vpc-attribute --vpc-id vpc-xxxxx --attribute enableDnsHostnames

Subnets

Minimum: 2 subnets (recommended for high availability)
Type: Private subnets with NAT Gateway, or public subnets with auto-assign public IP
Internet Access: Must have route to internet (via NAT Gateway or Internet Gateway)

Security Group

Create a security group for the satellite tasks. Required Egress Rules:

HTTPS (port 443) to Resolve SaaS
HTTPS (port 443) to integration endpoints (Datadog, Grafana, etc.)
If using Git with EFS: NFS (port 2049) to EFS security group

aws ec2 create-security-group \
  --group-name resolve-satellite-sg \
  --description "Security group for Resolve Satellite" \
  --vpc-id vpc-xxxxx

4. ECS Cluster

You must have an existing ECS cluster. The satellite will be deployed as a Fargate service.

aws ecs describe-clusters --clusters your-cluster-name

Configuration Reference

Required Parameters

Parameter	Description
`IngestTokenSecretArn`	ARN of Secrets Manager secret containing ingest token
`ExecutionRoleArn`	ARN of ECS task execution role
`TaskRoleArn`	ARN of ECS task role (can be the same as execution role)
`EcsClusterArn`	ARN of ECS cluster
`SecurityGroupId`	Security group ID for satellite tasks
`SubnetIds`	Comma-separated list of subnet IDs
`SatelliteName`	Name for this satellite instance

Optional Parameters

Parameter	Default	Description
`Image`	`resolveaihq/satellite`	Container image repository
`ImageTag`	`latest`	Container image tag
`LogLevel`	`info`	Log level (`debug`, `info`, `warn`, `error`)
`Cpu`	`1024`	CPU units (1024 = 1 vCPU)
`Memory`	`8192`	Memory in MB
`DesiredCount`	`1`	Number of tasks to run
`AssignPublicIp`	`DISABLED`	Assign public IP (`ENABLED` for public subnets without NAT)
`EnableGitVolume`	`false`	Enable EFS volume for Git integration
`IntegrationsConfig`	`""`	YAML configuration for integrations

Git Volume (EFS)

When EnableGitVolume=true, the CloudFormation template automatically creates:

EFS Filesystem: Encrypted, generalPurpose performance mode
EFS Security Group: Allows NFS (port 2049) traffic from satellite tasks
EFS Access Point: Isolated path /git with POSIX UID/GID 1000
EFS Mount Targets: One per subnet (takes 2-3 minutes to become available)

Additional Parameters

Parameter	Required	Default	Description
`VpcId`	Yes	-	VPC ID for EFS security group
`EfsPerformanceMode`	No	`generalPurpose`	EFS performance mode
`EfsThroughputMode`	No	`bursting`	EFS throughput mode

Cost Considerations

EFS Standard storage: ~$0.30/GB/month (pay only for actual usage)
No provisioned capacity needed
Bursting throughput included at no extra cost

Integrations Configuration

The IntegrationsConfig parameter accepts YAML configuration for integrations. All credentials must be stored in AWS Secrets Manager.

Git Integration

Git integration requires EFS volume for repository storage (EnableGitVolume=true).

GitHub App
Token auth

No credentials secret needed. Auth is configured through the Resolve UI after deployment.

git:
  type: git
  create: true
  connection:
    authConfigs:
      myrepos:
        type: github

Requires a credentials secret in AWS Secrets Manager (see Resource Setup Reference).

git:
  type: git
  create: true
  secretName: arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/git-credentials
  connection:
    authConfigs:
      myrepos:
        type: token
        tokenAuthRemoteURLs:
          - "https://github.com/your-org/repo-1.git"
          - "https://github.com/your-org/repo-2.git"

For detailed Git integration configuration including auth options, write/remediation behavior, and token setup, see Git on Satellite.

Datadog Integration

datadog:
  type: datadog
  create: true
  secretName: arn:aws:secretsmanager:us-east-1:123456789:secret:resolve/satellite/datadog-credentials
  connection:
    site: datadoghq.com

Supported sites: datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ddog-gov.com

Additional Integrations

Resolve Satellite supports many additional integrations including Grafana, Prometheus, Loki, Elasticsearch, Splunk, Kubernetes, AWS CloudWatch, and more. For complete integration schemas and configuration examples, see Reference Schema.

Verification

1. Check Task is Running

aws ecs list-tasks \
  --cluster resolve-satellite-cluster \
  --service-name resolve-satellite-my-satellite \
  --desired-status RUNNING

# Get task details
aws ecs describe-tasks \
  --cluster resolve-satellite-cluster \
  --tasks TASK_ARN

Task should be in RUNNING state with lastStatus: RUNNING.

2. Check CloudWatch Logs

LOG_GROUP=$(aws cloudformation describe-stacks \
  --stack-name resolve-satellite \
  --query 'Stacks[0].Outputs[?OutputKey==`LogGroupName`].OutputValue' \
  --output text)

aws logs tail $LOG_GROUP --follow

Expected log messages:

Satellite starting...
Connected to Resolve SaaS
Integration [name] initialized
Health check passed

3. Check Satellite in Resolve UI

Log in to Resolve UI
Navigate to Admin > Satellites
Verify your satellite appears with status “Connected”

4. Test Health Check

TASK_ARN=$(aws ecs list-tasks \
  --cluster resolve-satellite-cluster \
  --service-name resolve-satellite-my-satellite \
  --query 'taskArns[0]' \
  --output text)

TASK_IP=$(aws ecs describe-tasks \
  --cluster resolve-satellite-cluster \
  --tasks $TASK_ARN \
  --query 'tasks[0].attachments[0].details[?name==`privateIPv4Address`].value' \
  --output text)

# From a host in the same VPC
curl http://$TASK_IP:13131/live

Expected: HTTP 200 OK

5. Verify EFS Mount (if using Git integration)

# Enable ECS Exec (one-time setup)
aws ecs update-service \
  --cluster resolve-satellite-cluster \
  --service resolve-satellite-my-satellite \
  --enable-execute-command

# Exec into container
aws ecs execute-command \
  --cluster resolve-satellite-cluster \
  --task TASK_ARN \
  --container satellite \
  --interactive \
  --command "/bin/sh"

# Inside container, check mount
df -h | grep /integrationData/git
ls -la /integrationData/git

Updating the Satellite

Update to New Version

aws cloudformation deploy \
  --template-file satellite.yaml \
  --stack-name resolve-satellite \
  --parameter-overrides \
    ImageTag=v1.2.3 \
    # ... other parameters remain the same

CloudFormation performs a rolling update with zero downtime (if DesiredCount > 1).

Add Git Integration to Existing Deployment

aws cloudformation deploy \
  --template-file satellite.yaml \
  --stack-name resolve-satellite \
  --parameter-overrides \
    EnableGitVolume=true \
    VpcId=vpc-xxxxx \
    IntegrationsConfig="..." \
    # ... other parameters remain the same

This creates new EFS resources and restarts the task.

Deleting the Satellite

Delete CloudFormation Stack

aws cloudformation delete-stack --stack-name resolve-satellite

# Wait for deletion to complete
aws cloudformation wait stack-delete-complete \
  --stack-name resolve-satellite

The EFS filesystem has DeletionPolicy: Retain to prevent accidental data loss. After deleting the stack, delete the EFS filesystem manually if no longer needed:

aws efs delete-file-system --file-system-id fs-xxxxx

Cleanup IAM Roles and Secrets

IAM roles and Secrets Manager secrets are not managed by the CloudFormation stack. Delete them manually if no longer needed:

# Delete secrets
aws secretsmanager delete-secret \
  --secret-id resolve/satellite/ingest-token \
  --force-delete-without-recovery

# Delete role (detach policies first)
aws iam delete-role --role-name resolveSatelliteRole

Troubleshooting

Task Fails to Start

Task transitions from PENDING to STOPPED immediately.

Cause	Resolution
Invalid Secrets ARN	Verify secret exists: `aws secretsmanager describe-secret --secret-id SECRET_ARN`
Insufficient IAM permissions	Verify role has Secrets Manager access
Image pull failure	Verify image is accessible: `docker pull resolveaihq/satellite:latest`
No internet access	Verify subnet route table has NAT Gateway or Internet Gateway

EFS Mount Fails

Task logs show Failed to mount EFS or health check never passes.

Cause	Resolution
Mount targets not ready	Wait 2-3 minutes after stack creation. Check status: `aws efs describe-mount-targets --file-system-id fs-xxxxx`
Security group blocking NFS	Check EFS security group allows port 2049 from satellite security group
Role missing EFS permissions	Verify role has `elasticfilesystem:ClientMount` and `ClientWrite`
VPC DNS not enabled	Verify VPC has DNS resolution and hostnames enabled

Satellite Not Appearing in Resolve UI

Task is running but satellite doesn’t show as connected.

Cause	Resolution
Invalid ingest token	Verify token value in Secrets Manager matches Resolve UI
Network blocked	Verify security group allows outbound HTTPS to Resolve SaaS domain

High Memory Usage

Task getting killed due to OOM (Out of Memory).

Increase Memory parameter (default is 8192 MB)
Review CloudWatch Container Insights metrics

Integration Not Working

Integration appears in UI but queries fail.

Verify secret format matches the expected structure for each integration type
Verify security group allows outbound HTTPS to integration endpoints
For token auth, verify the secret key names match authConfigs key names
Check CloudWatch logs linked from the ECS task for detailed error messages

​Architecture

​Installation

​Step 1: Prepare Resources

​Step 2: Deploy with CloudFormation

​Step 3: Monitor Deployment

​Resource Setup Reference

​1. IAM Role

​2. AWS Secrets Manager Secrets

​A. Ingest Token (Required)

​B. Git Integration Credentials (Token Auth Only)

​C. Datadog Integration Credentials (Optional)

​3. Network Infrastructure

​VPC Requirements

​Subnets

​Security Group

​4. ECS Cluster

​Configuration Reference

​Required Parameters

​Optional Parameters

​Git Volume (EFS)

​Additional Parameters

​Cost Considerations

​Integrations Configuration

​Git Integration

​Datadog Integration

​Additional Integrations

​Verification

​1. Check Task is Running

​2. Check CloudWatch Logs

​3. Check Satellite in Resolve UI

​4. Test Health Check

​5. Verify EFS Mount (if using Git integration)

​Updating the Satellite

​Update to New Version

​Add Git Integration to Existing Deployment

​Deleting the Satellite

​Delete CloudFormation Stack

​Cleanup IAM Roles and Secrets

​Troubleshooting

​Task Fails to Start

​EFS Mount Fails

​Satellite Not Appearing in Resolve UI

​High Memory Usage

​Integration Not Working

Architecture

Installation

Step 1: Prepare Resources

Step 2: Deploy with CloudFormation

Step 3: Monitor Deployment

Resource Setup Reference

1. IAM Role

2. AWS Secrets Manager Secrets

A. Ingest Token (Required)

B. Git Integration Credentials (Token Auth Only)

C. Datadog Integration Credentials (Optional)

3. Network Infrastructure

VPC Requirements

Subnets

Security Group

4. ECS Cluster

Configuration Reference

Required Parameters

Optional Parameters

Git Volume (EFS)

Additional Parameters

Cost Considerations

Integrations Configuration

Git Integration

Datadog Integration

Additional Integrations

Verification

1. Check Task is Running

2. Check CloudWatch Logs

3. Check Satellite in Resolve UI

4. Test Health Check

5. Verify EFS Mount (if using Git integration)

Updating the Satellite

Update to New Version

Add Git Integration to Existing Deployment

Deleting the Satellite

Delete CloudFormation Stack

Cleanup IAM Roles and Secrets

Troubleshooting

Task Fails to Start

EFS Mount Fails

Satellite Not Appearing in Resolve UI

High Memory Usage

Integration Not Working