Documentation

• 1: Overview
• 2: Getting Started
• 2.1: Bootstrap a New Account
• 2.2: Set Up Your Local Repository
• 2.3: Importing an Existing Organization
• 2.4: Example tfvars
• 3: Examples
• 4: Concepts
• 5: Account Configurator
• 6: Tasks
• 6.1: Adding a New Account
• 6.2: Creating Policies
• 7: Granted Support
• 8: Reference
• 8.1: Module Documentation
• 8.2: Parameter Reference
• 9: Contribution Guidelines
• 10: Releases

1 - Overview

What is Org Kickstart?

Org Kickstart is an opinionated Terraform module for bootstrapping and managing AWS Organizations. It is PrimeHarbor’s alternative to AWS Control Tower — designed to give you the good parts of a landing zone without the cost, complexity, and lock-in that Control Tower brings.

Deployed into a brand new AWS Management (Payer) account, a single terraform apply can stand up a fully governed AWS Organization with security services enabled, organizational guardrails in place, and an account factory ready to provision new accounts.

Why not just use Control Tower?

Control Tower is a massive beast designed to support highly regulated enterprises. For most organizations, it brings significant drawbacks:

• Expensive: Heavy reliance on AWS Config means costs scale with the number of accounts and regions.
• Inflexible: Modifications require navigating AWS Service Catalog customizations.
• Slow to update: Features like Organization CloudTrail and GuardDuty Delegated Admin lagged behind AWS best practices for years.
• Complex: You effectively need a PhD in AWS Service Catalog to change anything.

Most organizations deploy Control Tower because their AWS Solutions Architect recommended it, or because they needed an account factory. Org Kickstart gives you the account factory, the security posture, and the governance — without the baggage.

What Org Kickstart does

Org Kickstart deploys and manages:

1. Security Account — Creates a dedicated security account and delegates GuardDuty, Macie, Inspector, Security Hub, SSO, and CloudFormation StackSets to a dedicated Security Account. Configures all security services in every default region across all accounts.
2. CloudTrail — Creates a CloudTrail bucket in the Security Account and enables an Organizations CloudTrail in the Management Account.
3. Alternate Contacts — Sets Billing, Operations, and Security contacts for all AWS accounts.
4. Organizational Units — Creates four default OUs (Workloads, Governance, Sandbox, Suspended) plus any custom OUs you define.
5. AI Opt-Out Policy — Creates and applies a default AI opt-out policy at the root OU.
6. Account Management — Manages AWS accounts and OU placement from Terraform.
7. Audit Role — Deploys an Audit Role via CloudFormation StackSet to all accounts, trusting the Security Account.
8. Billing Reports — Creates an S3 bucket for billing data and an Athena-compatible CUR report.
9. Organization Services — Enables all important AWS Organization Integrated Services.
10. Org Policies — Manages Service Control Policies, Declarative Policies, and Resource Control Policies with Terraform templating support.
11. SSO / Identity Center — Creates an AdministratorAccess Permission Set, an admin group, and assigns both to every account.

What is required vs. optional?

Cannot be disabled:

• Security Account
• Four default OUs (Governance, Workloads, Sandbox, Suspended)
• AI Opt-Out Policy
• Core Organization Integrated Services

Can be disabled via variables:

• CloudTrail management: cloudtrail_bucket_name = null
• SSO management: disable_sso_management = true
• Audit Role StackSet: deploy_audit_role = false
• Security services: security_services object with disable_* flags
• CUR reports: cur_report_frequency = "NONE"
• Alternate contacts: omit contact blocks from tfvars

Where should I go next?

• Getting Started — Bootstrap your account and run your first deploy
• Reference — Full variable and policy reference

2 - Getting Started

This section walks you through getting Org Kickstart deployed into a new AWS account.

Prerequisites

Before running Org Kickstart you need:

• Terraform >= 1.0 (< 2.0)
• AWS CLI configured with credentials for the Management (Payer) account
• An S3 bucket for Terraform remote state
• A few manual “artisanal” steps completed in the AWS console (see Bootstrap)

Steps

1. Complete the Bootstrap steps in the AWS Console
2. Set up your local repository — copy the local-deploy sample, pin the module version, and create your <env>.tfvars / <env>.tfbackend
3. Initialize Terraform:

   make env=your-org tf-init
   

4. Create the Security Account first (required before full apply):

   terraform apply -var-file="your-org.tfvars" -target module.security_account
   

5. Deploy everything:

   make env=your-org tf-execute
   

   This runs tf-plan followed by tf-apply — saving the plan, applying it, and writing output-your-org.json to your state bucket.

For subsequent updates, use:

make env=your-org update

Using with an Existing Organization

If you already have an AWS Organization, see Importing an Existing Org for guidance on importing existing resources into Terraform state.

Example tfvars

See the Reference page for a full annotated example. The examples/local-deploy directory in the repository contains a sample layout with a Makefile, backend config template, and helper scripts for running Org Kickstart from your workstation. To pin to a specific release, see Releases.

2.1 - Bootstrap a New Account

Before Org Kickstart can be deployed, a few steps must be completed via ClickOps in your new AWS Management (Payer) account. Terraform cannot perform these actions automatically.

Root Account Tasks

Log into the root user of your new AWS “payer” account and complete the following:

1. Add MFA to root
2. Enable IAM access to billing
3. Go to Organizations and create an Organization
4. Go to AWS IAM Identity Center (SSO) and enable it
5. Add yourself as a user in Identity Center
6. Create a Permission Set named TempAdministratorAccess (4-hour session recommended)
7. Assign the Permission Set to the Payer/Management Account for your user
8. Activate trusted access for CloudFormation StackSets — click “Activate trusted access with AWS Organizations to use service-managed permissions” (must be done via console)

