GETTING STARTED WITH AWS IAM IN SWAMP

In this tutorial, we will pull the AWS IAM extension, define an IAM role as a Swamp behavior, create the role in an AWS account, and then sync its state back into Swamp.

What we will build

We will create an IAM role named ec2-app-role that EC2 instances can assume. A behavior of type @swamp/aws/iam/role describes the role. Its create method provisions the role in AWS, and its sync method records the role's current state in Swamp.

Prerequisites

• Swamp installed (see Install Swamp)
• A terminal in a Swamp repository created with swamp repo init, while signed in to your Swamp account (see Swamp Account Requirement)
• AWS credentials in your environment or AWS profile that are allowed to create IAM roles (see Authenticate to AWS with SSO)

Pull the extension

First, we pull the extension that provides the IAM behavior types:

swamp extension pull @swamp/aws/iam

You will see output like:

INF extension·pull: Pulling "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Extracted 30 files:

The repository now has the IAM behavior types, including @swamp/aws/iam/role, which we use next.

Define the role

Now we add a behavior named ec2-app-role of type @swamp/aws/iam/role, as shown in Create and Run a Behavior. In its definition, we set these global arguments:

globalArguments:
  RoleName: ec2-app-role
  Description: Role for the app EC2 instances
  AssumeRolePolicyDocument:
    Version: "2012-10-17"
    Statement:
      - Effect: Allow
        Principal:
          Service: ec2.amazonaws.com
        Action: sts:AssumeRole

Notice that AssumeRolePolicyDocument is an object, not a string. This argument is the role's trust policy, and the role type requires it. This trust policy lets the EC2 service assume the role.

We leave accessKeyId, secretAccessKey and sessionToken unset, so the behavior uses the AWS credentials from our environment or profile. IAM is global, so we also leave region at its default of us-east-1.

Create the role in AWS

Next, we run the create method:

swamp behavior run ec2-app-role create

This command calls AWS IAM to create the role ec2-app-role with our trust policy. It also writes the IAM Role resource state for the behavior. If the run fails with an access denied error, the AWS credentials in the environment do not have permission to create IAM roles.

Sync the role's state

Now we read the role back from AWS:

swamp behavior run ec2-app-role sync

This command reads ec2-app-role from AWS and writes its current state to the behavior's IAM Role resource state. Notice that sync makes no changes in AWS. It only records what is there now.

What we built

We pulled @swamp/aws/iam and described an IAM role with an EC2 trust policy as a Swamp behavior. We created the role in AWS with the create method and recorded its current state with sync. The role ec2-app-role now exists in the account, and Swamp holds its resource state. You can query that state as shown in Working with Data.