Amazon Web Services

Note

There are more actors available in the kingpin.actors.aws module, but the below are the most commonly used.

CloudFormation

class kingpin.actors.aws.cloudformation.Stack(*args, **kwargs)[source]

Manages the state of a CloudFormation stack.

This actor can manage the following aspects of a CloudFormation stack in Amazon:

Ensure that the Stack is present or absent.

Monitor and update the stack Template and Parameters as necessary.

Default Parameters

If your CFN stack defines parameters with defaults, Kingpin will use the defaults unless the parameters are explicitly specified.

NoEcho Parameters

If your CFN stack takes a Password as a parameter or any other value thats secret and you set NoEcho: True on that parameter, Kingpin will be unable to diff it and compare whether or not the desired setting matches whats in Amazon. A warning will be thrown, and the rest of the actor will continue to operate as normal.

If any other difference triggers a Stack Update, the desired value for the parameter with NoEcho: True will be pushed in addition to all of the other stack parameters.

Options

Name:

The name of the queue to create

State:

(str) Present or Absent. Default: “present”

Capabilities:

(CapabilitiesConfig, None)

A list of CFN capabilities to add to the stack.

Disable_rollback:

Set to True to disable rollback of the stack if creation failed.

On_failure:

(OnFailureConfig, None)

One of the following strings: DO_NOTHING, ROLLBACK, DELETE

Default: DELETE

Parameters:

(ParametersConfig, None)

A dictionary of key/value pairs used to fill in the parameters for the CloudFormation template.

Region:

AWS region (or zone) string, like ‘us-west-2’.

Role_arn:

The Amazon IAM Role to use when executing the stack.

Template:

