AWS for Cloud Insights Using CLI

Limited Preview: Any information provided in this document regarding future functionalities is for informational purposes only and is subject to change including ceasing any further development of such functionality. Many of these future functionalities remain in varying stages of development and will be offered on a when-and-if available basis, and Cisco makes no commitment as to the final delivery of any of such future functionalities. Cisco will have no liability for Cisco's failure to deliver any or all future functionalities and any such failure would not in any way imply the right to return any previously purchased Cisco products.

The Amazon Web Services (AWS) for Cloud Insights integration can be created and managed via two methods: the AWS Console and the AWS Command Line Interface (CLI). For steps within the console, and to understand more of the context around this integration, see AWS for Cloud Insights. For steps to create the integration by the CLI only, see below.

Overview of CLI Steps

For inventory monitoring:

  • Create IAM (Identity and Access Management) policies and roles.

For flow logs monitoring:

  • Create IAM (Identity and Access Management) policies and roles.

  • Create an S3 (Simple Storage Service) bucket from which to send traffic flows.

  • Configure VPC (Virtual Private Cloud) flow logs.

  • Create an SNS (Simple Notification Service) topic and apply a policy.

  • Configure S3 bucket notifications to send events to the SNS topic.

Prerequisites

Before running the commands in this guide, ensure you meet the following prerequisites.

AWS CLI Installation

  1. Have the AWS CLI installed on your system (see how to download and install it).

  2. Your AWS CLI must be configured with appropriate IAM credentials.

    • You can configure the credentials using the aws configure command:

      aws configure
    • You will be prompted to enter your AWS Access Key ID, Secret Access Key, default region, and output format. The AWS keys must correspond to an IAM user that has the necessary permissions to perform the actions in this guide.

Environment Variables

Ensure the following environment variables are set (see Configuring environment variables for the AWS CLI for more information about setting environment variables) for more information about setting environment variables.

  1. For the inventory monitoring integration:

    • EXTERNAL_ID - A unique ID for external integrations which you can retrieve from the ThousandEyes-generated trust policy (see steps 1-5 and 10 of IAM Configuration for Inventory Monitoring) to find the trust policy screen on the ThousandEyes platform).

    • ACCOUNT_ID - Can be obtained from the AWS console or from the STS service: type aws sts get-caller-identity --query "Account" --output text into the CLI.

  2. For the flow logs monitoring integration:

    • EXTERNAL_ID - A unique ID for external integrations which you can retrieve from the ThousandEyes-generated Trust Policy (see steps 1-5 and 10 of IAM Configuration for Inventory Monitoring to find the trust policy screen on the ThousandEyes platform).

    • ACCOUNT_ID - Can be obtained from the AWS console or from the STS service: type “aws sts get-caller-identity --query "Account" --output text“ into the CLI.

    • S3_BUCKET_NAME - The name of the S3 bucket to be created (see bucket naming rules).

    • AWS_REGION - The AWS region where the resources will be created.

    • VPC_ID - The ID of the VPC from which flow logs will be created.

    • SNS_TOPIC_NAME - The name of the SNS topic to be created.

CLI Steps for Inventory Monitoring

The following steps create:

  • An IAM permission policy that allows ThousandEyes read access to your AWS resources.

  • An IAM role with a trust policy that allows ThousandEyes to assume the role to execute read actions and build an inventory.

Note: You will need to be logged into your ThousandEyes account to retrieve certain information while you enter commands into the CLI.

IAM Configuration for Inventory Monitoring

  1. In the ThousandEyes platform, go to the Integrations screen.

  2. Click + New Integration in the top right.

  3. In the Add New Integration side panel that opens, select Amazon Web Services.

  4. The resulting < Add AWS Integration screen defaults to showing the fields required for the “Test Recommendations” service.

  5. Select “Inventory Monitoring” from the ThousandEyes Supported Services dropdown.

  6. Give your integration a unique name. Duplicate names are not permitted.

  7. Open the Permission Policy dropdown.

  8. Copy the permission policy and save it as "te_cloud_insights_allow-all_inventory_policy.json".

    • Note: The permission policy shown below is for illustration purposes only. Your permission policy may be different, and that is the one you must copy.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "AllowTECloudInsightsReadAccessToAccountApis",
                  "Effect": "Allow",
                  "Action": [
                      "account:Get*",
                      "account:List*",
                      "iam:List*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToApiGateway",
                  "Effect": "Allow",
                  "Action": [
                      "apigateway:GET"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToCloudFrontApis",
                  "Effect": "Allow",
                  "Action": [
                      "cloudfront:List*",
                      "cloudfront:Get*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToCloudWatchApis",
                  "Effect": "Allow",
                  "Action": [
                      "cloudwatch:Describe*",
                      "cloudwatch:Get*",
                      "cloudwatch:List*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToEc2Apis",
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:Describe*",
                      "ec2:Describe*",
                      "ec2:Get*",
                      "ec2:Search*",
                      "ecs:Describe*",
                      "ecs:List*",
                      "eks:Describe*",
                      "eks:List*",
                      "elasticloadbalancing:Describe*",
                      "globalaccelerator:Describe*",
                      "globalaccelerator:List*",
                      "health:Describe*",
                      "lambda:Get*",
                      "lambda:List*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToDbApis",
                  "Effect": "Allow",
                  "Action": [
                      "elasticache:Describe*",
                      "elasticache:List*",
                      "es:Describe*",
                      "es:List*",
                      "kafka:Describe*",
                      "kafka:Get*",
                      "kafka:List*",
                      "rds:Describe*",
                      "rds:List*",
                      "elasticfilesystem:Describe*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToRoute53Apis",
                  "Effect": "Allow",
                  "Action": [
                      "route53:Get*",
                      "route53:List*",
                      "route53resolver:List*"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "AllowTECloudInsightsReadAccessToDirectConnectApis",
                  "Effect": "Allow",
                  "Action": [
                      "directconnect:Describe*"
                  ],
                  "Resource": "*"
              }
          ]
      }
  9. In your preferred terminal, type in the following command to create the IAM policy for inventory monitoring incorporating the permissions file you just created:

    aws iam create-policy \
      --policy-name TECloudInsightsInventoryReadAccess \
      --policy-document file://te_cloud_insights_allow-all_inventory_policy.json
  10. Back in the ThousandEyes platform, open the Trust Policy dropdown.

  11. Copy the trust policy and save it as "iam_role_trust_policy.json".

    • Note: The trust policy shown below is for illustration purposes only. Your trust policy will show a different External ID, and that is the one you must copy.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:iam::381492131706:user/thousandeyes-integrations-user"
                  },
                  "Action": "sts:AssumeRole",
                  "Condition": {
                      "StringEquals": {
                          "sts:ExternalId": "1a123456789b2c12d34f5g67890hijk12345l678"
                      }
                  }
              }
          ]
      }
  12. In your terminal, type the following command to create the IAM role with the trust policy you just created:

    aws iam create-role \
      --role-name TECloudInsightsRole \
      --assume-role-policy-document file://iam_role_trust_policy.json
  13. Copy the role ARN from the output of the command for use in step 15.

    {
         "Role": {
              "Path": "/",
              "RoleName": "TECloudInsightsRole",
              "RoleId": "AROA123456789ABCDFG",
              "Arn": "arn:aws:iam::123456789456:role/TECloudInsightsRole",
              ...
  14. Attach the policy to the role. You will need the ACCOUNT_ID environment variable you created at Environment Variables.

    aws iam attach-role-policy \
      --role-name TECloudInsightsRole \
      --policy-arn arn:aws:iam::$ACCOUNT_ID:policy/TECloudInsightsInventoryReadAccess
  15. In the ThousandEyes platform, paste the IAM role ARN from step 13 into the Account Resource Name (ARN) field.

  16. Click Test.

    • Note: The Test function only validates the trust relationship between AWS and ThousandEyes; it does not validate the permission policy.

  17. If testing was successful, click Save.

CLI Steps for Flow Logs Monitoring

The following steps create:

  • An S3 bucket in your specified region, if not already done so.

  • An IAM permission policy to allow ThousandEyes read access to your AWS S3 resources.

  • An IAM role with a trust policy that allows ThousandEyes to assume the role to execute read actions and build an inventory.

  • An IAM policy to attach traffic flow permissions to the IAM role.

  • VPC flow logs for the specified VPC ID, with logs stored in a central S3 bucket, if not already done so.

  • An SNS topic, and a policy applied to it, if not already done so.

  • Configuration of the S3 bucket to send notifications to the SNS topic when objects are created.

Create the S3 bucket

  1. If not already created, in your terminal type the following command to create an S3 bucket in your specified AWS region. You will need the S3_BUCKET_NAME environment variable, and potentially the AWS_REGION environment variable, which you created in Environment Variables.

    • Use the LocationConstraint parameter only if your preferred region is not the default us-east-1 region. The command errors if you use the LocationConstraint parameter and your region is the default; the command also errors if the LocationConstraint parameter is missing and your region is not the default.

      aws s3api create-bucket \
        --bucket $S3_BUCKET_NAME \
        --create-bucket-configuration LocationConstraint=$AWS_REGION

IAM configuration for Flow Logs Monitoring

  1. Follow steps 1-7 of IAM Configuration for Inventory Monitoring, substituting "Flow Logs Monitoring" for "Inventory Monitoring" in step 5.

  2. Copy the permission policy and save it as "te_cloud_insights_allow-s3-bucket_flow_logs.json".

    • Note: The permission policy shown below is for illustration purposes only. Your permission policy may be different, and that is the one you must copy.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "AllowTECloudInsightsS3ReadOnly",
                  "Effect": "Allow",
                  "Action": [
                      "s3:Get*",
                      "s3:List*",
                      "s3:Describe*"
                  ],
                  "Resource": "arn:aws:s3:::*"
              }
          ]
      }
  3. In your terminal, replace all bucket names in the file with the bucket variable you created in Environment Variables by running:

    sed -i.bak "s/S3_BUCKET_NAME/$S3_BUCKET_NAME/g" te_cloud_insights_allow-s3-bucket_flow_logs.json
  4. Back in the ThousandEyes platform, open the Trust Policy dropdown.

  5. Copy the trust policy, enter a role name and a description, and save it as "iam_role_trust_policy.json".

    • Note: The trust policy shown below is for illustration purposes only. Your trust policy will show a different External ID, and that is the one you must copy.

      aws iam create-role \
          --role-name <ENTER ROLE NAME> \
          --description "<ENTER DESCRIPTION>" \
          --assume-role-policy-document '
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:iam::381492131706:user/thousandeyes-integrations-user"
                  },
                  "Action": "sts:AssumeRole",
                  "Condition": {
                      "StringEquals": {
                          "sts:ExternalId": "1a123456789b2c12d34f5g67890hijk12345l678"
                      }
                  }
              }
          ]
      }'
  6. In your terminal, type the following command to create the IAM role with the trust policy attached.

    aws iam create-role \
      --role-name TECloudInsightsFlowLogsRole \
      --assume-role-policy-document file://iam_role_trust_policy.json
    • Copy or make a note of the role ARN from within the output for use within step 10.

  7. Create the S3 read access policy for flow logs, using the permission policy saved in step 3.

    aws iam create-policy \
      --policy-name TECloudInsightsReadAccessToS3 \
      --policy-document file://te_cloud_insights_allow-s3-bucket_flow_logs.json
  8. Attach the S3 read access policy to the IAM role created in step 7.

    aws iam attach-role-policy \
      --role-name TECloudInsightsFlowLogsRole \
      --policy-arn arn:aws:iam::$ACCOUNT_ID:policy/TECloudInsightsReadAccessToS3
  9. Back in the ThousandEyes platform, paste or type the role ARN you copied/noted in step 7 into the Account Resource Name (ARN) field.

VPC Flow Log Configuration

  1. If not already created, in your terminal type the following command to create VPC flow logs for the specified VPC ID (see environment variables). The logs are stored in an S3 bucket, and various log parameters are specified, including the log format and aggregation interval. See create-flow-logs for more information.

      RESPONSE=$(aws ec2 create-flow-logs \
        --resource-type VPC \
        --region $AWS_REGION \
        --resource-ids $VPC_ID \
        --traffic-type ALL \
        --log-destination-type s3 \
        --log-destination arn:aws:s3:::$S3_BUCKET_NAME \
        --log-format '${account-id} ${srcaddr} ${srcport} ${dstaddr} ${dstport} ${protocol} ${packets} ${bytes} ${start} ${end} ${action} ${log-status} ${flow-direction} ${traffic-path} ${region}' \
        --max-aggregation-interval 600 \
        --destination-options PerHourPartition=true \
        --tag-specifications 'ResourceType=vpc-flow-log,Tags=[{Key=Name,Value=CloudInsightsFlow}]')

Creating SNS Topics

  1. If not already created, type the following command to create an SNS topic. You will need the SNS_TOPIC_NAME and AWS_REGION environment variables you created in Environment Variables. The command incorporates the creation of the SNS_TOPIC_ARN variable, to be used in steps 13, 15, and 16.

    SNS_TOPIC_ARN=$(aws sns create-topic --name $SNS_TOPIC_NAME --region $AWS_REGION --output text --query 'TopicArn')
    • Copy or make a note of the SNS topic ARN for use within step 18.

  2. Copy the following SNS topic policy and save as "sns_topic_policy.json".

        {
          "Sid": "AllowS3Publish",
          "Effect": "Allow",
          "Principal": {
            "Service": "s3.amazonaws.com"
          },
          "Action": "SNS:Publish",
          "Resource": "SNS_TOPIC_ARN",
          "Condition": {
            "StringEquals": {
              "aws:SourceAccount": "ACCOUNT_ID"
            },
            "ArnLike": {
              "aws:SourceArn": "arn:aws:s3:::S3_BUCKET_NAME"
            }
          }
        },
        {
          "Sid": "AllowTECloudInsightsSubscribe",
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::381492131706:user/thousandeyes-integrations-user"
          },
          "Action": "SNS:Subscribe",
          "Resource": "SNS_TOPIC_ARN"
        }
      ]
    }
    
  3. Create the SNS_TOPIC_POLICY variable, to be used in the next step, and replace the placeholders in the SNS topic policy with the relevant variables.

    SNS_TOPIC_POLICY=$(cat sns_topic_policy.json | sed "s/SNS_TOPIC_ARN/$SNS_TOPIC_ARN/" | sed "s/ACCOUNT_ID/$ACCOUNT_ID/" | sed "s/S3_BUCKET_NAME/$S3_BUCKET_NAME/")
  4. Apply the SNS topic policy to the SNS topic. You will need the SNS_TOPIC_POLICY variable you just created and the SNS_TOPIC_ARN variable you created in step 12.

    aws sns set-topic-attributes \
      --topic-arn $SNS_TOPIC_ARN \
      --attribute-name Policy \
      --attribute-value "$SNS_TOPIC_POLICY"

S3 Bucket Notification Configuration

  1. Create the S3_NOTIFICATION_CONFIGURATION variable, using the SNS_TOPIC_ARN variable you created in step 12. You will use this in the next step.

    S3_NOTIFICATION_CONFIGURATION=$(cat <<EOF
    {
      "TopicConfigurations": [
        {
          "Id": "S3ObjectCreatedNotification",
          "TopicArn": "$SNS_TOPIC_ARN",
          "Events": [
            "s3:ObjectCreated:*"
          ]
        }
      ]
    }
    EOF
    )
  2. Apply the S3 bucket notification configuration to your S3 bucket. You will need the S3_BUCKET_NAME environment variable you created in Environment Variables and the S3_NOTIFICATION_CONFIGURATION variable you just created.

      aws s3api put-bucket-notification-configuration \
        --bucket $S3_BUCKET_NAME \
        --notification-configuration "$S3_NOTIFICATION_CONFIGURATION"

Complete the Integration in ThousandEyes

  1. Back in the ThousandEyes platform, paste the SNS Topic ARN from step 12 into the Simple Notification Service (SNS) Topics ARNs field.

  2. Click Test.

    • Note: The Test function only validates the trust relationship between AWS and ThousandEyes; it does not validate the permission policy.

  3. If testing was successful, click Save.

Verifying the Configuration

In your various AWS consoles (VPC, S3, SNS), you can look to verify that:

Using CloudTrail to Log S3 Events

If you use AWS CloudTrail, you can further track your events with the following commands using AWS Athena (see Query AWS CloudTrail logs). Type or paste the following query into your terminal.

SELECT * FROM "default"."cloudtrail_logs_aws_cloudtrail_logs_986837508024_494b5bb3" WHERE eventSource IN ('sts.amazonaws.com', 's3.amazonaws.com', 'sns.amazonaws.com') AND errorCode = 'AccessDenied' AND eventname = 'GetObject' limit 100;

Last updated