AWS Organization Formation (org-formation)

Org-formation uses the nunjucks template engine to generate CloudFormation templates from .njk files. This allows you to use loops, conditionals, and variables within your templates.

To enable templating in a task, you must provide a TemplatingContext. If you want to use templating without passing specific data, you must explicitly set TemplatingContext: {} to trigger the engine.

Example of a Nunjucks template (security-group.njk):

Description: Nunjucks Security group template
AWSTemplateFormatVersion: 2010-09-09
Resources:
  SecurityGroup:
    Type: 'AWS::EC2::SecurityGroup'
    Properties:
      GroupDescription: "Open ports for incoming traffic"
      VpcId: "vpc-1234ABC"
      SecurityGroupIngress:
{% for port in ports %}
        - CidrIp: "0.0.0.0/0"
          FromPort: {{ port }}
          ToPort: {{ port }}
          IpProtocol: tcp
{% endfor %}

SecurityGroupExample:
  Type: update-stacks
  Template: ./security-group.njk
  StackName: SecurityGroupExample
  TemplatingContext:
    ports:
      - 22
      - 80
  DefaultOrganizationBinding:
    Account: "*"
    Region: us-east-1

Org-formation enables resources in different accounts to reference each other (e.g., a CloudTrail in all accounts referencing an S3 bucket in a central Compliance account).

When a resource in one account (Target A) uses !Ref or !GetAtt on a resource bound to a different account (Target B), org-formation automatically handles the plumbing:

1. It creates a CloudFormation Export in the template deployed to Target B.
2. It creates a CloudFormation Parameter in the template deployed to Target A.
3. It maps the Export value to the Parameter during deployment.

Example Workflow

If you have a CloudTrail resource bound to all accounts (Account: "*") and an S3Bucket bound to a ComplianceAccount:

Resources:
  S3Bucket:
    OrganizationBinding: !Ref CloudTrailBucketBinding
    Type: AWS::S3::Bucket
    # ...

  CloudTrail:
    OrganizationBinding: !Ref CloudTrailBinding
    Type: AWS::CloudTrail::Trail
    Properties:
      S3BucketName: !Ref S3Bucket # This cross-account reference is handled by org-formation

The Fn::EnumTargetAccounts function generates an array of values (such as IAM ARNs) for every account included in a specified binding. This is primarily used to implement the principle of least-privilege when setting up cross-account IAM policies or resource policies.

To avoid errors when a binding is empty, you should use the Fn::TargetCount function within a CloudFormation Condition to ensure the resource (like a BucketPolicy) is only created if the binding contains one or more accounts.

# Example: Creating a policy that grants access to all accounts in a binding
Resources:
  BucketReadPolicy:
    Type: AWS::S3::BucketPolicy
    Condition: CreateReadBucketPolicy
    Properties:
      Bucket: !Ref Bucket
      PolicyDocument:
        Statement:
          - Sid: "Read operations on bucket"
            Action:
              - s3:Get*
              - s3:List*
            Effect: "Allow"
            Resource:
              - !Sub "${Bucket.Arn}"
              - !Sub "${Bucket.Arn}/*"
            Principal:
              AWS: Fn::EnumTargetAccounts ReadAccessAccountBinding arn:aws:iam::${account}:root

You can provision new AWS accounts by adding an OC::ORG::Account resource to your organization.yml file.

Key behaviors:

• Identification: Since the AccountId is unknown at creation time, use RootEmail as the unique identifier. The AccountId will be generated and stored in the S3 state file; you can add it to your YAML later if desired.
• Placement: Accounts not assigned to an Organizational Unit (OU) are added to the Organization Root. To add an account to an OU, use the Accounts attribute with a !Ref to the OU's logical name.
• Root Access: The root user will not have a password initially. You must reset the password using the configured RootEmail.
• Automation: You can trigger post-creation workflows (like notifications) by subscribing to the AccountCreated event from the oc.org-formation event source in AWS EventBridge.

MyNewAccount:
  Type: OC::ORG::Account
  Properties:
    AccountName: My New Account
    RootEmail: aws-accounts+new@myorg.com

The OrganizationBinding attribute determines where a CloudFormation resource is deployed within your AWS Organization. You can specify bindings at the resource level, within an OrganizationBindings section, or as a top-level DefaultOrganizationBinding.

Bindings can be combined and are additive (except for ExcludeAccount).

Binding Attributes Reference

Resources:
  Bucket:
    OrganizationBinding:
      Region: eu-west-1
      Account:
       - !Ref Account1
       - !Ref Account2
    Type: AWS::S3::Bucket

An Organization Binding is a core concept that allows you to specify target accounts and regions for resource deployment. When an Annotated CloudFormation template uses a binding, it creates deployment targets for every possible combination of the specified regions and accounts.

Key behaviors:

• A binding with 2 regions and 3 accounts results in 6 targets.
• A binding with 0 regions and 6 accounts results in 0 targets.
• To prevent deployment failures due to missing region specifications, you can use DefaultOrganizationBindingRegion to set a fallback region.

Binding Attributes:

• Region: Specifies the region(s) for the targets.
• Account: Specifies a specific account, a list of accounts, or "*" to include all accounts except the master account.
• IncludeMasterAccount: If true, includes the Master Account in the targets.
• OrganizationalUnit: Includes accounts from one or more Organizational Units.
• AccountsWithTag: Includes accounts that declare a specific tag in the organization.yml file.
• ExcludeOrganizationalUnit: Excludes accounts from specific Organizational Units.
• ExcludeAccount: Excludes specific accounts from the targets.

All references (like !Ref Account1) must use the logical names declared in your organization.yml file.

OrganizationBinding:
  Region: eu-west-1
  Account:
    - !Ref Account1
    - !Ref Account2