How do I connect AWS to OpsCompass for the first time?

OpsCompass makes it easy to connect AWS with OpsCompass for the first time. Follow these steps to connect.

First Time Setup

This article will explain the AWS account connection process for those connecting AWS to OpsCompass for the first time.

AWS Organizations

1. Accounts joined with OpsCompass must be a member of an AWS organization.

Verifying an Organization within the AWS console:

From the AWS console home dashboard, type or navigate to  "AWS Organizations."


You can verify whether you are a part of an organization here. If you are not a part of an organization and don't see a similar screen in AWS, please continue to step C.


Click on "Create an organization". You can also see "Get Started with AWS Organizations".

OpsCompass uses a read-only access role that exists in your AWS IAM service. This role provides the necessary permissions for OpsCompass to scan resources, detect events and report those to the OpsCompass platform. There are two ways to create the AWS IAM Role appropriate for OpsCompass, the AWS Console, and the AWS Command Line Interface (CLI).

Creating AWS IAM Roles using the AWS Console         

1. Log into the AWS Console.
   1. Click the link to deploy the OpsCompass Viewer IAM Role. This takes you to the CloudFormation Portal and sets all required fields as they are expected for OpsCompass.
      1. Stack Name – Changing the supplied value will cause the connection to fail.
      2. External ID - The external ID can be changed if needed.
   2. Acknowledge the warning about IAM resources with custom names.
2. Click ‘Create Stack.’
   1. This creates the OpsCompass viewer role with necessary permissions
   2. A new IAM policy, OpsCompass Denial role denies OpsCompass access to contents of S3 objects, databases, and other resources.
   3. A new IAM policy for OpsCompass denial is created, which is associated to the Denial role.
   4. Navigate to the newly created role in the AWS IAM Portal.
   5. Copy the role ARN to the clipboard.
3. Return to OpsCompass. In OpsCompass, two edit fields appear:
   1. AWS External ID – This is a generated field. If this field is changed, the OpsCompass Viewer role needs to be updated to match the new value.
   2. Role ARN – Past the ARN of the newly created OpsCompass View IAM Role. This must match the AWS IAM View Role ARN to successfully connect.
4. Click Connect. Upon connection, OpsCompass displays a progress bar to the user, indicating the status of account connection. Error messages will be displayed to the user in the case of problems. The process for connecting an account includes:
   1. Verifying the selected Role is a member of an organization.
   2. Verifying the role exists and has the correct permissions.
   3. Connect to the account and create the OpsCompass tenant for this account.
   4. Attempt to scan resources for the accounts in the organization, using the created role.
5. After the verification is complete, OpsCompass begins scanning resources in the account you have connected. This may take several minutes to complete if the account contains a large number of resources.
   
   NOTE: If you click “skip” and proceed to the product dashboard, you may not immediately see all the resources that you are expecting. It may take several minutes for all resources to appear.

Creating AWS IAM Roles using the AWS CLI         

Rather than using the AWS Console, you can create the OpsCompass IAM roles using the AWS CLI.

1. Using the AWS Command Line Interface (CLI) – OpsCompass has introduced new CLI commands to help you simplify the account connection process. Select “Setup our account via command line interface” in the Account Connection page.
2. Verify that your AWS CLI ins installed an associated to the account you wish to connect, using the command:
   

   aws --version

3. You can deploy the OpsCompass Integration CloudFormation Template by copying the command and executing it in the AWS CLI.
   

   aws cloudformation create-stack --stack-name OpsCompassIntegration --template-url https://opscompass-templates.s3.amazonaws.com/opscompass_role_creation.template --capabilities CAPABILITY_NAMED_IAM --parameters ParameterKey=ExternalID,ParameterValue=[this will be provided during setup] && aws cloudformation wait stack-create-complete --stack-name OpsCompassIntegration

4. After the command has executed successfully, you can verify the existence of the OpsCompass Viewer role:
   

   aws iam get-role --role-name OpsCompassViewer 

5. After completing the OpsCompass Integration CloudFormation Template deployment, copy the resource ID (the AWS ARN) to the clipboard, and proceed with the connection experience.
6. Paste the ARN into the Role ARN field.
7. Click Connect. Upon connection, OpsCompass displays a progress bar to the user, indicating the status of account connection. Error messages will be displayed to the user in the case of problems. The process for connecting an account includes:
   1. Verifying the selected Role is a member of an organization.
   2. Verifying the role exists and has the correct permissions.
   3. Connect to the account and create the OpsCompass tenant for this account.
   4. Attempt to scan resources for the accounts in the organization, using the created role.
8. After the verification is complete, OpsCompass begins scanning resources in the account you have connected. This may take several minutes to complete if the account contains a large number of resources.
   1. If you click “skip” and proceed to the product dashboard, you may not immediately see all the resources that you are expecting. It may take several minutes for all resources to appear.

Adding Event Forwarding to OpsCompass Using the AWS Console

1. Creating the Event Forwarding architecture – OpsCompass supports the forwarding of CloudTrail events from AWS accounts, allowing for near real time resource scanning and analysis for supported events. There are two ways to create the AWS Event Forwarding architecture appropriate for OpsCompass.
   
   1. Be sure you are logged into the AWS Console.
   2. Return to OpsCompass
   3. Click the ‘Enable Event Scanning’ button to deploy the OpsCompass EventForwarding Template. This takes you to the CloudFormation Portal and sets all required fields as they are expected for OpsCompass.
      1. Stack Name – Changing the supplied value will cause the connection to fail.
   4. Click ‘Create Stack.’ This begins the deployment of the following resources
      1. An event forwarding rule, used to select and send CloudTrail events to OpsCompass.
      2. A CloudTrail to capture events generated by CloudTrail and AWS services.
      3. A S3 Bucket, used to store all events captured by the newly made CloudTrail bucket.
      4. A S3 Bucket Policy to be attached to the newly created bucket. This allows for the newly created CloudTrail to forward to the S3 bucket.
      5. Copy the role ARN to the clipboard.
      6. Once the deployment of the stack is complete, your AWS account is setup to forward events to OpsCompass.
   5. Navigate back to OpsCompass
   6. In OpsCompass, click ‘Done’ to be navigated back to your company dashboard.

Using the AWS Command Line Interface (CLI)

1. OpsCompass has introduced new CLI commands to help you simplify the setup of event forwarding
   1. Select “Enable event scanning via AWS command line interface”
   2. You can deploy the OpsCompassEventForwarding Template by copying the command and executing it in the AWS CLI
      
      

      aws cloudformation create-stack  --stack-name OpsCompassEventForwarding --template-url https://opscompass-templates.s3.amazonaws.com/opscompass_event_based.template && aws cloudformation wait stack-create-complete --stack-name OpsCompassEventForwarding

   3. Once the deployment of the stack is complete, your AWS account is setup to forward events to OpsCompass.
   1. 1. Navigate back to OpsCompass
      2. In OpsCompass, click ‘Skip’ to be navigated back to your company dashboard.

Additional Resources: 

How do I connect additional clouds to OpsCompass?

How do I connect an Azure account to OpsCompass?

How do I connect a Google Cloud (GCP) Project to OpsCompass?

How do I connect a Microsoft 365 Tenant to OpsCompass?

How do I invite a new user to OpsCompass