Log out of root and never use it again.

Note: As of June 2026, aws login works for the root user with Terraform — but the root user cannot assume IAM roles, and Org Kickstart assumes roles (for example OrganizationAccountAccessRole into the security account). That is why you must run Terraform as an IAM Identity Center user or an IAM User rather than as root.

On Your Machine

1. Check email and activate your IAM Identity Center account
2. Add MFA to your Identity Center account
3. Configure AWS credentials in your environment:

   aws configure sso
   # or
   export AWS_PROFILE=your-sso-profile
   

4. Create the S3 bucket that will hold the Terraform state. It must exist before the first terraform init, since the S3 backend lives in it:

   aws s3 mb s3://org-kickstart-fooli
   

   This is the bucket you set as backend_bucket. By default (manage_state_bucket = true) Org Kickstart then adopts it into Terraform and enforces versioning, public-access-block, and encryption — see the Parameter Reference.

You are now ready to deploy Org Kickstart.

Next Steps

• Create your tfvars file — see the Reference for all variables and a full example
• Run terraform init and your first apply — see Getting Started

2.2 - Set Up Your Local Repository

Once the Bootstrap steps are complete, set up a private repository to hold your organization’s configuration and deploy Org Kickstart from your workstation.

1. Copy the sample

Copy the examples/local-deploy directory into your own private git repository. It provides:

• main.tf — calls the Org Kickstart module
• import.tf — adopts the AWS Organization, the payer account, and the state bucket
• Makefile — the env-based workflow (below)
• sample.tfvars / sample.tfbackend — templates to copy
• scripts/ and granted.yml — helper scripts and the Granted registry manifest

2. Pin the module version

main.tf pins the module to a tagged release:

source = "github.com/primeharbor/org-kickstart?ref=0.3.1"

See Releases for tracking the rolling latest branch versus pinning to a tag.

3. Create your environment files

Pick a short environment name ($env) for your org — for example fooli. Copy the samples so their names match it:

cp sample.tfvars    fooli.tfvars
cp sample.tfbackend fooli.tfbackend

• Edit fooli.tfvars — see the Parameter Reference and the Example tfvars for all options.
• Set the state bucket name in fooli.tfbackend — the bucket you created with aws s3 mb during Bootstrap. By default (manage_state_bucket = true) Org Kickstart adopts and manages it.

4. The Makefile workflow

Every target takes env=<your env>:

make env=fooli tf-init      # terraform init with your backend config
make env=fooli tf-plan      # write a saved plan
make env=fooli tf-apply     # apply the saved plan and write outputs
make env=fooli tf-execute   # tf-plan followed by tf-apply
make env=fooli update       # tf-init + tf-execute — your day-to-day command

The first apply creates the organization structure, OUs, and the security account.

Next steps

• Granted Support — generate AWS CLI profiles for your accounts and share them with your team.
• Account Configurator — automatically harden new accounts on creation.
• Adopting an organization that already exists? See Importing an Existing Organization.

2.3 - Importing an Existing Organization

Org Kickstart can manage an existing AWS Organization. Several resources must be imported into Terraform state before running terraform apply.

The minimum required imports are the organization, the management account, and the Security Account (if it already exists). You may also want to import existing accounts, CloudTrail buckets, billing buckets, and SSO configuration.

Automated Import

The scripts/import_org.sh script generates an import-org.tf file and a TFVars snippet for your existing accounts.

# From the org-kickstart directory
./scripts/import_org.sh

Review the generated import-org.tf carefully before running Terraform.

Steps

1. Run import_org.sh and review import-org.tf
2. Add your CloudTrail or billing bucket to the import file if applicable
3. Review SCPs you want to import:

   aws organizations list-policies --filter SERVICE_CONTROL_POLICY \
     --query 'Policies[].[Id,Name]' --output text
   

4. Iterate with tf-plan until no unwanted changes appear:

   make env=your-org tf-plan
   make env=your-org tf-show    # review the plan output
   

5. Once satisfied, apply:

   make env=your-org tf-apply
   

6. Incrementally enable additional features

Manual Import Examples

Organizational Units

ROOT_OU=$(aws organizations list-roots --query Roots[0].Id --output text)
aws organizations list-organizational-units-for-parent \
  --parent-id $ROOT_OU \
  --query 'OrganizationalUnits[].[Id,Name]' --output text

import {
  to = module.organization.aws_organizations_organizational_unit.TF_VARS_KEY
  id = "ou-xxxx-xxxxxxxx"
}

IAM Identity Center (SSO)

To opt out of managing an existing Identity Center, set disable_sso_management = true in your tfvars. This is recommended for existing orgs with complex SSO configurations.

IDENTITY_STORE_ID=$(aws sso-admin list-instances \
  --query Instances[0].IdentityStoreId --output text)
SSO_INSTANCE_ARN=$(aws sso-admin list-instances \
  --query Instances[0].InstanceArn --output text)

import {
  to = module.organization.aws_identitystore_group.admin_group
  id = "$IDENTITY_STORE_ID/$GROUP_ID"
}
import {
  to = module.organization.aws_ssoadmin_permission_set.admin_permission_set
  id = "$PERMISSION_SET_ARN,$SSO_INSTANCE_ARN"
}
import {
  to = module.organization.aws_ssoadmin_managed_policy_attachment.admin_policy_attachments
  id = "arn:aws:iam::aws:policy/AdministratorAccess,$PERMISSION_SET_ARN,$SSO_INSTANCE_ARN"
}

CloudTrail

aws cloudtrail list-trails --query Trails[].TrailARN --output text

import {
  to = module.organization.aws_s3_bucket.cloudtrail_bucket[0]
  id = "YOUR_EXISTING_BUCKET_NAME"
}
import {
  to = module.organization.aws_cloudtrail.org_cloudtrail[0]
  id = "TRAIL_ARN"
}

