Fjall Docs — deploy AWS infrastructure into your own account

Overview

The IAM constructs give AWS services and applications identity-based access control. Role, Policy and InstanceProfile are pass-through wrappers over the CDK classes with identical props and methods. ManagedPolicy adds one default. DelegationRole is a composite construct that Fjall builds for cross-account Route53 delegation. Most roles in a Fjall application are created for you. Read How Fjall constructs consume roles before writing one by hand.

Resource Classes

Class	Extends	What Fjall adds
`Role`	`iam.Role`	Nothing. Props and methods pass straight through.
`Policy`	`iam.Policy`	Nothing. `props` is required rather than optional.
`ManagedPolicy`	`iam.ManagedPolicy`	Default `description` of `${id} IAM Managed Policy`.
`InstanceProfile`	`iam.CfnInstanceProfile`	Nothing. This is an L1 construct, so `roles` takes ARNs or role refs.
`DelegationRole`	`Construct`	A complete cross-account Route53 delegation role, trust, and export.

import { Role } from "@fjall/components-infrastructure/lib/resources/aws/iam/role";
import { Policy } from "@fjall/components-infrastructure/lib/resources/aws/iam/policy";
import { ManagedPolicy } from "@fjall/components-infrastructure/lib/resources/aws/iam/managedPolicy";
import { InstanceProfile } from "@fjall/components-infrastructure/lib/resources/aws/iam/instanceProfile";
import { DelegationRole } from "@fjall/components-infrastructure/lib/resources/aws/iam/delegationRole";

The deep lib/... path is a published subpath of the package. IAM constructs are not re-exported from the package root, so this import is the only one that compiles. Import each module directly, since the directory barrel itself is not a resolvable subpath.

This page covers using the construct classes directly. The scaffolded fjall/<app>/infrastructure.ts that fjall create application writes never does that: it imports App and the *Factory symbols from the package root, and fjall add edits it through the codemod engine.

What This Creates

Construct	CloudFormation resources
`Role`	`AWS::IAM::Role`, plus one `AWS::IAM::Policy` holding every `addToPolicy` statement
`Policy`	`AWS::IAM::Policy`
`ManagedPolicy`	`AWS::IAM::ManagedPolicy`
`InstanceProfile`	`AWS::IAM::InstanceProfile`
`DelegationRole`	`AWS::IAM::Role` with two inline policies, plus a `CfnOutput` with an export

Role forces no defaults. Every removal policy, name and permission comes from the props you pass or from CDK’s own defaults.

Basic Usage

const role = new Role(this, "ApiRole", {
  assumedBy: new ServicePrincipal("lambda.amazonaws.com"),
  description: "API function execution role",
});

props is required. assumedBy is the only required field inside it.

Configuration Options

All standard CDK RoleProps are supported.

Property	Type	Description
`assumedBy`	`IPrincipal`	Principal that can assume this role. Required
`description`	`string`	Role description
`roleName`	`string`	Physical role name. Account-global
`path`	`string`	IAM path, for path-scoped grants and SCPs
`managedPolicies`	`IManagedPolicy[]`	AWS or customer managed policies
`inlinePolicies`	`{ [name: string]: PolicyDocument }`	Inline policies created with the role
`maxSessionDuration`	`Duration`	Maximum session duration. Minimum 1 hour
`permissionsBoundary`	`IManagedPolicy`	Ceiling on the role’s effective permissions
`externalIds`	`string[]`	External IDs required to assume the role

A fixed roleName is account-global. Set one only on a role confined to a single account and region stack, otherwise regional duplicates of the same stack collide on the name and roll back.

Common Patterns

Lambda execution role

const lambdaRole = new Role(this, "ApiLambdaRole", {
  assumedBy: new ServicePrincipal("lambda.amazonaws.com"),
  description: "API Lambda execution role",
  managedPolicies: [
    ManagedPolicy.fromAwsManagedPolicyName(
      "service-role/AWSLambdaBasicExecutionRole",
    ),
  ],
  inlinePolicies: {
    S3Access: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["s3:GetObject", "s3:PutObject"],
          resources: [`${uploadsBucket.bucketArn}/*`],
        }),
      ],
    }),
  },
});

ECS task role

