Kingpin: Deployment Automation Engine¶

kingpin.actors.aws.base¶

The AWS Actors allow you to interact with the resources (such as SQS and ELB) inside your Amazon AWS account. These actors all support dry runs properly, but each actor has its own caveats with dry=True. Please read the instructions below for using each actor.

Required Environment Variables

_Note, these can be skipped only if you have a .aws/credentials file in place._

exception kingpin.actors.aws.base.InvalidPolicy[source]

Raised when Amazon indicates that policy JSON is invalid.

kingpin.actors.aws.cloudformation¶

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

Creates a CloudFormation stack.

Creates a CloudFormation stack from scratch and waits until the stack is fully built before exiting the actor.

Options

Capabilities:	A list of CF capabilities to add to the stack.
Disable_rollback:
	Set to True to disable rollback of the stack if creation failed.
Name:	The name of the queue to create
Parameters:	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’
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 https://my_site.com/cf.json).
Timeout_in_minutes:
	The amount of time that can pass before the stack status becomes CREATE_FAILED.

Examples

{ "desc": "Create production backend stack",
  "actor": "aws.cloudformation.Create",
  "options": {
    "capabilities": [ "CAPABILITY_IAM" ],
    "disable_rollback": true,
    "name": "%CF_NAME%",
    "parameters": {
      "test_param": "%TEST_PARAM_NAME%",
    },
    "region": "us-west-1",
    "template": "/examples/cloudformation_test.json",
    "timeout_in_minutes": 45,
  }
}

Dry Mode

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

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

Deletes a CloudFormation stack

Options

Name:	The name of the queue to create
Region:	AWS region (or zone) string, like ‘us-west-2’

Examples

{ "desc": "Delete production backend stack",
  "actor": "aws.cloudformation.Create",
  "options" {
    "region": "us-west-1",
    "name": "%CF_NAME%",
  }
}

Dry Mode

Validates that the CF stack exists, but does not delete it.

kingpin.actors.aws.elb¶

class kingpin.actors.aws.elb.WaitUntilHealthy(*args, **kwargs)[source]

Wait indefinitely until a specified ELB is considered “healthy”.

This actor will loop infinitely until a healthy threshold of the ELB is met. The threshold can be reached when the count as specified in the options is less than or equal to the number of InService instances in the ELB.

Another situation is for count to be a string specifying a percentage (see examples). In this case the percent of InService instances has to be greater than the count percentage.

Options

Name:	The name of the ELB to operate on
Count:	Number, or percentage of InService instance to consider this ELB healthy
Region:	AWS region (or zone) name, such as us-east-1 or us-west-2

Examples

{ "actor": "aws.elb.WaitUntilHealthy",
  "desc": "Wait until production-frontend has 16 hosts",
  "options": {
    "name": "production-frontend",
    "count": 16,
    "region": "us-west-2"
  }
}

{ "actor": "aws.elb.WaitUntilHealthy",
  "desc": "Wait until production-frontend has 85% of hosts in-service",
  "options": {
    "name": "production-frontend",
    "count": "85%",
    "region": "us-west-2"
  }
}

Dry Mode

This actor performs the finding of the ELB as well as calculating its health at all times. The only difference in dry mode is that it will not re-count the instances if the ELB is not healthy. A log message will be printed indicating that the run is dry, and the actor will exit with success.

class kingpin.actors.aws.elb.SetCert(*args, **kwargs)[source]

Find a server cert in IAM and use it for a specified ELB.

Options

Region:	(str) AWS region (or zone) name, like us-west-2
Name:	(str) Name of the ELB
Cert_name:	(str) Unique IAM certificate name, or ARN
Port:	(int) Port associated with the cert. (default: 443)

Example

{ "actor": "aws.elb.SetCert",
  "desc": "Run SetCert",
  "options": {
    "cert_name": "new-cert",
    "name": "some-elb",
    "region": "us-west-2"
  }
}

Dry run

