Skip to content

Latest commit

 

History

History
122 lines (87 loc) · 4.21 KB

migrating_to_17.md

File metadata and controls

122 lines (87 loc) · 4.21 KB
Raw

Migrating to Bento v17

Key points:

  • Bento now has observability tools to help monitor the services (Grafana). Some setup is required for this feature to work.
  • Katsu discovery endpoints now have an authorization layer.
    • Data that used to be completely public by default (i.e., censored counts) now requires a permission (query:project_level_counts and/or query:dataset_level_counts), and thus a grant in the authorization service.
    • Beacon now requires a client ID/secret and an authorization service grant to access uncensored data.
  • Katsu discovery is now more granular, and can be configured to the project or dataset level, in addition to the instance level. See the Public data discovery configuration document for more information.
  • ...

1. Stop Bento

./bentoctl.bash stop

2. Checkout to v17 and pull new Docker images

# Checkout on the v17 tag
git checkout v17
# Pull new Docker images
./bentoctl.bash pull

3. Set up credentials for aggregation/Beacon and, optionally, set up Grafana

If you wish to enable Grafana, you first must enable the monitoring feature in your local.env file:

BENTO_MONITORING_ENABLED='true'

After enabling the Grafana feature flag for the first time, you must initialize the Docker networks and mounted directories.

# Init new Docker networks and directories if using Grafana
./bentoctl.bash init-docker
./bentoctl.bash init-dirs

To create the client secrets for aggregation/Beacon and Grafana (if the latter is enabled), run the following commands:

./bentoctl.bash run auth && ./bentoctl.bash run gateway
./bentoctl.bash init-auth

Reminder: Make sure to put the client secret(s) generated by init-auth into your local.env file!

Aggregation/Beacon data access authorization will not work until an authorization service grant is configured; see step 4 below.

Grafana will not be accessible to users until they are given a valid role; see the monitoring user management section for details.

4. Set up aggregation/Beacon permissions and public data access grants

Now that Beacon uses a client ID/secret to get authorized, uncensored data access for discovery, a grant must be configured to give the aggregation/Beacon client data access.

Another change to permissions: starting from Bento v17, anonymous visitors do not have access to see censored counts data by default, even if a discovery configuration has been set up. For anonymous visitors to access data, a level (bool, counts, full) must be chosen and passed to the bento_authz CLI command below.

./bentoctl.bash run authz
./bentoctl.bash shell authz

# Configure aggregation/Beacon permissions
# ----------------------------------------
# This assumes the aggregation/Beacon client ID is "aggregation". 
# <ISSUER_HERE> MUST be replaced with your actual issuer value.
#  - The query:data permission gives access to Katsu endpoints which are properly authz-enabled.
#  - The view:private_portal permission gives access to Katsu and Gohan endpoints where the proxy still manages access.
#    This permission will be removed in an uncoming version.
bento_authz create grant \
  '{"iss": "<ISSUER_HERE>", "client": "aggregation"}' \
  '{"everything": true}' \
  'query:data' 'view:private_portal'

# Configure public data access
# ----------------------------
# The level below ("counts") preserves previous functionality. Other possible options are:
#  - none - will do nothing.
#  - bool - for censored true/false discovery, but in effect right now forbids access.
#  - counts - for censored count discovery.
#  - full - allows full data access (record-level, including sensitive data such as IDs), uncensored counts, etc.
bento_authz public-data-access counts

5. Optionally, add Beacon network

To host a network of beacons, with a corresponding UI in Bento Public, first copy the config file:

./bentoctl.bash init-config beacon-network

then update values at lib/beacon/config/beacon_network_config.json. Activate the network by adding (or modifying) this value in local.env:

BENTO_BEACON_NETWORK_ENABLED='true'

6. Start Bento

./bentoctl.bash start