From 3b13657ced82ea84932ea762d6bdb9ca348a092a Mon Sep 17 00:00:00 2001 From: Daniel Miranda Date: Sun, 10 Mar 2019 04:40:50 -0300 Subject: [PATCH] docs: document external stacks --- docs/config.rst | 117 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 93 insertions(+), 24 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index a6804926b..ab1441a9e 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -334,13 +334,49 @@ stacks that will be deployed in the environment. The top level keyword *stacks* is populated with a list of dictionaries, each representing a single stack to be built. -A stack has the following keys: +Stacks are managed by Stacker by default. They will be created and updated as +needed using the template file or blueprint class specified. Stacks that are +created by external tools and meant to be used only as references for output +lookups can be marked as *external*. + +The following options are available for all stacks: **name:** The logical name for this stack, which can be used in conjuction with the ``output`` lookup. The value here must be unique within the config. If no ``stack_name`` is provided, the value here will be used for the name of the CloudFormation stack. +**stack_name:** + (optional) If provided, this will be used as the name of the CloudFormation + stack. Unlike ``name``, the value doesn't need to be unique within the config, + since you could have multiple stacks with the same name, but in different + regions or accounts. (note: the namespace from the environment will be + prepended to this) +**region**: + (optional): If provided, specifies the name of the region that the + CloudFormation stack should reside in. If not provided, the default region + will be used (``AWS_DEFAULT_REGION``, ``~/.aws/config`` or the ``--region`` + flag). If both ``region`` and ``profile`` are specified, the value here takes + precedence over the value in the profile. +**profile**: + (optional): If provided, specifies the name of a AWS profile to use when + performing AWS API calls for this stack. This can be used to provision stacks + in multiple accounts or regions. +**external**: + (optional): If set to true, this stack is considered read-only, will not be + modified by Stacker, and most of the options related to stack deployment + should be omitted. + +External stacks accept the following additional options: + +**fqn**: + (optional): Fully-qualified physical name of the stack to be loaded from + CloudFormation. Use instead of ``stack_name`` if the stack lies in a + different namespace, as this value *does not* get the namespace applied to + it. + +Managed stacks accept the following additional options: + **class_path:** The python class path to the Blueprint to be used. Specify this or ``template_path`` for the stack. @@ -350,7 +386,6 @@ A stack has the following keys: working directory (e.g. templates stored alongside the Config), or relative to a directory in the python ``sys.path`` (i.e. for loading templates retrieved via ``packages_sources``). - **description:** A short description to apply to the stack. This overwrites any description provided in the Blueprint. See: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-description-structure.html @@ -363,8 +398,10 @@ A stack has the following keys: updated unless the stack is passed to stacker via the *--force* flag. This is useful for *risky* stacks that you don't want to take the risk of allowing CloudFormation to update, but still want to make - sure get launched when the environment is first created. When ``locked``, - it's not necessary to specify a ``class_path`` or ``template_path``. + sure get launched when the environment is first created. + Note: when ``locked``, it's not necessary to specify a ``class_path`` + or ``template_path``, but this functionality is deprecated in favour of + ``external``. **enabled:** (optional) If set to false, the stack is disabled, and will not be built or updated. This can allow you to disable stacks in different @@ -383,22 +420,6 @@ A stack has the following keys: **tags:** (optional) a dictionary of CloudFormation tags to apply to this stack. This will be combined with the global tags, but these tags will take precendence. -**stack_name:** - (optional) If provided, this will be used as the name of the CloudFormation - stack. Unlike ``name``, the value doesn't need to be unique within the config, - since you could have multiple stacks with the same name, but in different - regions or accounts. (note: the namespace from the environment will be - prepended to this) -**region**: - (optional): If provided, specifies the name of the region that the - CloudFormation stack should reside in. If not provided, the default region - will be used (``AWS_DEFAULT_REGION``, ``~/.aws/config`` or the ``--region`` - flag). If both ``region`` and ``profile`` are specified, the value here takes - precedence over the value in the profile. -**profile**: - (optional): If provided, specifies the name of a AWS profile to use when - performing AWS API calls for this stack. This can be used to provision stacks - in multiple accounts or regions. **stack_policy_path**: (optional): If provided, specifies the path to a JSON formatted stack policy that will be applied when the CloudFormation stack is created and updated. @@ -411,13 +432,20 @@ A stack has the following keys: option to `wait` and stacker will wait for the previous update to complete before attempting to update the stack. -Stacks Example -~~~~~~~~~~~~~~ +Examples +~~~~~~~~ + +VPC + Instances +::::::::::::::: -Here's an example from stacker_blueprints_, used to create a VPC:: +Here's an example from stacker_blueprints_, used to create a VPC and and two EC2 +Instances:: + + namespace: example stacks: - - name: vpc-example + - name: vpc + stack_name: test-vpc class_path: stacker_blueprints.vpc.VPC locked: false enabled: true @@ -438,6 +466,47 @@ Here's an example from stacker_blueprints_, used to create a VPC:: - 10.128.20.0/22 CidrBlock: 10.128.0.0/16 + - name: instances + stack_name: + class_path: stacker_blueprints.ec2.Instances + enabled: true + variables: + SmallInstance: + InstanceType: t2.small + ImageId: &amazon_linux_ami "${ami owners:amazon name_regex:amzn-ami-hvm-2018.03.*-x86_64-gp2}" + AvailabilityZone: ${output vpc::AvailabilityZone0} + SubnetId: ${output vpc::PublicSubnet0} + LargeInstance: + InstanceType: m5.xlarge + ImageId: *amazon_linux_ami + AvailabilityZone: ${output vpc::AvailabilityZone1} + SubnetId: ${output vpc::PublicSubnet1} + + +Referencing External Stacks +::::::::::::::::::::::::::: + +This example creates a security group in VPC from the previous example by +importing it as an external stack with a custom profile:: + + namespace: other-example + stacks: + - name: vpc + fqn: example-test-vpc + profile: custom-profile + external: yes + + - name: sg + class_path: stacker_blueprints.ec2.SecurityGroups + variables: + SecurityGroups: + VpcId: ${output vpc::VpcId} + SecurityGroupIngress: + - CidrIp: 0.0.0.0/0 + FromPort: 22 + ToPort: 22 + IpProtocol: tcp + Targets -------