Skip to content

Commit 1f7a33a

Browse files
andreyaksenovandreyaksenov
authored
Configuration: document the 'credentials' option (#4035)
1 parent 47b9380 commit 1f7a33a

File tree

20 files changed

+615
-119
lines changed

20 files changed

+615
-119
lines changed

‎doc/book/admin/access_control.rst

Lines changed: 61 additions & 61 deletions
Large diffs are not rendered by default.

‎doc/code_snippets/snippets/config/instances.enabled/credentials/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Credentials
2+
3+
A sample application demonstrating how configure user credentials in a YAML configuration.
4+
5+
## Running
6+
7+
Start the application by executing the following command in the [config](../../../config) directory:
8+
9+
```console
10+
$ tt start credentials
11+
```

‎doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
credentials:
2+
users:
3+
dbadmin:
4+
password: 'T0p_Secret_P@$$w0rd'
5+
roles: [ super ]
6+
sampleuser:
7+
password: '123456'
8+
roles: [ writers_space_reader ]
9+
privileges:
10+
- permissions: [ read, write ]
11+
spaces: [ books ]
12+
roles:
13+
writers_space_reader:
14+
privileges:
15+
- permissions: [ read ]
16+
spaces: [ writers ]
17+
18+
groups:
19+
group001:
20+
replicasets:
21+
replicaset001:
22+
instances:
23+
instance001:
24+
iproto:
25+
listen:
26+
- uri: '127.0.0.1:3301'
27+
28+
# Load sample data
29+
app:
30+
file: 'myapp.lua'

‎doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
instance001:

‎doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
function create_spaces()
2+
box.schema.space.create('writers')
3+
box.space.writers:format({
4+
{ name = 'id', type = 'unsigned' },
5+
{ name = 'name', type = 'string' }
6+
})
7+
box.space.writers:create_index('primary', { parts = { 'id' } })
8+
9+
box.schema.space.create('books')
10+
box.space.books:format({
11+
{ name = 'id', type = 'unsigned' },
12+
{ name = 'title', type = 'string' },
13+
{ name = 'author_id', foreign_key = { space = 'writers', field = 'id' } },
14+
})
15+
box.space.books:create_index('primary', { parts = { 'id' } })
16+
end
17+
18+
function load_data()
19+
box.space.writers:insert { 1, 'Leo Tolstoy' }
20+
box.space.writers:insert { 2, 'Fyodor Dostoevsky' }
21+
box.space.writers:insert { 3, 'Alexander Pushkin' }
22+
23+
box.space.books:insert { 1, 'War and Peace', 1 }
24+
box.space.books:insert { 2, 'Anna Karenina', 1 }
25+
box.space.books:insert { 3, 'Resurrection', 1 }
26+
box.space.books:insert { 4, 'Crime and Punishment', 2 }
27+
box.space.books:insert { 5, 'The Idiot', 2 }
28+
box.space.books:insert { 6, 'The Brothers Karamazov', 2 }
29+
box.space.books:insert { 7, 'Eugene Onegin', 3 }
30+
box.space.books:insert { 8, 'The Captain\'s Daughter', 3 }
31+
box.space.books:insert { 9, 'Boris Godunov', 3 }
32+
box.space.books:insert { 10, 'Ruslan and Ludmila', 3 }
33+
end
34+
35+
create_spaces()
36+
load_data()

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Credentials: environment variables
2+
3+
A sample application demonstrating how set passwords in a YAML configuration using environment variables.
4+
5+
## Running
6+
7+
Before starting instances, set the `DBADMIN_PASSWORD` and `SAMPLEUSER_PASSWORD` environment variables, for example:
8+
9+
```console
10+
$ export DBADMIN_PASSWORD='T0p_Secret_P@$$w0rd'
11+
$ export SAMPLEUSER_PASSWORD='123456'
12+
```
13+
14+
Then, start the application by executing the following command in the [config](../../../config) directory:
15+
16+
```console
17+
$ tt start credentials_context_env
18+
```

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
config:
2+
context:
3+
dbadmin_password:
4+
from: env
5+
env: DBADMIN_PASSWORD
6+
sampleuser_password:
7+
from: env
8+
env: SAMPLEUSER_PASSWORD
9+
10+
credentials:
11+
users:
12+
dbadmin:
13+
password: '{{ context.dbadmin_password }}'
14+
sampleuser:
15+
password: '{{ context.sampleuser_password }}'
16+
17+
groups:
18+
group001:
19+
replicasets:
20+
replicaset001:
21+
instances:
22+
instance001:
23+
iproto:
24+
listen:
25+
- uri: '127.0.0.1:3301'

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
instance001:

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Credentials: files
2+
3+
A sample application demonstrating how load passwords to a YAML configuration from files.
4+
5+
## Running
6+
7+
Start the application by executing the following command in the [config](../../../config) directory:
8+
9+
```console
10+
$ tt start credentials_context_file
11+
```

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
config:
2+
context:
3+
dbadmin_password:
4+
from: file
5+
file: secrets/dbadmin_password.txt
6+
rstrip: true
7+
sampleuser_password:
8+
from: file
9+
file: secrets/sampleuser_password.txt
10+
rstrip: true
11+
12+
credentials:
13+
users:
14+
dbadmin:
15+
password: '{{ context.dbadmin_password }}'
16+
sampleuser:
17+
password: '{{ context.sampleuser_password }}'
18+
19+
groups:
20+
group001:
21+
replicasets:
22+
replicaset001:
23+
instances:
24+
instance001:
25+
iproto:
26+
listen:
27+
- uri: '127.0.0.1:3301'

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
instance001:

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
T0p_Secret_P@$$w0rd

‎doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
123456

‎doc/concepts/configuration.rst

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -395,18 +395,15 @@ Access control
395395
~~~~~~~~~~~~~~
396396

397397
The ``credentials`` section allows you to create users and grant them the specified privileges.
398-
In the example below, there are two users:
398+
In the example below, a ``dbadmin`` user with the specified password is created:
399399

400-
* The *replicator* user is used for replication and has a corresponding role.
401-
* The *storage* user has the ``sharding`` role.
402-
403-
.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml
400+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
404401
:language: yaml
405402
:start-at: credentials:
406-
:end-at: roles: [sharding]
403+
:end-at: T0p_Secret
407404
:dedent:
408405

409-
To learn more, see the :ref:`Access control <authentication>` section.
406+
To learn more, see the :ref:`configuration_credentials` section.
410407

411408

412409
.. _configuration_options_memory:
@@ -451,5 +448,6 @@ To learn more about the persistence mechanism in Tarantool, see the :ref:`Persis
451448
configuration/configuration_etcd
452449
configuration/configuration_code
453450
configuration/configuration_connections
451+
configuration/configuration_credentials
454452
configuration/configuration_authentication
455453
.. configuration/configuration_migrating

‎doc/concepts/configuration/configuration_credentials.rst

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
.. _configuration_credentials:
2+
3+
Credentials
4+
===========
5+
6+
Tarantool enables flexible management of access to various database resources by providing specific privileges to users.
7+
You can read more about the main concepts of Tarantool access control system in the :ref:`authentication` section.
8+
9+
This topic describes how to create users and grant them the specified privileges in the :ref:`credentials <configuration_reference_credentials>` section of a YAML configuration.
10+
For example, you can define users with the ``replication`` and ``sharding`` roles to maintain :ref:`replication <replication-master_replica_configuring_credentials>` and sharding in a Tarantool cluster.
11+
12+
13+
.. _configuration_credentials_managing_users_roles:
14+
15+
Managing users and roles
16+
------------------------
17+
18+
.. _configuration_credentials_managing_users_roles_creating_user:
19+
20+
Creating a user
21+
~~~~~~~~~~~~~~~
22+
23+
You can create new or configure credentials of the existing users in the :ref:`credentials.users <configuration_reference_credentials_users>` section.
24+
25+
In the example below, a ``dbadmin`` user without a password is created:
26+
27+
.. code-block:: yaml
28+
29+
credentials:
30+
users:
31+
dbadmin: {}
32+
33+
To set a password, use the :ref:`credentials.users.\<username\>.password <configuration_reference_credentials_users_name_password>` option:
34+
35+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
36+
:language: yaml
37+
:start-at: credentials:
38+
:end-at: T0p_Secret
39+
:dedent:
40+
41+
.. _configuration_credentials_managing_users_roles_granting_privileges:
42+
43+
Granting privileges to a user
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
To assign a role to a user, use the :ref:`credentials.users.\<username\>.roles <configuration_reference_credentials_users_name_roles>` option.
47+
In this example, the ``dbadmin`` user gets privileges granted to the ``super`` built-in role:
48+
49+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
50+
:language: yaml
51+
:start-at: credentials:
52+
:end-at: [ super ]
53+
:dedent:
54+
55+
To create a new role, define it in the :ref:`credentials.roles.* <configuration_reference_credentials_roles_options>` section.
56+
In the example below, the ``writers_space_reader`` role gets privileges to select data in the ``writers`` space:
57+
58+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
59+
:language: yaml
60+
:start-after: spaces: [ books ]
61+
:end-at: spaces: [ writers ]
62+
:dedent:
63+
64+
Then, you can assign this role to a user using :ref:`credentials.users.\<username\>.roles <configuration_reference_credentials_users_name_roles>` (``sampleuser`` in the example below):
65+
66+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
67+
:language: yaml
68+
:start-at: sampleuser:
69+
:end-at: [ writers_space_reader ]
70+
:dedent:
71+
72+
You can grant specific privileges directly using :ref:`credentials.users.\<username\>.privileges <configuration_reference_credentials_users_name_privileges>`.
73+
In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space:
74+
75+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml
76+
:language: yaml
77+
:start-at: sampleuser:
78+
:end-at: [ books ]
79+
:dedent:
80+
81+
You can find the full example here: `credentials <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/credentials>`_.
82+
83+
84+
85+
.. _configuration_credentials_loading_secrets:
86+
87+
Loading secrets from safe storage
88+
---------------------------------
89+
90+
Tarantool enables you to load secrets from safe storage such as external files or environment variables.
91+
To do this, you need to define corresponding options in the :ref:`config.context <configuration_reference_config_context_options>` section.
92+
In the examples below, ``context.dbadmin_password`` and ``context.sampleuser_password`` define how to load user passwords from ``*.txt`` files or environment variables:
93+
94+
* This example shows how to load passwords from ``*.txt`` files:
95+
96+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml
97+
:language: yaml
98+
:start-at: config:
99+
:end-before: credentials:
100+
:dedent:
101+
102+
* This example shows how to load passwords from environment variables:
103+
104+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml
105+
:language: yaml
106+
:start-at: config:
107+
:end-before: credentials:
108+
:dedent:
109+
110+
These environment variables should be set before :ref:`starting instances <configuration_run_instance>`.
111+
112+
After configuring how to load passwords, you can set password values using :ref:`credentials.users.\<username\>.password <configuration_reference_credentials_users_name_password>` as follows:
113+
114+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml
115+
:language: yaml
116+
:start-at: credentials:
117+
:end-at: context.sampleuser_password
118+
:dedent:
119+
120+
You can find the full examples here: `credentials_context_file <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file>`_, `credentials_context_env <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env>`_.

0 commit comments

Comments
 (0)