From 56087183020831e723296c6399565b998cf06aca Mon Sep 17 00:00:00 2001 From: Jeffrey Lester Date: Thu, 14 Nov 2024 23:29:01 -0800 Subject: [PATCH] Update module readmes --- src/lib/modules/admin/cache-service/readme.md | 18 ++++ src/lib/modules/admin/data-products/readme.md | 7 +- .../admin/file-group-provider/readme.md | 6 +- src/lib/modules/admin/insights/readme.md | 18 ++-- src/lib/modules/catalog/db2/readme.md | 5 +- src/lib/modules/catalog/delta-lake/readme.md | 52 ++++++--- .../modules/catalog/elasticsearch/readme.md | 15 ++- src/lib/modules/catalog/hive/readme.md | 53 +++++++--- src/lib/modules/catalog/iceberg/readme.md | 41 ++++++- src/lib/modules/catalog/mariadb/readme.md | 27 ++--- src/lib/modules/catalog/mysql/readme.md | 22 ++-- src/lib/modules/catalog/pinot/readme.md | 12 +-- src/lib/modules/catalog/postgres/readme.md | 13 ++- src/lib/modules/catalog/sqlserver/readme.md | 12 ++- src/lib/modules/security/biac/readme.md | 100 ++++++------------ .../security/file-access-control/readme.md | 4 +- src/lib/modules/security/ldap/readme.md | 6 +- src/lib/modules/security/oauth2/readme.md | 6 +- .../modules/security/password-file/readme.md | 2 +- src/lib/modules/security/tls/readme.md | 4 +- 20 files changed, 255 insertions(+), 168 deletions(-) diff --git a/src/lib/modules/admin/cache-service/readme.md b/src/lib/modules/admin/cache-service/readme.md index 45c94980..5e5ff0d2 100644 --- a/src/lib/modules/admin/cache-service/readme.md +++ b/src/lib/modules/admin/cache-service/readme.md @@ -18,6 +18,10 @@ For troubleshooting, the bootstrap script enables debug logging for with the cache service. The JMX dump tables can be queried in the `jmx.history` schema. +## Usage + + minitrino --env STARBURST_VER= provision --module cache-service + ## Table Scan Redirections (TSRs) The `rules.json` file configures two tables for TSRs: `postgres.public.customer` @@ -29,3 +33,17 @@ cache service operations as they occur. An example MV is created in `hive_mv_tsr.mvs.example`. Any number of MVs can be added to this catalog, and MVs can pull data from any data source. + +## Editing the `hive_mv_tsr.properties` File + +This module uses a roundabout way to mount the `hive_mv_tsr.properties` file +that allows for edits to be made to the file inside the Trino container without +the source file being modified on the host. To edit the file, exec into the +Trino container, make the desired changes, and then restart the container for +the changes to take effect: + + docker exec -it trino bash + vi /etc/starburst/catalog/hive_mv_tsr.properties + exit + + docker restart trino diff --git a/src/lib/modules/admin/data-products/readme.md b/src/lib/modules/admin/data-products/readme.md index b1ecdb97..828b768c 100644 --- a/src/lib/modules/admin/data-products/readme.md +++ b/src/lib/modules/admin/data-products/readme.md @@ -1,6 +1,6 @@ # Data Products Module -A module which deploys the Starburst [data +A module which configures the [data products](https://docs.starburst.io/latest/data-products.html) feature. The `hive` and `insights` modules are dependencies of this module. @@ -11,3 +11,8 @@ The `hive` and `insights` modules are dependencies of this module. docker exec -it trino bash trino-cli trino> show schemas from backend_svc; + +For configuring data product domains, use this `s3a` path, which is from a +bucket auto-provisioned in the related MinIO container: + + s3a://sample-bucket/ diff --git a/src/lib/modules/admin/file-group-provider/readme.md b/src/lib/modules/admin/file-group-provider/readme.md index 85689310..8a833c29 100644 --- a/src/lib/modules/admin/file-group-provider/readme.md +++ b/src/lib/modules/admin/file-group-provider/readme.md @@ -5,13 +5,17 @@ provider](https://docs.starburst.io/latest/security/group-file.html). ## Usage + # View group definitions + docker exec trino sh -c 'cat /etc/starburst/groups.txt' + + # Get into the container and connect as a user tied to a group minitrino --env STARBURST_VER= provision --module file-group-provider docker exec -it trino bash trino-cli --user admin trino> show schemas from tpch; You will need to supply a username to the Trino CLI in order to map to a group -(see `lib/modules/security/file-access-control/resources/trino/group.txt` for +(see `lib/modules/security/file-access-control/resources/trino/groups.txt` for which users belong to which groups). Example: trino-cli --user admin # maps to group sepadmins diff --git a/src/lib/modules/admin/insights/readme.md b/src/lib/modules/admin/insights/readme.md index 7161662d..a1d4dcf0 100644 --- a/src/lib/modules/admin/insights/readme.md +++ b/src/lib/modules/admin/insights/readme.md @@ -4,12 +4,13 @@ This module configures and deploys the necessary components for [Insights](https://docs.starburst.io/latest/insights/configuration.html) features in the SEP web UI, including the required [backend service](https://docs.starburst.io/latest/admin/backend-service.html) database -which persists the data to provide information needed for Insights features. - -This module is a prerequisite for Built-in access control (BIAC). +which persists the data to provide information needed for the Insights UI. ## Usage +The backend service database can be queried directly, as it is exposed as a +catalog. For example: + minitrino --env STARBURST_VER= provision --module insights docker exec -it trino bash trino-cli @@ -17,11 +18,6 @@ This module is a prerequisite for Built-in access control (BIAC). ## Accessing Insights Web UI -Open a web browser and go to [https://localhost:8080](https://localhost:8080) -and log in with a user that is authorized to access insights. - -Note: `insights.authorized-*` properties cannot be used in conjunction with -SEP's built-in access control properties (`starburst.access-control`). If you -need to access Insights features in the UI without enabling BIAC, you will need -to uncomment the `insights.authorized-users=.*` property in the coordinator's -`/etc/starburst/config.properties` file. +Open a web browser, navigate to +[https://localhost:8080](https://localhost:8080), and log in with any user. The +Insights UI should be enabled. diff --git a/src/lib/modules/catalog/db2/readme.md b/src/lib/modules/catalog/db2/readme.md index 52508c57..4c7c3c1c 100644 --- a/src/lib/modules/catalog/db2/readme.md +++ b/src/lib/modules/catalog/db2/readme.md @@ -1,4 +1,7 @@ -# Db2 Connector Module +# Db2 Catalog Module + +**Note**: this module doesn't really work on newer Macs with M chips. I will +look into fixing that. This module provisions a standalone Db2 service. Note that the Db2 service can take a long time to start (10-20+ minutes), so ensure you are viewing the Db2 diff --git a/src/lib/modules/catalog/delta-lake/readme.md b/src/lib/modules/catalog/delta-lake/readme.md index 5f23ec87..b8393d75 100644 --- a/src/lib/modules/catalog/delta-lake/readme.md +++ b/src/lib/modules/catalog/delta-lake/readme.md @@ -1,14 +1,16 @@ -# Delta-Lake Module +# Delta Lake Catalog Module -This module uses Minio as a local S3 service. You can write data to this service -and the files will be written to your machine. You can read more about Minio -[here](https://docs.min.io/docs/minio-docker-quickstart-guide.html). This module -also uses a Hive metastore (HMS) container along with a Postgres container for -the HMS's backend storage. The HMS image is based off of naushadh's repository -[here](https://github.com/naushadh/hive-metastore) (refer to his repository for -additional documentation on the HMS image and configuration options). +This module deploys the necessary components for a Delta Lake environment. -You can access the Minio UI at `http://localhost:9002` with `access-key` and +- **Object storage**: served via MinIO (`minio-delta-lake` container and + bootstrapped by `create-minio-delta-lake-buckets`) +- **Metastore**: served via a Hive metastore (`metastore-delta-lake` container + backed by `postgres-delta-lake` for storage) + - The HMS image is based off of naushadh's repository + [here](https://github.com/naushadh/hive-metastore) (refer to his repository + for additional documentation on the HMS image and configuration options) + +The MinIO UI can be viewed at `http://localhost:9002` using `access-key` and `secret-key` for credentials. This module uses the Delta Lake connector. There is no Spark backend, so tables @@ -21,7 +23,7 @@ need to be created via `CREATE TABLE AS ...` queries from Trino. Example: AS SELECT * FROM tpch.tiny.customer; This will create the table `delta.default.customer` and a corresponding -`_delta_log` directory in the backing MinIO object storage. +`_delta_log` directory in MinIO object storage. ## Usage @@ -30,9 +32,9 @@ This will create the table `delta.default.customer` and a corresponding trino-cli trino> show schemas from delta; -## Cleanup +## Persistent Storage -This module uses named volumes to persist MinIO and HMS data: +This module uses named volumes to persist MinIO and metastore data: volumes: postgres-delta-lake-data: @@ -44,6 +46,32 @@ This module uses named volumes to persist MinIO and HMS data: - com.starburst.tests=minitrino - com.starburst.tests.module.delta-lake=catalog-delta-lake +The user-facing implication is that the data in the Hive metastore and the data +files stored in MinIO are retained even after shutting down and/or removing the +environment's containers. Minitrino issues a warning about this whenever a +module with named volumes is deployed––be sure to look out for these warnings: + + [w] Module '' has persistent volumes associated with it. To delete these volumes, remember to run `minitrino remove --volumes`. + To remove these volumes, run: minitrino -v remove --volumes --label com.starburst.tests.module.delta-lake=catalog-delta-lake + +Or, remove them directly using the Docker CLI: + + docker volume rm minitrino_postgres-delta-lake-data \ + minitrino_minio-delta-lake-data + +## Editing the `delta.properties` File + +This module uses a roundabout way to mount the `delta.properties` file that +allows for edits to be made to the file inside the Trino container without the +source file being modified on the host. To edit the file, exec into the Trino +container, make the desired changes, and then restart the container for the +changes to take effect: + + docker exec -it trino bash + vi /etc/starburst/catalog/delta.properties + exit + + docker restart trino diff --git a/src/lib/modules/catalog/elasticsearch/readme.md b/src/lib/modules/catalog/elasticsearch/readme.md index 6c275a6f..c6bad07d 100644 --- a/src/lib/modules/catalog/elasticsearch/readme.md +++ b/src/lib/modules/catalog/elasticsearch/readme.md @@ -1,11 +1,13 @@ -# Elasticsearch Connector Module +# Elasticsearch Catalog Module This module contains an ES container with some preloaded data. It contains: a -schema (ES mapping), a table (ES doc mapping), and data (ES docs). +schema (ES mapping), a table (ES doc mapping), and 500 rows of fake data (ES +docs). -## Loading your own data +## Loading Data -Since port 9200 is exposed on localhost you can add your own data like this: +Elasticsearch is exposed on `localhost:9200`, so additional data can be loaded +as follows: # Create user index curl -XPUT http://localhost:9200/user?pretty=true; @@ -41,6 +43,11 @@ Since port 9200 is exposed on localhost you can add your own data like this: } '; +If scripting fake data is preferable, reference the bootstrap script leveraged +by this module, located at: + + lib/modules/catalog/elasticsearch/resources/bootstrap/bootstrap-elasticsearch.sh + ## Usage minitrino --env STARBURST_VER= provision --module elasticsearch diff --git a/src/lib/modules/catalog/hive/readme.md b/src/lib/modules/catalog/hive/readme.md index ded6f952..5ed59010 100644 --- a/src/lib/modules/catalog/hive/readme.md +++ b/src/lib/modules/catalog/hive/readme.md @@ -1,17 +1,19 @@ -# Hive Module +# Hive Catalog Module -This module uses Minio as a local S3 service. You can write data to this service -and the files will be written to your machine. You can read more about Minio -[here](https://docs.min.io/docs/minio-docker-quickstart-guide.html). This module -also uses a Hive metastore (HMS) container along with a Postgres container for -the HMS's backend storage. The HMS image is based off of naushadh's repository -[here](https://github.com/naushadh/hive-metastore) (refer to his repository for -additional documentation on the HMS image and configuration options). +This module deploys the necessary components for a Delta Lake environment. -You can access the Minio UI at `http://localhost:9001` with `access-key` and +- **Object storage**: served via MinIO (`minio` container and bootstrapped by + `create-minio-buckets`) +- **Metastore**: served via a Hive metastore (`metastore-hive` container backed + by `postgres-hive` for storage) + - The HMS image is based off of naushadh's repository + [here](https://github.com/naushadh/hive-metastore) (refer to his repository + for additional documentation on the HMS image and configuration options) + +The MinIO UI can be viewed at `http://localhost:9001` using `access-key` and `secret-key` for credentials. -You can create a table with ORC data with Trino very quickly: +Tables backed by ORC data files can be easily created: trino> create schema hive.tiny with (location='s3a://sample-bucket/wh/tiny/'); CREATE SCHEMA @@ -19,7 +21,7 @@ You can create a table with ORC data with Trino very quickly: trino> create table hive.tiny.customer as select * from tpch.tiny.customer; CREATE TABLE: 1500 rows -You will see the ORC data stored in your local Minio bucket. +The ORC data files can be viewed directly in the MinIO bucket via the MinIO UI. ## Usage @@ -28,9 +30,9 @@ You will see the ORC data stored in your local Minio bucket. trino-cli trino> show schemas from hive; -## Cleanup +## Persistent Storage -This module uses named volumes to persist MinIO and HMS data: +This module uses named volumes to persist MinIO and metastore data: volumes: postgres-hive-data: @@ -42,6 +44,31 @@ This module uses named volumes to persist MinIO and HMS data: - com.starburst.tests=minitrino - com.starburst.tests.module.hive=catalog-hive +The user-facing implication is that the data in the Hive metastore and the data +files stored in MinIO are retained even after shutting down and/or removing the +environment's containers. Minitrino issues a warning about this whenever a +module with named volumes is deployed––be sure to look out for these warnings: + + [w] Module '' has persistent volumes associated with it. To delete these volumes, remember to run `minitrino remove --volumes`. + To remove these volumes, run: minitrino -v remove --volumes --label com.starburst.tests.module.hive=catalog-hive + +Or, remove them directly using the Docker CLI: + + docker volume rm minitrino_postgres-hive-data minitrino_minio-hive-data + +## Editing the `hive.properties` File + +This module uses a roundabout way to mount the `hive.properties` file that +allows for edits to be made to the file inside the Trino container without the +source file being modified on the host. To edit the file, exec into the Trino +container, make the desired changes, and then restart the container for the +changes to take effect: + + docker exec -it trino bash + vi /etc/starburst/catalog/hive.properties + exit + + docker restart trino diff --git a/src/lib/modules/catalog/iceberg/readme.md b/src/lib/modules/catalog/iceberg/readme.md index 34f8b34c..052b28ce 100644 --- a/src/lib/modules/catalog/iceberg/readme.md +++ b/src/lib/modules/catalog/iceberg/readme.md @@ -1,4 +1,4 @@ -# Iceberg Module +# Iceberg Catalog Module This module deploys infrastructure for an Iceberg catalog leveraging the Iceberg REST catalog. @@ -9,10 +9,18 @@ requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.h ## Usage minitrino --env STARBURST_VER= provision --module iceberg + docker exec -it trino bash + trino-cli + trino> show schemas from hive; -## Cleanup +Create a schema and a table: -This module uses a named volume to persist MinIO data: + create schema iceberg.test with (location = 's3a://sample-bucket/wh/test'); + create table iceberg.test.test_tbl as select * from tpch.tiny.customer; + +## Persistent Storage + +This module uses named volumes to persist MinIO data: volumes: minio-iceberg-data: @@ -20,6 +28,31 @@ This module uses a named volume to persist MinIO data: - com.starburst.tests=minitrino - com.starburst.tests.module.iceberg=catalog-iceberg -To remove this volume, run: +The user-facing implication is that the data files stored in MinIO are retained +even after shutting down and/or removing the environment's containers. Minitrino +issues a warning about this whenever a module with named volumes is deployed––be +sure to look out for these warnings: + + [w] Module '' has persistent volumes associated with it. To delete these volumes, remember to run `minitrino remove --volumes`. + +To remove these volumes, run: minitrino -v remove --volumes --label com.starburst.tests.module.iceberg=catalog-iceberg + +Or, remove them directly using the Docker CLI: + + docker volume rm minitrino_minio-iceberg-data + +## Editing the `iceberg.properties` File + +This module uses a roundabout way to mount the `iceberg.properties` file that +allows for edits to be made to the file inside the Trino container without the +source file being modified on the host. To edit the file, exec into the Trino +container, make the desired changes, and then restart the container for the +changes to take effect: + + docker exec -it trino bash + vi /etc/starburst/catalog/iceberg.properties + exit + + docker restart trino diff --git a/src/lib/modules/catalog/mariadb/readme.md b/src/lib/modules/catalog/mariadb/readme.md index 4f174653..37fe2aec 100644 --- a/src/lib/modules/catalog/mariadb/readme.md +++ b/src/lib/modules/catalog/mariadb/readme.md @@ -1,28 +1,23 @@ -# MariaDB Connector Module +# MariaDB Catalog Module This module provisions a standalone MariaDB service. By default, it is exposed to the internal Docker network only via: -```yaml -ports: - - :3306 -``` + ports: + - :3306 To expose it at the host level, add a port to the left of the colon, e.g.: -```yaml -ports: - - 3307:3306 -``` + ports: + - 3307:3306 This will allow you to connect to the service from any SQL client that supports -MariaDB drivers on `localhost:3307`. +MariaDB drivers on `localhost:3307`. Note that a unique port (`3307`) was used +here as the MySQL module already claims the host port `3306`. ## Usage -```sh -minitrino provision -m mariadb -docker exec -it trino bash -trino-cli -trino> show schemas from mariadb; -``` + minitrino --env STARBURST_VER= provision --module mariadb + docker exec -it trino bash + trino-cli + trino> show schemas from mariadb; diff --git a/src/lib/modules/catalog/mysql/readme.md b/src/lib/modules/catalog/mysql/readme.md index 1f97f35f..1400d39c 100644 --- a/src/lib/modules/catalog/mysql/readme.md +++ b/src/lib/modules/catalog/mysql/readme.md @@ -1,21 +1,17 @@ -# MySQL Connector Module +# MySQL Catalog Module This module provisions a standalone MySQL service. By default, it is exposed both to the internal Docker network and the host via: -```yaml -ports: - - 3306:3306 -``` + ports: + - 3306:3306 -This will allow you to connect to the service from any SQL client that supports -MySQL drivers on `localhost:3306`. +This will allows users to connect to the service from any SQL client that +supports MySQL drivers on `localhost:3306`. ## Usage -```sh -minitrino provision -m mysql -docker exec -it trino bash -trino-cli -trino> show schemas from mysql; -``` + minitrino --env STARBURST_VER= provision --module mysql + docker exec -it trino bash + trino-cli + trino> show schemas from mysql; diff --git a/src/lib/modules/catalog/pinot/readme.md b/src/lib/modules/catalog/pinot/readme.md index 2ad7996d..88aa75d1 100644 --- a/src/lib/modules/catalog/pinot/readme.md +++ b/src/lib/modules/catalog/pinot/readme.md @@ -1,4 +1,4 @@ -# Pinot Connector Module +# Pinot Catalog Module This module adds a Pinot catalog to Trino and provisions a Pinot cluster with all the main Pinot components: @@ -15,11 +15,9 @@ image. To deploy the module: -```sh -minitrino provision -m pinot -docker exec -it trino bash -trino-cli -trino> show schemas from pinot; -``` + minitrino --env STARBURST_VER= provision --module pinot + docker exec -it trino bash + trino-cli + trino> show schemas from pinot; The Pinot web UI can be viewed at `localhost:9090`. diff --git a/src/lib/modules/catalog/postgres/readme.md b/src/lib/modules/catalog/postgres/readme.md index d3ea8c18..b808e7c5 100644 --- a/src/lib/modules/catalog/postgres/readme.md +++ b/src/lib/modules/catalog/postgres/readme.md @@ -1,8 +1,13 @@ -# Postgres Connector Module +# Postgres Catalog Module -This module provisions a standalone Postgres service. It is named uniquely to -avoid conflicts with other modules that may use Trino as a backend, such as the -`hive-s3` module. +This module provisions a standalone Postgres service. By default, it is exposed +both to the internal Docker network and the host via: + + ports: + - 5432:5432 + +This will allows users to connect to the service from any SQL client that +supports Postgres drivers on `localhost:5432`. ## Usage diff --git a/src/lib/modules/catalog/sqlserver/readme.md b/src/lib/modules/catalog/sqlserver/readme.md index cdd757fa..06202eb9 100644 --- a/src/lib/modules/catalog/sqlserver/readme.md +++ b/src/lib/modules/catalog/sqlserver/readme.md @@ -1,11 +1,13 @@ -# SQL Server Connector Module +# SQL Server Catalog Module -This module provisions a standalone SQL Server service. +This module provisions a standalone SQL Server service. By default, it is +exposed both to the internal Docker network and the host via: -Default database created is `master`. + ports: + - 1433:1433 -Note that the 2017 version of SQL Server is used by default, as previous -versions were only available on Windows and do not have Docker containers. +This will allows users to connect to the service from any SQL client that +supports SQL Server drivers on `localhost:1433`. ## Usage diff --git a/src/lib/modules/security/biac/readme.md b/src/lib/modules/security/biac/readme.md index 39b3fed0..018ead7a 100644 --- a/src/lib/modules/security/biac/readme.md +++ b/src/lib/modules/security/biac/readme.md @@ -1,82 +1,53 @@ # Built-in Access Control (BIAC) Module This module configures Trino to enable the built-in access control (BIAC) system -integrated with the SEP web UI. - -This module can be used in conjunction with the `password-file` and `ldap` -security modules to provide usernames. +integrated with the SEP web UI. ## Usage minitrino --env STARBURST_VER= provision --module biac -### Usage with Delta Lake or Hive modules - -Additional configuration is required for use of BIAC with the `Delta Lake` and -`Hive` object storage catalogs. - -**Delta Lake**: Add the following property to `delta.properties`: - - delta.security=starburst - -**Hive**: Add the following property to `hive.properties`: - - hive.security=starburst - ## Accessing Roles and Privileges in the SEP UI Standalone BIAC: + - Open a web browser and go to [http://localhost:8080](http://localhost:8080) -- Sign in using a username for an authorized user (Default: `admin`, - `starburst_service`) -- Click on your username in the top right corner > switch role > `sysadmin` - -BIAC with `password-file` or `ldap` module: -- Open a web browser and go to [https://localhost:8443](https://localhost:8443) -- Have the browser accept the self-signed certificate: - - **Chrome**: Click anywhere on the page and type `thisisunsafe` - - **Firefox**: Click on the Advanced button and then click on **Accept the - Risk and Continue**. - - **Safari**: Click on the button **Show Details** and then click the link - **visit this website**. -- Sign in using a username/password for an authorized user (`admin / - trinoRocks15`) -- Click on your username in the top right corner > switch role > `sysadmin` - -## Using the SEP REST API with BIAC + (or [https://localhost:8443](hhttps://localhost:8443) if TLS is configured) +- Log in using an authorized sysadmin user (`admin` or `starburst_service`) +- Click on the username in the top right corner > switch role > `sysadmin` + +Once the `sysadmin` role has been assumed, you can begin to create roles and +grant various privileges. + +## Using the SEP REST API with BIAC You can manage BIAC entities and their actions via the SEP REST API (BIAC endpoints are of the form `/api/v1/biac/...`). See the list of available endpoints and methods in our [API Documentation](https://docs.starburst.io/latest/api/index.html#api-_). -Note: The SEP REST API can only be used for clusters secured with `PASSWORD` -authentication. To test using the BIAC REST API endpoints, ensure the BIAC -module has been provisioned in conjunction with the `password-file` or `ldap` -module. - ### Example 1: List Roles curl -k --location \ - -X GET 'https://localhost:8443/api/v1/biac/roles' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'X-Trino-Role: system=ROLE{sysadmin}' \ - -u 'admin:trinoRocks15' + -X GET 'http://localhost:8080/api/v1/biac/roles' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'X-Trino-Role: system=ROLE{sysadmin}' \ + -u 'admin:' -### Example 2: Adding a user to authorized users +### Example 2: Adding a User to Authorized Users The following API POST request adds user `Alice` to authorized users. After performing the following successfully, Alice will be able to access BIAC -features in the SEP UI. +features in the SEP UI. curl -k --location \ - -X POST 'https://localhost:8443/api/v1/biac/subjects/users/alice/assignments' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'X-Trino-Role: system=ROLE{sysadmin}' \ - -u 'admin:trinoRocks15' \ - -d '{ "roleId":"-2", "roleAdmin":"true"}' + -X POST 'http://localhost:8080/api/v1/biac/subjects/users/alice/assignments' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'X-Trino-Role: system=ROLE{sysadmin}' \ + -u 'admin:' \ + -d '{ "roleId":"-2", "roleAdmin":"true"}' ### Example 3: Get Role Assignments for a Role @@ -84,19 +55,18 @@ The following API GET request returns users/groups assigned to the `sysadmin` role which is defined by `roleId=-1`. curl -k --location \ - -X GET 'https://localhost:8443/api/v1/biac/roles/-2/assignments?pageToken=&pageSize=&pageSort=' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'X-Trino-Role: system=ROLE{sysadmin}' \ - -u 'admin:trinoRocks15' - + -X GET 'http://localhost:8080/api/v1/biac/roles/-2/assignments?pageToken=&pageSize=&pageSort=' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'X-Trino-Role: system=ROLE{sysadmin}' \ + -u 'admin:' -### Example 4: Create Role +### Example 4: Create a Role curl -k --location \ - -X POST 'https://localhost:8443/api/v1/biac/roles' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'X-Trino-Role: system=ROLE{sysadmin}' \ - -u 'admin:trinoRocks15' \ - -d '{ "name": "testRole", "description":"test creating new BIAC role"}' + -X POST 'http://localhost:8080/api/v1/biac/roles' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'X-Trino-Role: system=ROLE{sysadmin}' \ + -u 'admin:' \ + -d '{ "name": "test_role", "description":"test creating new BIAC role"}' diff --git a/src/lib/modules/security/file-access-control/readme.md b/src/lib/modules/security/file-access-control/readme.md index 0434d019..90fc5c6f 100644 --- a/src/lib/modules/security/file-access-control/readme.md +++ b/src/lib/modules/security/file-access-control/readme.md @@ -2,13 +2,13 @@ A module which utilizes Trino's [file-based system access control plugin](https://docs.starburst.io/latest/security/file-system-access-control.html). -This also makes used of the [file-based group +This module also makes used of the [file-based group provider](https://docs.starburst.io/latest/security/group-file.html). ## Policies The access policy is located in the `rules.json` file which defines groups of -users that map to a certain access control permission. The users for the groups +users that map to certain access control permissions. The users for the groups are defined in the `groups.txt` file. - Users in the `sepadmins` group have full access to all objects within Trino diff --git a/src/lib/modules/security/ldap/readme.md b/src/lib/modules/security/ldap/readme.md index 2ed86d7a..cf475041 100644 --- a/src/lib/modules/security/ldap/readme.md +++ b/src/lib/modules/security/ldap/readme.md @@ -1,4 +1,4 @@ -# LDAP Module +# LDAP Password Authenticator Module This module provisions an LDAP server for authenticating users in Trino. @@ -19,7 +19,7 @@ This module provisions an LDAP server for authenticating users in Trino. - alice / trinoRocks15 - bob / trinoRocks15 -## Adding a New User to LDAP +## Add a New User to LDAP 1. Open a shell to the LDAP container @@ -41,7 +41,7 @@ This module provisions an LDAP server for authenticating users in Trino. userPassword: trinoRocks15 EOF -3. Use the **ldapmodify** tool to add the new user +3. Use the `ldapmodify` tool to add the new user ldapmodify -x -D "cn=admin,dc=example,dc=com" \ -w trinoRocks15 -H ldaps://ldap:636 -f jeff.ldif diff --git a/src/lib/modules/security/oauth2/readme.md b/src/lib/modules/security/oauth2/readme.md index 76cda65c..370ce004 100644 --- a/src/lib/modules/security/oauth2/readme.md +++ b/src/lib/modules/security/oauth2/readme.md @@ -1,8 +1,8 @@ -# OAuth2 Module +# OAuth2 Authenticator Module This module secures Trino with OAuth2 authentication. -## Usage +## Prerequisites Prior to deploying this module, you must authenticate to the Github container registry @@ -17,7 +17,7 @@ The `hosts` file modification allows for all Docker services to be exposed on your host at `host.docker.internal:${PORT}`. This is a requirement given the nature of the redirects and callbacks that occur during the OAuth2 flow. -To provision this module, run: +## Usage minitrino --env STARBURST_VER= provision --module oauth2 diff --git a/src/lib/modules/security/password-file/readme.md b/src/lib/modules/security/password-file/readme.md index c15d853c..86c1dbb1 100644 --- a/src/lib/modules/security/password-file/readme.md +++ b/src/lib/modules/security/password-file/readme.md @@ -1,4 +1,4 @@ -# Password File Authentication Module +# Password File Authenticator Module This module configures Trino to authenticate users with a password file. diff --git a/src/lib/modules/security/tls/readme.md b/src/lib/modules/security/tls/readme.md index 1e768ecd..4d72a638 100644 --- a/src/lib/modules/security/tls/readme.md +++ b/src/lib/modules/security/tls/readme.md @@ -1,6 +1,6 @@ -# Password File Authentication Module +# TLS Module -This module configures server TLS for the Trino container using a self-signed +This module configures server TLS on the Trino container using a self-signed certificate. ## Client Keystore and Truststore