Boto 3 Documentation¶

Boto 3 Docs 1.1.4 documentation

Boto is the Amazon Web Services (AWS) SDK for Python, which allows Python developers to write software that makes use of Amazon services like S3 and EC2. Boto provides an easy to use, object-oriented API as well as low-level direct service access.

Quickstart

Quickstart

Getting started with Boto 3 is easy, but requires a few steps.

Installation

Install the latest Boto 3 release via pip:

pip install boto3

You may also install a specific version:

pip install boto3==1.0.0

Note

The latest development version can always be found on GitHub.

Configuration

Before you can begin using Boto 3, you should set up authentication credentials. Credentials for your AWS account can be found in the IAM Console. You can create or use an existing user. Go to manage access keys and generate a new set of keys.

If you have the AWS CLI installed, then you can use it to configure your credentials file:

aws configure

Alternatively, you can create the credential file yourself. By default, its location is at ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

You may also want to set a default region. This can be done in the configuration file. By default, its location is at ~/.aws/config:

[default]
region=us-east-1

Alternatively, you can pass a region_name when creating clients and resources.

This sets up credentials for the default profile as well as a default region to use when creating connections. See Configuration for in-depth configuration sources and options.

Using Boto 3

To use Boto 3, you must first import it and tell it what service you are going to use:

import boto3

# Let's use Amazon S3
s3 = boto3.resource('s3')

Now that you have an s3 resource, you can make requests and process responses from the service. The following uses the buckets collection to print out all bucket names:

# Print out bucket names
for bucket in s3.buckets.all():
    print(bucket.name)

It's also easy to upload and download binary data. For example, the following uploads a new file to S3. It assumes that the bucket my-bucket already exists:

# Upload a new file
data = open('test.jpg', 'rb')
s3.Bucket('my-bucket').put_object(Key='test.jpg', Body=data)

Resources and Collections will be covered in more detail in the following sections, so don't worry if you do not completely understand the examples.

A Sample Tutorial

This tutorial will show you how to use Boto3 with an AWS service. In this sample tutorial, you will learn how to use Boto3 with Amazon Simple Queue Service (SQS)

SQS

SQS allows you to queue and then process messages. This tutorial covers how to create a new queue, get and use an existing queue, push new messages onto the queue, and process messages from the queue by using Resources and Collections.

Creating a Queue

Queues are created with a name. You may also optionally set queue attributes, such as the number of seconds to wait before an item may be processed. The examples below will use the queue name test. Before creating a queue, you must first get the SQS service resource:

# Get the service resource
sqs = boto3.resource('sqs')

# Create the queue. This returns an SQS.Queue instance
queue = sqs.create_queue(QueueName='test', Attributes={'DelaySeconds': '5'})

# You can now access identifiers and attributes
print(queue.url)
print(queue.attributes.get('DelaySeconds'))

Reference: SQS.ServiceResource.create_queue()

Warning

The code above may throw an exception if you already have a queue named test.

Using an Existing Queue

It is possible to look up a queue by its name. If the queue does not exist, then an exception will be thrown:

# Get the service resource
sqs = boto3.resource('sqs')

# Get the queue. This returns an SQS.Queue instance
queue = sqs.get_queue_by_name(QueueName='test')

# You can now access identifiers and attributes
print(queue.url)
print(queue.attributes.get('DelaySeconds'))

It is also possible to list all of your existing queues:

# Print out each queue name, which is part of its ARN
for queue in sqs.queues.all():
    print(queue.url)

Note

To get the name from a queue, you must use its ARN, which is available in the queue's attributes attribute. Using queue.attributes['QueueArn'].split(':')[-1] will return its name.

Reference: SQS.ServiceResource.get_queue_by_name(), SQS.ServiceResource.queues

Sending Messages

Sending a message adds it to the end of the queue:

# Get the service resource
sqs = boto3.resource('sqs')

# Get the queue
queue = sqs.get_queue_by_name(QueueName='test')

# Create a new message
response = queue.send_message(MessageBody='world')

# The response is NOT a resource, but gives you a message ID and MD5
print(response.get('MessageId'))
print(response.get('MD5OfMessageBody'))

You can also create messages with custom attributes:

queue.send_message(MessageBody='boto3', MessageAttributes={
    'Author': {
        'StringValue': 'Daniel',
        'DataType': 'string'
    }
})

Messages can also be sent in batches. For example, sending the two messages described above in a single request would look like the following:

response = queue.send_messages(Entries=[
    {
        'Id': '1',
        'MessageBody': 'world'
    },
    {
        'Id': '2',
        'MessageBody': 'boto3',
        'MessageAttributes': {
            'Author': {
                'StringValue': 'Daniel',
                'DataType': 'string'
            }
        }
    }
])

# Print out any failures
print(response.get('Failed'))

In this case, the response contains lists of Successful and Failed messages, so you can retry failures if needed.

Reference: SQS.Queue.send_message(), SQS.Queue.send_messages()

Processing Messages

Messages are processed in batches:

# Get the service resource
sqs = boto3.resource('sqs')

# Get the queue
queue = sqs.get_queue_by_name(QueueName='test')

# Process messages by printing out body and optional author name
for message in queue.receive_messages(MessageAttributeNames=['Author']):
    # Get the custom author message attribute if it was set
    author_text = ''
    if message.message_attributes is not None:
        author_name = message.message_attributes.get('Author').get('StringValue')
        if author_name:
            author_text = ' ({0})'.format(author_name)

    # Print out the body and author (if set)
    print('Hello, {0}!{1}'.format(message.body, author_text))

    # Let the queue know that the message is processed
    message.delete()

Given only the messages that were sent in a batch with SQS.Queue.send_messages() in the previous section, the above code will print out:

Hello, world!
Hello, boto3! (Daniel)

Reference: SQS.Queue.receive_messages(), SQS.Message.delete()

User Guide

User Guides

Migration Guides

What's New

Boto 3 is a ground-up rewrite of Boto. It uses a data-driven approach to generate classes at runtime from JSON description files that are shared between SDKs in various languages. This includes descriptions for a high level, object oriented interface similar to those availabe in previous versions of Boto.

Because Boto 3 is generated from these shared JSON files, we get fast updates to the latest services and features and a consistent API across services. Community contributions to JSON description files in other SDKs also benefit Boto 3, just as contributions to Boto 3 benefit the other SDKs.

Major Features

Boto 3 consists of the following major features:

  • Resources: a high level, object oriented interface
  • Collections: a tool to iterate and manipulate groups of resources
  • Clients: low level service connections
  • Paginators: automatic paging of responses
  • Waiters: a way to block until a certain state has been reached

Along with these major features, Boto 3 also provides sessions and per-session credentials & configuration, as well as basic components like authentication, parameter & response handling, an event system for customizations and logic to retry failed requests.

Botocore

Boto 3 is built atop of a library called Botocore, which is shared by the AWS CLI. Botocore provides the low level clients, session, and credential & configuration data. Boto 3 builds on top of Botocore by providing its own session, resources and collections.

Migrating from Boto 2.x

Current Boto users can begin using Boto 3 right away. The two modules can live side-by-side in the same project, which means that a piecemeal approach can be used. New features can be written in Boto 3, or existing code can be migrated over as needed, piece by piece.

High Level Concepts

Boto 2.x modules are typically split into two categories, those which include a high-level object-oriented interface and those which include only a low-level interface which matches the underlying Amazon Web Services API. Some modules are completely high-level (like Amazon S3 or EC2), some include high-level code on top of a low-level connection (like Amazon DynamoDB), and others are 100% low-level (like Amazon Elastic Transcoder).

In Boto 3 this general low-level and high-level concept hasn't changed much, but there are two important points to understand.

Data Driven

First, in Boto 3 classes are created at runtime from JSON data files that describe AWS APIs and organizational structures built atop of them. These data files are loaded at runtime and can be modified and updated without the need of installing an entirely new SDK release.

A side effect of having all the services generated from JSON files is that there is now consistency between all AWS service modules. One important change is that all API call parameters must now be passed as keyword arguments, and these keyword arguments take the form defined by the upstream service. Though there are exceptions, this typically means UpperCamelCasing parameter names. You will see this in the service-specific migration guides linked to below.

Resource Objects

Second, while every service now uses the runtime-generated low-level client, some services additionally have high-level generated objects that we refer to as Resources. The lower-level is comparable to Boto 2.x layer 1 connection objects in that they provide a one to one mapping of API operations and return low-level responses. The higher level is comparable to the high-level customizations from Boto 2.x: an S3 Key, an EC2 Instance, and a DynamoDB Table are all considered resources in Boto 3. Just like a Boto 2.x S3Connection's list_buckets will return Bucket objects, the Boto 3 resource interface provides actions and collections that return resources. Some services may also have hand-written customizations built on top of the runtime-generated high-level resources (such as utilities for working with S3 multipart uploads).

import boto, boto3

# Low-level connections
conn = boto.connect_elastictranscoder()
client = boto3.client('elastictranscoder')

# High-level connections & resource objects
from boto.s3.bucket import Bucket
s3_conn = boto.connect_s3()
boto2_bucket = Bucket('mybucket')

s3 = boto3.resource('s3')
boto3_bucket = s3.Bucket('mybucket')
Installation & Configuration

The Quickstart guide provides instructions for installing Boto 3. You can also follow the instructions there to set up new credential files, or you can continue to use your existing Boto 2.x credentials. Please note that Boto 3, the AWS CLI, and several other SDKs all use the shared credentials file (usually at ~/.aws/credentials).

Once configured, you may begin using Boto 3:

import boto3

for bucket in boto3.resource('s3').buckets.all():
    print(bucket.name)

See the tutorial_list and Boto 3 Documentation for more information.

The rest of this document will describe specific common usage scenarios of Boto 2 code and how to accomplish the same tasks with Boto 3.

Services
Amazon S3

Boto 2.x contains a number of customizations to make working with Amazon S3 buckets and keys easy. Boto 3 exposes these same objects through its resources interface in a unified and consistent way.

Creating the Connection

Boto 3 has both low-level clients and higher-level resources. For Amazon S3, the higher-level resources are the most similar to Boto 2.x's s3 module:

# Boto 2.x
import boto
s3_connection = boto.connect_s3()

# Boto 3
import boto3
s3 = boto3.resource('s3')
Creating a Bucket

Creating a bucket in Boto 2 and Boto 3 is very similar, except that in Boto 3 all action parameters must be passed via keyword arguments and a bucket configuration must be specified manually:

# Boto 2.x
s3_connection.create_bucket('mybucket')
s3_connection.create_bucket('mybucket', location=Location.USWest)

# Boto 3
s3.create_bucket(Bucket='mybucket')
s3.create_bucket(Bucket='mybucket', CreateBucketConfiguration={
    'LocationConstraint': 'us-west-1'})
Storing Data

Storing data from a file, stream, or string is easy:

# Boto 2.x
from boto.s3.key import Key
key = Key('hello.txt')
key.set_contents_from_file('/tmp/hello.txt')

# Boto 3
s3.Object('mybucket', 'hello.txt').put(Body=open('/tmp/hello.txt', 'rb'))
Accessing a Bucket

Getting a bucket is easy with Boto 3's resources, however these do not automatically validate whether a bucket exists:

# Boto 2.x
bucket = s3_connection.get_bucket('mybucket', validate=False)
exists = s3_connection.lookup('mybucket')

# Boto 3
import botocore
bucket = s3.Bucket('mybucket')
exists = True
try:
    s3.meta.client.head_bucket(Bucket='mybucket')
except botocore.exceptions.ClientError as e:
    # If a client error is thrown, then check that it was a 404 error.
    # If it was a 404 error, then the bucket does not exist.
    error_code = int(e.response['Error']['Code'])
    if error_code == 404:
        exists = False
Deleting a Bucket

All of the keys in a bucket must be deleted before the bucket itself can be deleted:

# Boto 2.x
for key in bucket:
    key.delete()
bucket.delete()

# Boto 3
for key in bucket.objects.all():
    key.delete()
bucket.delete()
Iteration of Buckets and Keys

Bucket and key objects are no longer iterable, but now provide collection attributes which can be iterated:

# Boto 2.x
for bucket in s3_connection:
    for key in bucket:
        print(key.name)

# Boto 3
for bucket in s3.buckets.all():
    for key in bucket.objects.all():
        print(key.key)
Access Controls

Getting and setting canned access control values in Boto 3 operates on an ACL resource object:

# Boto 2.x
bucket.set_acl('public-read')
key.set_acl('public-read')

# Boto 3
bucket.Acl().put(ACL='public-read')
obj.put(ACL='public-read')

It's also possible to retrieve the policy grant information:

# Boto 2.x
acp = bucket.get_acl()
for grant in acp.acl.grants:
    print(grant.display_name, grant.permission)

# Boto 3
acl = bucket.Acl()
for grant in acl.grants:
    print(grant['DisplayName'], grant['Permission'])

Boto 3 lacks the grant shortcut methods present in Boto 2.x, but it is still fairly simple to add grantees:

# Boto 2.x
bucket.add_email_grant('READ', 'user@domain.tld')

# Boto 3
bucket.Acl.put(GrantRead='emailAddress=user@domain.tld')
Key Metadata

It's possible to set arbitrary metadata on keys:

# Boto 2.x
key.set_metadata('meta1', 'This is my metadata value')
print(key.get_metadata('meta1'))

# Boto 3
key.put(Metadata={'meta1': 'This is my metadata value'})
print(key.metadata['meta1'])
Managing CORS Configuration

Allows you to manage the cross-origin resource sharing configuration for S3 buckets:

# Boto 2.x
cors = bucket.get_cors()

config = CORSConfiguration()
config.add_rule('GET', '*')
bucket.set_cors(config)

bucket.delete_cors()

# Boto 3
cors = bucket.Cors()

config = {
    'CORSRules': [
        {
            'AllowedMethods': ['GET'],
            'AllowedOrigins': ['*']
        }
    ]
}
cors.put(CORSConfiguration=config)

cors.delete()
Amazon EC2

Boto 2.x contains a number of customizations to make working with Amazon EC2 instances, storage and networks easy. Boto 3 exposes these same objects through its resources interface in a unified and consistent way.

Creating the Connection

Boto 3 has both low-level clients and higher-level resources. For Amazon EC2, the higher-level resources are the most similar to Boto 2.x's ec2 and vpc modules:

# Boto 2.x
import boto
ec2_connection = boto.connect_ec2()
vpc_connection = boto.connect_vpc()

# Boto 3
import boto3
ec2 = boto3.resource('ec2')
Launching New Instances

Launching new instances requires an image ID and the number of instances to launch. It can also take several optional parameters, such as the instance type and security group:

# Boto 2.x
ec2_connection.run_instances('<ami-image-id>')

# Boto 3
ec2.create_instances(ImageId='<ami-image-id>', MinCount=1, MaxCount=5)
Stopping & Terminating Instances

Stopping and terminating multiple instances given a list of instance IDs uses Boto 3 collection filtering:

ids = ['instance-id-1', 'instance-id-2', ...]

# Boto 2.x
ec2_connection.stop_instances(instance_ids=ids)
ec2_connection.terminate_instances(instance_ids=ids)

# Boto 3
ec2.instances.filter(InstanceIds=ids).stop()
ec2.instances.filter(InstanceIds=ids).terminate()
Checking What Instances Are Running

Boto 3 collections come in handy when listing all your running instances as well. Every collection exposes a filter method that allows you to pass additional parameters to the underlying service API operation. The EC2 instances collection takes a parameter called Filters which is a list of names and values, for example:

# Boto 2.x
reservations = ec2_connection.get_all_reservations(
    filters={'instance-state-name': 'running'})
for reservation in reservations:
    for instance in reservation.instances:
        print(instance.instance_id, instance.instance_type)

# Boto 3
# Use the filter() method of the instances collection to retrieve
# all running EC2 instances.
instances = ec2.instances.filter(
    Filters=[{'Name': 'instance-state-name', 'Values': ['running']}])
for instance in instances:
    print(instance.id, instance.instance_type)
Checking Health Status Of Instances

It is possible to get scheduled maintenance information for your running instances. At the time of this writing Boto 3 does not have a status resource, so you must drop down to the low-level client via ec2.meta.client:

# Boto 2.x
for status in ec2_connection.get_all_instance_statuses():
    print(status)

# Boto 3
for status in ec2.meta.client.describe_instance_status()['InstanceStatuses']:
    print(status)
Working with EBS Snapshots

Snapshots provide a way to create a copy of an EBS volume, as well as make new volumes from the snapshot which can be attached to an instance:

# Boto 2.x
snapshot = ec2_connection.create_snapshot('volume-id', 'Description')
volume = snapshot.create_volume('us-west-2')
ec2_connection.attach_volume(volume.id, 'instance-id', '/dev/sdy')
ec2_connection.delete_snapshot(snapshot.id)

# Boto 3
snapshot = ec2.create_snapshot(VolumeId='volume-id', Description='description')
volume = ec2.create_volume(SnapshotId=snapshot.id, AvailabilityZone='us-west-2a')
ec2.Instance('instance-id').attach_volume(VolumeId=volume.id, Device='/dev/sdy')
snapshot.delete()
Creating a VPC, Subnet, and Gateway

Creating VPC resources in Boto 3 is very similar to Boto 2.x:

# Boto 2.x
vpc = vpc_connection.create_vpc('10.0.0.0/24')
subnet = vpc_connection.create_subnet(vpc.id, '10.0.0.0/25')
gateway = vpc_connection.create_internet_gateway()

# Boto 3
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/24')
subnet = vpc.create_subnet(CidrBlock='10.0.0.0/25')
gateway = ec2.create_internet_gateway()
Attaching and Detaching an Elastic IP and Gateway

Elastic IPs and gateways provide a way for instances inside of a VPC to communicate with the outside world:

# Boto 2.x
ec2_connection.attach_internet_gateway(gateway.id, vpc.id)
ec2_connection.detach_internet_gateway(gateway.id, vpc.id)

from boto.ec2.address import Address
address = Address()
address.allocation_id = 'eipalloc-35cf685d'
address.associate('i-71b2f60b')
address.disassociate()

# Boto 3
gateway.attach_to_vpc(VpcId=vpc.id)
gateway.detach_from_vpc(VpcId=vpc.id)

address = ec2.VpcAddress('eipalloc-35cf685d')
address.associate('i-71b2f60b')
address.association.delete()

General Feature Guides

Resources
Overview

Resources represent an object-oriented interface to Amazon Web Services (AWS). They provide a higher-level abstraction than the raw, low-level calls made by service clients. To use resources, you invoke the resource() method of a Session and pass in a service name:

# Get resources from the default session
sqs = boto3.resource('sqs')
s3 = boto3.resource('s3')

Every resource instance has a number of attributes and methods. These can conceptually be split up into identifiers, attributes, actions, references, sub-resources, and collections. Each of these is described in further detail below and in the following section.

Resources themselves can also be conceptually split into service resources (like sqs, s3, ec2, etc) and individual resources (like sqs.Queue or s3.Bucket). Service resources do not have identifiers or attributes. The two share the same components otherwise.

Identifiers & Attributes

An identifier is a unique value that is used to call actions on the resource. Resources must have at least one identifier, except for the top-level service resources (e.g. sqs or s3). An identifier is set at instance creation-time, and failing to provide all necessary identifiers during instantiation will result in an exception. Examples of identifiers:

# SQS Queue (url is an identifier)
queue = sqs.Queue(url='http://...')
print(queue.url)

# S3 Object (bucket_name and key are identifiers)
obj = s3.Object(bucket_name='boto3', key='test.py')
print(obj.bucket_name)
print(obj.key)

# Raises exception, missing identifier: key!
obj = s3.Object(bucket_name='boto3')

Identifiers may also be passed as positional arguments:

# SQS Queue
queue = sqs.Queue('http://...')

# S3 Object
obj = s3.Object('boto3', 'test.py')

# Raises exception, missing key!
obj = s3.Object('boto3')

Identifiers also play a role in resource instance equality. For two instances of a resource to be considered equal, their identifiers must be equal:

>>> bucket1 = s3.Bucket('boto3')
>>> bucket2 = s3.Bucket('boto3')
>>> bucket3 = s3.Bucket('some-other-bucket')

>>> bucket1 == bucket2
True
>>> bucket1 == bucket3
False

Note

Only identifiers are taken into account for instance equality. Region, account ID and other data members are not considered. When using temporary credentials or multiple regions in your code please keep this in mind.

Resources may also have attributes, which are lazy-loaded properties on the instance. They may be set at creation time from the response of an action on another resource, or they may be set when accessed or via an explicit call to the load or reload action. Examples of attributes:

# SQS Message
message.body

# S3 Object
obj.last_modified
obj.md5

Warning

Attributes may incur a load action when first accessed. If latency is a concern, then manually calling load will allow you to control exactly when the load action (and thus latency) is invoked. The documentation for each resource explicitly lists its attributes.

Additionally, attributes may be reloaded after an action has been performed on the resource. For example, if the last_modified attribute of an S3 object is loaded and then a put action is called, then the next time you access last_modified it will reload the object's metadata.

Actions

An action is a method which makes a call to the service. Actions may return a low-level response, a new resource instance or a list of new resource instances. Actions automatically set the resource identifiers as parameters, but allow you to pass additional parameters via keyword arguments. Examples of actions:

# SQS Queue
messages = queue.receive_messages()

# SQS Message
for message in messages:
    message.delete()

# S3 Object
obj = s3.Object(bucket_name='boto3', key='test.py')
response = obj.get()
data = response['Body'].read()

Examples of sending additional parameters:

# SQS Service
queue = sqs.get_queue_by_name(QueueName='test')

# SQS Queue
queue.send_message(MessageBody='hello')

Note

Parameters must be passed as keyword arguments. They will not work as positional arguments.

References

A reference is an attribute which may be None or a related resource instance. The resource instance does not share identifiers with its reference resource, that is, it is not a strict parent to child relationship. In relational terms, these can be considered many-to-one or one-to-one. Examples of references:

# EC2 Instance
instance.subnet
instance.vpc

In the above example, an EC2 instance may have exactly one associated subnet, and may have exactly one associated VPC. The subnet does not require the instance ID to exist, hence it is not a parent to child relationship.

Sub-resources

A sub-resource is similar to a reference, but is a related class rather than an instance. Sub-resources, when instantiated, share identifiers with their parent. It is a strict parent-child relationship. In relational terms, these can be considered one-to-many. Examples of sub-resources:

# SQS
queue = sqs.Queue(url='...')
message = queue.Message(receipt_handle='...')
print(queue.url == message.queue_url)
print(message.receipt_handle)

# S3
obj = bucket.Object(key='new_file.txt')
print(obj.bucket_name)
print(obj.key)

Because an SQS message cannot exist without a queue, and an S3 object cannot exist without a bucket, these are parent to child relationships.

Waiters

A waiter is similiar to an action. A waiter will poll the status of a resource and suspend execution until the resource reaches the state that is being polling for or a failure occurs while polling. Waiters automatically set the resource identifiers as parameters, but allow you to pass additional parameters via keyword arguments. Examples of waiters include:

# S3: Wait for a bucket to exist.
bucket.wait_until_exists()

# EC2: Wait for an instance to reach the running state.
instance.wait_until_running()
Multithreading

It is recommended to create a resource instance for each thread in a multithreaded application rather than sharing a single instance among the threads. For example:

import boto3
import boto3.session
import threading

class MyTask(threading.Thread):
    def run(self):
        session = boto3.session.Session()
        s3 = session.resource('s3')
        # ... do some work with S3 ...

In the example above, each thread would have its own Boto 3 session and its own instance of the S3 resource. This is a good idea because resources contain shared data when loaded and calling actions, accessing properties, or manually loading or reloading the resource can modify this data.

Collections
Overview

A collection provides an iterable interface to a group of resources. Collections behave similarly to Django QuerySets and expose a similar API. A collection seamlessly handles pagination for you, making it possible to easily iterate over all items from all pages of data. Example of a collection:

# SQS list all queues
sqs = boto3.resource('sqs')
for queue in sqs.queues.all():
    print(queue.url)
When Collections Make Requests

Collections can be created and manipulated without any request being made to the underlying service. A collection makes a remote service request under the following conditions:

  • Iteration:

    for bucket in s3.buckets.all():
        print(bucket.name)
    
  • Conversion to list():

    buckets = list(s3.buckets.all())
    
  • Batch actions (see below):

    s3.Bucket('my-bucket').objects.delete()
    
Filtering

Some collections support extra arguments to filter the returned data set, which are passed into the underlying service operation. Use the filter() method to filter the results:

# S3 list all keys with the prefix '/photos'
s3 = boto3.resource('s3')
for bucket in s3.buckets.all():
    for obj in bucket.objects.filter(Prefix='/photos'):
        print('{0}:{1}'.format(bucket.name, obj.key))

Warning

Behind the scenes, the above example will call ListBuckets, ListObjects, and HeadObject many times. If you have a large number of S3 objects then this could incur a significant cost.

Chainability

Collection methods are chainable. They return copies of the collection rather than modifying the collection, including a deep copy of any associated operation parameters. For example, this allows you to build up multiple collections from a base which they all have in common:

# EC2 find instances
ec2 = boto3.resource('ec2')
base = ec2.instances.filter(InstanceIds=['id1', 'id2', 'id3'])

filters = [{
    'name': 'tenancy',
    'value': 'dedicated'
}]
filtered1 = base.filter(Filters=filters)

# Note, this does NOT modify the filters in ``filtered1``!
filters.append({'name': 'instance-type', 'value': 't1.micro'})
filtered2 = base.filter(Filters=filters)

print('All instances:')
for instance in base:
    print(instance.id)

print('Dedicated instances:')
for instance in filtered1:
    print(instance.id)

print('Dedicated micro instances:')
for instance in filtered2:
    print(instance.id)
Limiting Results

It is possible to limit the number of items returned from a collection by using either the limit() method:

# S3 iterate over first ten buckets
for bucket in s3.buckets.limit(10):
    print(bucket.name)

In both cases, up to 10 items total will be returned. If you do not have 10 buckets, then all of your buckets will be returned.

Controlling Page Size

Collections automatically handle paging through results, but you may want to control the number of items returned from a single service operation call. You can do so using the page_size() method:

# S3 iterate over all objects 100 at a time
for obj in bucket.objects.page_size(100):
    print(obj.key)

By default, S3 will return 1000 objects at a time, so the above code would let you process the items in smaller batches, which could be beneficial for slow or unreliable internet connections.

Batch Actions

Some collections support batch actions, which are actions that operate on an entire page of results at a time. They will automatically handle pagination:

# S3 delete everything in `my-bucket`
s3 = boto3.resource('s3')
s3.buckets('my-bucket').objects.delete()

Danger

The above example will completely erase all data in the my-bucket bucket! Please be careful with batch actions.

Low-level Clients

Clients provide a low-level interface to AWS whose methods map close to 1:1 with service APIs. All service operations are supported by clients. Clients are generated from a JSON service definition file.

Creating Clients

Clients are created in a similar fashion to resources:

import boto3

# Create a low-level client with the service name
sqs = boto3.client('sqs')

It is also possible to access the low-level client from an existing resource:

# Create the resource
sqs_resource = boto3.resource('sqs')

# Get the client from the resource
sqs = sqs_resource.meta.client
Service Operations

Service operations map to client methods of the same name and provide access to the same operation parameters via keyword arguments:

# Make a call using the low-level client
response = sqs.send_message(QueueUrl='...', MessageBody='...')

As can be seen above, the method arguments map directly to the associated SQS API.

Note

The method names have been snake-cased for better looking Python code.

Parameters must be sent as keyword arguments. They will not work as positional arguments.

Handling Responses

Responses are returned as python dictionaries. It is up to you to traverse or otherwise process the response for the data you need, keeping in mind that responses may not always include all of the expected data. In the example below, response.get('QueueUrls', []) is used to ensure that a list is always returned, even when the response has no key 'QueueUrls':

# List all your queues
response = sqs.list_queues()
for url in response.get('QueueUrls', []):
    print(url)

The response in the example above looks something like this:

{
    "QueueUrls": [
        "http://url1",
        "http://url2",
        "http://url3"
    ]
}
Waiters

Waiters use a client's service operations to poll the status of an AWS resource and suspend execution until the AWS resource reaches the state that the waiter is polling for or a failure occurs while polling. Using clients, you can learn the name of each waiter that a client has access to:

import boto3

s3 = boto3.client('s3')
sqs = boto3.client('sqs')

# List all of the possible waiters for both clients
print("s3 waiters:")
s3.waiter_names

print("sqs waiters:")
sqs.waiter_names

Note if a client does not have any waiters, it will return an empty list when accessing its waiter_names attribute:

s3 waiters:
[u'bucket_exists', u'bucket_not_exists', u'object_exists', u'object_not_exists']
sqs waiters:
[]

Using a client's get_waiter() method, you can obtain a specific waiter from its list of possible waiters:

# Retrieve waiter instance that will wait till a specified
# S3 bucket exists
s3_bucket_exists_waiter = s3.get_waiter('bucket_exists')

Then to actually start waiting, you must call the waiter's wait() method with the method's appropriate parameters passed in:

# Begin waiting for the S3 bucket, mybucket, to exist
s3_bucket_exists_waiter.wait(Bucket='mybucket')
Session

A session manages state about a particular configuration. By default a session is created for you when needed. However it is possible and recommended to maintain your own session(s) in some scenarios. Sessions typically store:

  • Credentials
  • Region
  • Other configurations
Default Session

The boto3 module acts as a proxy to the default session, which is created automatically when needed. Example default session use:

# Using the default session
sqs = boto3.client('sqs')
s3 = boto3.resource('s3')
Custom Session

It is also possible to manage your own session and create clients or resources from it:

# Creating your own session
session = boto3.session.Session()

sqs = session.client('sqs')
s3 = session.resource('s3')
Configuration

Boto can be configured in multiple ways. Regardless of the source or sources that you choose, you must have AWS credentials and a region set in order to make requests.

Interactive Configuration

If you have the AWS CLI, then you can use its interactive configure command to set up your credentials and default region:

aws configure

Follow the prompts and it will generate configuration files in the correct locations for you.

Configuration Sources

There are multiple sources from which configuration data can be loaded. The general order in which they are checked is as follows:

  1. Method parameters
  2. Environment variables
  3. Configuration files
  4. EC2 Instance metadata

If a configuration value is set in multiple places, then the first will be used according the the order above. For example, if I have set a default region in both my environment variables and configuration file, then the environment variable is used.

Available Options

The available options for various configuration sources are listed below.

Method Parameters

When creating a session, client, or resource you can pass in credential and configuration options:

from boto3.session import Session

session = Session(aws_access_key_id='<YOUR ACCESS KEY ID>',
                  aws_secret_access_key='<YOUR SECRET KEY>',
                  region_name='<REGION NAME>')

ec2 = session.resource('ec2')
ec2_us_west_2 = session.resource('ec2', region_name='us-west-2')

# List all of my EC2 instances in my default region.
print('Default region:')
for instance in ec2.instances.all():
    print(instance.id)

# List all of my EC2 instances in us-west-2.
print('US West 2 region:')
for instance in ec2_us_west_2.instances.all():
    print(instance.id)

For a list of all options, look at the Session documentation.

Environment Variables
AWS_ACCESS_KEY_ID
The access key for your AWS account.
AWS_SECRET_ACCESS_KEY
The secret key for your AWS account.
AWS_DEFAULT_REGION
The default region to use, e.g. us-east-1.
AWS_PROFILE
The default credential and configuration profile to use, if any.
Configuration Files

There are two configuration files that Boto checks. The first is the shared credential file, which holds only credentials and is shared between various SDKs and tools like Boto and the AWS CLI. By default, this file is located at ~/.aws/credentials:

[default]
# The access key for your AWS account
aws_access_key_id=<YOUR ACCESS KEY ID>

# The secret key for your AWS account
aws_secret_access_key=<YOUR SECRET KEY>

Credentials can also be set for individual profiles:

[dev-profile]
# The access key for your dev-profile account
aws_access_key_id=<YOUR ACCESS KEY ID>

# The secret key for your dev-profile account
aws_secret_access_key=<YOUR SECRET KEY>

The second configuration file stores all settings which are not credentials. Its default location is ~/.aws/config:

[default]
# The default region when making requests
region=<REGION NAME>

It also supports profiles, but these are prefixed with the word profile because this file supports sections other than profiles:

[profile dev-profile]
# The default region when using the dev-profile account
region=<REGION NAME>
Extensibility Guide

All of Boto3's resource and client classes are generated at runtime. This means that you cannot directly inherit and then extend the functionality of these classes because they do not exist until the program actually starts running.

However it is still possible to extend the functionality of classes through Boto3's event system.

An Introduction to the Event System

Boto3's event system allows users to register a function to a specific event. Then once the running program reaches a line that emits that specific event, Boto3 will call every function registered to the event in the order in which they were registered. When Boto3 calls each of these registered functions, it will call each of them with a specific set of keyword arguments that are associated with that event. Then once the registered function is called, the function may modify the keyword arguments passed to that function or return a value. Here is an example of how the event system works:

import boto3

s3 = boto3.client('s3')

# Access the event system on the S3 client
event_system = s3.meta.events

# Create a function
def add_my_bucket(params, **kwargs):
    # Add the name of the bucket you want to default to.
    if 'Bucket' not in params:
        params['Bucket'] = 'mybucket'

# Register the function to an event
event_system.register('provide-client-params.s3.ListObjects', add_my_bucket)

response = s3.list_objects()

In this example, the handler add_my_bucket is registered such that the handler will inject the value 'mybucket for the Bucket parameter whenever the the list_objects client call is made without the Bucket parameter. Note that if the same list_objects call is made without the Bucket parameter and the registered handler, it will result in a validation error.

Here are the takeaways from this example:

  • All clients have their own event system that you can use to fire events and register functions. You can access the event system through the meta.events attribute on the client.
  • All functions registered to the event system must have **kwargs in the function signature. This is because emitting an event can have any number of keyword arguments emitted along side it, and so if your function is called without **kwargs, its signature will have to match every keyword argument emitted by the event. This also allows for more keyword arguments to be added to the emitted event in the future without breaking existing handlers.
  • To register a function to an event, call the register method on the event system with the name of the event you want to register the function to and the function handle. Note that if you register the event after the event is emitted, the function will not be called unless the event is emitted again. In the example, the add_my_bucket handler was registered to the 'provide-client-params.s3.ListObjects' event, which is an event that can be used to inject and modify parameters passed in by the client method. To read more about the event refer to provide-client-params
A Hierarchical Structure

The event system also provides a hierarchy for registering events such that you can register a function to a set of events depending on the event name heirarchy.

An event name can have its own heirachy by specifying . in its name. For example, take the event name 'general.specific.more_specific'. When this event is emitted, the registered functions will be called in the order from most specific to least specific registration. So in this example, the functions will be called in the following order:

  1. Functions registered to 'general.specific.more_specific'
  2. Functions registered to 'general.specific'
  3. Functions registered to 'general'

Here is a deeper example of how the event system works with respect to its hierarchial structure:

import boto3

s3 = boto3.client('s3')

# Access the event system on the S3 client
event_system = s3.meta.events

def add_my_general_bucket(params, **kwargs):
    if 'Bucket' not in params:
        params['Bucket'] = 'mybucket'

def add_my_specific_bucket(params, **kwargs):
    if 'Bucket' not in params:
        params['Bucket'] = 'myspecificbucket'

event_system.register('provide-client-params.s3', add_my_general_bucket)
event_system.register('provide-client-params.s3.ListObjects', add_my_specific_bucket)

list_obj_response = s3.list_objects()
put_obj_response = s3.put_object(Key='mykey', Body=b'my body')

In this example, the list_objects method call will use the 'myspecificbucket' for the bucket instead of 'mybucket' because the add_my_specific_bucket method was registered to the 'provide-client-params.s3.ListObjects' event which is more specific than the 'provide-client-params.s3' event. Thus, the add_my_specific_bucket function is called before the add_my_general_bucket function is called when the event is emitted.

However for the put_object call, the bucket used is 'mybucket'. This is because the event emitted for the put_object client call is 'provide-client-params.s3.PutObject' and the add_my_general_bucket method is called via its registration to 'provide-client-params.s3'. The 'provide-client-params.s3.ListObjects' event is never emitted so the registered add_my_specific_bucket function is never called.

Wildcard Matching

