From bfbc99ccbe92a054df3fb6c899672e0e428e4c35 Mon Sep 17 00:00:00 2001
From: "Eric J. Holmes" <eric@ejholmes.net>
Date: Fri, 16 Mar 2018 17:15:52 -0700
Subject: [PATCH] Document creating stacker bucket with CloudFormation.

---
 docs/config.rst                | 27 +++++++++++++++++++++++----
 stacker/blueprints/__init__.py | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 0848a460b..fd0e5497a 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -56,10 +56,29 @@ config.
 If you want to change this, provide the **stacker_bucket** top level key word
 in the config.
 
-The bucket will be created in the same region that the stacks will be launched
-in.  If you want to change this, or if you already have an existing bucket
-in a different region, you can set the **stacker_bucket_region** to
-the region where you want to create the bucket.
+The bucket will be created in the default region (either from ``AWS_REGION`` or
+the ``--region`` CLI flag).  If you want to change this, or if you already have
+an existing bucket in a different region, you can set the
+**stacker_bucket_region** to the region where you want to create the bucket.
+
+Alternatively, if you'd like to have more control over creation of the stacker
+bucket, you can add a stack to your config to create the bucket, "bootstrap"
+the bucket stack, then set the ``stacker_bucket`` value in your config after
+the bucket has been created. Stacker includes a base blueprint to create a
+stacker bucket with AES encryption by default::
+
+  # Bootstrap the bucket stack:
+  #   stacker build --stacks stacker-bucket -e stacker_bucket='' stacker.yaml
+  # Now that the bucket is created, you can use it for all future builds:
+  #   stacker build -e stacker_bucket='my-bucket-id' stacker.yaml
+  namespace: ''
+  stacker_bucket: ${stacker_bucket}
+
+  stacks:
+    - name: stacker-bucket
+      class_path: stacker.blueprints.StackerBucket
+    - name: vpc
+      class_path: stacker.tests.fixtures.mock_blueprints.Dummy
 
 **S3 Bucket location prior to 1.0.4:**
   There was a "bug" early on in stacker that created the s3 bucket in us-east-1,
diff --git a/stacker/blueprints/__init__.py b/stacker/blueprints/__init__.py
index e69de29bb..3a23fb188 100644
--- a/stacker/blueprints/__init__.py
+++ b/stacker/blueprints/__init__.py
@@ -0,0 +1,33 @@
+from stacker.blueprints.base import Blueprint
+
+from troposphere import Ref
+from troposphere import s3
+
+
+class StackerBucket(Blueprint):
+    VARIABLES = {
+        "BucketName": {
+            "type": str,
+            "default": "",
+            "description": "When provided, specifies an explicit bucket name "
+                           "to use when creating the bucket. If none is "
+                           "specified, CloudFormation will create a random "
+                           "name."
+        },
+    }
+
+    @property
+    def bucket(self):
+        bucket_name = self.get_variables()["BucketName"] or Ref("AWS::NoValue")
+        aes = s3.ServerSideEncryptionRule(
+                ServerSideEncryptionByDefault=s3.ServerSideEncryptionByDefault(
+                    SSEAlgorithm="AES256"))
+
+        return s3.Bucket(
+            "StackerBucket",
+            BucketName=bucket_name,
+            BucketEncryption=s3.BucketEncryption(
+                ServerSideEncryptionConfiguration=[aes]))
+
+    def create_template(self):
+        self.template.add_resource(self.bucket)