AWS Setup¶

Configure AWS credentials and permissions for OmniDeploy.

Quick Start with Bootstrap Command¶

The easiest way to set up AWS IAM resources is using the omnideploy bootstrap command:

# Using admin credentials, create policy and group
omnideploy bootstrap run

# Or create a user with access keys
omnideploy bootstrap run --user deployer --create-key

This creates:

OmniDeployPolicy - IAM policy with required permissions
omnideploy-users - IAM group with the policy attached
Optionally, an IAM user with access keys

See Bootstrap Command for details.

Supported Regions¶

LightSail Container Services are available in these regions:

Region	Location
`us-west-2`	Oregon (default)
`us-east-1`	N. Virginia
`us-east-2`	Ohio
`eu-west-1`	Ireland
`eu-west-2`	London
`eu-west-3`	Paris
`eu-central-1`	Frankfurt
`ap-south-1`	Mumbai
`ap-northeast-1`	Tokyo
`ap-northeast-2`	Seoul
`ap-southeast-1`	Singapore
`ap-southeast-2`	Sydney
`ca-central-1`	Canada

Note: us-west-1 (N. California) does NOT support LightSail containers.

Required Permissions¶

OmniDeploy needs permissions for the deployment target and container registry.

LightSail Target¶

Permission	Purpose
`lightsail:CreateContainerService`	Create container service
`lightsail:CreateContainerServiceDeployment`	Deploy containers
`lightsail:GetContainerServices`	Check service status
`lightsail:DeleteContainerService`	Destroy resources
`lightsail:UpdateContainerService`	Update configuration

ECR (Container Registry)¶

Permission	Purpose
`ecr:GetAuthorizationToken`	Authenticate Docker
`ecr:CreateRepository`	Create image repository
`ecr:BatchCheckLayerAvailability`	Push images
`ecr:PutImage`	Push images
`ecr:BatchGetImage`	Pull images

SSM (Secrets)¶

Permission	Purpose
`ssm:GetParameter`	Read secrets
`ssm:PutParameter`	Store secrets (optional)

Creating an IAM User¶

Option 1: Managed Policies (Recommended)¶

Attach AWS-managed policies for simplicity:

Go to IAM Console → Users → Create user
Enter username (e.g., omnideploy)
Select Attach policies directly
Search and attach these managed policies:

Policy	Permissions
`AmazonLightsailFullAccess`	Full LightSail access
`AmazonEC2ContainerRegistryFullAccess`	Full ECR access
`AmazonSSMReadOnlyAccess`	Read SSM parameters

Click Create user
Go to Security credentials → Create access key
Select Command Line Interface (CLI)
Download or copy the access key and secret

Option 2: Custom Policy (Least Privilege)¶

For production, create a custom policy with minimal permissions:

Go to IAM Console → Policies → Create policy
Use this JSON:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LightSailContainers",
      "Effect": "Allow",
      "Action": [
        "lightsail:CreateContainerService",
        "lightsail:CreateContainerServiceDeployment",
        "lightsail:CreateContainerServiceRegistryLogin",
        "lightsail:DeleteContainerService",
        "lightsail:GetContainerServiceDeployments",
        "lightsail:GetContainerServices",
        "lightsail:GetContainerLog",
        "lightsail:RegisterContainerImage",
        "lightsail:UpdateContainerService"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ECR",
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:CreateRepository",
        "ecr:DescribeRepositories"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SSMSecrets",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:GetParameters"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/*"
    }
  ]
}

Name it OmniDeployPolicy
Create IAM user and attach this policy

Option 3: IAM Group (Teams)¶

For teams, use groups:

Create IAM group omnideploy-users
Attach policies to the group
Add users to the group

Configuring Credentials¶

Environment Variables¶

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-west-2"

AWS CLI Profile¶

aws configure --profile omnideploy
# Enter access key, secret, region

export AWS_PROFILE="omnideploy"

Shared Credentials File¶

Add to ~/.aws/credentials:

[omnideploy]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

Add to ~/.aws/config:

[profile omnideploy]
region = us-west-2
output = json

Verify Setup¶

# Check identity
aws sts get-caller-identity

# Expected output:
{
    "UserId": "AIDA...",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/omnideploy"
}

Setting Up ECR¶

Create a repository for your container images:

# Create repository
aws ecr create-repository \
    --repository-name my-app \
    --region us-west-2

# Get repository URI
aws ecr describe-repositories \
    --repository-names my-app \
    --query 'repositories[0].repositoryUri' \
    --output text
# Output: 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app

Push Image to ECR¶

# Login to ECR
aws ecr get-login-password --region us-west-2 | \
    docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.us-west-2.amazonaws.com

# Tag image
docker tag my-app:latest \
    123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

# Push
docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Update deploy.yaml¶

container:
  image: 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Using GHCR with Private Repos¶

If using GitHub Container Registry with private images, configure registry credentials:

container:
  image: ghcr.io/owner/repo:latest
  registry:
    server: ghcr.io
    username: github-username
    password_env: GITHUB_TOKEN

Create a GitHub token with read:packages scope and set:

export GITHUB_TOKEN="ghp_..."

IAM Roles for CI/CD¶

For GitHub Actions, use OIDC instead of access keys:

Create IAM Identity Provider for GitHub
Create IAM Role with trust policy for GitHub
Attach OmniDeploy permissions to the role

See GitHub Actions deployment for details.

Troubleshooting¶

"Access Denied" Errors¶

Check that your IAM user has the required policies attached:

aws iam list-attached-user-policies --user-name omnideploy

"Token Expired" Errors¶

Refresh credentials:

# For SSO
aws sso login --profile your-profile

# For access keys, create new ones in IAM Console

Ensure you have ecr:GetAuthorizationToken permission:

aws ecr get-login-password --region us-west-2

If this fails, check IAM permissions.

Bootstrap Command¶

The omnideploy bootstrap command automates IAM setup.

Commands¶

# Create policy and group (requires admin credentials)
omnideploy bootstrap run

# Create policy, group, and user with access keys
omnideploy bootstrap run --user deployer --create-key

# Check current status
omnideploy bootstrap status

# View the IAM policy document
omnideploy bootstrap policy

Workflow¶

Get admin credentials - Use AWS Console or existing admin profile

Run bootstrap:

export AWS_PROFILE=admin  # or export AWS_ACCESS_KEY_ID/SECRET
omnideploy bootstrap run --user deployer --create-key

Save the output - Copy the access key and secret

Use new credentials for deployments:

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-west-2"

omnideploy up --config deploy.yaml

What Bootstrap Creates¶

Resource	Name	Description
IAM Policy	`OmniDeployPolicy`	Permissions for LightSail, ECR, SSM
IAM Group	`omnideploy-users`	Group with policy attached
IAM User	(optional)	User in the group
Access Key	(optional)	Credentials for the user

Idempotent¶

The bootstrap command is safe to run multiple times. It checks for existing resources and skips creation if they already exist.