Another aspect of Boto3's event system is that it has the capability to do wildcard matching using the '*' notation. Here is an example of using wildcards in the event system:

import boto3

s3 = boto3.client('s3')

# Access the event system on the S3 client
event_system = s3.meta.events

def add_my_wildcard_bucket(params, **kwargs):
    if 'Bucket' not in params:
        params['Bucket'] = 'mybucket'

event_system.register('provide-client-params.s3.*', add_my_wildcard_bucket)
response = s3.list_objects()

The '*' allows you to register to a group of events without having to know the actual name of the event. This is useful when you have to apply the same handler in multiple places. Also note that if the wildcard is used, it must be isolated. It does not handle globbing with additional characters. So in the previous example, if the my_wildcard_function was registered to 'provide-client-params.s3.*objects', the handler would not be called because it will consider 'provide-client-params.s3.*objects' to be a specific event.

The wildcard also respects the hierarchical structure of the event system. If another handler was registered to the 'provide-client-params.s3' event, the add_my_wildcard_bucket would be called first because it is registered to 'provide-client-params.s3.*' which is more specific than the event 'provide-client.s3'.

Isolation of Event Systems

The event system in Boto3 has the notion of isolation: all clients maintain their own set of registered handlers. For example if a handler is registered to one client's event system, it will not be registered to another client's event system:

import boto3

client1 = boto3.client('s3')
client2 = boto3.client('s3')

def add_my_bucket(params, **kwargs):
    if 'Bucket' not in params:
        params['Bucket'] = 'mybucket'

def add_my_other_bucket(params, **kwargs):
    if 'Bucket' not in params:
        params['Bucket'] = 'myotherbucket'

client1.meta.events.register(
    'provide-client-params.s3.ListObjects', add_my_bucket)
client2.meta.events.register(
    'provide-client-params.s3.ListObjects', add_my_other_bucket)

client1_response = client1.list_objects()
client2_response = client2.list_objects()

Thanks to the isolation of clients' event systems, client1 will inject 'mybucket' for its list_objects method call while client2 will inject 'myotherbucket' for its list_objects method call because add_my_bucket was registered to client1 while add_my_other_bucket was registered to client2.

Boto3 Specific Events

Boto3 emits a set of events that users can register to customize clients or resources and modify the behavior of method calls.

Here is the list of events that users of boto3 can register handlers to:

  • 'creating-client-class
  • 'creating-resource-class
  • 'provide-client-params'
creating-client-class
Full Event Name

'creating-client-class.service-name'

Note: service-name refers to the value used to instantiate a client i.e. boto3.client('service-name')

Description

This event is emitted upon creation of the client class for a service. The client class for a service is not created until the first instantiation of the client class. Use this event for adding methods to the client class or adding classes for the client class to inherit from.

Keyword Arguments Emitted
type class_attributes
dict
param class_attributes
A dictionary where the keys are the names of the attributes of the class and the values are the actual attributes of the class.
type base_classes
list
param base_classes
A list of classes that the client class will inherit from where the order of inheritance is the same as the order of the list.
Expected Return Value

Do not return anything.

Example

Here is an example of how to add a method to the client class:

from boto3.session import Session

def custom_method(self):
    print('This is my custom method')

def add_custom_method(class_attributes, **kwargs):
    class_attributes['my_method'] = custom_method

session = Session()
session.events.register('creating-client-class.s3', add_custom_method)

client = session.client('s3')
client.my_method()

This should output:

This is my custom method

Here is an example of how to add a new class for the client class to inherit from:

from boto3.session import Session

class MyClass(object):
    def __init__(self, *args, **kwargs):
        super(MyClass, self).__init__(*args, **kwargs)
        print('Client instantiated!')

def add_custom_class(base_classes, **kwargs):
    base_classes.insert(0, MyClass)

session = Session()
session.events.register('creating-client-class.s3', add_custom_class)

client = session.client('s3')

This should output:

Client instantiated!
creating-resource-class
Full Event Name

'creating-resource-class.service-name.resource-name'

Note: service-name refers to the value used to instantiate a service resource i.e. boto3.resource('service-name') and resource-name refers to the name of the resource class.

Description

This event is emitted upon creation of the resource class. The resource class is not created until the first instantiation of the resource class. Use this event for adding methods to the resource class or adding classes for the resource class to inherit from.

Keyword Arguments Emitted
type class_attributes
dict
param class_attributes
A dictionary where the keys are the names of the attributes of the class and the values are the actual attributes of the class.
type base_classes
list
param base_classes
A list of classes that the resource class will inherit from where the order of inheritance is the same as the order of the list.
Expected Return Value

Do not return anything.

Example

Here is an example of how to add a method to a resource class:

from boto3.session import Session

def custom_method(self):
    print('This is my custom method')

def add_custom_method(class_attributes, **kwargs):
    class_attributes['my_method'] = custom_method

session = Session()
session.events.register('creating-resource-class.s3.ServiceResource',
                        add_custom_method)

resource = session.resource('s3')
resource.my_method()

This should output:

This is my custom method

Here is an example of how to add a new class for a resource class to inherit from:

from boto3.session import Session

class MyClass(object):
    def __init__(self, *args, **kwargs):
        super(MyClass, self).__init__(*args, **kwargs)
        print('Resource instantiated!')

def add_custom_class(base_classes, **kwargs):
    base_classes.insert(0, MyClass)

session = Session()
session.events.register('creating-resource-class.s3.ServiceResource',
                        add_custom_class)

resource = session.resource('s3')

This should output:

Resource instantiated!
provide-client-params
Full Event Name

'provide-client.service-name.operation-name'

Note: service-name refers to the value used to instantiate a client i.e. boto3.client('service-name'). operation-name refers to the underlying API operation of the corresponding client method. To access the operation API name, retrieve the value from the client.meta.method_to_api_mapping dictionary using the name of the desired client method as the key.

Description

This event is emitted before validation of the parameters passed to client method. Use this event to inject or modify parameters prior to the parameters being validated and built into a request that is sent over the wire.

Keyword Arguments Emitted
type params
dict
param params
A dictionary where the keys are the names of the parameters passed through the client method and the values are the values of those parameters.
type model
botocore.model.OperationModel
param model
A model representing the underlying API operation of the client method.
Expected Return Value

Do not return anything or return a new dictionary of parameters to use when making the request.

Example

Here is an example of how to inject a parameter using the event:

import boto3

s3 = boto3.client('s3')

# Access the event system on the S3 client
event_system = s3.meta.events

# Create a function
def add_my_bucket(params, **kwargs):
    # Add the name of the bucket you want to default to.
    if 'Bucket' not in params:
        params['Bucket'] = 'mybucket'

# Register the function to an event
event_system.register('provide-client-params.s3.ListObjects', add_my_bucket)

response = s3.list_objects()

Service Feature Guides

DynamoDB

By following this guide, you will learn how to use the DynamoDB.ServiceResource and DynamoDB.Table resources in order to create tables, write items to tables, modify existing items, retrieve items, and query/filter the items in the table.

Creating a New Table

In order to create a new table, use the DynamoDB.ServiceResource.create_table() method:

import boto3

# Get the service resource.
dynamodb = boto3.resource('dynamodb')

# Create the DynamoDB table.
table = dynamodb.create_table(
    TableName='users',
    KeySchema=[
        {
            'AttributeName': 'username',
            'KeyType': 'HASH'
        },
        {
            'AttributeName': 'last_name',
            'KeyType': 'RANGE'
        }
    ],
    AttributeDefinitions=[
        {
            'AttributeName': 'username',
            'AttributeType': 'S'
        },
        {
            'AttributeName': 'last_name',
            'AttributeType': 'S'
        },

    ],
    ProvisionedThroughput={
        'ReadCapacityUnits': 5,
        'WriteCapacityUnits': 5
    }
)

# Wait until the table exists.
table.meta.client.get_waiter('table_exists').wait(TableName='users')

# Print out some data about the table.
print(table.item_count)

Expected Output:

0

This creates a table named users that respectively has the hash and range primary keys username and last_name. This method will return a DynamoDB.Table resource to call additional methods on the created table.

Using an Existing Table

It is also possible to create a DynamoDB.Table resource from an existing table:

import boto3

# Get the service resource.
dynamodb = boto3.resource('dynamodb')

# Instantiate a table resource object without actually
# creating a DynamoDB table. Note that the attributes of this table
# are lazy-loaded: a request is not made nor are the attribute
# values populated until the attributes
# on the table resource are accessed or its load() method is called.
table = dynamodb.Table('users')

# Print out some data about the table.
# This will cause a request to be made to DynamoDB and its attribute
# values will be set based on the response.
print(table.creation_date_time)

Expected Output (Pleas note that probably the actual times will not match up):

2015-06-26 12:42:45.149000-07:00
Creating a New Item

Once you have a DynamoDB.Table resource you can add new items to the table using DynamoDB.Table.put_item():

table.put_item(
   Item={
        'username': 'janedoe',
        'first_name': 'Jane',
        'last_name': 'Doe',
        'age': 25,
        'account_type': 'standard_user',
    }
)

For all of the valid types that can be used for an item, refer to Valid DynamoDB Types.

Getting an Item

You can then retrieve the object using DynamoDB.Table.get_item():

response = table.get_item(
    Key={
        'username': 'janedoe',
        'last_name': 'Doe'
    }
)
item = response['Item']
print(item)

Expected Output:

{u'username': u'janedoe',
 u'first_name': u'Jane',
 u'last_name': u'Doe',
 u'account_type': u'standard_user',
 u'age': Decimal('25')}
Updating Item

Using the retrieved item, you can update attributes of the item in the table:

item['age'] = 26
table.put_item(Item=item)

Then if you retrieve the item again, it will be updated appropriately:

response = table.get_item(
    Key={
        'username': 'janedoe',
        'last_name': 'Doe'
    }
)
item = response['Item']
print(item)

Expected Output:

{u'username': u'janedoe',
 u'first_name': u'Jane',
 u'last_name': u'Doe',
 u'account_type': u'standard_user',
 u'age': Decimal('26')}
Deleting Item

You can also delete the item using DynamoDB.Table.delete_item():

table.delete_item(
    Key={
        'username': 'janedoe',
        'last_name': 'Doe'
    }
)
Batch Writing

If you are loading a lot of data at a time, you can make use of DyanmoDB.Table.batch_writer() so you can both speed up the process and reduce the number of write requests made to the service.

This method returns a handle to a batch writer object that will automatically handle buffering and sending items in batches. In addition, the batch writer will also automatically handle any unprocessed items and resend them as needed. All you need to do is call put_item for any items you want to add, and delete_item for any items you want to delete:

with table.batch_writer() as batch:
    batch.put_item(
        Item={
            'account_type': 'standard_user',
            'username': 'johndoe',
            'first_name': 'John',
            'last_name': 'Doe',
            'age': 25,
            'address': {
                'road': '1 Jefferson Street',
                'city': 'Los Angeles',
                'state': 'CA',
                'zipcode': 90001
            }
        }
    )
    batch.put_item(
        Item={
            'account_type': 'super_user',
            'username': 'janedoering',
            'first_name': 'Jane',
            'last_name': 'Doering',
            'age': 40,
            'address': {
                'road': '2 Washington Avenue',
                'city': 'Seattle',
                'state': 'WA',
                'zipcode': 98109
            }
        }
    )
    batch.put_item(
        Item={
            'account_type': 'standard_user',
            'username': 'bobsmith',
            'first_name': 'Bob',
            'last_name':  'Smith',
            'age': 18,
            'address': {
                'road': '3 Madison Lane',
                'city': 'Louisville',
                'state': 'KY',
                'zipcode': 40213
            }
        }
    )
    batch.put_item(
        Item={
            'account_type': 'super_user',
            'username': 'alicedoe',
            'first_name': 'Alice',
            'last_name': 'Doe',
            'age': 27,
            'address': {
                'road': '1 Jefferson Street',
                'city': 'Los Angeles',
                'state': 'CA',
                'zipcode': 90001
            }
        }
    )

The batch writer is even able to handle a very large amount of writes to the table.

with table.batch_writer() as batch:
    for i in range(50):
        batch.put_item(
            Item={
                'account_type': 'anonymous',
                'username': 'user' + str(i),
                'first_name': 'unknown',
                'last_name': 'unknown'
            }
        )
Querying and Scanning

With the table full of items, you can then query or scan the items in the table using the DynamoDB.Table.query() or DynamoDB.Table.scan() methods respectively. To add conditions to scanning and querying the table, you will need to import the boto3.dynamodb.conditions.Key and boto3.dynamodb.conditions.Attr classes. The boto3.dynamodb.conditions.Key should be used when the condition is related to the key of the item. The boto3.dynamodb.conditions.Attr should be used when the condition is related to an attribute of the item:

from boto3.dynamodb.conditions import Key, Attr

This queries for all of the users whose username key equals johndoe:

response = table.query(
    KeyConditionExpression=Key('username').eq('johndoe')
)
items = response['Items']
print(items)

Expected Output:

[{u'username': u'johndoe',
  u'first_name': u'John',
  u'last_name': u'Doe',
  u'account_type': u'standard_user',
  u'age': Decimal('25'),
  u'address': {u'city': u'Los Angeles',
               u'state': u'CA',
               u'zipcode': Decimal('90001'),
               u'road': u'1 Jefferson Street'}}]

Similiarly you can scan the table based on attributes of the items. For example, this scans for all the users whose age is less than 27:

response = table.scan(
    FilterExpression=Attr('age').lt(27)
)
items = response['Items']
print(items)

Expected Output:

[{u'username': u'johndoe',
  u'first_name': u'John',
  u'last_name': u'Doe',
  u'account_type': u'standard_user',
  u'age': Decimal('25'),
  u'address': {u'city': u'Los Angeles',
               u'state': u'CA',
               u'zipcode': Decimal('90001'),
               u'road': u'1 Jefferson Street'}},
 {u'username': u'bobsmith',
  u'first_name': u'Bob',
  u'last_name': u'Smith',
  u'account_type': u'standard_user',
  u'age': Decimal('18'),
  u'address': {u'city': u'Louisville',
               u'state': u'KY',
               u'zipcode': Decimal('40213'),
               u'road': u'3 Madison Lane'}}]

You are also able to chain conditions together using the logical operators: & (and), | (or), and ~ (not). For example, this scans for all users whose first_name starts with J and whose account_type is super_user:

response = table.scan(
    FilterExpression=Attr('first_name').begins_with('J') & Attr('account_type').eq('super_user')
)
items = response['Items']
print(items)

Expected Output:

[{u'username': u'janedoering',
  u'first_name': u'Jane',
  u'last_name': u'Doering',
  u'account_type': u'super_user',
  u'age': Decimal('40'),
  u'address': {u'city': u'Seattle',
               u'state': u'WA',
               u'zipcode': Decimal('98109'),
               u'road': u'2 Washington Avenue'}}]

You can even scan based on conditions of a nested attribute. For example this scans for all users whose state in their address is CA:

response = table.scan(
    FilterExpression=Attr('address.state').eq('CA')
)
items = response['Items']
print(items)

Expected Output:

[{u'username': u'johndoe',
  u'first_name': u'John',
  u'last_name': u'Doe',
  u'account_type': u'standard_user',
  u'age': Decimal('25'),
  u'address': {u'city': u'Los Angeles',
               u'state': u'CA',
               u'zipcode': Decimal('90001'),
               u'road': u'1 Jefferson Street'}},
 {u'username': u'alicedoe',
  u'first_name': u'Alice',
  u'last_name': u'Doe',
  u'account_type': u'super_user',
  u'age': Decimal('27'),
  u'address': {u'city': u'Los Angeles',
               u'state': u'CA',
               u'zipcode': Decimal('90001'),
               u'road': u'1 Jefferson Street'}}]

For more information on the various conditions you can use for queries and scans, refer to DynamoDB Conditions.

Deleting a Table

Finally, if you want to delete your table call DynamoDB.Table.delete():

table.delete()

API Reference

Services

Available Services

AutoScaling

Table of Contents

Client
class AutoScaling.Client

A low-level client representing Auto Scaling:

import boto3

client = boto3.client('autoscaling')

These are the available methods:

attach_instances(**kwargs)

Attaches one or more EC2 instances to the specified Auto Scaling group.

For more information, see Attach EC2 Instances to Your Auto Scaling Group in the Auto Scaling Developer Guide .

Request Syntax

response = client.attach_instances(
    InstanceIds=[
        'string',
    ],
    AutoScalingGroupName='string'
)
Parameters
  • InstanceIds (list) --

    One or more EC2 instance IDs.

    • (string) --
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group.

Returns

None

attach_load_balancers(**kwargs)

Attaches one or more load balancers to the specified Auto Scaling group.

To describe the load balancers for an Auto Scaling group, use DescribeLoadBalancers . To detach the load balancer from the Auto Scaling group, use DetachLoadBalancers .

For more information, see Attach a Load Balancer to Your Auto Scaling Group in the Auto Scaling Developer Guide .

Request Syntax