Service Control Policies

aws organizations list-policies --filter SERVICE_CONTROL_POLICY \
  --query 'Policies[].[Id,Name]' --output text

# Get OUs targeted by a policy
aws organizations list-targets-for-policy --policy-id p-xxxxxx

import {
  to = module.organization.module.scp["POLICY_BLOCK_IDENTIFIER_FROM_TFVARS"].aws_organizations_policy.org_policy
  id = "p-xxxxxx"
}

Disabling Features for Initial Import

When importing an existing org, you may want to temporarily disable features to prevent unintended changes on the first apply:

• CloudTrail: cloudtrail_bucket_name = null
• SSO: disable_sso_management = true
• Audit Role StackSet: deploy_audit_role = false
• Security Services: use the security_services block with disable_* flags

2.4 - Example tfvars

The following is a complete example tfvars file showing all major configuration options. Copy this as a starting point and customize for your organization.

organization = {
  organization_name                 = "my-org"
  payer_name                        = "My Org Management Account"
  payer_email                       = "aws+payer@example.com"
  security_account_name             = "my-org-security"
  security_account_root_email       = "aws+security@example.com"
  cloudtrail_bucket_name            = "my-org-cloudtrail"
  cloudtrail_loggroup_name          = "CloudTrail/DefaultLogGroup"
  billing_data_bucket_name          = "my-org-cur"
  cur_report_frequency              = "DAILY"   # DAILY, HOURLY, or MONTHLY
  session_duration                  = "PT8H"
  admin_permission_set_name         = "AdministratorAccess"
  admin_group_name                  = "AllAdmins"
  disable_sso_management            = false
  deploy_audit_role                 = true
  audit_role_name                   = "security-audit"
  audit_role_stack_set_template_url = "https://s3.amazonaws.com/pht-cloudformation/aws-account-automation/AuditRole-Template.yaml"
  declarative_policy_bucket_name    = "my-org-account-status"
  vpc_flowlogs_bucket_name          = "my-org-flowlogs"
  macie_bucket_name                 = "my-org-macie-findings"

  # Custom OUs (in addition to the four required OUs)
  organization_units = {
    "Platform" = {
      name             = "Platform"
      is_child_of_root = true
    }
  }

  # AWS Accounts
  accounts = {
    dev = {
      account_name          = "my-org-dev"
      account_email         = "aws+dev@example.com"
      monthly_budget_amount = 500
    }

    prod = {
      account_name   = "my-org-prod"
      account_email  = "aws+prod@example.com"
      parent_ou_name = "Workloads"
    }

    sandbox = {
      account_name   = "my-org-sandbox"
      account_email  = "aws+sandbox@example.com"
      parent_ou_name = "Sandbox"
    }

    sso = {
      account_name    = "my-org-sso"
      account_email   = "aws+sso@example.com"
      parent_ou_name  = "Governance"
      delegated_admin = ["sso.amazonaws.com"]
    }
  }

  # Alternate contacts applied to all accounts (can be overridden per account)
  global_billing_contact = {
    name          = "Finance Team"
    title         = "CFO"
    email_address = "billing@example.com"
    phone_number  = "+14041234567"
  }

  global_security_contact = {
    name          = "Security Team"
    title         = "CISO"
    email_address = "security@example.com"
    phone_number  = "+14041234567"
  }

  global_primary_contact = {
    full_name       = "IT Operations"
    company_name    = "My Org, Inc."
    address_line_1  = "123 Main Street"
    city            = "Atlanta"
    state_or_region = "GA"
    postal_code     = "30332"
    country_code    = "US"
    email_address   = "aws@example.com"
    phone_number    = "+14041234567"
  }

  # Service Control Policies
  service_control_policies = {
    deny_root = {
      policy_name        = "DenyRoot"
      policy_description = "Denies use of root user"
      policy_json_file   = "policies/DenyRootSCP.json"
    }

    security_controls = {
      policy_name        = "DefaultSecurityControls"
      policy_description = "Base security controls for all accounts"
      policy_json_file   = "policies/SecurityControlsSCP.json.tftpl"
      policy_vars = {
        audit_role_name = "security-audit"
      }
    }
  }

  # Resource Control Policies
  resource_control_policies = {
    s3_data_perimeter = {
      policy_name        = "S3DataPerimeter"
      policy_description = "Restricts S3 to principals inside the org"
      policy_json_file   = "policies/RCP_S3DataPerimeter.json.tftpl"
      policy_vars = {
        org_id = "o-xxxxxxxxxxxx"
      }
    }
  }

  # Declarative Policies
  declarative_policies = {
    deny_public_ami = {
      policy_name        = "Block_Public_AMIs"
      policy_description = "Deny public sharing of all AMIs"
      policy_type        = "DECLARATIVE_POLICY_EC2"
      policy_json_file   = "policies/EC2ImageBPA_DCP.json"
      policy_targets     = ["Workloads", "Governance", "Sandbox"]
    }
  }

  # Security Services
  security_services = {
    disable_guardduty   = false
    disable_securityhub = false
    disable_macie       = false
  }

  # CloudFormation stacks to deploy into the payer account.
  # Use this for billing notifications, cost alarms, or other payer-scoped
  # automation. Exactly one of template_file or template_url is required.
  payer_cloudformation_stacks = {
    billing_alerts = {
      stack_name    = "slack_billing_alerts"
      template_file = "cloudformation/slack-Template.yaml"
      regions       = ["us-east-1"]
      parameters = {
        pExecutionRate = "cron(0 09 * * ? *)"
        # JSON parameter values can use a heredoc; the module canonicalizes
        # JSON-valued parameters so whitespace differences don't cause drift.
        pEventInput = <<-EOT
          {
            "threshold": "10",
            "alert_percent": "20"
          }
        EOT
        pSlackWebhookSecret = "SlackWebHook"
        pRuleState          = "ENABLED"
        pAccountDescription = "My-Payer"
      }
    }
  }

  # CloudFormation stacks to deploy into the security account via the
  # OrganizationAccountAccessRole. Same schema as payer_cloudformation_stacks.
  security_account_stacks = {
    findings_processor = {
      stack_name    = "security-findings-processor"
      template_file = "cloudformation/findings-processor-Template.yaml"
      regions       = ["us-east-1"]
      parameters = {
        pSlackWebhookSecret = "SlackWebHook"
        pSeverityThreshold  = "MEDIUM"
      }
    }
  }

  # Billing Alerts
  billing_alerts = {
    levels = {
      level1  = 100
      level2  = 500
      oh_shit = 1000
    }
    subscriptions = ["billing-alerts@example.com"]
  }

  budget_defaults = {
    alert_recipients      = ["finance@example.com"]
    currency              = "USD"
    warning_percentage    = 80
    organizational_budget = 1000
  }
}

backend_bucket = "my-org-terraform-state-123456789012"

Backend Config File

Create a my-org.tfbackend file alongside your tfvars:

bucket = "my-org-terraform-state-123456789012"
key    = "org-kickstart.tfstate"
region = "us-east-1"

Then initialize with:

terraform init -backend-config="my-org.tfbackend"

3 - Examples

Local Deploy Sample

The examples/local-deploy directory contains a sample layout for managing your organization with Terraform from your workstation via its Makefile. It shows how to structure your organization-specific configuration (<env>.tfvars, <env>.tfbackend) alongside the module.

Sample tfvars

See the Example tfvars page for a full annotated example configuration file covering all major options.

Policy Library

Ready-to-use policy files are available in the policies/ directory:

• DenyRootSCP.json — Deny root user access
• SecurityControlsSCP.json.tftpl — Base security guardrails
• DisableRegionsPolicy.json.tftpl — Region restrictions
• RCP_S3DataPerimeter.json.tftpl — S3 data perimeter
• EC2IMDSv2Enforce_DCP.json — IMDSv2 enforcement
• And more…

Importing an Existing Organization

See Importing an Existing Organization for a step-by-step guide on adopting Org Kickstart in an existing AWS Organization.

4 - Concepts

AWS Organizations Structure

Org Kickstart manages resources in two AWS accounts simultaneously using Terraform’s multi-provider pattern:

• Management (Payer) Account — Where Terraform runs. Contains the Organization, OUs, SCPs, RCPs, Declarative Policies, CloudTrail, and SSO/Identity Center.
• Security Account — A dedicated account that is Delegated Administrator for GuardDuty, Macie, Inspector, Security Hub, CloudFormation StackSets, and optionally SSO.

Required Organizational Units

Four OUs are always created and cannot be disabled:

Policy Types

AWS Organizations supports three types of preventive controls, all managed by Org Kickstart:

All three are defined using the same Terraform structure and support .tftpl templating.

Security Services

Org Kickstart enables and configures the following security services across all default AWS regions and all accounts in the organization:

• GuardDuty — Threat detection. Payer and Security account both run detectors.
• Security Hub — Aggregated security findings. Security Account is delegated admin.
• Inspector — Vulnerability management. Security Account is delegated admin.
• Macie — S3 data security. Security Account is delegated admin.

Audit Role

A cross-account audit role is deployed to every account via CloudFormation StackSets. The role trusts the Security Account, allowing centralized read access for security tools and audits without needing IAM users in every account.

Account Factory Pattern

New AWS accounts are defined in the accounts map in tfvars. The account module handles everything automatically:

1. Creates the AWS Organizations account
2. Places it in the correct OU
3. Assigns SSO access (via Identity Center group and Permission Set)
4. Sets billing, operations, and security alternate contacts
5. Creates a budget with alert thresholds
6. Applies SCPs/RCPs/Declarative Policies inherited from the parent OU

5 - Account Configurator

When AWS Organizations creates a new account, a number of AWS-recommended best practices are not turned on by default. The pht-account-configurator is a Step Function + Lambda that listens for the “account created” EventBridge event and configures each new account for you. Org Kickstart can deploy and manage it as an optional add-on.

What it configures

Driven by a config file (see below), the configurator can:

• Set a CIS-compliant IAM password policy.
• Enable account-wide S3 Block Public Access.
• Enable EBS snapshot Block Public Access in every enabled region.
• Enable EBS default encryption in every enabled region.
• Delete the default VPCs in every region (except regions you mark to preserve, and any VPC that still has an ENI in it).

Sections omitted from the config file are simply skipped.

How Org Kickstart deploys it

Set the account_configurator block in your organization object. When present, Org Kickstart creates a CloudFormation stack (org-kickstart-account-configurator) from the packaged template and uploads your config file to the Terraform state bucket. Omit the block (or set it to null) to disable the feature.

account_configurator = {
  template                    = "https://s3.amazonaws.com/<state-bucket>/pht-account-configurator/AccountFactory-Template-Transformed-<version>.yaml"
  account_factory_config_file = "<env>-account-config.yaml"
}

Setting it up

The configurator is maintained in its own repo and pulled into your Org Kickstart deployment repo as a git submodule. The examples/local-deploy Makefile ships an account-configurator target that does the rest.

1. Add the submodule (once):

   git submodule add git@github.com:primeharbor/pht-account-configurator.git pht-account-configurator
   

