summaryrefslogtreecommitdiff
path: root/contrib/cirrus/README.md
diff options
context:
space:
mode:
authorChris Evich <cevich@redhat.com>2020-06-08 13:45:26 -0400
committerChris Evich <cevich@redhat.com>2020-06-09 09:53:19 -0400
commit4314336ce346efb3f9aa128a3dd9680603cffaf4 (patch)
tree170d771aa413a06ec1afafb91fc1b44a776727a5 /contrib/cirrus/README.md
parent2869cce1d53aedfe2500f3d921fb901dd5994690 (diff)
downloadpodman-4314336ce346efb3f9aa128a3dd9680603cffaf4.tar.gz
podman-4314336ce346efb3f9aa128a3dd9680603cffaf4.tar.bz2
podman-4314336ce346efb3f9aa128a3dd9680603cffaf4.zip
Improve swagger+CORS metadata docs
Signed-off-by: Chris Evich <cevich@redhat.com>
Diffstat (limited to 'contrib/cirrus/README.md')
-rw-r--r--contrib/cirrus/README.md62
1 files changed, 47 insertions, 15 deletions
diff --git a/contrib/cirrus/README.md b/contrib/cirrus/README.md
index 541cf2f54..c8ec766e7 100644
--- a/contrib/cirrus/README.md
+++ b/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.
-
-***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:
+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)
+
+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.