aws

aws Cookbook

Overview

This cookbook provides resources for configuring and managing nodes running in Amazon Web Services as well as several AWS service offerings.

Included resources:

• CloudFormation Stack Management (cloudformation_stack)
• CloudWatch (cloudwatch)
• CloudWatch Instance Monitoring (instance_monitoring)
• DynamoDB (dynamodb_table)
• EBS Volumes (ebs_volume)
• EC2 Instance Role (instance_role)
• EC2 Instance Termination Protection (instance_term_protection)
• Elastic IPs (elastic_ip)
• Elastic Load Balancer (elastic_lb)
• IAM User, Group, Policy, and Role Management: (iam_user, iam_group, iam_policy, iam_role)
• Kinesis Stream Management (kinesis_stream)
• Resource Tags (resource_tag)
• Route53 DNS Records (route53_record)
• Route53 DNS Zones (route53_zone)
• S3 Files (s3_file)
• S3 Buckets (s3_bucket)
• Secondary IPs (secondary_ip)
• Security Groups (security_group)
• AWS SSM Parameter Store (ssm_parameter_store)
• Autoscaling (autoscaling)

Unsupported AWS resources that have other cookbooks include but are not limited to:

• aws_security

Important - Security Implications

Please review any and all security implications of using any of these resources. This cookbook presents resources which could easily be poorly implemented, abused or exploited.

• They have the ability to perform destructive actions (ex. delete *)
• They manage sensitive resources (ex. IAM/SSM)
• They require IAM keys which could be compromised

You will want to understand any and all security implications and architect your implementation accordingly before proceeding.

Some recommendations are below:

• Do not use IAM credentials of the node - pass a separate set of credentials to these resources
• Use IAM to restrict credentials to only the actions required, implementing conditions whenever necessary (follow least privileged principles.)

See iam_restrictions_and_conditions

• Follow any and all aws best practices for managing credentials and security
• Review your cookbook implementation as cloudformation or alternative tooling may be a better fit for managing aws infrastructure as code.

Maintainers

This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit sous-chefs.org or come chat with us on the Chef Community Slack in #sous-chefs.

Requirements

Platforms

• Any platform supported by Chef and the AWS-SDK

Chef

• Chef 15.3+

Cookbooks

• None

Credentials

In order to manage AWS components, authentication credentials need to be available to the node. There are 3 ways to handle this:

1. Explicitly set the credentials when using the resources
2. Use the credentials in the ~/.aws/credentials file
3. Let the resource pick up credentials from the IAM role assigned to the instance

Also new resources can now assume an STS role, with support for MFA as well. Instructions are below in the relevant section.

Using resource parameters

In order to pass the credentials to the resource, credentials must be available to the node. There are a number of ways to handle this, such as node attributes applied to the node or via Chef roles/environments.

We recommend storing these in an encrypted databag, and loading them in the recipe where the resources are used.

Example Data Bag:

% knife data bag show aws main
{
  "id": "main",
  "aws_access_key_id": "YOUR_ACCESS_KEY",
  "aws_secret_access_key": "YOUR_SECRET_ACCESS_KEY",
  "aws_session_token": "YOUR_SESSION_TOKEN"
}

This can be loaded in a recipe with:

aws = data_bag_item('aws', 'main')

And to access the values:

aws['aws_access_key_id']
aws['aws_secret_access_key']
aws['aws_session_token']

We'll look at specific usage below.

Using local credentials

If credentials are not supplied via parameters, resources will look for the credentials in the ~/.aws/credentials file:

[default]
aws_access_key_id = ACCESS_KEY_ID
aws_secret_access_key = ACCESS_KEY

Note that this also accepts other profiles if they are supplied via the ENV['AWS_PROFILE'] environment variable.

Using IAM instance role

If your instance has an IAM role, then the credentials can be automatically resolved by the cookbook using Amazon instance metadata API.

You can then omit the authentication properties aws_secret_access_key and aws_access_key when using the resource.

Of course, the instance role must have the required policies. Here is a sample policy for EBS volume management:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ec2:AttachVolume",
        "ec2:CreateVolume",
        "ec2:ModifyInstanceAttribute",
        "ec2:ModifyVolumeAttribute",
        "ec2:DescribeVolumeAttribute",
        "ec2:DescribeVolumeStatus",
        "ec2:DescribeVolumes",
        "ec2:DetachVolume",
        "ec2:EnableVolumeIO"
      ],
      "Sid": "Stmt1381536011000",
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    }
  ]
}

For resource tags:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ec2:CreateTags",
        "ec2:DescribeTags"
      ],
      "Sid": "Stmt1381536708000",
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    }
  ]
}

Assuming roles via STS and using MFA

The following is an example of how roles can be assumed using MFA. The following can also be used to assumes roles that do not require MFA, just ensure that the MFA arguments (serial_number and token_code) are omitted.

This assumes you have also stored the cfn_role_arn, and mfa_serial attributes as well, but there are plenty of ways these attributes can be supplied (they could be stored locally in the consuming cookbook, for example).