2. Run the target. Using an environment named fooli:

   make env=fooli account-configurator
   

   This will:

   • check out the submodule if needed;
   • seed fooli-account-config.yaml from the submodule’s sample if you don’t already have one;
   • package the configurator’s CloudFormation template into your Org Kickstart state bucket; and
   • point account_configurator.template and account_configurator.account_factory_config_file in fooli.tfvars at the freshly packaged template and your config file.

3. Review and deploy. Edit fooli-account-config.yaml to taste, then apply as usual:

   make env=fooli tf-plan
   make env=fooli tf-apply
   

   Re-run make env=fooli account-configurator whenever you want to ship a new version of the Lambda/template; it repackages and updates the template URL, and the next apply rolls it out.

The configuration file

<env>-account-config.yaml controls what the Lambda does. A full example:

# Configure the IAM Password Policy per CIS Benchmarks
account_password_policy:
  update_account_password_policy: true
  password_policy:
      MinimumPasswordLength: 24
      RequireSymbols: True
      RequireNumbers: True
      RequireUppercaseCharacters: True
      RequireLowercaseCharacters: True
      AllowUsersToChangePassword: True
      MaxPasswordAge: 90
      PasswordReusePrevention: 24
      HardExpiry: False

# Delete Default VPCs
default_vpc:
  delete_default_vpc: true
  # Regions in this list will keep their default VPCs
  preserve_vpc_regions:
    - "us-east-1"
    - "eu-central-1"

# Enable Default Encryption of EBS in all enabled regions
enable_ebs_default_encryption: true

# Enable Block Public Access for EBS snapshots in all enabled regions
enable_ebs_block_public_access: true

# Enable Account Wide S3 Block Public Access
enable_account_s3_block_public_access:
    BlockPublicAcls: True
    IgnorePublicAcls: True
    BlockPublicPolicy: True
    RestrictPublicBuckets: true

Running against existing accounts

The Step Function normally runs on account creation, but you can also trigger it manually against an existing account. Be aware of two risks before doing so:

• Enabling account-wide S3 Block Public Access can break legitimately public S3 buckets.
• Enabling EBS default encryption may interact with existing custom KMS key configurations.

Pair S3 Block Public Access with an SCP that prevents accounts from disabling it, and route any genuinely public content to a dedicated account.

6 - Tasks

This section contains task-oriented guides for common Org Kickstart operations.

Common Tasks

• Adding a New Account — Add a new AWS account to your organization
• Creating Policies — Create and attach SCPs, RCPs, and Declarative Policies
• Adding Custom OUs — Define additional Organizational Units

6.1 - Adding a New Account

Adding a new AWS account is the most common operation in Org Kickstart. All account configuration lives in the accounts map in your tfvars file.

Steps

1. Add an entry to the accounts map in your tfvars file:

   accounts = {
     # ... existing accounts ...
   
     my_new_account = {
       account_name  = "my-org-new-account"
       account_email = "aws+new-account@example.com"
       parent_ou_name = "Workloads"
       monthly_budget_amount = 500
     }
   }
   

2. Plan and apply:

   make env=your-org tf-execute
   

   Or step-by-step to review the plan before applying:

   make env=your-org tf-plan
   make env=your-org tf-show
   make env=your-org tf-apply
   make env=your-org granted # (if you're using granted)
   

Org Kickstart will create the AWS account, place it in the correct OU, assign SSO access, set alternate contacts, and apply any policies that target the parent OU. See Granted Support for more information about how org-kickstart can seed your granted registry for you.

Account Options

Notes

• The account_email must be unique across all AWS accounts globally
• New accounts are created by AWS Organizations and may take a few minutes to become available
• The Security Account is managed separately via the security_account block

6.2 - Creating Policies

Org Kickstart manages three types of AWS Organizations policies via the same Terraform pattern: Service Control Policies (SCPs), Resource Control Policies (RCPs), and Declarative Policies.

Steps

1. Create a policy JSON file in the policies/ directory of your deployment repo. For dynamic values, use a .tftpl extension and Terraform template syntax.

   // policies/MyPolicy.json
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Deny",
         "Action": "s3:DeleteBucket",
         "Resource": "*"
       }
     ]
   }
   

2. Add the policy definition to the appropriate block in your tfvars file:

   service_control_policies = {
     deny_s3_delete = {
       policy_name        = "DenyS3BucketDeletion"
       policy_description = "Prevent deletion of S3 buckets"
       policy_json_file   = "policies/MyPolicy.json"
       policy_targets     = ["Workloads", "Sandbox"]
     }
   }
   

3. Plan and apply:

   make env=your-org tf-execute
   

   SCPs and RCPs are high-impact changes. Always review the plan before applying:

   make env=your-org tf-plan
   make env=your-org tf-show
   make env=your-org tf-apply
   

   You can also run a security scan of the plan with Checkov before applying:

   make env=your-org checkov
   

Policy Types

Declarative Policies also require policy_type = "DECLARATIVE_POLICY_EC2".

Targeting OUs

policy_targets accepts a list of OU names or OU IDs. Use "Root" to target the organization root:

policy_targets = ["Root"]                          # all accounts
policy_targets = ["Workloads", "Sandbox"]          # by name
policy_targets = ["ou-xxxx-xxxxxxxx"]             # by ID

Templated Policies

For policies that need org-specific values, use a .tftpl file:

// policies/AuditRoleProtection.json.tftpl
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Deny",
    "Action": ["iam:Delete*"],
    "Resource": "arn:aws:iam::*:role/${audit_role_name}"
  }]
}

service_control_policies = {
  protect_audit_role = {
    policy_name      = "ProtectAuditRole"
    policy_json_file = "policies/AuditRoleProtection.json.tftpl"
    policy_vars = {
      audit_role_name = "security-audit"
    }
  }
}

Sample Policies

See the policies/ directory in the repository for a library of ready-to-use policies. Or check out PrimeHarbor’s respository of Organizational Policies.

