Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Running a single AWS account:

Install the Fjall CLI.
Connect your AWS account with fjall connect (see Getting Started).
Scaffold the account infrastructure with fjall create account.

Running an AWS Organisation? Complete these first:

Deploy account infrastructure to your connected AWS account. In an organisation, deploy it to every member account other than the root or platform account. The account baseline holds the deploy role, the monitoring and audit roles, and the shared account-wide resources that applications build on. It runs once per account and region, before any application deploy.

Scaffold the account infrastructure

fjall account deploy deploys the CDK app at fjall/account/infrastructure.ts. fjall create account writes that file:

fjall create account

Flag	Description
`--primary-region <region>`	Primary AWS region for the project (default `us-east-2`).
`--force`	Overwrite scaffold files that already exist with new contents.

Run this once per project. If you scaffolded with fjall create organisation, the account component is already in place, so skip straight to the deploy.

Select the deployment target

A deployment target is an account and region pair, derived from your organisation config. Target names follow <account-name>-<abbreviated-region>, for example production-use1 or development-euw1. There is no manual AWS profile step. List the available targets:

fjall target list

The active target is marked with a ▸ and repeated on a trailing Active: line. Set a different one by name:

fjall target set production-use1

Confirm the active target:

fjall target get

fjall target set writes activeTarget to .fjall/local.json, which is not committed. It requires a Fjall login, and inside a project it requires the project’s organisation binding to match your current credential. Outside a project it refuses unless you pass --create-config. If the target’s region is not yet one of the organisation’s configured regions, it refuses unless you pass -y, --yes, which adds that region to the organisation config.

fjall account deploy auto-selects when the organisation has exactly one member account, so a single account spanning two regions still resolves without a prompt and you can skip this step. To override the active target for a single deploy, pass --target <name>. An unknown target name fails with the list of valid names, never a silent fallback.

Deploy the account

From the root of your project, run:

fjall account deploy

To deploy a specific member account without changing the active target, override it inline:

fjall account deploy --target production-use1

Tier deploys are noun-verb. fjall deploy account is retired and fails before authentication with a teaching error. fjall deploy takes application names only.

What happens

The deploy runs five steps:

Authenticating with AWS: mints short-lived credentials for the resolved target.
Connect securely: establishes the AWS context for the account and region.
Prepare environment: synthesises the CloudFormation template and compares template hashes.
Deploy infrastructure: applies the account stack.
Enable monitoring: wires up the account monitoring resources.

The account stack provisions:

Resource	Purpose
OIDC deploy role	Lets Fjall assume a scoped role in this account without stored keys. Capped by a permissions boundary by default.
Account monitoring role	Read-only role Fjall uses to collect account health and posture data.
Account audit role	Read-only role for compliance and asset discovery.
Management-events CloudTrail	Records management-plane API activity for the account.
Default container image helper	Seeds a placeholder image so ECS services can start before the first application build.
Shared alarm topic	Single SNS topic that account and application alarms publish to.
S3 Block Public Access	Account-level block on public S3 access.
Disaster recovery resources	Created for `production` and `compliance` accounts when a DR region is set.

The IAM globals (deploy role, monitoring role, audit role, CloudTrail, S3 Block Public Access) carry fixed names, so they are created only in the account’s home region. Other regions get the region-local resources. VPCs and security groups are not part of this stack. Fjall creates them per application at application deploy time. Security services (GuardDuty, Security Hub, AWS Config recorder, IAM Access Analyzer, Amazon Inspector) render into the account scaffold only when it was generated by fjall create organisation --security <tier>. A standalone fjall create account scaffold carries no governance profile.

The deploy role is capped by a permissions boundary

The account stack creates FjallDeployBoundary<orgId>, an account-global customer-managed policy, and attaches it to the FjallDeploy<orgId> role as its permissions boundary. This happens by default, whether or not the scaffold carries a governance profile: a scaffold with no securityTier still gets the hardened boundary, because the tier chooses which ceiling the role has, never whether it has one. The full policy, the three tiers and what each denies are documented on fjall connect, which installs the same policy through the quick-create template. To change the tier, or to opt out, edit the Account props in fjall/account/infrastructure.ts:

const account = OrganisationFactory.build("Account", {
  type: "account",
  securityTier: "compliance", // foundation | compliance | hardened (default)
})(app);

const account = OrganisationFactory.build("Account", {
  type: "account",
  deployRoleBoundary: false, // no boundary; the deploy role keeps unbounded AdministratorAccess
})(app);

fjall create organisation --security <tier> writes securityTier into this file for you. There is no CLI flag for either setting on a deploy: both are properties of the infrastructure you are deploying, so they live in the file.

The opt-out is a create-time decision. Setting deployRoleBoundary: false on a role that is already capped fails the deploy, because the boundary denies iam:DeleteRolePermissionsBoundary — the role cannot remove its own ceiling. Uncapping an existing role is an administrator step from a principal outside the boundary. Setting securityTier and deployRoleBoundary: false together contradicts itself and fails at synth.

The boundary lands in two passes

The policy has to exist in the account before a bootstrap can point CDK’s execution role at it, so a new account converges over two deploys:

Pass	What it caps
First deploy into the account	The account stack creates the policy and caps `FjallDeploy<orgId>`. The bootstrap ran before the policy existed, so the CDK execution role is not capped yet
Next deploy of any kind into that region	The bootstrap finds the policy and caps `cdk-hnb659fds-cfn-exec-role-<account id>-<region>`

Bootstrapping is per account and region, so each region converges on its own schedule. A region you deploy into later is capped by the first deploy that reaches it — usually an application deploy — not retroactively by the account deploy. Nothing is ever silently left uncapped. The first pass logs the state and the cure:

Deploy boundary FjallDeployBoundary<orgId> not found in account <account id> — the CDK execution role
keeps its current cap; none on a first bootstrap. The Account or Platform stack creates the policy;
the next deploy after that stack lands caps the role

and the second logs the cap being applied:

Bootstrapping with the deploy boundary FjallDeployBoundary<orgId> on the CDK execution role

A deploy that cannot read the policy — a throttled or denied iam:GetPolicy — warns and bootstraps without passing the boundary flag. That never loosens anything: CloudFormation carries the toolkit stack’s previous value through unchanged, so an already-capped role stays capped. A CDK line reading Removing existing permissions boundary during such a run is misleading and can be ignored; the parameter is carried over, not cleared.

Check which roles are capped

ListRoles does not return the PermissionsBoundary field, so any check built on a role listing reports every role as uncapped. Read it per role with get-role instead, through fjall aws exec so the call runs on Fjall-minted credentials:

# The deploy role, which the first deploy into the account caps
fjall aws exec --target production-use2 -- \
  aws iam get-role --role-name FjallDeploy<orgId> --query Role.PermissionsBoundary

# The CDK execution role for that account and region, which the next deploy caps
fjall aws exec --target production-use2 -- \
  aws iam get-role --role-name cdk-hnb659fds-cfn-exec-role-<account id>-us-east-2 \
  --query Role.PermissionsBoundary

A capped role answers with the boundary object — PermissionsBoundaryType of Policy and a PermissionsBoundaryArn ending in FjallDeployBoundary<orgId>. An uncapped one answers null. Run it once per deployment target to see the whole estate. fjall target list gives you the target names, and fjall org get gives you the organisation id. To read the policy itself, including which version is live and how many roles it caps:

fjall aws exec --target production-use2 -- \
  aws iam get-policy --policy-arn arn:aws:iam::<account id>:policy/FjallDeployBoundary<orgId>

Output

Interactive runs finish with a step tick-list titled Deploying account: account, then a Next Steps section pointing at fjall deploy. When the template is unchanged you see No changes to deploy. Your infrastructure is up to date. instead. Non-interactive runs print a summary block:

── Summary ───────────────────────────────
  Result:   ✓ account deployed successfully
  Duration: 4m 12s
──────────────────────────────────────────

Options

Flag	Description
`--target <name>`	Deploy to a specific member account and region instead of the active target.
`-e, --environment <env>`	Workload stage recorded for a standalone account registration: `production`, `staging`, `development`, `platform` or `compliance`. Rejected for an org-membered account.
`-f, --force`	Redeploy even when no infrastructure changes are detected.
`--skip-confirmation`	Skip deployment confirmation prompts. On a standalone account this answers the stage picker with the default, `production`.
`--non-interactive`	Force plain CLI output with no interactive UI.
`-v, --verbose`	Enable verbose output.
`--agent`	Enable agent output mode.
`--budget <level>`	Output budget: `minimal`, `compact`, or a token count.
`--fields <fields>`	Select exactly these output fields.
`--full`	Disable content truncation.

--region, --all-regions, --skip-migrations and --skip-build belong to the application command, fjall deploy <app>. The tier leaves register only their own flags, so passing one of those here fails with error: unknown option. Use --target <name> instead, which carries the region.

“Standalone” here means an account deployed before any provider account is registered with an organisation. Once the account is org-membered, its stage lives in the organisation registry and is set by fjall connect or the web app. Passing -e, --environment to an org-membered account fails with a teaching error rather than restaging it.

Next Steps

Create Application

Scaffold your first application’s infrastructure.

Deploy Application

Deploy an application to your managed AWS account.

Understanding Profiles

See how Fjall derives AWS credentials and deployment targets.

Deployment Safety

Review the approval gates that guard destructive changes.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Deploy Account

Scaffold the account infrastructure

Select the deployment target

Deploy the account

What happens

The deploy role is capped by a permissions boundary

The boundary lands in two passes

Check which roles are capped

Output

Options

Next Steps

Create Application

Deploy Application

Understanding Profiles

Deployment Safety

​Scaffold the account infrastructure

​Select the deployment target

​Deploy the account

​What happens

​The deploy role is capped by a permissions boundary

​The boundary lands in two passes

​Check which roles are capped

​Output

​Options

​Next Steps

Create Application

Deploy Application

Understanding Profiles

Deployment Safety

Scaffold the account infrastructure

Select the deployment target

Deploy the account

What happens

The deploy role is capped by a permissions boundary

The boundary lands in two passes

Check which roles are capped

Output

Options

Next Steps