opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-06-12 19:14:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #6521 from cevich/update_cors_docs

Browse Source 
[CI:DOCS] Improve swagger+CORS metadata docs
This commit is contained in:
OpenShift Merge Robot
2020-06-09 16:43:32 +02:00
committed by GitHub
parent a2e0e170f9 4314336ce3
commit c831ae110e
3 changed files with 68 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
contrib/cirrus/README.md
View File

@ -167,26 +167,50 @@ env:
### `docs` Task ### `docs` Task
Builds swagger API documentation YAML and uploads to google storage for both Builds swagger API documentation YAML and uploads to google storage (an online
PR's (for testing the process) and after a merge into any branch. For PR's 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 the YAML is uploaded into a [dedicated short-pruning cycle
bucket.](https://storage.googleapis.com/libpod-pr-releases/) For branches, bucket.](https://storage.googleapis.com/libpod-pr-releases/) for testing purposes
a [separate bucket is only. For the master branch, a [separate bucket is
used.](https://storage.googleapis.com/libpod-master-releases) used](https://storage.googleapis.com/libpod-master-releases) and provides the
In both cases the filename includes the source content rendered on [the API Reference page](https://docs.podman.io/en/latest/_static/api.html)
PR number or branch name.
***Note***: [The online documentation](http://docs.podman.io/en/latest/_static/api.html) The online API reference is presented by javascript to the client. To prevent hijacking
is presented through javascript on the client-side. This requires CORS to be properly of the client by malicious data, the [javascript utilises CORS](https://cloud.google.com/storage/docs/cross-origin).
configured on the bucket, for the `http://docs.podman.io` origin. Please see This CORS metadata is served by `https://storage.googleapis.com` when configured correctly.
[Configuring CORS on a bucket](https://cloud.google.com/storage/docs/configuring-cors#configure-cors-bucket) It will appear in [the request and response headers from the
for details. This may be performed by anybody with admin access to the google storage bucket, client](https://cloud.google.com/storage/docs/configuring-cors#troubleshooting) when accessing
using the following JSON: 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 ```JSON
[ [
{ {
"origin": ["http://docs.podman.io"], "origin": ["http://docs.podman.io", "https://docs.podman.io"],
"responseHeader": ["Content-Type"], "responseHeader": ["Content-Type"],
"method": ["GET"], "method": ["GET"],
"maxAgeSeconds": 600 "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
Base-images are VM disk-images specially prepared for executing as GCE VMs. Base-images are VM disk-images specially prepared for executing as GCE VMs.

BIN
contrib/cirrus/swagger_stack_trace.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

28
docs/Readme.md
View File

@ -30,10 +30,26 @@ link on that page.
## API Reference ## API Reference
The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is 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 automatically generated by two cooperating automation systems based on committed upstream
cache involved, in case old content or an error is returned, try clearing your browser source code. Firstly, [the Cirrus-CI docs task](../contrib/cirrus/README.md#docs-task) builds
cache or returning to the site after 10-30 minutes. `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 Since there are multiple systems and local cache is involved, it's possible that updates to
documentation](../contrib/cirrus/README.md#docs-task) for documentation (especially the swagger/API docs) will lag by 10-or-so minutes. However,
important operational details. 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.