Improve swagger+CORS metadata docs

Signed-off-by: Chris Evich <cevich@redhat.com>

contrib/cirrus/README.md

@@ -167,26 +167,50 @@ env:
 
 ### `docs` Task
 
-Builds swagger API documentation YAML and uploads to google storage for both
-PR's (for testing the process) and after a merge into any branch.  For PR's
+Builds swagger API documentation YAML and uploads to google storage (an online
+service for storing unstructured data) for both
+PR's (for testing the process) and the master branch.  For PR's
 the YAML is uploaded into a [dedicated short-pruning cycle
-bucket.](https://storage.googleapis.com/libpod-pr-releases/)  For branches,
-a [separate bucket is
-used.](https://storage.googleapis.com/libpod-master-releases)
-In both cases the filename includes the source
-PR number or branch name.
+bucket.](https://storage.googleapis.com/libpod-pr-releases/) for testing purposes
+only.  For the master branch, a [separate bucket is
+used](https://storage.googleapis.com/libpod-master-releases) and provides the
+content rendered on [the API Reference page](https://docs.podman.io/en/latest/_static/api.html)
 
-***Note***: [The online documentation](http://docs.podman.io/en/latest/_static/api.html)
-is presented through javascript on the client-side.  This requires CORS to be properly
-configured on the bucket, for the `http://docs.podman.io` origin.  Please see
-[Configuring CORS on a bucket](https://cloud.google.com/storage/docs/configuring-cors#configure-cors-bucket)
-for details.  This may be performed by anybody with admin access to the google storage bucket,
-using the following JSON:
+The online API reference is presented by javascript to the client.  To prevent hijacking
+of the client by malicious data, the [javascript utilises CORS](https://cloud.google.com/storage/docs/cross-origin).
+This CORS metadata is served by `https://storage.googleapis.com` when configured correctly.
+It will appear in [the request and response headers from the
+client](https://cloud.google.com/storage/docs/configuring-cors#troubleshooting) when accessing
+the API reference page.
+
+However, when the CORS metadata is missing or incorrectly configured, clients will receive an
+error-message similar to:
+
+![Javascript Stack Trace Image](swagger_stack_trace.png)
+
+For documentation built by Read The Docs from the master branch, CORS metadata is
+set on the `libpod-master-releases` storage bucket.  Viewing or setting the CORS
+metadata on the bucket requires having locally [installed and
+configured the google-cloud SDK](https://cloud.google.com/sdk/docs).  It also requires having
+admin access to the google-storage bucket.  Contact a project owner for help if you are
+unsure of your permissions or need help resolving an error similar to the picture above.
+
+Assuming the SDK is installed, and you have the required admin access, the following command
+will display the current CORS metadata:
+
+```
+gsutil cors get gs://libpod-master-releases
+```
+
+To function properly (allow client "trust" of content from `storage.googleapis.com`) the followiing
+metadata JSON should be used.  Following the JSON, is an example of the command used to set this
+metadata on the libpod-master-releases bucket.  For additional information about configuring CORS
+please referr to [the google-storage documentation](https://cloud.google.com/storage/docs/configuring-cors).
 
 ```JSON
 [
     {
-      "origin": ["http://docs.podman.io"],
+      "origin": ["http://docs.podman.io", "https://docs.podman.io"],
       "responseHeader": ["Content-Type"],
       "method": ["GET"],
       "maxAgeSeconds": 600
@@ -194,6 +218,14 @@ using the following JSON:
 ]
 ```
 
+```
+gsutil cors set /path/to/file.json gs://libpod-master-releases
+```
+
+***Note:*** The CORS metadata does _NOT_ change after the `docs` task uploads a new swagger YAML
+file.  Therefore, if it is not functioning or misconfigured, a person must have altered it or
+changes were made to the referring site (e.g. `docs.podman.io`).
+
 ## Base-images
 
 Base-images are VM disk-images specially prepared for executing as GCE VMs.

docs/Readme.md

@@ -30,10 +30,26 @@ link on that page.
 ## API Reference
 
 The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
-automatically generated from committed upstream sources.  There is a short-duration
-cache involved, in case old content or an error is returned, try clearing your browser
-cache or returning to the site after 10-30 minutes.
+automatically generated by two cooperating automation systems based on committed upstream
+source code.  Firstly, [the Cirrus-CI docs task](../contrib/cirrus/README.md#docs-task) builds
+`pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket -
+an online service for storing unstructured data).  Second, [Read The Docs](readthedocs.com)
+reacts to the github.com repository change, building the content for the [libpod documentation
+site](https://podman.readthedocs.io/).  This site includes for the API section,
+some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
+Storage Bucket.
 
-***Maintainers Note***: Please refer to [the Cirrus-CI tasks
-documentation](../contrib/cirrus/README.md#docs-task) for
-important operational details.
+Since there are multiple systems and local cache is involved, it's possible that updates to
+documentation (especially the swagger/API docs) will lag by 10-or-so minutes.  However,
+because the client (i.e. your web browser) is fetching content from multiple locations that
+do not share a common domain, accessing the API section may show a stack-trace similar to
+the following:
+
+![Javascript Stack Trace Image](../contrib/cirrus/swagger_stack_trace.png)
+
+If reloading the page, or clearing your local cache does not fix the problem, it is
+likely caused by broken metadata needed to protect clients from cross-site-scripting
+style attacks.  Please [notify a maintainer](https://github.com/containers/libpod#communications)
+so they may investigate how/why the swagger.yaml file's CORS-metadata is incorrect.  See
+[the Cirrus-CI tasks documentation](../contrib/cirrus/README.md#docs-task) for
+details regarding this situation.