Skip to content

AWS Prerequisites

This guide provides step-by-step instructions for configuring all AWS prerequisites required by the provider to manage AWS tenancy resources. The provider uses an IAM Cross-Account Role to authenticate and perform operations in your AWS management account.

The following prerequisites must be completed before using the <no value>_tenancy_aws resource:

  1. Create the Volocloud Account Resource
  2. Deploy the CloudFormation Stack
  3. Configure Microsoft Entra ID for SSO (optional)

1. Create the Volocloud Account Resource

The <no value>_account resource MUST be created first. Once created, it generates a CloudFormation template URL that is used to create the IAM roles required by the provider in your AWS management account.

resource "<no value>_account" "example" {
  account_id = "<volocloud-account-id>"
  email      = "cloud-platform@example.com"
  name       = "example"
  tenancies = {
    non_marketplace_onboarding = {
      aws_management_accounts = ["123456789012"]
    }
  }
}

After applying, the resource outputs the CloudFormation template URL:

  • resources.aws.management_accounts["<account-id>"].bootstrap_role_cloudformation_template_url
  • resources.aws.management_accounts["<account-id>"].bootstrap_role_arn
  • resources.aws.management_accounts["<account-id>"].bootstrap_role_external_id

2. Deploy the CloudFormation Stack

The CloudFormation template creates the IAM cross-account role that the provider assumes to manage resources in your AWS environment.

Using the AWS Console

  1. Sign in to the AWS Management Account as an administrator
  2. Navigate to CloudFormation > Create stack > With existing resources (import resources) or With new resources
  3. Select Amazon S3 URL and paste the CloudFormation template URL from the account resource output
  4. Set the stack name (e.g. volocloud-bootstrap)
  5. Add the following required tags to the stack:
Tag Name Tag Value
ManagedBy Volo Cloud Foundations
  1. Review and create the stack

Using the AWS CLI

aws cloudformation create-stack \
  --stack-name "volocloud-bootstrap" \
  --template-url "<cloudformation-template-url>" \
  --capabilities CAPABILITY_NAMED_IAM \
  --tags Key=ManagedBy,Value="Volo Cloud Foundations"

Note

The CloudFormation stack MUST be deployed in the AWS management account. The stack creates an IAM role with cross-account trust to the Volocloud platform, along with the permissions required to manage AWS Organizations, accounts, and services.

Configure the Tenancy Resource

Once the CloudFormation stack is deployed, use the ARN and External ID from the account resource outputs in the <no value>_tenancy_aws resource:

resource "<no value>_tenancy_aws" "example" {
  account_id = <no value>_account.example.account_id
  configuration = {
    assume_role = {
      account_id  = "123456789012"
      arn         = <no value>_account.example.resources.aws.management_accounts["123456789012"].bootstrap_role_arn
      external_id = <no value>_account.example.resources.aws.management_accounts["123456789012"].bootstrap_role_external_id
    }
    # ... rest of configuration ...
  }
  name = "example"
}

3. Configure Microsoft Entra ID for SSO (Optional)

If integrating Microsoft Entra ID as an external Identity Provider with AWS Identity Center for Single Sign-On, the provider requires a separate Service Principal in your Azure AD tenant with specific permissions.

Create the Service Principal

  1. Navigate to Microsoft Entra ID > App registrations > New registration
  2. Set the following values:
    • Name: a descriptive name (e.g. app-aws-sso-integration)
    • Supported Account Types: "Accounts in this organizational directory only (single-tenant)"
  3. Click Register
  4. Generate a Client Secret under Certificates & secrets

Assign Entra ID Built-in Roles

The Service Principal requires the following directory roles:

Role Purpose
Application Administrator Manage the SAML/SCIM enterprise application for AWS SSO
Groups Administrator Manage security groups synchronized to AWS Identity Center
  1. Navigate to Microsoft Entra ID > Roles and administrators
  2. Assign Application Administrator to the Service Principal
  3. Assign Groups Administrator to the Service Principal

Grant Microsoft Graph API Permissions

The Service Principal requires the following Microsoft Graph API permission:

Permission Type Purpose
Application.ReadWrite.OwnedBy Application Manage the enterprise application it owns for SAML/SCIM provisioning
  1. Navigate to the App Registration > API permissions > Add a permission
  2. Select Microsoft Graph > Application permissions
  3. Add Application.ReadWrite.OwnedBy
  4. Click Grant admin consent

Provide SSO Credentials to the Tenancy Resource

The SSO credentials are provided in the credentials.idp block of the <no value>_tenancy_aws resource:

resource "<no value>_tenancy_aws" "example" {
  # ... configuration ...
  credentials = {
    idp = {
      external = {
        microsoft_entra_id = {
          client_id     = "<sso-app-client-id>"
          client_secret = "<sso-app-client-secret>"
          tenant_id     = "<azure-tenant-id>"
        }
      }
    }
  }
}

Note

This step is only required if configuring AWS Identity Center with Microsoft Entra ID as the external identity provider. If using AWS Identity Center's built-in identity store or another IdP, this can be skipped.

Summary of Required Permissions

Component Permission Scope Required
AWS IAM CloudFormation Stack (cross-account role) Management Account Yes
Entra ID Role Application Administrator Tenant If using Entra ID SSO
Entra ID Role Groups Administrator Tenant If using Entra ID SSO
Microsoft Graph API Application.ReadWrite.OwnedBy Tenant If using Entra ID SSO

Troubleshooting

CloudFormation Stack Missing Tags

If the CloudFormation stack is deployed without the required tag (ManagedBy: Volo Cloud Foundations), the provider will not be able to identify and use the IAM role. Add the tag to the stack and update.

Cross-Account Role Trust Issues

If the provider fails to assume the IAM role, verify:

  • The CloudFormation stack was deployed in the management account (not a member account)
  • The stack completed successfully without errors
  • The ARN and External ID in the tenancy resource match the account resource outputs