Docs for roles/role_cfg #4221

andreyaksenov · 2024-05-23T08:28:19Z

Docs for roles.

Created several samples for demonstrating built-in and custom roles:
- Updated the sharded_cluster_crud sample to using built-in CRUD roles.
- Added a hello world role without config.
- Added a hello world role with config.
- Added a sample that demonstrates how to create an HTTP API role.
Updated the main Configuration topic:
- Replaced a section about app with roles: Enabling and configuring roles
- Added a note about option precedence for different scopes: Configuration scopes
- Updated the TT_APP_CFG example to TT_ROLES_CFG: Environment variables | Map
- Removed the Configuration options overview section. Existing topics already cover this info.
Created a new Application roles topic inside Developing applications with Tarantool.
Config reference:
- roles/roles_cfg options: roles
- app options: app

doc/reference/configuration/configuration_reference.rst

Totktonada

Thank you for the decent work!

p7nov

Great addition, I finally understood what are these application roles :)

One general question: should we maybe provide more cross-links to doc pages where built-in roles and module roles are explained or used? I mean, you say there are built-in roles, and the reader wonders What built-in roles? Is there a list? How to use them?

p7nov · 2024-06-10T04:54:39Z

doc/concepts/configuration.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An application role is a Lua module that implements specific functions or logic.
+You can enable or turn off a particular role for certain instances in a configuration without restarting these instances.


"enable or turn off" sounds inconsistent. Let's use one word for the two states (enable/disable or turn on/off)

p7nov · 2024-06-10T05:00:09Z

doc/concepts/configuration.rst

-Loading an application
-**********************
+This section describes how to enable and configure roles.
+To learn how to develop custom roles, see :ref:`application_roles`.


You write about custom roles, but there there is no explanation of non custom roles. Maybe add a sentence about them to the first paragraph?

Good point, updated the intro of this section to tell a bit about different types of roles.

p7nov · 2024-06-10T05:02:59Z

doc/concepts/configuration.rst

+As the most of configuration options, roles and their configurations can be defined at :ref:`different levels <configuration_scopes>`.
+Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, there are some specifics of applying the configuration:
+
+-   For ``roles``, an instance's role takes precedence over roles defined at another level.


Suggested change

- For ``roles``, an instance's role takes precedence over roles defined at another level.

- For ``roles``, an instance's role overwrites all roles defined at another levels.

Nit: overwrites seems a more straightforward verb to explain that other roles are discarded.

p7nov · 2024-06-10T05:06:58Z

doc/how-to/app/app_roles.rst

+
+Roles can be divided into the following groups:
+
+-   Roles provided by Tarantool.


Suggested change

- Roles provided by Tarantool.

- Tarantool's built-in roles.

Nit: this sounds more natural to me (if this wording is correct in our terminology).

p7nov · 2024-06-10T05:12:06Z

doc/how-to/app/app_roles.rst

+    -   A role is a container for privileges that can be granted to users. Learn more in :ref:`access_control_concepts_roles`.
+    -   A role of a replica set in regard to sharding. Learn more in :ref:`vshard_config_sharding_roles`.


Suggested change

- A role is a container for privileges that can be granted to users. Learn more in :ref:`access_control_concepts_roles`.

- A role of a replica set in regard to sharding. Learn more in :ref:`vshard_config_sharding_roles`.

- A user role is a container for privileges that can be granted to users. Learn more in :ref:`access_control_concepts_roles`.

- A sharding role of a replica set in regard to sharding. Learn more in :ref:`vshard_config_sharding_roles`.

Just an idea, to decrease readers' confusion a bit

A user role

Sounds better but a role can also has a role :) So, it's better to keep it as is.

A sharding role of a replica set in regard to sharding.

sharding meets two times in this case and add some confusion.

p7nov · 2024-06-10T05:17:21Z

doc/how-to/app/app_roles.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To validate a role's configuration, you need to define the :ref:`validate([cfg]) <roles_api_reference_validate>` function.
+The ``cfg`` argument allows you to get access to the provided :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.


Suggested change

The ``cfg`` argument allows you to get access to the provided :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.

The ``cfg`` argument provides access to the :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.

Seems shorter and easier to read

p7nov · 2024-06-10T05:19:33Z

doc/how-to/app/app_roles.rst

+
+.. _roles_create_space:
+
+Specifics of creating spaces


Suggested change

Specifics of creating spaces

Creating spaces in roles

This applies to creating spaces for applications in general. So, I'm going to move this section outside this topic at some moment.

p7nov · 2024-06-10T05:22:30Z

doc/how-to/app/app_roles.rst

+
+..  _roles_life_cycle_stopping_roles:
+
+2)  *Stopping roles*


Maybe Spotting removed roles or smth like that? the current wording surprised me and took some time to understand which roles we're talking about

p7nov · 2024-06-10T05:24:28Z

doc/how-to/app/app_roles.rst

+For roles that :ref:`depend <roles_create_custom_role_dependencies>` on each other, their ``validate()``,  ``apply()``, and ``stop()`` functions are executed taking into account the dependencies.
+Suppose, there are two independent roles (``role1``, ``role2``) and three roles that depend on each other as follows:
+
+..  code-block:: none


Maybe add a verbal explanation? It's unclear to me now.

p7nov · 2024-06-10T05:27:57Z

doc/how-to/app/app_roles.rst

+
+..  data:: dependencies
+
+    (Optional) Define a role's dependencies.


Suggested change

(Optional) Define a role's dependencies.

(Optional) Role's dependencies.

Nit: IMO, verbs are not needed in option/parameter/variable descriptions in references.

andreyaksenov · 2024-06-10T08:38:19Z

One general question: should we maybe provide more cross-links to doc pages where built-in roles and module roles are explained or used? I mean, you say there are built-in roles, and the reader wonders What built-in roles? Is there a list? How to use them?

It's a good idea. AFAIK, Tarantool provides only one role for now. For roles provided by external modules, this question goes beyond roles. Currently, I know two external modules that provide its own roles: CRUD and expirationd (and the docs gives a link to CRUD as an example). At the same time, any information for these modules are missing in our docs. I'll create an issue to think how to deal with this.

This was linked to issues May 23, 2024

Roles #3702

Closed

Update CRUD sample to using built-in roles #4152

Closed

andreyaksenov force-pushed the roles-samples branch 2 times, most recently from 1ea3af2 to 1609842 Compare May 27, 2024 08:10

andreyaksenov changed the title ~~Roles samples~~ MVP docs for roles/role_cfg May 27, 2024

andreyaksenov force-pushed the roles-samples branch 2 times, most recently from b9c3af8 to 12b4c1c Compare May 27, 2024 10:00

andreyaksenov linked an issue May 27, 2024 that may be closed by this pull request

dependencies for roles #3883

Closed

andreyaksenov force-pushed the roles-samples branch 3 times, most recently from 0bcfb08 to 8564127 Compare May 27, 2024 10:30

andreyaksenov marked this pull request as ready for review May 27, 2024 10:31

andreyaksenov force-pushed the roles-samples branch 2 times, most recently from c8cd763 to 6359787 Compare May 27, 2024 12:05

andreyaksenov requested a review from ImeevMA May 27, 2024 12:08

andreyaksenov force-pushed the roles-samples branch from 6359787 to 349a2e8 Compare May 27, 2024 12:39

ImeevMA approved these changes May 27, 2024

View reviewed changes