Role

AWS IAM Role resource for identity and access management

Role

Creates and manages IAM roles with support for inline policies, managed policies, and automatic cleanup of attached policies during deletion.

Props

assumeRolePolicy · PolicyDocument · required

Policy that defines which entities can assume this role.

roleName · string

Name of the IAM role.

Default: ${app}-${stage}-${id}

description · string

Optional description of the role’s purpose.

path · string

Optional path prefix for the role.

maxSessionDuration · number

Maximum session duration in seconds when assumed.

Default: 3600 (1 hour)

permissionsBoundary · string

ARN of the policy used to set the permissions boundary.

policies · Array<object>

Inline policies to embed in the role. Each policy must have a unique name and policy document.

Show properties

policies[].policyName · string · required

Name of the inline policy.

policies[].policyDocument · PolicyDocument · required

The policy document defining permissions.

managedPolicyArns · string[]

List of managed policy ARNs to attach to the role.

tags · Record<string, string>

Resource tags for the role.

Output

arn · string

ARN of the role.

roleName · string

Name of the Role.

uniqueId · string

Unique identifier for the role.

roleId · string

The stable and unique string identifying the role.

createDate · Date

When the role was created.

Examples

Basic Lambda execution role with inline policy

import { Role } from "alchemy/aws";

const basicRole = await Role("lambda-role", {
  roleName: "lambda-role",
  assumeRolePolicy: {
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: {
        Service: "lambda.amazonaws.com"
      },
      Action: "sts:AssumeRole"
    }]
  },
  description: "Basic Lambda execution role",
  tags: {
    Environment: "production"
  },
  policies: [{
    policyName: "logs",
    policyDocument: {
      Version: "2012-10-17",
      Statement: [{
        Effect: "Allow",
        Action: [
          "logs:CreateLogGroup",
          "logs:CreateLogStream",
          "logs:PutLogEvents"
        ],
        Resource: "*"
      }]
    }
  }]
});

Role with AWS managed policies

import { Role } from "alchemy/aws";

const managedRole = await Role("readonly-role", {
  roleName: "readonly-role",
  assumeRolePolicy: {
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: {
        Service: "lambda.amazonaws.com"
      },
      Action: "sts:AssumeRole"
    }]
  },
  description: "Role with managed policies",
  managedPolicyArns: [
    "arn:aws:iam::aws:policy/ReadOnlyAccess"
  ],
  tags: {
    Environment: "production"
  }
});

Role with multiple inline policies and custom session duration

import { Role } from "alchemy/aws";

const customRole = await Role("custom-role", {
  roleName: "custom-role",
  assumeRolePolicy: {
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: {
        Service: "lambda.amazonaws.com"
      },
      Action: "sts:AssumeRole"
    }]
  },
  description: "Role with multiple policies",
  maxSessionDuration: 7200,
  policies: [
    {
      policyName: "logs",
      policyDocument: {
        Version: "2012-10-17",
        Statement: [{
          Effect: "Allow",
          Action: [
            "logs:CreateLogGroup",
            "logs:CreateLogStream",
            "logs:PutLogEvents"
          ],
          Resource: "*"
        }]
      }
    },
    {
      policyName: "s3",
      policyDocument: {
        Version: "2012-10-17",
        Statement: [{
          Effect: "Allow",
          Action: "s3:ListBucket",
          Resource: "*"
        }]
      }
    }
  ],
  tags: {
    Environment: "production",
    Updated: "true"
  }
});