covalence 0.0.1 → 0.7.9.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ae5280fc919f97574c1b871e8ec7977f6e6dc484
-  data.tar.gz: bbae92253785eb1e56713516e2593772ad03125b
+SHA256:
+  metadata.gz: 6996b380a260e1574dddef9841685368579573823dd9df81ee8b2e2049b17ad6
+  data.tar.gz: 22b8030ef7c9ae4acd112fe3446958e04de60dc871e8c0582a7478ff972c3837
 SHA512:
-  metadata.gz: 47960bc98f248d7bca5070cde0135bb889b219f29dc15b6dac633b7b17aefc3174ce8439cc7e22ea8713e132e182d61e1186232f5b19a3e588fd492b23435e1e
-  data.tar.gz: 40a56a52a4b05108fe48a660ad85893938c44f2def6700c9c7567f64e359baaa076e11e9cd3513406a2cc274cfa31d458f138a1b621a441c526b4d876b5c1800
+  metadata.gz: 432db3aa484713ec86a56970402789b3e3b3b0c71877a16e7d5840b3546a40a56d5246b57b50514b1e85da5504a3f992c06b18f02bc975a33671f2d9654f633a
+  data.tar.gz: 9bd16e47bbab6d00b73c5ef87d61f5720b7e767380a21afdd82a9b31e49c2d02ce28d97d134c157371a0bf2cc2a089c339409e04ce9728d7706bf364b460e276

data/CHANGELOG.md

@@ -0,0 +1,164 @@
+## Unreleased
+* Add ability to toggle primary state store
+* Add environment variable interpolation for input variables
+* Add support for sops encryption / decryption of hierarchy data
+
+## 0.7.8 (May 9, 2018)
+IMPROVEMENTS:
+- Added support for Terraform workspaces
+
+## 0.7.7 (May 6, 2018)
+BACKWARDS INCOMPATIBILITIES:
+- Versions of Terraform prior to v0.11.4 are no longer supported.
+
+IMPROVEMENTS:
+- Extended shell interpolation for input values to support nesting and escaping
+- Improved support for Terraform plugin caching
+- Replaced deprecated `-force` option for Terraform `destroy` task with `-auto-approve=true`.
+
+FIXES:
+- Updated input processing to support nested complex types properly.
+- Updated input processing to properly handle non-string values for non-complex input types.
+
+## 0.7.6 (December 6, 2017)
+IMPROVEMENTS:
+- Terraform init failures were not being reported.  Update spec tests to catch errors with 'terraform init'.
+
+## 0.7.5 (October 12, 2017)
+IMPROVEMENTS:
+- Fix the sync command to call Terraform get prior to init command.  This is required with new version of Terraform.
+
+## 0.7.4 (September 26, 2017)
+IMPROVEMENTS:
+- Updated Covalence to work with Terraform 0.10.x.  Updates were made in 0.10.x that requires all variables set for validate to run.
+- Also added setting for the apply to auto approve.  This will be required in upcoming releases and will prompt for input from user.
+
+## 0.7.3 (June 20, 2017)
+IMPROVEMENTS:
+- Tasks within the 'ci' and 'spec' namespaces will no longer load all individual stack tasks like the 'all' namespace.
+
+FIXES:
+- Tasks in the reserved 'ci' and 'spec' namespaces were failing in the environments filter logic. These namespaces are not properly ignored.
+
+## 0.7.2 (June 17, 2017)
+IMPROVEMENTS:
+- Added input logging for Packer stacks.
+- Removed logic for driving Docker containers with Covalence. Default mode of operation is now within a container.
+- Further merged Terraform and Packer internal structures.
+- Various performance improvements in the way in which stacks are loaded and processed.
+
+FIXES:
+- Fixed Terraform `refresh` task.
+
+## 0.7.1 (May 15, 2017)
+IMPROVEMENTS:
+- Updated Hiera to 3.3.1 to enable `list` and `map` lookups from within the data using the alias lookup function.
+
+FIXES:
+- Updated Packer `inspect` task to operate in a temporary directory, so that any generated assets are cleaned up after execution.
+
+## 0.7.0 (May 15. 2017)
+BACKWARDS INCOMPATIBILITIES:
+- Terraform `apply` and `destroy` tasks will no longer include `plan` and `plan_destroy` respectively.
+- The Packer stack `packer-module` parameter has been replaced by `module` for standardization with Terraform stacks.
+- The Packer namespace `packer-template` parameter has been moved to the stack scope and is now a relative path to the module (e.g. `packer::build::packer-template: 'fully/qualified/path/template.json'` would become `mystack::packer-template: 'template.json'` for `mystack::module: 'fully/qualified/path'`)
+- The Packer namespace `packer-targets` parameter has been removed.
+- The Packer namespace `packer-vars` parameter has been replaced by `vars` for standardization with Terraform stacks.
+- The `COVALENCE_TERRAFORM_DIR` and `COVALENCE_PACKER_DIR` environment variables now default to the same value as `COVALENCE_WORKSPACE` and are now deprecated.
+
+FEATURES:
+- Terraform input variables are now fed in via `-var-file` instead of individual `-var` arguments.
+- Dependencies can now be specified at the stack scope using `<stack>::deps`, which is an Array of directory paths that are to be made available in the working directory. Paths are relative to the Covalence root directory.
+- Added support for `list` and `map` input types.
+
+IMPROVEMENTS:
+- Exposed Terraform `refresh` command.
+- Added `refresh` command at the environment and global scope.
+- Added `format` command at the environment and global scope (#33).
+- Added `plan` command at the global scope (#40).
+
+FIXES:
+- The `targets` namespace parameter is now properly ignored for Packer stacks.
+- Environment spec tasks now properly account for execution errors (#43)
+
+## 0.6.1 (April 8, 2017)
+IMPROVEMENTS:
+- Stack sync no longer sources modules when retrieving state.
+
+FIXES:
+- Fixed regression in sourcing modules from relative paths.
+
+## 0.6.0 (April 8, 2017)
+BACKWARDS INCOMPATIBILITIES:
+- Versions of Terraform prior to v0.9.0 are no longer supported.
+
+FEATURES:
+- Added support for remote backends.
+
+IMPROVEMENTS:
+- Log level now configurable via the COVALENCE_LOG environment variable.
+
+## 0.5.3 (October 19, 2016)
+FIXES:
+- terraform destroy tasks receive the `-force` param instead of `-input=false`.
+- `env:spec` only does format checking on the specific path module, not the dependent modules referenced underneath.
+
+## 0.5.2 (October 12, 2016)
+FEATURES:
+- Packer can now be ran from docker containers. Follows the same conventions as terraform by specifying `PACKER_IMG`, `PACKER_CMD`
+
+FIXES:
+- More minor PopenWrapper return code fixes
+- Allow packer to deal with shell interpolation values via the same terraform shell interpolation prefix: `$(...`
+
+
+## 0.5.1 (October 10, 2016)
+
+FEATURES:
+- Packer build and validate now accept runtime arguments, ie `rake example:packer-module:build -- -var "foo=baz"`
+
+FIXES:
+- PopenWrapper issues with mismatching exit-codes for happy path runs.
+- Terraform remote config needed to ignore exitcodes in a few places where it was being called as a precaution or for 0.6.x compatibility reasons.
+
+## 0.5.0 (October 5, 2016)
+
+FEATURES:
+- Better control of running terraform/packer subprocesses:
+  - Ctrl-C breaks out of Terraform/Packer commands (also suppresses the normal debugging output from packer/terraform when they're natively sent a SIGINT)
+  - Debug capability built into the rake task runs to manually confirm each step
+
+IMPROVEMENTS:
+- Allow packer stacks to standalone
+- Finer grain control around terraform exit-codes and when to abort the rake task
+
+FIXES:
+- Non-zero error codes now return properly from rake tasks (if the
+  underlying CLI command did not choose to ignore error codes)
+- Packer runs generate temp JSON files in the packer module directory,
+  allows the use of `{{ template_dir }}` for script locations.
+
+## 0.4.3 (September 27, 2016)
+FIXES:
+- Handle new terraform API output formats for remote inputs
+
+## 0.4.2 (September 26, 2016)
+FIXES:
+- Terraform remote config now works from the module path instead of a temporary directory, which should ensure that the state gets read correctly when ran from a docker context
+
+## 0.4.1 (September 25, 2016)
+
+FEATURES:
+- Terraform rake tasks now accept runtime arguments, ie: `rake example:module_test:plan[1,2] -- --no-drift --help`
+
+IMPROVEMENTS:
+- Change COVALENCE_CONFIG to default to covalence.yaml
+- Gem spec enforce Ruby version >= 2.0.0
+
+FIXES:
+- Terraform path handling when terraform is ran in a docker container context. Volume is mounted at the TERRAFORM_DIR base, workdir is a relative subpath to the TERRAFORM_DIR base.
+- Fixed shell interpolation bug for terraform 0.7.x inputs, which currently forces string types.
+
+## 0.4.0 (September 14, 2016)
+
+* Initial release

data/README.md

@@ -1,41 +1,511 @@
-# PrometheusUnifio
+# Covalence
+[![CircleCI](https://circleci.com/gh/unifio/covalence.svg?style=svg)](https://circleci.com/gh/unifio/covalence)
+[![Dependency Status](https://gemnasium.com/badges/github.com/unifio/covalence.svg)](https://gemnasium.com/github.com/unifio/covalence)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/prometheus_unifio`. To experiment with that code, run `bin/console` for an interactive prompt.
+A tool for the management and orchestration of data used by HashiCorp infrastructure tooling.
 
-TODO: Delete this and the text above, and describe your gem
+<img src="./images/bond.jpg">
 
-## Installation
+# Why Covalence?
 
-Add this line to your application's Gemfile:
+## Separation of data and code
+Covalence allows for Terraform [Backends](https://www.terraform.io/docs/backends/) and variable inputs to be source agnostic, so your modules aren't hard coded to specific data sources.
+
+## Code / data reuse
+No more copying around of tfvars files or creating glue code to tie together modules. Covalence will assemble the proper data inputs and modules for the contexts you want.
+
+## Infrastructure as layers
+We have found that there is tremendous value in decoupling our infrastructure into layers and coordinating those layers with data. The overhead of managing layers adds up quickly though and introduces risk for human error in coordinating data and state. Coavalence models each context as an executable stack, so that data and state are always managed properly.
+
+# FAQ
+
+### Does using Covalence impact my ability to use my code with the HashiCorp tools natively?
+No. Covalence is a superset of functionality on top of the native HashiCorp tools. While it is opinionated, it does not require any fundamental departure from HashiCorp best practices that would render it unusable with the stand alone products.
+
+### Why Hiera?
+Covalence was a tool born of necessity. For those who were early adopters of Terraform, you know what I'm talking about.
+
+The first Covalence data backend was a single YAML file. That quickly failed to scale as we began using the tool to decouple more and more layers. We needed to move to something more flexible. As you might have guessed, the first projects we used Covalence with also included Puppet. Puppet suffered from similar data management issues that impacted code complexity and reusability. Given that our target users were already comfortable with Hiera and we were using Ruby, it was an obvious fit.
+
+If you're not familiar with Hiera, you'll want to read up on it [here](https://puppet.com/docs/puppet/5.4/hiera_intro.html). Covalence uses Hiera v3, as v4 and up are no longer separate from Puppet.
+
+# Requirements
+
+* [Bash](https://www.gnu.org/software/bash/) shell environment. Windows users, you will need the [Linux subsystem](https://docs.microsoft.com/en-us/windows/wsl/install-win10) installed.
+* [Docker](https://docs.docker.com/engine/installation/)
+
+# Quick Start
+
+* Securely download [covalence](https://s3.amazonaws.com/unifio-covalence/get_covalence/covalence) and add to the `bin` directory of your infrastructure repository or directory.
+* Change the mode of the file to allow execution: `chmod +x bin/covalence`
+* Execute `bin/covalence`. This will download the most current version of the launcher script and return a usage statement to the command line. The launcher should be committed to source control.
+
+For example:
+
+```
+|-- bin
+|   |-- covalence
+|   |-- .covalence
+|       |-- launcher
+...
+```
+
+To begin using Covalence, some configuration is required. The following files are required:
+
+```
+|-- bin
+|   |-- covalence
+|-- covalence.yaml
+|-- Rakefile
+...
+```
+
+See [example](./example) for a minimal configuration.
+
+While the `.env.covalence` and `.env.docker` files are not a hard requirement, they are the preferred method of overriding values in the Covalence launcher as well as configuring tools within the container. Sample files have been provided as a reference, but many additional options are available.
+
+# Configure Your Rakefile
+
+The minimal configuration for your Rakefile is as follows:
 
 ```ruby
-gem 'prometheus_unifio'
+require 'rake'
+require 'rspec/core/rake_task'
+require 'covalence/environment_tasks'
+require 'covalence/spec_tasks'
+```
+
+This file is exposed so that you can add other rake tasks as desired. See [example/Rakefile](./example/Rakefile) for an example of extending the Rakefile. Note, if you add dependencies on gems that are not present in the default container, you will need to add them.
+
+## Reserved Namespaces
+
+In addition to avoiding any task names that will overlap your environment names, there are several additional tasks built into Covalence.
+
+### All
+
+The `all` environment allows for the execution of actions against all configured stacks in all configured environments.
+
+For example:
+
+```bash
+$ bin/covalence all:format
+```
+
+would execute `terraform fmt` on all configured stacks in all configured environments.
+
+Note: Passing a task of the form `<environment>:<action>` will have the same effect on all stacks for the specified environment.
+
+### RSpec
+
+Unit tests for all tasks and tools.
+
+The suite can be executed with the following command:
+
+```bash
+$ bin/covalence spec
+```
+
+### UAT
+
+User acceptance tests targeting execution in a continuous integration (CI) environment.
+
+The suite can be executed with the following command:
+
+```bash
+$ bin/covalence ci
+```
+
+# Configure Your Data Hierarchy
+
+If you're not familiar with Hiera, you'll want to start your reading [here](https://puppet.com/docs/hiera/3.3/index.html).
+
+The hierarchy is driven by the **covalence.yaml** configuration. It is important to note that it is not a requirement that all directories and files in the hierarchy exist, the hierarchy simply dictates an order of priority for looking up values.
+
+An exmaple configuration is as follows:
+
+**data/covalence.yaml**
+```yaml
+---
+:backends:
+  - yaml                                          # Data store type. Also supports JSON out-of-the-box.
+                                                  # Can support multiple concurrently.
+
+:logger: noop                                     # Suppress Hiera logging. Can be re-enabled by
+                                                  # commenting this line out.
+
+:merge_behavior: 'deeper'                         # Merge strategy for Hash lookups.
+
+:hierarchy:                                       # Data store hierarchy. Lookups will traverse the
+                                                  # hierarchy in order from top to bottom.
+  - "environments/%{environment}"
+  - "stacks/%{stack}"
+  - "global"
+  - "environments"
+
+:yaml:                                            # Configuration specific to the YAML backend.
+  :datadir: data                                  # Root directory of the YAML data store.
+
+```
+
+The hierarchy can be changed, but the only two context variables currently supported are the `environment` and `stack` names.
+
+# Create a Stack
+
+## Terraform
+
+A Covalence stack is a pairing of data for a single context with a module. A Terraform stack must minimally include a module mapping as well as a state storage configuration.
+
+For example, let's create a stack called vpc. Given our hierarchy above, let's add a `data/stacks/vpc.yaml` file and configure it as follows:
+
+**data/stacks/vpc.yaml**
+```yaml
+---
+# VPC stack
+
+# Terraform module
+vpc::module: 'terraform/vpc'                          # Terraform module directory if different than
+                                                      # the stack name. The key is prepended with the
+                                                      # stack name, as module assignment is stack specific.
+
+# State storage
+vpc::state:                                           # Terraform backend configuration. The key is
+                                                      # prepended with the stack name, as the backend
+                                                      # configuration is stack specific. The `state` map
+                                                      # accepts a list of Terraform backend configuration
+                                                      # maps. The first in the list is considered the
+                                                      # primary backend while subsequent entries are
+                                                      # targets for replication. Backend names and
+                                                      # parameters map directly to what is supported by
+                                                      # Terraform. Covalence will generate the code
+                                                      # associated with backend initialization at runtime.
+
+  - s3:                                               # Backend type.
+      bucket: "%{alias('tf_state_bucket')}"           # Example for looking up a value from another
+                                                      # context within the hierarchy (e.g. data/environments/test.yaml)
+      encrypt: true
+      name: "%{environment}/%{stack}"                 # Example of interpolating context specific
+                                                      # variables.
+      region: "%{alias('tf_state_region')}"
+      role_arn: "%{alias('cross_acct_role_arn')}"
+  - consul:                                           # Secondary backend configuration
+      address: 'consul.example.com:8500'
+      name: "%{environment}/%{stack}"
+
+# Workspace
+vpc::workspace: 'blue'                                # Terraform workspace configuration. The key is
+                                                      # prepended with the stack name, as the backend
+                                                      # configuration is stack specific.
+
+## Dependencies
+vpc::deps:                                            # List of paths to files or directories outside
+                                                      # of the module directory that are to be copied
+                                                      # into the working directory of the module during
+                                                      # Covalence execution. An example of this would be
+                                                      # an SSH key for cloning a private Terraform
+                                                      # module.
+  - '.ssh'
+
+# Execution targets
+terraform::vpc::targets:                              # Resource targeting. The key is prepended with
+                                                      # the module name, as target assignment can be
+                                                      # shared across contexts.
+
+  az0:                                                # Context name
+    - 'module.az0'                                    # Resource target (e.g. terraform plan -target=module.az0)
+  az1:
+    - 'module.az1'
+
+# Additional arguments
+terraform::vpc::args: '-no-color'                     # Additional arguments to be passed to Terraform.
+                                                      # The key is prepended with the module name, as
+                                                      # arguments can be shared across contexts.
+
+# Input variables
+terraform::vpc::vars:                                 # Input variables. The key is prepended with the
+                                                      # module name, as variable assignment can be shared
+                                                      # across contexts.
+
+  region: 'us-east-1'                                 # Short form input string
+  stack_item_label: 'testing'
+```
+
+As indicated in the comments above, keys that are stack specific are prepended with the stack name as opposed to the module name. Currently, this include the `module` and `state` parameters only. All other keys will be prepended with the module name, allowing for data sharing between stacks that are based on the same module.
+
+To demonstrate this, let's add a `data/environments/test.yaml` file and configure it as follows:
+
+**data/environments/test.yaml**
+```yaml
+---
+# Test environment
+
+# VPC input variables
+terraform::vpc::vars:
+  region: 'us-west-2'
+```
+
+Let's also go ahead and define some environments by adding the following to `data/environments.yaml`:
+
+**data/environments.yaml**
+```yaml
+---
+environments:
+  test:
+    - vpc
+  staging:
+    - vpc
+```
+
+Our configuration now has two actionable contexts of the VPC stack; `test` and `staging`.
+
+A call to `bin/covalence -l` will now produce output similar to the following:
+
+```bash
+$ bin/covalence -l
+staging:vpc:apply               # Apply changes to the vpc stack of the staging environment
+staging:vpc:destroy             # Destroy the vpc stack of the staging environment
+staging:vpc:format              # Format the vpc stack of the staging environment
+staging:vpc:plan                # Create execution plan for the vpc stack of the staging environment
+staging:vpc:plan_destroy        # Create destruction plan for the vpc stack of the staging environment
+staging:vpc:refresh             # Refresh the vpc stack of the staging environment
+staging:vpc:sync                # Synchronize state stores for the vpc stack of the staging environment
+staging:vpc:verify              # Verify the vpc stack of the staging environment
+test:vpc:apply                  # Apply changes to the vpc stack of the test environment
+test:vpc:destroy                # Destroy the vpc stack of the test environment
+test:vpc:format                 # Format the vpc stack of the test environment
+test:vpc:plan                   # Create execution plan for the vpc stack of the test environment
+test:vpc:plan_destroy           # Create destruction plan for the vpc stack of the test environment
+test:vpc:refresh                # Refresh the vpc stack of the test environment
+test:vpc:sync                   # Synchronize state stores for the vpc stack of the test environment
+test:vpc:verify                 # Verify the vpc stack of the test environment
+```
+
+If we were to execute the `staging:vpc:plan` task, we will see that the VPC is targeted for the `us-east-1` region. However, if we execute the `test:vpc:plan` task, we will see that the VPC is targeted for the `us-west-2` region.
+
+If we review our hierarchy, we see that values in the `environments` directory take precedence over those in the `stacks` directory. With the addition of `data/environments/test.yaml`, we have introduced variable overrides for the stack defaults in the context of the test environment. As there is no `data/environments/staging.yaml`, the stack default of `us-east-1` is the first value discovered when traversing the hierarchy in the context of the staging environment.
+
+## Packer
+
+Packer stacks are managed in the same manner as Terraform stacks within Covalence, but have different configuration requirements. A Packer stack must minimally include a module and build template mapping.
+
+```yaml
+---
+# ECS artifact defaults
+
+## Module
+ecs-artifact::module: 'packer/ecs'                    # Packer module directory if different than
+                                                      # the stack name. The key is prepended with the
+                                                      # stack name, as module assignment is stack specific.
+                                                      # Assets associated with the build (e.g. scripts)
+                                                      # should be co-located with the build template within
+                                                      # the module path.
+
+## Build template
+ecs-artifact::packer-template: 'aws-linux-ecs.json'   # Relative path to the Packer build template
+                                                      # from within the module directory.
+
+## Dependencies
+ecs-artifact::deps:                                   # List of paths to files or directories outside
+                                                      # of the module directory that are to be copied
+                                                      # into the working directory of the module during
+                                                      # Covalence execution. An example of this would be
+                                                      # a common suite of unit tests that exist above
+                                                      # the context of each individual Packer build.
+  - 'serverspec'
+
+## Input variables
+packer::ecs::vars:
+  region: "%{alias('region')}"                        # Example for looking up a value from another
+                                                      # context within the hierarchy (e.g. data/environments/test.yaml)
+  version: '1.0.0'
+```
+
+Note: Covalence provides support for YAML based Packer build templates. This capability is not compatible with native Packer, which only supports JSON.
+
+# Complex Inputs
+
+Covalence adds additional data processing capabilities on top of Hiera.
+
+The most basic input is a string. The following is an example of the short form notation for a string input.
+
+```yaml
+terraform::example::vars:
+  label: 'test'
+```
+
+Standard YAML notation for lists and maps will work as expected as well:
+
+```yaml
+terraform::example::vars:
+  labels:
+    - 'test0'
+    - 'test1'
+    - 'test2'
+  samples:
+    terraform: 'testing'
+    packer: 'testing'
+```
+
+The long form for the same inputs are as follows:
+
+```yaml
+terraform::example::vars:
+  label:
+    type: 'string'
+    value: 'test'
+  labels:
+    type: 'list'
+    value:
+      - 'test0'
+      - 'test1'
+      - 'test2'
+  samples:
+    type: 'map'
+    value:
+      terraform: 'testing'
+      packer: 'testing'
 ```
 
-And then execute:
+Maps are processed by Covalence as complex inputs. The `type` parameter is reserved for identifying the type of input. For simple types, like those shown above, the long format is unnecessary in most instances. However, it is the basis for invoking more complex lookups via integrations to other tools.
 
-    $ bundle
+For example, the following is an example of a lookup from a Terraform state file stored on S3:
 
-Or install it yourself as:
+```yaml
+terraform::ecs::cluster::vars:
+  vpc_id:
+    type: 's3.state'
+    bucket: "%{alias('tf_state_bucket')}"
+    document: "%{environment}/vpc/terraform.tfstate"
+    key: 'vpc_id'
+```
+
+See the Integrations section below for a list of supported lookups.
+
+Covalence will also perform UNIX shell interpolation on inputs of the following form:
+
+```yaml
+terraform::ecs::cluster::vars:
+  app_label: "$(echo 'this is a test')"
+```
+
+# Integrations
+
+## Terraform Enterprise (formerly Atlas)
+Module for interacting with the Terraform Enterprise backend.
+
+### Supported operations
+
+| K/V Read | K/V Write | Remote State Read | State Storage Backend |
+|:--------:|:---------:|:-----------------:|:---------------------:|
+| <img src="./images/checkmark.png"> | | <img src="./images/checkmark.png"> | <img src="./images/checkmark.png"> |
+
+### Configuration parameters
+
+| ENV Variable             | Default                           | Description                          |
+| ------------------------ | --------------------------------- | ------------------------------------ |
+| ATLAS_TOKEN              |                                   | HTTP authentication token.           |
+
+### Usage
+
+Artifacts:
+
+```yaml
+ami:
+  type: 'atlas.artifact'
+  slug: 'unifio/app/amazon.ami'
+  version: 'latest'
+  key: 'region.us-east-1'
+```
+
+State Outputs:
+
+```yaml
+vpc_id:
+  type: 'atlas.state'
+  stack: 'unifio/vpc'
+  key: 'vpc_id'
+```
 
-    $ gem install prometheus_unifio
+## Consul
+Module for interacting with the Consul backend.
 
-## Usage
+### Supported operations
 
-TODO: Write usage instructions here
+| K/V Read | K/V Write | Remote State Read | State Storage Backend |
+|:--------:|:---------:|:-----------------:|:---------------------:|
+| <img src="./images/checkmark.png"> | | <img src="./images/checkmark.png"> | <img src="./images/checkmark.png"> |
 
-## Development
+### Configuration parameters
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+| ENV Variable             | Default                           | Description                          |
+| ------------------------ | --------------------------------- | ------------------------------------ |
+| CONSUL_HTTP_ADDR         |                                   | DNS name and port of your Consul endpoint specified in the format dnsname:port. Defaults to the local agent HTTP listener. |
+| CONSUL_HTTP_TOKEN        |                                   | HTTP authentication token |
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Usage
 
-## Contributing
+Keys:
+
+```yaml
+ami:
+  type: 'consul.key'
+  key: 'unifio/app/amazon.ami'
+```
+
+State Outputs:
+
+```yaml
+vpc_id:
+  type: 'consul.state'
+  stack: 'unifio/vpc'
+  key: 'vpc_id'
+```
+
+## S3
+Module for interacting with the AWS Simple Storage Service (S3) backend.
+
+### Supported operations
+
+| K/V Read | K/V Write | Remote State Read | State Storage Backend |
+|:--------:|:---------:|:-----------------:|:---------------------:|
+| <img src="./images/checkmark.png"> | | <img src="./images/checkmark.png"> | <img src="./images/checkmark.png"> |
+
+### Configuration parameters
+
+| ENV Variable             | Default                           | Description                          |
+| ------------------------ | --------------------------------- | ------------------------------------ |
+| AWS_ACCESS_KEY_ID        |                                   | AWS access key. |
+| AWS_SECRET_ACCESS_KEY    |                                   | AWS secret key. Access and secret key variables override credentials stored in credential and config files. |
+| AWS_REGION               |                                   | AWS region. This variable overrides the default region of the in-use profile, if set. |
+| AWS_PROFILE              |                                   | AWS profile. For use with with a credential file. |
+
+### Usage
+
+Keys:
+
+```yaml
+docker_image:
+  type: 's3.key'
+  bucket: 'artifact-registry'
+  document: 'app-prod.json'
+  key: 'id'
+```
+
+State Outputs:
+
+```yaml
+vpc_id:
+  type: 's3.state'
+  bucket: 'terraform-state'
+  document: 'production/vpc/terraform.tfstate'
+  key: 'vpc_id'
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/prometheus_unifio. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+# Build From Source
 
+Covalence is packaged as a Ruby Gem.
 
-## License
+Execute the following to build the gem:
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+`$ gem build covalence.gemspec`
 
+Gem artifacts are hosted at https://repo.fury.io/unifio/.