Note that MFA codes cannot be recycled, hence the importance of creating a single STS session and passing that to resources. If multiple roles need to be assumed using MFA, it is probably prudent that these be broken up into different recipes and chef-client runs.

…

When running the cookbook, ensure that an attribute JSON is passed that supplies the MFA code. Example using chef-zero:

echo '{ "aws": { "mfa_code": "123456" } }' > mfa.json && chef-client -z -o 'recipe[aws_test]' -j mfa.json

Running outside of an AWS instance

region can be specified on each resource if the cookbook is being run outside of an AWS instance. This can prevent some kinds of failures that happen when resources try to detect region.

aws_cloudformation_stack 'kitchen-test-stack' do
  action :create
  template_source 'kitchen-test-stack.tpl'
  region 'us-east-1'
end

Resources

aws_cloudformation_stack

Manage CloudFormation stacks.

Actions

• create: Creates the stack, or updates it if it already exists.
• delete: Begins the deletion process for the stack.

Properties

• template_source: Required - the location of the CloudFormation template file. The file should be stored in the files directory in the cookbook.
• parameters: An array of parameter_key and parameter_value pairs for parameters in the template. Follow the syntax in the example above.
• disable_rollback: Set this to true if you want stack rollback to be disabled if creation of the stack fails. Default: false
• stack_policy_body: Optionally define a stack policy to apply to the stack, mainly used in protecting stack resources after they are created. For more information, see Prevent Updates to Stack Resources in the CloudFormation user guide.
• iam_capability: Set to true to allow the CloudFormation template to create IAM resources. This is the equivalent of setting CAPABILITY_IAM When using the SDK or CLI. Default: false
• named_iam_capability: Set to true to allow the CloudFormation template to create IAM resources with custom names. This is the equivalent of setting CAPABILITY_NAMED_IAM When using the SDK or CLI. Default: false

Examples

aws_cloudformation_stack 'example-stack' do
  region 'us-east-1'
  template_source 'example-stack.tpl'
  parameters ([
    {
      :parameter_key => 'KeyPair',
      :parameter_value => 'user@host'
    },
    {
      :parameter_key => 'SSHAllowIPAddress',
      :parameter_value => '127.0.0.1/32'
    }
  ])
end

aws_cloudwatch

Use this resource to manage CloudWatch alarms.

Actions

• create - Create or update CloudWatch alarms.
• delete - Delete CloudWatch alarms.
• disable_action - Disable action of the CloudWatch alarms.
• enable_action - Enable action of the CloudWatch alarms.

Properties

• aws_secret_access_key, aws_access_key and optionally aws_session_token - required, unless using IAM roles for authentication.
• alarm_name - the alarm name. If none is given on assignment, will take the resource name.
• alarm_description - the description of alarm. Can be blank also.
• actions_enabled - true for enable action on OK, ALARM or Insufficient data. if true, any of ok_actions, alarm_actions or insufficient_data_actions must be specified.
• ok_actions - array of action if alarm state is OK. If specified actions_enabled must be true.
• alarm_actions - array of action if alarm state is ALARM. If specified actions_enabled must be true.
• insufficient_data_actions - array of action if alarm state is INSUFFICIENT_DATA. If specified actions_enabled must be true.
• metric_name - CloudWatch metric name of the alarm. eg - CPUUtilization.Required parameter.
• namespace - namespace of the alarm. eg - AWS/EC2, required parameter.
• statistic - statistic of the alarm. Value must be in any of SampleCount, Average, Sum, Minimum or Maximum. Required parameter.
• extended_statistic - extended_statistic of the alarm. Specify a value between p0.0 and p100. Optional parameter.
• dimensions - dimensions for the metric associated with the alarm. Array of name and value.
• period - in seconds, over which the specified statistic is applied. Integer type and required parameter.
• unit - unit of measure for the statistic. Required parameter.
• evaluation_periods - number of periods over which data is compared to the specified threshold. Required parameter.
• threshold - value against which the specified statistic is compared. Can be float or integer type. Required parameter.
• comparison_operator - arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand.

For more information about parameters, see CloudWatch Identifiers in the Using CloudWatch guide.

Examples

aws_cloudwatch "kitchen_test_alarm" do
  period 21600
  evaluation_periods 2
  threshold 50.0
  comparison_operator "LessThanThreshold"
  metric_name "CPUUtilization"
  namespace "AWS/EC2"
  statistic "Maximum"
  dimensions [{"name" : "InstanceId", "value" : "i-xxxxxxx"}]
  action :create
end

aws_dynamodb_table

Use this resource to create and delete DynamoDB tables. This includes the ability to add global secondary indexes to existing tables.

Actions

• create: Creates the table. Will update the following if the table exists:
• global_secondary_indexes: Will remove non-existent indexes, add new ones, and update throughput for existing ones. All attributes need to be present in attribute_definitions. No effect if the resource is omitted.
• `stream_