Will check that ELB and Cert names are existent, and will also check that the credentials provided for AWS have access to the new cert for ssl.

class kingpin.actors.aws.elb.RegisterInstance(*args, **kwargs)[source]

Add an EC2 instance to a load balancer.

Options

Elb:	(str) Name of the ELB
Instances:	(str, list) Instance id, or list of ids. Default “self” id.
Region:	(str) AWS region (or zone) name, like us-west-2
Enable_zones:	(bool) add all available AZ to the elb. Default: True

Example

{ "actor": "aws.elb.RegisterInstance",
  "desc": "Run RegisterInstance",
  "options": {
    "elb": "prod-loadbalancer",
    "instances": "i-123456",
    "region": "us-east-1",
  }
}

Dry run

Will find the specified ELB, but not take any actions regarding instances.

class kingpin.actors.aws.elb.DeregisterInstance(*args, **kwargs)[source]

Remove EC2 instance(s) from an ELB.

Options

Elb:	(str) Name of the ELB. Optionally this may also be a *.
Instances:	(str, list) Instance id, or list of ids
Region:	(str) AWS region (or zone) name, like us-west-2
Wait_on_draining:
	(bool) Whether or not to wait for connection draining

Example

{ "actor": "aws.elb.DeregisterInstance",
  "desc": "Run DeregisterInstance",
  "options": {
    "elb": "my-webserver-elb",
    "instances": "i-abcdeft",
    "region": "us-west-2"
  }
}

Extremely simple way to remove the local instance running this code from all ELBs its been joined to:

{ "actor": "aws.elb.DeregisterInstance",
  "desc": "Run DeregisterInstance",
  "options": {
    "elb": "*",
    "region": "us-west-2"
  }
}

Dry run

Will find the ELB but not take any actions regarding the instances.

kingpin.actors.aws.iam¶

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.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.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: None

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.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.

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

Uploads a new SSL Cert to AWS IAM.

Options

Private_key_path:
	(str) Path to the private key.
Path:	(str) The AWS “path” for the server certificate. Default: “/”
Public_key_path:
	(str) Path to the public key certificate.
Name:	(str) The name for the server certificate.
Cert_chain_path:
	(str) Path to the certificate chain. Optional.

Example

{ "actor": "aws.iam.UploadCert",
  "desc": "Upload a new cert",
  "options": {
    "name": "new-cert",
    "private_key_path": "/cert.key",
    "public_key_path": "/cert.pem",
    "cert_chain_path": "/cert-chain.pem"
  }
}

Dry run

Checks that the passed file paths are valid. In the future will also validate that the files are of correct format and content.

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

Delete an existing SSL Cert in AWS IAM.

Options

Name:	(str) The name for the server certificate.

Example

{ "actor": "aws.iam.DeleteCert",
  "desc": "Run DeleteCert",
  "options": {
    "name": "fill-in"
  }
}

Dry run

Will find the cert by name or raise an exception if it’s not found.

kingpin.actors.aws.s3¶

class kingpin.actors.aws.s3.LoggingConfig[source]

Provides JSON-Schema based validation of the supplied logging config.

The S3 LoggingConfig format should look like this:

{ "target": "s3_bucket_name_here",
  "prefix": "an_optional_prefix_here" }

If you supply an empty target, then we will explicitly remove the logging configuration from the bucket. Example:

{ "target": "" }

class kingpin.actors.aws.s3.LifecycleConfig[source]

Provides JSON-Schema based validation of the supplied Lifecycle config.

The S3 Lifecycle system allows for many unique configurations. Each configuration object defined in this schema will be turned into a boto.s3.lifecycle.Rule object. All of the rules together will be turned into a boto.s3.lifecycle.Lifecycle object.

[
  { "id": "unique_rule_identifier",
    "prefix": "/some_path",
    "status": "Enabled",
    "expiration": 365,
    "transition": {
      "days": 90,
      "date": "2016-05-19T20:04:17+00:00",
      "storage_class": "GLACIER",
    }
  }
]

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.

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 the id, prefix and status as required parameters. Optionally you can supply an expiration and/or transition dictionary. 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.
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
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