const taskRole = new Role(this, "WebTaskRole", {
  assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
  description: "Web service task role",
  inlinePolicies: {
    SecretsAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["secretsmanager:GetSecretValue"],
          resources: [
            "arn:aws:secretsmanager:us-east-1:123456789012:secret:web/db-*",
          ],
        }),
      ],
    }),
  },
});

EC2 instance role

const instanceRole = new Role(this, "WorkerInstanceRole", {
  assumedBy: new ServicePrincipal("ec2.amazonaws.com"),
  description: "Worker EC2 instance role",
  managedPolicies: [
    ManagedPolicy.fromAwsManagedPolicyName("AmazonSSMManagedInstanceCore"),
    ManagedPolicy.fromAwsManagedPolicyName("CloudWatchAgentServerPolicy"),
  ],
});

const instanceProfile = new InstanceProfile(this, "WorkerInstanceProfile", {
  roles: [instanceRole.roleName],
});

InstanceProfile wraps the L1 CfnInstanceProfile, so roles takes role names or refs rather than IRole objects.

Principals

Principals come from aws-cdk-lib/aws-iam unchanged. See the AWS IAM principal reference for the full list.

// AWS service
new ServicePrincipal("ecs-tasks.amazonaws.com");

// Another account
new AccountPrincipal("123456789012");

// Every account in the AWS Organization
new OrganizationPrincipal("o-abc123def4");

// Several services on one role
new CompositePrincipal(
  new ServicePrincipal("lambda.amazonaws.com"),
  new ServicePrincipal("events.amazonaws.com"),
);

// Conditional trust
new ServicePrincipal("lambda.amazonaws.com").withConditions({
  StringEquals: { "sts:ExternalId": "unique-external-id" },
});

// Session tags
new ServicePrincipal("lambda.amazonaws.com").withSessionTags();

GitHub Actions OIDC

const githubRole = new Role(this, "GitHubActionsRole", {
  assumedBy: new OpenIdConnectPrincipal(oidcProvider, {
    StringEquals: {
      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
      "token.actions.githubusercontent.com:sub":
        "repo:acme/api:ref:refs/heads/main",
    },
  }),
  description: "GitHub Actions deployment role",
});

For CI deploys you do not need this role. fjall ci setup --provider github writes the workflow and Fjall mints short-lived credentials for the run. Mint the deploy token in the web app under Settings → CI/CD Tokens.

Policies

Inline policies

Inline policies live and die with the role. Use them for permissions no other identity needs.

const role = new Role(this, "WorkerRole", {
  assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
  inlinePolicies: {
    QueueAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["sqs:ReceiveMessage", "sqs:DeleteMessage"],
          resources: [jobQueue.queueArn],
        }),
      ],
    }),
    TableAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["dynamodb:GetItem", "dynamodb:PutItem"],
          resources: [jobsTable.tableArn],
        }),
      ],
    }),
  },
});

Managed policies

The Fjall ManagedPolicy inherits CDK’s static factories, so fromAwsManagedPolicyName and fromManagedPolicyArn work on either import. The one difference is on construction: a Fjall ManagedPolicy created without a description gets `${id} IAM Managed Policy` instead of no description at all.

import { ManagedPolicy } from "@fjall/components-infrastructure/lib/resources/aws/iam/managedPolicy";

// description defaults to "ConfigReadPolicy IAM Managed Policy"
const configRead = new ManagedPolicy(this, "ConfigReadPolicy", {
  statements: [
    new PolicyStatement({
      actions: ["s3:ListBucket"],
      resources: [configBucket.bucketArn],
    }),
  ],
});

const role = new Role(this, "DashboardRole", {
  assumedBy: new ServicePrincipal("lambda.amazonaws.com"),
  managedPolicies: [
    configRead,
    ManagedPolicy.fromAwsManagedPolicyName("AWSXRayDaemonWriteAccess"),
  ],
});

Adding permissions after creation

role.addToPolicy(
  new PolicyStatement({
    actions: ["s3:GetObject"],
    resources: [`${assetsBucket.bucketArn}/*`],
  }),
);

role.addManagedPolicy(
  ManagedPolicy.fromAwsManagedPolicyName("AWSXRayDaemonWriteAccess"),
);

Prefer resource grant methods where they exist. They write the tightest possible statement and wire up KMS decrypt for you.

