diff options
Diffstat (limited to 'contrib/cirrus/README.md')
| -rw-r--r-- | contrib/cirrus/README.md | 62 |
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: + + + +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. |