AWS

Cloud Management Platform (CMP) seeds three AWS technologies: Amazon Web Services, AWS GovCloud (US), and AWS China. All three work the same way, and this page describes the first. See AWS GovCloud (US) and AWS China for their differences. When adding a handler, you choose the regions to import, and CMP creates one environment for each VPC in each region.

Credentials types

The first step of the add dialog is Credentials Type, which determines how CMP authenticates with AWS and which fields the rest of the form displays.

AWS GovCloud (US) and AWS China handlers always use an access key and secret key.

AWS permissions

Regardless of the credential type, CMP requires AWS permissions to perform its work. These policies are the reference set for the rest of the AWS pages.

The minimum for adding a handler and provisioning through it:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ce:GetCostAndUsage",
                "ec2:AssociateIamInstanceProfile",
                "ec2:AttachVolume",
                "ec2:CreateTags",
                "ec2:CreateVolume",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeAddresses",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeHosts",
                "ec2:DescribeIamInstanceProfileAssociations",
                "ec2:DescribeImages",
                "ec2:DescribeInstanceAttribute",
                "ec2:DescribeInstances",
                "ec2:DescribeInstanceStatus",
                "ec2:DescribeInstanceTypeOfferings",
                "ec2:DescribeInstanceTypes",
                "ec2:DescribeKeyPairs",
                "ec2:DescribeRegions",
                "ec2:DescribeReservedInstances",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeTags",
                "ec2:DescribeVolumeAttribute",
                "ec2:DescribeVolumes",
                "ec2:DescribeVolumesModifications",
                "ec2:DescribeVolumeStatus",
                "ec2:DescribeVpcs",
                "ec2:GetConsoleOutput",
                "ec2:ModifyVolume",
                "ec2:RebootInstances",
                "ec2:ReplaceIamInstanceProfileAssociation",
                "ec2:RunInstances",
                "ec2:StartInstances",
                "ec2:StopInstances",
                "ec2:TerminateInstances",
                "iam:PassRole",
                "kms:CreateGrant",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:ReEncrypt*",
                "pricing:GetProducts",
                "ram:ListResources",
                "resource-groups:GetGroupConfiguration",
                "resource-groups:ListGroups",
                "ssm:CreateDocument",
                "ssm:DeleteDocument",
                "ssm:DescribeDocument",
                "ssm:DescribeInstanceInformation",
                "ssm:GetCommandInvocation",
                "ssm:ListDocuments",
                "ssm:SendCommand"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

To let CMP run remote scripts on EC2 instances, add permission to create roles and instance profiles:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile"
            ],
            "Resource": "*"
        }
    ]
}

To import CloudWatch data into server statistics, add the CloudWatchReadOnlyAccess managed policy, or its equivalent:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:Describe*",
                "cloudwatch:Describe*",
                "cloudwatch:Get*",
                "cloudwatch:List*",
                "logs:Get*",
                "logs:List*",
                "logs:StartQuery",
                "logs:StopQuery",
                "logs:Describe*",
                "logs:TestMetricFilter",
                "logs:FilterLogEvents",
                "oam:ListSinks",
                "sns:Get*",
                "sns:List*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "oam:ListAttachedLinks"
            ],
            "Resource": "arn:aws:oam:*:*:sink/*"
        }
    ]
}

Add an AWS resource handler

These steps use an access key and secret key. For the other credential types, select the link for your credential type in the table above, then return here for the second form.

1. Go to Admin > Resource Handlers.

2. Select Add.

3. Select the Amazon Web Services tile. Use the Filter providers box if you do not see it.

4. Leave Credentials Type set to Account Credentials and Authentication Type set to Access & Secret Key.

5. Enter the Access Key ID and Secret Access Key. Both keys are available in the Security Credentials section of the AWS Console. If the password vault feature is enabled, Secret Access Key offers Locally Stored or Vault Managed; select Vault Managed to read the key from a configured vault provider.

6. Select Continue. CMP validates the credentials, then opens a second form for the handler’s settings.

7. Enter a Name, select at least one entry under Available Regions, and complete the optional settings: a description, the S3 billing bucket, an SSM ARN for managing resources through AWS Systems Manager, Split by region to split AWS sync jobs by region, and Add Name & Annotation tags to new servers.

8. Select Done. CMP creates the handler and starts a job to import the regions and sync the account’s existing instances.

   (opens full-size image in a new tab)

Use Verify Connection on the handler’s Overview tab to confirm the credentials work.

IAM profile on a server

When an EC2 instance has an IAM profile, its ARN appears in the Amazon Web Services Details section on the server’s details page.

Environments and AWS parameters

Each environment CMP creates for an AWS region carries a set of AWS-specific parameters on the environment’s AWS Parameters tab. The environment discovers which instance types, key pairs, and security groups are available in its region.

Images

Importing an AMI creates an OS build for it. Import the same AMI into another region, and CMP reuses the existing OS build rather than creating a second one, as long as the build name matches the AMI name. An admin can point an AMI at a different OS build to override this. For the import procedure, see Import AMIs.

Billing data

CMP can import AWS billing data and show billed costs for individual servers and for groups. The Billing and Reserved Instances tabs on an AWS handler are behind the resourcehandler::billingtab feature, which is disabled by default. See Resource handlers for how to enable a feature.

Set up billing

1. In AWS, set up an S3 bucket to receive cost and usage reports as .csv files. See Setting Up an Amazon S3 Bucket for AWS Cost and Usage Reports.
2. Open the AWS resource handler for that account and select Edit Settings.
3. Enter the bucket name in the S3 billing bucket field, then select Save.

The Import Public Cloud Billing Data recurring job downloads the previous month’s data. It is enabled and runs at 2:00 AM on the first of each month. Change its schedule to align with when your bills arrive, or run it on demand to retrieve existing data.

Where billing appears

• A group’s Billing tab graphs its charges per resource handler.
• A server’s Billing tab shows charges only for that instance.
• A handler’s Reserved Instances tab lists the reserved instances that CMP recommends buying based on the account’s usage.

Provision to EC2 Dedicated Hosts

CMP can provision instances onto your EC2 Dedicated Hosts, either a specific host or a host resource group. Set a value for Dedicated Host or Dedicated Host Group, not both. If both have a value, Dedicated Host takes precedence.

Prerequisites

• For Dedicated Host, an AWS dedicated host.
• For Dedicated Host Group, an AWS host resource group with the right licensing, and at least one licensed AMI allocated to a dedicated host. Note the licensed AMI’s ID, which you need in CMP. In AWS, the licenses are under License Manager > Customer Managed Licenses.

Set up a dedicated host

1. In the AWS resource handler, select Import AMIs, then select an AMI that is not licensed. An AMI tied to a license configuration makes AWS expect a host group, and provisioning fails.
2. Open the environment and go to the AWS Parameters tab.
3. Select Import in the Dedicated Host parameter to import the values from AWS. A host added to a host resource group in AWS does not appear because AWS does not allow launching directly onto it.
4. Choose a value for Dedicated Host.
5. Select the host on the order form.

Set up a dedicated host group

1. In the AWS resource handler, select Import AMIs and select a licensed AMI.
2. Open the environment and go to the AWS Parameters tab.
3. Select Import in the Dedicated Host Group parameter to import the values from AWS.
4. Choose a value for Dedicated Host Group.
5. Select the host group on the order form.

Importing also finds host resource groups shared with the account through AWS Resource Access Manager, if the handler’s credentials have the ram:ListResources and resource-groups:GetGroupConfiguration permissions. Without them, CMP imports only the groups the account owns.

Where an environment has no values for either parameter, because none have been imported or none exist, the order form shows a free-text field and rejects a name that does not resolve.

One AWS error is worth recognizing. An error occurred (InvalidParameterValue) when calling the RunInstances operation: Multiple resource groups match the host bound licenses in request means the AMI is tied to a license configuration in a host group, but no host group was selected. Select an AMI without a license configuration, or select the host group.

Volumes

Beyond disk size, AWS disks carry a volume type and, for some types, a minimum size that AWS enforces.

• A volume with no type set uses gp2, the AWS default.
• An io1 volume requires at least 100 IOPS.
• A gp2 volume must be at least 4 GiB. An st1 or sc1 volume must be at least 500 GiB.
• A volume can be encrypted using AWS-managed encryption.

A modification order placed through the API accepts these parameters when adding or changing a disk:

• disk_size: the new size for the original volume.
• new_disk_size: the size of a volume to add.
• ebs_volume_type: the type of the new volume. Accepted values are io1, gp2, gp3, st1, sc1, and standard.
• iops: accepted with the io1 volume type.
• aws_volume_encryption: True or False, to encrypt the added volume.
• aws_volume_encryption_key_arn: encrypts with a KMS key other than the account default. Leave it blank to use the account key. Single-region and multi-region KMS keys both work, and a multi-region key must be replicated to the regions where you plan to use it.

Windows instances

AWS relies on SSH keys to reach instances, and running remote scripts on Windows requires additional configuration. CMP will use a password if supplied, as described under Passwords. If you provide an SSH key instead, CMP asks EC2 for the Administrator password, which works only when the instance is configured in EC2 for get_password_data to succeed.

To run remote scripts without a username and password, enable tech-specific script execution.