Deploy with Terraform

Single Account

Creates the IAM role, trust policy, and permissions directly as Terraform resources. This gives you full control over the role, including tags, a permissions boundary, or a custom path.

Download the read-only policy

Save the published policy next to your Terraform files so permission changes are reviewed in your own pull requests:

curl -sSfo DrafttReadOnlyPolicy.json \
  https://draftt-public.s3.amazonaws.com/DrafttReadOnlyPolicy.js

Declare the trust policy

Only the draftt-fetcher role in Draftt’s AWS account can assume the role, and only with your External ID:

data "aws_iam_policy_document" "draftt_assume_role" {
  statement {
    sid     = "AllowDrafttFetcherAssumeRole"
    effect  = "Allow"
    actions = ["sts:AssumeRole"]

    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::339712924365:root"]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:PrincipalArn"
      values   = ["arn:aws:iam::339712924365:role/draftt-fetcher"]
    }

    condition {
      test     = "StringEquals"
      variable = "sts:ExternalId"
      values   = [var.draftt_external_id]
    }
  }
}

Create the role

Draftt requests 30-minute sessions, which fit within the default one-hour maximum session duration:

resource "aws_iam_role" "draftt_access" {
  name                 = var.draftt_role_name
  description          = "Draftt cross-account read-only access role"
  assume_role_policy   = data.aws_iam_policy_document.draftt_assume_role.json
  max_session_duration = 3600

  tags = var.tags
}

Attach the AWS managed policies

resource "aws_iam_role_policy_attachment" "draftt_managed" {
  for_each = {
    security_audit   = "arn:aws:iam::aws:policy/SecurityAudit"
    view_only_access = "arn:aws:iam::aws:policy/job-function/ViewOnlyAccess"
  }

  role       = aws_iam_role.draftt_access.name
  policy_arn = each.value
}

Attach DrafttReadOnlyPolicy

The policy is attached inline, matching the CloudFormation template. Decoding and re-encoding the file validates it at plan time and normalises whitespace:

resource "aws_iam_role_policy" "draftt_read_only" {
  name   = "DrafttReadOnlyPolicy"
  role   = aws_iam_role.draftt_access.name
  policy = jsonencode(jsondecode(file("${path.module}/DrafttReadOnlyPolicy.json")))
}

Declare inputs and outputs

variable "draftt_external_id" {
  description = "External ID shown in the Draftt setup dialog (Integrations > AWS)."
  type        = string
  sensitive   = true
  nullable    = false
}

variable "draftt_role_name" {
  description = "Name of the IAM role Draftt assumes. Keep it identical across all connected accounts."
  type        = string
  default     = "DrafttAccess-Role"
  nullable    = false
}

variable "tags" {
  description = "Tags applied to the Draftt IAM resources."
  type        = map(string)
  default     = {}
  nullable    = false
}

output "draftt_role_arn" {
  description = "Paste this ARN into the Draftt setup dialog."
  value       = aws_iam_role.draftt_access.arn
}

Plan and apply

Provide the External ID through a variable file or environment variable rather than on the command line:

export TF_VAR_draftt_external_id="<provided-in-draftt>"
terraform init
terraform plan -out=draftt.tfplan
terraform apply draftt.tfplan

The plan shows one role, one inline policy, and two policy attachments.

Enter the Role ARN in Draftt

Copy the draftt_role_arn output into the Role ARN field in the Draftt setup dialog and click Create.

CloudFormation Stack

Deploys Draftt’s published CloudFormation template as a Terraform-managed stack. Terraform tracks the stack, and CloudFormation creates the role and policies exactly as the console setup does. Use this to keep the template canonical without maintaining a copy of the read-only policy.

Create the stack

resource "aws_cloudformation_stack" "draftt" {
  name         = "DrafttStack"
  template_url = "https://draftt-public.s3.amazonaws.com/draftt-onboarding-cloudformation.json"
  capabilities = ["CAPABILITY_NAMED_IAM"]

  parameters = {
    DrafttRoleName = var.draftt_role_name
    ExternalId     = var.draftt_external_id
  }

  tags = var.tags
}

Declare inputs and outputs

variable "draftt_external_id" {
  description = "External ID shown in the Draftt setup dialog (Integrations > AWS)."
  type        = string
  sensitive   = true
  nullable    = false
}

variable "draftt_role_name" {
  description = "Name of the IAM role the stack creates. Keep it identical across all connected accounts."
  type        = string
  default     = "DrafttAccess-Role"
  nullable    = false
}

variable "tags" {
  description = "Tags applied to the CloudFormation stack."
  type        = map(string)
  default     = {}
  nullable    = false
}

output "draftt_role_arn" {
  description = "Paste this ARN into the Draftt setup dialog."
  value       = aws_cloudformation_stack.draftt.outputs["DrafttRoleArn"]
}

Plan and apply

export TF_VAR_draftt_external_id="<provided-in-draftt>"
terraform init
terraform plan -out=draftt.tfplan
terraform apply draftt.tfplan

The plan shows a single CloudFormation stack. The role and policies appear in the CloudFormation console under the stack’s resources.

Enter the Role ARN in Draftt

Copy the draftt_role_arn output into the Role ARN field in the Draftt setup dialog and click Create.

The template echoes the External ID in the ExternalID stack output, so it is visible to anyone with cloudformation:DescribeStacks in the account. The stack outputs are also stored in Terraform state.

CloudFormation StackSet (Multi Account)

Apply in the organization management account. Creates the organization-level role and a service-managed StackSet that deploys the per-account role to every member account. Requires CloudFormation StackSets trusted access in AWS Organizations.

Delegated StackSets administrator accounts are not supported. Draftt reads the StackSet status without the delegated-administrator call mode, so a StackSet owned by a delegated administrator is not visible to Draftt.

Declare the trust policy

The organization-level role uses the same trust policy and External ID as the per-account role:

data "aws_iam_policy_document" "draftt_assume_role" {
  statement {
    sid     = "AllowDrafttFetcherAssumeRole"
    effect  = "Allow"
    actions = ["sts:AssumeRole"]

    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::339712924365:root"]
    }

    condition {
      test     = "StringEquals"
      variable = "aws:PrincipalArn"
      values   = ["arn:aws:iam::339712924365:role/draftt-fetcher"]
    }

    condition {
      test     = "StringEquals"
      variable = "sts:ExternalId"
      values   = [var.draftt_external_id]
    }
  }
}

Create the organization-level role

resource "aws_iam_role" "draftt_organization_access" {
  name                 = "DrafttReadOnlyAccess-OrganizationLevel"
  description          = "Draftt organization-level read-only access role"
  assume_role_policy   = data.aws_iam_policy_document.draftt_assume_role.json
  max_session_duration = 3600

  tags = var.tags
}

Attach the AWS managed policies

Draftt uses these to list member accounts and read the StackSet rollout status:

resource "aws_iam_role_policy_attachment" "draftt_organization_managed" {
  for_each = {
    organizations_read_only  = "arn:aws:iam::aws:policy/AWSOrganizationsReadOnlyAccess"
    cloudformation_read_only = "arn:aws:iam::aws:policy/AWSCloudFormationReadOnlyAccess"
  }

  role       = aws_iam_role.draftt_organization_access.name
  policy_arn = each.value
}

Create the StackSet

resource "aws_cloudformation_stack_set" "draftt" {
  name             = "DrafttStackSet"
  description      = "Deploys the Draftt cross-account read-only role to organization accounts"
  template_url     = "https://draftt-public.s3.amazonaws.com/draftt-onboarding-cloudformation.json"
  permission_model = "SERVICE_MANAGED"
  capabilities     = ["CAPABILITY_NAMED_IAM"]

  parameters = {
    DrafttRoleName = var.draftt_role_name
    ExternalId     = var.draftt_external_id
  }

  auto_deployment {
    enabled                          = true
    retain_stacks_on_account_removal = false
  }

  tags = var.tags

  lifecycle {
    ignore_changes = [administration_role_arn]
  }
}

Deploy the stack instances

IAM is global, so a single region is enough. Target the organization root to cover every account, or specific organizational units:

resource "aws_cloudformation_stack_instances" "draftt" {
  stack_set_name = aws_cloudformation_stack_set.draftt.name
  regions        = ["us-east-1"]

  deployment_targets {
    organizational_unit_ids = var.target_organizational_unit_ids
  }

  operation_preferences {
    failure_tolerance_percentage = 100
    max_concurrent_percentage    = 25
  }
}

Declare inputs and outputs

variable "draftt_external_id" {
  description = "External ID shown in the Draftt setup dialog (Integrations > AWS)."
  type        = string
  sensitive   = true
  nullable    = false
}

variable "draftt_role_name" {
  description = "Name of the IAM role the StackSet creates in each member account."
  type        = string
  default     = "DrafttAccess-Role"
  nullable    = false
}

variable "target_organizational_unit_ids" {
  description = "Organization root ID (r-xxxx) or organizational unit IDs (ou-xxxx-xxxxxxxx) to deploy into. Find them with `aws organizations list-roots`."
  type        = list(string)
  nullable    = false
}

variable "tags" {
  description = "Tags applied to the Draftt resources."
  type        = map(string)
  default     = {}
  nullable    = false
}

output "draftt_organization_role_arn" {
  description = "Paste this ARN into the Draftt setup dialog as the organization role."
  value       = aws_iam_role.draftt_organization_access.arn
}

output "draftt_stack_set_arn" {
  description = "Paste this ARN into the Draftt setup dialog so Draftt can track the rollout."
  value       = aws_cloudformation_stack_set.draftt.arn
}

Plan and apply

export TF_VAR_draftt_external_id="<provided-in-draftt>"
export TF_VAR_target_organizational_unit_ids='["r-xxxx"]'
terraform init
terraform plan -out=draftt.tfplan
terraform apply draftt.tfplan

Confirm every target account shows SUCCEEDED under the StackSet’s stack instances before continuing. Draftt waits up to 30 minutes for the rollout and only connects accounts that succeeded.

Enter the ARNs in Draftt

Copy the draftt_organization_role_arn output into the organization Role ARN field, and the draftt_stack_set_arn output into the StackSet ARN field in the Draftt setup dialog.

Destroying aws_cloudformation_stack_instances removes the Draftt role from every member account at once. To stop onboarding new accounts without touching existing ones, set auto_deployment.enabled to false instead.

OVERVIEW

CLOUD INFRASTRUCTURE

CLOUD RESOURCES

DATA PLATFORMS

AI PLATFORMS

ENDPOINT MANAGEMENT

CMDB

TICKETING & COLLABORATION

Deploy with Terraform

Prerequisites

Setup methods

Notes

​Prerequisites

​Setup methods

​Notes

Prerequisites

Setup methods

Notes