Skip to main content

IAM Role Setup

EZ-CDC needs an IAM role in your AWS account to provision and manage worker infrastructure. This guide explains how to create the required role using CloudFormation.

Overview​

The IAM role allows EZ-CDC to:

  • Deploy EC2 instances for workers
  • Create Auto Scaling Groups
  • Configure security groups
  • Download binaries from S3

Important: EZ-CDC never has access to your database credentials or data.

Create the IAM Role​

  1. Log in to the EZ-CDC Portal

  2. Go to Deployments → New Deployment

  3. Click Download CloudFormation Template

  4. In AWS Console:

    • Go to CloudFormation → Create Stack
    • Choose Upload a template file
    • Upload the downloaded template
    • Click Next

  5. Configure the stack:

    • Stack name: ez-cdc-iam-role
    • ExternalId: (auto-filled from template)

  6. Click Next → Next → Create Stack

  7. Wait for stack creation (1-2 minutes)

  8. Go to Outputs tab and copy the RoleArn

Option 2: Manual Creation​

If you prefer to create the role manually:

Trust Policy​

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::830087179307:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }
  ]
}
External ID

The External ID is unique to your account. Get it from the EZ-CDC portal when creating a deployment.

Permission Policy​

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EC2Management",
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus",
        "ec2:CreateTags",
        "ec2:DescribeTags"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestedRegion": ["us-west-2", "us-east-1", "eu-west-1"]
        }
      }
    },
    {
      "Sid": "AutoScaling",
      "Effect": "Allow",
      "Action": [
        "autoscaling:CreateAutoScalingGroup",
        "autoscaling:UpdateAutoScalingGroup",
        "autoscaling:DeleteAutoScalingGroup",
        "autoscaling:DescribeAutoScalingGroups",
        "autoscaling:CreateLaunchConfiguration",
        "autoscaling:DeleteLaunchConfiguration",
        "autoscaling:DescribeLaunchConfigurations"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SecurityGroups",
      "Effect": "Allow",
      "Action": [
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:DescribeSecurityGroups",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupEgress"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Networking",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeAvailabilityZones"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::*:role/ez-cdc-*"
    }
  ]
}

Worker Instance Role​

Workers also need an instance role to:

  • Download binaries from S3
  • Send logs to CloudWatch (optional)
  • Use SSM for remote access (optional)

This role is created automatically by EZ-CDC during deployment:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3BinaryDownload",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::ez-cdc-releases/*"
      ]
    },
    {
      "Sid": "SSMAccess",
      "Effect": "Allow",
      "Action": [
        "ssm:UpdateInstanceInformation",
        "ssm:DescribeInstanceInformation",
        "ssmmessages:CreateControlChannel",
        "ssmmessages:CreateDataChannel",
        "ssmmessages:OpenControlChannel",
        "ssmmessages:OpenDataChannel"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:/ez-cdc/*"
    }
  ]
}

Security Considerations​

Principle of Least Privilege​

The IAM role follows least-privilege principles:

  • Regional restrictions: Actions limited to specified regions
  • Resource tagging: Resources tagged for identification
  • No data access: No permissions to read database content
  • No credential access: Secrets stored in EZ-CDC, not AWS

What EZ-CDC Can Do​

✅ Create and manage EC2 instances tagged with ez-cdc ✅ Create and configure security groups ✅ Create Auto Scaling Groups ✅ Read VPC and subnet information

What EZ-CDC Cannot Do​

❌ Access your databases directly ❌ Read S3 buckets (except ez-cdc-releases) ❌ Modify IAM policies ❌ Access other AWS services ❌ Create resources without ez-cdc tags

Verification​

After creating the role, verify it in the EZ-CDC portal:

  1. Go to Deployments → New Deployment
  2. Paste the Role ARN
  3. Click Validate Role

You should see:

✓ Role validated successfully
✓ Trust relationship configured
✓ Required permissions present

Troubleshooting​

"Access Denied" during validation​

  • Verify the External ID matches exactly
  • Check the trust policy allows arn:aws:iam::830087179307:root

"Missing permissions" error​

  • Ensure all required actions are in the policy
  • Check for any explicit Deny statements in SCPs

CloudFormation stack fails​

  • Check the Events tab for detailed errors
  • Ensure you have permissions to create IAM roles

Next Steps​

With the IAM role created:

  1. Create Deployment - Launch your workers