assetsBucket.grantRead(role);
jobsTable.grantReadWriteData(role);
dbSecret.grantRead(role);
alertsTopic.grantPublish(role);

Permission boundaries

const boundary = ManagedPolicy.fromManagedPolicyArn(
  this,
  "Boundary",
  "arn:aws:iam::123456789012:policy/BoundaryPolicy",
);

const role = new Role(this, "TenantRole", {
  assumedBy: new ServicePrincipal("lambda.amazonaws.com"),
  permissionsBoundary: boundary,
});

How Fjall Constructs Consume Roles

Lambda

LambdaFunction builds its own execution role and accepts no role prop. Attach permissions through inlinePolicy, and pin the role’s description, path or name through the dedicated props.

import { LambdaFunction } from "@fjall/components-infrastructure/lib/resources/aws/compute/lambda";

const fn = new LambdaFunction(this, "ApiFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  roleDescription: "API function execution role",
  rolePath: "/fjall/",
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject"],
      resources: [`${assetsBucket.bucketArn}/*`],
    }),
  ],
});

Prop	Effect on the generated role
`inlinePolicy`	Each statement is added with `addToRolePolicy`. Required
`roleDescription`	Sets `description` on the L1 `CfnRole`, which CDK does not expose
`rolePath`	Fixed IAM path, for SCP-exemptable ARNs
`roleName`	Fixed physical name. Account-global, so single-region stacks only

LambdaFunction rejects deprecated runtimes at synth time. nodejs18.x and every earlier Node.js, Python 3.9 and below, java8, dotnet6, go1.x and the rest of the deprecated set throw with a message pointing at Runtime.NODEJS_24_X. This is the shift-left of the posture scan’s LAMBDA_DEPRECATED_RUNTIME finding.

ECS services

The ECS pattern creates two roles per service, named ${serviceName}ExecutionRole and ${serviceName}TaskRole. Do not build them yourself. The execution role carries the four ECR pull actions and a ViaService-conditioned kms:Decrypt, plus path-scoped ssm:GetParameter and ssm:GetParameters when the service declares secrets. It deliberately omits logs:* and secretsmanager:GetSecretValue, because CDK auto-grants those on the exact log group and secret ARNs. The task role carries the four ECS Exec ssmmessages actions. At the enterprise backup tier the exec session channel and its audit log are encrypted with the stack’s shared key (alias/cmk/<stack>/FjallStackEncryptionKey), and the task role’s kms:Decrypt and kms:GenerateDataKey on it are wired for you. The principal running aws ecs execute-command needs its own grant: ecs:ExecuteCommand on the cluster and its tasks, plus kms:GenerateDataKey on that key at enterprise. grantExecuteCommand grants both halves, scoped to the cluster, at every tier:

const api = app.addCompute(ComputeFactory.build("Api", { type: "ecs", /* … */ }));
const operators = new Role(stack, "ExecOperators", {
  assumedBy: new AccountPrincipal(stack.account),
});
api.grantExecuteCommand(operators);

The fjall aws exec deploy session and the AdministratorAccess permission set already carry both. A custom Identity Center permission set adds the KMS statement itself:

{
  "Effect": "Allow",
  "Action": "kms:GenerateDataKey",
  "Resource": "arn:aws:kms:<region>:<account>:key/*",
  "Condition": {
    "ForAnyValue:StringLike": {
      "kms:ResourceAliases": "alias/cmk/*/FjallStackEncryptionKey"
    }
  }
}

Extend the task role from the service props.

{
  name: "web",
  taskRoleInlinePolicies: {
    UploadsAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["s3:PutObject"],
          resources: [`${uploadsBucket.bucketArn}/*`],
        }),
      ],
    }),
  },
  taskRoleManagedPolicies: [
    ManagedPolicy.fromAwsManagedPolicyName("AWSXRayDaemonWriteAccess"),
  ],
}

Route53 delegation

DelegationRole is built by the HostedZone construct when a zone mints delegation for child accounts. You read its roleArn, you do not construct it.

Prop	Type	Description
`zoneName`	`string`	Zone the role delegates. Required
`hostedZone`	`IHostedZone`	Zone the record-set grant is scoped to. Required
`organisationId`	`string`	Literal AWS Organization id for the trust. Required
`naming`	`"full-zone" \| "first-label"`	Role-name derivation. Default `"full-zone"`
`description`	`string`	Defaults to a Fjall-managed description naming the zone

The role trusts OrganizationPrincipal(organisationId) and holds two inline policies: route53:ListHostedZonesByName on *, and route53:ChangeResourceRecordSets scoped to that one zone ARN. The physical name is <stem>DelegateHostedZoneRole, and the ARN is published as a stack export.

Changing naming changes both the role name and the construct id, which replaces the role. Child accounts hold the old ARN literally and lose delegation. Apex zones pin naming: "first-label" for exactly this reason.

Least-Privilege Rules

Scope Secrets Manager ARNs with `-*`

Secrets Manager appends a six-character random ID after a - separator. A bare * suffix therefore matches sibling secrets.

// Wrong. Matches "web/db-AbCdEf" and also "web/db2-XyZw1A"
resources: ["arn:aws:secretsmanager:us-east-1:123456789012:secret:web/db*"];

// Right. Matches only the six-character suffixes of that one secret
resources: ["arn:aws:secretsmanager:us-east-1:123456789012:secret:web/db-*"];

Fjall’s own constructs are lint-enforced on this by the fjall/iam-secrets-arn-suffix rule. Apply the same shape to policies you write by hand.

Avoid wildcard actions and resources

// Wrong
new PolicyStatement({ actions: ["*"], resources: ["*"] });

// Right
new PolicyStatement({
  actions: ["s3:GetObject", "s3:PutObject"],
  resources: [`${uploadsBucket.bucketArn}/uploads/*`],
});

Some AWS actions are account-level and legitimately need resources: ["*"]. ecr:GetAuthorizationToken and the ECS Exec ssmmessages actions are the ones Fjall’s own roles use. Constrain everything else with a condition.

new PolicyStatement({
  actions: ["kms:Decrypt", "kms:DescribeKey"],
  resources: ["*"],
  conditions: {
    StringEquals: {
      "kms:ViaService": `secretsmanager.${this.region}.amazonaws.com`,
    },
  },
});

Complete Example

import { Role } from "@fjall/components-infrastructure/lib/resources/aws/iam/role";
import {
  CompositePrincipal,
  ManagedPolicy,
  PolicyDocument,
  PolicyStatement,
  ServicePrincipal,
} from "aws-cdk-lib/aws-iam";
import { CfnOutput, Duration, Tags } from "aws-cdk-lib";

const appServiceRole = new Role(this, "ApplicationServiceRole", {
  description: "API application service role",

  assumedBy: new CompositePrincipal(
    new ServicePrincipal("lambda.amazonaws.com"),
    new ServicePrincipal("ecs-tasks.amazonaws.com"),
  ),

  managedPolicies: [
    ManagedPolicy.fromAwsManagedPolicyName(
      "service-role/AWSLambdaBasicExecutionRole",
    ),
    ManagedPolicy.fromAwsManagedPolicyName("AWSXRayDaemonWriteAccess"),
  ],

  inlinePolicies: {
    DatabaseAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          sid: "RDSDataAccess",
          actions: [
            "rds-data:ExecuteStatement",
            "rds-data:BatchExecuteStatement",
          ],
          resources: ["arn:aws:rds:us-east-1:123456789012:cluster:api-db"],
        }),
      ],
    }),

    StorageAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          sid: "S3ObjectAccess",
          actions: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
          resources: [`${uploadsBucket.bucketArn}/*`],
        }),
        new PolicyStatement({
          sid: "S3ListAccess",
          actions: ["s3:ListBucket"],
          resources: [uploadsBucket.bucketArn],
          conditions: {
            StringLike: { "s3:prefix": ["uploads/*", "processed/*"] },
          },
        }),
      ],
    }),

    SecretsAccess: new PolicyDocument({
      statements: [
        new PolicyStatement({
          sid: "GetSecrets",
          actions: [
            "secretsmanager:GetSecretValue",
            "secretsmanager:DescribeSecret",
          ],
          resources: [appSecret.secretArn, dbSecret.secretArn],
        }),
        new PolicyStatement({
          sid: "KMSDecrypt",
          actions: ["kms:Decrypt", "kms:DescribeKey"],
          resources: ["*"],
          conditions: {
            StringEquals: {
              "kms:ViaService": `secretsmanager.${this.region}.amazonaws.com`,
            },
          },
        }),
      ],
    }),
  },

  maxSessionDuration: Duration.hours(1),
});