7 - Granted Support

Granted is a tool for quickly assuming roles across many AWS accounts via IAM Identity Center (SSO). Org Kickstart can generate a ready-to-use AWS config from your Terraform outputs, and your org-kickstart repo can double as a Granted Registry so your whole team gets the same set of account profiles.

The examples below use an environment named fooli. Substitute your own env name throughout.

Prerequisites

• Granted is installed (brew install granted or see the Granted docs).
• IAM Identity Center is enabled and your org has been deployed at least once, so a terraform apply has produced an output-<env>.json file. The generator reads the account_map, sso_start_url, sso_region, and sso_role_name outputs.

Generating an AWS config with make granted

After an apply, run the granted Makefile target:

make env=fooli granted

This runs scripts/generate_granted_config.sh against output-fooli.json and writes an AWS CLI config to granted/aws-config. The file contains one sso-session block plus one profile per account in your organization:

[sso-session fooli-sso]
sso_start_url = https://fooli.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile fooli-payer]
sso_session    = fooli-sso
sso_account_id = 111111111111
sso_role_name  = AdministratorAccess

[profile fooli-sandbox]
sso_session    = fooli-sso
sso_account_id = 222222222222
sso_role_name  = AdministratorAccess

Profiles are named after the keys in your accounts map (plus the payer and security accounts), so re-running make granted after adding accounts keeps the config in sync. Regenerate it any time the account list changes.

Once the profiles are in your AWS config you can assume any account with Granted:

assume fooli-sandbox
# or log the whole SSO session in first
aws sso login --sso-session fooli-sso

Sharing your repo as a Granted Registry

A Granted Registry lets everyone on the team pull the same account profiles straight from a git repo — no copy/pasting config files. Since your org-kickstart repo already generates the config, it’s the natural place to host the registry.

1. Confirm the granted.yml manifest. The examples/local-deploy sample already ships one at the repo root pointing at the generated config, so there’s nothing to create — just keep it. It looks like this:

   awsConfig:
       - ./granted/aws-config
   

2. Commit the generated config. Run make env=fooli granted and commit both granted.yml and granted/aws-config to the repo. (Re-run and commit whenever accounts change.)

3. Team members add the registry once:

   granted registry add -n fooli-admin -u git@github.com:fooli/fooli-org-kickstart.git
   

   Granted clones the repo, reads granted.yml, and merges the referenced profiles into the user’s ~/.aws/config. From then on they can assume fooli-payer, assume fooli-sandbox, and so on.

4. Stay current. When the registry repo is updated, team members pull the latest profiles with:

   granted registry sync
   

Tip: keep the registry in a private repo. The generated config contains AWS account IDs and your SSO start URL. Those aren’t secrets on their own, but there’s no reason to publish them.

8 - Reference

This section contains low-level reference documentation for Org Kickstart.

In This Section

• Parameter Reference — All Terraform variables and their defaults
• Module Documentation — Auto-generated resource and module reference

Source

The complete module documentation is generated from the Terraform source and available in the ModuleDocs.md file in the repository.

Policy Library

Sample policies are included in the policies/ directory of the repository:

Policies with the .tftpl extension support Terraform template variables via policy_vars.

8.1 - Module Documentation

Requirements

Providers

Modules

Resources

Inputs

object({
    account_factory_config_file = string
    template                    = string
  })

map(
    object({
      account_name    = string
      account_email   = string
      delegated_admin = optional(list(string), [])
      operations_contact = optional(object({
        name          = string
        title         = string
        email_address = string
        phone_number  = string
      }))
      primary_contact = optional(object({
        full_name          = string
        company_name       = optional(string)
        address_line_1     = string
        address_line_2     = optional(string)
        address_line_3     = optional(string)
        city               = string
        district_or_county = optional(string)
        state_or_region    = optional(string)
        postal_code        = string
        country_code       = string
        phone_number       = string
        website_url        = optional(string)
      }))
      # parent_ou_id can explicitly override the OU assignment and lookup by name.
      # parent_ou_id takes precedence over parent_ou_name
      parent_ou_name            = optional(string, “Workloads”)
      parent_ou_id              = optional(string, null)
      monthly_budget_amount     = optional(number, 0)
      budget_alert_recipients   = optional(list(string), [])
      service_control_policies  = optional(list(string), [])
      resource_control_policies = optional(list(string), [])
      declarative_policies_ec2  = optional(list(string), [])
    })
  )

object({
    levels        = map(number)
    subscriptions = list(string)
  })

object({
    alert_recipients      = optional(list(string), [])
    currency              = optional(string, “USD”)
    warning_percentage    = optional(number, 85)
    organizational_budget = optional(number, 0)
  })

object({
    bucket_name      = string
    trail_name       = string
    enabled          = optional(bool, true)
    excluded_buckets = list(string)
  })

map(object({
    policy_name        = string
    policy_type        = string
    policy_description = string
    policy_json_file   = string
    policy_targets     = optional(list(string), [“Root”])
    policy_vars        = optional(map(string), {})
    do_not_attach      = optional(bool, false)
  }))

object({
    name          = string
    title         = string
    email_address = string
    phone_number  = string
  })

object({
    name          = string
    title         = string
    email_address = string
    phone_number  = string
  })

object({
    full_name          = string
    company_name       = optional(string)
    address_line_1     = string
    address_line_2     = optional(string)
    address_line_3     = optional(string)
    city               = string
    district_or_county = optional(string)
    state_or_region    = optional(string)
    postal_code        = string
    country_code       = string
    phone_number       = string
    website_url        = optional(string)
  })

object({
    name          = string
    title         = string
    email_address = string
    phone_number  = string
  })

