Merge pull request #137 from desimone/docs/add-upgrading-guide

docs: add upgrade guide

docs/.vuepress/config.js

@@ -52,7 +52,7 @@ function docsSidebar(title) {
 		{
 			title,
 			collapsable: false,
-			children: ["", "identity-providers", "signed-headers", "certificates", "examples"]
+			children: ["", "identity-providers", "signed-headers", "certificates", "examples", "upgrading"]
 		}
 	];
 }

docs/docs/upgrading.md

@@ -0,0 +1,49 @@
+---
+title: Upgrading
+description: >-
+  This page contains the list of deprecations and important or breaking changes
+  for Pomerium. Please read it carefully.
+---
+
+# Overview
+
+## Since 0.0.4
+
+This page contains the list of deprecations and important or breaking changes for pomerium `v0.0.4` compared to `v0.0.5`. Please read it carefully.
+
+### Breaking: POLICY_FILE removed
+
+Usage of the POLICY_FILE envvar is no longer supported.  Support for file based policy configuratin has been shifted into the new unified config file.  
+
+### Important: Configuration file support added
+
+* Pomerium now supports an optional -config flag.  This flag specifies a file from which to read all configuration options.  It supports yaml, json, toml and properties formats.
+
+* All options which can be specified via MY_SETTING style envvars can now be specified within your configuration file as key/value.  The key is generally the same as the envvar name, but lower cased.  See Reference Documentation for exact names.
+
+* Options precedence is ENV > Config > Defaults
+
+* The options file supports a policy key, which contains policy in the same format as POLICY_FILE.  To convert an existing policy.yaml into a config.yaml, just move your policy under a policy key.
+
+  Old:
+  ```yaml
+  - from: httpbin.corp.beyondperimeter.com
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+    cors_allow_preflight: true
+    timeout: 30s
+  ```
+
+  New:
+  ```yaml
+  policy:
+    - from: httpbin.corp.beyondperimeter.com
+      to: http://httpbin
+      allowed_domains:
+        - pomerium.io
+      cors_allow_preflight: true
+      timeout: 30s
+  ```
+
+### Z