Include overview

README.md

@@ -2,6 +2,95 @@
 
 A command line tool for managing Terraform blueprints.
 
+## Overiew
+
+The Bedrock command line tool builds on the excellent features of Terraform to provide a "no-code" approach to
+provisioning infrastructure.
+
+## Introduction
+
+Bedrock can be used as a drop-in replacement for Terraform, in that all the commands are the same with the exception
+of two key differences:
+
+First, all commands are executed in the context of a `blueprint`, which is a predefined Terraform
+configuration. Each command will prompt for selection from a list of registered blueprints before executing
+the command.
+
+The other key difference is that all local state, modules, plugins, etc. are stored under a single directory, which
+by default is created in the user home directory and named `.bedrock`. This means that you don't need to change
+directories in order to run commands on different Terraform configurations.
+
+## Bedrock Commands
+
+To support these differences Bedrock introduces three additional commands that are not available with Terraform:
+
+### Backend
+
+The backend command supports configuration of Terraform state management, which may be either a `local`, `s3`, or
+`remote` configuration.
+
+A local configuration is the default for all blueprints, and just means that state is stored locally under the 
+`~/.bedrock` directory. Whilst no configuration is required for local state, it can be a poor choice if you don't 
+create regular backups or use ephemeral execution environments.
+
+An AWS S3 bucket may be used to store Terraform state securely, which requires the appropriate credentials to be
+configured to read and write to the bucket.
+
+Finally a remote configuration using Terraform Cloud may be configured for which a configuration file should be
+provided in the user home directory (i.e. `.terraformrc`).
+
+_NOTE:_ Terraform doesn't support different backend configurations for workspaces in a single configuration. This
+means that you must use the same state management configuration for all instances of a blueprint. If you need to
+manage multiple independent configuration sets you can override the blueprint home directory (see below). 
+
+
+### Config
+
+If a blueprint doesn't provide default values for all variables, or if you would like to override some defaults, you
+may use the Bedrock config command. This is a simple way to specify variables values using a `key=value` format. For
+more complex variable configurations you may specify a var-file location for some commands using the `-var-file` option.
+
+### Blueprint
+
+Finally, the blueprint command allows you to configure and manage registered blueprints. Whilst the default blueprints
+may support general purpose use-cases, sometimes you may want to provide your own more specialised blueprints for use
+with the Bedrock command line tool.
+
+To create a Bedrock-compatible blueprint you just need to create a Docker image that includes a version of Terraform,
+and the blueprint configuration under the `/blueprint` directory.
+
+## Workspaces
+
+To support creating multiple instances of a blueprint you may use Terraform workspaces in the same way as you would
+with the Terraform command line tool. For each blueprint workspace, Bedrock will provide separate state management and
+variable overrides.
+
+As workspaces may be used to create blueprint instances across multiple environments and accounts, some care should
+be taken to define a workspace naming convention. For example, you may wish to prefix workspace names with the
+account number, followed by application name, environment, etc.
+
+As an example, to configure an ECS cluster I might create a workspace such as: `987654321-myapp-staging`
+
+## Blueprint Home Directory
+
+As mentioned earlier all local state and configuration is maintained in a single default directory. Sometimes you
+may require isolation of state files, such as when managing different tenancies or separation of production and
+non-production environments.
+
+Bedrock supports an environment variable to override the default blueprint home directory, which you can specify
+either on the command line or export to your environment:
+
+    $ BLUEPRINT_HOME=/tmp/bedrock bedrock workspace list
+
+Used in conjunction with target environment overrides (such as `AWS_PROFILE` for AWS tenancy management) you can
+switch between different tenancies very easily:
+
+    $ AWS_PROFILE=staging BLUEPRINT_HOME=/opt/bedrock/staging bedrock apply # make changes in staging environment
+
+
+
+--------------
+
 ## Introduction
 
 The bedrock CLI is a simple tool to help manage the execution of Terraform blueprints.