String of path to CloudFormation template. Can either be in the form of a local file path (ie, /my_template.json) or a URI (ie s3://bucket-name/cfn.json).

Timeout_in_minutes:

The amount of time that can pass before the stack status becomes CREATE_FAILED.

Enable_termination_protection:

Whether termination protection is enabled for the stack.

Examples

{
    "actor": "aws.cloudformation.Stack",
    "desc": "Manages the state of a CloudFormation stack",
    "options": {
        "capabilities": [ "CAPABILITY_IAM" ],
        "on_failure": "DELETE",
        "name": "%CFN_NAME%",
        "parameters": {
            "test_param": "%TEST_PARAM_NAME%",
        },
        "region": "us-west-1",
        "role_arn": "arn:aws:iam::123456789012:role/DeployRole",
        "state": "present",
        "template": "/examples/cloudformation_test.json",
        "timeout_in_minutes": 45,
        "enable_termination_protection": true,
    }
}

Dry Mode

Validates the template, verifies that an existing stack with that name does not exist. Does not create the stack.

Identity and Access Management (IAM)

class kingpin.actors.aws.iam.Role(*args, **kwargs)[source]

Manages an IAM Role.

This actor manages the state of an Amazon IAM Role.

Currently we can:

Ensure is present or absent

Manage the inline policies for the role

Manage the Assume Role Policy Document

Options

Name:

(str) Name of the Role to manage

State:

(str) Present or Absent. Default: “present”

Inline_policies:

(str,array) A list of strings that point to JSON files to use as inline policies. You can also pass in a single inline policy as a string. Default: None

Assume_role_policy_document:

(str) A string with an Amazon IAM Assume Role policy. Not providing this causes Kingpin to ignore the value, and Amazon defaults the role to an ‘EC2’ style rule. Supplying the document will cause Kingpin to ensure the assume role policy is correct.

Default:

{ "Version": "2012-10-17",
  "Statement": [
      { "Effect": "Allow",
        "Principal": {
            "Service": "ec2.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      }
  ]
}

Example

{ "actor": "aws.iam.Role",
  "desc": "Ensure that myapp exists",
  "options": {
    "name": "myapp",
    "state": "present",
    "inline_policies": [
      "read-all-s3.json",
      "create-other-stuff.json"
    ]
  }
}

Dry run

Will let you know if the group exists or not, and what changes it would make to the groups policy and settings. Will also parse the inline policies supplied, make sure any tokens in the files are replaced, and that the files are valid JSON.

class kingpin.actors.aws.iam.Group(*args, **kwargs)[source]

Manages an IAM Group.

This actor manages the state of an Amazon IAM Group.

Currently we can:

Ensure is present or absent

Manage the inline policies for the group

Purge (or not) all group members and delete the group

Options

Name:: (str) Name of the Group profile to manage
Force:: (bool) Forcefully delete the group (explicitly purging all group memberships). Default: false
State:: (str) Present or Absent. Default: “present”
Inline_policies:: (str,array) A list of strings that point to JSON files to use as inline policies. You can also pass in a single inline policy as a string. Default: None

Example

{ "actor": "aws.iam.Group",
  "desc": "Ensure that devtools exists",
  "options": {
    "name": "devtools",
    "state": "present",
    "inline_policies": [
      "read-all-s3.json",
      "create-other-stuff.json"
    ]
  }
}

Dry run

Will let you know if the group exists or not, and what changes it would make to the groups policy and settings. Will also parse the inline policies supplied, make sure any tokens in the files are replaced, and that the files are valid JSON.

class kingpin.actors.aws.iam.User(*args, **kwargs)[source]

Manages an IAM User.

This actor manages the state of an Amazon IAM User.

Currently we can:

Ensure is present or absent

Manage the inline policies for the user

Manage the groups the user is in

Options

Name:: (str) Name of the User profile to manage
State:: (str) Present or Absent. Default: “present”
Groups:: (str,array) A list of groups for the user to be a member of. Default: None
Inline_policies:: (str,array) A list of strings that point to JSON files to use as inline policies. Default: None

Example

{ "actor": "aws.iam.User",
  "desc": "Ensure that Bob exists",
  "options": {
    "name": "bob",
    "state": "present",
    "groups": "my-test-group",
    "inline_policies": [
      "read-all-s3.json",
      "create-other-stuff.json"
    ]
  }
}

Dry run

Will let you know if the user exists or not, and what changes it would make to the users policy and settings. Will also parse the inline policies supplied, make sure any tokens in the files are replaced, and that the files are valid JSON.

class kingpin.actors.aws.iam.InstanceProfile(*args, **kwargs)[source]

Manages an IAM Instance Profile.

This actor manages the state of an Amazon IAM Instance Profile.

Currently we can:

Ensure is present or absent

Assign an IAM Role to the Instance Profile

Options

Name:: (str) Name of the Role to manage
State:: (str) Present or Absent. Default: “present”
Role:: (str) Name of an IAM Role to assign to the Instance Profile. Default: None

Example

{ "actor": "aws.iam.InstanceProfile",
  "desc": "Ensure that my-ecs-servers exists",
  "options": {
    "name": "my-ecs-servers",
    "state": "present",
    "role": "some-iam-role",
  }
}

Dry run

Will let you know if the profile exists or not, and what changes it would make to the profile.

Simple Storage Service (S3)

class kingpin.actors.aws.s3.Bucket(*args, **kwargs)[source]

Manage the state of a single S3 Bucket.

The actor has the following functionality:

Ensure that an S3 bucket is present or absent.

Manage the bucket policy.

Manage the bucket Lifecycle configurations.

Enable or Suspend Bucket Versioning. Note: It is impossible to actually _disable_ bucket versioning – once it is enabled, you can only suspend it, or re-enable it.

Enable Event Notification. (limited to SQS for now)

Note about Buckets with Files

Amazon requires that an S3 bucket be empty in order to delete it. Although we could recursively search for all files in the bucket and then delete them, this is a wildly dangerous thing to do inside the confines of this actor. Instead, we raise an exception and alert the you to the fact that they need to delete the files themselves.

Options

Name:

The name of the bucket to operate on

State:

(str) Present or Absent. Default: “present”

Lifecycle:

(LifecycleConfig, None)

A list of individual Lifecycle configurations. Each dictionary includes keys for:

id
status
filter (or prefix, which is deprecated)

and at least one of:

transitions (or transition, which is deprecated)
noncurrent_version_transitions (or noncurrent_version_transition)
expiration
noncurrent_version_expiration
abort_incomplete_multipart_upload

If an empty list is supplied, or the list in any way does not match what is currently configured in Amazon, the appropriate changes will be made.

Logging:

(LoggingConfig, None)

If a dictionary is supplied ({'target': 'logging_bucket', 'prefix': '/mylogs'}), then we will configure bucket logging to the supplied bucket and prefix. If prefix is missing then no prefix will be used.

If target is supplied as an empty string (''), then we will disable logging on the bucket. If None is supplied, we will not manage logging either way.

Tags:

(TaggingConfig, None)

A list of dictionaries with a key and value key. Defaults to an empty list, which means that if you manually add tags, they will be removed.

Policy:

(str, None) A JSON file with the bucket policy. Passing in a blank string will cause any policy to be deleted. Passing in None (or not passing it in at all) will cause Kingpin to ignore the policy for the bucket entirely. Default: None

Public_access_block_configuration:

(PublicAccessBlockConfig, None)

If a dictionary is supplied, then it must conform to the PublicAccessBlockConfig type and include all of the Public Access Block Configuration parameters.

If an empty dictionary is supplied, then Kingpin will explicitly remove any Public Access Block Configurations from the bucket.

Finally, if None is supplied, Kingpin will ignore the checks entirely on this portion of the bucket configuration.

Default: None

Region:

AWS region (or zone) name, such as us-east-1 or us-west-2

Versioning:

(bool, None): Whether or not to enable Versioning on the bucket. If “None”, then we don’t manage versioning either way. Default: None

Notification_configuration:

(NotificationConfiguration, None)

If a dictionary is supplised, then it must conform to NotificationConfiguration, type and include mapping queuearn & events

If an empty dictionary is supplied, then Kingpin will explicitly remove any Notification Configuration from the bucket.

Finally, If None is supplies, Kingoin will ignore the checks entire on this portion of the bucket configuration

Examples

{
  "actor": "aws.s3.Bucket",
  "options": {
    "name": "kingpin-integration-testing",
    "region": "us-west-2",
    "policy": "./examples/aws.s3/amazon_put.json",
    "lifecycle": [
       {
         "id": "main",
         "status": "Enabled",
         "filter": {
             "prefix": "/"
         },
         "expiration": 30,
       }
    ],
    "logging": {
      "target": "logs.myco.com",
      "prefix": "/kingpin-integratin-testing"
    },
    "tags": [
      {"key": "my_key", "value": "billing-grp-1"},
    ],
    "versioning": true,
    "notification_configuration": {
       "queue_configurations": [
         {
           "queue_arn": "arn:aws:sqs:us-east-1:1234567:some_sqs",
           "events": [
                         "s3:ObjectCreated:*",
                         "s3:ObjectRemoved*"
                     ]
         }
       ]
    }
  }
}

Dry Mode

Finds the bucket if it exists (or tells you it would create it). Describes each potential change it would make to the bucket depending on the configuration of the live bucket, and the options that were passed into the actor.

Will gracefully fail and alert you if there are files in the bucket and you are trying to delete it.