-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: introduce deployment & development guides
Add one page covering deployment issues and one page covering development. The motivation of introducing these docs right now is to ensure there's a place where the authentication scheme can be documented. Other sections of the docs are light on detail at the moment.
- Loading branch information
Showing
5 changed files
with
122 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
.. _deploy-guide: | ||
|
||
Deployment Guide | ||
================ | ||
|
||
|
||
Target platform | ||
--------------- | ||
|
||
exodus-gw is an ASGI application which may be deployed using any ASGI-compliant | ||
web server. The development team's recommended setup is summarized as: | ||
|
||
- Use OpenShift >= 4.x to deploy the service. | ||
|
||
- Use the exodus-gw images at https://quay.io/repository/exodus/exodus-gw to run | ||
the service. These images run the service using gunicorn & uvicorn on RHEL8. | ||
|
||
In general, the | ||
`uvicorn deployment advice <https://www.uvicorn.org/deployment/>`_ | ||
applies. | ||
|
||
- Deploy the service's primary container behind a reverse-proxy implementing | ||
authentication according to your organization's needs (see next section). | ||
|
||
|
||
Authentication & Authorization | ||
------------------------------ | ||
|
||
The exodus-gw service does not implement any authentication mechanism. It is instead | ||
designed to integrate with a reverse-proxy implementing any desired mechanism. | ||
|
||
.. warning:: | ||
If exodus-gw is deployed without an authenticating reverse-proxy, the service must | ||
be considered completely unsecured - all users will be able to perform all operations. | ||
|
||
This reverse-proxy must add an ``X-RhApiPlatform-CallContext`` header onto all incoming | ||
requests. This header must contain a base64-encoded form of the following JSON object: | ||
|
||
.. code-block:: json | ||
{ | ||
"client": { | ||
"roles": ["someRole", "anotherRole"], | ||
"authenticated": true, | ||
"serviceAccountId": "clientappname" | ||
}, | ||
"user": { | ||
"roles": ["viewer"], | ||
"authenticated": true, | ||
"internalUsername": "someuser" | ||
} | ||
} | ||
The ``roles`` and ``authenticated`` fields influence whether an exodus-gw request will be | ||
permitted - the necessary roles are documented on relevant exodus-gw API endpoints. | ||
Other fields are unused or used only for logging. | ||
|
||
The separate ``client`` and ``user`` fields can be used to separate service accounts | ||
(machine users) from human users, but this does not affect exodus-gw. | ||
|
||
Within Red Hat, a container known as "platform-sidecar" is used as the reverse proxy - consult | ||
internal documentation for information on this component. In other contexts, any reverse | ||
proxy may be used as long as it produces headers according to the scheme documented above. | ||
|
||
|
||
Settings | ||
-------- | ||
|
||
.. autoclass:: exodus_gw.settings.Settings() | ||
:members: | ||
|
||
exodus-gw may be configured by the following settings. | ||
|
||
Each settings value may be overridden using an environment variable of the | ||
same name, prefixed with ``EXODUS_GW_`` (example: ``EXODUS_GW_CALL_CONTEXT_HEADER``). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
.. _dev-guide: | ||
|
||
Development Guide | ||
================= | ||
|
||
This document contains useful info for developers contributing | ||
to the exodus-gw project. | ||
|
||
|
||
Spoofing authentication | ||
----------------------- | ||
|
||
The exodus-gw service parses an ``X-RhApiPlatform-CallContext`` header for information | ||
relating to authentication & authorization; see :ref:`deploy-guide` for more info on | ||
this scheme. | ||
|
||
During development, arbitrary values for this header may be used to test the | ||
behavior of endpoints with various roles. However, due to the format of this header, | ||
generating these values by hand can be cumbersome. | ||
|
||
To assist in this, a helper script is provided in the exodus-gw repo at | ||
``scripts/call-context``. This script accepts any number of role names as arguments | ||
and produces a header value which will produce an authenticated & authorized request | ||
using those roles. | ||
|
||
For example, if we want to use ``curl`` to make a request to an endpoint needing | ||
``qa-uploader`` role, we can use the following command: | ||
|
||
.. code-block:: shell | ||
curl \ | ||
-H "X-RhApiPlatform-CallContext: $(scripts/call-context qa-uploader)" \ | ||
http://localhost:8080/some/qa/endpoint | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters