create_stack ( $stack_name, $opt )

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.

Currently, the limit for stacks is 20 stacks per account per region.

Access

public

Parameters

Parameter

Type

Required

Description

$stack_name

string

Required

The name associated with the stack. The name must be unique within your AWS account.

Must contain only alphanumeric characters (case sensitive) and start with an alpha character. Maximum length of the name is 255 characters.

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • TemplateBody - string - Optional - Structure containing the template body. (For more information, go to the AWS CloudFormation User Guide.) Conditional: You must pass TemplateBody or TemplateURL. If both are passed, only TemplateBody is used.
  • TemplateURL - string - Optional - Location of file containing the template body. The URL must point to a template (max size: 307,200 bytes) located in an S3 bucket in the same region as the stack. For more information, go to the AWS CloudFormation User Guide. Conditional: You must pass TemplateURL or TemplateBody. If both are passed, only TemplateBody is used.
  • Parameters - array - Optional - A list of Parameter structures that specify input parameters for the stack.
    • x - array - Optional - This represents a simple array index.
      • ParameterKey - string - Optional - The key associated with the parameter.
      • ParameterValue - string - Optional - The value associated with the parameter.
  • DisableRollback - boolean - Optional - 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 - Optional - 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 - string|array - Optional - 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). Pass a string for a single value, or an indexed array for multiple values.
  • Capabilities - string|array - Optional - The list of capabilities that you want to allow in the stack. If your template contains IAM resources, you must specify the CAPABILITY_IAM value for this parameter; otherwise, this action returns an InsufficientCapabilities error. IAM resources are the following: AWS::IAM::AccessKey, AWS::IAM::Group, AWS::IAM::Policy, AWS::IAM::User, and AWS::IAM::UserToGroupAddition. Pass a string for a single value, or an indexed array for multiple values.
  • OnFailure - string - Optional - 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 [Allowed values: DO_NOTHING, ROLLBACK, DELETE]
  • Tags - array - Optional - A set of user-defined Tags to associate with this stack, represented by key/value pairs. Tags defined for the stack are propogated to EC2 resources that are created as part of the stack. A maximum number of 10 tags can be specified.
    • x - array - Optional - This represents a simple array index.
      • Key - string - Optional - 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 - Optional - Required. A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Create a new stack using a remote template.

CloudFormation can access stack templates from public URLs.

$stack = new AmazonCloudFormation();

