Skip to main content

Cloud

Onboard an AWS Cloud Organization

AWS Organizations and Root Accounts

An AWS organization is a service AWS provides that allows you to consolidate multiple accounts into an organization and manage them centrally. The hierarchy of AWS organization is as follows:

  • Root - The parent container for all accounts. It consists of Organizational Units (OU) and accounts.

  • Organizational Unit (OU) - The container for accounts within root. It can also contain other Organizational Units.

  • Account - The standard AWS account that contains the AWS resources

When the AWS root account is onboarded into Illumio Cloud, all the accounts under the root will be onboarded (provided the user runs the StackSet). Cloud supports onboarding AWS Organization (root account) and AWS accounts. It does not support onboarding AWS Organizational Units.

Onboarding of an AWS organization (root account) is a two-step process.

  1. Run a CloudFormation stack on a root account.

  2. Run a CloudFormation stackset on a root account, which in turn runs the stack in all accounts under the root account.

Note

If you want to onboard only the accounts under root account, but not the root account itself, then the first step can be skipped.

Prerequisites

  • Before onboarding an AWS organization, copy the root account ID for the account you want to onboard so that you can specify it in the first step of the onboarding wizard

  • Prior to onboarding an AWS account, ensure that Cloud has the required AWS permissions. See Prerequisites for Onboarding AWS for information.

  • You need to login to the root account in which you will run the stack or stackset

Onboard AWS Organizations in Cloud

  1. Launch the onboarding wizard in either of the following ways:

    • Click + AWS in the Onboarding page to onboard your first organization when you sign in for the first time

    • From the left navigation, choose Onboarding and click + AWS at the top of the page.

  2. Provide the following information about your AWS account:

    • Name for the root account

      This name is what will appear in Cloud. The name should be descriptive so that you can easily identify it in Cloud.

    • The AWS ID of the root account you are onboarding into Cloud

    Note

    The page contains a toggle below the Account ID field to specify the type of access Cloud will have to your AWS account. Choosing Yes grants the Illumio Cross Account Role permission to view your AWS account resources and to apply policy to them. Choosing No provides the Illumio Cross Account Role read-only access. To view the permissions you are granting Cloud to your AWS account, click Download Permissions.

    When done completing these settings, click Next.

    The wizard advances to step two: Set up Access.

  3. Select or create a service account.

    Note

    During onboarding, you configure a service account for Cloud. Cloud uses this digital identity to interact with your AWS account. The service account has read/write access, which you granted in the first step of the wizard.

    If you haven't onboarded any accounts yet, click Add a new Service Account in the Service Account drop-down list and specify a name and description (optional) and click Create.

    A pop-up dialog box appears displaying information about the credentials created for the service account.

    You cannot copy information from the dialog box. Click Download Credentials to save this information locally, then click Close.

    Important

    • Make a note of the Cloud Tenant Id. It will be needed for running the template in AWS Console.

    • Open the downloaded credentials file (Service-Account-<name>.txt) for the service account and copy the value in the serviceAccountKeyId and serviceAccountToken fields. You will need these values when creating the CloudFormation stack or stackset n AWS. Cloud provides these credentials for download only during this step of the onboarding wizard.

    Note

    Alternatively, you can select an existing service account from a previous onboarding. When you use an existing service account, you must still have access to the downloaded credentials file and service account secret. If you do not have access to that file, you must create a new service account.

  4. In step two (Set up Access) of the onboarding wizard, select Download Cloud Formation Stack and click Download.

    Cloud downloads an AWS Integration YAML file to your local system.

  5. Click Next. The final step of the wizard appears.

  6. Review the account information and if everything looks correct, click Save and Confirm. If you see issues you need to correct, click Back and return to that wizard step.

Create Roles in the AWS Console by Running a Stack

Note

Choose this option when you want to onboard accounts under root account, and the root account itself. Then follow the subsequent instructions in Create Roles in the AWS Console for Accounts Under the Root Account.

In order to create the Assume role and provide Illumio Cloud with read/read-write permission to resources in your AWS root account, follow these steps to run the template as stack in the root account.

Create the Stack

  1. Log into your AWS console with the required permissions (root account) to run a CloudFormation stack or provide the file to members of your organization who have the required AWS root account access.

  2. Under Services, click CloudFormation.

  3. Click on Create Stack and choose the With new resources option.

  4. In the Create stack page, select the Template is ready and Upload a template file options, and click Choose File. (The Cloud YAML file provided by Illumio is a valid stack template file.)

  5. Upload the Illumio Cloud YAML file and click Next.

Specify the Stack Details

  1. In the Specify stack details page, enter the Stack name. The stack name must be unique and not the same name used to create previous stacks.

  2. In the IllumioServiceAccountKey and IllumioServiceAccountSecret text boxes, enter the serviceAccountKeyId and serviceAccountToken, respectively, from the downloaded ServiceAccount file.

  3. Enter the CloudTenantId in the form. The IAMRoleName field will auto-populate with a default, but you can modify the name if needed.

  4. Click Next to continue.

Configure, Review, and Run the Stack

  1. In the Configure stack option page, allow the default values and click Next.

  2. In the Review page, select the acknowledgment check box and click Submit.

The stack will run, creating the resources needed to create the IAM Assume role and will make a callback to Illumio Cloud with the RoleARN, ExternalId, OrgId, and MasterAccountId. The RoleARN and ExternalId will be used by Illumio Cloud to connect with the account and sync resources. The OrgId and MasterAccountId will be used by Illumio Cloud to create a mapping between the root account and the accounts under it.

When the stack command finishes running in AWS and you've successfully created the stack, a Cloud script will notify Cloud that the stack was successfully created and Cloud will detect that the organization was onboarded and begin synchronizing the organization resources with Cloud. A new row for that organization will appear in the Onboarding page.

Create Roles in the AWS Console for Accounts Under the Root Account

Note

Choose this option solely when you want to onboard only the accounts under root account, but not the root account itself.

If you want to onboard the accounts under the root account, and the root account itself, you must first perform the steps in Create Roles in the AWS Console by Running a Stack before performing these steps.

In order to create the Assume role and provide Illumio Cloud with read/read-write permission to resources in your AWS accounts under the root account, follow these steps to run the template as a stackset in the root account.

Create a Stackset

  1. Log into your AWS console with the required permissions (root account) to run a CloudFormation stack or provide the file to members of your organization who have the required AWS root account access.

  2. Under Services, click CloudFormation.

  3. Click Create StackSet.

Choose a Template

  1. In the Choose a template page, select the Service-managed permissions, Template is ready, and Upload a template file options, and click Choose File.

  2. Upload the Illumio Cloud YAML file and click Next. (The Cloud YAML file provided by Illumio is a valid stack template file.)

Specify the Stackset Details

  1. In the Specify stackset details page, enter the Stackset name. The stack name must be unique and not the same name used to create previous stacks.

  2. Add a description in the Stackset description field.

  3. In the IllumioServiceAccountKey and IllumioServiceAccountSecret text boxes, enter the serviceAccountKeyId and serviceAccountToken, respectively, from the downloaded ServiceAccount file.

  4. Enter the CloudTenantId in the form. The IAMRoleName field will auto-populate with a default, but you can modify the name if needed.

  5. Click Next to continue.

Configure, Review, and Run the Stackset

  1. In the Specify regions options page, choose the region under which the stacks are set to be deployed. This will allow Illumio Cloud to access resources in all regions, so selecting only one region is preferable.

    In the Set deployment options page, assuming that only one region was chosen, allow the default values and click Next.

  2. In the Review page, select the acknowledgment check box and click Submit.

The stackset will run, creating the resources in all accounts under the root account to create the IAM Assume role and will make a callback to Illumio Cloud with the RoleARN, ExternalId, OrgId, and MasterAccountId. The RoleARN and ExternalId will be used by Illumio Cloud to connect with the account and sync resources. The OrgId and MasterAccountId will be used by Illumio Cloud to create mapping between the root account and accounts under it.

When the stack command finishes running in AWS and you've successfully created the stack, a Cloud script will notify Cloud that the stack was successfully created and Cloud will detect that the organization was onboarded and begin synchronizing the organization resources with Cloud. Clicking the organization in the Onboarding page will let you see the accounts under it.

What's Next?

For the next steps after onboarding organization, see AWS Onboarding Workflow and After Onboarding your Accounts.

Edit the Accounts in the Organization

  1. In the Onboarding page, click on the organization.

  2. Click Edit.

  3. You can change read/write access permissions if you like.

  4. Select the individual account in question and click Enable, Disable, or Remove as needed.

  5. In the dialog that appears, click to confirm.

Remove the Integration

You can delete the integration for a given organization by selecting the it in the Onboarding page and clicking Remove > Remove. However, you will need to then manually delete the CloudFormation stack and/or stackset in AWS.

Note: Once an AWS organization is deleted, the accounts under the account will also be removed.

Remove the Stack in AWS

  1. Login to the AWS Console and choose Services > CloudFormation.

  2. Select Stacks, and, in the list of stacks, choose the stack name you used while onboarding Cloud and click Delete.

    Initially the stack deletion will fail. The CloudFormation template provided by Cloud creates Lambda-backed custom resources, which AWS does not automatically clear.

  3. If it fails, select the stack and click Delete again.

    A pop-up window appears with the option to retain the resources that are failing to delete.

  4. Choose that checkbox option and click Delete.

    Note: Although you selected the option to retain resources, custom resources are specific to CloudFormation and they will be cleared upon the deletion of the stack. Ref: https://repost.aws/knowledge-center/cloudformation-lambda-resource-delete.

    The Stack will be deleted, removing all the resources (Role, Lambda, Custom Resource) created when running the stack.

Remove the Stackset in AWS

  1. Login to the AWS Console and choose Services > CloudFormation.

  2. Select StackSet, and, in the list of stacksets, choose the stackset name you used while onboarding Cloud.

  3. From the Actions drop-down menu, select Delete stacks from StackSet. (This must be done before you can delete the stackset.)

  4. In the Set deployment options page, Organization units (OUs) section, enter the AWS OU ID (the organization ID, which can be found in the organization service).

  5. In the Set deployment options page, Specify Regions section, select the region. This will be the region you selected when you created the stackset.

  6. Leave the rest of the options with their defaults and click Next.

  7. In the Review page, click Submit.

    This will remove all the stacks from the stackset. To monitor the status of the operation, select the stackset and click the Operations tab.

  8. If the action fails, it means that the individual stacks in the accounts under the master account are failing to delete. If that happens, login to the specific accounts (not the root account) and follow the same steps seen in Remove the Stack in AWS. Once that is done, repeat the instructions to Remove the Stackset in AWS.

    Once the stacks are completely removed, select the stackset again and choose Delete StackSet from the Actions drop-down menu.