Examples

{ "actor": "aws.s3.Bucket",
  "options": {
    "name": "kingpin-integration-testing",
    "region": "us-west-2",
    "policy": "./examples/aws.s3/amazon_put.json",
    "lifecycle": {
       "id": "main",
       "prefix": "/",
       "status": "Enabled",
       "expiration": 30,
    },
    "logging": {
      "target": "logs.myco.com",
      "prefix": "/kingpin-integratin-testing"
    },
    "versioning": true,
  }
}

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.

kingpin.actors.aws.sqs¶

class kingpin.actors.aws.sqs.Create(*args, **kwargs)[source]

Creates a new SQS queue with the specified name

Options

Name:	(str) The name of the queue to create
Region:	(str) AWS region (or zone) string, like ‘us-west-2’

Examples

{ "actor": "aws.sqs.Create",
  "desc": "Create queue named async-tasks",
  "options": {
    "name": "async-tasks",
    "region": "us-east-1",
  }
}

Dry Mode

Will not create any queue, or even contact SQS. Will create a mock.Mock object and exit with success.

class kingpin.actors.aws.sqs.Delete(*args, **kwargs)[source]

Deletes the SQS queues

Note: even if it`s not empty

Options

Name:	(str) The name of the queue to destroy
Region:	(str) AWS region (or zone) string, like ‘us-west-2’
Idempotent:	(bool) Will not raise errors if no matching queues are found. (default: False)

Examples

{ "actor": "aws.sqs.Delete",
  "desc": "Delete queue async-tasks",
  "options": {
    "name": "async-tasks",
    "region": "us-east-1"
  }
}

{ "actor": "aws.sqs.Delete",
  "desc": "Delete queues with 1234 in the name",
  "options": {
    "name": "1234",
    "region": "us-east-1"
  }
}

Dry Mode

Will find the specified queue, but will have a noop regarding its deletion. Dry mode will fail if no queues are found, and idempotent flag is set to False.

class kingpin.actors.aws.sqs.WaitUntilEmpty(*args, **kwargs)[source]

Wait indefinitely until for SQS queues to become empty

This actor will loop infinitely as long as the count of messages in at least one queue is greater than zero. SQS does not guarantee exact count, so this can return a stale value if the number of messages in the queue changes rapidly.

Options

Name:	(str) The name or regex pattern of the queues to operate on
Region:	(str) AWS region (or zone) string, like ‘us-west-2’
Required:	(bool) Fail if no matching queues are found. (default: False)

Examples

{ "actor": "aws.sqs.WaitUntilEmpty",
  "desc": "Wait until release-0025a* queues are empty",
  "options": {
    "name": "release-0025a",
    "region": "us-east-1",
    "required": true
  }
}

Dry Mode

This actor performs the finding of the queue, but will pretend that the count is 0 and return success. Will fail even in dry mode if required option is set to True and no queues with the name pattern are found.

kingpin.actors.packagecloud¶

The packagecloud actor allows you to perform maintenance operations on repositories hosted by packagecloud.io using their API:

https://packagecloud.io/docs/api

Required Environment Variables

kingpin.actors.rightscale.base¶

The RightScale Actors allow you to interact with resources inside your Rightscale account. These actors all support dry runs properly, but each actor has its own caveats with dry=True. Please read the instructions below for using each actor.

Required Environment Variables

exception kingpin.actors.rightscale.base.ArrayNotFound[source]

Raised when a ServerArray could not be found.

exception kingpin.actors.rightscale.base.ArrayAlreadyExists[source]

Raised when a ServerArray already exists by a given name.

kingpin.actors.rightscale.deployment¶

class kingpin.actors.rightscale.deployment.Create(*args, **kwargs)[source]

Creates a RightScale deployment.

Options match the documentation in RightScale: http://reference.rightscale.com/api1.5/resources/ResourceDeployments.html

Options

Name:	The name of the deployment to be created.
Description:	The description of the deployment to be created. (optional)
Server_tag_scope:
	The routing scope for tags for servers in the deployment. Can be ‘deployment’ or ‘account’ (optional, default: deployment)

class kingpin.actors.rightscale.deployment.Destroy(*args, **kwargs)[source]

Deletes a RightScale deployment.

Options match the documentation in RightScale: http://reference.rightscale.com/api1.5/resources/ResourceDeployments.html

Options

Name:	The name of the deployment to be deleted.

kingpin.actors.rightscale.alerts¶

class kingpin.actors.rightscale.alerts.Create(*args, **kwargs)[source]

Create a RightScale Alert Spec

Options match the documentation in RightScale: http://reference.rightscale.com/api1.5/resources/ResourceAlertSpecs.html#create

Options

Array:	The name of the Server or ServerArray to create the AlertSpec on.
Strict_array:	Whether or not to fail if the Server/ServerArray does not exist. (default: False)
Condition:	The condition (operator) in the condition sentence. (>, >=, <, <=, ==, !=)
Description:	The description of the AlertSpec. (optional)
Duration:	The duration in minutes of the condition sentence. (^d+$)
Escalation_name:
	Escalate to the named alert escalation when the alert is triggered. (optional)
File:	The RRD path/file_name of the condition sentence.
Name:	The name of the AlertSpec.
Threshold:	The threshold of the condition sentence.
Variable:	The RRD variable of the condition sentence
Vote_tag:	Should correspond to a vote tag on a ServerArray if vote to grow or shrink.
Vote_type:	Vote to grow or shrink a ServerArray when the alert is triggered. Must either escalate or vote. (grow or shrink)

Examples

Create a high network activity alert on my-array:

{ "desc": "Create high network rx alert",
  "actor": "rightscale.alerts.Create",
  "options": {
    "array": "my-array",
    "strict_array": true,
    "condition": ">",
    "description": "Alert if amount of network data received is high",
    "duration": 180,
    "escalation_name": "Email Engineering",
    "file": "interface/if_octets-eth0",
    "name": "high network rx activity",
    "threshold": "50000000",
    "variable": "rx"
  }
}

Dry Mode

In Dry mode this actor does validate that the array array exists. If it does not, a kingpin.actors.rightscale.api.ServerArrayException is thrown. Once that has been validated, the dry mode execution simply logs the Alert Spec that it would have created.

Example dry output:

TODO: Fill this in

class kingpin.actors.rightscale.alerts.Destroy(*args, **kwargs)[source]

Destroy existing RightScale Alert Specs

This actor searches RightScale for any Alert Specs that match the name and array that you supplied, then deletes all of them. RightScale lets you have multiple alert specs with the same name, so if this actor finds multiple specs, it will delete them all.

Options

Array:	The name of the Server or ServerArray to delete the AlertSpec from.
Name:	The name of the AlertSpec.

Examples

Destroy a high network activity alert on my-array:

{ "desc": "Destroy high network rx alert",
  "actor": "rightscale.alerts.Destroy",
  "options": {
    "array": "my-array",
    "name": "high network rx activity",
  }
}

Dry Mode

In Dry mode this actor does validate that the array array exists, and that the AlertSpec exists on that array so that it can be deleted. A RecoverableActorFailure error is thrown if it does not exist.

Example dry output:

14:31:49   INFO      Rehearsing... Break a leg!
14:31:49   INFO      [DRY: Kingpin] Preparing actors from delete.json
14:31:53   INFO      [DRY: Destroy high network rx alert] Found
  my-array (/api/server_arrays/329142003) to delete alert spec from
14:31:54   INFO      [DRY: Destroy high network rx alert] Would have
  deleted the alert spec "high network rx activity" on my-array

kingpin.actors.rightscale.server_array¶

class kingpin.actors.rightscale.server_array.Clone(*args, **kwargs)[source]

Clones a RightScale Server Array.

Clones a ServerArray in RightScale and renames it to the newly supplied name. By default, this actor is extremely strict about validating that the source array already exists, and that the dest array does not yet exist. This behavior can be overridden though if your Kingpin script creates the source, or destroys an existing dest ServerArray sometime before this actor executes.

Options

Source:	The name of the ServerArray to clone
Strict_source:	Whether or not to fail if the source ServerArray does not exist. (default: True)
Dest:	The new name for your cloned ServerArray
Strict_dest:	Whether or not to fail if the destination ServerArray already exists. (default: True)

Examples

Clone my-template-array to my-new-array:

{ "desc": "Clone my array",
  "actor": "rightscale.server_array.Clone",
  "options": {
    "source": "my-template-array",
    "dest": "my-new-array"
  }
}

Clone an array that was created sometime earlier in the Kingpin JSON, and thus does not exist yet during the dry run:

{ "desc": "Clone that array we created earlier",
  "actor": "rightscale.server_array.Clone",
  "options": {
    "source": "my-template-array",
    "strict_source": false,
    "dest": "my-new-array"
  }
}

Clone an array into a destination name that was destroyed sometime earlier in the Kingpin JSON:

{ "desc": "Clone that array we created earlier",
  "actor": "rightscale.server_array.Clone",
  "options": {
    "source": "my-template-array",
    "dest": "my-new-array",
    "strict_dest": false,
  }
}

Dry Mode

In Dry mode this actor does validate that the source array exists. If it does not, a kingpin.actors.rightscale.api.ServerArrayException is thrown. Once that has been validated, the dry mode execution pretends to copy the array by creating a mocked cloned array resource. This mocked resource is then operated on during the rest of the execution of the actor, guaranteeing that no live resources are modified.

Example dry output:

[Copy Test (DRY Mode)] Verifying that array "temp" exists
[Copy Test (DRY Mode)] Verifying that array "new" does not exist
[Copy Test (DRY Mode)] Cloning array "temp"
[Copy Test (DRY Mode)] Renaming array "<mocked clone of temp>" to "new"

class kingpin.actors.rightscale.server_array.Update(*args, **kwargs)[source]

Update ServerArray Settings

Updates an existing ServerArray in RightScale with the supplied parameters. Can update any parameter that is described in the RightScale API docs here:

Parameters are passed into the actor in the form of a dictionary, and are then converted into the RightScale format. See below for examples.

Options

Array:	(str) The name of the ServerArray to update
Exact:	(bool) whether or not to search for the exact array name. (default: true)
Params:	(dict) Dictionary of parameters to update
Inputs:	(dict) Dictionary of next-instance server arryay inputs to update

Examples

{ "desc": "Update my array",
  "actor": "rightscale.server_array.Update",
  "options": {
    "array": "my-new-array",
    "params": {
      "elasticity_params": {
        "bounds": {
          "min_count": 4
        },
        "schedule": [
          {"day": "Sunday", "max_count": 2,
           "min_count": 1, "time": "07:00" },
          {"day": "Sunday", "max_count": 2,
           "min_count": 2, "time": "09:00" }
        ]
      },
      "name": "my-really-new-name"
    }
  }
}

{ "desc": "Update my array inputs",
  "actor": "rightscale.server_array.Update",
  "options": {
    "array": "my-new-array",
    "inputs": {
      "ELB_NAME": "text:foobar"
    }
  }
}

Dry Mode

In Dry mode this actor does search for the array, but allows it to be missing because its highly likely that the array does not exist yet. If the array does not exist, a mocked array object is created for the rest of the execution.

During the rest of the execution, the code bypasses making any real changes and just tells you what changes it would have made.

This means that the dry mode cannot validate that the supplied inputs will work.

Example dry output:

[Update Test (DRY Mode)] Verifying that array "new" exists
[Update Test (DRY Mode)] Array "new" not found -- creating a mock.
[Update Test (DRY Mode)] Would have updated "<mocked array new>" with
params: {'server_array[name]': 'my-really-new-name',
         'server_array[elasticity_params][bounds][min_count]': '4'}

class kingpin.actors.rightscale.server_array.UpdateNextInstance(*args, **kwargs)[source]

Update the Next Instance parameters for a Server Array

Updates an existing ServerArray in RightScale with the supplied parameters. Can update any parameter that is described in the RightScale ResourceInstances docs.

Note about the image_href parameter

If you pass in the string default to the image_href key in your params dictionary, we will search and find the default image that your ServerArray’s Multi Cloud Image refers to. This helper is useful if you update your ServerArrays to use custom AMIs, and then occasionally want to go back to using a stock AMI. For example, if you boot up your instances occasionally off a stock AMI, customize the host, and then bake that host into a custom AMI.

Parameters are passed into the actor in the form of a dictionary, and are then converted into the RightScale format. See below for examples.

Options

Array:	(str) The name of the ServerArray to update
Exact:	(bool) whether or not to search for the exact array name. (default: true)
Params:	(dict) Dictionary of parameters to update

Examples

{ "desc": "Update my array",
  "actor": "rightscale.server_array.UpdateNextInstance",
  "options": {
    "array": "my-new-array",
    "params": {
      "associate_public_ip_address": true,
      "image_href": "/image/href/123",
    }
  }
}

{ "desc": "Reset the AMI image to the MCI default",
  "actor": "rightscale.server_array.UpdateNextInstance",
  "options": {
    "array": "my-new-array",
    "params": {
      "image_href": "default",
    }
  }
}

Dry Mode

In Dry mode this actor does search for the array, but allows it to be missing because its highly likely that the array does not exist yet. If the array does not exist, a mocked array object is created for the rest of the execution.

During the rest of the execution, the code bypasses making any real changes and just tells you what changes it would have made.

This means that the dry mode cannot validate that the supplied params will work.

Example dry output:

[Update my array (DRY Mode)] Verifying that array "new" exists
[Update my array (DRY Mode)] Array "new" not found -- creating a mock.
[Update my array (DRY Mode)] Would have updated "<mocked array new>"
with params: {'server_array[associate_public_ip_address]': true,
         'server_array[image_href]': '/image/href/'}

class kingpin.actors.rightscale.server_array.Terminate(*args, **kwargs)[source]

Terminate all instances in a ServerArray

Terminates all instances for a ServerArray in RightScale marking the array disabled.

Options

Array:	(str) The name of the ServerArray to destroy
Exact:	(bool) Whether or not to search for the exact array name. (default: true)
Strict:	(bool) Whether or not to fail if the ServerArray does not exist. (default: true)

Examples

 { "desc": "Terminate my array",
  "actor": "rightscale.server_array.Terminate",
  "options": {
    "array": "my-array"
  }
}

{ "desc": "Terminate many arrays",
  "actor": "rightscale.server_array.Terminate",
  "options": {
    "array": "array-prefix",
    "exact": false,
  }
}

Dry Mode

Dry mode still validates that the server array you want to terminate is actually gone. If you want to bypass this check, then set the warn_on_failure flag for the actor.

class kingpin.actors.rightscale.server_array.Destroy(*args, **kwargs)[source]

Destroy a ServerArray in RightScale

Destroys a ServerArray in RightScale by first invoking the Terminate actor, and then deleting the array as soon as all of the running instances have been terminated.

Options

Array:	(str) The name of the ServerArray to destroy
Exact:	(bool) Whether or not to search for the exact array name. (default: true)
Strict:	(bool) Whether or not to fail if the ServerArray does not exist. (default: true)

Examples

{ "desc": "Destroy my array",
  "actor": "rightscale.server_array.Destroy",
  "options": {
    "array": "my-array"
  }
}

{ "desc": "Destroy many arrays",
  "actor": "rightscale.server_array.Destroy",
  "options": {
    "array": "array-prefix",
    "exact": false,
  }
}

Dry Mode

In Dry mode this actor does search for the array, but allows it to be missing because its highly likely that the array does not exist yet. If the array does not exist, a mocked array object is created for the rest of the execution.

During the rest of the execution, the code bypasses making any real changes and just tells you what changes it would have made.

Example dry output:

[Destroy Test (DRY Mode)] Beginning
[Destroy Test (DRY Mode)] Terminating array before destroying it.
[Destroy Test (terminate) (DRY Mode)] Array "my-array" not found --
creating a mock.
[Destroy Test (terminate) (DRY Mode)] Disabling Array "my-array"
[Destroy Test (terminate) (DRY Mode)] Would have terminated all array
"<mocked array my-array>" instances.
[Destroy Test (terminate) (DRY Mode)] Pretending that array <mocked
array my-array> instances are terminated.
[Destroy Test (DRY Mode)] Pretending to destroy array "<mocked array
my-array>"
[Destroy Test (DRY Mode)] Finished successfully. Result: True

class kingpin.actors.rightscale.server_array.Launch(*args, **kwargs)[source]

Launch instances in a ServerArray

Launches instances in an existing ServerArray and waits until that array has become healthy before returning. Healthy means that the array has at least the user-specified count or min_count number of instances running as defined by the array definition in RightScale.

Options

Array:	(str) The name of the ServerArray to launch
Count:	(str, int) Optional number of instance to launch. Defaults to min_count of the array.
Enable:	(bool) Should the autoscaling of the array be enabled? Settings this to false, or omitting the parameter will not disable an enabled array.
Exact:	(bool) Whether or not to search for the exact array name. (default: true)

Examples

{ "desc": "Enable array and launch it",
  "actor": "rightscale.server_array.Launch",
  "options": {
    "array": "my-array",
    "enable": true
  }
}

{ "desc": "Enable arrays starting with my-array and launch them",
  "actor": "rightscale.server_array.Launch",
  "options": {
    "array": "my-array",
    "enable": true,
    "exact": false
  }
}

{ "desc": "Enable array and launch 1 instance",
  "actor": "rightscale.server_array.Launch",
  "options": {
    "array": "my-array",
    "count": 1
  }
}

Dry Mode

In Dry mode this actor does search for the array, but allows it to be missing because its highly likely that the array does not exist yet. If the array does not exist, a mocked array object is created for the rest of the execution.

During the rest of the execution, the code bypasses making any real changes and just tells you what changes it would have made.

Example dry output:

[Launch Array Test #0 (DRY Mode)] Verifying that array "my-array" exists
[Launch Array Test #0 (DRY Mode)] Array "my-array" not found -- creating
    a mock.
[Launch Array Test #0 (DRY Mode)] Enabling Array "my-array"
[Launch Array Test #0 (DRY Mode)] Launching Array "my-array" instances
[Launch Array Test #0 (DRY Mode)] Would have launched instances of array
    <MagicMock name='my-array.self.show().soul.__getitem__()'
    id='4420453200'>
[Launch Array Test #0 (DRY Mode)] Pretending that array <MagicMock
    name='my-array.self.show().soul.__getitem__()' id='4420453200'>
    instances are launched.

class kingpin.actors.rightscale.server_array.Execute(*args, **kwargs)[source]

Executes a RightScale script/recipe on a ServerArray

Executes a RightScript or Recipe on a set of hosts in a ServerArray in RightScale using individual calls to the live running instances. These can be found in your RightScale account under Design -> RightScript or Design -> Cookbooks

The RightScale API offers a multi_run_executable method that can be used to run a single script on all servers in an array – but unfortunately this API method provides no way to monitor the progress of the individual jobs on the hosts. Furthermore, the method often executes on recently terminated or terminating hosts, which throws false-negative error results.

Our actor explicitly retrieves a list of the operational hosts in an array and kicks off individual execution tasks for every host. It then tracks the execution of those tasks from start to finish and returns the results.

Options

Array:	(str) The name of the ServerArray to operate on
Script:	(str) The name of the RightScript or Recipe to execute
Expected_runtime:
	(str, int) Expected number of seconds to execute. (default: 5)
Concurrency:	Max number of concurrent executions. This will fire off N executions in parallel, and continue with the remained as soon as the first execution is done. This is faster than creating N Sync executions. Note: When applied to multiple (M) arrays cumulative concurrency accross all arrays will remain at N. It will not be M x N.
Inputs:	(dict) Dictionary of Key/Value pairs to use as inputs for the script
Exact:	(str) Boolean whether or not to search for the exact array name. (default: true)

Examples

{ "desc":" Execute script on my-array",
  "actor": "rightscale.server_array.Execute",
  "options": {
    "array": "my-array",
    "script": "connect to elb",
    "expected_runtime": 3,
    "inputs": {
      "ELB_NAME": "text:my-elb"
    }
  }
}

Dry Mode

In Dry mode this actor does search for the array, but allows it to be missing because its highly likely that the array does not exist yet. If the array does not exist, a mocked array object is created for the rest of the execution.

During the rest of the execution, the code bypasses making any real changes and just tells you what changes it would have made.

Example dry output:

[Destroy Test (DRY Mode)] Verifying that array "my-array" exists
[Execute Test (DRY Mode)]
    kingpin.actors.rightscale.server_array.Execute Initialized
[Execute Test (DRY Mode)] Beginning execution
[Execute Test (DRY Mode)] Verifying that array "my-array" exists
[Execute Test (DRY Mode)] Would have executed "Connect instance to ELB"
    with inputs "{'inputs[ELB_NAME]': 'text:my-elb'}" on "my-array".
[Execute Test (DRY Mode)] Returning result: True

kingpin.actors.rightscale.mci¶

class kingpin.actors.rightscale.mci.Create(*args, **kwargs)[source]

Creates a RightScale Multi Cloud Image.

Options match the documentation in RightScale: http://reference.rightscale.com/api1.5/resources/ResourceMultiCloudImages.html

Options

Name:	The name of the MCI to be created.
Description:	The description of the MCI to be created. (optional)
Images:	A list of dicts that each describe a single cloud and the image in that cloud to launch. See below for details.

Image Definitions

Each cloud image definition is a dictionary that takes a few keys.

Cloud:	The name of the cloud as found in RightScale. We use the cloud ‘Name’ which can be found in your Settings -> Account Settings -> Clouds -> insert_cloud_here page. For example AWS us-west-2.
Image:	The cloud-specific Image UID. For example ami-a1234abc.
Instance_type:	The default instance type to launch when this AMI is launched. For example, m1.small. (optional)
User_data:	The custom user data to pass to the instance on-bootup. (optional)

Examples

{ "actor": "rightscale.mci.Create",
  "desc": "Create an MCI",
  "options": {
      "name": "Ubuntu i386 14.04",
      "description": "this is our test mci",
      "images": [
        {
            "cloud": "EC2 us-west-2",
            "image": "ami-e29774d1",
            "instance_type": "m1.small",
            "user_data": "cd /bin/bash"
        },
        {
            "cloud": "EC2 us-west-1",
            "image": "ami-b58142f1",
            "instance_type": "m1.small",
            "user_data": "cd /bin/bash"
        }
      ]
  }
}

class kingpin.actors.rightscale.mci.Destroy(*args, **kwargs)[source]

Deletes a RightScale MCI.

Options match the documentation in RightScale: http://reference.rightscale.com/api1.5/resources/ResourceMultiCloudImages.html

Options

Name:	The name of the multi cloud image to be deleted.

Examples

{ "actor": "rightscale.mci.Destroy",
  "desc": "Create an MCI",
  "options": {
      "name": "Ubuntu i386 14.04",
  }
}