Merge pull request #1706 from 18F/egress-docs

updates egress documentation

docs/egress.md

@@ -26,61 +26,90 @@ cloud.gov allows configuration of [egress traffic controls](https://cloud.gov/do
 
 ## Tock staging setup
 
+### Create the egress proxy
+
 To create a new proxy, follow the [cf-egress-proxy README](https://github.com/GSA-TTS/cg-egress-proxy).
 
 As an example, to set up egress for Tock staging:
 
-- create a new cloud.gov space
-  - `cf create-space staging-egress -o gsa-18f-tock`
-- git clone [GSA-TTS/cf-egress-proxy](https://github.com/GSA-TTS/cg-egress-proxy)
-- build the Caddy proxy (optional, not needed anymore)
-  - `make caddy-v2-with-forwardproxy`
-  - note: requires Docker
-- rename `vars.myapp.yml` to `vars.tock.yml`
-  - configure `proxyname`, `hostname`, `username` and `password`
-  - configure with above proxy rules
-- `cf target -s staging-egress`
-- `cf push --vars-file vars.tock.yml`
-- enable Tock staging to connect to Tock egress
-  - `cf add-network-policy tock-staging staging-egress -s staging-egress`
+Create a new cloud.gov space
+```bash
+cf login -a api.fr.cloud.gov --sso
+cf create-space staging-egress -o gsa-18f-tock
+```
+
+Clone the egress proxy from [GSA-TTS/cf-egress-proxy](https://github.com/GSA-TTS/cg-egress-proxy). Refer to its documentation for more information about local development.
+```bash
+git clone [email protected]:GSA-TTS/cg-egress-proxy.git
+```
 
-At this stage it is prudent to verify that the proxy is working as advertised. One way is to `cf ssh` the staging environment (`cf ssh staging-egress -t -c "/tmp/lifecycle/launcher /home/vcap/app /bin/bash 0"`) and test with commands such as `curl -x "https://<username>:<password>@<egress-host>.apps.internal:61443" restricted-domain.com` and make sure Caddy returns a `403 Forbidden`. Similarly, you want to test for trusted domains and verify that the proxy passes these requests through. 
+Rename `vars.yml-example` to `vars.tock.yml` and configure it for your application. Use `uuidgen` for the username and password.
 
-Test that curl connects properly from your application's container.
+```
+proxyname:  staging-egress
+hostname:   tock-staging-egress
+username:   (generated)
+password:   (generated)
+
+# See [the docs]() for more about what can appear below
+proxydeny:
+proxyallow: |
+  uaa.fr.cloud.gov
+  google-analytics.com
+```
+
+Open `manifest.yml` and change the instances to 1:
 
 ```bash
-# Get a shell inside the app
-$ cf ssh staging-egress -t -c "/tmp/lifecycle/launcher /home/vcap/app /bin/bash 0"
+    instances: 1
+```
 
-# Use curl to test that the container can reach things it should
-$ curl http://allowedhost:allowedport
-[...response from allowedhost...] # allowed
+Push the egress application to your space
+```bash
+cf target -s staging-egress
+cf push --vars-file vars.tock.yml
+```
+
+SSH into the proxy to make sure that it is running and restricting URLs as advertised.
+
+```bash
+cf ssh staging-egress -t -c "/tmp/lifecycle/launcher /home/vcap/app /bin/bash 0"
+
+# from the staging-egress terminal
+
+# test that it is blocking egress appropriately
+$ curl https://18f.gsa.gov
+> curl: (56) Received HTTP code 403 from proxy after CONNECT
 
-$ curl https://allowedhost:allowedport
-[...response from allowedhost...] # allowed
+# test that it is allowing egress appropriately
+$ curl https://google-analytics.com
+> (html response)
+```
+
+Once that looks good, you will need to set the proxy environment variable on Tock staging. Use the proxy path from the egress space.
 
-# Use curl to test that the container can't reach things it shouldn't
-$ curl http://allowedhost:deniedport
-curl: (56) Received HTTP code 403 from proxy after CONNECT # denied
+```bash
+cf target -s tock-staging
 
-$ curl http://deniedhost:allowedport
-curl: (56) Received HTTP code 403 from proxy after CONNECT # denied
+# enable tock staging to talk to the egress server
+cf add-network-policy tock-staging staging-egress -s staging-egress
 
-$ curl https://allowedhost:deniedport
-curl: (56) Received HTTP code 403 from proxy after CONNECT # denied
+# provide an environment variable with the egress_proxy path
+cf set-env tock-staging egress_proxy https://<username>:<password>@<egress-host>.apps.internal:61443
 
-$ curl https://deniedhost:allowedport
-curl: (56) Received HTTP code 403 from proxy after CONNECT # denied
+# restage the application so it can use the variable
+cf restage tock-staging
 ```
 
-Once everything looks good:
+SSH into the Tock staging space and confirm with `curl` that traffic out is being vetted by staging-egress.
+
+__Note:__ The [../.profile](.profile file) (see the [relevant documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/deploy-app.html#profile)) is configured to export the environmental variables `http_proxy` and `https_proxy` to whatever `egress_proxy` is set to. This allows us to update cloud.gov buildpacks and build the application itself without the proxy active. In other words, the proxy is only active once the application has booted up.
 
-- set the proxy environment variable on Tock staging
-  - `cf set-env tock-staging egress_proxy https://<username>:<password>@<egress-host>.apps.internal:61443`
-- restage Tock staging
-  - `cf restage tock-staging`
-    - Note that the [../.profile](.profile file) (see the [relevant documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/deploy-app.html#profile)) is configured to export the environmental variables `http_proxy` and `https_proxy` to whatever `egress_proxy` is set to.
-    - Doing so allows us to update cloud.gov buildpacks and build the application itself without the proxy active. In other words, the proxy is only active once the application has booted up.
+If you need to troubleshoot, you may want to start with the logs:
+
+```bash
+cf logs staging-egress --recent
+```
 
 ## A note on SSL certificates