map(
    object({
      name             = string
      is_child_of_root = optional(bool) # This is ignored, it is retained for backwards compatibility
      parent_id        = optional(string)
    })
  )

map(
    object({
      stack_name         = string
      template_file      = optional(string)
      template_url       = optional(string)
      regions            = optional(list(string))
      parameters         = optional(map(string), {})
      timeout_in_minutes = optional(number, 15)
      on_failure         = optional(string, “DO_NOTHING”)
    })
  )

map(
    object({
      policy_name        = string
      policy_description = string
      policy_json_file   = string
      policy_targets     = optional(list(string), [“Root”])
      policy_vars        = optional(map(string), {})
      do_not_attach      = optional(bool, false)
    })
  )

object({
    # These will move from the main module to here at some point.
    # account_name    = string
    # account_email   = string
    delegated_admin = optional(list(string), [])
    operations_contact = optional(object({
      name          = string
      title         = string
      email_address = string
      phone_number  = string
    }))
    primary_contact = optional(object({
      full_name          = string
      company_name       = optional(string)
      address_line_1     = string
      address_line_2     = optional(string)
      address_line_3     = optional(string)
      city               = string
      district_or_county = optional(string)
      state_or_region    = optional(string)
      postal_code        = string
      country_code       = string
      phone_number       = string
      website_url        = optional(string)
    }))
    monthly_budget_amount   = optional(number, 0)
    budget_alert_recipients = optional(list(string), [])
  })

map(
    object({
      stack_name         = string
      template_file      = optional(string)
      template_url       = optional(string)
      regions            = optional(list(string))
      parameters         = optional(map(string), {})
      timeout_in_minutes = optional(number, 15)
      on_failure         = optional(string, “DO_NOTHING”)
    })
  )

object({
    disable_guardduty   = optional(bool, false)
    disable_macie       = optional(bool, false)
    disable_inspector   = optional(bool, false)
    disable_securityhub = optional(bool, false)
    disable_stacksets   = optional(bool, false)
  })

map(
    object({
      policy_name        = string
      policy_description = string
      policy_json_file   = string
      policy_targets     = optional(list(string), [“Root”])
      policy_vars        = optional(map(string), {})
      do_not_attach      = optional(bool, false)
    })
  )

Outputs

8.2 - Parameter Reference

All configuration is passed via the organization variable (an object type) and a few top-level variables. Below are the key configuration parameters.

Top-Level Variables

Organization Object

Core Identity

State Bucket

CloudTrail

SSO / Identity Center

Audit Role

Billing

Security Services

Configure which security services to enable/disable (each defaults to false):

security_services = {
  disable_guardduty   = false
  disable_macie       = false
  disable_inspector   = false
  disable_securityhub = false
  disable_stacksets   = false
}

Log & Findings Buckets

Organization Services & Policy Types

org-kickstart enables an opinionated set of AWS service-access principals and organization policy types. Adjust the defaults with:

Account Configurator

Optional integration with pht-account-configurator to harden new accounts on creation — see the Account Configurator guide. Set the account_configurator object, or omit it to disable:

DataTrail

Optional DataTrail (CloudTrail S3 data-event) configuration in the security account. Set the datatrail object, or omit it to disable:

Organizational Units

Four OUs are always created: Governance, Workloads, Sandbox, Suspended. Additional OUs can be defined:

organization_units = {
  "MyOU" = {
    name             = "MyOU"
    is_child_of_root = true
  }
  "NestedOU" = {
    name         = "NestedOU"
    parent_id    = "MyOU"   # use parent OU name for direct children of custom OUs
  }
}

Accounts

Each account in the accounts map:

accounts = {
  my_account = {
    account_name          = "my-org-prod"        # AWS account display name
    account_email         = "aws+prod@example.com" # root email (must be unique)
    parent_ou_name        = "Workloads"           # OU name (or use parent_ou_id)
    monthly_budget_amount = 1000                  # optional, in USD
    delegated_admin       = ["service.amazonaws.com"]  # optional

    # Optional: override primary contact for this account
    primary_contact = {
      full_name       = "Account Owner"
      company_name    = "My Org"
      address_line_1  = "123 Main St"
      city            = "Atlanta"
      state_or_region = "GA"
      postal_code     = "30332"
      country_code    = "US"
      email_address   = "owner@example.com"
      phone_number    = "+14041234567"
    }
  }
}

The org-wide default_close_on_deletion (bool, default false) controls whether an account is closed — not just removed from the org — when it leaves org-kickstart. Use with caution.

Security Account

The security account is created and managed like a workload account, but its settings live in a dedicated required security_account block. Its name and root email come from security_account_name / security_account_root_email; everything else is optional:

security_account = {
  delegated_admin         = ["guardduty.amazonaws.com"]  # services it is delegated admin for
  monthly_budget_amount   = 100                          # optional, USD
  budget_alert_recipients = ["security@example.com"]     # optional
  # operations_contact and primary_contact may also be set (same shape as an account entry)
}

Alternate Contacts

Applied org-wide (overridable per account):

global_billing_contact = {
  name          = "Name"
  title         = "CFO"
  email_address = "billing@example.com"
  phone_number  = "+1xxxxxxxxxx"
}

global_security_contact = {
  name          = "Name"
  title         = "CISO"
  email_address = "security@example.com"
  phone_number  = "+1xxxxxxxxxx"
}

global_operations_contact = {
  name          = "Name"
  title         = "VP Engineering"
  email_address = "ops@example.com"
  phone_number  = "+1xxxxxxxxxx"
}

global_primary_contact = {
  full_name       = "Name"
  company_name    = "My Org"
  address_line_1  = "123 Main St"
  city            = "Atlanta"
  state_or_region = "GA"
  postal_code     = "30332"
  country_code    = "US"
  email_address   = "aws@example.com"
  phone_number    = "+1xxxxxxxxxx"
}

Policies

All three policy types follow the same structure:

service_control_policies = {
  my_policy = {
    policy_name        = "MyPolicy"
    policy_description = "Description"
    policy_json_file   = "policies/MyPolicy.json"
    policy_targets     = ["Workloads", "ou-xxxx-xxxxxxxx"]  # OU names or IDs
    policy_vars = {                                         # for .tftpl files
      variable_name = "value"
    }
  }
}

The same structure applies to resource_control_policies and declarative_policies (which also require policy_type = "DECLARATIVE_POLICY_EC2").

Billing Alerts

billing_alerts = {
  levels = {
    level1  = 100   # USD threshold
    level2  = 500
    oh_shit = 1000
  }
  subscriptions = ["email@example.com"]
}

budget_defaults = {
  alert_recipients      = ["email@example.com"]
  currency              = "USD"
  warning_percentage    = 80
  organizational_budget = 1000
}

Payer CloudFormation Stacks

payer_cloudformation_stacks deploys arbitrary CloudFormation stacks into the payer (management) account. It’s the right hook for things like billing notifications, payer-scoped cost-explorer alarms, or other automation that has to live in the payer because of where billing data and Organizations APIs are exposed.

Each map entry creates one stack per region listed. The Terraform resource addresses use a <key>-<region> composite, so adding a region later does not rename existing stacks.

All stacks are created with the full set of CloudFormation capabilities (CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND).

payer_cloudformation_stacks = {
  billing_alerts = {
    stack_name    = "slack_billing_alerts"
    template_file = "cloudformation/slack-Template.yaml"
    regions       = ["us-east-1"]
    parameters = {
      pExecutionRate = "cron(0 09 * * ? *)"
      # JSON-valued parameters can be written as heredocs. The module
      # canonicalizes any value that parses as JSON, so multi-line
      # formatting does not cause drift on subsequent plans.
      pEventInput = <<-EOT
        {
          "threshold": "10",
          "alert_percent": "20"
        }
      EOT
      pSlackWebhookSecret = "SlackWebHook"
      pRuleState          = "ENABLED"
      pAccountDescription = "My-Payer"
    }
  }
}

Security Account Stacks

security_account_stacks is the same idea as payer_cloudformation_stacks, but the stacks are deployed into the Security Account via the OrganizationAccountAccessRole. Use it for security-scoped automation that needs to live in the delegated-admin account: Security Hub finding processors, GuardDuty event handlers, KMS keys for security data, ChatBot integrations, and similar.

Schema, defaults, composite-key behavior, capabilities, and JSON parameter canonicalization are identical to payer_cloudformation_stacks.

security_account_stacks = {
  findings_processor = {
    stack_name    = "security-findings-processor"
    template_file = "cloudformation/findings-processor-Template.yaml"
    regions       = ["us-east-1"]
    parameters = {
      pSlackWebhookSecret = "SlackWebHook"
      pSeverityThreshold  = "MEDIUM"
    }
  }
}

9 - Contribution Guidelines

We welcome contributions to both the Terraform module and this documentation site. All submissions require review via GitHub pull request.

Contributing to the Module

1. Fork the org-kickstart repo on GitHub
2. Create a feature branch
3. Make your changes and test them against a real AWS Organization (see the CLAUDE.md for testing guidance)
4. Send a pull request with a clear description of the change and why it’s needed

Testing

When modifying the module:

• Use make env=your-org tf-plan extensively before applying
• Test in a non-production organization first
• Use targeted applies for risky changes: terraform apply -var-file="your-org.tfvars" -target <resource>
• Verify SCPs don’t lock out root or prevent remediation

Contributing to the Docs

The documentation source lives in the org-kickstart-site/ directory alongside the module.

Running the Site Locally

Requirements:

• Hugo extended >= 0.155.0
• Node.js (for PostCSS/SCSS processing)

cd org-kickstart-site
make npm        # install Node dependencies (first time only)
make test       # starts dev server at http://localhost:1319/

Use make test-drafts to also render draft and future-dated content.

Editing Pages

1. Fork the org-kickstart-site repo
2. Edit files under org-kickstart-site/content/en/
3. Preview locally with make test
4. Submit a pull request

You can also click Edit this page in the top right of any documentation page to jump directly to the source file on GitHub.

Creating an Issue

Found a bug or want to request a feature? Open an issue on GitHub.

Useful Resources

• Docsy user guide
• Hugo documentation
• Terraform AWS Provider docs

10 - Releases

Org Kickstart uses a simple versioning model: a rolling latest branch and fixed, tagged releases.

We target quarterly releases, but may cut a new version sooner when significant new AWS organization-management features warrant it.

The latest branch

The default branch is latest. It always holds the most recent changes. Point your module source at it (with no ?ref=) to track the newest code:

module "organization" {
  source = "github.com/primeharbor/org-kickstart"
  # ...
}

Use this if you want the newest features and are comfortable reviewing every terraform plan for changes before you apply.

Tagged releases

Each release is a fixed, immutable git tag — for example 0.3.1. Pin to a tag for a stable, reproducible deployment:

module "organization" {
  source = "github.com/primeharbor/org-kickstart?ref=0.3.1"
  # ...
}

The examples/local-deploy sample pins to the current release by default. Bump the ?ref= value when you’re ready to move to a newer release — and read its release notes for breaking changes first.

Release notes

Per-release changes — new features, breaking changes, and migration steps — are published as release notes on the blog, and in each release’s docs/v<version>-notes.md file in the repository.

Which should I use?

• Production: pin to a tagged release (?ref=0.3.1) and upgrade deliberately after reviewing the release notes.
• Evaluating or lab environments: track latest for the newest capabilities.