AWS Keys Integration

AWS Keys integration is used to connect Shippable to AWS services, such as:

  • ECR
  • ECS
  • EC2
  • S3
  • Any other service that needs AWS Access and Secret keys to connect

Creating an Account Integration

You can add this account integration by following steps on the Adding an account integration page.

Here is the information you need to create this integration:

  • Integration type -- AWS Keys
  • Name -- choose a friendly name for the integration
  • Access Key: Access key obtained from AWS
  • Secret Key: Secret key obtained from AWS

Usage in CI

Note: Since this is integration is of generic type, it can be plugged into other sections like hub, deploy in the following use cases:

Usage in Assembly Lines

The AWS Keys integration can be used in the following resources:

The following scenarios need this integration:

IAM Policies

There are two ways to use an AWS Keys integration in Shippable Assembly Lines:

  1. automated, managed Amazon ECS deployments via managed deploy jobs
  2. AWS CLI configuration via cliConfig resources in a runSh job

For managed deployments via deploy jobs, the keys need to belong to a user with a policy attached that will allow Shippable to create, delete, and update services and register task definitions. Here is an example policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DeregisterTaskDefinition",
                "ecs:UpdateService",
                "ecs:CreateService",
                "ecs:RegisterTaskDefinition",
                "ecs:DeleteService",
                "ecs:DescribeServices",
                "ecs:ListTaskDefinitions"
            ],
            "Resource": "*"
        }
    ]
}

If your managed deployment includes a loadBalancer, the policy will also need permission to assume a role for the load balancer:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DeregisterTaskDefinition",
                "ecs:UpdateService",
                "ecs:CreateService",
                "ecs:RegisterTaskDefinition",
                "ecs:DeleteService",
                "ecs:DescribeServices",
                "ecs:ListTaskDefinitions"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole",
                "iam:ListRoles"
            ],
            "Resource": "arn:aws:iam::*:*"
        }
    ]
}

And if you are adding scaling policies or AWS CloudWatch metric alarms, you will need additional permissions for that as well.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "application-autoscaling:RegisterScalableTarget",
                "application-autoscaling:DeregisterScalableTarget",
                "application-autoscaling:PutScalingPolicy",
                "application-autoscaling:DeleteScalingPolicy",
                "cloudwatch:PutMetricAlarm",
                "cloudwatch:DeleteAlarms",
                "ecs:DeregisterTaskDefinition",
                "ecs:UpdateService",
                "ecs:CreateService",
                "ecs:RegisterTaskDefinition",
                "ecs:DeleteService",
                "ecs:DescribeServices",
                "ecs:ListTaskDefinitions"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole",
                "iam:ListRoles"
            ],
            "Resource": "arn:aws:iam::*:*"
        }
    ]
}

For cliConfig resources, you should make sure that your policy allows you to perform whatever actions you plan to take in your custom script. This could mean ECR actions to pull images, ECS actions to create deployments, EC2 actions to run instances, etc.

Default Environment Variables

When you create a resource with this integration, and use it as an IN or OUT for a job that can execute user defined scripts, a set of environment variables are configured by the platform that may be useful to set the context before user defined scripts execute as part of the job. These variables are available when a resource with this integration type is used.

<NAME> is the the friendly name of the resource.

Environment variable Description
<NAME>_INTEGRATION_ACCESSKEY Access key supplied in the integration
<NAME>_INTEGRATION_SECRETKEY Secret key supplied in the integration

When you create a resource with this integration, and use it as an IN or OUT for a runSh or runCI job, a set of environment variables is automatically made available that you can use in your scripts.

Shippable Utility Functions

The platform also provides a command line utility called shipctl that can be used to retrieve the values of these environment variables.

The specific function that can be used in the jobs yml is: shipctl get_integration_resource_field <resource name> <field name>.

Here is a table that provides the mapping from the environment variable to the field name.

Environment variable Field Name
<NAME>_INTEGRATION_ACCESSKEY accessKey
<NAME>_INTEGRATION_SECRETKEY secretKey

More information on other utility functions is documented here.