$response = $stack->create_stack('my-stack', array(
	'TemplateURL' => 'http://cloudformation-us-east-1.s3.amazonaws.com/cloudformation.json'
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create a new stack using a JSON template.

Use a JSON string to define a stack template, then pass it to create_stack().

$stack = new AmazonCloudFormation();

$template = CFStackTemplate::json('{
	"AWSTemplateFormatVersion" : "2010-09-09",
	"Resources" : {
		"MyGroup" : {
			"Type" : "AWS::AutoScaling::AutoScalingGroup",
			"Properties" : {
				"AvailabilityZones" : [ "us-east-1a" ],
				"LaunchConfigurationName" : { "Ref" : "SimpleConfig" },
				"MinSize" : "1",
				"MaxSize" : "3",
				"LoadBalancerNames" : [ { "Ref" : "MyLoadBalancer" } ]
			}
		},
		"MyLoadBalancer" : {
			"Type" : "AWS::ElasticLoadBalancing::LoadBalancer",
			"Properties" : {
				"AvailabilityZones" : [ "us-east-1a" ],
				"Listeners" : [ {
					"LoadBalancerPort" : "80",
					"InstancePort" : "80",
					"Protocol" : "HTTP"
				} ]
			}
		},
		"SimpleConfig" : {
			"Type" : "AWS::AutoScaling::LaunchConfiguration",
			"Properties" : {
				"ImageId" : "ami-20b65349",
				"SecurityGroups" : [ { "Ref" : "OpenPorts" } ],
				"InstanceType" : "m1.small"
			}
		},
		"OpenPorts" : {
			"Type" : "AWS::EC2::SecurityGroup",
			"Properties" : {
				"GroupDescription" : "open port 80",
				"SecurityGroupIngress" : [ {
					"IpProtocol" : "tcp",
					"FromPort" : "80",
					"ToPort" : "80",
					"CidrIp" : "0.0.0.0/0"
				} ]
			}
		},
		"MyTrigger" : {
			"Type" : "AWS::AutoScaling::Trigger",
			"Properties" : {
				"MetricName" : "CPUUtilization",
				"Namespace" : "AWS/EC2",
				"Statistic" : "Average",
				"Period" : "300",
				"UpperBreachScaleIncrement" : "1",
				"LowerBreachScaleIncrement" : "-1",
				"AutoScalingGroupName" : { "Ref" : "MyGroup" },
				"BreachDuration" : "600",
				"UpperThreshold" : "90",
				"LowerThreshold" : "75",
				"Dimensions" : [ {
					"Name" : "AutoScalingGroupName",
					"Value" : { "Ref" : "MyGroup" }
				} ]
			}
		}
	},
	"Outputs" : {
		"URL" : {
			"Value" : { "Ref" : "MyLoadBalancer" }
		}
	}
}');

$response = $stack->create_stack('my-stack', array(
	'TemplateBody' => $template
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create a new stack using an associative array (map) template.

Use a multi-dimensional array to define a stack template, then pass it to create_stack().

$stack = new AmazonCloudFormation();

$template = CFStackTemplate::map(array(
	'AWSTemplateFormatVersion' => '2010-09-09',
	'Resources' => array(
		'MyGroup' => array(
			'Type' => 'AWS::AutoScaling::AutoScalingGroup',
			'Properties' => array(
				'AvailabilityZones' => array( 'us-east-1a' ),
				'LaunchConfigurationName' => array( 'Ref' => 'SimpleConfig' ),
				'MinSize' => '1',
				'MaxSize' => '3',
				'LoadBalancerNames' => array(
					array( 'Ref' => 'MyLoadBalancer' )
				)
			)
		),
		'MyLoadBalancer' => array(
			'Type' => 'AWS::ElasticLoadBalancing::LoadBalancer',
			'Properties' => array(
				'AvailabilityZones' => array( 'us-east-1a' ),
				'Listeners' => array(
					array(
						'LoadBalancerPort' => '80',
						'InstancePort' => '80',
						'Protocol' => 'HTTP'
					)
				)
			)
		),
		'SimpleConfig' => array(
			'Type' => 'AWS::AutoScaling::LaunchConfiguration',
			'Properties' => array(
				'ImageId' => 'ami-20b65349',
				'SecurityGroups' => array(
					array( 'Ref' => 'OpenPorts' )
				),
				'InstanceType' => 'm1.small'
			)
		),
		'OpenPorts' => array(
			'Type' => 'AWS::EC2::SecurityGroup',
			'Properties' => array(
				'GroupDescription' => 'open port 80',
				'SecurityGroupIngress' => array(
					array(
						'IpProtocol' => 'tcp',
						'FromPort' => '80',
						'ToPort' => '80',
						'CidrIp' => '0.0.0.0/0'
					)
				)
			)
		),
		'MyTrigger' => array(
			'Type' => 'AWS::AutoScaling::Trigger',
			'Properties' => array(
				'MetricName' => 'CPUUtilization',
				'Namespace' => 'AWS/EC2',
				'Statistic' => 'Average',
				'Period' => '300',
				'UpperBreachScaleIncrement' => '1',
				'LowerBreachScaleIncrement' => '-1',
				'AutoScalingGroupName' => array( 'Ref' => 'MyGroup' ),
				'BreachDuration' => '600',
				'UpperThreshold' => '90',
				'LowerThreshold' => '75',
				'Dimensions' => array(
					array(
						'Name' => 'AutoScalingGroupName',
						'Value' => array( 'Ref' => 'MyGroup' )
					)
				)
			)
		)
	),
	'Outputs' => array(
		'URL' => array(
			'Value' => array( 'Ref' => 'MyLoadBalancer' )
		)
	)
));

$response = $stack->create_stack('my-stack', array(
	'TemplateBody' => $template
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create a new stack using a remote template. Also set other optional parameters.

Uses a Notification ARN.

$stack = new AmazonCloudFormation();

$response = $stack->create_stack('my-stack', array(
	'TemplateURL' => 'https://s3.amazonaws.com/cloudformation-templates/CloudFormationSample_Instance.template',
	'NotificationARNs' => 'arn:aws:sns:us-east-1:0123456789012:my-topic',
	'Parameters' => array(
		array( 'ParameterKey' => 'KeyPair', 'ParameterValue' => 'my-keypair' )
	),
	'DisableRollback' => 'false',
	'TimeoutInMinutes' => 15
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Related Methods

Source

Method defined in services/cloudformation.class.php | Toggle source view (43 lines) | View on GitHub

public function create_stack($stack_name, $opt = null)
{
    if (!$opt) $opt = array();
    $opt['StackName'] = $stack_name;
    
    // Optional list + map
    if (isset($opt['Parameters']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Parameters' => $opt['Parameters']
        ), 'member'));
        unset($opt['Parameters']);
    }
    
    // Optional list (non-map)
    if (isset($opt['NotificationARNs']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'NotificationARNs' => (is_array($opt['NotificationARNs']) ? $opt['NotificationARNs'] : array($opt['NotificationARNs']))
        ), 'member'));
        unset($opt['NotificationARNs']);
    }
    
    // Optional list (non-map)
    if (isset($opt['Capabilities']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Capabilities' => (is_array($opt['Capabilities']) ? $opt['Capabilities'] : array($opt['Capabilities']))
        ), 'member'));
        unset($opt['Capabilities']);
    }
    
    // Optional list + map
    if (isset($opt['Tags']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Tags' => $opt['Tags']
        ), 'member'));
        unset($opt['Tags']);
    }

    return $this->authenticate('CreateStack', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback