Skip to content

AWS Setup

Jump to bottom
Eric Mann edited this page Dec 13, 2025 · 1 revision

Amazon Web Services (AWS) Setup Guide

This step-by-step guide walks you through setting up Amazon Web Services to work with Displace. No prior AWS experience required.

Subscription Required: AWS provider access requires a paid Displace subscription. Local development is always free.

Note: AWS provider currently uses the AWS CLI. Future versions may migrate to Terraform for infrastructure management.

What You'll Need

Before starting, you'll need:

  • An email address for your AWS account
  • A credit card for AWS account verification
  • About 20-30 minutes to complete setup

What We're Setting Up

To use Displace with AWS, you need:

  1. AWS Account - Your Amazon Web Services account
  2. IAM User - A special user account that Displace uses to manage resources
  3. Access Keys - Credentials that prove Displace is authorized to use that user
  4. AWS CLI - The command-line tool that connects to AWS

Don't worry - we'll walk through each step!

Step 1: Create an AWS Account

If you already have an AWS account, skip to Step 2.

  1. Go to aws.amazon.com

  2. Click Create an AWS Account (top right)

  3. Enter your email address and choose an account name

  4. Verify your email address

  5. Create a root user password

  6. Select Personal or Business account type

  7. Enter your contact information

  8. Enter payment information (required for verification)

  9. Verify your phone number

  10. Select a support plan (Free tier is fine for getting started)

What you should see: The AWS Management Console welcome page

Free Tier: New AWS accounts get 12 months of free tier access. EKS clusters themselves cost ~$0.10/hour, but you can use free tier for EC2 instances.

Step 2: Create an IAM User

IAM (Identity and Access Management) users are more secure than using your root account. We'll create a dedicated user for Displace.

  1. Sign in to the AWS Console

  2. In the search bar at the top, type IAM and click on IAM

  3. In the left sidebar, click Users

  4. Click Create user (blue button)

  5. Enter user details:

    • User name: displace-cli
    • Provide user access to the AWS Management Console: Leave unchecked (not needed)

  6. Click Next

What you should see: The "Set permissions" page appears

Step 3: Create an IAM Policy

Displace needs specific permissions to manage EKS clusters. We'll create a custom policy with exactly what's needed.

You should still be on the user creation page. First, let's create the policy:

  1. Open a new browser tab and go to the AWS Console

  2. Search for IAM and click on it

  3. In the left sidebar, click Policies

  4. Click Create policy

  5. Click the JSON tab

  6. Delete the existing content and paste this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "eks:ListClusters",
        "eks:DescribeCluster",
        "eks:CreateCluster",
        "eks:DeleteCluster",
        "eks:UpdateClusterConfig",
        "eks:UpdateClusterVersion",
        "eks:ListNodegroups",
        "eks:CreateNodegroup",
        "eks:DeleteNodegroup",
        "eks:UpdateNodegroupConfig",
        "eks:DescribeNodegroup",
        "eks:ListUpdates",
        "eks:DescribeUpdate",
        "eks:ListFargateProfiles",
        "eks:CreateFargateProfile",
        "eks:DeleteFargateProfile",
        "eks:DescribeFargateProfile",
        "eks:TagResource",
        "eks:UntagResource",
        "eks:ListTagsForResource"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::*:role/eks-*",
        "arn:aws:iam::*:role/AmazonEKS*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "iam:AWSServiceName": [
            "eks.amazonaws.com",
            "eks-nodegroup.amazonaws.com"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetRole"
      ],
      "Resource": "arn:aws:iam::*:role/aws-service-role/eks-nodegroup.amazonaws.com/AWSServiceRoleForAmazonEKSNodegroup"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeRouteTables",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeNatGateways",
        "ec2:DescribeVpcEndpoints",
        "ec2:DescribeAvailabilityZones"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:CreateVpc",
        "ec2:CreateSubnet",
        "ec2:CreateSecurityGroup",
        "ec2:CreateRouteTable",
        "ec2:CreateInternetGateway",
        "ec2:CreateNatGateway",
        "ec2:CreateVpcEndpoint",
        "ec2:CreateTags",
        "ec2:ModifyVpcAttribute",
        "ec2:ModifySubnetAttribute",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:CreateRoute",
        "ec2:DeleteRoute",
        "ec2:ReplaceRoute",
        "ec2:AssociateRouteTable",
        "ec2:DisassociateRouteTable",
        "ec2:AttachInternetGateway",
        "ec2:DetachInternetGateway"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DeleteVpc",
        "ec2:DeleteSubnet",
        "ec2:DeleteSecurityGroup",
        "ec2:DeleteRouteTable",
        "ec2:DeleteInternetGateway",
        "ec2:DeleteNatGateway"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:CreateLaunchTemplate",
        "ec2:CreateLaunchTemplateVersion",
        "ec2:DescribeLaunchTemplates",
        "ec2:DescribeLaunchTemplateVersions",
        "ec2:DeleteLaunchTemplate",
        "ec2:DeleteLaunchTemplateVersions"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:DescribeInstances",
        "ec2:TerminateInstances",
        "ec2:StartInstances",
        "ec2:StopInstances"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:CreateKeyPair",
        "ec2:DescribeKeyPairs",
        "ec2:DeleteKeyPair"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:AllocateAddress",
        "ec2:DescribeAddresses",
        "ec2:ReleaseAddress"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "autoscaling:CreateAutoScalingGroup",
        "autoscaling:DescribeAutoScalingGroups",
        "autoscaling:UpdateAutoScalingGroup",
        "autoscaling:DeleteAutoScalingGroup",
        "autoscaling:CreateLaunchConfiguration",
        "autoscaling:DescribeLaunchConfigurations",
        "autoscaling:DeleteLaunchConfiguration"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:GetRole",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies",
        "iam:PutRolePolicy",
        "iam:DeleteRolePolicy",
        "iam:AttachRolePolicy",
        "iam:DetachRolePolicy",
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::*:role/eks-*",
        "arn:aws:iam::*:role/AmazonEKSClusterRole",
        "arn:aws:iam::*:role/AmazonEKSNodeRole"
      ]
    }
  ]
}

  1. Click Next

  2. Enter policy details:

    • Policy name: DisplaceEKSPolicy
    • Description: IAM policy for Displace CLI to manage EKS clusters

  3. Click Create policy

What you should see: "Policy DisplaceEKSPolicy created" message

Step 4: Attach the Policy to Your User

Go back to the browser tab where you were creating the IAM user.

  1. On the "Set permissions" page, click Attach policies directly

  2. In the search box, type DisplaceEKSPolicy

  3. Check the box next to your newly created policy

  4. Click Next

  5. Review the user details and click Create user

What you should see: "User created successfully" message

Step 5: Create Access Keys

Access keys are like a username and password that Displace uses to authenticate.

  1. Click on the user name displace-cli to open the user details

  2. Click the Security credentials tab

  3. Scroll down to Access keys

  4. Click Create access key

  5. Select Command Line Interface (CLI)

  6. Check the confirmation box at the bottom

  7. Click Next

  8. (Optional) Add a description tag like Displace CLI access

  9. Click Create access key

  10. IMPORTANT: You'll see your Access Key ID and Secret Access Key. Save these now!

    • Click Download .csv file to save them
    • Or copy them to a secure location

What you should see: Your Access Key ID and Secret Access Key displayed

Security Warning: This is the only time you'll see the Secret Access Key. If you lose it, you'll need to create a new one.

  • Never share these keys publicly
  • Never commit them to git
  • Store them securely

Step 6: Install the AWS CLI

The AWS CLI connects your computer to AWS. Displace uses it to manage your EKS clusters.

Linux

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

macOS

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Windows (WSL2)

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Verify Installation

aws --version

What you should see: Something like aws-cli/2.x.x Python/3.x.x ...

Step 7: Configure AWS CLI

Now we'll configure the AWS CLI with your access keys.

  1. Run the configure command:

    aws configure

  2. Enter the requested information:

    • AWS Access Key ID: Paste your Access Key ID from Step 5
    • AWS Secret Access Key: Paste your Secret Access Key from Step 5
    • Default region name: Enter a region like us-west-2 or us-east-1
    • Default output format: Press Enter to accept default (or type json)

What you should see: The prompt returns with no error

Verify Configuration

aws sts get-caller-identity

What you should see:

{
    "UserId": "AIDAEXAMPLEID123456",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/displace-cli"
}

Step 8: Configure Displace

Now connect Displace to your AWS account.

displace provider aws configure

When prompted:

  • AWS Region: Enter your preferred region (e.g., us-west-2)
  • AWS Profile: Press Enter to use default, or specify a profile name

What you should see:

✅ AWS provider configured successfully
   Region: us-west-2
   Profile: default

Step 9: Test Your Configuration

Verify everything is working:

# Test the provider connection
displace provider test aws

What you should see:

✅ AWS provider test successful
   - Credentials valid
   - Permissions verified

You can also audit your configuration:

displace provider aws audit

Step 10: Create Your First Cluster

You're ready to create a Kubernetes cluster!

# Create a cluster named "my-cluster"
displace cluster create my-cluster --provider aws

This will:

  1. Create a VPC with subnets
  2. Set up security groups
  3. Create an EKS cluster
  4. Configure node groups
  5. Configure kubectl to connect
  6. Install monitoring and ingress components

Wait time: EKS cluster creation takes 10-15 minutes.

What you should see:

Creating cluster 'my-cluster' on AWS...
✅ VPC created
✅ Subnets configured
✅ Security groups configured
✅ EKS cluster created
✅ Node group ready
✅ Kubectl configured
✅ Monitoring installed
✅ Ingress controller installed

Cluster 'my-cluster' is ready!

Understanding AWS Costs

AWS charges for resources your cluster uses. Here's what to expect:

Free Tier Limitations

AWS Free Tier includes some EC2 hours, but EKS itself is not free:

  • EKS cluster management: $0.10 per hour (~$72/month)
  • EC2 instances: Varies by type (some free tier eligible)

Typical Costs

Resource Approximate Cost
EKS cluster $0.10/hour (~$72/month)
t3.medium node (2 vCPU, 4GB) ~$30/month
t3.small node (2 vCPU, 2GB) ~$15/month
EBS storage (20GB) ~$2/month
Network load balancer ~$18/month

Cost-Saving Tips

  1. Destroy clusters when not in use:

    displace cluster destroy my-cluster

  2. Use smaller node types for development:

    displace cluster create dev-cluster --provider aws --node-type t3.small

  3. Reduce node count:

    displace cluster create dev-cluster --provider aws --node-count 1

  4. Use spot instances (for non-production):

    • Significant cost savings (up to 90%)
    • Instances may be interrupted

  5. Set up billing alerts in AWS Console > Billing > Budgets

Troubleshooting

"Access Denied" or "Not authorized"

Cause: IAM user missing required permissions.

Solution:

  1. Go to IAM > Users > displace-cli
  2. Click Permissions tab
  3. Verify DisplaceEKSPolicy is attached
  4. If missing, click Add permissions > Attach policies directly

"Invalid credentials"

Cause: Access keys incorrect or expired.

Solution:

  1. Verify your ~/.aws/credentials file has the correct keys
  2. Create new access keys if needed (Step 5)
  3. Run aws configure again

"Region not enabled"

Cause: Some regions require manual opt-in.

Solution:

  1. Go to Account Settings in AWS Console
  2. Find the region and click Enable
  3. Wait a few minutes, then try again

"Service limit exceeded"

Cause: AWS limits how many resources you can create.

Solution:

  1. Request a limit increase in AWS Console > Service Quotas
  2. Or try a different region
  3. Common limits: VPCs (5), Elastic IPs (5), EC2 instances (varies)

"VPC limit exceeded"

Cause: You've hit the maximum VPCs in a region (default: 5).

Solution:

  1. Delete unused VPCs in EC2 Console > VPC
  2. Or request a limit increase

Cluster creation timeout

Cause: EKS creation can take 15+ minutes.

Solution:

  1. Check status in AWS Console > EKS
  2. Look for error events
  3. Common issues: IAM role problems, subnet configuration

Security Best Practices

  1. Never use root account for CLI

    • Always use IAM users with limited permissions
    • Enable MFA on your root account

  2. Rotate access keys regularly

    • Create new keys periodically
    • Delete old keys after rotation

  3. Use the principle of least privilege

    • Only grant permissions that are needed
    • Use the custom policy we provided

  4. Protect your credentials

    • Never commit ~/.aws/credentials to git
    • Don't share access keys
    • Consider AWS SSO for team access

  5. Enable CloudTrail

    • Track API calls for security auditing
    • Go to CloudTrail in AWS Console

Cleaning Up

When you're done testing or want to remove resources:

Delete a Cluster

displace cluster destroy my-cluster --provider aws

Delete Access Keys (if rotating)

  1. Go to IAM > Users > displace-cli
  2. Click Security credentials tab
  3. Find the access key and click Delete

Delete the IAM User (if no longer needed)

  1. Go to IAM > Users
  2. Select displace-cli
  3. Click Delete user
  4. Type the user name to confirm

Delete the IAM Policy (if no longer needed)

  1. Go to IAM > Policies
  2. Search for DisplaceEKSPolicy
  3. Select it and click Delete

AWS Regions Reference

Choose a region close to your users for better performance:

Region Code Location
us-east-1 N. Virginia (most services)
us-east-2 Ohio
us-west-1 N. California
us-west-2 Oregon
eu-west-1 Ireland
eu-west-2 London
eu-central-1 Frankfurt
ap-southeast-1 Singapore
ap-southeast-2 Sydney
ap-northeast-1 Tokyo

Quick Reference

Commands

# Configure AWS provider
displace provider aws configure

# Test configuration
displace provider test aws

# Audit configuration
displace provider aws audit

# View required IAM policy
displace provider aws policy

# Create cluster
displace cluster create my-cluster --provider aws

# Check cluster status
displace cluster status my-cluster --provider aws

# Destroy cluster
displace cluster destroy my-cluster --provider aws

Required AWS CLI Commands

# Check credentials
aws sts get-caller-identity

# List EKS clusters
aws eks list-clusters --region us-west-2

Related Documentation:

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally