Document needed permissions

[tyler-ball]

For Test Kitchen to create and manage the AWS host, the provisioning account needs certain permissions. These permissions are different between Windows and Linux guests. We should document these needed permissions so users can setup a provisioning account with the minimum required access.

For example we need to be able to query AMI information to see root_device status and look at an instance's console for Windows guests.

[diranged]

:+1: I spent a few hours trying to narrow down the permissions the other night and ran into a bunch of roadblocks. Ideally we'd be able to setup a policy that specifically requires a number of things:

• Instances are tagged in a particular way
• Tags are only created/modified during the RunInstance call
• SecurityGroups and SSH Keys are generated with a particular name/tag
• Optionally a specific VPC that we want things launched in
• All Destroy/Delete calls are limited to the naming/tagging scheme

[bpholt]

FWIW, I used CloudTrail to see exactly what calls were made to test several Linux and Windows based EC2 instances during a recent run in our CI environment. This may not be exhaustive (I'm not sure we're using all the features the EC2 driver has to offer) but it could be a good start to defining a narrower list in the documentation.

ec2:CreateTags
ec2:DescribeImages
ec2:DescribeInstances
ec2:DescribeVolumes
ec2:GetConsoleOutput
ec2:RunInstances
ec2:TerminateInstances

We attach an IAM policy like the following to the ECS task that is responsible for running Test Kitchen (and will therefore be creating and destroying the actual instances) to avoid having to grant AmazonEC2FullAccess.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Creator": "test-kitchen"
                }
            },
            "Action": [
                "ec2:TerminateInstances"
            ],
            "Resource": [
                "arn:aws:ec2:us-west-2:xxxxxxxxxxxx:*"
            ],
            "Effect": "Allow",
            "Sid": "TerminateTestKitchenInstances"
        },
        {
            "Action": [
                "ec2:RunInstances",
                "ec2:CreateTags",
                "ec2:Get*",
                "ec2:Describe*",
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow",
            "Sid": "RunAndTagTestKitchenInstances"
        },
        {
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam:: xxxxxxxxxxxx:role/TestKitchenInstanceRole"
            ],
            "Effect": "Allow",
            "Sid": "PassTestKitchenRole"
        }
    ]
}

The TestKitchenInstanceRole allows access to some private S3 buckets (so Chef can download needed resources as per our internal recipes) and to ec2:DescribeInstances.