Merge pull request #46 from objectrocket/readme-updates

Add some more examples and info to the README

Author: ephur

README.md

@@ -62,6 +62,52 @@ Build and publish the package to PYPI:
  % poetry publish --build
 ```
 
+## Configuration
+
+A project is configured through a worker config, a yaml file that specifies the definitions, inputs, outputs, providers and all other necessary configuration. The worker config is what specifies how state is shared among your definitions. The config support jinja templating that can be used to conditionally pass state or pass in env variables through the command line via the `--config-var` option.
+
+*./worker.yaml*
+```yaml
+terraform:
+  providers:
+    aws:
+      vars:
+        region: {{ aws-region }}
+        version: "~> 2.61"
+
+  # global level variables
+  terraform_vars:
+    region: {{ aws-region }}
+    environment: dev
+
+  definitions:
+    # Either setup a VPC and resources, or deploy into an existing one
+    network:
+      path: /definitions/aws/network-existing
+
+    database:
+      path: /definitions/aws/rds
+      remote_vars:
+        subnet: network.outputs.subnet_id
+```
+
+In this config, the worker manages two separate terraform modules, a `network` and a `database` definition, and shares an output from the network definition with the database definition. This is made available inside of the `database` definition through the `local.subnet` value.
+
+`aws-region` is substituted at runtime for the value of `--aws-region` passed through the command line.
+
+## Troubleshooting
+
+Running the worker with the `--no-clean` option will keep around the terraform files that the worker generates. You can use these generated files to directly run terraform commands for that definition. This is useful for when you need to do things like troubleshoot or delete items from the remote state. After running the worker with --no-clean, cd into the definition directory where the terraform-worker generates it's tf files. The worker should tell you where it's putting these for example:
+
+```
+...
+building deployment mfaitest
+using temporary Directory: /tmp/tmpew44uopp
+...
+```
+
+In order to troubleshoot this definition, you would cd /tmp/tmpew44uopp/definitions/my_definition/ and then perform any terraform commands from there.
+
 ## Background
 
 The terraform worker was a weekend project to run terraform against a series of definitions (modules). The idea was the configuration vars, provider configuration, remote state, and variables from remote state would all be dynamically generated. The purpose was for building kubernetes deployments, and allowing all of the configuration information to be stored as either yamnl files in github, or have the worker configuration generated by an API which stored all of the deployment configurations in a database.