This repository is no longer being used. Its contents were moved to bigchaindb/bigchaindb and it's just being kept around for historical interest. To understand why the move was done, and more, see issue bigchaindb/bigchaindb#1588.
nginx_3scale agent is a module that is responsible for providing authentication, authorization and metering of BigchainDB API users, by communicating with 3scale. We use the openresty for this, which is nginx bundled with lua libraries. More information at their website
It validates the tokens sent by users in HTTP headers. The user tokens map directly to the Application Plan specified in 3scale.
Use the docker_build_and_push.bash script to build the latest docker image
and upload it to Docker Hub.
Ensure that the image tag is updated to a new version number to properly
reflect any changes made to the container.
-
We define a lua module and custom hooks (lua functions to be executed at certain phases of the nginx request processing lifecycle) to authenticate an API request.
-
Download the template available from 3scale which pre-defines all the rules defined using the 3scale UI for monitoring, and the basic nginx configuration.
-
We heavily modify these templates to add our custom functionality.
-
The nginx_3scale image reads the environment variables and accordingly creates the nginx.conf and nginx.lua files from the templates.
-
Every request calls the
_M.access()function. This function extracts theapp_idandapp_keyfrom the HTTP request headers and forwards it to 3scale to see if a request is allowed to be forwarded to the BigchainDB backend. The request also contains the various parameters that one would like to set access policies on. If theapp_idandapp_keyis successful, the access rules for the parameters passed with the request are checked to see if the request can pass through. For example, we can send a parameter, sayrequest_body_size, to the 3scale auth API. If we have defined a rule in the 3scale dashboard to droprequest_body_sizeabove a certain threshold, the authorization will fail even if theapp_idandapp_keyare valid. -
A successful response from the auth API causes the request to be proxied to the backend. After a backend response, the
_M.post_action_contenthook is called. We calculate details about all the metrics we are interested in and form a payload for the 3scale reporting API. This ensures that we update parameters of every metric defined in the 3scale UI after every request. -
Note: We do not cache the keys in nginx so that we can validate every request with 3scale and apply plan rules immediately. We can add auth caching to improve performance, and in case we move to a fully post-paid billing model.
-
Refer to the references made in the lua module for more details about how nginx+lua+3scale works
-
For HTTPS support, we also need to add the signed certificate and the corresponding private key to the folder
/usr/local/openresty/nginx/conf/ssl/. Name the pem-encoded certificate ascert.pemand the private key ascert.key.
We currently use the terms frontend, backend, upstream in our code and
configuration. This diagram should help understand the various terms.
The final goal is to have a deployment that looks like this:
+------------+ +------------+
| | | |
+-----------------------------+----+ N | +---------------------+------+ |
| BigchainDB Frontend Port | G | | BigchainDB Backend Port | |
| | I | | | |
|[port number exposed globally | N | +--------> |[port where BDB instance | |
| for backend BDB cluster services]| X | | | listens/waits for requests]| |
+-----------------------------+----+ | | +---------------------+------+ |
| G | | | |
+-----------------------------+----+ A | | | BigchainDB |
| Health Check Port | T | | | Backend |
| | E | | | Host |
| [port number exposed to the LB | W | | +------------+
| for health checks] | A | |
+-----------------------------+----+ Y | | +------------+
| | | | MongoDB |
| +--+------------------+-------+ | Backend |
+-----------------------------+----+ | Upstream API Port | | Host |
| MongoDB Frontend Port | | | | |
| | |[internal port where we can | +--------------------+--------+ |
| [port number for MongoDB | |access backend BDB cluster | | MongoDB Backend Port | |
| instances to communicate | +--+--------------------------+ | | |
| with each other +-------+----------------------------->|[port where MongoDB instance | |
+-----------------------------+----+ | | listens/waits for requests] | |
| | +--------------------+--------+ |
+------------+ +------------+