Some docs about parameters

cloudtools · Mar 31, 2015 · ed2024e · ed2024e
1 parent cdd9506
commit ed2024e
Showing 1 changed file with 52 additions and 31 deletions.
diff --git a/README.rst b/README.rst
@@ -37,37 +37,38 @@ installing stacker and loading your AWS API keys in your environment
 
 Here's the syntax help from the command::
 
-   # stacker -h
-   usage: stacker [-h] [-r REGION] [-m MAX_ZONES] [-v] [-d DOMAIN]
-                  [-p PARAMETER=VALUE] [--prompt]
-                  config
-
-   Launches AWS Cloudformation stacks from config.
-
-   positional arguments:
-     config                The config file where stack configuration is located.
-                           Must be in yaml format.
-
-   optional arguments:
-     -h, --help            show this help message and exit
-     -r REGION, --region REGION
-                           The AWS region to launch in. Default: us-east-1
-     -m MAX_ZONES, --max-zones MAX_ZONES
-                           Gives you the ability to limit the # of zones that
-                           resources will be launched in. If not given, then
-                           resources will be launched in all available
-                           availability zones.
-     -v, --verbose         Increase output verbosity. May be specified up to
-                           twice.
-     -d DOMAIN, --domain DOMAIN
-                           The domain to run in. Gets converted into the
-                           BaseDomain Parameter for use in stack templates.
-     -p PARAMETER=VALUE, --parameter PARAMETER=VALUE
-                           Adds parameters from the command line that can be used
-                           inside any of the stacks being built. Can be specified
-                           more than once.
-     --prompt              Drop to python prompt rather than kicking off build of
-                           the stack.
+  # stacker -h
+  usage: stacker [-h] [-r REGION] [-m MAX_ZONES] [-v] [-d DOMAIN]
+                 [-p PARAMETER=VALUE] [--stacks STACKNAME]
+                 config
+
+  Launches AWS Cloudformation stacks from config.
+
+  positional arguments:
+    config                The config file where stack configuration is located.
+                          Must be in yaml format.
+
+  optional arguments:
+    -h, --help            show this help message and exit
+    -r REGION, --region REGION
+                          The AWS region to launch in. Default: us-east-1
+    -m MAX_ZONES, --max-zones MAX_ZONES
+                          Gives you the ability to limit the # of zones that
+                          resources will be launched in. If not given, then
+                          resources will be launched in all available
+                          availability zones.
+    -v, --verbose         Increase output verbosity. May be specified up to
+                          twice.
+    -d DOMAIN, --domain DOMAIN
+                          The domain to run in. Gets converted into the
+                          BaseDomain Parameter for use in stack templates.
+    -p PARAMETER=VALUE, --parameter PARAMETER=VALUE
+                          Adds parameters from the command line that can be
+                          used inside any of the stacks being built. Can be
+                          specified more than once.
+    --stacks STACKNAME    Only work on the stacks given. Can be specified more
+                          than once. If not specified then stacker will work on
+                          all stacks in the config file.
 
 As of now there is no option to tear down the stack in the tool (we plan to
 add it), so you'll need to tear the stacks it creates down manually. When doing
@@ -77,5 +78,25 @@ tear down the VPC stack. If you try deleting them all (including VPC) in one
 swoop, you'll see that VPC stack gets hung up while waiting for the others to
 tear down.
 
+Defining Parameters
+===================
+
+There are multiple ways to define parameters for stacks, each useful in
+different ways:
+
+- the ``-p/--parameter`` command line argument
+- in the stack config
+- from an existing stack
+
+Each of those overrides similarly named parameters beneath it, so if you
+use ``-p CidrBlock`` on the command line, it doesn't matter what is in the
+config file or any existing stacks. This is useful if, for example, you want
+to keep sensitive information (passwords, etc) out of the config file (which
+you'll likely check into a RCS), but need a way to supply them.
+
+When updating an existing stack, if you don't supply a parameter in either the
+config or CLI, it will fall back on checking the existing stack for the
+parameter. If it finds it, it will use that automatically.
+
 .. _Remind: http://www.remind.com/
 .. _troposphere: https://github.com/cloudtools/troposphere