Connecting AWS to Landfall

Landfall reads your AWS telemetry (CloudWatch metrics and logs, resource state) while Beacon, its diagnosis agent, works an incident. The recommended path hands over no key at all: you create a read-only IAM role in your account with our ready-made module, Landfall assumes it at read time, and deleting the role revokes everything instantly.

What you'll need

• Your own AWS credentials, allowed to create an IAM role in the account you're connecting.
• An admin seat on your Landfall organization.

Connect with one command (recommended)

The landfall CLI runs the whole flow: it fetches Landfall's principal, generates a strong external id, creates the read-only role with your own AWS CLI from the pinned published template, registers the connection, and health-checks it. You type three commands and zero ARNs:

brew tap landfalls-ai/landfall && brew install landfall
landfall login
landfall connect aws

• Terraform shop? landfall connect aws --terraform prints the pinned module snippet instead of running anything, and takes the resulting role ARN back.
• Several accounts? landfall connect aws --management --member <accountId> declares member accounts on a management connection and prints the exact per-member role instructions.
• At no point does Landfall see or store an AWS credential: role creation runs under your own AWS identity, and the command tells you which account it connected.

Manual alternative

Everything the command does, by hand. The role is deliberately auditable in one screen: the AWS-managed ReadOnlyAccess policy, a trust statement pinned to Landfall's platform principal, and a required external id so nobody else can ask Landfall to assume your role on their behalf (confused-deputy protection). Both variants of the published module produce the identical role.

1. Get the two Landfall-side values

   The module needs Landfall's platform principal ARN (the identity that will assume your role, provided by Landfall; ask your Landfall contact or see your deployment's documentation) and an external id you generate yourself (any hard-to-guess string of 8+ characters, e.g. openssl rand -hex 16). You will enter the same external id on both sides.

2. Create the role: two commands, nothing to clone

   With your own AWS CLI credentials (CloudFormation variant: no Terraform needed, no repository visit needed):

   curl -fsSLo landfall-role.yaml \
     https://raw.githubusercontent.com/landfalls-ai/landfall-aws-onboarding/v0.1.0/cloudformation/landfall-readonly-role.yaml
   
   aws cloudformation deploy \
     --template-file landfall-role.yaml \
     --stack-name landfall-onboarding \
     --capabilities CAPABILITY_NAMED_IAM \
     --parameter-overrides \
       LandfallPrincipalArn=<landfall platform principal> \
       ExternalId=<your generated external id>
   
   aws cloudformation describe-stacks --stack-name landfall-onboarding \
     --query "Stacks[0].Outputs[?OutputKey=='RoleArn'].OutputValue" --output text

   Or, if your infrastructure is Terraform, the same role as a pinned module:

   module "landfall_onboarding" {
     source                 = "github.com/landfalls-ai/landfall-aws-onboarding//terraform?ref=v0.1.0"
     landfall_principal_arn = "<landfall platform principal>"
     external_id            = "<your generated external id>"
   }

   Want to read what you're about to run first? The template and module are ~50 audited lines each in landfalls-ai/landfall-aws-onboarding. One role, the AWS-managed ReadOnlyAccess policy, a pinned trust statement, and nothing else.

3. Open Settings → Integrations → AWS (CloudWatch)

   Set Authentication to role, enter the module's role_arn output, your region, and the same external id you generated above.

   Settings → Integrations → AWS (CloudWatch)

   

4. Fill in the role and save

   The values below are examples. Use your own role's ARN, your own region, and the external id you generated, never anyone else's.

   Settings → Integrations → AWS (CloudWatch)

   

5. Confirm it's connected

   Back on the Integrations list, AWS (CloudWatch) shows Configured alongside a live healthy check.

   Settings → Integrations

   

Alternative: access keys

Where role assumption isn't possible, the same panel also accepts an access key id + secret for a read-only IAM user: set Authentication to keys instead of role, and the Role ARN and External id fields go unused. Landfall stores the secret in its dedicated secret manager, never in its database, but a long-lived key is still a long-lived key: prefer the role.

Multiple accounts

Connect as many AWS accounts as you like: each shows up as its own named connection, and Beacon addresses reads to a specific one. Two shapes:

• One connection per account. Repeat the steps above in each account and add each role as a named connection (e.g. prod, staging).
• A management account reaching member accounts. Create the role in your management account, then create a role with the same name (e.g. landfall-readonly) in each member account, trusting the management role. Declare the members on the connection: memberRoleName plus a memberAccounts list of account ids and labels, and each member becomes its own queryable target under the one connection. Members are always declared explicitly; Landfall never enumerates your AWS organization.

What Beacon does with the connection

When an incident opens, the agent's working context is built from everything your organization has connected: every source, every connection, each with its own operations. With AWS connected it can list and read CloudWatch metrics and log groups from the specific account a read names, cite them as provenance in its findings, and chart them on the incident canvas. It is read-only by construction: there is no write tool, and every proposed remediation waits for a human approval.