jobsTable.grantReadWriteData(appServiceRole);
jobQueue.grantConsumeMessages(appServiceRole);
alertsTopic.grantPublish(appServiceRole);

Tags.of(appServiceRole).add("Application", "api");

new CfnOutput(this, "ServiceRoleArn", {
  value: appServiceRole.roleArn,
  description: "API service role ARN",
});

Best Practices

Prefer resource grant* methods over hand-written statements.
Let LambdaFunction and the ECS pattern build their own roles. Extend them through inlinePolicy and taskRoleInlinePolicies.
Give every role a description. Fjall sets one on its own generated roles so an audit sees a purpose on each.
Scope Secrets Manager ARNs with -*, never a bare *.
Leave roleName unset unless a path- or name-scoped grant needs to match it.
Use permissionsBoundary for roles that application code can influence.
Constrain unavoidable resources: ["*"] statements with a condition.

Troubleshooting

Symptom	Cause and fix
`AccessDenied` at runtime	Check the trust policy first, then the permission policy
`MalformedPolicyDocument`	Service principal is wrong. Use the full `<service>.amazonaws.com` form
`LimitExceeded` on policy size	Move statements into a managed policy and attach it
Circular dependency at synth	Create the role first, then add permissions with `addToPolicy`
`EntityAlreadyExists` on rollback	A fixed `roleName` collided across regions. Drop it or scope the stack

Inspect a deployed role

Run AWS commands through Fjall so credentials are minted for the right account.

# Discover target names
fjall target list

# Read the role and its policies
fjall aws exec --target production-use1 -- aws iam get-role --role-name MyRole
fjall aws exec --target production-use1 -- aws iam list-role-policies --role-name MyRole
fjall aws exec --target production-use1 -- aws iam list-attached-role-policies --role-name MyRole

# Test an action against the role
fjall aws exec --target production-use1 -- aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/MyRole \
  --action-names s3:GetObject \
  --resource-arns "arn:aws:s3:::my-bucket/*"

Next Steps

Secrets Manager

Store and grant access to credentials and API keys.

KMS Key

Encrypt data and scope decryption to specific roles.

Lambda Function

Attach permissions to a serverless function through inlinePolicy.

ECS Cluster

Extend the generated task role for a container service.

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

IAM Role

Overview

Resource Classes

What This Creates

Basic Usage

Configuration Options

Common Patterns

Lambda execution role

ECS task role

EC2 instance role

Principals

GitHub Actions OIDC

Policies

Inline policies

Managed policies

Adding permissions after creation

Permission boundaries

How Fjall Constructs Consume Roles

Lambda

ECS services

Route53 delegation

Least-Privilege Rules

Scope Secrets Manager ARNs with `-*`

Avoid wildcard actions and resources

Complete Example

Best Practices

Troubleshooting

Inspect a deployed role

Next Steps

Secrets Manager

KMS Key

Lambda Function

ECS Cluster

​Overview

​Resource Classes

​What This Creates

​Basic Usage

​Configuration Options

​Common Patterns

​Lambda execution role

​ECS task role

​EC2 instance role

​Principals

​GitHub Actions OIDC

​Policies

​Inline policies

​Managed policies

​Adding permissions after creation

​Permission boundaries

​How Fjall Constructs Consume Roles

​Lambda

​ECS services

​Route53 delegation

​Least-Privilege Rules

​Scope Secrets Manager ARNs with -*

​Avoid wildcard actions and resources

​Complete Example

​Best Practices

​Troubleshooting

​Inspect a deployed role

​Next Steps

Secrets Manager

KMS Key

Lambda Function

ECS Cluster

Overview

Resource Classes

What This Creates

Basic Usage

Configuration Options

Common Patterns

Lambda execution role

ECS task role

EC2 instance role

Principals

GitHub Actions OIDC

Policies

Inline policies

Managed policies

Adding permissions after creation

Permission boundaries

How Fjall Constructs Consume Roles

Lambda

ECS services

Route53 delegation

Least-Privilege Rules

Scope Secrets Manager ARNs with `-*`

Avoid wildcard actions and resources

Complete Example

Best Practices

Troubleshooting

Inspect a deployed role

Next Steps