response = client.attach_load_balancers(
    AutoScalingGroupName='string',
    LoadBalancerNames=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • LoadBalancerNames (list) --

    One or more load balancer names.

    • (string) --
Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters
operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Returns
True if the operation can be paginated, False otherwise.
complete_lifecycle_action(**kwargs)

Completes the lifecycle action for the associated token initiated under the given lifecycle hook with the specified result.

This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:

  • Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
  • Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the designated SQS queue or SNS topic.
  • Create the lifecycle hook. You can create a hook that acts when instances launch or when instances terminate.
  • If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
  • Complete the lifecycle action .

For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto Scaling Developer Guide .

Request Syntax

response = client.complete_lifecycle_action(
    LifecycleHookName='string',
    AutoScalingGroupName='string',
    LifecycleActionToken='string',
    LifecycleActionResult='string'
)
Parameters
  • LifecycleHookName (string) --

    [REQUIRED]

    The name of the lifecycle hook.

  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group for the lifecycle hook.

  • LifecycleActionToken (string) --

    [REQUIRED]

    A universally unique identifier (UUID) that identifies a specific lifecycle action associated with an instance. Auto Scaling sends this token to the notification target you specified when you created the lifecycle hook.

  • LifecycleActionResult (string) --

    [REQUIRED]

    The action for the group to take. This parameter can be either CONTINUE or ABANDON .

Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

create_auto_scaling_group(**kwargs)

Creates an Auto Scaling group with the specified name and attributes.

If you exceed your maximum limit of Auto Scaling groups, which by default is 20 per region, the call fails. For information about viewing and updating this limit, see DescribeAccountLimits .

For more information, see Auto Scaling Groups in the Auto Scaling Developer Guide .

Request Syntax

response = client.create_auto_scaling_group(
    AutoScalingGroupName='string',
    LaunchConfigurationName='string',
    InstanceId='string',
    MinSize=123,
    MaxSize=123,
    DesiredCapacity=123,
    DefaultCooldown=123,
    AvailabilityZones=[
        'string',
    ],
    LoadBalancerNames=[
        'string',
    ],
    HealthCheckType='string',
    HealthCheckGracePeriod=123,
    PlacementGroup='string',
    VPCZoneIdentifier='string',
    TerminationPolicies=[
        'string',
    ],
    Tags=[
        {
            'ResourceId': 'string',
            'ResourceType': 'string',
            'Key': 'string',
            'Value': 'string',
            'PropagateAtLaunch': True|False
        },
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group. This name must be unique within the scope of your AWS account.

  • LaunchConfigurationName (string) -- The name of the launch configuration. Alternatively, use the InstanceId parameter to specify an EC2 instance instead of a launch configuration.
  • InstanceId (string) --

    The ID of the EC2 instance used to create a launch configuration for the group. Alternatively, use the LaunchConfigurationName parameter to specify a launch configuration instead of an EC2 instance.

    When you specify an ID of an instance, Auto Scaling creates a new launch configuration and associates it with the group. This launch configuration derives its attributes from the specified instance, with the exception of the block device mapping.

    For more information, see Create an Auto Scaling Group from an EC2 Instance in the Auto Scaling Developer Guide .

  • MinSize (integer) --

    [REQUIRED]

    The minimum size of the group.

  • MaxSize (integer) --

    [REQUIRED]

    The maximum size of the group.

  • DesiredCapacity (integer) -- The number of EC2 instances that should be running in the group. This number must be greater than or equal to the minimum size of the group and less than or equal to the maximum size of the group.
  • DefaultCooldown (integer) --

    The amount of time, in seconds, after a scaling activity completes before another scaling activity can start.

    If this parameter is not specified, the default value is 300. For more information, see Understanding Auto Scaling Cooldowns in the Auto Scaling Developer Guide .

  • AvailabilityZones (list) --

    One or more Availability Zones for the group. This parameter is optional if you specify subnets using the VPCZoneIdentifier parameter.

    • (string) --
  • LoadBalancerNames (list) --

    One or more load balancers.

    For more information, see Load Balance Your Auto Scaling Group in the Auto Scaling Developer Guide .

    • (string) --
  • HealthCheckType (string) --

    The service to use for the health checks. The valid values are EC2 and ELB .

    By default, health checks use Amazon EC2 instance status checks to determine the health of an instance. For more information, see Health Checks .

  • HealthCheckGracePeriod (integer) --

    The amount of time, in seconds, after an EC2 instance comes into service that Auto Scaling starts checking its health. During this time, any health check failures for the instance are ignored.

    This parameter is required if you are adding an ELB health check. Frequently, new instances need to warm up, briefly, before they can pass a health check. To provide ample warm-up time, set the health check grace period of the group to match the expected startup period of your application.

    For more information, see Add an Elastic Load Balancing Health Check to Your Auto Scaling Group in the Auto Scaling Developer Guide .

  • PlacementGroup (string) -- The name of the placement group into which you'll launch your instances, if any. For more information, see Placement Groups in the Amazon Elastic Compute Cloud User Guide .
  • VPCZoneIdentifier (string) --

    A comma-separated list of subnet identifiers for your virtual private cloud (VPC).

    If you specify subnets and Availability Zones with this call, ensure that the subnets' Availability Zones match the Availability Zones specified.

    For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto Scaling Developer Guide .

  • TerminationPolicies (list) --

    One or more termination policies used to select the instance to terminate. These policies are executed in the order that they are listed.

    For more information, see Choosing a Termination Policy for Your Auto Scaling Group in the Auto Scaling Developer Guide .

    • (string) --
  • Tags (list) --

    The tag to be created or updated. Each tag should be defined by its resource type, resource ID, key, value, and a propagate flag. Valid values: key=*value* , value=*value* , propagate=*true* or false . Value and propagate are optional parameters.

    For more information, see Tagging Auto Scaling Groups and Instances in the Auto Scaling Developer Guide .

    • (dict) --

      Describes a tag for an Auto Scaling group.

      • ResourceId (string) --

        The name of the group.

      • ResourceType (string) --

        The type of resource. The only supported value is auto-scaling-group .

      • Key (string) -- [REQUIRED]

        The tag key.

      • Value (string) --

        The tag value.

      • PropagateAtLaunch (boolean) --

        Determines whether the tag is added to new instances as they are launched in the group.

Returns

None

create_launch_configuration(**kwargs)

Creates a launch configuration.

If you exceed your maximum limit of launch configurations, which by default is 100 per region, the call fails. For information about viewing and updating this limit, see DescribeAccountLimits .

For more information, see Launch Configurations in the Auto Scaling Developer Guide .

Request Syntax

response = client.create_launch_configuration(
    LaunchConfigurationName='string',
    ImageId='string',
    KeyName='string',
    SecurityGroups=[
        'string',
    ],
    ClassicLinkVPCId='string',
    ClassicLinkVPCSecurityGroups=[
        'string',
    ],
    UserData='string',
    InstanceId='string',
    InstanceType='string',
    KernelId='string',
    RamdiskId='string',
    BlockDeviceMappings=[
        {
            'VirtualName': 'string',
            'DeviceName': 'string',
            'Ebs': {
                'SnapshotId': 'string',
                'VolumeSize': 123,
                'VolumeType': 'string',
                'DeleteOnTermination': True|False,
                'Iops': 123
            },
            'NoDevice': True|False
        },
    ],
    InstanceMonitoring={
        'Enabled': True|False
    },
    SpotPrice='string',
    IamInstanceProfile='string',
    EbsOptimized=True|False,
    AssociatePublicIpAddress=True|False,
    PlacementTenancy='string'
)
Parameters
  • LaunchConfigurationName (string) --

    [REQUIRED]

    The name of the launch configuration. This name must be unique within the scope of your AWS account.

  • ImageId (string) -- The ID of the Amazon Machine Image (AMI) to use to launch your EC2 instances. For more information, see Finding an AMI in the Amazon Elastic Compute Cloud User Guide .
  • KeyName (string) -- The name of the key pair. For more information, see Amazon EC2 Key Pairs in the Amazon Elastic Compute Cloud User Guide .
  • SecurityGroups (list) --

    One or more security groups with which to associate the instances.

    If your instances are launched in EC2-Classic, you can either specify security group names or the security group IDs. For more information about security groups for EC2-Classic, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud User Guide .

    If your instances are launched into a VPC, specify security group IDs. For more information, see Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide .

    • (string) --
  • ClassicLinkVPCId (string) -- The ID of a ClassicLink-enabled VPC to link your EC2-Classic instances to. This parameter is supported only if you are launching EC2-Classic instances. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .
  • ClassicLinkVPCSecurityGroups (list) --

    The IDs of one or more security groups for the VPC specified in ClassicLinkVPCId . This parameter is required if ClassicLinkVPCId is specified, and is not supported otherwise. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .

    • (string) --
  • UserData (string) --

    The user data to make available to the launched EC2 instances. For more information, see Instance Metadata and User Data in the Amazon Elastic Compute Cloud User Guide .

    At this time, launch configurations don't support compressed (zipped) user data files.

    This value will be base64 encoded automatically. Do not base64 encode this value prior to performing the operation.
  • InstanceId (string) --

    The ID of the EC2 instance to use to create the launch configuration.

    The new launch configuration derives attributes from the instance, with the exception of the block device mapping.

    To create a launch configuration with a block device mapping or override any other instance attributes, specify them as part of the same request.

    For more information, see Create a Launch Configuration Using an EC2 Instance in the Auto Scaling Developer Guide .

  • InstanceType (string) -- The instance type of the EC2 instance. For information about available instance types, see Available Instance Types in the Amazon Elastic Cloud Compute User Guide.
  • KernelId (string) -- The ID of the kernel associated with the AMI.
  • RamdiskId (string) -- The ID of the RAM disk associated with the AMI.
  • BlockDeviceMappings (list) --

    One or more mappings that specify how block devices are exposed to the instance. For more information, see Block Device Mapping in the Amazon Elastic Compute Cloud User Guide .

    • (dict) --

      Describes a block device mapping.

      • VirtualName (string) --

        The name of the virtual device, ephemeral0 to ephemeral3 .

      • DeviceName (string) -- [REQUIRED]

        The device name exposed to the EC2 instance (for example, /dev/sdh or xvdh ).

      • Ebs (dict) --

        The information about the Amazon EBS volume.

        • SnapshotId (string) --

          The ID of the snapshot.

        • VolumeSize (integer) --

          The volume size, in gigabytes.

          Valid values: If the volume type is io1 , the minimum size of the volume is 10 GiB. If you specify SnapshotId and VolumeSize , VolumeSize must be equal to or larger than the size of the snapshot.

          Default: If you create a volume from a snapshot and you don't specify a volume size, the default is the size of the snapshot.

          Required: Required when the volume type is io1 .

        • VolumeType (string) --

          The volume type.

          Valid values: standard | io1 | gp2

          Default: standard

        • DeleteOnTermination (boolean) --

          Indicates whether to delete the volume on instance termination.

          Default: true

        • Iops (integer) --

          For Provisioned IOPS (SSD) volumes only. The number of I/O operations per second (IOPS) to provision for the volume.

          Valid values: Range is 100 to 4000.

          Default: None

      • NoDevice (boolean) --

        Suppresses a device mapping.

        If this parameter is true for the root device, the instance might fail the EC2 health check. Auto Scaling launches a replacement instance if the instance fails the health check.

  • InstanceMonitoring (dict) --

    Enables detailed monitoring if it is disabled. Detailed monitoring is enabled by default.

    When detailed monitoring is enabled, Amazon CloudWatch generates metrics every minute and your account is charged a fee. When you disable detailed monitoring, by specifying False , CloudWatch generates metrics every 5 minutes. For more information, see Monitor Your Auto Scaling Instances in the Auto Scaling Developer Guide .

    • Enabled (boolean) --

      If True , instance monitoring is enabled.

  • SpotPrice (string) -- The maximum hourly price to be paid for any Spot Instance launched to fulfill the request. Spot Instances are launched when the price you specify exceeds the current Spot market price. For more information, see Launch Spot Instances in Your Auto Scaling Group in the Auto Scaling Developer Guide .
  • IamInstanceProfile (string) --

    The name or the Amazon Resource Name (ARN) of the instance profile associated with the IAM role for the instance.

    EC2 instances launched with an IAM role will automatically have AWS security credentials available. You can use IAM roles with Auto Scaling to automatically enable applications running on your EC2 instances to securely access other AWS resources. For more information, see Launch Auto Scaling Instances with an IAM Role in the Auto Scaling Developer Guide .

  • EbsOptimized (boolean) -- Indicates whether the instance is optimized for Amazon EBS I/O. By default, the instance is not optimized for EBS I/O. The optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal I/O performance. This optimization is not available with all instance types. Additional usage charges apply. For more information, see Amazon EBS-Optimized Instances in the Amazon Elastic Compute Cloud User Guide .
  • AssociatePublicIpAddress (boolean) --

    Used for groups that launch instances into a virtual private cloud (VPC). Specifies whether to assign a public IP address to each instance. For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto Scaling Developer Guide .

    If you specify a value for this parameter, be sure to specify at least one subnet using the VPCZoneIdentifier parameter when you create your group.

    Default: If the instance is launched into a default subnet, the default is true . If the instance is launched into a nondefault subnet, the default is false . For more information, see Supported Platforms in the Amazon Elastic Compute Cloud User Guide .

  • PlacementTenancy (string) --

    The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware and can only be launched into a VPC.

    You must set the value of this parameter to dedicated if want to launch Dedicated Instances into a shared tenancy VPC (VPC with instance placement tenancy attribute set to default ).

    If you specify a value for this parameter, be sure to specify at least one subnet using the VPCZoneIdentifier parameter when you create your group.

    For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto Scaling Developer Guide .

    Valid values: default | dedicated

Returns

None

create_or_update_tags(**kwargs)

Creates or updates tags for the specified Auto Scaling group.

A tag is defined by its resource ID, resource type, key, value, and propagate flag. The value and the propagate flag are optional parameters. The only supported resource type is auto-scaling-group , and the resource ID must be the name of the group. The PropagateAtLaunch flag determines whether the tag is added to instances launched in the group. Valid values are true or false .

When you specify a tag with a key that already exists, the operation overwrites the previous tag definition, and you do not get an error message.

For more information, see Tagging Auto Scaling Groups and Instances in the Auto Scaling Developer Guide .

Request Syntax

response = client.create_or_update_tags(
    Tags=[
        {
            'ResourceId': 'string',
            'ResourceType': 'string',
            'Key': 'string',
            'Value': 'string',
            'PropagateAtLaunch': True|False
        },
    ]
)
Parameters
Tags (list) --

[REQUIRED]

One or more tags.

  • (dict) --

    Describes a tag for an Auto Scaling group.

    • ResourceId (string) --

      The name of the group.

    • ResourceType (string) --

      The type of resource. The only supported value is auto-scaling-group .

    • Key (string) -- [REQUIRED]

      The tag key.

    • Value (string) --

      The tag value.

    • PropagateAtLaunch (boolean) --

      Determines whether the tag is added to new instances as they are launched in the group.

Returns
None
delete_auto_scaling_group(**kwargs)

Deletes the specified Auto Scaling group.

The group must have no instances and no scaling activities in progress.

To remove all instances before calling DeleteAutoScalingGroup , call UpdateAutoScalingGroup to set the minimum and maximum size of the Auto Scaling group to zero.

Request Syntax

response = client.delete_auto_scaling_group(
    AutoScalingGroupName='string',
    ForceDelete=True|False
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group to delete.

  • ForceDelete (boolean) -- Specifies that the group will be deleted along with all instances associated with the group, without waiting for all instances to be terminated. This parameter also deletes any lifecycle actions associated with the group.
Returns

None

delete_launch_configuration(**kwargs)

Deletes the specified launch configuration.

The launch configuration must not be attached to an Auto Scaling group. When this call completes, the launch configuration is no longer available for use.

Request Syntax

response = client.delete_launch_configuration(
    LaunchConfigurationName='string'
)
Parameters
LaunchConfigurationName (string) --

[REQUIRED]

The name of the launch configuration.

Returns
None
delete_lifecycle_hook(**kwargs)

Deletes the specified lifecycle hook.

If there are any outstanding lifecycle actions, they are completed first (ABANDON for launching instances, CONTINUE for terminating instances).

Request Syntax

response = client.delete_lifecycle_hook(
    LifecycleHookName='string',
    AutoScalingGroupName='string'
)
Parameters
  • LifecycleHookName (string) --

    [REQUIRED]

    The name of the lifecycle hook.

  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group for the lifecycle hook.

Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

delete_notification_configuration(**kwargs)

Deletes the specified notification.

Request Syntax

response = client.delete_notification_configuration(
    AutoScalingGroupName='string',
    TopicARN='string'
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

  • TopicARN (string) --

    [REQUIRED]

    The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.

Returns

None

delete_policy(**kwargs)

Deletes the specified Auto Scaling policy.

Request Syntax

response = client.delete_policy(
    AutoScalingGroupName='string',
    PolicyName='string'
)
Parameters
  • AutoScalingGroupName (string) -- The name of the Auto Scaling group.
  • PolicyName (string) --

    [REQUIRED]

    The name or Amazon Resource Name (ARN) of the policy.

Returns

None

delete_scheduled_action(**kwargs)

Deletes the specified scheduled action.

Request Syntax

response = client.delete_scheduled_action(
    AutoScalingGroupName='string',
    ScheduledActionName='string'
)
Parameters
  • AutoScalingGroupName (string) -- The name of the Auto Scaling group.
  • ScheduledActionName (string) --

    [REQUIRED]

    The name of the action to delete.

Returns

None

delete_tags(**kwargs)

Deletes the specified tags.

Request Syntax

response = client.delete_tags(
    Tags=[
        {
            'ResourceId': 'string',
            'ResourceType': 'string',
            'Key': 'string',
            'Value': 'string',
            'PropagateAtLaunch': True|False
        },
    ]
)
Parameters
Tags (list) --

[REQUIRED]

Each tag should be defined by its resource type, resource ID, key, value, and a propagate flag. Valid values are: Resource type = auto-scaling-group , Resource ID = AutoScalingGroupName , key=*value* , value=*value* , propagate=*true* or false .

  • (dict) --

    Describes a tag for an Auto Scaling group.

    • ResourceId (string) --

      The name of the group.

    • ResourceType (string) --

      The type of resource. The only supported value is auto-scaling-group .

    • Key (string) -- [REQUIRED]

      The tag key.

    • Value (string) --

      The tag value.

    • PropagateAtLaunch (boolean) --

      Determines whether the tag is added to new instances as they are launched in the group.

Returns
None
describe_account_limits()

Describes the current Auto Scaling resource limits for your AWS account.

For information about requesting an increase in these limits, see AWS Service Limits in the Amazon Web Services General Reference .

Request Syntax

response = client.describe_account_limits()
Return type
dict
Returns
Response Syntax
{
    'MaxNumberOfAutoScalingGroups': 123,
    'MaxNumberOfLaunchConfigurations': 123
}

Response Structure

  • (dict) --
    • MaxNumberOfAutoScalingGroups (integer) --

      The maximum number of groups allowed for your AWS account. The default limit is 20 per region.

    • MaxNumberOfLaunchConfigurations (integer) --

      The maximum number of launch configurations allowed for your AWS account. The default limit is 100 per region.

describe_adjustment_types()

Describes the policy adjustment types for use with PutScalingPolicy .

Request Syntax

response = client.describe_adjustment_types()
Return type
dict
Returns
Response Syntax
{
    'AdjustmentTypes': [
        {
            'AdjustmentType': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • AdjustmentTypes (list) --

      The policy adjustment types.

      • (dict) --

        Describes a policy adjustment type.

        For more information, see Dynamic Scaling in the Auto Scaling Developer Guide .

        • AdjustmentType (string) --

          The policy adjustment type. The valid values are ChangeInCapacity , ExactCapacity , and PercentChangeInCapacity .

describe_auto_scaling_groups(**kwargs)

Describes one or more Auto Scaling groups. If a list of names is not provided, the call describes all Auto Scaling groups.

Request Syntax

response = client.describe_auto_scaling_groups(
    AutoScalingGroupNames=[
        'string',
    ],
    NextToken='string',
    MaxRecords=123
)
Parameters
  • AutoScalingGroupNames (list) --

    The group names.

    • (string) --
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call.
Return type

dict

Returns

Response Syntax

{
    'AutoScalingGroups': [
        {
            'AutoScalingGroupName': 'string',
            'AutoScalingGroupARN': 'string',
            'LaunchConfigurationName': 'string',
            'MinSize': 123,
            'MaxSize': 123,
            'DesiredCapacity': 123,
            'DefaultCooldown': 123,
            'AvailabilityZones': [
                'string',
            ],
            'LoadBalancerNames': [
                'string',
            ],
            'HealthCheckType': 'string',
            'HealthCheckGracePeriod': 123,
            'Instances': [
                {
                    'InstanceId': 'string',
                    'AvailabilityZone': 'string',
                    'LifecycleState': 'Pending'|'Pending:Wait'|'Pending:Proceed'|'Quarantined'|'InService'|'Terminating'|'Terminating:Wait'|'Terminating:Proceed'|'Terminated'|'Detaching'|'Detached'|'EnteringStandby'|'Standby',
                    'HealthStatus': 'string',
                    'LaunchConfigurationName': 'string'
                },
            ],
            'CreatedTime': datetime(2015, 1, 1),
            'SuspendedProcesses': [
                {
                    'ProcessName': 'string',
                    'SuspensionReason': 'string'
                },
            ],
            'PlacementGroup': 'string',
            'VPCZoneIdentifier': 'string',
            'EnabledMetrics': [
                {
                    'Metric': 'string',
                    'Granularity': 'string'
                },
            ],
            'Status': 'string',
            'Tags': [
                {
                    'ResourceId': 'string',
                    'ResourceType': 'string',
                    'Key': 'string',
                    'Value': 'string',
                    'PropagateAtLaunch': True|False
                },
            ],
            'TerminationPolicies': [
                'string',
            ]
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • AutoScalingGroups (list) --

      The groups.

      • (dict) --

        Describes an Auto Scaling group.

        • AutoScalingGroupName (string) --

          The name of the group.

        • AutoScalingGroupARN (string) --

          The Amazon Resource Name (ARN) of the group.

        • LaunchConfigurationName (string) --

          The name of the associated launch configuration.

        • MinSize (integer) --

          The minimum size of the group.

        • MaxSize (integer) --

          The maximum size of the group.

        • DesiredCapacity (integer) --

          The desired size of the group.

        • DefaultCooldown (integer) --

          The number of seconds after a scaling activity completes before any further scaling activities can start.

        • AvailabilityZones (list) --

          One or more Availability Zones for the group.

          • (string) --
        • LoadBalancerNames (list) --

          One or more load balancers associated with the group.

          • (string) --
        • HealthCheckType (string) --

          The service of interest for the health status check, which can be either EC2 for Amazon EC2 or ELB for Elastic Load Balancing.

        • HealthCheckGracePeriod (integer) --

          The amount of time that Auto Scaling waits before checking an instance's health status. The grace period begins when an instance comes into service.

        • Instances (list) --

          The EC2 instances associated with the group.

          • (dict) --

            Describes an EC2 instance.

            • InstanceId (string) --

              The ID of the instance.

            • AvailabilityZone (string) --

              The Availability Zone in which the instance is running.

            • LifecycleState (string) --

              A description of the current lifecycle state. Note that the Quarantined state is not used.

            • HealthStatus (string) --

              The health status of the instance.

            • LaunchConfigurationName (string) --

              The launch configuration associated with the instance.

        • CreatedTime (datetime) --

          The date and time the group was created.

        • SuspendedProcesses (list) --

          The suspended processes associated with the group.

          • (dict) --

            Describes an Auto Scaling process that has been suspended. For more information, see ProcessType .

            • ProcessName (string) --

              The name of the suspended process.

            • SuspensionReason (string) --

              The reason that the process was suspended.

        • PlacementGroup (string) --

          The name of the placement group into which you'll launch your instances, if any. For more information, see Placement Groups .

        • VPCZoneIdentifier (string) --

          One or more subnet IDs, if applicable, separated by commas.

          If you specify VPCZoneIdentifier and AvailabilityZones , ensure that the Availability Zones of the subnets match the values for AvailabilityZones .

        • EnabledMetrics (list) --

          The metrics enabled for the group.

          • (dict) --

            Describes an enabled metric.

            • Metric (string) --

              The name of the metric.

              • GroupMinSize
              • GroupMaxSize
              • GroupDesiredCapacity
              • GroupInServiceInstances
              • GroupPendingInstances
              • GroupStandbyInstances
              • GroupTerminatingInstances
              • GroupTotalInstances
            • Granularity (string) --

              The granularity of the metric. The only valid value is 1Minute .

        • Status (string) --

          The current state of the group when DeleteAutoScalingGroup is in progress.

        • Tags (list) --

          The tags for the group.

          • (dict) --

            Describes a tag for an Auto Scaling group.

            • ResourceId (string) --

              The name of the group.

            • ResourceType (string) --

              The type of resource. The only supported value is auto-scaling-group .

            • Key (string) --

              The tag key.

            • Value (string) --

              The tag value.

            • PropagateAtLaunch (boolean) --

              Determines whether the tag is added to new instances as they are launched in the group.

        • TerminationPolicies (list) --

          The termination policies for the group.

          • (string) --
    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_auto_scaling_instances(**kwargs)

Describes one or more Auto Scaling instances. If a list is not provided, the call describes all instances.

Request Syntax

response = client.describe_auto_scaling_instances(
    InstanceIds=[
        'string',
    ],
    MaxRecords=123,
    NextToken='string'
)
Parameters
  • InstanceIds (list) --

    One or more Auto Scaling instances to describe, up to 50 instances. If you omit this parameter, all Auto Scaling instances are described. If you specify an ID that does not exist, it is ignored with no error.

    • (string) --
  • MaxRecords (integer) -- The maximum number of items to return with this call.
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
Return type

dict

Returns

Response Syntax

{
    'AutoScalingInstances': [
        {
            'InstanceId': 'string',
            'AutoScalingGroupName': 'string',
            'AvailabilityZone': 'string',
            'LifecycleState': 'string',
            'HealthStatus': 'string',
            'LaunchConfigurationName': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • AutoScalingInstances (list) --

      The instances.

      • (dict) --

        Describes an EC2 instance associated with an Auto Scaling group.

        • InstanceId (string) --

          The ID of the instance.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group associated with the instance.

        • AvailabilityZone (string) --

          The Availability Zone for the instance.

        • LifecycleState (string) --

          The lifecycle state for the instance. For more information, see Auto Scaling Instance States in the Auto Scaling Developer Guide .

        • HealthStatus (string) --

          The health status of this instance. "Healthy" means that the instance is healthy and should remain in service. "Unhealthy" means that the instance is unhealthy and Auto Scaling should terminate and replace it.

        • LaunchConfigurationName (string) --

          The launch configuration associated with the instance.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_auto_scaling_notification_types()

Describes the notification types that are supported by Auto Scaling.

Request Syntax

response = client.describe_auto_scaling_notification_types()
Return type
dict
Returns
Response Syntax
{
    'AutoScalingNotificationTypes': [
        'string',
    ]
}

Response Structure

  • (dict) --
    • AutoScalingNotificationTypes (list) --

      One or more of the following notification types:

      • autoscaling:EC2_INSTANCE_LAUNCH
      • autoscaling:EC2_INSTANCE_LAUNCH_ERROR
      • autoscaling:EC2_INSTANCE_TERMINATE
      • autoscaling:EC2_INSTANCE_TERMINATE_ERROR
      • autoscaling:TEST_NOTIFICATION
      • (string) --
describe_launch_configurations(**kwargs)

Describes one or more launch configurations. If you omit the list of names, then the call describes all launch configurations.

Request Syntax

response = client.describe_launch_configurations(
    LaunchConfigurationNames=[
        'string',
    ],
    NextToken='string',
    MaxRecords=123
)
Parameters
  • LaunchConfigurationNames (list) --

    The launch configuration names.

    • (string) --
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call. The default is 100.
Return type

dict

Returns

Response Syntax

{
    'LaunchConfigurations': [
        {
            'LaunchConfigurationName': 'string',
            'LaunchConfigurationARN': 'string',
            'ImageId': 'string',
            'KeyName': 'string',
            'SecurityGroups': [
                'string',
            ],
            'ClassicLinkVPCId': 'string',
            'ClassicLinkVPCSecurityGroups': [
                'string',
            ],
            'UserData': 'string',
            'InstanceType': 'string',
            'KernelId': 'string',
            'RamdiskId': 'string',
            'BlockDeviceMappings': [
                {
                    'VirtualName': 'string',
                    'DeviceName': 'string',
                    'Ebs': {
                        'SnapshotId': 'string',
                        'VolumeSize': 123,
                        'VolumeType': 'string',
                        'DeleteOnTermination': True|False,
                        'Iops': 123
                    },
                    'NoDevice': True|False
                },
            ],
            'InstanceMonitoring': {
                'Enabled': True|False
            },
            'SpotPrice': 'string',
            'IamInstanceProfile': 'string',
            'CreatedTime': datetime(2015, 1, 1),
            'EbsOptimized': True|False,
            'AssociatePublicIpAddress': True|False,
            'PlacementTenancy': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • LaunchConfigurations (list) --

      The launch configurations.

      • (dict) --

        Describes a launch configuration.

        • LaunchConfigurationName (string) --

          The name of the launch configuration.

        • LaunchConfigurationARN (string) --

          The Amazon Resource Name (ARN) of the launch configuration.

        • ImageId (string) --

          The ID of the Amazon Machine Image (AMI).

        • KeyName (string) --

          The name of the key pair.

        • SecurityGroups (list) --

          The security groups to associate with the instances.

          • (string) --
        • ClassicLinkVPCId (string) --

          The ID of a ClassicLink-enabled VPC to link your EC2-Classic instances to. This parameter can only be used if you are launching EC2-Classic instances. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .

        • ClassicLinkVPCSecurityGroups (list) --

          The IDs of one or more security groups for the VPC specified in ClassicLinkVPCId . This parameter is required if ClassicLinkVPCId is specified, and cannot be used otherwise. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .

          • (string) --
        • UserData (string) --

          The user data available to the instances.

        • InstanceType (string) --

          The instance type for the instances.

        • KernelId (string) --

          The ID of the kernel associated with the AMI.

        • RamdiskId (string) --

          The ID of the RAM disk associated with the AMI.

        • BlockDeviceMappings (list) --

          A block device mapping, which specifies the block devices for the instance.

          • (dict) --

            Describes a block device mapping.

            • VirtualName (string) --

              The name of the virtual device, ephemeral0 to ephemeral3 .

            • DeviceName (string) --

              The device name exposed to the EC2 instance (for example, /dev/sdh or xvdh ).

            • Ebs (dict) --

              The information about the Amazon EBS volume.

              • SnapshotId (string) --

                The ID of the snapshot.

              • VolumeSize (integer) --

                The volume size, in gigabytes.

                Valid values: If the volume type is io1 , the minimum size of the volume is 10 GiB. If you specify SnapshotId and VolumeSize , VolumeSize must be equal to or larger than the size of the snapshot.

                Default: If you create a volume from a snapshot and you don't specify a volume size, the default is the size of the snapshot.

                Required: Required when the volume type is io1 .

              • VolumeType (string) --

                The volume type.

                Valid values: standard | io1 | gp2

                Default: standard

              • DeleteOnTermination (boolean) --

                Indicates whether to delete the volume on instance termination.

                Default: true

              • Iops (integer) --

                For Provisioned IOPS (SSD) volumes only. The number of I/O operations per second (IOPS) to provision for the volume.

                Valid values: Range is 100 to 4000.

                Default: None

            • NoDevice (boolean) --

              Suppresses a device mapping.

              If this parameter is true for the root device, the instance might fail the EC2 health check. Auto Scaling launches a replacement instance if the instance fails the health check.

        • InstanceMonitoring (dict) --

          Controls whether instances in this group are launched with detailed monitoring.

          • Enabled (boolean) --

            If True , instance monitoring is enabled.

        • SpotPrice (string) --

          The price to bid when launching Spot Instances.

        • IamInstanceProfile (string) --

          The name or Amazon Resource Name (ARN) of the instance profile associated with the IAM role for the instance.

        • CreatedTime (datetime) --

          The creation date and time for the launch configuration.

        • EbsOptimized (boolean) --

          Controls whether the instance is optimized for EBS I/O (true ) or not (false ).

        • AssociatePublicIpAddress (boolean) --

          Specifies whether the instances are associated with a public IP address (true ) or not (false ).

        • PlacementTenancy (string) --

          The tenancy of the instance, either default or dedicated . An instance with dedicated tenancy runs in an isolated, single-tenant hardware and can only be launched into a VPC.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_lifecycle_hook_types()

Describes the available types of lifecycle hooks.

Request Syntax

response = client.describe_lifecycle_hook_types()
Return type
dict
Returns
Response Syntax
{
    'LifecycleHookTypes': [
        'string',
    ]
}

Response Structure

  • (dict) --
    • LifecycleHookTypes (list) --

      One or more of the following notification types:

      • autoscaling:EC2_INSTANCE_LAUNCHING
      • autoscaling:EC2_INSTANCE_TERMINATING
      • (string) --
describe_lifecycle_hooks(**kwargs)

Describes the lifecycle hooks for the specified Auto Scaling group.

Request Syntax

response = client.describe_lifecycle_hooks(
    AutoScalingGroupName='string',
    LifecycleHookNames=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group.

  • LifecycleHookNames (list) --

    The names of one or more lifecycle hooks.

    • (string) --
Return type

dict

Returns

Response Syntax

{
    'LifecycleHooks': [
        {
            'LifecycleHookName': 'string',
            'AutoScalingGroupName': 'string',
            'LifecycleTransition': 'string',
            'NotificationTargetARN': 'string',
            'RoleARN': 'string',
            'NotificationMetadata': 'string',
            'HeartbeatTimeout': 123,
            'GlobalTimeout': 123,
            'DefaultResult': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • LifecycleHooks (list) --

      The lifecycle hooks for the specified group.

      • (dict) --

        Describes a lifecycle hook, which tells Auto Scaling that you want to perform an action when an instance launches or terminates. When you have a lifecycle hook in place, the Auto Scaling group will either:

        • Pause the instance after it launches, but before it is put into service
        • Pause the instance as it terminates, but before it is fully terminated

        For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto Scaling Developer Guide .

        • LifecycleHookName (string) --

          The name of the lifecycle hook.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group for the lifecycle hook.

        • LifecycleTransition (string) --

          The state of the EC2 instance to which you want to attach the lifecycle hook. For a list of lifecycle hook types, see DescribeLifecycleHookTypes .

        • NotificationTargetARN (string) --

          The ARN of the notification target that Auto Scaling uses to notify you when an instance is in the transition state for the lifecycle hook. This ARN target can be either an SQS queue or an SNS topic. The notification message sent to the target includes the following:

          • Lifecycle action token
          • User account ID
          • Name of the Auto Scaling group
          • Lifecycle hook name
          • EC2 instance ID
          • Lifecycle transition
          • Notification metadata
        • RoleARN (string) --

          The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.

        • NotificationMetadata (string) --

          Additional information that you want to include any time Auto Scaling sends a message to the notification target.

        • HeartbeatTimeout (integer) --

          The amount of time that can elapse before the lifecycle hook times out. When the lifecycle hook times out, Auto Scaling performs the action defined in the DefaultResult parameter. You can prevent the lifecycle hook from timing out by calling RecordLifecycleActionHeartbeat .

        • GlobalTimeout (integer) --

          The maximum length of time an instance can remain in a Pending:Wait or Terminating:Wait state. Currently, the maximum is set to 48 hours.

        • DefaultResult (string) --

          Defines the action the Auto Scaling group should take when the lifecycle hook timeout elapses or if an unexpected failure occurs. The valid values are CONTINUE and ABANDON . The default value is CONTINUE .

describe_load_balancers(**kwargs)

Describes the load balancers for the specified Auto Scaling group.

Request Syntax

response = client.describe_load_balancers(
    AutoScalingGroupName='string',
    NextToken='string',
    MaxRecords=123
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group.

  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call.
Return type

dict

Returns

Response Syntax

{
    'LoadBalancers': [
        {
            'LoadBalancerName': 'string',
            'State': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • LoadBalancers (list) --

      The load balancers.

      • (dict) --

        Describes the state of a load balancer.

        • LoadBalancerName (string) --

          The name of the load balancer.

        • State (string) --

          The state of the load balancer.

          • Adding - The instances in the group are being registered with the load balancer.
          • Added - All instances in the group are registered with the load balancer.
          • InService - At least one instance in the group passed an ELB health check.
          • Removing - The instances are being deregistered from the load balancer. If connection draining is enabled, Elastic Load Balancing waits for in-flight requests to complete before deregistering the instances.
    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_metric_collection_types()

Describes the available CloudWatch metrics for Auto Scaling.

Note that the GroupStandbyInstances metric is not returned by default. You must explicitly request this metric when calling EnableMetricsCollection .

Request Syntax

response = client.describe_metric_collection_types()
Return type
dict
Returns
Response Syntax
{
    'Metrics': [
        {
            'Metric': 'string'
        },
    ],
    'Granularities': [
        {
            'Granularity': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Metrics (list) --

      One or more metrics.

      • (dict) --

        Describes a metric.

        • Metric (string) --

          The metric.

          • GroupMinSize
          • GroupMaxSize
          • GroupDesiredCapacity
          • GroupInServiceInstances
          • GroupPendingInstances
          • GroupStandbyInstances
          • GroupTerminatingInstances
          • GroupTotalInstances
    • Granularities (list) --

      The granularities for the metrics.

      • (dict) --

        Describes a granularity of a metric.

        • Granularity (string) --

          The granularity. The only valid value is 1Minute .

describe_notification_configurations(**kwargs)

Describes the notification actions associated with the specified Auto Scaling group.

Request Syntax

response = client.describe_notification_configurations(
    AutoScalingGroupNames=[
        'string',
    ],
    NextToken='string',
    MaxRecords=123
)
Parameters
  • AutoScalingGroupNames (list) --

    The name of the group.

    • (string) --
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call.
Return type

dict

Returns

Response Syntax

{
    'NotificationConfigurations': [
        {
            'AutoScalingGroupName': 'string',
            'TopicARN': 'string',
            'NotificationType': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • NotificationConfigurations (list) --

      The notification configurations.

      • (dict) --

        Describes a notification.

        • AutoScalingGroupName (string) --

          The name of the group.

        • TopicARN (string) --

          The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.

        • NotificationType (string) --

          The types of events for an action to start.

          • autoscaling:EC2_INSTANCE_LAUNCH
          • autoscaling:EC2_INSTANCE_LAUNCH_ERROR
          • autoscaling:EC2_INSTANCE_TERMINATE
          • autoscaling:EC2_INSTANCE_TERMINATE_ERROR
          • autoscaling:TEST_NOTIFICATION
    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_policies(**kwargs)

Describes the policies for the specified Auto Scaling group.

Request Syntax

response = client.describe_policies(
    AutoScalingGroupName='string',
    PolicyNames=[
        'string',
    ],
    PolicyTypes=[
        'string',
    ],
    NextToken='string',
    MaxRecords=123
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • PolicyNames (list) --

    One or more policy names or policy ARNs to be described. If you omit this list, all policy names are described. If an group name is provided, the results are limited to that group. This list is limited to 50 items. If you specify an unknown policy name, it is ignored with no error.

    • (string) --
  • PolicyTypes (list) --

    One or more policy types. Valid values are SimpleScaling and StepScaling .

    • (string) --
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to be returned with each call.
Return type

dict

Returns

Response Syntax

{
    'ScalingPolicies': [
        {
            'AutoScalingGroupName': 'string',
            'PolicyName': 'string',
            'PolicyARN': 'string',
            'PolicyType': 'string',
            'AdjustmentType': 'string',
            'MinAdjustmentStep': 123,
            'MinAdjustmentMagnitude': 123,
            'ScalingAdjustment': 123,
            'Cooldown': 123,
            'StepAdjustments': [
                {
                    'MetricIntervalLowerBound': 123.0,
                    'MetricIntervalUpperBound': 123.0,
                    'ScalingAdjustment': 123
                },
            ],
            'MetricAggregationType': 'string',
            'EstimatedInstanceWarmup': 123,
            'Alarms': [
                {
                    'AlarmName': 'string',
                    'AlarmARN': 'string'
                },
            ]
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • ScalingPolicies (list) --

      The scaling policies.

      • (dict) --

        Describes a scaling policy.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group associated with this scaling policy.

        • PolicyName (string) --

          The name of the scaling policy.

        • PolicyARN (string) --

          The Amazon Resource Name (ARN) of the policy.

        • PolicyType (string) --

          The policy type. Valid values are SimpleScaling and StepScaling .

        • AdjustmentType (string) --

          The adjustment type, which specifies how ScalingAdjustment is interpreted. Valid values are ChangeInCapacity , ExactCapacity , and PercentChangeInCapacity .

        • MinAdjustmentStep (integer) --

          Available for backward compatibility. Use MinAdjustmentMagnitude instead.

        • MinAdjustmentMagnitude (integer) --

          The minimum number of instances to scale. If the value of AdjustmentType is PercentChangeInCapacity , the scaling policy changes the DesiredCapacity of the Auto Scaling group by at least this many instances. Otherwise, the error is ValidationError .

        • ScalingAdjustment (integer) --

          The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

        • Cooldown (integer) --

          The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start.

        • StepAdjustments (list) --

          A set of adjustments that enable you to scale based on the size of the alarm breach.

          • (dict) --

            Describes an adjustment based on the difference between the value of the aggregated CloudWatch metric and the breach threshold that you've defined for the alarm.

            For the following examples, suppose that you have an alarm with a breach threshold of 50:

            • If you want the adjustment to be triggered when the metric is greater than or equal to 50 and less than 60, specify a lower bound of 0 and an upper bound of 10.
            • If you want the adjustment to be triggered when the metric is greater than 40 and less than or equal to 50, specify a lower bound of -10 and an upper bound of 0.

            There are a few rules for the step adjustments for your step policy:

            • The ranges of your step adjustments can't overlap or have a gap.
            • At most one step adjustment can have a null lower bound. If one step adjustment has a negative lower bound, then there must be a step adjustment with a null lower bound.
            • At most one step adjustment can have a null upper bound. If one step adjustment has a positive upper bound, then there must be a step adjustment with a null upper bound.
            • The upper and lower bound can't be null in the same step adjustment.
            • MetricIntervalLowerBound (float) --

              The lower bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the lower bound is inclusive (the metric must be greater than or equal to the threshold plus the lower bound). Otherwise, it is exclusive (the metric must be greater than the threshold plus the lower bound). A null value indicates negative infinity.

            • MetricIntervalUpperBound (float) --

              The upper bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the upper bound is exclusive (the metric must be less than the threshold plus the upper bound). Otherwise, it is inclusive (the metric must be less than or equal to the threshold plus the upper bound). A null value indicates positive infinity.

              The upper bound must be greater than the lower bound.

            • ScalingAdjustment (integer) --

              The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

        • MetricAggregationType (string) --

          The aggregation type for the CloudWatch metrics. Valid values are Minimum , Maximum , and Average .

        • EstimatedInstanceWarmup (integer) --

          The estimated time, in seconds, until a newly launched instance can contribute to the CloudWatch metrics.

        • Alarms (list) --

          The CloudWatch alarms related to the policy.

          • (dict) --

            Describes an alarm.

            • AlarmName (string) --

              The name of the alarm.

            • AlarmARN (string) --

              The Amazon Resource Name (ARN) of the alarm.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_scaling_activities(**kwargs)

Describes one or more scaling activities for the specified Auto Scaling group. If you omit the ActivityIds , the call returns all activities from the past six weeks. Activities are sorted by the start time. Activities still in progress appear first on the list.

Request Syntax

response = client.describe_scaling_activities(
    ActivityIds=[
        'string',
    ],
    AutoScalingGroupName='string',
    MaxRecords=123,
    NextToken='string'
)
Parameters
  • ActivityIds (list) --

    The activity IDs of the desired scaling activities. If this list is omitted, all activities are described. If the AutoScalingGroupName parameter is provided, the results are limited to that group. The list of requested activities cannot contain more than 50 items. If unknown activities are requested, they are ignored with no error.

    • (string) --
  • AutoScalingGroupName (string) -- The name of the group.
  • MaxRecords (integer) -- The maximum number of items to return with this call.
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
Return type

dict

Returns

Response Syntax

{
    'Activities': [
        {
            'ActivityId': 'string',
            'AutoScalingGroupName': 'string',
            'Description': 'string',
            'Cause': 'string',
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
            'StatusMessage': 'string',
            'Progress': 123,
            'Details': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Activities (list) --

      The scaling activities.

      • (dict) --

        Describes scaling activity, which is a long-running process that represents a change to your Auto Scaling group, such as changing its size or replacing an instance.

        • ActivityId (string) --

          The ID of the activity.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group.

        • Description (string) --

          A friendly, more verbose description of the activity.

        • Cause (string) --

          The reason the activity began.

        • StartTime (datetime) --

          The start time of the activity.

        • EndTime (datetime) --

          The end time of the activity.

        • StatusCode (string) --

          The current status of the activity.

        • StatusMessage (string) --

          A friendly, more verbose description of the activity status.

        • Progress (integer) --

          A value between 0 and 100 that indicates the progress of the activity.

        • Details (string) --

          The details about the activity.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_scaling_process_types()

Describes the scaling process types for use with ResumeProcesses and SuspendProcesses .

Request Syntax

response = client.describe_scaling_process_types()
Return type
dict
Returns
Response Syntax
{
    'Processes': [
        {
            'ProcessName': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Processes (list) --

      The names of the process types.

      • (dict) --

        Describes a process type.

        For more information, see Auto Scaling Processes in the Auto Scaling Developer Guide .

        • ProcessName (string) --

          The name of the process.

          • Launch
          • Terminate
          • AddToLoadBalancer
          • AlarmNotification
          • AZRebalance
          • HealthCheck
          • ReplaceUnhealthy
          • ScheduledActions
describe_scheduled_actions(**kwargs)

Describes the actions scheduled for your Auto Scaling group that haven't run. To describe the actions that have already run, use DescribeScalingActivities .

Request Syntax

response = client.describe_scheduled_actions(
    AutoScalingGroupName='string',
    ScheduledActionNames=[
        'string',
    ],
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    NextToken='string',
    MaxRecords=123
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • ScheduledActionNames (list) --

    Describes one or more scheduled actions. If you omit this list, the call describes all scheduled actions. If you specify an unknown scheduled action it is ignored with no error.

    You can describe up to a maximum of 50 instances with a single call. If there are more items to return, the call returns a token. To get the next set of items, repeat the call with the returned token in the NextToken parameter.

    • (string) --
  • StartTime (datetime) -- The earliest scheduled start time to return. If scheduled action names are provided, this parameter is ignored.
  • EndTime (datetime) -- The latest scheduled start time to return. If scheduled action names are provided, this parameter is ignored.
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call.
Return type

dict

Returns

Response Syntax

{
    'ScheduledUpdateGroupActions': [
        {
            'AutoScalingGroupName': 'string',
            'ScheduledActionName': 'string',
            'ScheduledActionARN': 'string',
            'Time': datetime(2015, 1, 1),
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'Recurrence': 'string',
            'MinSize': 123,
            'MaxSize': 123,
            'DesiredCapacity': 123
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • ScheduledUpdateGroupActions (list) --

      The scheduled actions.

      • (dict) --

        Describes a scheduled update to an Auto Scaling group.

        • AutoScalingGroupName (string) --

          The name of the group.

        • ScheduledActionName (string) --

          The name of the scheduled action.

        • ScheduledActionARN (string) --

          The Amazon Resource Name (ARN) of the scheduled action.

        • Time (datetime) --

          This parameter is deprecated; use StartTime instead.

        • StartTime (datetime) --

          The date and time that the action is scheduled to begin. This date and time can be up to one month in the future.

          When StartTime and EndTime are specified with Recurrence , they form the boundaries of when the recurring action will start and stop.

        • EndTime (datetime) --

          The date and time that the action is scheduled to end. This date and time can be up to one month in the future.

        • Recurrence (string) --

          The recurring schedule for the action.

        • MinSize (integer) --

          The minimum size of the group.

        • MaxSize (integer) --

          The maximum size of the group.

        • DesiredCapacity (integer) --

          The number of instances you prefer to maintain in the group.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_tags(**kwargs)

Describes the specified tags.

You can use filters to limit the results. For example, you can query for the tags for a specific Auto Scaling group. You can specify multiple values for a filter. A tag must match at least one of the specified values for it to be included in the results.

You can also specify multiple filters. The result includes information for a particular tag only if it matches all the filters. If there's no match, no special message is returned.

Request Syntax

response = client.describe_tags(
    Filters=[
        {
            'Name': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    NextToken='string',
    MaxRecords=123
)
Parameters
  • Filters (list) --

    A filter used to scope the tags to return.

    • (dict) --

      Describes a filter.

      • Name (string) --

        The name of the filter. The valid values are: "auto-scaling-group" , "key" , "value" , and "propagate-at-launch" .

      • Values (list) --

        The value of the filter.

        • (string) --
  • NextToken (string) -- The token for the next set of items to return. (You received this token from a previous call.)
  • MaxRecords (integer) -- The maximum number of items to return with this call.
Return type

dict

Returns

Response Syntax

{
    'Tags': [
        {
            'ResourceId': 'string',
            'ResourceType': 'string',
            'Key': 'string',
            'Value': 'string',
            'PropagateAtLaunch': True|False
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Tags (list) --

      The tags.

      • (dict) --

        Describes a tag for an Auto Scaling group.

        • ResourceId (string) --

          The name of the group.

        • ResourceType (string) --

          The type of resource. The only supported value is auto-scaling-group .

        • Key (string) --

          The tag key.

        • Value (string) --

          The tag value.

        • PropagateAtLaunch (boolean) --

          Determines whether the tag is added to new instances as they are launched in the group.

    • NextToken (string) --

      The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

describe_termination_policy_types()

Describes the termination policies supported by Auto Scaling.

Request Syntax

response = client.describe_termination_policy_types()
Return type
dict
Returns
Response Syntax
{
    'TerminationPolicyTypes': [
        'string',
    ]
}

Response Structure

  • (dict) --
    • TerminationPolicyTypes (list) --

      The termination policies supported by Auto Scaling (OldestInstance , OldestLaunchConfiguration , NewestInstance , ClosestToNextInstanceHour , and Default ).

      • (string) --
detach_instances(**kwargs)

Removes one or more instances from the specified Auto Scaling group. After the instances are detached, you can manage them independently from the rest of the Auto Scaling group.

For more information, see Detach EC2 Instances from Your Auto Scaling Group in the Auto Scaling Developer Guide .

Request Syntax

response = client.detach_instances(
    InstanceIds=[
        'string',
    ],
    AutoScalingGroupName='string',
    ShouldDecrementDesiredCapacity=True|False
)
Parameters
  • InstanceIds (list) --

    One or more instance IDs.

    • (string) --
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the group.

  • ShouldDecrementDesiredCapacity (boolean) --

    [REQUIRED]

    If True , the Auto Scaling group decrements the desired capacity value by the number of instances detached.

Return type

dict

Returns

Response Syntax

{
    'Activities': [
        {
            'ActivityId': 'string',
            'AutoScalingGroupName': 'string',
            'Description': 'string',
            'Cause': 'string',
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
            'StatusMessage': 'string',
            'Progress': 123,
            'Details': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • Activities (list) --

      The activities related to detaching the instances from the Auto Scaling group.

      • (dict) --

        Describes scaling activity, which is a long-running process that represents a change to your Auto Scaling group, such as changing its size or replacing an instance.

        • ActivityId (string) --

          The ID of the activity.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group.

        • Description (string) --

          A friendly, more verbose description of the activity.

        • Cause (string) --

          The reason the activity began.

        • StartTime (datetime) --

          The start time of the activity.

        • EndTime (datetime) --

          The end time of the activity.

        • StatusCode (string) --

          The current status of the activity.

        • StatusMessage (string) --

          A friendly, more verbose description of the activity status.

        • Progress (integer) --

          A value between 0 and 100 that indicates the progress of the activity.

        • Details (string) --

          The details about the activity.

detach_load_balancers(**kwargs)

Removes one or more load balancers from the specified Auto Scaling group.

When you detach a load balancer, it enters the Removing state while deregistering the instances in the group. When all instances are deregistered, then you can no longer describe the load balancer using DescribeLoadBalancers . Note that the instances remain running.

Request Syntax

response = client.detach_load_balancers(
    AutoScalingGroupName='string',
    LoadBalancerNames=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • LoadBalancerNames (list) --

    One or more load balancer names.

    • (string) --
Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

disable_metrics_collection(**kwargs)

Disables monitoring of the specified metrics for the specified Auto Scaling group.

Request Syntax

response = client.disable_metrics_collection(
    AutoScalingGroupName='string',
    Metrics=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or Amazon Resource Name (ARN) of the group.

  • Metrics (list) --

    One or more metrics. If you omit this parameter, all metrics are disabled.

    • GroupMinSize
    • GroupMaxSize
    • GroupDesiredCapacity
    • GroupInServiceInstances
    • GroupPendingInstances
    • GroupStandbyInstances
    • GroupTerminatingInstances
    • GroupTotalInstances
    • (string) --
Returns

None

enable_metrics_collection(**kwargs)

Enables monitoring of the specified metrics for the specified Auto Scaling group.

You can only enable metrics collection if InstanceMonitoring in the launch configuration for the group is set to True .

Request Syntax

response = client.enable_metrics_collection(
    AutoScalingGroupName='string',
    Metrics=[
        'string',
    ],
    Granularity='string'
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or ARN of the Auto Scaling group.

  • Metrics (list) --

    One or more metrics. If you omit this parameter, all metrics are enabled.

    • GroupMinSize
    • GroupMaxSize
    • GroupDesiredCapacity
    • GroupInServiceInstances
    • GroupPendingInstances
    • GroupStandbyInstances
    • GroupTerminatingInstances
    • GroupTotalInstances

    Note that the GroupStandbyInstances metric is not enabled by default. You must explicitly request this metric.

    • (string) --
  • Granularity (string) --

    [REQUIRED]

    The granularity to associate with the metrics to collect. The only valid value is 1Minute .

Returns

None

enter_standby(**kwargs)

Moves the specified instances into Standby mode.

For more information, see Auto Scaling InService State in the Auto Scaling Developer Guide .

Request Syntax

response = client.enter_standby(
    InstanceIds=[
        'string',
    ],
    AutoScalingGroupName='string',
    ShouldDecrementDesiredCapacity=True|False
)
Parameters
  • InstanceIds (list) --

    One or more instances to move into Standby mode. You must specify at least one instance ID.

    • (string) --
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

  • ShouldDecrementDesiredCapacity (boolean) --

    [REQUIRED]

    Specifies whether the instances moved to Standby mode count as part of the Auto Scaling group's desired capacity. If set, the desired capacity for the Auto Scaling group decrements by the number of instances moved to Standby mode.

Return type

dict

Returns

Response Syntax

{
    'Activities': [
        {
            'ActivityId': 'string',
            'AutoScalingGroupName': 'string',
            'Description': 'string',
            'Cause': 'string',
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
            'StatusMessage': 'string',
            'Progress': 123,
            'Details': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • Activities (list) --

      The activities related to moving instances into Standby mode.

      • (dict) --

        Describes scaling activity, which is a long-running process that represents a change to your Auto Scaling group, such as changing its size or replacing an instance.

        • ActivityId (string) --

          The ID of the activity.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group.

        • Description (string) --

          A friendly, more verbose description of the activity.

        • Cause (string) --

          The reason the activity began.

        • StartTime (datetime) --

          The start time of the activity.

        • EndTime (datetime) --

          The end time of the activity.

        • StatusCode (string) --

          The current status of the activity.

        • StatusMessage (string) --

          A friendly, more verbose description of the activity status.

        • Progress (integer) --

          A value between 0 and 100 that indicates the progress of the activity.

        • Details (string) --

          The details about the activity.

execute_policy(**kwargs)

Executes the specified policy.

Request Syntax

response = client.execute_policy(
    AutoScalingGroupName='string',
    PolicyName='string',
    HonorCooldown=True|False,
    MetricValue=123.0,
    BreachThreshold=123.0
)
Parameters
  • AutoScalingGroupName (string) -- The name or Amazon Resource Name (ARN) of the Auto Scaling group.
  • PolicyName (string) --

    [REQUIRED]

    The name or ARN of the policy.

  • HonorCooldown (boolean) --

    If this parameter is true, Auto Scaling waits for the cooldown period to complete before executing the policy. Otherwise, Auto Scaling executes the policy without waiting for the cooldown period to complete.

    This parameter is not supported if the policy type is StepScaling .

    For more information, see Understanding Auto Scaling Cooldowns in the Auto Scaling Developer Guide .

  • MetricValue (float) --

    The metric value to compare to BreachThreshold . This enables you to execute a policy of type StepScaling and determine which step adjustment to use. For example, if the breach threshold is 50 and you want to use a step adjustment with a lower bound of 0 and an upper bound of 10, you can set the metric value to 59.

    If you specify a metric value that doesn't correspond to a step adjustment for the policy, the call returns an error.

    This parameter is required if the policy type is StepScaling and not supported otherwise.

  • BreachThreshold (float) --

    The breach threshold for the alarm.

    This parameter is required if the policy type is StepScaling and not supported otherwise.

Returns

None

exit_standby(**kwargs)

Moves the specified instances out of Standby mode.

For more information, see Auto Scaling InService State in the Auto Scaling Developer Guide .

Request Syntax

response = client.exit_standby(
    InstanceIds=[
        'string',
    ],
    AutoScalingGroupName='string'
)
Parameters
  • InstanceIds (list) --

    One or more instance IDs. You must specify at least one instance ID.

    • (string) --
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

Return type

dict

Returns

Response Syntax

{
    'Activities': [
        {
            'ActivityId': 'string',
            'AutoScalingGroupName': 'string',
            'Description': 'string',
            'Cause': 'string',
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
            'StatusMessage': 'string',
            'Progress': 123,
            'Details': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • Activities (list) --

      The activities related to moving instances out of Standby mode.

      • (dict) --

        Describes scaling activity, which is a long-running process that represents a change to your Auto Scaling group, such as changing its size or replacing an instance.

        • ActivityId (string) --

          The ID of the activity.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group.

        • Description (string) --

          A friendly, more verbose description of the activity.

        • Cause (string) --

          The reason the activity began.

        • StartTime (datetime) --

          The start time of the activity.

        • EndTime (datetime) --

          The end time of the activity.

        • StatusCode (string) --

          The current status of the activity.

        • StatusMessage (string) --

          A friendly, more verbose description of the activity status.

        • Progress (integer) --

          A value between 0 and 100 that indicates the progress of the activity.

        • Details (string) --

          The details about the activity.

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters
  • ClientMethod (string) -- The client method to presign for
  • Params (dict) -- The parameters normally passed to ClientMethod.
  • ExpiresIn (int) -- The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)
  • HttpMethod (string) -- The http method to use on the generated url. By default, the http method is whatever is used in the method's model.
Returns

The presigned url

get_paginator(operation_name)

Create a paginator for an operation.

Parameters
operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Raises OperationNotPageableError
Raised if the operation is not pageable. You can use the client.can_paginate method to check if an operation is pageable.
Return type
L{botocore.paginate.Paginator}
Returns
A paginator object.
get_waiter(waiter_name)
put_lifecycle_hook(**kwargs)

Creates or updates a lifecycle hook for the specified Auto Scaling Group.

A lifecycle hook tells Auto Scaling that you want to perform an action on an instance that is not actively in service; for example, either when the instance launches or before the instance terminates.

This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:

  • Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
  • Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the designated SQS queue or SNS topic.
  • Create the lifecycle hook. You can create a hook that acts when instances launch or when instances terminate.
  • If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
  • Complete the lifecycle action.

For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto Scaling Developer Guide .

If you exceed your maximum limit of lifecycle hooks, which by default is 50 per region, the call fails. For information about updating this limit, see AWS Service Limits in the Amazon Web Services General Reference .

Request Syntax

response = client.put_lifecycle_hook(
    LifecycleHookName='string',
    AutoScalingGroupName='string',
    LifecycleTransition='string',
    RoleARN='string',
    NotificationTargetARN='string',
    NotificationMetadata='string',
    HeartbeatTimeout=123,
    DefaultResult='string'
)
Parameters
  • LifecycleHookName (string) --

    [REQUIRED]

    The name of the lifecycle hook.

  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group to which you want to assign the lifecycle hook.

  • LifecycleTransition (string) --

    The instance state to which you want to attach the lifecycle hook. For a list of lifecycle hook types, see DescribeLifecycleHookTypes .

    This parameter is required for new lifecycle hooks, but optional when updating existing hooks.

  • RoleARN (string) --

    The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.

    This parameter is required for new lifecycle hooks, but optional when updating existing hooks.

  • NotificationTargetARN (string) --

    The ARN of the notification target that Auto Scaling will use to notify you when an instance is in the transition state for the lifecycle hook. This ARN target can be either an SQS queue or an SNS topic.

    This parameter is required for new lifecycle hooks, but optional when updating existing hooks.

    The notification message sent to the target will include:

    • LifecycleActionToken . The Lifecycle action token.
    • AccountId . The user account ID.
    • AutoScalingGroupName . The name of the Auto Scaling group.
    • LifecycleHookName . The lifecycle hook name.
    • EC2InstanceId . The EC2 instance ID.
    • LifecycleTransition . The lifecycle transition.
    • NotificationMetadata . The notification metadata.

    This operation uses the JSON format when sending notifications to an Amazon SQS queue, and an email key/value pair format when sending notifications to an Amazon SNS topic.

    When you call this operation, a test message is sent to the notification target. This test message contains an additional key/value pair: Event:autoscaling:TEST_NOTIFICATION .

  • NotificationMetadata (string) -- Contains additional information that you want to include any time Auto Scaling sends a message to the notification target.
  • HeartbeatTimeout (integer) -- Defines the amount of time, in seconds, that can elapse before the lifecycle hook times out. When the lifecycle hook times out, Auto Scaling performs the action defined in the DefaultResult parameter. You can prevent the lifecycle hook from timing out by calling RecordLifecycleActionHeartbeat . The default value for this parameter is 3600 seconds (1 hour).
  • DefaultResult (string) -- Defines the action the Auto Scaling group should take when the lifecycle hook timeout elapses or if an unexpected failure occurs. The value for this parameter can be either CONTINUE or ABANDON . The default value for this parameter is ABANDON .
Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

put_notification_configuration(**kwargs)

Configures an Auto Scaling group to send notifications when specified events take place. Subscribers to this topic can have messages for events delivered to an endpoint such as a web server or email address.

For more information see Getting Notifications When Your Auto Scaling Group Changes in the Auto Scaling Developer Guide .

This configuration overwrites an existing configuration.

Request Syntax

response = client.put_notification_configuration(
    AutoScalingGroupName='string',
    TopicARN='string',
    NotificationTypes=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

  • TopicARN (string) --

    [REQUIRED]

    The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.

  • NotificationTypes (list) --

    [REQUIRED]

    The type of event that will cause the notification to be sent. For details about notification types supported by Auto Scaling, see DescribeAutoScalingNotificationTypes .

    • (string) --
Returns

None

put_scaling_policy(**kwargs)

Creates or updates a policy for an Auto Scaling group. To update an existing policy, use the existing policy name and set the parameters you want to change. Any existing parameter not changed in an update to an existing policy is not changed in this update request.

If you exceed your maximum limit of step adjustments, which by default is 20 per region, the call fails. For information about updating this limit, see AWS Service Limits in the Amazon Web Services General Reference .

Request Syntax

response = client.put_scaling_policy(
    AutoScalingGroupName='string',
    PolicyName='string',
    PolicyType='string',
    AdjustmentType='string',
    MinAdjustmentStep=123,
    MinAdjustmentMagnitude=123,
    ScalingAdjustment=123,
    Cooldown=123,
    MetricAggregationType='string',
    StepAdjustments=[
        {
            'MetricIntervalLowerBound': 123.0,
            'MetricIntervalUpperBound': 123.0,
            'ScalingAdjustment': 123
        },
    ],
    EstimatedInstanceWarmup=123
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or ARN of the group.

  • PolicyName (string) --

    [REQUIRED]

    The name of the policy.

  • PolicyType (string) -- The policy type. Valid values are SimpleScaling and StepScaling . If the policy type is null, the value is treated as SimpleScaling .
  • AdjustmentType (string) --

    [REQUIRED]

    The adjustment type. Valid values are ChangeInCapacity , ExactCapacity , and PercentChangeInCapacity .

    For more information, see Dynamic Scaling in the Auto Scaling Developer Guide .

  • MinAdjustmentStep (integer) -- Available for backward compatibility. Use MinAdjustmentMagnitude instead.
  • MinAdjustmentMagnitude (integer) -- The minimum number of instances to scale. If the value of AdjustmentType is PercentChangeInCapacity , the scaling policy changes the DesiredCapacity of the Auto Scaling group by at least this many instances. Otherwise, the error is ValidationError .
  • ScalingAdjustment (integer) --

    The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

    This parameter is required if the policy type is SimpleScaling and not supported otherwise.

  • Cooldown (integer) --

    The amount of time, in seconds, after a scaling activity completes and before the next scaling activity can start. If this parameter is not specified, the default cooldown period for the group applies.

    This parameter is not supported unless the policy type is SimpleScaling .

    For more information, see Understanding Auto Scaling Cooldowns in the Auto Scaling Developer Guide .

  • MetricAggregationType (string) --

    The aggregation type for the CloudWatch metrics. Valid values are Minimum , Maximum , and Average . If the aggregation type is null, the value is treated as Average .

    This parameter is not supported if the policy type is SimpleScaling .

  • StepAdjustments (list) --

    A set of adjustments that enable you to scale based on the size of the alarm breach.

    This parameter is required if the policy type is StepScaling and not supported otherwise.

    • (dict) --

      Describes an adjustment based on the difference between the value of the aggregated CloudWatch metric and the breach threshold that you've defined for the alarm.

      For the following examples, suppose that you have an alarm with a breach threshold of 50:

      • If you want the adjustment to be triggered when the metric is greater than or equal to 50 and less than 60, specify a lower bound of 0 and an upper bound of 10.
      • If you want the adjustment to be triggered when the metric is greater than 40 and less than or equal to 50, specify a lower bound of -10 and an upper bound of 0.

      There are a few rules for the step adjustments for your step policy:

      • The ranges of your step adjustments can't overlap or have a gap.
      • At most one step adjustment can have a null lower bound. If one step adjustment has a negative lower bound, then there must be a step adjustment with a null lower bound.
      • At most one step adjustment can have a null upper bound. If one step adjustment has a positive upper bound, then there must be a step adjustment with a null upper bound.
      • The upper and lower bound can't be null in the same step adjustment.
      • MetricIntervalLowerBound (float) --

        The lower bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the lower bound is inclusive (the metric must be greater than or equal to the threshold plus the lower bound). Otherwise, it is exclusive (the metric must be greater than the threshold plus the lower bound). A null value indicates negative infinity.

      • MetricIntervalUpperBound (float) --

        The upper bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the upper bound is exclusive (the metric must be less than the threshold plus the upper bound). Otherwise, it is inclusive (the metric must be less than or equal to the threshold plus the upper bound). A null value indicates positive infinity.

        The upper bound must be greater than the lower bound.

      • ScalingAdjustment (integer) -- [REQUIRED]

        The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

  • EstimatedInstanceWarmup (integer) --

    The estimated time, in seconds, until a newly launched instance can contribute to the CloudWatch metrics. The default is to use the value specified for the default cooldown period for the group.

    This parameter is not supported if the policy type is SimpleScaling .

Return type

dict

Returns

Response Syntax

{
    'PolicyARN': 'string'
}

Response Structure

  • (dict) --

    • PolicyARN (string) --

      The Amazon Resource Name (ARN) of the policy.

put_scheduled_update_group_action(**kwargs)

Creates or updates a scheduled scaling action for an Auto Scaling group. When updating a scheduled scaling action, if you leave a parameter unspecified, the corresponding value remains unchanged in the affected Auto Scaling group.

For more information, see Scheduled Scaling in the Auto Scaling Developer Guide .

Request Syntax

response = client.put_scheduled_update_group_action(
    AutoScalingGroupName='string',
    ScheduledActionName='string',
    Time=datetime(2015, 1, 1),
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    Recurrence='string',
    MinSize=123,
    MaxSize=123,
    DesiredCapacity=123
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or Amazon Resource Name (ARN) of the Auto Scaling group.

  • ScheduledActionName (string) --

    [REQUIRED]

    The name of this scaling action.

  • Time (datetime) --

    This parameter is deprecated; use StartTime instead.

    The time for this action to start. If both Time and StartTime are specified, their values must be identical.

  • StartTime (datetime) --

    The time for this action to start, in "YYYY-MM-DDThh:mm:ssZ" format in UTC/GMT only (for example, 2014-06-01T00:00:00Z ).

    If you try to schedule your action in the past, Auto Scaling returns an error message.

    When StartTime and EndTime are specified with Recurrence , they form the boundaries of when the recurring action starts and stops.

  • EndTime (datetime) -- The time for this action to end.
  • Recurrence (string) --

    The time when recurring future actions will start. Start time is specified by the user following the Unix cron syntax format. For more information, see Cron in Wikipedia.

    When StartTime and EndTime are specified with Recurrence , they form the boundaries of when the recurring action will start and stop.

  • MinSize (integer) -- The minimum size for the Auto Scaling group.
  • MaxSize (integer) -- The maximum size for the Auto Scaling group.
  • DesiredCapacity (integer) -- The number of EC2 instances that should be running in the group.
Returns

None

record_lifecycle_action_heartbeat(**kwargs)

Records a heartbeat for the lifecycle action associated with a specific token. This extends the timeout by the length of time defined by the HeartbeatTimeout parameter of PutLifecycleHook .

This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:

  • Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
  • Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the designated SQS queue or SNS topic.
  • Create the lifecycle hook. You can create a hook that acts when instances launch or when instances terminate.
  • If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
  • Complete the lifecycle action.

For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto Scaling Developer Guide .

Request Syntax

response = client.record_lifecycle_action_heartbeat(
    LifecycleHookName='string',
    AutoScalingGroupName='string',
    LifecycleActionToken='string'
)
Parameters
  • LifecycleHookName (string) --

    [REQUIRED]

    The name of the lifecycle hook.

  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group for the hook.

  • LifecycleActionToken (string) --

    [REQUIRED]

    A token that uniquely identifies a specific lifecycle action associated with an instance. Auto Scaling sends this token to the notification target you specified when you created the lifecycle hook.

Return type

dict

Returns

Response Syntax

{}

Response Structure

  • (dict) --

resume_processes(**kwargs)

Resumes the specified suspended Auto Scaling processes for the specified Auto Scaling group. To resume specific processes, use the ScalingProcesses parameter. To resume all processes, omit the ScalingProcesses parameter. For more information, see Suspend and Resume Auto Scaling Processes in the Auto Scaling Developer Guide .

Request Syntax

response = client.resume_processes(
    AutoScalingGroupName='string',
    ScalingProcesses=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or Amazon Resource Name (ARN) of the Auto Scaling group.

  • ScalingProcesses (list) --

    One or more of the following processes:

    • Launch
    • Terminate
    • HealthCheck
    • ReplaceUnhealthy
    • AZRebalance
    • AlarmNotification
    • ScheduledActions
    • AddToLoadBalancer
    • (string) --
Returns

None

set_desired_capacity(**kwargs)

Sets the size of the specified Auto Scaling group.

For more information about desired capacity, see What Is Auto Scaling? in the Auto Scaling Developer Guide .

Request Syntax

response = client.set_desired_capacity(
    AutoScalingGroupName='string',
    DesiredCapacity=123,
    HonorCooldown=True|False
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

  • DesiredCapacity (integer) --

    [REQUIRED]

    The number of EC2 instances that should be running in the Auto Scaling group.

  • HonorCooldown (boolean) -- By default, SetDesiredCapacity overrides any cooldown period associated with the Auto Scaling group. Specify True to make Auto Scaling to wait for the cool-down period associated with the Auto Scaling group to complete before initiating a scaling activity to set your Auto Scaling group to its new capacity.
Returns

None

set_instance_health(**kwargs)

Sets the health status of the specified instance.

For more information, see Health Checks in the Auto Scaling Developer Guide .

Request Syntax

response = client.set_instance_health(
    InstanceId='string',
    HealthStatus='string',
    ShouldRespectGracePeriod=True|False
)
Parameters
  • InstanceId (string) --

    [REQUIRED]

    The ID of the EC2 instance.

  • HealthStatus (string) --

    [REQUIRED]

    The health status of the instance. Set to Healthy if you want the instance to remain in service. Set to Unhealthy if you want the instance to be out of service. Auto Scaling will terminate and replace the unhealthy instance.

  • ShouldRespectGracePeriod (boolean) --

    If the Auto Scaling group of the specified instance has a HealthCheckGracePeriod specified for the group, by default, this call will respect the grace period. Set this to False , if you do not want the call to respect the grace period associated with the group.

    For more information, see the HealthCheckGracePeriod parameter description for CreateAutoScalingGroup .

Returns

None

suspend_processes(**kwargs)

Suspends the specified Auto Scaling processes for the specified Auto Scaling group. To suspend specific processes, use the ScalingProcesses parameter. To suspend all processes, omit the ScalingProcesses parameter.

Note that if you suspend either the Launch or Terminate process types, it can prevent other process types from functioning properly.

To resume processes that have been suspended, use ResumeProcesses .

For more information, see Suspend and Resume Auto Scaling Processes in the Auto Scaling Developer Guide .

Request Syntax

response = client.suspend_processes(
    AutoScalingGroupName='string',
    ScalingProcesses=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name or Amazon Resource Name (ARN) of the Auto Scaling group.

  • ScalingProcesses (list) --

    One or more of the following processes:

    • Launch
    • Terminate
    • HealthCheck
    • ReplaceUnhealthy
    • AZRebalance
    • AlarmNotification
    • ScheduledActions
    • AddToLoadBalancer
    • (string) --
Returns

None

terminate_instance_in_auto_scaling_group(**kwargs)

Terminates the specified instance and optionally adjusts the desired group size.

This call simply makes a termination request. The instances is not terminated immediately.

Request Syntax

response = client.terminate_instance_in_auto_scaling_group(
    InstanceId='string',
    ShouldDecrementDesiredCapacity=True|False
)
Parameters
  • InstanceId (string) --

    [REQUIRED]

    The ID of the EC2 instance.

  • ShouldDecrementDesiredCapacity (boolean) --

    [REQUIRED]

    If true , terminating this instance also decrements the size of the Auto Scaling group.

Return type

dict

Returns

Response Syntax

{
    'Activity': {
        'ActivityId': 'string',
        'AutoScalingGroupName': 'string',
        'Description': 'string',
        'Cause': 'string',
        'StartTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1),
        'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
        'StatusMessage': 'string',
        'Progress': 123,
        'Details': 'string'
    }
}

Response Structure

  • (dict) --

    • Activity (dict) --

      A scaling activity.

      • ActivityId (string) --

        The ID of the activity.

      • AutoScalingGroupName (string) --

        The name of the Auto Scaling group.

      • Description (string) --

        A friendly, more verbose description of the activity.

      • Cause (string) --

        The reason the activity began.

      • StartTime (datetime) --

        The start time of the activity.

      • EndTime (datetime) --

        The end time of the activity.

      • StatusCode (string) --

        The current status of the activity.

      • StatusMessage (string) --

        A friendly, more verbose description of the activity status.

      • Progress (integer) --

        A value between 0 and 100 that indicates the progress of the activity.

      • Details (string) --

        The details about the activity.

update_auto_scaling_group(**kwargs)

Updates the configuration for the specified Auto Scaling group.

To update an Auto Scaling group with a launch configuration with InstanceMonitoring set to False , you must first disable the collection of group metrics. Otherwise, you will get an error. If you have previously enabled the collection of group metrics, you can disable it using DisableMetricsCollection .

The new settings are registered upon the completion of this call. Any launch configuration settings take effect on any triggers after this call returns. Scaling activities that are currently in progress aren't affected.

Note the following:

  • If you specify a new value for MinSize without specifying a value for DesiredCapacity , and the new MinSize is larger than the current size of the group, we implicitly call SetDesiredCapacity to set the size of the group to the new value of MinSize .
  • If you specify a new value for MaxSize without specifying a value for DesiredCapacity , and the new MaxSize is smaller than the current size of the group, we implicitly call SetDesiredCapacity to set the size of the group to the new value of MaxSize .
  • All other optional parameters are left unchanged if not specified.

Request Syntax

response = client.update_auto_scaling_group(
    AutoScalingGroupName='string',
    LaunchConfigurationName='string',
    MinSize=123,
    MaxSize=123,
    DesiredCapacity=123,
    DefaultCooldown=123,
    AvailabilityZones=[
        'string',
    ],
    HealthCheckType='string',
    HealthCheckGracePeriod=123,
    PlacementGroup='string',
    VPCZoneIdentifier='string',
    TerminationPolicies=[
        'string',
    ]
)
Parameters
  • AutoScalingGroupName (string) --

    [REQUIRED]

    The name of the Auto Scaling group.

  • LaunchConfigurationName (string) -- The name of the launch configuration.
  • MinSize (integer) -- The minimum size of the Auto Scaling group.
  • MaxSize (integer) -- The maximum size of the Auto Scaling group.
  • DesiredCapacity (integer) -- The number of EC2 instances that should be running in the Auto Scaling group. This number must be greater than or equal to the minimum size of the group and less than or equal to the maximum size of the group.
  • DefaultCooldown (integer) -- The amount of time, in seconds, after a scaling activity completes before another scaling activity can start. For more information, see Understanding Auto Scaling Cooldowns .
  • AvailabilityZones (list) --

    One or more Availability Zones for the group.

    • (string) --
  • HealthCheckType (string) -- The type of health check for the instances in the Auto Scaling group. The health check type can either be EC2 for Amazon EC2 or ELB for Elastic Load Balancing.
  • HealthCheckGracePeriod (integer) -- The amount of time, in seconds, that Auto Scaling waits before checking the health status of an instance. The grace period begins when the instance passes the system status and instance status checks from Amazon EC2. For more information, see ` .
  • PlacementGroup (string) -- The name of the placement group into which you'll launch your instances, if any. For more information, see Placement Groups .
  • VPCZoneIdentifier (string) --

    The ID of the subnet, if you are launching into a VPC. You can specify several subnets in a comma-separated list.

    When you specify VPCZoneIdentifier with AvailabilityZones , ensure that the subnets' Availability Zones match the values you specify for AvailabilityZones .

    For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto Scaling Developer Guide .

  • TerminationPolicies (list) --

    A standalone termination policy or a list of termination policies used to select the instance to terminate. The policies are executed in the order that they are listed.

    For more information, see Choosing a Termination Policy for Your Auto Scaling Group in the Auto Scaling Developer Guide .

    • (string) --
Returns

None

Paginators

The available paginators are:

class AutoScaling.Paginator.DescribeAutoScalingGroups
paginator = client.get_paginator('describe_auto_scaling_groups')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_auto_scaling_groups().

Request Syntax

response_iterator = paginator.paginate(
    AutoScalingGroupNames=[
        'string',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • AutoScalingGroupNames (list) --

    The group names.

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'AutoScalingGroups': [
        {
            'AutoScalingGroupName': 'string',
            'AutoScalingGroupARN': 'string',
            'LaunchConfigurationName': 'string',
            'MinSize': 123,
            'MaxSize': 123,
            'DesiredCapacity': 123,
            'DefaultCooldown': 123,
            'AvailabilityZones': [
                'string',
            ],
            'LoadBalancerNames': [
                'string',
            ],
            'HealthCheckType': 'string',
            'HealthCheckGracePeriod': 123,
            'Instances': [
                {
                    'InstanceId': 'string',
                    'AvailabilityZone': 'string',
                    'LifecycleState': 'Pending'|'Pending:Wait'|'Pending:Proceed'|'Quarantined'|'InService'|'Terminating'|'Terminating:Wait'|'Terminating:Proceed'|'Terminated'|'Detaching'|'Detached'|'EnteringStandby'|'Standby',
                    'HealthStatus': 'string',
                    'LaunchConfigurationName': 'string'
                },
            ],
            'CreatedTime': datetime(2015, 1, 1),
            'SuspendedProcesses': [
                {
                    'ProcessName': 'string',
                    'SuspensionReason': 'string'
                },
            ],
            'PlacementGroup': 'string',
            'VPCZoneIdentifier': 'string',
            'EnabledMetrics': [
                {
                    'Metric': 'string',
                    'Granularity': 'string'
                },
            ],
            'Status': 'string',
            'Tags': [
                {
                    'ResourceId': 'string',
                    'ResourceType': 'string',
                    'Key': 'string',
                    'Value': 'string',
                    'PropagateAtLaunch': True|False
                },
            ],
            'TerminationPolicies': [
                'string',
            ]
        },
    ],

}

Response Structure

  • (dict) --

    • AutoScalingGroups (list) --

      The groups.

      • (dict) --

        Describes an Auto Scaling group.

        • AutoScalingGroupName (string) --

          The name of the group.

        • AutoScalingGroupARN (string) --

          The Amazon Resource Name (ARN) of the group.

        • LaunchConfigurationName (string) --

          The name of the associated launch configuration.

        • MinSize (integer) --

          The minimum size of the group.

        • MaxSize (integer) --

          The maximum size of the group.

        • DesiredCapacity (integer) --

          The desired size of the group.

        • DefaultCooldown (integer) --

          The number of seconds after a scaling activity completes before any further scaling activities can start.

        • AvailabilityZones (list) --

          One or more Availability Zones for the group.

          • (string) --
        • LoadBalancerNames (list) --

          One or more load balancers associated with the group.

          • (string) --
        • HealthCheckType (string) --

          The service of interest for the health status check, which can be either EC2 for Amazon EC2 or ELB for Elastic Load Balancing.

        • HealthCheckGracePeriod (integer) --

          The amount of time that Auto Scaling waits before checking an instance's health status. The grace period begins when an instance comes into service.

        • Instances (list) --

          The EC2 instances associated with the group.

          • (dict) --

            Describes an EC2 instance.

            • InstanceId (string) --

              The ID of the instance.

            • AvailabilityZone (string) --

              The Availability Zone in which the instance is running.

            • LifecycleState (string) --

              A description of the current lifecycle state. Note that the Quarantined state is not used.

            • HealthStatus (string) --

              The health status of the instance.

            • LaunchConfigurationName (string) --

              The launch configuration associated with the instance.

        • CreatedTime (datetime) --

          The date and time the group was created.

        • SuspendedProcesses (list) --

          The suspended processes associated with the group.

          • (dict) --

            Describes an Auto Scaling process that has been suspended. For more information, see ProcessType .

            • ProcessName (string) --

              The name of the suspended process.

            • SuspensionReason (string) --

              The reason that the process was suspended.

        • PlacementGroup (string) --

          The name of the placement group into which you'll launch your instances, if any. For more information, see Placement Groups .

        • VPCZoneIdentifier (string) --

          One or more subnet IDs, if applicable, separated by commas.

          If you specify VPCZoneIdentifier and AvailabilityZones , ensure that the Availability Zones of the subnets match the values for AvailabilityZones .

        • EnabledMetrics (list) --

          The metrics enabled for the group.

          • (dict) --

            Describes an enabled metric.

            • Metric (string) --

              The name of the metric.

              • GroupMinSize
              • GroupMaxSize
              • GroupDesiredCapacity
              • GroupInServiceInstances
              • GroupPendingInstances
              • GroupStandbyInstances
              • GroupTerminatingInstances
              • GroupTotalInstances
            • Granularity (string) --

              The granularity of the metric. The only valid value is 1Minute .

        • Status (string) --

          The current state of the group when DeleteAutoScalingGroup is in progress.

        • Tags (list) --

          The tags for the group.

          • (dict) --

            Describes a tag for an Auto Scaling group.

            • ResourceId (string) --

              The name of the group.

            • ResourceType (string) --

              The type of resource. The only supported value is auto-scaling-group .

            • Key (string) --

              The tag key.

            • Value (string) --

              The tag value.

            • PropagateAtLaunch (boolean) --

              Determines whether the tag is added to new instances as they are launched in the group.

        • TerminationPolicies (list) --

          The termination policies for the group.

          • (string) --

class AutoScaling.Paginator.DescribeAutoScalingInstances
paginator = client.get_paginator('describe_auto_scaling_instances')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_auto_scaling_instances().

Request Syntax

response_iterator = paginator.paginate(
    InstanceIds=[
        'string',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • InstanceIds (list) --

    One or more Auto Scaling instances to describe, up to 50 instances. If you omit this parameter, all Auto Scaling instances are described. If you specify an ID that does not exist, it is ignored with no error.

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'AutoScalingInstances': [
        {
            'InstanceId': 'string',
            'AutoScalingGroupName': 'string',
            'AvailabilityZone': 'string',
            'LifecycleState': 'string',
            'HealthStatus': 'string',
            'LaunchConfigurationName': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    • AutoScalingInstances (list) --

      The instances.

      • (dict) --

        Describes an EC2 instance associated with an Auto Scaling group.

        • InstanceId (string) --

          The ID of the instance.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group associated with the instance.

        • AvailabilityZone (string) --

          The Availability Zone for the instance.

        • LifecycleState (string) --

          The lifecycle state for the instance. For more information, see Auto Scaling Instance States in the Auto Scaling Developer Guide .

        • HealthStatus (string) --

          The health status of this instance. "Healthy" means that the instance is healthy and should remain in service. "Unhealthy" means that the instance is unhealthy and Auto Scaling should terminate and replace it.

        • LaunchConfigurationName (string) --

          The launch configuration associated with the instance.

class AutoScaling.Paginator.DescribeLaunchConfigurations
paginator = client.get_paginator('describe_launch_configurations')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_launch_configurations().

Request Syntax

response_iterator = paginator.paginate(
    LaunchConfigurationNames=[
        'string',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • LaunchConfigurationNames (list) --

    The launch configuration names.

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'LaunchConfigurations': [
        {
            'LaunchConfigurationName': 'string',
            'LaunchConfigurationARN': 'string',
            'ImageId': 'string',
            'KeyName': 'string',
            'SecurityGroups': [
                'string',
            ],
            'ClassicLinkVPCId': 'string',
            'ClassicLinkVPCSecurityGroups': [
                'string',
            ],
            'UserData': 'string',
            'InstanceType': 'string',
            'KernelId': 'string',
            'RamdiskId': 'string',
            'BlockDeviceMappings': [
                {
                    'VirtualName': 'string',
                    'DeviceName': 'string',
                    'Ebs': {
                        'SnapshotId': 'string',
                        'VolumeSize': 123,
                        'VolumeType': 'string',
                        'DeleteOnTermination': True|False,
                        'Iops': 123
                    },
                    'NoDevice': True|False
                },
            ],
            'InstanceMonitoring': {
                'Enabled': True|False
            },
            'SpotPrice': 'string',
            'IamInstanceProfile': 'string',
            'CreatedTime': datetime(2015, 1, 1),
            'EbsOptimized': True|False,
            'AssociatePublicIpAddress': True|False,
            'PlacementTenancy': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    • LaunchConfigurations (list) --

      The launch configurations.

      • (dict) --

        Describes a launch configuration.

        • LaunchConfigurationName (string) --

          The name of the launch configuration.

        • LaunchConfigurationARN (string) --

          The Amazon Resource Name (ARN) of the launch configuration.

        • ImageId (string) --

          The ID of the Amazon Machine Image (AMI).

        • KeyName (string) --

          The name of the key pair.

        • SecurityGroups (list) --

          The security groups to associate with the instances.

          • (string) --
        • ClassicLinkVPCId (string) --

          The ID of a ClassicLink-enabled VPC to link your EC2-Classic instances to. This parameter can only be used if you are launching EC2-Classic instances. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .

        • ClassicLinkVPCSecurityGroups (list) --

          The IDs of one or more security groups for the VPC specified in ClassicLinkVPCId . This parameter is required if ClassicLinkVPCId is specified, and cannot be used otherwise. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .

          • (string) --
        • UserData (string) --

          The user data available to the instances.

        • InstanceType (string) --

          The instance type for the instances.

        • KernelId (string) --

          The ID of the kernel associated with the AMI.

        • RamdiskId (string) --

          The ID of the RAM disk associated with the AMI.

        • BlockDeviceMappings (list) --

          A block device mapping, which specifies the block devices for the instance.

          • (dict) --

            Describes a block device mapping.

            • VirtualName (string) --

              The name of the virtual device, ephemeral0 to ephemeral3 .

            • DeviceName (string) --

              The device name exposed to the EC2 instance (for example, /dev/sdh or xvdh ).

            • Ebs (dict) --

              The information about the Amazon EBS volume.

              • SnapshotId (string) --

                The ID of the snapshot.

              • VolumeSize (integer) --

                The volume size, in gigabytes.

                Valid values: If the volume type is io1 , the minimum size of the volume is 10 GiB. If you specify SnapshotId and VolumeSize , VolumeSize must be equal to or larger than the size of the snapshot.

                Default: If you create a volume from a snapshot and you don't specify a volume size, the default is the size of the snapshot.

                Required: Required when the volume type is io1 .

              • VolumeType (string) --

                The volume type.

                Valid values: standard | io1 | gp2

                Default: standard

              • DeleteOnTermination (boolean) --

                Indicates whether to delete the volume on instance termination.

                Default: true

              • Iops (integer) --

                For Provisioned IOPS (SSD) volumes only. The number of I/O operations per second (IOPS) to provision for the volume.

                Valid values: Range is 100 to 4000.

                Default: None

            • NoDevice (boolean) --

              Suppresses a device mapping.

              If this parameter is true for the root device, the instance might fail the EC2 health check. Auto Scaling launches a replacement instance if the instance fails the health check.

        • InstanceMonitoring (dict) --

          Controls whether instances in this group are launched with detailed monitoring.

          • Enabled (boolean) --

            If True , instance monitoring is enabled.

        • SpotPrice (string) --

          The price to bid when launching Spot Instances.

        • IamInstanceProfile (string) --

          The name or Amazon Resource Name (ARN) of the instance profile associated with the IAM role for the instance.

        • CreatedTime (datetime) --

          The creation date and time for the launch configuration.

        • EbsOptimized (boolean) --

          Controls whether the instance is optimized for EBS I/O (true ) or not (false ).

        • AssociatePublicIpAddress (boolean) --

          Specifies whether the instances are associated with a public IP address (true ) or not (false ).

        • PlacementTenancy (string) --

          The tenancy of the instance, either default or dedicated . An instance with dedicated tenancy runs in an isolated, single-tenant hardware and can only be launched into a VPC.

class AutoScaling.Paginator.DescribeNotificationConfigurations
paginator = client.get_paginator('describe_notification_configurations')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_notification_configurations().

Request Syntax

response_iterator = paginator.paginate(
    AutoScalingGroupNames=[
        'string',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • AutoScalingGroupNames (list) --

    The name of the group.

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'NotificationConfigurations': [
        {
            'AutoScalingGroupName': 'string',
            'TopicARN': 'string',
            'NotificationType': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    • NotificationConfigurations (list) --

      The notification configurations.

      • (dict) --

        Describes a notification.

        • AutoScalingGroupName (string) --

          The name of the group.

        • TopicARN (string) --

          The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.

        • NotificationType (string) --

          The types of events for an action to start.

          • autoscaling:EC2_INSTANCE_LAUNCH
          • autoscaling:EC2_INSTANCE_LAUNCH_ERROR
          • autoscaling:EC2_INSTANCE_TERMINATE
          • autoscaling:EC2_INSTANCE_TERMINATE_ERROR
          • autoscaling:TEST_NOTIFICATION

class AutoScaling.Paginator.DescribePolicies
paginator = client.get_paginator('describe_policies')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_policies().

Request Syntax

response_iterator = paginator.paginate(
    AutoScalingGroupName='string',
    PolicyNames=[
        'string',
    ],
    PolicyTypes=[
        'string',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • PolicyNames (list) --

    One or more policy names or policy ARNs to be described. If you omit this list, all policy names are described. If an group name is provided, the results are limited to that group. This list is limited to 50 items. If you specify an unknown policy name, it is ignored with no error.

    • (string) --
  • PolicyTypes (list) --

    One or more policy types. Valid values are SimpleScaling and StepScaling .

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'ScalingPolicies': [
        {
            'AutoScalingGroupName': 'string',
            'PolicyName': 'string',
            'PolicyARN': 'string',
            'PolicyType': 'string',
            'AdjustmentType': 'string',
            'MinAdjustmentStep': 123,
            'MinAdjustmentMagnitude': 123,
            'ScalingAdjustment': 123,
            'Cooldown': 123,
            'StepAdjustments': [
                {
                    'MetricIntervalLowerBound': 123.0,
                    'MetricIntervalUpperBound': 123.0,
                    'ScalingAdjustment': 123
                },
            ],
            'MetricAggregationType': 'string',
            'EstimatedInstanceWarmup': 123,
            'Alarms': [
                {
                    'AlarmName': 'string',
                    'AlarmARN': 'string'
                },
            ]
        },
    ],

}

Response Structure

  • (dict) --

    • ScalingPolicies (list) --

      The scaling policies.

      • (dict) --

        Describes a scaling policy.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group associated with this scaling policy.

        • PolicyName (string) --

          The name of the scaling policy.

        • PolicyARN (string) --

          The Amazon Resource Name (ARN) of the policy.

        • PolicyType (string) --

          The policy type. Valid values are SimpleScaling and StepScaling .

        • AdjustmentType (string) --

          The adjustment type, which specifies how ScalingAdjustment is interpreted. Valid values are ChangeInCapacity , ExactCapacity , and PercentChangeInCapacity .

        • MinAdjustmentStep (integer) --

          Available for backward compatibility. Use MinAdjustmentMagnitude instead.

        • MinAdjustmentMagnitude (integer) --

          The minimum number of instances to scale. If the value of AdjustmentType is PercentChangeInCapacity , the scaling policy changes the DesiredCapacity of the Auto Scaling group by at least this many instances. Otherwise, the error is ValidationError .

        • ScalingAdjustment (integer) --

          The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

        • Cooldown (integer) --

          The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start.

        • StepAdjustments (list) --

          A set of adjustments that enable you to scale based on the size of the alarm breach.

          • (dict) --

            Describes an adjustment based on the difference between the value of the aggregated CloudWatch metric and the breach threshold that you've defined for the alarm.

            For the following examples, suppose that you have an alarm with a breach threshold of 50:

            • If you want the adjustment to be triggered when the metric is greater than or equal to 50 and less than 60, specify a lower bound of 0 and an upper bound of 10.
            • If you want the adjustment to be triggered when the metric is greater than 40 and less than or equal to 50, specify a lower bound of -10 and an upper bound of 0.

            There are a few rules for the step adjustments for your step policy:

            • The ranges of your step adjustments can't overlap or have a gap.
            • At most one step adjustment can have a null lower bound. If one step adjustment has a negative lower bound, then there must be a step adjustment with a null lower bound.
            • At most one step adjustment can have a null upper bound. If one step adjustment has a positive upper bound, then there must be a step adjustment with a null upper bound.
            • The upper and lower bound can't be null in the same step adjustment.
            • MetricIntervalLowerBound (float) --

              The lower bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the lower bound is inclusive (the metric must be greater than or equal to the threshold plus the lower bound). Otherwise, it is exclusive (the metric must be greater than the threshold plus the lower bound). A null value indicates negative infinity.

            • MetricIntervalUpperBound (float) --

              The upper bound for the difference between the alarm threshold and the CloudWatch metric. If the metric value is above the breach threshold, the upper bound is exclusive (the metric must be less than the threshold plus the upper bound). Otherwise, it is inclusive (the metric must be less than or equal to the threshold plus the upper bound). A null value indicates positive infinity.

              The upper bound must be greater than the lower bound.

            • ScalingAdjustment (integer) --

              The amount by which to scale, based on the specified adjustment type. A positive value adds to the current capacity while a negative number removes from the current capacity.

        • MetricAggregationType (string) --

          The aggregation type for the CloudWatch metrics. Valid values are Minimum , Maximum , and Average .

        • EstimatedInstanceWarmup (integer) --

          The estimated time, in seconds, until a newly launched instance can contribute to the CloudWatch metrics.

        • Alarms (list) --

          The CloudWatch alarms related to the policy.

          • (dict) --

            Describes an alarm.

            • AlarmName (string) --

              The name of the alarm.

            • AlarmARN (string) --

              The Amazon Resource Name (ARN) of the alarm.

class AutoScaling.Paginator.DescribeScalingActivities
paginator = client.get_paginator('describe_scaling_activities')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_scaling_activities().

Request Syntax

response_iterator = paginator.paginate(
    ActivityIds=[
        'string',
    ],
    AutoScalingGroupName='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • ActivityIds (list) --

    The activity IDs of the desired scaling activities. If this list is omitted, all activities are described. If the AutoScalingGroupName parameter is provided, the results are limited to that group. The list of requested activities cannot contain more than 50 items. If unknown activities are requested, they are ignored with no error.

    • (string) --
  • AutoScalingGroupName (string) -- The name of the group.
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'Activities': [
        {
            'ActivityId': 'string',
            'AutoScalingGroupName': 'string',
            'Description': 'string',
            'Cause': 'string',
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'|'WaitingForInstanceId'|'PreInService'|'InProgress'|'WaitingForELBConnectionDraining'|'MidLifecycleAction'|'WaitingForInstanceWarmup'|'Successful'|'Failed'|'Cancelled',
            'StatusMessage': 'string',
            'Progress': 123,
            'Details': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    • Activities (list) --

      The scaling activities.

      • (dict) --

        Describes scaling activity, which is a long-running process that represents a change to your Auto Scaling group, such as changing its size or replacing an instance.

        • ActivityId (string) --

          The ID of the activity.

        • AutoScalingGroupName (string) --

          The name of the Auto Scaling group.

        • Description (string) --

          A friendly, more verbose description of the activity.

        • Cause (string) --

          The reason the activity began.

        • StartTime (datetime) --

          The start time of the activity.

        • EndTime (datetime) --

          The end time of the activity.

        • StatusCode (string) --

          The current status of the activity.

        • StatusMessage (string) --

          A friendly, more verbose description of the activity status.

        • Progress (integer) --

          A value between 0 and 100 that indicates the progress of the activity.

        • Details (string) --

          The details about the activity.

class AutoScaling.Paginator.DescribeScheduledActions
paginator = client.get_paginator('describe_scheduled_actions')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_scheduled_actions().

Request Syntax

response_iterator = paginator.paginate(
    AutoScalingGroupName='string',
    ScheduledActionNames=[
        'string',
    ],
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • AutoScalingGroupName (string) -- The name of the group.
  • ScheduledActionNames (list) --

    Describes one or more scheduled actions. If you omit this list, the call describes all scheduled actions. If you specify an unknown scheduled action it is ignored with no error.

    You can describe up to a maximum of 50 instances with a single call. If there are more items to return, the call returns a token. To get the next set of items, repeat the call with the returned token in the NextToken parameter.

    • (string) --
  • StartTime (datetime) -- The earliest scheduled start time to return. If scheduled action names are provided, this parameter is ignored.
  • EndTime (datetime) -- The latest scheduled start time to return. If scheduled action names are provided, this parameter is ignored.
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'ScheduledUpdateGroupActions': [
        {
            'AutoScalingGroupName': 'string',
            'ScheduledActionName': 'string',
            'ScheduledActionARN': 'string',
            'Time': datetime(2015, 1, 1),
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'Recurrence': 'string',
            'MinSize': 123,
            'MaxSize': 123,
            'DesiredCapacity': 123
        },
    ],

}

Response Structure

  • (dict) --

    • ScheduledUpdateGroupActions (list) --

      The scheduled actions.

      • (dict) --

        Describes a scheduled update to an Auto Scaling group.

        • AutoScalingGroupName (string) --

          The name of the group.

        • ScheduledActionName (string) --

          The name of the scheduled action.

        • ScheduledActionARN (string) --

          The Amazon Resource Name (ARN) of the scheduled action.

        • Time (datetime) --

          This parameter is deprecated; use StartTime instead.

        • StartTime (datetime) --

          The date and time that the action is scheduled to begin. This date and time can be up to one month in the future.

          When StartTime and EndTime are specified with Recurrence , they form the boundaries of when the recurring action will start and stop.

        • EndTime (datetime) --

          The date and time that the action is scheduled to end. This date and time can be up to one month in the future.

        • Recurrence (string) --

          The recurring schedule for the action.

        • MinSize (integer) --

          The minimum size of the group.

        • MaxSize (integer) --

          The maximum size of the group.

        • DesiredCapacity (integer) --

          The number of instances you prefer to maintain in the group.

class AutoScaling.Paginator.DescribeTags
paginator = client.get_paginator('describe_tags')
paginate(**kwargs)

Creates an iterator that will paginate through responses from AutoScaling.Client.describe_tags().

Request Syntax

response_iterator = paginator.paginate(
    Filters=[
        {
            'Name': 'string',
            'Values': [
                'string',
            ]
        },
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • Filters (list) --

    A filter used to scope the tags to return.

    • (dict) --

      Describes a filter.

      • Name (string) --

        The name of the filter. The valid values are: "auto-scaling-group" , "key" , "value" , and "propagate-at-launch" .

      • Values (list) --

        The value of the filter.

        • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'Tags': [
        {
            'ResourceId': 'string',
            'ResourceType': 'string',
            'Key': 'string',
            'Value': 'string',
            'PropagateAtLaunch': True|False
        },
    ],

}

Response Structure

  • (dict) --

    • Tags (list) --

      The tags.

      • (dict) --

        Describes a tag for an Auto Scaling group.

        • ResourceId (string) --

          The name of the group.

        • ResourceType (string) --

          The type of resource. The only supported value is auto-scaling-group .

        • Key (string) --

          The tag key.

        • Value (string) --

          The tag value.

        • PropagateAtLaunch (boolean) --

          Determines whether the tag is added to new instances as they are launched in the group.

CloudFormation
Client
class CloudFormation.Client

A low-level client representing AWS CloudFormation:

import boto3

client = boto3.client('cloudformation')

These are the available methods:

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters
operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Returns
True if the operation can be paginated, False otherwise.
cancel_update_stack(**kwargs)

Cancels an update on the specified stack. If the call completes successfully, the stack will roll back the update and revert to the previous stack configuration.

Note

Only stacks that are in the UPDATE_IN_PROGRESS state can be canceled.

Request Syntax

response = client.cancel_update_stack(
    StackName='string'
)
Parameters
StackName (string) --

[REQUIRED]

The name or the unique stack ID that is associated with the stack.

Returns
None
create_stack(**kwargs)

Creates a stack as specified in the template. After the call completes successfully, the stack creation starts. You can check the status of the stack via the DescribeStacks API.

Request Syntax

response = client.create_stack(
    StackName='string',
    TemplateBody='string',
    TemplateURL='string',
    Parameters=[
        {
            'ParameterKey': 'string',
            'ParameterValue': 'string',
            'UsePreviousValue': True|False
        },
    ],
    DisableRollback=True|False,
    TimeoutInMinutes=123,
    NotificationARNs=[
        'string',
    ],
    Capabilities=[
        'CAPABILITY_IAM',
    ],
    OnFailure='DO_NOTHING'|'ROLLBACK'|'DELETE',
    StackPolicyBody='string',
    StackPolicyURL='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name that is associated with the stack. The name must be unique in the region in which you are creating the stack.

    Note

    A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It must start with an alphabetic character and cannot be longer than 255 characters.

  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) located in an S3 bucket in the same region as the stack. For more information, go to the Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • Parameters (list) --

    A list of Parameter structures that specify input parameters for the stack.

    • (dict) --

      The Parameter data type.

      • ParameterKey (string) --

        The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

      • ParameterValue (string) --

        The value associated with the parameter.

      • UsePreviousValue (boolean) --

        During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

  • DisableRollback (boolean) --

    Set to true to disable rollback of the stack if stack creation failed. You can specify either DisableRollback or OnFailure , but not both.

    Default: false

  • TimeoutInMinutes (integer) -- The amount of time that can pass before the stack status becomes CREATE_FAILED; if DisableRollback is not set or is set to false , the stack will be rolled back.
  • NotificationARNs (list) --

    The Simple Notification Service (SNS) topic ARNs to publish stack related events. You can find your SNS topic ARNs using the SNS console or your Command Line Interface (CLI).

    • (string) --
  • Capabilities (list) --

    A list of capabilities that you must specify before AWS CloudFormation can create or update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter.

    Currently, the only valid value is CAPABILITY_IAM , which is required for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack template contains these resources, we recommend that you review any permissions associated with them. If you don't specify this parameter, this action returns an InsufficientCapabilities error.

    • (string) --
  • OnFailure (string) --

    Determines what action will be taken if stack creation fails. This must be one of: DO_NOTHING, ROLLBACK, or DELETE. You can specify either OnFailure or DisableRollback , but not both.

    Default: ROLLBACK

  • StackPolicyBody (string) -- Structure containing the stack policy body. For more information, go to Prevent Updates to Stack Resources in the AWS CloudFormation User Guide. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
  • StackPolicyURL (string) -- Location of a file containing the stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
  • Tags (list) --

    A set of user-defined Tags to associate with this stack, represented by key/value pairs. Tags defined for the stack are propagated to EC2 resources that are created as part of the stack. A maximum number of 10 tags can be specified.

    • (dict) --

      The Tag type is used by CreateStack in the Tags parameter. It allows you to specify a key/value pair that can be used to store information related to cost allocation for an AWS CloudFormation stack.

      • Key (string) --

        Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .

      • Value (string) --

        Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.

Return type

dict

Returns

Response Syntax

{
    'StackId': 'string'
}

Response Structure

  • (dict) --

    The output for a CreateStack action.

    • StackId (string) --

      Unique identifier of the stack.

delete_stack(**kwargs)

Deletes a specified stack. Once the call completes successfully, stack deletion starts. Deleted stacks do not show up in the DescribeStacks API if the deletion has been completed successfully.

Request Syntax

response = client.delete_stack(
    StackName='string'
)
Parameters
StackName (string) --

[REQUIRED]

The name or the unique stack ID that is associated with the stack.

Returns
None
describe_stack_events(**kwargs)

Returns all stack related events for a specified stack. For more information about a stack's event history, go to Stacks in the AWS CloudFormation User Guide.

Note

You can list events for stacks that have failed to create or have been deleted by specifying the unique stack identifier (stack ID).

Request Syntax

response = client.describe_stack_events(
    StackName='string',
    NextToken='string'
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • NextToken (string) --

    String that identifies the start of the next list of events, if there is one.

    Default: There is no default value.

Return type

dict

Returns

Response Syntax

{
    'StackEvents': [
        {
            'StackId': 'string',
            'EventId': 'string',
            'StackName': 'string',
            'LogicalResourceId': 'string',
            'PhysicalResourceId': 'string',
            'ResourceType': 'string',
            'Timestamp': datetime(2015, 1, 1),
            'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
            'ResourceStatusReason': 'string',
            'ResourceProperties': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    The output for a DescribeStackEvents action.

    • StackEvents (list) --

      A list of StackEvents structures.

      • (dict) --

        The StackEvent data type.

        • StackId (string) --

          The unique ID name of the instance of the stack.

        • EventId (string) --

          The unique ID of this event.

        • StackName (string) --

          The name associated with a stack.

        • LogicalResourceId (string) --

          The logical name of the resource specified in the template.

        • PhysicalResourceId (string) --

          The name or unique identifier associated with the physical instance of the resource.

        • ResourceType (string) --

          Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

        • Timestamp (datetime) --

          Time the status was updated.

        • ResourceStatus (string) --

          Current status of the resource.

        • ResourceStatusReason (string) --

          Success/failure message associated with the resource.

        • ResourceProperties (string) --

          BLOB of the properties used to create the resource.

    • NextToken (string) --

      String that identifies the start of the next list of events, if there is one.

describe_stack_resource(**kwargs)

Returns a description of the specified resource in the specified stack.

For deleted stacks, DescribeStackResource returns resource information for up to 90 days after the stack has been deleted.

Request Syntax

response = client.describe_stack_resource(
    StackName='string',
    LogicalResourceId='string'
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • LogicalResourceId (string) --

    [REQUIRED]

    The logical name of the resource as specified in the template.

    Default: There is no default value.

Return type

dict

Returns

Response Syntax

{
    'StackResourceDetail': {
        'StackName': 'string',
        'StackId': 'string',
        'LogicalResourceId': 'string',
        'PhysicalResourceId': 'string',
        'ResourceType': 'string',
        'LastUpdatedTimestamp': datetime(2015, 1, 1),
        'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
        'ResourceStatusReason': 'string',
        'Description': 'string',
        'Metadata': 'string'
    }
}

Response Structure

  • (dict) --

    The output for a DescribeStackResource action.

    • StackResourceDetail (dict) --

      A StackResourceDetail structure containing the description of the specified resource in the specified stack.

      • StackName (string) --

        The name associated with the stack.

      • StackId (string) --

        Unique identifier of the stack.

      • LogicalResourceId (string) --

        The logical name of the resource specified in the template.

      • PhysicalResourceId (string) --

        The name or unique identifier that corresponds to a physical instance ID of a resource supported by AWS CloudFormation.

      • ResourceType (string) --

        Type of resource. ((For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

      • LastUpdatedTimestamp (datetime) --

        Time the status was updated.

      • ResourceStatus (string) --

        Current status of the resource.

      • ResourceStatusReason (string) --

        Success/failure message associated with the resource.

      • Description (string) --

        User defined description associated with the resource.

      • Metadata (string) --

        The JSON format content of the Metadata attribute declared for the resource. For more information, see Metadata Attribute in the AWS CloudFormation User Guide.

describe_stack_resources(**kwargs)

Returns AWS resource descriptions for running and deleted stacks. If StackName is specified, all the associated resources that are part of the stack are returned. If PhysicalResourceId is specified, the associated resources of the stack that the resource belongs to are returned.

Note

Only the first 100 resources will be returned. If your stack has more resources than this, you should use ListStackResources instead.

For deleted stacks, DescribeStackResources returns resource information for up to 90 days after the stack has been deleted.

You must specify either StackName or PhysicalResourceId , but not both. In addition, you can specify LogicalResourceId to filter the returned result. For more information about resources, the LogicalResourceId and PhysicalResourceId , go to the AWS CloudFormation User Guide .

Note

A ValidationError is returned if you specify both StackName and PhysicalResourceId in the same request.

Request Syntax

response = client.describe_stack_resources(
    StackName='string',
    LogicalResourceId='string',
    PhysicalResourceId='string'
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

    Required: Conditional. If you do not specify StackName , you must specify PhysicalResourceId .

  • LogicalResourceId (string) --

    The logical name of the resource as specified in the template.

    Default: There is no default value.

  • PhysicalResourceId (string) --

    The name or unique identifier that corresponds to a physical instance ID of a resource supported by AWS CloudFormation.

    For example, for an Amazon Elastic Compute Cloud (EC2) instance, PhysicalResourceId corresponds to the InstanceId . You can pass the EC2 InstanceId to DescribeStackResources to find which stack the instance belongs to and what other resources are part of the stack.

    Required: Conditional. If you do not specify PhysicalResourceId , you must specify StackName .

    Default: There is no default value.

Return type

dict

Returns

Response Syntax

{
    'StackResources': [
        {
            'StackName': 'string',
            'StackId': 'string',
            'LogicalResourceId': 'string',
            'PhysicalResourceId': 'string',
            'ResourceType': 'string',
            'Timestamp': datetime(2015, 1, 1),
            'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
            'ResourceStatusReason': 'string',
            'Description': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    The output for a DescribeStackResources action.

    • StackResources (list) --

      A list of StackResource structures.

      • (dict) --

        The StackResource data type.

        • StackName (string) --

          The name associated with the stack.

        • StackId (string) --

          Unique identifier of the stack.

        • LogicalResourceId (string) --

          The logical name of the resource specified in the template.

        • PhysicalResourceId (string) --

          The name or unique identifier that corresponds to a physical instance ID of a resource supported by AWS CloudFormation.

        • ResourceType (string) --

          Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

        • Timestamp (datetime) --

          Time the status was updated.

        • ResourceStatus (string) --

          Current status of the resource.

        • ResourceStatusReason (string) --

          Success/failure message associated with the resource.

        • Description (string) --

          User defined description associated with the resource.

describe_stacks(**kwargs)

Returns the description for the specified stack; if no stack name was specified, then it returns the description for all the stacks created.

Request Syntax

response = client.describe_stacks(
    StackName='string',
    NextToken='string'
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • NextToken (string) -- String that identifies the start of the next list of stacks, if there is one.
Return type

dict

Returns

Response Syntax

{
    'Stacks': [
        {
            'StackId': 'string',
            'StackName': 'string',
            'Description': 'string',
            'Parameters': [
                {
                    'ParameterKey': 'string',
                    'ParameterValue': 'string',
                    'UsePreviousValue': True|False
                },
            ],
            'CreationTime': datetime(2015, 1, 1),
            'LastUpdatedTime': datetime(2015, 1, 1),
            'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
            'StackStatusReason': 'string',
            'DisableRollback': True|False,
            'NotificationARNs': [
                'string',
            ],
            'TimeoutInMinutes': 123,
            'Capabilities': [
                'CAPABILITY_IAM',
            ],
            'Outputs': [
                {
                    'OutputKey': 'string',
                    'OutputValue': 'string',
                    'Description': 'string'
                },
            ],
            'Tags': [
                {
                    'Key': 'string',
                    'Value': 'string'
                },
            ]
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    The output for a DescribeStacks action.

    • Stacks (list) --

      A list of stack structures.

      • (dict) --

        The Stack data type.

        • StackId (string) --

          Unique identifier of the stack.

        • StackName (string) --

          The name associated with the stack.

        • Description (string) --

          User defined description associated with the stack.

        • Parameters (list) --

          A list of Parameter structures.

          • (dict) --

            The Parameter data type.

            • ParameterKey (string) --

              The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

            • ParameterValue (string) --

              The value associated with the parameter.

            • UsePreviousValue (boolean) --

              During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

        • CreationTime (datetime) --

          Time at which the stack was created.

        • LastUpdatedTime (datetime) --

          The time the stack was last updated. This field will only be returned if the stack has been updated at least once.

        • StackStatus (string) --

          Current status of the stack.

        • StackStatusReason (string) --

          Success/failure message associated with the stack status.

        • DisableRollback (boolean) --

          Boolean to enable or disable rollback on stack creation failures:

          • true : disable rollback
          • false : enable rollback
        • NotificationARNs (list) --

          SNS topic ARNs to which stack related events are published.

          • (string) --
        • TimeoutInMinutes (integer) --

          The amount of time within which stack creation should complete.

        • Capabilities (list) --

          The capabilities allowed in the stack.

          • (string) --
        • Outputs (list) --

          A list of output structures.

          • (dict) --

            The Output data type.

            • OutputKey (string) --

              The key associated with the output.

            • OutputValue (string) --

              The value associated with the output.

            • Description (string) --

              User defined description associated with the output.

        • Tags (list) --

          A list of Tag s that specify cost allocation information for the stack.

          • (dict) --

            The Tag type is used by CreateStack in the Tags parameter. It allows you to specify a key/value pair that can be used to store information related to cost allocation for an AWS CloudFormation stack.

            • Key (string) --

              Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .

            • Value (string) --

              Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.

    • NextToken (string) -- String that identifies the start of the next list of stacks, if there is one.

estimate_template_cost(**kwargs)

Returns the estimated monthly cost of a template. The return value is an AWS Simple Monthly Calculator URL with a query string that describes the resources required to run the template.

Request Syntax

response = client.estimate_template_cost(
    TemplateBody='string',
    TemplateURL='string',
    Parameters=[
        {
            'ParameterKey': 'string',
            'ParameterValue': 'string',
            'UsePreviousValue': True|False
        },
    ]
)
Parameters
  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. (For more information, go to Template Anatomy in the AWS CloudFormation User Guide.)

    Conditional: You must pass TemplateBody or TemplateURL . If both are passed, only TemplateBody is used.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template located in an S3 bucket in the same region as the stack. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must pass TemplateURL or TemplateBody . If both are passed, only TemplateBody is used.

  • Parameters (list) --

    A list of Parameter structures that specify input parameters.

    • (dict) --

      The Parameter data type.

      • ParameterKey (string) --

        The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

      • ParameterValue (string) --

        The value associated with the parameter.

      • UsePreviousValue (boolean) --

        During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

Return type

dict

Returns

Response Syntax

{
    'Url': 'string'
}

Response Structure

  • (dict) --

    The output for a EstimateTemplateCost action.

    • Url (string) --

      An AWS Simple Monthly Calculator URL with a query string that describes the resources required to run the template.

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters
  • ClientMethod (string) -- The client method to presign for
  • Params (dict) -- The parameters normally passed to ClientMethod.
  • ExpiresIn (int) -- The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)
  • HttpMethod (string) -- The http method to use on the generated url. By default, the http method is whatever is used in the method's model.
Returns

The presigned url

get_paginator(operation_name)

Create a paginator for an operation.

Parameters
operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Raises OperationNotPageableError
Raised if the operation is not pageable. You can use the client.can_paginate method to check if an operation is pageable.
Return type
L{botocore.paginate.Paginator}
Returns
A paginator object.
get_stack_policy(**kwargs)

Returns the stack policy for a specified stack. If a stack doesn't have a policy, a null value is returned.

Request Syntax

response = client.get_stack_policy(
    StackName='string'
)
Parameters
StackName (string) --

[REQUIRED]

The name or unique stack ID that is associated with the stack whose policy you want to get.

Return type
dict
Returns
Response Syntax
{
    'StackPolicyBody': 'string'
}

Response Structure

  • (dict) --

    The output for the GetStackPolicy action.

    • StackPolicyBody (string) --

      Structure containing the stack policy body. (For more information, go to Prevent Updates to Stack Resources in the AWS CloudFormation User Guide.)

get_template(**kwargs)

Returns the template body for a specified stack. You can get the template for running or deleted stacks.

For deleted stacks, GetTemplate returns the template for up to 90 days after the stack has been deleted.

Note

If the template does not exist, a ValidationError is returned.

Request Syntax

response = client.get_template(
    StackName='string'
)
Parameters
StackName (string) --

[REQUIRED]

The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

  • Running stacks: You can specify either the stack's name or its unique stack ID.
  • Deleted stacks: You must specify the unique stack ID.

Default: There is no default value.

Return type
dict
Returns
Response Syntax
{
    'TemplateBody': 'string'
}

Response Structure

  • (dict) --

    The output for GetTemplate action.

    • TemplateBody (string) --

      Structure containing the template body. (For more information, go to Template Anatomy in the AWS CloudFormation User Guide.)

get_template_summary(**kwargs)

Returns information about a new or existing template. The GetTemplateSummary action is useful for viewing parameter information, such as default parameter values and parameter types, before you create or update a stack.

You can use the GetTemplateSummary action when you submit a template, or you can get template information for a running or deleted stack.

For deleted stacks, GetTemplateSummary returns the template information for up to 90 days after the stack has been deleted. If the template does not exist, a ValidationError is returned.

Request Syntax

response = client.get_template_summary(
    TemplateBody='string',
    TemplateURL='string',
    StackName='string'
)
Parameters
  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information about templates, see Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) located in an Amazon S3 bucket. For more information about templates, see Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .

  • StackName (string) --

    The name or the stack ID that is associated with the stack, which are not always interchangeable. For running stacks, you can specify either the stack's name or its unique stack ID. For deleted stack, you must specify the unique stack ID.

    Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .

Return type

dict

Returns

Response Syntax

{
    'Parameters': [
        {
            'ParameterKey': 'string',
            'DefaultValue': 'string',
            'ParameterType': 'string',
            'NoEcho': True|False,
            'Description': 'string',
            'ParameterConstraints': {
                'AllowedValues': [
                    'string',
                ]
            }
        },
    ],
    'Description': 'string',
    'Capabilities': [
        'CAPABILITY_IAM',
    ],
    'CapabilitiesReason': 'string',
    'Version': 'string',
    'Metadata': 'string'
}

Response Structure

  • (dict) --

    The output for the GetTemplateSummary action.

    • Parameters (list) --

      A list of parameter declarations that describe various properties for each parameter.

      • (dict) --

        The ParameterDeclaration data type.

        • ParameterKey (string) --

          The name that is associated with the parameter.

        • DefaultValue (string) --

          The default value of the parameter.

        • ParameterType (string) --

          The type of parameter.

        • NoEcho (boolean) --

          Flag that indicates whether the parameter value is shown as plain text in logs and in the AWS Management Console.

        • Description (string) --

          The description that is associate with the parameter.

        • ParameterConstraints (dict) --

          The criteria that AWS CloudFormation uses to validate parameter values.

          • AllowedValues (list) --

            A list of values that are permitted for a parameter.

            • (string) --
    • Description (string) --

      The value that is defined in the Description property of the template.

    • Capabilities (list) --

      The capabilities found within the template. Currently, AWS CloudFormation supports only the CAPABILITY_IAM capability. If your template contains IAM resources, you must specify the CAPABILITY_IAM value for this parameter when you use the CreateStack or UpdateStack actions with your template; otherwise, those actions return an InsufficientCapabilities error.

      • (string) --
    • CapabilitiesReason (string) --

      The list of resources that generated the values in the Capabilities response element.

    • Version (string) --

      The AWS template format version, which identifies the capabilities of the template.

    • Metadata (string) --

      The value that is defined for the Metadata property of the template.

get_waiter(waiter_name)
list_stack_resources(**kwargs)

Returns descriptions of all resources of the specified stack.

For deleted stacks, ListStackResources returns resource information for up to 90 days after the stack has been deleted.

Request Syntax

response = client.list_stack_resources(
    StackName='string',
    NextToken='string'
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • NextToken (string) --

    String that identifies the start of the next list of stack resource summaries, if there is one.

    Default: There is no default value.

Return type

dict

Returns

Response Syntax

{
    'StackResourceSummaries': [
        {
            'LogicalResourceId': 'string',
            'PhysicalResourceId': 'string',
            'ResourceType': 'string',
            'LastUpdatedTimestamp': datetime(2015, 1, 1),
            'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
            'ResourceStatusReason': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    The output for a ListStackResources action.

    • StackResourceSummaries (list) --

      A list of StackResourceSummary structures.

      • (dict) --

        Contains high-level information about the specified stack resource.

        • LogicalResourceId (string) --

          The logical name of the resource specified in the template.

        • PhysicalResourceId (string) --

          The name or unique identifier that corresponds to a physical instance ID of the resource.

        • ResourceType (string) --

          Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

        • LastUpdatedTimestamp (datetime) --

          Time the status was updated.

        • ResourceStatus (string) --

          Current status of the resource.

        • ResourceStatusReason (string) --

          Success/failure message associated with the resource.

    • NextToken (string) --

      String that identifies the start of the next list of stack resources, if there is one.

list_stacks(**kwargs)

Returns the summary information for stacks whose status matches the specified StackStatusFilter. Summary information for stacks that have been deleted is kept for 90 days after the stack is deleted. If no StackStatusFilter is specified, summary information for all stacks is returned (including existing stacks and stacks that have been deleted).

Request Syntax

response = client.list_stacks(
    NextToken='string',
    StackStatusFilter=[
        'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
    ]
)
Parameters
  • NextToken (string) --

    String that identifies the start of the next list of stacks, if there is one.

    Default: There is no default value.

  • StackStatusFilter (list) --

    Stack status to use as a filter. Specify one or more stack status codes to list only stacks with the specified status codes. For a complete list of stack status codes, see the StackStatus parameter of the Stack data type.

    • (string) --
Return type

dict

Returns

Response Syntax

{
    'StackSummaries': [
        {
            'StackId': 'string',
            'StackName': 'string',
            'TemplateDescription': 'string',
            'CreationTime': datetime(2015, 1, 1),
            'LastUpdatedTime': datetime(2015, 1, 1),
            'DeletionTime': datetime(2015, 1, 1),
            'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
            'StackStatusReason': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    The output for ListStacks action.

    • StackSummaries (list) --

      A list of StackSummary structures containing information about the specified stacks.

      • (dict) --

        The StackSummary Data Type

        • StackId (string) --

          Unique stack identifier.

        • StackName (string) --

          The name associated with the stack.

        • TemplateDescription (string) --

          The template description of the template used to create the stack.

        • CreationTime (datetime) --

          The time the stack was created.

        • LastUpdatedTime (datetime) --

          The time the stack was last updated. This field will only be returned if the stack has been updated at least once.

        • DeletionTime (datetime) --

          The time the stack was deleted.

        • StackStatus (string) --

          The current status of the stack.

        • StackStatusReason (string) --

          Success/Failure message associated with the stack status.

    • NextToken (string) --

      String that identifies the start of the next list of stacks, if there is one.

set_stack_policy(**kwargs)

Sets a stack policy for a specified stack.

Request Syntax

response = client.set_stack_policy(
    StackName='string',
    StackPolicyBody='string',
    StackPolicyURL='string'
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name or unique stack ID that you want to associate a policy with.

  • StackPolicyBody (string) -- Structure containing the stack policy body. For more information, go to Prevent Updates to Stack Resources in the AWS CloudFormation User Guide. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
  • StackPolicyURL (string) -- Location of a file containing the stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
Returns

None

signal_resource(**kwargs)

Sends a signal to the specified resource with a success or failure status. You can use the SignalResource API in conjunction with a creation policy or update policy. AWS CloudFormation doesn't proceed with a stack creation or update until resources receive the required number of signals or the timeout period is exceeded. The SignalResource API is useful in cases where you want to send signals from anywhere other than an Amazon EC2 instance.

Request Syntax

response = client.signal_resource(
    StackName='string',
    LogicalResourceId='string',
    UniqueId='string',
    Status='SUCCESS'|'FAILURE'
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The stack name or unique stack ID that includes the resource that you want to signal.

  • LogicalResourceId (string) --

    [REQUIRED]

    The logical ID of the resource that you want to signal. The logical ID is the name of the resource that given in the template.

  • UniqueId (string) --

    [REQUIRED]

    A unique ID of the signal. When you signal Amazon EC2 instances or Auto Scaling groups, specify the instance ID that you are signaling as the unique ID. If you send multiple signals to a single resource (such as signaling a wait condition), each signal requires a different unique ID.

  • Status (string) --

    [REQUIRED]

    The status of the signal, which is either success or failure. A failure signal causes AWS CloudFormation to immediately fail the stack creation or update.

Returns

None

update_stack(**kwargs)

Updates a stack as specified in the template. After the call completes successfully, the stack update starts. You can check the status of the stack via the DescribeStacks action.

To get a copy of the template for an existing stack, you can use the GetTemplate action.

Tags that were associated with this stack during creation time will still be associated with the stack after an UpdateStack operation.

For more information about creating an update template, updating a stack, and monitoring the progress of the update, see Updating a Stack .

Request Syntax

response = client.update_stack(
    StackName='string',
    TemplateBody='string',
    TemplateURL='string',
    UsePreviousTemplate=True|False,
    StackPolicyDuringUpdateBody='string',
    StackPolicyDuringUpdateURL='string',
    Parameters=[
        {
            'ParameterKey': 'string',
            'ParameterValue': 'string',
            'UsePreviousValue': True|False
        },
    ],
    Capabilities=[
        'CAPABILITY_IAM',
    ],
    StackPolicyBody='string',
    StackPolicyURL='string',
    NotificationARNs=[
        'string',
    ]
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name or unique stack ID of the stack to update.

  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. (For more information, go to Template Anatomy in the AWS CloudFormation User Guide.)

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template located in an S3 bucket in the same region as the stack. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • UsePreviousTemplate (boolean) -- Reuse the existing template that is associated with the stack that you are updating.
  • StackPolicyDuringUpdateBody (string) --

    Structure containing the temporary overriding stack policy body. You can specify either the StackPolicyDuringUpdateBody or the StackPolicyDuringUpdateURL parameter, but not both.

    If you want to update protected resources, specify a temporary overriding stack policy during this update. If you do not specify a stack policy, the current policy that is associated with the stack will be used.

  • StackPolicyDuringUpdateURL (string) --

    Location of a file containing the temporary overriding stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyDuringUpdateBody or the StackPolicyDuringUpdateURL parameter, but not both.

    If you want to update protected resources, specify a temporary overriding stack policy during this update. If you do not specify a stack policy, the current policy that is associated with the stack will be used.

  • Parameters (list) --

    A list of Parameter structures that specify input parameters for the stack. For more information, see the Parameter data type.

    • (dict) --

      The Parameter data type.

      • ParameterKey (string) --

        The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

      • ParameterValue (string) --

        The value associated with the parameter.

      • UsePreviousValue (boolean) --

        During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

  • Capabilities (list) --

    A list of capabilities that you must specify before AWS CloudFormation can create or update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter. Currently, the only valid value is CAPABILITY_IAM , which is required for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack template contains these resources, we recommend that you review any permissions associated with them. If you don't specify this parameter, this action returns an InsufficientCapabilities error.

    • (string) --
  • StackPolicyBody (string) --

    Structure containing a new stack policy body. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.

    You might update the stack policy, for example, in order to protect a new resource that you created during a stack update. If you do not specify a stack policy, the current policy that is associated with the stack is unchanged.

  • StackPolicyURL (string) --

    Location of a file containing the updated stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.

    You might update the stack policy, for example, in order to protect a new resource that you created during a stack update. If you do not specify a stack policy, the current policy that is associated with the stack is unchanged.

  • NotificationARNs (list) --

    Update the ARNs for the Amazon SNS topics that are associated with the stack.

    • (string) --
Return type

dict

Returns

Response Syntax

{
    'StackId': 'string'
}

Response Structure

  • (dict) --

    The output for a UpdateStack action.

    • StackId (string) --

      Unique identifier of the stack.

validate_template(**kwargs)

Validates a specified template.

Request Syntax

response = client.validate_template(
    TemplateBody='string',
    TemplateURL='string'
)
Parameters
  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must pass TemplateURL or TemplateBody . If both are passed, only TemplateBody is used.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) located in an S3 bucket in the same region as the stack. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must pass TemplateURL or TemplateBody . If both are passed, only TemplateBody is used.

Return type

dict

Returns

Response Syntax

{
    'Parameters': [
        {
            'ParameterKey': 'string',
            'DefaultValue': 'string',
            'NoEcho': True|False,
            'Description': 'string'
        },
    ],
    'Description': 'string',
    'Capabilities': [
        'CAPABILITY_IAM',
    ],
    'CapabilitiesReason': 'string'
}

Response Structure

  • (dict) --

    The output for ValidateTemplate action.

    • Parameters (list) --

      A list of TemplateParameter structures.

      • (dict) --

        The TemplateParameter data type.

        • ParameterKey (string) --

          The name associated with the parameter.

        • DefaultValue (string) --

          The default value associated with the parameter.

        • NoEcho (boolean) --

          Flag indicating whether the parameter should be displayed as plain text in logs and UIs.

        • Description (string) --

          User defined description associated with the parameter.

    • Description (string) --

      The description found within the template.

    • Capabilities (list) --

      The capabilities found within the template. Currently, AWS CloudFormation supports only the CAPABILITY_IAM capability. If your template contains IAM resources, you must specify the CAPABILITY_IAM value for this parameter when you use the CreateStack or UpdateStack actions with your template; otherwise, those actions return an InsufficientCapabilities error.

      • (string) --
    • CapabilitiesReason (string) --

      The list of resources that generated the values in the Capabilities response element.

Paginators

The available paginators are:

class CloudFormation.Paginator.DescribeStackEvents
paginator = client.get_paginator('describe_stack_events')
paginate(**kwargs)

Creates an iterator that will paginate through responses from CloudFormation.Client.describe_stack_events().

Request Syntax

response_iterator = paginator.paginate(
    StackName='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'StackEvents': [
        {
            'StackId': 'string',
            'EventId': 'string',
            'StackName': 'string',
            'LogicalResourceId': 'string',
            'PhysicalResourceId': 'string',
            'ResourceType': 'string',
            'Timestamp': datetime(2015, 1, 1),
            'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
            'ResourceStatusReason': 'string',
            'ResourceProperties': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    The output for a DescribeStackEvents action.

    • StackEvents (list) --

      A list of StackEvents structures.

      • (dict) --

        The StackEvent data type.

        • StackId (string) --

          The unique ID name of the instance of the stack.

        • EventId (string) --

          The unique ID of this event.

        • StackName (string) --

          The name associated with a stack.

        • LogicalResourceId (string) --

          The logical name of the resource specified in the template.

        • PhysicalResourceId (string) --

          The name or unique identifier associated with the physical instance of the resource.

        • ResourceType (string) --

          Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

        • Timestamp (datetime) --

          Time the status was updated.

        • ResourceStatus (string) --

          Current status of the resource.

        • ResourceStatusReason (string) --

          Success/failure message associated with the resource.

        • ResourceProperties (string) --

          BLOB of the properties used to create the resource.

class CloudFormation.Paginator.DescribeStacks
paginator = client.get_paginator('describe_stacks')
paginate(**kwargs)

Creates an iterator that will paginate through responses from CloudFormation.Client.describe_stacks().

Request Syntax

response_iterator = paginator.paginate(
    StackName='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'Stacks': [
        {
            'StackId': 'string',
            'StackName': 'string',
            'Description': 'string',
            'Parameters': [
                {
                    'ParameterKey': 'string',
                    'ParameterValue': 'string',
                    'UsePreviousValue': True|False
                },
            ],
            'CreationTime': datetime(2015, 1, 1),
            'LastUpdatedTime': datetime(2015, 1, 1),
            'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
            'StackStatusReason': 'string',
            'DisableRollback': True|False,
            'NotificationARNs': [
                'string',
            ],
            'TimeoutInMinutes': 123,
            'Capabilities': [
                'CAPABILITY_IAM',
            ],
            'Outputs': [
                {
                    'OutputKey': 'string',
                    'OutputValue': 'string',
                    'Description': 'string'
                },
            ],
            'Tags': [
                {
                    'Key': 'string',
                    'Value': 'string'
                },
            ]
        },
    ],

}

Response Structure

  • (dict) --

    The output for a DescribeStacks action.

    • Stacks (list) --

      A list of stack structures.

      • (dict) --

        The Stack data type.

        • StackId (string) --

          Unique identifier of the stack.

        • StackName (string) --

          The name associated with the stack.

        • Description (string) --

          User defined description associated with the stack.

        • Parameters (list) --

          A list of Parameter structures.

          • (dict) --

            The Parameter data type.

            • ParameterKey (string) --

              The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

            • ParameterValue (string) --

              The value associated with the parameter.

            • UsePreviousValue (boolean) --

              During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

        • CreationTime (datetime) --

          Time at which the stack was created.

        • LastUpdatedTime (datetime) --

          The time the stack was last updated. This field will only be returned if the stack has been updated at least once.

        • StackStatus (string) --

          Current status of the stack.

        • StackStatusReason (string) --

          Success/failure message associated with the stack status.

        • DisableRollback (boolean) --

          Boolean to enable or disable rollback on stack creation failures:

          • true : disable rollback
          • false : enable rollback
        • NotificationARNs (list) --

          SNS topic ARNs to which stack related events are published.

          • (string) --
        • TimeoutInMinutes (integer) --

          The amount of time within which stack creation should complete.

        • Capabilities (list) --

          The capabilities allowed in the stack.

          • (string) --
        • Outputs (list) --

          A list of output structures.

          • (dict) --

            The Output data type.

            • OutputKey (string) --

              The key associated with the output.

            • OutputValue (string) --

              The value associated with the output.

            • Description (string) --

              User defined description associated with the output.

        • Tags (list) --

          A list of Tag s that specify cost allocation information for the stack.

          • (dict) --

            The Tag type is used by CreateStack in the Tags parameter. It allows you to specify a key/value pair that can be used to store information related to cost allocation for an AWS CloudFormation stack.

            • Key (string) --

              Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .

            • Value (string) --

              Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.

class CloudFormation.Paginator.ListStackResources
paginator = client.get_paginator('list_stack_resources')
paginate(**kwargs)

Creates an iterator that will paginate through responses from CloudFormation.Client.list_stack_resources().

Request Syntax

response_iterator = paginator.paginate(
    StackName='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'StackResourceSummaries': [
        {
            'LogicalResourceId': 'string',
            'PhysicalResourceId': 'string',
            'ResourceType': 'string',
            'LastUpdatedTimestamp': datetime(2015, 1, 1),
            'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE',
            'ResourceStatusReason': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    The output for a ListStackResources action.

    • StackResourceSummaries (list) --

      A list of StackResourceSummary structures.

      • (dict) --

        Contains high-level information about the specified stack resource.

        • LogicalResourceId (string) --

          The logical name of the resource specified in the template.

        • PhysicalResourceId (string) --

          The name or unique identifier that corresponds to a physical instance ID of the resource.

        • ResourceType (string) --

          Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

        • LastUpdatedTimestamp (datetime) --

          Time the status was updated.

        • ResourceStatus (string) --

          Current status of the resource.

        • ResourceStatusReason (string) --

          Success/failure message associated with the resource.

class CloudFormation.Paginator.ListStacks
paginator = client.get_paginator('list_stacks')
paginate(**kwargs)

Creates an iterator that will paginate through responses from CloudFormation.Client.list_stacks().

Request Syntax

response_iterator = paginator.paginate(
    StackStatusFilter=[
        'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters
  • StackStatusFilter (list) --

    Stack status to use as a filter. Specify one or more stack status codes to list only stacks with the specified status codes. For a complete list of stack status codes, see the StackStatus parameter of the Stack data type.

    • (string) --
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type

dict

Returns

Response Syntax

{
    'StackSummaries': [
        {
            'StackId': 'string',
            'StackName': 'string',
            'TemplateDescription': 'string',
            'CreationTime': datetime(2015, 1, 1),
            'LastUpdatedTime': datetime(2015, 1, 1),
            'DeletionTime': datetime(2015, 1, 1),
            'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_FAILED'|'ROLLBACK_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'UPDATE_IN_PROGRESS'|'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE',
            'StackStatusReason': 'string'
        },
    ],

}

Response Structure

  • (dict) --

    The output for ListStacks action.

    • StackSummaries (list) --

      A list of StackSummary structures containing information about the specified stacks.

      • (dict) --

        The StackSummary Data Type

        • StackId (string) --

          Unique stack identifier.

        • StackName (string) --

          The name associated with the stack.

        • TemplateDescription (string) --

          The template description of the template used to create the stack.

        • CreationTime (datetime) --

          The time the stack was created.

        • LastUpdatedTime (datetime) --

          The time the stack was last updated. This field will only be returned if the stack has been updated at least once.

        • DeletionTime (datetime) --

          The time the stack was deleted.

        • StackStatus (string) --

          The current status of the stack.

        • StackStatusReason (string) --

          Success/Failure message associated with the stack status.

Service Resource
class CloudFormation.ServiceResource

A resource representing AWS CloudFormation:

import boto3

cloudformation = boto3.resource('cloudformation')

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available collections:

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

create_stack(**kwargs)

Creates a stack as specified in the template. After the call completes successfully, the stack creation starts. You can check the status of the stack via the DescribeStacks API.

Request Syntax

stack = cloudformation.create_stack(
    StackName='string',
    TemplateBody='string',
    TemplateURL='string',
    Parameters=[
        {
            'ParameterKey': 'string',
            'ParameterValue': 'string',
            'UsePreviousValue': True|False
        },
    ],
    DisableRollback=True|False,
    TimeoutInMinutes=123,
    NotificationARNs=[
        'string',
    ],
    Capabilities=[
        'CAPABILITY_IAM',
    ],
    OnFailure='DO_NOTHING'|'ROLLBACK'|'DELETE',
    StackPolicyBody='string',
    StackPolicyURL='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
Parameters
  • StackName (string) --

    [REQUIRED]

    The name that is associated with the stack. The name must be unique in the region in which you are creating the stack.

    Note

    A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It must start with an alphabetic character and cannot be longer than 255 characters.

  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) located in an S3 bucket in the same region as the stack. For more information, go to the Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • Parameters (list) --

    A list of Parameter structures that specify input parameters for the stack.

    • (dict) --

      The Parameter data type.

      • ParameterKey (string) --

        The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

      • ParameterValue (string) --

        The value associated with the parameter.

      • UsePreviousValue (boolean) --

        During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

  • DisableRollback (boolean) --

    Set to true to disable rollback of the stack if stack creation failed. You can specify either DisableRollback or OnFailure , but not both.

    Default: false

  • TimeoutInMinutes (integer) -- The amount of time that can pass before the stack status becomes CREATE_FAILED; if DisableRollback is not set or is set to false , the stack will be rolled back.
  • NotificationARNs (list) --

    The Simple Notification Service (SNS) topic ARNs to publish stack related events. You can find your SNS topic ARNs using the SNS console or your Command Line Interface (CLI).

    • (string) --
  • Capabilities (list) --

    A list of capabilities that you must specify before AWS CloudFormation can create or update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter.

    Currently, the only valid value is CAPABILITY_IAM , which is required for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack template contains these resources, we recommend that you review any permissions associated with them. If you don't specify this parameter, this action returns an InsufficientCapabilities error.

    • (string) --
  • OnFailure (string) --

    Determines what action will be taken if stack creation fails. This must be one of: DO_NOTHING, ROLLBACK, or DELETE. You can specify either OnFailure or DisableRollback , but not both.

    Default: ROLLBACK

  • StackPolicyBody (string) -- Structure containing the stack policy body. For more information, go to Prevent Updates to Stack Resources in the AWS CloudFormation User Guide. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
  • StackPolicyURL (string) -- Location of a file containing the stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.
  • Tags (list) --

    A set of user-defined Tags to associate with this stack, represented by key/value pairs. Tags defined for the stack are propagated to EC2 resources that are created as part of the stack. A maximum number of 10 tags can be specified.

    • (dict) --

      The Tag type is used by CreateStack in the Tags parameter. It allows you to specify a key/value pair that can be used to store information related to cost allocation for an AWS CloudFormation stack.

      • Key (string) --

        Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .

      • Value (string) --

        Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.

Return type

cloudformation.Stack

Returns

Stack resource

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Event(id)

Creates a Event resource.:

event = cloudformation.Event('id')
Parameters
id (string) -- The Event's id identifier. This must be set.
Return type
CloudFormation.Event
Returns
A Event resource
Stack(name)

Creates a Stack resource.:

stack = cloudformation.Stack('name')
Parameters
name (string) -- The Stack's name identifier. This must be set.
Return type
CloudFormation.Stack
Returns
A Stack resource
StackResource(stack_name, logical_id)

Creates a StackResource resource.:

stack_resource = cloudformation.StackResource('stack_name','logical_id')
Parameters
  • stack_name (string) -- The StackResource's stack_name identifier. This must be set.
  • logical_id (string) -- The StackResource's logical_id identifier. This must be set.
Return type

CloudFormation.StackResource

Returns

A StackResource resource

StackResourceSummary(stack_name, logical_id)

Creates a StackResourceSummary resource.:

stack_resource_summary = cloudformation.StackResourceSummary('stack_name','logical_id')
Parameters
  • stack_name (string) -- The StackResourceSummary's stack_name identifier. This must be set.
  • logical_id (string) -- The StackResourceSummary's logical_id identifier. This must be set.
Return type

CloudFormation.StackResourceSummary

Returns

A StackResourceSummary resource

Collections

Collections provide an interface to iterate over and manipulate groups of resources. For more information about collections refer to the Resources Introduction Guide.

stacks
all()

Creates an iterable of all Stack resources in the collection.

Request Syntax

stack_iterator = cloudformation.stacks.all()
Return type
list(cloudformation.Stack)
Returns
A list of Stack resources
filter(**kwargs)

Creates an iterable of all Stack resources in the collection filtered by kwargs passed to method.

Request Syntax

stack_iterator = cloudformation.stacks.filter(
    StackName='string',
    NextToken='string'
)
Parameters
  • StackName (string) --

    The name or the unique stack ID that is associated with the stack, which are not always interchangeable:

    • Running stacks: You can specify either the stack's name or its unique stack ID.
    • Deleted stacks: You must specify the unique stack ID.

    Default: There is no default value.

  • NextToken (string) -- String that identifies the start of the next list of stacks, if there is one.
Return type

list(cloudformation.Stack)

Returns

A list of Stack resources

limit(**kwargs)

Creates an iterable up to a specified amount of Stack resources in the collection.

Request Syntax

stack_iterator = cloudformation.stacks.limit(
    count=123
)
Parameters
count (integer) -- The limit to the number of resources in the iterable.
Return type
list(cloudformation.Stack)
Returns
A list of Stack resources
page_size(**kwargs)

Creates an iterable of all Stack resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

stack_iterator = cloudformation.stacks.page_size(
    count=123
)
Parameters
count (integer) -- The number of items returned by each service call
Return type
list(cloudformation.Stack)
Returns
A list of Stack resources
Event
class CloudFormation.Event(id)

A resource representing an AWS CloudFormation Event:

import boto3

cloudformation = boto3.resource('cloudformation')
event = cloudformation.Event('id')
Parameters
id (string) -- The Event's id identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

id

(string) The Event's id identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

event_id

(string)

The unique ID of this event.

logical_resource_id

(string)

The logical name of the resource specified in the template.

physical_resource_id

(string)

The name or unique identifier associated with the physical instance of the resource.

resource_properties

(string)

BLOB of the properties used to create the resource.

resource_status

(string)

Current status of the resource.

resource_status_reason

(string)

Success/failure message associated with the resource.

resource_type

(string)

Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

stack_id

(string)

The unique ID name of the instance of the stack.

stack_name

(string)

The name associated with a stack.

timestamp

(datetime)

Time the status was updated.

Stack
class CloudFormation.Stack(name)

A resource representing an AWS CloudFormation Stack:

import boto3

cloudformation = boto3.resource('cloudformation')
stack = cloudformation.Stack('name')
Parameters
name (string) -- The Stack's name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available collections:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

name

(string) The Stack's name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

capabilities

(list)

The capabilities allowed in the stack.

creation_time

(datetime)

Time at which the stack was created.

description

(string)

User defined description associated with the stack.

disable_rollback

(boolean)

Boolean to enable or disable rollback on stack creation failures:

  • true : disable rollback
  • false : enable rollback
last_updated_time

(datetime)

The time the stack was last updated. This field will only be returned if the stack has been updated at least once.

notification_arns

(list)

SNS topic ARNs to which stack related events are published.

outputs

(list)

A list of output structures.

parameters

(list)

A list of Parameter structures.

stack_id

(string)

Unique identifier of the stack.

stack_name

(string)

The name associated with the stack.

stack_status

(string)

Current status of the stack.

stack_status_reason

(string)

Success/failure message associated with the stack status.

tags

(list)

A list of Tag s that specify cost allocation information for the stack.

timeout_in_minutes

(integer)

The amount of time within which stack creation should complete.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

cancel_update()

Cancels an update on the specified stack. If the call completes successfully, the stack will roll back the update and revert to the previous stack configuration.

Note

Only stacks that are in the UPDATE_IN_PROGRESS state can be canceled.

Request Syntax

response = stack.cancel_update()
Returns
None
delete()

Deletes a specified stack. Once the call completes successfully, stack deletion starts. Deleted stacks do not show up in the DescribeStacks API if the deletion has been completed successfully.

Request Syntax

response = stack.delete()
Returns
None
load()

Calls cloudformation.Client.describe_stacks() to update the attributes of the Stack resource

Request Syntax

stack.load()
Returns
None
reload()

Calls cloudformation.Client.describe_stacks() to update the attributes of the Stack resource

Request Syntax

stack.reload()
Returns
None
update(**kwargs)

Updates a stack as specified in the template. After the call completes successfully, the stack update starts. You can check the status of the stack via the DescribeStacks action.

To get a copy of the template for an existing stack, you can use the GetTemplate action.

Tags that were associated with this stack during creation time will still be associated with the stack after an UpdateStack operation.

For more information about creating an update template, updating a stack, and monitoring the progress of the update, see Updating a Stack .

Request Syntax

response = stack.update(
    TemplateBody='string',
    TemplateURL='string',
    UsePreviousTemplate=True|False,
    StackPolicyDuringUpdateBody='string',
    StackPolicyDuringUpdateURL='string',
    Parameters=[
        {
            'ParameterKey': 'string',
            'ParameterValue': 'string',
            'UsePreviousValue': True|False
        },
    ],
    Capabilities=[
        'CAPABILITY_IAM',
    ],
    StackPolicyBody='string',
    StackPolicyURL='string',
    NotificationARNs=[
        'string',
    ]
)
Parameters
  • TemplateBody (string) --

    Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. (For more information, go to Template Anatomy in the AWS CloudFormation User Guide.)

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • TemplateURL (string) --

    Location of file containing the template body. The URL must point to a template located in an S3 bucket in the same region as the stack. For more information, go to Template Anatomy in the AWS CloudFormation User Guide.

    Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.

  • UsePreviousTemplate (boolean) -- Reuse the existing template that is associated with the stack that you are updating.
  • StackPolicyDuringUpdateBody (string) --

    Structure containing the temporary overriding stack policy body. You can specify either the StackPolicyDuringUpdateBody or the StackPolicyDuringUpdateURL parameter, but not both.

    If you want to update protected resources, specify a temporary overriding stack policy during this update. If you do not specify a stack policy, the current policy that is associated with the stack will be used.

  • StackPolicyDuringUpdateURL (string) --

    Location of a file containing the temporary overriding stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyDuringUpdateBody or the StackPolicyDuringUpdateURL parameter, but not both.

    If you want to update protected resources, specify a temporary overriding stack policy during this update. If you do not specify a stack policy, the current policy that is associated with the stack will be used.

  • Parameters (list) --

    A list of Parameter structures that specify input parameters for the stack. For more information, see the Parameter data type.

    • (dict) --

      The Parameter data type.

      • ParameterKey (string) --

        The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.

      • ParameterValue (string) --

        The value associated with the parameter.

      • UsePreviousValue (boolean) --

        During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.

  • Capabilities (list) --

    A list of capabilities that you must specify before AWS CloudFormation can create or update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter. Currently, the only valid value is CAPABILITY_IAM , which is required for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack template contains these resources, we recommend that you review any permissions associated with them. If you don't specify this parameter, this action returns an InsufficientCapabilities error.

    • (string) --
  • StackPolicyBody (string) --

    Structure containing a new stack policy body. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.

    You might update the stack policy, for example, in order to protect a new resource that you created during a stack update. If you do not specify a stack policy, the current policy that is associated with the stack is unchanged.

  • StackPolicyURL (string) --

    Location of a file containing the updated stack policy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in the same region as the stack. You can specify either the StackPolicyBody or the StackPolicyURL parameter, but not both.

    You might update the stack policy, for example, in order to protect a new resource that you created during a stack update. If you do not specify a stack policy, the current policy that is associated with the stack is unchanged.

  • NotificationARNs (list) --

    Update the ARNs for the Amazon SNS topics that are associated with the stack.

    • (string) --
Return type

dict

Returns

Response Syntax

{
    'StackId': 'string'
}

Response Structure

  • (dict) --

    The output for a UpdateStack action.

    • StackId (string) --

      Unique identifier of the stack.

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Resource(logical_id)

Creates a StackResource resource.:

stack_resource = stack.Resource('logical_id')
Parameters
logical_id (string) -- The Resource's logical_id identifier. This must be set.
Return type
CloudFormation.StackResource
Returns
A StackResource resource

Collections

Collections provide an interface to iterate over and manipulate groups of resources. For more information about collections refer to the Resources Introduction Guide.

events
all()

Creates an iterable of all Event resources in the collection.

Request Syntax

event_iterator = stack.events.all()
Return type
list(cloudformation.Event)
Returns
A list of Event resources
filter(**kwargs)

Creates an iterable of all Event resources in the collection filtered by kwargs passed to method.

Request Syntax

event_iterator = stack.events.filter(
    NextToken='string'
)
Parameters
NextToken (string) --

String that identifies the start of the next list of events, if there is one.

Default: There is no default value.

Return type
list(cloudformation.Event)
Returns
A list of Event resources
limit(**kwargs)

Creates an iterable up to a specified amount of Event resources in the collection.

Request Syntax

event_iterator = stack.events.limit(
    count=123
)
Parameters
count (integer) -- The limit to the number of resources in the iterable.
Return type
list(cloudformation.Event)
Returns
A list of Event resources
page_size(**kwargs)

Creates an iterable of all Event resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

event_iterator = stack.events.page_size(
    count=123
)
Parameters
count (integer) -- The number of items returned by each service call
Return type
list(cloudformation.Event)
Returns
A list of Event resources
resource_summaries
all()

Creates an iterable of all StackResourceSummary resources in the collection.

Request Syntax

stack_resource_summary_iterator = stack.resource_summaries.all()
Return type
list(cloudformation.StackResourceSummary)
Returns
A list of StackResourceSummary resources
filter(**kwargs)

Creates an iterable of all StackResourceSummary resources in the collection filtered by kwargs passed to method.

Request Syntax

stack_resource_summary_iterator = stack.resource_summaries.filter(
    NextToken='string'
)
Parameters
NextToken (string) --

String that identifies the start of the next list of stack resource summaries, if there is one.

Default: There is no default value.

Return type
list(cloudformation.StackResourceSummary)
Returns
A list of StackResourceSummary resources
limit(**kwargs)

Creates an iterable up to a specified amount of StackResourceSummary resources in the collection.

Request Syntax

stack_resource_summary_iterator = stack.resource_summaries.limit(
    count=123
)
Parameters
count (integer) -- The limit to the number of resources in the iterable.
Return type
list(cloudformation.StackResourceSummary)
Returns
A list of StackResourceSummary resources
page_size(**kwargs)

Creates an iterable of all StackResourceSummary resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

stack_resource_summary_iterator = stack.resource_summaries.page_size(
    count=123
)
Parameters
count (integer) -- The number of items returned by each service call
Return type
list(cloudformation.StackResourceSummary)
Returns
A list of StackResourceSummary resources
StackResource
class CloudFormation.StackResource(stack_name, logical_id)

A resource representing an AWS CloudFormation StackResource:

import boto3

cloudformation = boto3.resource('cloudformation')
stack_resource = cloudformation.StackResource('stack_name','logical_id')
Parameters
  • stack_name (string) -- The StackResource's stack_name identifier. This must be set.
  • logical_id (string) -- The StackResource's logical_id identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

stack_name

(string) The StackResource's stack_name identifier. This must be set.

logical_id

(string) The StackResource's logical_id identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

description

(string)

User defined description associated with the resource.

last_updated_timestamp

(datetime)

Time the status was updated.

logical_resource_id

(string)

The logical name of the resource specified in the template.

metadata

(string)

The JSON format content of the Metadata attribute declared for the resource. For more information, see Metadata Attribute in the AWS CloudFormation User Guide.

physical_resource_id

(string)

The name or unique identifier that corresponds to a physical instance ID of a resource supported by AWS CloudFormation.

resource_status

(string)

Current status of the resource.

resource_status_reason

(string)

Success/failure message associated with the resource.

resource_type

(string)

Type of resource. ((For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

stack_id

(string)

Unique identifier of the stack.

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Stack()

Creates a Stack resource.:

stack = stack_resource.Stack()
Return type
CloudFormation.Stack
Returns
A Stack resource
StackResourceSummary
class CloudFormation.StackResourceSummary(stack_name, logical_id)

A resource representing an AWS CloudFormation StackResourceSummary:

import boto3

cloudformation = boto3.resource('cloudformation')
stack_resource_summary = cloudformation.StackResourceSummary('stack_name','logical_id')
Parameters
  • stack_name (string) -- The StackResourceSummary's stack_name identifier. This must be set.
  • logical_id (string) -- The StackResourceSummary's logical_id identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

stack_name

(string) The StackResourceSummary's stack_name identifier. This must be set.

logical_id

(string) The StackResourceSummary's logical_id identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

last_updated_timestamp

(datetime)

Time the status was updated.

logical_resource_id

(string)

The logical name of the resource specified in the template.

physical_resource_id

(string)

The name or unique identifier that corresponds to a physical instance ID of the resource.

resource_status

(string)

Current status of the resource.

resource_status_reason

(string)

Success/failure message associated with the resource.

resource_type

(string)

Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFormation User Guide.)

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Resource()

Creates a StackResource resource.:

stack_resource = stack_resource_summary.Resource()
Return type
CloudFormation.StackResource
Returns
A StackResource resource
CloudFront

Table of Contents

Client
class CloudFront.Client

A low-level client representing Amazon CloudFront:

import boto3

client = boto3.client('cloudfront')

These are the available methods:

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters
operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Returns
True if the operation can be paginated, False otherwise.
create_cloud_front_origin_access_identity(**kwargs)

Create a new origin access identity.

Request Syntax

response = client.create_cloud_front_origin_access_identity(
    CloudFrontOriginAccessIdentityConfig={
        'CallerReference': 'string',
        'Comment': 'string'
    }
)
Parameters
CloudFrontOriginAccessIdentityConfig (dict) --

[REQUIRED] The origin access identity's configuration information.

  • CallerReference (string) -- [REQUIRED] A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the CloudFrontOriginAccessIdentityConfig object), a new origin access identity is created. If the CallerReference is a value you already sent in a previous request to create an identity, and the content of the CloudFrontOriginAccessIdentityConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create an identity but the content of the CloudFrontOriginAccessIdentityConfig is different from the original request, CloudFront returns a CloudFrontOriginAccessIdentityAlreadyExists error.
  • Comment (string) -- [REQUIRED] Any comments you want to include about the origin access identity.
Return type
dict
Returns
Response Syntax
{
    'CloudFrontOriginAccessIdentity': {
        'Id': 'string',
        'S3CanonicalUserId': 'string',
        'CloudFrontOriginAccessIdentityConfig': {
            'CallerReference': 'string',
            'Comment': 'string'
        }
    },
    'Location': 'string',
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • CloudFrontOriginAccessIdentity (dict) -- The origin access identity's information.
      • Id (string) -- The ID for the origin access identity. For example: E74FTE3AJFJ256A.
      • S3CanonicalUserId (string) -- The Amazon S3 canonical user ID for the origin access identity, which you use when giving the origin access identity read permission to an object in Amazon S3.
      • CloudFrontOriginAccessIdentityConfig (dict) -- The current configuration information for the identity.
        • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the CloudFrontOriginAccessIdentityConfig object), a new origin access identity is created. If the CallerReference is a value you already sent in a previous request to create an identity, and the content of the CloudFrontOriginAccessIdentityConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create an identity but the content of the CloudFrontOriginAccessIdentityConfig is different from the original request, CloudFront returns a CloudFrontOriginAccessIdentityAlreadyExists error.
        • Comment (string) -- Any comments you want to include about the origin access identity.
    • Location (string) -- The fully qualified URI of the new origin access identity just created. For example: https://cloudfront.amazonaws.com/2010-11-01/origin-access-identity/cloudfront/E74FTE3AJFJ256A.
    • ETag (string) -- The current version of the origin access identity created.
create_distribution(**kwargs)

Create a new distribution.

Request Syntax

response = client.create_distribution(
    DistributionConfig={
        'CallerReference': 'string',
        'Aliases': {
            'Quantity': 123,
            'Items': [
                'string',
            ]
        },
        'DefaultRootObject': 'string',
        'Origins': {
            'Quantity': 123,
            'Items': [
                {
                    'Id': 'string',
                    'DomainName': 'string',
                    'OriginPath': 'string',
                    'S3OriginConfig': {
                        'OriginAccessIdentity': 'string'
                    },
                    'CustomOriginConfig': {
                        'HTTPPort': 123,
                        'HTTPSPort': 123,
                        'OriginProtocolPolicy': 'http-only'|'match-viewer'
                    }
                },
            ]
        },
        'DefaultCacheBehavior': {
            'TargetOriginId': 'string',
            'ForwardedValues': {
                'QueryString': True|False,
                'Cookies': {
                    'Forward': 'none'|'whitelist'|'all',
                    'WhitelistedNames': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
                'Headers': {
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                }
            },
            'TrustedSigners': {
                'Enabled': True|False,
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
            'MinTTL': 123,
            'AllowedMethods': {
                'Quantity': 123,
                'Items': [
                    'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                ],
                'CachedMethods': {
                    'Quantity': 123,
                    'Items': [
                        'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                    ]
                }
            },
            'SmoothStreaming': True|False,
            'DefaultTTL': 123,
            'MaxTTL': 123
        },
        'CacheBehaviors': {
            'Quantity': 123,
            'Items': [
                {
                    'PathPattern': 'string',
                    'TargetOriginId': 'string',
                    'ForwardedValues': {
                        'QueryString': True|False,
                        'Cookies': {
                            'Forward': 'none'|'whitelist'|'all',
                            'WhitelistedNames': {
                                'Quantity': 123,
                                'Items': [
                                    'string',
                                ]
                            }
                        },
                        'Headers': {
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        }
                    },
                    'TrustedSigners': {
                        'Enabled': True|False,
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    },
                    'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                    'MinTTL': 123,
                    'AllowedMethods': {
                        'Quantity': 123,
                        'Items': [
                            'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                        ],
                        'CachedMethods': {
                            'Quantity': 123,
                            'Items': [
                                'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                            ]
                        }
                    },
                    'SmoothStreaming': True|False,
                    'DefaultTTL': 123,
                    'MaxTTL': 123
                },
            ]
        },
        'CustomErrorResponses': {
            'Quantity': 123,
            'Items': [
                {
                    'ErrorCode': 123,
                    'ResponsePagePath': 'string',
                    'ResponseCode': 'string',
                    'ErrorCachingMinTTL': 123
                },
            ]
        },
        'Comment': 'string',
        'Logging': {
            'Enabled': True|False,
            'IncludeCookies': True|False,
            'Bucket': 'string',
            'Prefix': 'string'
        },
        'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
        'Enabled': True|False,
        'ViewerCertificate': {
            'IAMCertificateId': 'string',
            'CloudFrontDefaultCertificate': True|False,
            'SSLSupportMethod': 'sni-only'|'vip',
            'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
        },
        'Restrictions': {
            'GeoRestriction': {
                'RestrictionType': 'blacklist'|'whitelist'|'none',
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            }
        }
    }
)
Parameters
DistributionConfig (dict) --

[REQUIRED] The distribution's configuration information.

  • CallerReference (string) -- [REQUIRED] A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the DistributionConfig object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create a distribution, and the content of the DistributionConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of the DistributionConfig is different from the original request, CloudFront returns a DistributionAlreadyExists error.
  • Aliases (dict) -- A complex type that contains information about CNAMEs (alternate domain names), if any, for this distribution.
    • Quantity (integer) -- [REQUIRED] The number of CNAMEs, if any, for this distribution.
    • Items (list) -- Optional: A complex type that contains CNAME elements, if any, for this distribution. If Quantity is 0, you can omit Items.
      • (string) --
  • DefaultRootObject (string) -- The object that you want CloudFront to return (for example, index.html) when an end user requests the root URL for your distribution (http://www.example.com) instead of an object in your distribution (http://www.example.com/index.html). Specifying a default root object avoids exposing the contents of your distribution. If you don't want to specify a default root object when you create a distribution, include an empty DefaultRootObject element. To delete the default root object from an existing distribution, update the distribution configuration and include an empty DefaultRootObject element. To replace the default root object, update the distribution configuration and specify the new object.
  • Origins (dict) -- [REQUIRED] A complex type that contains information about origins for this distribution.
    • Quantity (integer) -- [REQUIRED] The number of origins for this distribution.
    • Items (list) -- A complex type that contains origins for this distribution.
      • (dict) -- A complex type that describes the Amazon S3 bucket or the HTTP server (for example, a web server) from which CloudFront gets your files.You must create at least one origin.
        • Id (string) -- [REQUIRED] A unique identifier for the origin. The value of Id must be unique within the distribution. You use the value of Id when you create a cache behavior. The Id identifies the origin that CloudFront routes a request to when the request matches the path pattern for that cache behavior.
        • DomainName (string) -- [REQUIRED] Amazon S3 origins: The DNS name of the Amazon S3 bucket from which you want CloudFront to get objects for this origin, for example, myawsbucket.s3.amazonaws.com. Custom origins: The DNS domain name for the HTTP server from which you want CloudFront to get objects for this origin, for example, www.example.com.
        • OriginPath (string) -- An optional element that causes CloudFront to request your content from a directory in your Amazon S3 bucket or your custom origin. When you include the OriginPath element, specify the directory name, beginning with a /. CloudFront appends the directory name to the value of DomainName.
        • S3OriginConfig (dict) -- A complex type that contains information about the Amazon S3 origin. If the origin is a custom origin, use the CustomOriginConfig element instead.
          • OriginAccessIdentity (string) -- [REQUIRED] The CloudFront origin access identity to associate with the origin. Use an origin access identity to configure the origin so that end users can only access objects in an Amazon S3 bucket through CloudFront. If you want end users to be able to access objects using either the CloudFront URL or the Amazon S3 URL, specify an empty OriginAccessIdentity element. To delete the origin access identity from an existing distribution, update the distribution configuration and include an empty OriginAccessIdentity element. To replace the origin access identity, update the distribution configuration and specify the new origin access identity. Use the format origin-access-identity/cloudfront/Id where Id is the value that CloudFront returned in the Id element when you created the origin access identity.
        • CustomOriginConfig (dict) -- A complex type that contains information about a custom origin. If the origin is an Amazon S3 bucket, use the S3OriginConfig element instead.
          • HTTPPort (integer) -- [REQUIRED] The HTTP port the custom origin listens on.
          • HTTPSPort (integer) -- [REQUIRED] The HTTPS port the custom origin listens on.
          • OriginProtocolPolicy (string) -- [REQUIRED] The origin protocol policy to apply to your origin.
  • DefaultCacheBehavior (dict) -- [REQUIRED] A complex type that describes the default cache behavior if you do not specify a CacheBehavior element or if files don't match any of the values of PathPattern in CacheBehavior elements.You must create exactly one default cache behavior.
    • TargetOriginId (string) -- [REQUIRED] The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
    • ForwardedValues (dict) -- [REQUIRED] A complex type that specifies how CloudFront handles query strings, cookies and headers.
      • QueryString (boolean) -- [REQUIRED] Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
      • Cookies (dict) -- [REQUIRED] A complex type that specifies how CloudFront handles cookies.
        • Forward (string) -- [REQUIRED] Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
        • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
          • Quantity (integer) -- [REQUIRED] The number of whitelisted cookies for this cache behavior.
          • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
            • (string) --
      • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
        • Quantity (integer) -- [REQUIRED] The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
        • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
          • (string) --
    • TrustedSigners (dict) -- [REQUIRED] A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
      • Enabled (boolean) -- [REQUIRED] Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
      • Quantity (integer) -- [REQUIRED] The number of trusted signers for this cache behavior.
      • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
        • (string) --
    • ViewerProtocolPolicy (string) -- [REQUIRED] Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
    • MinTTL (integer) -- [REQUIRED] The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
    • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
      • Quantity (integer) -- [REQUIRED] The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
      • Items (list) -- [REQUIRED] A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
        • (string) --
      • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
        • Quantity (integer) -- [REQUIRED] The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
        • Items (list) -- [REQUIRED] A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
          • (string) --
    • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
    • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
    • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
  • CacheBehaviors (dict) -- A complex type that contains zero or more CacheBehavior elements.
    • Quantity (integer) -- [REQUIRED] The number of cache behaviors for this distribution.
    • Items (list) -- Optional: A complex type that contains cache behaviors for this distribution. If Quantity is 0, you can omit Items.
      • (dict) -- A complex type that describes how CloudFront processes requests. You can create up to 10 cache behaviors.You must create at least as many cache behaviors (including the default cache behavior) as you have origins if you want CloudFront to distribute objects from all of the origins. Each cache behavior specifies the one origin from which you want CloudFront to get objects. If you have two origins and only the default cache behavior, the default cache behavior will cause CloudFront to get objects from one of the origins, but the other origin will never be used. If you don't want to specify any cache behaviors, include only an empty CacheBehaviors element. Don't include an empty CacheBehavior element, or CloudFront returns a MalformedXML error. To delete all cache behaviors in an existing distribution, update the distribution configuration and include only an empty CacheBehaviors element. To add, change, or remove one or more cache behaviors, update the distribution configuration and specify all of the cache behaviors that you want to include in the updated distribution.
        • PathPattern (string) -- [REQUIRED] The pattern (for example, images/*.jpg) that specifies which requests you want this cache behavior to apply to. When CloudFront receives an end-user request, the requested path is compared with path patterns in the order in which cache behaviors are listed in the distribution. The path pattern for the default cache behavior is * and cannot be changed. If the request for an object does not match the path pattern for any cache behaviors, CloudFront applies the behavior in the default cache behavior.
        • TargetOriginId (string) -- [REQUIRED] The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
        • ForwardedValues (dict) -- [REQUIRED] A complex type that specifies how CloudFront handles query strings, cookies and headers.
          • QueryString (boolean) -- [REQUIRED] Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
          • Cookies (dict) -- [REQUIRED] A complex type that specifies how CloudFront handles cookies.
            • Forward (string) -- [REQUIRED] Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
            • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
              • Quantity (integer) -- [REQUIRED] The number of whitelisted cookies for this cache behavior.
              • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
                • (string) --
          • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
            • Quantity (integer) -- [REQUIRED] The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
            • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
              • (string) --
        • TrustedSigners (dict) -- [REQUIRED] A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
          • Enabled (boolean) -- [REQUIRED] Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
          • Quantity (integer) -- [REQUIRED] The number of trusted signers for this cache behavior.
          • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
            • (string) --
        • ViewerProtocolPolicy (string) -- [REQUIRED] Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
        • MinTTL (integer) -- [REQUIRED] The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
          • Quantity (integer) -- [REQUIRED] The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
          • Items (list) -- [REQUIRED] A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
            • (string) --
          • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
            • Quantity (integer) -- [REQUIRED] The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
            • Items (list) -- [REQUIRED] A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
              • (string) --
        • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
        • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
  • CustomErrorResponses (dict) -- A complex type that contains zero or more CustomErrorResponse elements.
    • Quantity (integer) -- [REQUIRED] The number of custom error responses for this distribution.
    • Items (list) -- Optional: A complex type that contains custom error responses for this distribution. If Quantity is 0, you can omit Items.
      • (dict) -- A complex type that describes how you'd prefer CloudFront to respond to requests that result in either a 4xx or 5xx response. You can control whether a custom error page should be displayed, what the desired response code should be for this error page and how long should the error response be cached by CloudFront. If you don't want to specify any custom error responses, include only an empty CustomErrorResponses element. To delete all custom error responses in an existing distribution, update the distribution configuration and include only an empty CustomErrorResponses element. To add, change, or remove one or more custom error responses, update the distribution configuration and specify all of the custom error responses that you want to include in the updated distribution.
        • ErrorCode (integer) -- [REQUIRED] The 4xx or 5xx HTTP status code that you want to customize. For a list of HTTP status codes that you can customize, see CloudFront documentation.
        • ResponsePagePath (string) -- The path of the custom error page (for example, /custom_404.html). The path is relative to the distribution and must begin with a slash (/). If the path includes any non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters. Do not URL encode any other characters in the path, or CloudFront will not return the custom error page to the viewer.
        • ResponseCode (string) -- The HTTP status code that you want CloudFront to return with the custom error page to the viewer. For a list of HTTP status codes that you can replace, see CloudFront Documentation.
        • ErrorCachingMinTTL (integer) -- The minimum amount of time you want HTTP error codes to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated. You can specify a value from 0 to 31,536,000.
  • Comment (string) -- [REQUIRED] Any comments you want to include about the distribution.
  • Logging (dict) -- A complex type that controls whether access logs are written for the distribution.
    • Enabled (boolean) -- [REQUIRED] Specifies whether you want CloudFront to save access logs to an Amazon S3 bucket. If you do not want to enable logging when you create a distribution or if you want to disable logging for an existing distribution, specify false for Enabled, and specify empty Bucket and Prefix elements. If you specify false for Enabled but you specify values for Bucket, prefix and IncludeCookies, the values are automatically deleted.
    • IncludeCookies (boolean) -- [REQUIRED] Specifies whether you want CloudFront to include cookies in access logs, specify true for IncludeCookies. If you choose to include cookies in logs, CloudFront logs all cookies regardless of how you configure the cache behaviors for this distribution. If you do not want to include cookies when you create a distribution or if you want to disable include cookies for an existing distribution, specify false for IncludeCookies.
    • Bucket (string) -- [REQUIRED] The Amazon S3 bucket to store the access logs in, for example, myawslogbucket.s3.amazonaws.com.
    • Prefix (string) -- [REQUIRED] An optional string that you want CloudFront to prefix to the access log filenames for this distribution, for example, myprefix/. If you want to enable logging, but you do not want to specify a prefix, you still must include an empty Prefix element in the Logging element.
  • PriceClass (string) -- A complex type that contains information about price class for this distribution.
  • Enabled (boolean) -- [REQUIRED] Whether the distribution is enabled to accept end user requests for content.
  • ViewerCertificate (dict) -- A complex type that contains information about viewer certificates for this distribution.
    • IAMCertificateId (string) -- If you want viewers to use HTTPS to request your objects and you're using an alternate domain name in your object URLs (for example, https://example.com/logo.jpg), specify the IAM certificate identifier of the custom viewer certificate for this distribution. Specify either this value or CloudFrontDefaultCertificate.
    • CloudFrontDefaultCertificate (boolean) -- If you want viewers to use HTTPS to request your objects and you're using the CloudFront domain name of your distribution in your object URLs (for example, https://d111111abcdef8.cloudfront.net/logo.jpg), set to true. Omit this value if you are setting an IAMCertificateId.
    • SSLSupportMethod (string) -- If you specify a value for IAMCertificateId, you must also specify how you want CloudFront to serve HTTPS requests. Valid values are vip and sni-only. If you specify vip, CloudFront uses dedicated IP addresses for your content and can respond to HTTPS requests from any viewer. However, you must request permission to use this feature, and you incur additional monthly charges. If you specify sni-only, CloudFront can only respond to HTTPS requests from viewers that support Server Name Indication (SNI). All modern browsers support SNI, but some browsers still in use don't support SNI. Do not specify a value for SSLSupportMethod if you specified true for CloudFrontDefaultCertificate.
    • MinimumProtocolVersion (string) -- Specify the minimum version of the SSL protocol that you want CloudFront to use, SSLv3 or TLSv1, for HTTPS connections. CloudFront will serve your objects only to browsers or devices that support at least the SSL version that you specify. The TLSv1 protocol is more secure, so we recommend that you specify SSLv3 only if your users are using browsers or devices that don't support TLSv1. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using dedicated IP (if you specify vip for SSLSupportMethod), you can choose SSLv3 or TLSv1 as the MinimumProtocolVersion. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using SNI (if you specify sni-only for SSLSupportMethod), you must specify TLSv1 for MinimumProtocolVersion.
  • Restrictions (dict) -- A complex type that identifies ways in which you want to restrict distribution of your content.
    • GeoRestriction (dict) -- [REQUIRED] A complex type that controls the countries in which your content is distributed. For more information about geo restriction, go to Customizing Error Responses in the Amazon CloudFront Developer Guide. CloudFront determines the location of your users using MaxMind GeoIP databases. For information about the accuracy of these databases, see How accurate are your GeoIP databases? on the MaxMind website.
      • RestrictionType (string) -- [REQUIRED] The method that you want to use to restrict distribution of your content by country: - none: No geo restriction is enabled, meaning access to content is not restricted by client geo location. - blacklist: The Location elements specify the countries in which you do not want CloudFront to distribute your content. - whitelist: The Location elements specify the countries in which you want CloudFront to distribute your content.
      • Quantity (integer) -- [REQUIRED] When geo restriction is enabled, this is the number of countries in your whitelist or blacklist. Otherwise, when it is not enabled, Quantity is 0, and you can omit Items.
      • Items (list) -- A complex type that contains a Location element for each country in which you want CloudFront either to distribute your content (whitelist) or not distribute your content (blacklist). The Location element is a two-letter, uppercase country code for a country that you want to include in your blacklist or whitelist. Include one Location element for each country. CloudFront and MaxMind both use ISO 3166 country codes. For the current list of countries and the corresponding codes, see ISO 3166-1-alpha-2 code on the International Organization for Standardization website. You can also refer to the country list in the CloudFront console, which includes both country names and codes.
        • (string) --
Return type
dict
Returns
Response Syntax
{
    'Distribution': {
        'Id': 'string',
        'Status': 'string',
        'LastModifiedTime': datetime(2015, 1, 1),
        'InProgressInvalidationBatches': 123,
        'DomainName': 'string',
        'ActiveTrustedSigners': {
            'Enabled': True|False,
            'Quantity': 123,
            'Items': [
                {
                    'AwsAccountNumber': 'string',
                    'KeyPairIds': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
            ]
        },
        'DistributionConfig': {
            'CallerReference': 'string',
            'Aliases': {
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'DefaultRootObject': 'string',
            'Origins': {
                'Quantity': 123,
                'Items': [
                    {
                        'Id': 'string',
                        'DomainName': 'string',
                        'OriginPath': 'string',
                        'S3OriginConfig': {
                            'OriginAccessIdentity': 'string'
                        },
                        'CustomOriginConfig': {
                            'HTTPPort': 123,
                            'HTTPSPort': 123,
                            'OriginProtocolPolicy': 'http-only'|'match-viewer'
                        }
                    },
                ]
            },
            'DefaultCacheBehavior': {
                'TargetOriginId': 'string',
                'ForwardedValues': {
                    'QueryString': True|False,
                    'Cookies': {
                        'Forward': 'none'|'whitelist'|'all',
                        'WhitelistedNames': {
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        }
                    },
                    'Headers': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
                'TrustedSigners': {
                    'Enabled': True|False,
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                },
                'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                'MinTTL': 123,
                'AllowedMethods': {
                    'Quantity': 123,
                    'Items': [
                        'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                    ],
                    'CachedMethods': {
                        'Quantity': 123,
                        'Items': [
                            'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                        ]
                    }
                },
                'SmoothStreaming': True|False,
                'DefaultTTL': 123,
                'MaxTTL': 123
            },
            'CacheBehaviors': {
                'Quantity': 123,
                'Items': [
                    {
                        'PathPattern': 'string',
                        'TargetOriginId': 'string',
                        'ForwardedValues': {
                            'QueryString': True|False,
                            'Cookies': {
                                'Forward': 'none'|'whitelist'|'all',
                                'WhitelistedNames': {
                                    'Quantity': 123,
                                    'Items': [
                                        'string',
                                    ]
                                }
                            },
                            'Headers': {
                                'Quantity': 123,
                                'Items': [
                                    'string',
                                ]
                            }
                        },
                        'TrustedSigners': {
                            'Enabled': True|False,
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        },
                        'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                        'MinTTL': 123,
                        'AllowedMethods': {
                            'Quantity': 123,
                            'Items': [
                                'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                            ],
                            'CachedMethods': {
                                'Quantity': 123,
                                'Items': [
                                    'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                                ]
                            }
                        },
                        'SmoothStreaming': True|False,
                        'DefaultTTL': 123,
                        'MaxTTL': 123
                    },
                ]
            },
            'CustomErrorResponses': {
                'Quantity': 123,
                'Items': [
                    {
                        'ErrorCode': 123,
                        'ResponsePagePath': 'string',
                        'ResponseCode': 'string',
                        'ErrorCachingMinTTL': 123
                    },
                ]
            },
            'Comment': 'string',
            'Logging': {
                'Enabled': True|False,
                'IncludeCookies': True|False,
                'Bucket': 'string',
                'Prefix': 'string'
            },
            'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
            'Enabled': True|False,
            'ViewerCertificate': {
                'IAMCertificateId': 'string',
                'CloudFrontDefaultCertificate': True|False,
                'SSLSupportMethod': 'sni-only'|'vip',
                'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
            },
            'Restrictions': {
                'GeoRestriction': {
                    'RestrictionType': 'blacklist'|'whitelist'|'none',
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                }
            }
        }
    },
    'Location': 'string',
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • Distribution (dict) -- The distribution's information.
      • Id (string) -- The identifier for the distribution. For example: EDFDVBD632BHDS5.
      • Status (string) -- This response element indicates the current status of the distribution. When the status is Deployed, the distribution's information is fully propagated throughout the Amazon CloudFront system.
      • LastModifiedTime (datetime) -- The date and time the distribution was last modified.
      • InProgressInvalidationBatches (integer) -- The number of invalidation batches currently in progress.
      • DomainName (string) -- The domain name corresponding to the distribution. For example: d604721fxaaqy9.cloudfront.net.
      • ActiveTrustedSigners (dict) -- CloudFront automatically adds this element to the response only if you've set up the distribution to serve private content with signed URLs. The element lists the key pair IDs that CloudFront is aware of for each trusted signer. The Signer child element lists the AWS account number of the trusted signer (or an empty Self element if the signer is you). The Signer element also includes the IDs of any active key pairs associated with the trusted signer's AWS account. If no KeyPairId element appears for a Signer, that signer can't create working signed URLs.
        • Enabled (boolean) -- Each active trusted signer.
        • Quantity (integer) -- The number of unique trusted signers included in all cache behaviors. For example, if three cache behaviors all list the same three AWS accounts, the value of Quantity for ActiveTrustedSigners will be 3.
        • Items (list) -- A complex type that contains one Signer complex type for each unique trusted signer that is specified in the TrustedSigners complex type, including trusted signers in the default cache behavior and in all of the other cache behaviors.
          • (dict) -- A complex type that lists the AWS accounts that were included in the TrustedSigners complex type, as well as their active CloudFront key pair IDs, if any.
            • AwsAccountNumber (string) -- Specifies an AWS account that can create signed URLs. Values: self, which indicates that the AWS account that was used to create the distribution can created signed URLs, or an AWS account number. Omit the dashes in the account number.
            • KeyPairIds (dict) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
              • Quantity (integer) -- The number of active CloudFront key pairs for AwsAccountNumber.
              • Items (list) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
                • (string) --
      • DistributionConfig (dict) -- The current configuration information for the distribution.
        • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the DistributionConfig object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create a distribution, and the content of the DistributionConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of the DistributionConfig is different from the original request, CloudFront returns a DistributionAlreadyExists error.
        • Aliases (dict) -- A complex type that contains information about CNAMEs (alternate domain names), if any, for this distribution.
          • Quantity (integer) -- The number of CNAMEs, if any, for this distribution.
          • Items (list) -- Optional: A complex type that contains CNAME elements, if any, for this distribution. If Quantity is 0, you can omit Items.
            • (string) --
        • DefaultRootObject (string) -- The object that you want CloudFront to return (for example, index.html) when an end user requests the root URL for your distribution (http://www.example.com) instead of an object in your distribution (http://www.example.com/index.html). Specifying a default root object avoids exposing the contents of your distribution. If you don't want to specify a default root object when you create a distribution, include an empty DefaultRootObject element. To delete the default root object from an existing distribution, update the distribution configuration and include an empty DefaultRootObject element. To replace the default root object, update the distribution configuration and specify the new object.
        • Origins (dict) -- A complex type that contains information about origins for this distribution.
          • Quantity (integer) -- The number of origins for this distribution.
          • Items (list) -- A complex type that contains origins for this distribution.
            • (dict) -- A complex type that describes the Amazon S3 bucket or the HTTP server (for example, a web server) from which CloudFront gets your files.You must create at least one origin.
              • Id (string) -- A unique identifier for the origin. The value of Id must be unique within the distribution. You use the value of Id when you create a cache behavior. The Id identifies the origin that CloudFront routes a request to when the request matches the path pattern for that cache behavior.
              • DomainName (string) -- Amazon S3 origins: The DNS name of the Amazon S3 bucket from which you want CloudFront to get objects for this origin, for example, myawsbucket.s3.amazonaws.com. Custom origins: The DNS domain name for the HTTP server from which you want CloudFront to get objects for this origin, for example, www.example.com.
              • OriginPath (string) -- An optional element that causes CloudFront to request your content from a directory in your Amazon S3 bucket or your custom origin. When you include the OriginPath element, specify the directory name, beginning with a /. CloudFront appends the directory name to the value of DomainName.
              • S3OriginConfig (dict) -- A complex type that contains information about the Amazon S3 origin. If the origin is a custom origin, use the CustomOriginConfig element instead.
                • OriginAccessIdentity (string) -- The CloudFront origin access identity to associate with the origin. Use an origin access identity to configure the origin so that end users can only access objects in an Amazon S3 bucket through CloudFront. If you want end users to be able to access objects using either the CloudFront URL or the Amazon S3 URL, specify an empty OriginAccessIdentity element. To delete the origin access identity from an existing distribution, update the distribution configuration and include an empty OriginAccessIdentity element. To replace the origin access identity, update the distribution configuration and specify the new origin access identity. Use the format origin-access-identity/cloudfront/Id where Id is the value that CloudFront returned in the Id element when you created the origin access identity.
              • CustomOriginConfig (dict) -- A complex type that contains information about a custom origin. If the origin is an Amazon S3 bucket, use the S3OriginConfig element instead.
                • HTTPPort (integer) -- The HTTP port the custom origin listens on.
                • HTTPSPort (integer) -- The HTTPS port the custom origin listens on.
                • OriginProtocolPolicy (string) -- The origin protocol policy to apply to your origin.
        • DefaultCacheBehavior (dict) -- A complex type that describes the default cache behavior if you do not specify a CacheBehavior element or if files don't match any of the values of PathPattern in CacheBehavior elements.You must create exactly one default cache behavior.
          • TargetOriginId (string) -- The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
          • ForwardedValues (dict) -- A complex type that specifies how CloudFront handles query strings, cookies and headers.
            • QueryString (boolean) -- Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
            • Cookies (dict) -- A complex type that specifies how CloudFront handles cookies.
              • Forward (string) -- Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
              • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
                • Quantity (integer) -- The number of whitelisted cookies for this cache behavior.
                • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
                  • (string) --
            • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
              • Quantity (integer) -- The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
              • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
                • (string) --
          • TrustedSigners (dict) -- A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
            • Enabled (boolean) -- Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
            • Quantity (integer) -- The number of trusted signers for this cache behavior.
            • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
              • (string) --
          • ViewerProtocolPolicy (string) -- Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
          • MinTTL (integer) -- The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
          • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
            • Quantity (integer) -- The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
            • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
              • (string) --
            • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
              • Quantity (integer) -- The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
              • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
                • (string) --
          • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
          • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
          • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • CacheBehaviors (dict) -- A complex type that contains zero or more CacheBehavior elements.
          • Quantity (integer) -- The number of cache behaviors for this distribution.
          • Items (list) -- Optional: A complex type that contains cache behaviors for this distribution. If Quantity is 0, you can omit Items.
            • (dict) -- A complex type that describes how CloudFront processes requests. You can create up to 10 cache behaviors.You must create at least as many cache behaviors (including the default cache behavior) as you have origins if you want CloudFront to distribute objects from all of the origins. Each cache behavior specifies the one origin from which you want CloudFront to get objects. If you have two origins and only the default cache behavior, the default cache behavior will cause CloudFront to get objects from one of the origins, but the other origin will never be used. If you don't want to specify any cache behaviors, include only an empty CacheBehaviors element. Don't include an empty CacheBehavior element, or CloudFront returns a MalformedXML error. To delete all cache behaviors in an existing distribution, update the distribution configuration and include only an empty CacheBehaviors element. To add, change, or remove one or more cache behaviors, update the distribution configuration and specify all of the cache behaviors that you want to include in the updated distribution.
              • PathPattern (string) -- The pattern (for example, images/*.jpg) that specifies which requests you want this cache behavior to apply to. When CloudFront receives an end-user request, the requested path is compared with path patterns in the order in which cache behaviors are listed in the distribution. The path pattern for the default cache behavior is * and cannot be changed. If the request for an object does not match the path pattern for any cache behaviors, CloudFront applies the behavior in the default cache behavior.
              • TargetOriginId (string) -- The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
              • ForwardedValues (dict) -- A complex type that specifies how CloudFront handles query strings, cookies and headers.
                • QueryString (boolean) -- Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
                • Cookies (dict) -- A complex type that specifies how CloudFront handles cookies.
                  • Forward (string) -- Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
                  • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
                    • Quantity (integer) -- The number of whitelisted cookies for this cache behavior.
                    • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
                      • (string) --
                • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
                  • Quantity (integer) -- The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
                  • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
                    • (string) --
              • TrustedSigners (dict) -- A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
                • Enabled (boolean) -- Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
                • Quantity (integer) -- The number of trusted signers for this cache behavior.
                • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
                  • (string) --
              • ViewerProtocolPolicy (string) -- Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
              • MinTTL (integer) -- The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
              • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
                • Quantity (integer) -- The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
                • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
                  • (string) --
                • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
                  • Quantity (integer) -- The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
                  • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
                    • (string) --
              • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
              • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
              • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • CustomErrorResponses (dict) -- A complex type that contains zero or more CustomErrorResponse elements.
          • Quantity (integer) -- The number of custom error responses for this distribution.
          • Items (list) -- Optional: A complex type that contains custom error responses for this distribution. If Quantity is 0, you can omit Items.
            • (dict) -- A complex type that describes how you'd prefer CloudFront to respond to requests that result in either a 4xx or 5xx response. You can control whether a custom error page should be displayed, what the desired response code should be for this error page and how long should the error response be cached by CloudFront. If you don't want to specify any custom error responses, include only an empty CustomErrorResponses element. To delete all custom error responses in an existing distribution, update the distribution configuration and include only an empty CustomErrorResponses element. To add, change, or remove one or more custom error responses, update the distribution configuration and specify all of the custom error responses that you want to include in the updated distribution.
              • ErrorCode (integer) -- The 4xx or 5xx HTTP status code that you want to customize. For a list of HTTP status codes that you can customize, see CloudFront documentation.
              • ResponsePagePath (string) -- The path of the custom error page (for example, /custom_404.html). The path is relative to the distribution and must begin with a slash (/). If the path includes any non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters. Do not URL encode any other characters in the path, or CloudFront will not return the custom error page to the viewer.
              • ResponseCode (string) -- The HTTP status code that you want CloudFront to return with the custom error page to the viewer. For a list of HTTP status codes that you can replace, see CloudFront Documentation.
              • ErrorCachingMinTTL (integer) -- The minimum amount of time you want HTTP error codes to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated. You can specify a value from 0 to 31,536,000.
        • Comment (string) -- Any comments you want to include about the distribution.
        • Logging (dict) -- A complex type that controls whether access logs are written for the distribution.
          • Enabled (boolean) -- Specifies whether you want CloudFront to save access logs to an Amazon S3 bucket. If you do not want to enable logging when you create a distribution or if you want to disable logging for an existing distribution, specify false for Enabled, and specify empty Bucket and Prefix elements. If you specify false for Enabled but you specify values for Bucket, prefix and IncludeCookies, the values are automatically deleted.
          • IncludeCookies (boolean) -- Specifies whether you want CloudFront to include cookies in access logs, specify true for IncludeCookies. If you choose to include cookies in logs, CloudFront logs all cookies regardless of how you configure the cache behaviors for this distribution. If you do not want to include cookies when you create a distribution or if you want to disable include cookies for an existing distribution, specify false for IncludeCookies.
          • Bucket (string) -- The Amazon S3 bucket to store the access logs in, for example, myawslogbucket.s3.amazonaws.com.
          • Prefix (string) -- An optional string that you want CloudFront to prefix to the access log filenames for this distribution, for example, myprefix/. If you want to enable logging, but you do not want to specify a prefix, you still must include an empty Prefix element in the Logging element.
        • PriceClass (string) -- A complex type that contains information about price class for this distribution.
        • Enabled (boolean) -- Whether the distribution is enabled to accept end user requests for content.
        • ViewerCertificate (dict) -- A complex type that contains information about viewer certificates for this distribution.
          • IAMCertificateId (string) -- If you want viewers to use HTTPS to request your objects and you're using an alternate domain name in your object URLs (for example, https://example.com/logo.jpg), specify the IAM certificate identifier of the custom viewer certificate for this distribution. Specify either this value or CloudFrontDefaultCertificate.
          • CloudFrontDefaultCertificate (boolean) -- If you want viewers to use HTTPS to request your objects and you're using the CloudFront domain name of your distribution in your object URLs (for example, https://d111111abcdef8.cloudfront.net/logo.jpg), set to true. Omit this value if you are setting an IAMCertificateId.
          • SSLSupportMethod (string) -- If you specify a value for IAMCertificateId, you must also specify how you want CloudFront to serve HTTPS requests. Valid values are vip and sni-only. If you specify vip, CloudFront uses dedicated IP addresses for your content and can respond to HTTPS requests from any viewer. However, you must request permission to use this feature, and you incur additional monthly charges. If you specify sni-only, CloudFront can only respond to HTTPS requests from viewers that support Server Name Indication (SNI). All modern browsers support SNI, but some browsers still in use don't support SNI. Do not specify a value for SSLSupportMethod if you specified true for CloudFrontDefaultCertificate.
          • MinimumProtocolVersion (string) -- Specify the minimum version of the SSL protocol that you want CloudFront to use, SSLv3 or TLSv1, for HTTPS connections. CloudFront will serve your objects only to browsers or devices that support at least the SSL version that you specify. The TLSv1 protocol is more secure, so we recommend that you specify SSLv3 only if your users are using browsers or devices that don't support TLSv1. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using dedicated IP (if you specify vip for SSLSupportMethod), you can choose SSLv3 or TLSv1 as the MinimumProtocolVersion. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using SNI (if you specify sni-only for SSLSupportMethod), you must specify TLSv1 for MinimumProtocolVersion.
        • Restrictions (dict) -- A complex type that identifies ways in which you want to restrict distribution of your content.
          • GeoRestriction (dict) -- A complex type that controls the countries in which your content is distributed. For more information about geo restriction, go to Customizing Error Responses in the Amazon CloudFront Developer Guide. CloudFront determines the location of your users using MaxMind GeoIP databases. For information about the accuracy of these databases, see How accurate are your GeoIP databases? on the MaxMind website.
            • RestrictionType (string) -- The method that you want to use to restrict distribution of your content by country: - none: No geo restriction is enabled, meaning access to content is not restricted by client geo location. - blacklist: The Location elements specify the countries in which you do not want CloudFront to distribute your content. - whitelist: The Location elements specify the countries in which you want CloudFront to distribute your content.
            • Quantity (integer) -- When geo restriction is enabled, this is the number of countries in your whitelist or blacklist. Otherwise, when it is not enabled, Quantity is 0, and you can omit Items.
            • Items (list) -- A complex type that contains a Location element for each country in which you want CloudFront either to distribute your content (whitelist) or not distribute your content (blacklist). The Location element is a two-letter, uppercase country code for a country that you want to include in your blacklist or whitelist. Include one Location element for each country. CloudFront and MaxMind both use ISO 3166 country codes. For the current list of countries and the corresponding codes, see ISO 3166-1-alpha-2 code on the International Organization for Standardization website. You can also refer to the country list in the CloudFront console, which includes both country names and codes.
              • (string) --
    • Location (string) -- The fully qualified URI of the new distribution resource just created. For example: https://cloudfront.amazonaws.com/2010-11-01/distribution/EDFDVBD632BHDS5.
    • ETag (string) -- The current version of the distribution created.
create_invalidation(**kwargs)

Create a new invalidation.

Request Syntax

response = client.create_invalidation(
    DistributionId='string',
    InvalidationBatch={
        'Paths': {
            'Quantity': 123,
            'Items': [
                'string',
            ]
        },
        'CallerReference': 'string'
    }
)
Parameters
  • DistributionId (string) -- [REQUIRED] The distribution's id.
  • InvalidationBatch (dict) --

    [REQUIRED] The batch information for the invalidation.

    • Paths (dict) -- [REQUIRED] The path of the object to invalidate. The path is relative to the distribution and must begin with a slash (/). You must enclose each invalidation object with the Path element tags. If the path includes non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters. Do not URL encode any other characters in the path, or CloudFront will not invalidate the old version of the updated object.
      • Quantity (integer) -- [REQUIRED] The number of objects that you want to invalidate.
      • Items (list) -- A complex type that contains a list of the objects that you want to invalidate.
        • (string) --
    • CallerReference (string) -- [REQUIRED] A unique name that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the Path object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create an invalidation batch, and the content of each Path element is identical to the original request, the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of any Path is different from the original request, CloudFront returns an InvalidationBatchAlreadyExists error.
Return type

dict

Returns

Response Syntax

{
    'Location': 'string',
    'Invalidation': {
        'Id': 'string',
        'Status': 'string',
        'CreateTime': datetime(2015, 1, 1),
        'InvalidationBatch': {
            'Paths': {
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'CallerReference': 'string'
        }
    }
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • Location (string) -- The fully qualified URI of the distribution and invalidation batch request, including the Invalidation ID.
    • Invalidation (dict) -- The invalidation's information.
      • Id (string) -- The identifier for the invalidation request. For example: IDFDVBD632BHDS5.
      • Status (string) -- The status of the invalidation request. When the invalidation batch is finished, the status is Completed.
      • CreateTime (datetime) -- The date and time the invalidation request was first made.
      • InvalidationBatch (dict) -- The current invalidation information for the batch request.
        • Paths (dict) -- The path of the object to invalidate. The path is relative to the distribution and must begin with a slash (/). You must enclose each invalidation object with the Path element tags. If the path includes non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters. Do not URL encode any other characters in the path, or CloudFront will not invalidate the old version of the updated object.
          • Quantity (integer) -- The number of objects that you want to invalidate.
          • Items (list) -- A complex type that contains a list of the objects that you want to invalidate.
            • (string) --
        • CallerReference (string) -- A unique name that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the Path object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create an invalidation batch, and the content of each Path element is identical to the original request, the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of any Path is different from the original request, CloudFront returns an InvalidationBatchAlreadyExists error.

create_streaming_distribution(**kwargs)

Create a new streaming distribution.

Request Syntax

response = client.create_streaming_distribution(
    StreamingDistributionConfig={
        'CallerReference': 'string',
        'S3Origin': {
            'DomainName': 'string',
            'OriginAccessIdentity': 'string'
        },
        'Aliases': {
            'Quantity': 123,
            'Items': [
                'string',
            ]
        },
        'Comment': 'string',
        'Logging': {
            'Enabled': True|False,
            'Bucket': 'string',
            'Prefix': 'string'
        },
        'TrustedSigners': {
            'Enabled': True|False,
            'Quantity': 123,
            'Items': [
                'string',
            ]
        },
        'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
        'Enabled': True|False
    }
)
Parameters
StreamingDistributionConfig (dict) --

[REQUIRED] The streaming distribution's configuration information.

  • CallerReference (string) -- [REQUIRED] A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the StreamingDistributionConfig object), a new streaming distribution is created. If the CallerReference is a value you already sent in a previous request to create a streaming distribution, and the content of the StreamingDistributionConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a streaming distribution but the content of the StreamingDistributionConfig is different from the original request, CloudFront returns a DistributionAlreadyExists error.
  • S3Origin (dict) -- [REQUIRED] A complex type that contains information about the Amazon S3 bucket from which you want CloudFront to get your media files for distribution.
    • DomainName (string) -- [REQUIRED] The DNS name of the S3 origin.
    • OriginAccessIdentity (string) -- [REQUIRED] Your S3 origin's origin access identity.
  • Aliases (dict) -- A complex type that contains information about CNAMEs (alternate domain names), if any, for this streaming distribution.
    • Quantity (integer) -- [REQUIRED] The number of CNAMEs, if any, for this distribution.
    • Items (list) -- Optional: A complex type that contains CNAME elements, if any, for this distribution. If Quantity is 0, you can omit Items.
      • (string) --
  • Comment (string) -- [REQUIRED] Any comments you want to include about the streaming distribution.
  • Logging (dict) -- A complex type that controls whether access logs are written for the streaming distribution.
    • Enabled (boolean) -- [REQUIRED] Specifies whether you want CloudFront to save access logs to an Amazon S3 bucket. If you do not want to enable logging when you create a streaming distribution or if you want to disable logging for an existing streaming distribution, specify false for Enabled, and specify empty Bucket and Prefix elements. If you specify false for Enabled but you specify values for Bucket and Prefix, the values are automatically deleted.
    • Bucket (string) -- [REQUIRED] The Amazon S3 bucket to store the access logs in, for example, myawslogbucket.s3.amazonaws.com.
    • Prefix (string) -- [REQUIRED] An optional string that you want CloudFront to prefix to the access log filenames for this streaming distribution, for example, myprefix/. If you want to enable logging, but you do not want to specify a prefix, you still must include an empty Prefix element in the Logging element.
  • TrustedSigners (dict) -- [REQUIRED] A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
    • Enabled (boolean) -- [REQUIRED] Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
    • Quantity (integer) -- [REQUIRED] The number of trusted signers for this cache behavior.
    • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
      • (string) --
  • PriceClass (string) -- A complex type that contains information about price class for this streaming distribution.
  • Enabled (boolean) -- [REQUIRED] Whether the streaming distribution is enabled to accept end user requests for content.
Return type
dict
Returns
Response Syntax
{
    'StreamingDistribution': {
        'Id': 'string',
        'Status': 'string',
        'LastModifiedTime': datetime(2015, 1, 1),
        'DomainName': 'string',
        'ActiveTrustedSigners': {
            'Enabled': True|False,
            'Quantity': 123,
            'Items': [
                {
                    'AwsAccountNumber': 'string',
                    'KeyPairIds': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
            ]
        },
        'StreamingDistributionConfig': {
            'CallerReference': 'string',
            'S3Origin': {
                'DomainName': 'string',
                'OriginAccessIdentity': 'string'
            },
            'Aliases': {
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'Comment': 'string',
            'Logging': {
                'Enabled': True|False,
                'Bucket': 'string',
                'Prefix': 'string'
            },
            'TrustedSigners': {
                'Enabled': True|False,
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
            'Enabled': True|False
        }
    },
    'Location': 'string',
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • StreamingDistribution (dict) -- The streaming distribution's information.
      • Id (string) -- The identifier for the streaming distribution. For example: EGTXBD79H29TRA8.
      • Status (string) -- The current status of the streaming distribution. When the status is Deployed, the distribution's information is fully propagated throughout the Amazon CloudFront system.
      • LastModifiedTime (datetime) -- The date and time the distribution was last modified.
      • DomainName (string) -- The domain name corresponding to the streaming distribution. For example: s5c39gqb8ow64r.cloudfront.net.
      • ActiveTrustedSigners (dict) -- CloudFront automatically adds this element to the response only if you've set up the distribution to serve private content with signed URLs. The element lists the key pair IDs that CloudFront is aware of for each trusted signer. The Signer child element lists the AWS account number of the trusted signer (or an empty Self element if the signer is you). The Signer element also includes the IDs of any active key pairs associated with the trusted signer's AWS account. If no KeyPairId element appears for a Signer, that signer can't create working signed URLs.
        • Enabled (boolean) -- Each active trusted signer.
        • Quantity (integer) -- The number of unique trusted signers included in all cache behaviors. For example, if three cache behaviors all list the same three AWS accounts, the value of Quantity for ActiveTrustedSigners will be 3.
        • Items (list) -- A complex type that contains one Signer complex type for each unique trusted signer that is specified in the TrustedSigners complex type, including trusted signers in the default cache behavior and in all of the other cache behaviors.
          • (dict) -- A complex type that lists the AWS accounts that were included in the TrustedSigners complex type, as well as their active CloudFront key pair IDs, if any.
            • AwsAccountNumber (string) -- Specifies an AWS account that can create signed URLs. Values: self, which indicates that the AWS account that was used to create the distribution can created signed URLs, or an AWS account number. Omit the dashes in the account number.
            • KeyPairIds (dict) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
              • Quantity (integer) -- The number of active CloudFront key pairs for AwsAccountNumber.
              • Items (list) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
                • (string) --
      • StreamingDistributionConfig (dict) -- The current configuration information for the streaming distribution.
        • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the StreamingDistributionConfig object), a new streaming distribution is created. If the CallerReference is a value you already sent in a previous request to create a streaming distribution, and the content of the StreamingDistributionConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a streaming distribution but the content of the StreamingDistributionConfig is different from the original request, CloudFront returns a DistributionAlreadyExists error.
        • S3Origin (dict) -- A complex type that contains information about the Amazon S3 bucket from which you want CloudFront to get your media files for distribution.
          • DomainName (string) -- The DNS name of the S3 origin.
          • OriginAccessIdentity (string) -- Your S3 origin's origin access identity.
        • Aliases (dict) -- A complex type that contains information about CNAMEs (alternate domain names), if any, for this streaming distribution.
          • Quantity (integer) -- The number of CNAMEs, if any, for this distribution.
          • Items (list) -- Optional: A complex type that contains CNAME elements, if any, for this distribution. If Quantity is 0, you can omit Items.
            • (string) --
        • Comment (string) -- Any comments you want to include about the streaming distribution.
        • Logging (dict) -- A complex type that controls whether access logs are written for the streaming distribution.
          • Enabled (boolean) -- Specifies whether you want CloudFront to save access logs to an Amazon S3 bucket. If you do not want to enable logging when you create a streaming distribution or if you want to disable logging for an existing streaming distribution, specify false for Enabled, and specify empty Bucket and Prefix elements. If you specify false for Enabled but you specify values for Bucket and Prefix, the values are automatically deleted.
          • Bucket (string) -- The Amazon S3 bucket to store the access logs in, for example, myawslogbucket.s3.amazonaws.com.
          • Prefix (string) -- An optional string that you want CloudFront to prefix to the access log filenames for this streaming distribution, for example, myprefix/. If you want to enable logging, but you do not want to specify a prefix, you still must include an empty Prefix element in the Logging element.
        • TrustedSigners (dict) -- A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
          • Enabled (boolean) -- Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
          • Quantity (integer) -- The number of trusted signers for this cache behavior.
          • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
            • (string) --
        • PriceClass (string) -- A complex type that contains information about price class for this streaming distribution.
        • Enabled (boolean) -- Whether the streaming distribution is enabled to accept end user requests for content.
    • Location (string) -- The fully qualified URI of the new streaming distribution resource just created. For example: https://cloudfront.amazonaws.com/2010-11-01/streaming-distribution/EGTXBD79H29TRA8.
    • ETag (string) -- The current version of the streaming distribution created.
delete_cloud_front_origin_access_identity(**kwargs)

Delete an origin access identity.

Request Syntax

response = client.delete_cloud_front_origin_access_identity(
    Id='string',
    IfMatch='string'
)
Parameters
  • Id (string) -- [REQUIRED] The origin access identity's id.
  • IfMatch (string) -- The value of the ETag header you received from a previous GET or PUT request. For example: E2QWRUHAPOMQZL.
Returns

None

delete_distribution(**kwargs)

Delete a distribution.

Request Syntax

response = client.delete_distribution(
    Id='string',
    IfMatch='string'
)
Parameters
  • Id (string) -- [REQUIRED] The distribution id.
  • IfMatch (string) -- The value of the ETag header you received when you disabled the distribution. For example: E2QWRUHAPOMQZL.
Returns

None

delete_streaming_distribution(**kwargs)

Delete a streaming distribution.

Request Syntax

response = client.delete_streaming_distribution(
    Id='string',
    IfMatch='string'
)
Parameters
  • Id (string) -- [REQUIRED] The distribution id.
  • IfMatch (string) -- The value of the ETag header you received when you disabled the streaming distribution. For example: E2QWRUHAPOMQZL.
Returns

None

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters
  • ClientMethod (string) -- The client method to presign for
  • Params (dict) -- The parameters normally passed to ClientMethod.
  • ExpiresIn (int) -- The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)
  • HttpMethod (string) -- The http method to use on the generated url. By default, the http method is whatever is used in the method's model.
Returns

The presigned url

get_cloud_front_origin_access_identity(**kwargs)

Get the information about an origin access identity.

Request Syntax

response = client.get_cloud_front_origin_access_identity(
    Id='string'
)
Parameters
Id (string) -- [REQUIRED] The identity's id.
Return type
dict
Returns
Response Syntax
{
    'CloudFrontOriginAccessIdentity': {
        'Id': 'string',
        'S3CanonicalUserId': 'string',
        'CloudFrontOriginAccessIdentityConfig': {
            'CallerReference': 'string',
            'Comment': 'string'
        }
    },
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • CloudFrontOriginAccessIdentity (dict) -- The origin access identity's information.
      • Id (string) -- The ID for the origin access identity. For example: E74FTE3AJFJ256A.
      • S3CanonicalUserId (string) -- The Amazon S3 canonical user ID for the origin access identity, which you use when giving the origin access identity read permission to an object in Amazon S3.
      • CloudFrontOriginAccessIdentityConfig (dict) -- The current configuration information for the identity.
        • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the CloudFrontOriginAccessIdentityConfig object), a new origin access identity is created. If the CallerReference is a value you already sent in a previous request to create an identity, and the content of the CloudFrontOriginAccessIdentityConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create an identity but the content of the CloudFrontOriginAccessIdentityConfig is different from the original request, CloudFront returns a CloudFrontOriginAccessIdentityAlreadyExists error.
        • Comment (string) -- Any comments you want to include about the origin access identity.
    • ETag (string) -- The current version of the origin access identity's information. For example: E2QWRUHAPOMQZL.
get_cloud_front_origin_access_identity_config(**kwargs)

Get the configuration information about an origin access identity.

Request Syntax

response = client.get_cloud_front_origin_access_identity_config(
    Id='string'
)
Parameters
Id (string) -- [REQUIRED] The identity's id.
Return type
dict
Returns
Response Syntax
{
    'CloudFrontOriginAccessIdentityConfig': {
        'CallerReference': 'string',
        'Comment': 'string'
    },
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • CloudFrontOriginAccessIdentityConfig (dict) -- The origin access identity's configuration information.
      • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the CloudFrontOriginAccessIdentityConfig object), a new origin access identity is created. If the CallerReference is a value you already sent in a previous request to create an identity, and the content of the CloudFrontOriginAccessIdentityConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create an identity but the content of the CloudFrontOriginAccessIdentityConfig is different from the original request, CloudFront returns a CloudFrontOriginAccessIdentityAlreadyExists error.
      • Comment (string) -- Any comments you want to include about the origin access identity.
    • ETag (string) -- The current version of the configuration. For example: E2QWRUHAPOMQZL.
get_distribution(**kwargs)

Get the information about a distribution.

Request Syntax

response = client.get_distribution(
    Id='string'
)
Parameters
Id (string) -- [REQUIRED] The distribution's id.
Return type
dict
Returns
Response Syntax
{
    'Distribution': {
        'Id': 'string',
        'Status': 'string',
        'LastModifiedTime': datetime(2015, 1, 1),
        'InProgressInvalidationBatches': 123,
        'DomainName': 'string',
        'ActiveTrustedSigners': {
            'Enabled': True|False,
            'Quantity': 123,
            'Items': [
                {
                    'AwsAccountNumber': 'string',
                    'KeyPairIds': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
            ]
        },
        'DistributionConfig': {
            'CallerReference': 'string',
            'Aliases': {
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'DefaultRootObject': 'string',
            'Origins': {
                'Quantity': 123,
                'Items': [
                    {
                        'Id': 'string',
                        'DomainName': 'string',
                        'OriginPath': 'string',
                        'S3OriginConfig': {
                            'OriginAccessIdentity': 'string'
                        },
                        'CustomOriginConfig': {
                            'HTTPPort': 123,
                            'HTTPSPort': 123,
                            'OriginProtocolPolicy': 'http-only'|'match-viewer'
                        }
                    },
                ]
            },
            'DefaultCacheBehavior': {
                'TargetOriginId': 'string',
                'ForwardedValues': {
                    'QueryString': True|False,
                    'Cookies': {
                        'Forward': 'none'|'whitelist'|'all',
                        'WhitelistedNames': {
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        }
                    },
                    'Headers': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
                'TrustedSigners': {
                    'Enabled': True|False,
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                },
                'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                'MinTTL': 123,
                'AllowedMethods': {
                    'Quantity': 123,
                    'Items': [
                        'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                    ],
                    'CachedMethods': {
                        'Quantity': 123,
                        'Items': [
                            'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                        ]
                    }
                },
                'SmoothStreaming': True|False,
                'DefaultTTL': 123,
                'MaxTTL': 123
            },
            'CacheBehaviors': {
                'Quantity': 123,
                'Items': [
                    {
                        'PathPattern': 'string',
                        'TargetOriginId': 'string',
                        'ForwardedValues': {
                            'QueryString': True|False,
                            'Cookies': {
                                'Forward': 'none'|'whitelist'|'all',
                                'WhitelistedNames': {
                                    'Quantity': 123,
                                    'Items': [
                                        'string',
                                    ]
                                }
                            },
                            'Headers': {
                                'Quantity': 123,
                                'Items': [
                                    'string',
                                ]
                            }
                        },
                        'TrustedSigners': {
                            'Enabled': True|False,
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        },
                        'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                        'MinTTL': 123,
                        'AllowedMethods': {
                            'Quantity': 123,
                            'Items': [
                                'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                            ],
                            'CachedMethods': {
                                'Quantity': 123,
                                'Items': [
                                    'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                                ]
                            }
                        },
                        'SmoothStreaming': True|False,
                        'DefaultTTL': 123,
                        'MaxTTL': 123
                    },
                ]
            },
            'CustomErrorResponses': {
                'Quantity': 123,
                'Items': [
                    {
                        'ErrorCode': 123,
                        'ResponsePagePath': 'string',
                        'ResponseCode': 'string',
                        'ErrorCachingMinTTL': 123
                    },
                ]
            },
            'Comment': 'string',
            'Logging': {
                'Enabled': True|False,
                'IncludeCookies': True|False,
                'Bucket': 'string',
                'Prefix': 'string'
            },
            'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
            'Enabled': True|False,
            'ViewerCertificate': {
                'IAMCertificateId': 'string',
                'CloudFrontDefaultCertificate': True|False,
                'SSLSupportMethod': 'sni-only'|'vip',
                'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
            },
            'Restrictions': {
                'GeoRestriction': {
                    'RestrictionType': 'blacklist'|'whitelist'|'none',
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                }
            }
        }
    },
    'ETag': 'string'
}

Response Structure

  • (dict) -- The returned result of the corresponding request.
    • Distribution (dict) -- The distribution's information.
      • Id (string) -- The identifier for the distribution. For example: EDFDVBD632BHDS5.
      • Status (string) -- This response element indicates the current status of the distribution. When the status is Deployed, the distribution's information is fully propagated throughout the Amazon CloudFront system.
      • LastModifiedTime (datetime) -- The date and time the distribution was last modified.
      • InProgressInvalidationBatches (integer) -- The number of invalidation batches currently in progress.
      • DomainName (string) -- The domain name corresponding to the distribution. For example: d604721fxaaqy9.cloudfront.net.
      • ActiveTrustedSigners (dict) -- CloudFront automatically adds this element to the response only if you've set up the distribution to serve private content with signed URLs. The element lists the key pair IDs that CloudFront is aware of for each trusted signer. The Signer child element lists the AWS account number of the trusted signer (or an empty Self element if the signer is you). The Signer element also includes the IDs of any active key pairs associated with the trusted signer's AWS account. If no KeyPairId element appears for a Signer, that signer can't create working signed URLs.
        • Enabled (boolean) -- Each active trusted signer.
        • Quantity (integer) -- The number of unique trusted signers included in all cache behaviors. For example, if three cache behaviors all list the same three AWS accounts, the value of Quantity for ActiveTrustedSigners will be 3.
        • Items (list) -- A complex type that contains one Signer complex type for each unique trusted signer that is specified in the TrustedSigners complex type, including trusted signers in the default cache behavior and in all of the other cache behaviors.
          • (dict) -- A complex type that lists the AWS accounts that were included in the TrustedSigners complex type, as well as their active CloudFront key pair IDs, if any.
            • AwsAccountNumber (string) -- Specifies an AWS account that can create signed URLs. Values: self, which indicates that the AWS account that was used to create the distribution can created signed URLs, or an AWS account number. Omit the dashes in the account number.
            • KeyPairIds (dict) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
              • Quantity (integer) -- The number of active CloudFront key pairs for AwsAccountNumber.
              • Items (list) -- A complex type that lists the active CloudFront key pairs, if any, that are associated with AwsAccountNumber.
                • (string) --
      • DistributionConfig (dict) -- The current configuration information for the distribution.
        • CallerReference (string) -- A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the DistributionConfig object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create a distribution, and the content of the DistributionConfig is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of the DistributionConfig is different from the original request, CloudFront returns a DistributionAlreadyExists error.
        • Aliases (dict) -- A complex type that contains information about CNAMEs (alternate domain names), if any, for this distribution.
          • Quantity (integer) -- The number of CNAMEs, if any, for this distribution.
          • Items (list) -- Optional: A complex type that contains CNAME elements, if any, for this distribution. If Quantity is 0, you can omit Items.
            • (string) --
        • DefaultRootObject (string) -- The object that you want CloudFront to return (for example, index.html) when an end user requests the root URL for your distribution (http://www.example.com) instead of an object in your distribution (http://www.example.com/index.html). Specifying a default root object avoids exposing the contents of your distribution. If you don't want to specify a default root object when you create a distribution, include an empty DefaultRootObject element. To delete the default root object from an existing distribution, update the distribution configuration and include an empty DefaultRootObject element. To replace the default root object, update the distribution configuration and specify the new object.
        • Origins (dict) -- A complex type that contains information about origins for this distribution.
          • Quantity (integer) -- The number of origins for this distribution.
          • Items (list) -- A complex type that contains origins for this distribution.
            • (dict) -- A complex type that describes the Amazon S3 bucket or the HTTP server (for example, a web server) from which CloudFront gets your files.You must create at least one origin.
              • Id (string) -- A unique identifier for the origin. The value of Id must be unique within the distribution. You use the value of Id when you create a cache behavior. The Id identifies the origin that CloudFront routes a request to when the request matches the path pattern for that cache behavior.
              • DomainName (string) -- Amazon S3 origins: The DNS name of the Amazon S3 bucket from which you want CloudFront to get objects for this origin, for example, myawsbucket.s3.amazonaws.com. Custom origins: The DNS domain name for the HTTP server from which you want CloudFront to get objects for this origin, for example, www.example.com.
              • OriginPath (string) -- An optional element that causes CloudFront to request your content from a directory in your Amazon S3 bucket or your custom origin. When you include the OriginPath element, specify the directory name, beginning with a /. CloudFront appends the directory name to the value of DomainName.
              • S3OriginConfig (dict) -- A complex type that contains information about the Amazon S3 origin. If the origin is a custom origin, use the CustomOriginConfig element instead.
                • OriginAccessIdentity (string) -- The CloudFront origin access identity to associate with the origin. Use an origin access identity to configure the origin so that end users can only access objects in an Amazon S3 bucket through CloudFront. If you want end users to be able to access objects using either the CloudFront URL or the Amazon S3 URL, specify an empty OriginAccessIdentity element. To delete the origin access identity from an existing distribution, update the distribution configuration and include an empty OriginAccessIdentity element. To replace the origin access identity, update the distribution configuration and specify the new origin access identity. Use the format origin-access-identity/cloudfront/Id where Id is the value that CloudFront returned in the Id element when you created the origin access identity.
              • CustomOriginConfig (dict) -- A complex type that contains information about a custom origin. If the origin is an Amazon S3 bucket, use the S3OriginConfig element instead.
                • HTTPPort (integer) -- The HTTP port the custom origin listens on.
                • HTTPSPort (integer) -- The HTTPS port the custom origin listens on.
                • OriginProtocolPolicy (string) -- The origin protocol policy to apply to your origin.
        • DefaultCacheBehavior (dict) -- A complex type that describes the default cache behavior if you do not specify a CacheBehavior element or if files don't match any of the values of PathPattern in CacheBehavior elements.You must create exactly one default cache behavior.
          • TargetOriginId (string) -- The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
          • ForwardedValues (dict) -- A complex type that specifies how CloudFront handles query strings, cookies and headers.
            • QueryString (boolean) -- Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
            • Cookies (dict) -- A complex type that specifies how CloudFront handles cookies.
              • Forward (string) -- Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
              • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
                • Quantity (integer) -- The number of whitelisted cookies for this cache behavior.
                • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
                  • (string) --
            • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
              • Quantity (integer) -- The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
              • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
                • (string) --
          • TrustedSigners (dict) -- A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
            • Enabled (boolean) -- Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
            • Quantity (integer) -- The number of trusted signers for this cache behavior.
            • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
              • (string) --
          • ViewerProtocolPolicy (string) -- Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
          • MinTTL (integer) -- The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
          • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
            • Quantity (integer) -- The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
            • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
              • (string) --
            • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
              • Quantity (integer) -- The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
              • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
                • (string) --
          • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
          • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
          • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • CacheBehaviors (dict) -- A complex type that contains zero or more CacheBehavior elements.
          • Quantity (integer) -- The number of cache behaviors for this distribution.
          • Items (list) -- Optional: A complex type that contains cache behaviors for this distribution. If Quantity is 0, you can omit Items.
            • (dict) -- A complex type that describes how CloudFront processes requests. You can create up to 10 cache behaviors.You must create at least as many cache behaviors (including the default cache behavior) as you have origins if you want CloudFront to distribute objects from all of the origins. Each cache behavior specifies the one origin from which you want CloudFront to get objects. If you have two origins and only the default cache behavior, the default cache behavior will cause CloudFront to get objects from one of the origins, but the other origin will never be used. If you don't want to specify any cache behaviors, include only an empty CacheBehaviors element. Don't include an empty CacheBehavior element, or CloudFront returns a MalformedXML error. To delete all cache behaviors in an existing distribution, update the distribution configuration and include only an empty CacheBehaviors element. To add, change, or remove one or more cache behaviors, update the distribution configuration and specify all of the cache behaviors that you want to include in the updated distribution.
              • PathPattern (string) -- The pattern (for example, images/*.jpg) that specifies which requests you want this cache behavior to apply to. When CloudFront receives an end-user request, the requested path is compared with path patterns in the order in which cache behaviors are listed in the distribution. The path pattern for the default cache behavior is * and cannot be changed. If the request for an object does not match the path pattern for any cache behaviors, CloudFront applies the behavior in the default cache behavior.
              • TargetOriginId (string) -- The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.
              • ForwardedValues (dict) -- A complex type that specifies how CloudFront handles query strings, cookies and headers.
                • QueryString (boolean) -- Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
                • Cookies (dict) -- A complex type that specifies how CloudFront handles cookies.
                  • Forward (string) -- Use this element to specify whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.
                  • WhitelistedNames (dict) -- A complex type that specifies the whitelisted cookies, if any, that you want CloudFront to forward to your origin that is associated with this cache behavior.
                    • Quantity (integer) -- The number of whitelisted cookies for this cache behavior.
                    • Items (list) -- Optional: A complex type that contains whitelisted cookies for this cache behavior. If Quantity is 0, you can omit Items.
                      • (string) --
                • Headers (dict) -- A complex type that specifies the Headers, if any, that you want CloudFront to vary upon for this cache behavior.
                  • Quantity (integer) -- The number of different headers that you want CloudFront to forward to the origin and to vary on for this cache behavior. The maximum number of headers that you can specify by name is 10. If you want CloudFront to forward all headers to the origin and vary on all of them, specify 1 for Quantity and * for Name. If you don't want CloudFront to forward any additional headers to the origin or to vary on any headers, specify 0 for Quantity and omit Items.
                  • Items (list) -- Optional: A complex type that contains a Name element for each header that you want CloudFront to forward to the origin and to vary on for this cache behavior. If Quantity is 0, omit Items.
                    • (string) --
              • TrustedSigners (dict) -- A complex type that specifies the AWS accounts, if any, that you want to allow to create signed URLs for private content. If you want to require signed URLs in requests for objects in the target origin that match the PathPattern for this cache behavior, specify true for Enabled, and specify the applicable values for Quantity and Items. For more information, go to Using a Signed URL to Serve Private Content in the Amazon CloudFront Developer Guide. If you don't want to require signed URLs in requests for objects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit Items. To add, change, or remove one or more trusted signers, change Enabled to true (if it's currently false), change Quantity as applicable, and specify all of the trusted signers that you want to include in the updated distribution.
                • Enabled (boolean) -- Specifies whether you want to require end users to use signed URLs to access the files specified by PathPattern and TargetOriginId.
                • Quantity (integer) -- The number of trusted signers for this cache behavior.
                • Items (list) -- Optional: A complex type that contains trusted signers for this cache behavior. If Quantity is 0, you can omit Items.
                  • (string) --
              • ViewerProtocolPolicy (string) -- Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. If you want CloudFront to allow end users to use any available protocol, specify allow-all. If you want CloudFront to require HTTPS, specify https. If you want CloudFront to respond to an HTTP request with an HTTP status code of 301 (Moved Permanently) and the HTTPS URL, specify redirect-to-https. The viewer then resubmits the request using the HTTPS URL.
              • MinTTL (integer) -- The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.You can specify a value from 0 to 3,153,600,000 seconds (100 years).
              • AllowedMethods (dict) -- A complex type that controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin. There are three choices: - CloudFront forwards only GET and HEAD requests. - CloudFront forwards only GET, HEAD and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests. If you pick the third choice, you may need to restrict access to your Amazon S3 bucket or to your custom origin so users can't perform operations that you don't want them to. For example, you may not want users to have permission to delete objects from your origin.
                • Quantity (integer) -- The number of HTTP methods that you want CloudFront to forward to your origin. Valid values are 2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE requests).
                • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to process and forward to your origin.
                  • (string) --
                • CachedMethods (dict) -- A complex type that controls whether CloudFront caches the response to requests using the specified HTTP methods. There are two choices: - CloudFront caches responses to GET and HEAD requests. - CloudFront caches responses to GET, HEAD, and OPTIONS requests. If you pick the second choice for your S3 Origin, you may need to forward Access-Control-Request-Method, Access-Control-Request-Headers and Origin headers for the responses to be cached correctly.
                  • Quantity (integer) -- The number of HTTP methods for which you want CloudFront to cache responses. Valid values are 2 (for caching responses to GET and HEAD requests) and 3 (for caching responses to GET, HEAD, and OPTIONS requests).
                  • Items (list) -- A complex type that contains the HTTP methods that you want CloudFront to cache responses to.
                    • (string) --
              • SmoothStreaming (boolean) -- Indicates whether you want to distribute media files in Microsoft Smooth Streaming format using the origin that is associated with this cache behavior. If so, specify true; if not, specify false.
              • DefaultTTL (integer) -- If you don't configure your origin to add a Cache-Control max-age directive or an Expires header, DefaultTTL is the default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin does not add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
              • MaxTTL (integer) -- The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify applies only when your origin adds HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, and Expires to objects. You can specify a value from 0 to 3,153,600,000 seconds (100 years).
        • CustomErrorResponses (dict) -- A complex type that contains zero or more CustomErrorResponse elements.
          • Quantity (integer) -- The number of custom error responses for this distribution.
          • Items (list) -- Optional: A complex type that contains custom error responses for this distribution. If Quantity is 0, you can omit Items.
            • (dict) -- A complex type that describes how you'd prefer CloudFront to respond to requests that result in either a 4xx or 5xx response. You can control whether a custom error page should be displayed, what the desired response code should be for this error page and how long should the error response be cached by CloudFront. If you don't want to specify any custom error responses, include only an empty CustomErrorResponses element. To delete all custom error responses in an existing distribution, update the distribution configuration and include only an empty CustomErrorResponses element. To add, change, or remove one or more custom error responses, update the distribution configuration and specify all of the custom error responses that you want to include in the updated distribution.
              • ErrorCode (integer) -- The 4xx or 5xx HTTP status code that you want to customize. For a list of HTTP status codes that you can customize, see CloudFront documentation.
              • ResponsePagePath (string) -- The path of the custom error page (for example, /custom_404.html). The path is relative to the distribution and must begin with a slash (/). If the path includes any non-ASCII characters or unsafe characters as defined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters. Do not URL encode any other characters in the path, or CloudFront will not return the custom error page to the viewer.
              • ResponseCode (string) -- The HTTP status code that you want CloudFront to return with the custom error page to the viewer. For a list of HTTP status codes that you can replace, see CloudFront Documentation.
              • ErrorCachingMinTTL (integer) -- The minimum amount of time you want HTTP error codes to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated. You can specify a value from 0 to 31,536,000.
        • Comment (string) -- Any comments you want to include about the distribution.
        • Logging (dict) -- A complex type that controls whether access logs are written for the distribution.
          • Enabled (boolean) -- Specifies whether you want CloudFront to save access logs to an Amazon S3 bucket. If you do not want to enable logging when you create a distribution or if you want to disable logging for an existing distribution, specify false for Enabled, and specify empty Bucket and Prefix elements. If you specify false for Enabled but you specify values for Bucket, prefix and IncludeCookies, the values are automatically deleted.
          • IncludeCookies (boolean) -- Specifies whether you want CloudFront to include cookies in access logs, specify true for IncludeCookies. If you choose to include cookies in logs, CloudFront logs all cookies regardless of how you configure the cache behaviors for this distribution. If you do not want to include cookies when you create a distribution or if you want to disable include cookies for an existing distribution, specify false for IncludeCookies.
          • Bucket (string) -- The Amazon S3 bucket to store the access logs in, for example, myawslogbucket.s3.amazonaws.com.
          • Prefix (string) -- An optional string that you want CloudFront to prefix to the access log filenames for this distribution, for example, myprefix/. If you want to enable logging, but you do not want to specify a prefix, you still must include an empty Prefix element in the Logging element.
        • PriceClass (string) -- A complex type that contains information about price class for this distribution.
        • Enabled (boolean) -- Whether the distribution is enabled to accept end user requests for content.
        • ViewerCertificate (dict) -- A complex type that contains information about viewer certificates for this distribution.
          • IAMCertificateId (string) -- If you want viewers to use HTTPS to request your objects and you're using an alternate domain name in your object URLs (for example, https://example.com/logo.jpg), specify the IAM certificate identifier of the custom viewer certificate for this distribution. Specify either this value or CloudFrontDefaultCertificate.
          • CloudFrontDefaultCertificate (boolean) -- If you want viewers to use HTTPS to request your objects and you're using the CloudFront domain name of your distribution in your object URLs (for example, https://d111111abcdef8.cloudfront.net/logo.jpg), set to true. Omit this value if you are setting an IAMCertificateId.
          • SSLSupportMethod (string) -- If you specify a value for IAMCertificateId, you must also specify how you want CloudFront to serve HTTPS requests. Valid values are vip and sni-only. If you specify vip, CloudFront uses dedicated IP addresses for your content and can respond to HTTPS requests from any viewer. However, you must request permission to use this feature, and you incur additional monthly charges. If you specify sni-only, CloudFront can only respond to HTTPS requests from viewers that support Server Name Indication (SNI). All modern browsers support SNI, but some browsers still in use don't support SNI. Do not specify a value for SSLSupportMethod if you specified true for CloudFrontDefaultCertificate.
          • MinimumProtocolVersion (string) -- Specify the minimum version of the SSL protocol that you want CloudFront to use, SSLv3 or TLSv1, for HTTPS connections. CloudFront will serve your objects only to browsers or devices that support at least the SSL version that you specify. The TLSv1 protocol is more secure, so we recommend that you specify SSLv3 only if your users are using browsers or devices that don't support TLSv1. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using dedicated IP (if you specify vip for SSLSupportMethod), you can choose SSLv3 or TLSv1 as the MinimumProtocolVersion. If you're using a custom certificate (if you specify a value for IAMCertificateId) and if you're using SNI (if you specify sni-only for SSLSupportMethod), you must specify TLSv1 for MinimumProtocolVersion.
        • Restrictions (dict) -- A complex type that identifies ways in which you want to restrict distribution of your content.
          • GeoRestriction (dict) -- A complex type that controls the countries in which your content is distributed. For more information about geo restriction, go to Customizing Error Responses in the Amazon CloudFront Developer Guide. CloudFront determines the location of your users using MaxMind GeoIP databases. For information about the accuracy of these databases, see How accurate are your GeoIP databases? on the MaxMind website.
            • RestrictionType (string) -- The method that you want to use to restrict distribution of your content by country: - none: No geo restriction is enabled, meaning access to content is not restricted by client geo location. - blacklist: The Location elements specify the countries in which you do not want CloudFront to distribute your content. - whitelist: The Location elements specify the countries in which you want CloudFront to distribute your content.
            • Quantity (integer) -- When geo restriction is enabled, this is the number of countries in your whitelist or blacklist. Otherwise, when it is not enabled, Quantity is 0, and you can omit Items.
            • Items (list) -- A complex type that contains a Location element for each country in which you want CloudFront either to distribute your content (whitelist) or not distribute your content (blacklist). The Location element is a two-letter, uppercase country code for a country that you want to include in your blacklist or whitelist. Include one Location element for each country. CloudFront and MaxMind both use ISO 3166 country codes. For the current list of countries and the corresponding codes, see ISO 3166-1-alpha-2 code on the International Organization for Standardization website. You can also refer to the country list in the CloudFront console, which includes both country names and codes.
              • (string) --
    • ETag (string) -- The current version of the distribution's information. For example: E2QWRUHAPOMQZL.
get_distribution_config(**kwargs)

Get the configuration information about a distribution.

Request Syntax

response = client.get_distribution_config(
    Id='string'
)
Parameters
Id (string) -- [REQUIRED] The distribution's id.
Return type
dict
Returns
Response Syntax
{
    'DistributionConfig': {
        'CallerReference': 'string',
        'Aliases': {
            'Quantity': 123,
            'Items': [
                'string',
            ]
        },
        'DefaultRootObject': 'string',
        'Origins': {
            'Quantity': 123,
            'Items': [
                {
                    'Id': 'string',
                    'DomainName': 'string',
                    'OriginPath': 'string',
                    'S3OriginConfig': {
                        'OriginAccessIdentity': 'string'
                    },
                    'CustomOriginConfig': {
                        'HTTPPort': 123,
                        'HTTPSPort': 123,
                        'OriginProtocolPolicy': 'http-only'|'match-viewer'
                    }
                },
            ]
        },
        'DefaultCacheBehavior': {
            'TargetOriginId': 'string',
            'ForwardedValues': {
                'QueryString': True|False,
                'Cookies': {
                    'Forward': 'none'|'whitelist'|'all',
                    'WhitelistedNames': {
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    }
                },
                'Headers': {
                    'Quantity': 123,
                    'Items': [
                        'string',
                    ]
                }
            },
            'TrustedSigners': {
                'Enabled': True|False,
                'Quantity': 123,
                'Items': [
                    'string',
                ]
            },
            'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
            'MinTTL': 123,
            'AllowedMethods': {
                'Quantity': 123,
                'Items': [
                    'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                ],
                'CachedMethods': {
                    'Quantity': 123,
                    'Items': [
                        'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                    ]
                }
            },
            'SmoothStreaming': True|False,
            'DefaultTTL': 123,
            'MaxTTL': 123
        },
        'CacheBehaviors': {
            'Quantity': 123,
            'Items': [
                {
                    'PathPattern': 'string',
                    'TargetOriginId': 'string',
                    'ForwardedValues': {
                        'QueryString': True|False,
                        'Cookies': {
                            'Forward': 'none'|'whitelist'|'all',
                            'WhitelistedNames': {
                                'Quantity': 123,
                                'Items': [
                                    'string',
                                ]
                            }
                        },
                        'Headers': {
                            'Quantity': 123,
                            'Items': [
                                'string',
                            ]
                        }
                    },
                    'TrustedSigners': {
                        'Enabled': True|False,
                        'Quantity': 123,
                        'Items': [
                            'string',
                        ]
                    },
                    'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
                    'MinTTL': 123,
                    'AllowedMethods': {
                        'Quantity': 123,
                        'Items': [
                            'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                        ],
                        'CachedMethods': {
                            'Quantity': 123,
                            'Items': [
                                'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
                            ]
                        }
                    },
                    'SmoothStreaming': True|False,
                    'DefaultTTL': 123,