alexvanin/frostfs-s3-gw
1
0
Fork 0
forked from TrueCloudLab/frostfs-s3-gw
Code Issues Pull requests Projects Releases Packages Wiki Activity

[#396] Update docs

Browse source 
Signed-off-by: Angira Kekteeva <kira@nspcc.ru>
This commit is contained in:
Angira Kekteeva 2022-04-06 18:31:32 +04:00 committed by Alex Vanin
parent 3c5c2f20d8
commit 6a89ebb257
2 changed files with 207 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

188
docs/authmate.md
View file

@ -18,22 +18,18 @@ token, the object needs to be stored in a container available for the gateway
to read, and it needs to be encrypted with this gateway's key (among others to read, and it needs to be encrypted with this gateway's key (among others
potentially). potentially).
## Variables 1. [Generation of wallet](#Generation of wallet)
Authmate supports the following variables to decrypt wallets provided by `--wallet` and `--gate-wallet` 2. [Issuance of a secret](#Issuance of a secret)
parameters respectevely: 1. [CLI parameters](#CLI parameters)
* `AUTHMATE_WALLET_PASSPHRASE` 2. [Bearer tokens](#Bearer tokens)
* `AUTHMATE_WALLET_GATE_PASSPHRASE` 3. [Session tokens](#Session tokens)
4. [Containers policy](#Containers policy)
If the passphrase is not specified, you will be asked to enter the password interactively: 3. [Obtainment of a secret](#Obtainment of a secret access key)
```
Enter password for wallet.json >
```
## Generation of wallet ## Generation of wallet
To generate wallets for gateways, run the following command: To generate a wallet for a gateway, run the following command:
``` ```shell
$ ./neo-go wallet init -a -w wallet.json $ ./neo-go wallet init -a -w wallet.json
Enter the name of the account > AccountTestName Enter the name of the account > AccountTestName
@ -74,8 +70,8 @@ Confirm passphrase >
wallet successfully created, file location is wallet.json wallet successfully created, file location is wallet.json
``` ```
To get public key from wallet run: To get public key from the wallet:
``` ```shell
$ ./bin/neo-go wallet dump-keys -w wallet.json $ ./bin/neo-go wallet dump-keys -w wallet.json
NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract): NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract):
@ -84,32 +80,93 @@ NhLQpDnerpviUWDF77j5qyjFgavCmasJ4p (simple signature contract):
## Issuance of a secret ## Issuance of a secret
To issue a secret means to create a Bearer and (optionally) Session tokens and To issue a secret means to create a Bearer and, optionally, Session tokens and
put them as an object into a container on the NeoFS network. put them as an object into a container on the NeoFS network.
By default, the tool creates a container with a name the same as container ID in NeoFS and ACL ### CLI parameters
0x3c8c8cce (all operations are forbidden for `OTHERS` and `BEARER` user groups,
except for `GET`).
Also, you can put the tokens into an existing container via `--container-id` **Required parameters:**
parameter, but this way is **not recommended**. * `--wallet` - a path to a wallet `.json` file. You can provide a passphrase to decrypt
a wallet via environment variable `AUTHMATE_WALLET_PASSPHRASE`, or you will be asked to enter a passphrase
interactively. You can also specify an account address to use from a wallet using the `--address` parameter.
* `--peer` - address of a NeoFS peer to connect to
* `--gate-public-key` -- public `secp256r1` 33-byte short key of a gate (use flags repeatedly for multiple gates). The tokens are encrypted
by a set of gateway keys, so you need to pass them as well.
The tokens are encrypted by a set of gateway keys, so you need to pass them as well. You can issue a secret using the parameters above only. The tool will
1. create a new container
Creation of the bearer token is mandatory, while creation of the session token is 1. without a friendly name
optional. 2. with ACL `0x3c8c8cce` - all operations are forbidden for `OTHERS` and `BEARER` user groups, except for `GET`
3. with policy `REP 2 IN X CBF 3 SELECT 2 FROM * AS X`
Rules for bearer token can be set via param `bearer-rules` (json-string and file path allowed), if it is not set, 2. put bearer and session tokens with default rules (details in [Bearer tokens](#Bearer tokens) and
it will be auto-generated with values: [Session tokens](#Session tokens))
E.g.:
```shell
$ neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf\
--gate-public-key 0317585fa8274f7afdf1fc5f2a2e7bece549d5175c4e5182e37924f30229aef967
Enter password for wallet.json >
{
"access_key_id": "5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM",
"secret_access_key": "438bbd8243060e1e1c9dd4821756914a6e872ce29bf203b68f81b140ac91231c",
"owner_private_key": "274fdd6e71fc6a6b8fe77bec500254115d66d6d17347d7db0880d2eb80afc72a",
"container_id":"5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT"
}
``` ```
`access_key_id` and `secret_access_key` are AWS credentials that you can use with any S3 client.
`access_key_id` consists of Base58 encoded containerID(cid) and objectID(oid) stored on the NeoFS network and containing
the secret. Format of `access_key_id`: `%cid0%oid`, where 0(zero) is a delimiter.
**Optional parameters:**
* `--container-id` - you can put the tokens into an existing container, but this way is ***not recommended***.
* `--container-friendly-name` -- name of a container with tokens, by default container will not have a friendly name
* `--container-placement-policy` - placement policy of auth container to put the secret into. Default value is
`REP 2 IN X CBF 3 SELECT 2 FROM * AS X`
* `--lifetime`-- lifetime of tokens. For example 50h30m (note: max time unit is an hour so to set a day you should use
24h). Default value is `720h` (30 days). It will be ceil rounded to the nearest amount of epoch
* `--aws-cli-credentials` - path to the aws cli credentials file, where authmate will write `access_key_id` and
`secret_access_key` to
### Bearer tokens
Creation of the bearer tokens is mandatory.
Rules for bearer token can be set via parameter `--bearer-rules` (json-string and file path allowed):
```shell
$ neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--bearer-rules bearer-rules.json
```
where content of `bearer-rules.json`:
```json
{
"records": [
{"operation": "PUT", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GET", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "HEAD", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "DELETE", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "SEARCH", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GETRANGE", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]},
{"operation": "GETRANGEHASH", "action": "ALLOW", "filters": [], "targets": [{"role": "OTHERS", "keys": []}]}
]
}
```
If bearer rules are not set, a token will be auto-generated with a value:
```json
{ {
"version": { "version": {
"major": 2, "major": 2,
"minor": 6 "minor": 11
}, },
"containerID": { "containerID": {
"value": "%CID" "value": null
}, },
"records": [ "records": [
{ {
@ -127,16 +184,18 @@ it will be auto-generated with values:
} }
``` ```
With session token, there is 3 options: ### Session tokens
* append `--session-token` parameter with your custom rules in json format (as a string or file path, see an example below)
**NB!** To create buckets in NeoFS it's necessary to have session tokens with `PUT` and `SETEACL` permissions, that's why With session token, there are 3 options:
the authmate creates a `SETEACL` session token automatically in case when a user specified the token rule with `PUT` and 1. append `--session-token` parameter with your custom rules in json format (as a string or file path). E.g.:
forgot about the rule with `SETEACL`. ```shell
$ neofs-authmate issue-secret --wallet wallet.json \
* append `--session-token` parameter with the value `none` -- no session token will be created --peer 192.168.130.71:8080 \
* skip the parameter and `authmate` will create and put session tokens with default rules: --gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--session-token session.json
``` ```
where content of `session.json`:
```json
[ [
{ {
"verb": "PUT", "verb": "PUT",
@ -152,14 +211,24 @@ forgot about the rule with `SETEACL`.
"verb": "SETEACL", "verb": "SETEACL",
"wildcard": true, "wildcard": true,
"containerID": null "containerID": null
}, }
] ]
``` ```
> **_NB!_** To create buckets in NeoFS it's necessary to have session tokens with `PUT` and `SETEACL` permissions, that's why
the authmate creates a `SETEACL` session token automatically in case when a user specified the token rule with `PUT` and
forgot about the rule with `SETEACL`.
2. append `--session-token` parameter with the value `none` -- no session token will be created
3. skip the parameter, and `authmate` will create session tokens with default rules (the same as in `session.json`
in example above)
### Containers policy
Rules for mapping of `LocationConstraint` ([aws spec](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestBody)) Rules for mapping of `LocationConstraint` ([aws spec](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestBody))
to `PlacementPolicy` ([neofs spec](https://github.com/nspcc-dev/neofs-spec/blob/master/01-arch/02-policy.md)) to `PlacementPolicy` ([neofs spec](https://github.com/nspcc-dev/neofs-spec/blob/master/01-arch/02-policy.md))
can be set via param `container-policy` (json-string and file path allowed): can be set via parameter `--container-policy` (json-string and file path allowed):
``` ```json
{ {
"rep-3": "REP 3", "rep-3": "REP 3",
"complex": "REP 1 IN X CBF 1 SELECT 1 FROM * AS X", "complex": "REP 1 IN X CBF 1 SELECT 1 FROM * AS X",
@ -167,43 +236,18 @@ can be set via param `container-policy` (json-string and file path allowed):
} }
``` ```
Example of a command to issue a secret with custom rules for multiple gates:
```
$ ./neofs-authmate issue-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \
--bearer-rules '{"records":[{"operation":"PUT","action":"ALLOW","filters":[],"targets":[{"role":"OTHERS","keys":[]}]}]}' \
--gate-public-key 0313b1ac3a8076e155a7e797b24f0b650cccad5941ea59d7cfd51a024a8b2a06bf \
--gate-public-key 0317585fa8274f7afdf1fc5f2a2e7bece549d5175c4e5182e37924f30229aef967 \
--session-token '[{"verb":"DELETE","wildcard":false,"containerID":{"value":"%CID"}}]'
--container-policy '{"rep-3": "REP 3"}'
Enter password for wallet.json >
{
"access_key_id": "5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM",
"secret_access_key": "438bbd8243060e1e1c9dd4821756914a6e872ce29bf203b68f81b140ac91231c",
"owner_private_key": "274fdd6e71fc6a6b8fe77bec500254115d66d6d17347d7db0880d2eb80afc72a",
"container_id":"5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT"
}
```
Access key ID and secret access key are AWS credentials that you can use with
any S3 client.
Access key ID consists of Base58 encoded containerID(cid) and objectID(oid) stored on the NeoFS network and containing
the secret. Format of access_key_id: `%cid0%oid`, where 0(zero) is a delimiter.
## Obtainment of a secret access key ## Obtainment of a secret access key
You can get a secret access key associated with an access key ID by obtaining a You can get a secret access key associated with an access key ID by obtaining a
secret stored on the NeoFS network. Here is an example of providing one password (for `wallet.json`) via env variable secret stored on the NeoFS network. Here is an example of providing one password (for `wallet.json`) via env variable
and the other (for `gate-wallet.json`) interactively: and the other (for `gate-wallet.json`) interactively:
``` ```shell
$ AUTHMATE_WALLET_PASSPHRASE=some-pwd \ $ AUTHMATE_WALLET_PASSPHRASE=some-pwd \
./neofs-authmate obtain-secret --wallet wallet.json \ neofs-authmate obtain-secret --wallet wallet.json \
--peer 192.168.130.71:8080 \ --peer 192.168.130.71:8080 \
--gate-wallet gate-wallet.json \ --gate-wallet gate-wallet.json \
--access-key-id 5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM --access-key-id 5g933dyLEkXbbAspouhPPTiyLZRg4axBW1axSPD87eVT0AiXsH4AjYy1iTJ4C1WExzjBrSobJsQFWEyKLREe5sQYM
Enter password for gate-wallet.json > Enter password for gate-wallet.json >
{ {

183
docs/configuration.md
View file

@ -1,37 +1,51 @@
# Configuration # Configuration
Actually, everything available as a CLI parameter can also be specified via There are three ways to configure the S3 GW:
environment variables, so they're not specifically mentioned in most cases 1. CLI parameters
(see `--help` also). If you prefer a config file you can use it in yaml format. 2. YAML file
3. Environment variables
## Nodes and weights Everything available as a CLI parameter can also be specified via environment variables and almost everything can be
specified via `.yaml` configuration file.
But **not vice versa**, some parameters can be configured only with environment variables/configuration file.
Most of these parameters have default values, therefore, these ways to configure the gateway are optional and
basic configuration can be completed with CLI parameters only.
1. [CLI parameters](#CLI parameters)
1. [Nodes and weights](#Nodes and weights)
2. [Wallet](#Wallet)
3. [Binding and TLS](#Listening on address and TLS)
4. [RPC endpoint and resolving of bucket names](#RPC endpoint and resolving of bucket names)
5. [Processing of requests](#Processing of requests)
6. [Connection to NeoFS](#Connection to NeoFS)
7. [Monitoring and metrics](#Monitoring and metrics)
2. [YAML file and environment variables](#YAML file and environment variables)
1. [Notifications](#Notifications)
## CLI parameters
### Nodes and weights
You can specify multiple `-p` options to add more NeoFS nodes; this will make You can specify multiple `-p` options to add more NeoFS nodes; this will make
a gateway spread requests equally among them (using weight 1 for every node): a gateway spread requests equally among them (using weight 1 for every node):
``` ```shell
$ neofs-s3-gw -p 192.168.130.72:8080 -p 192.168.130.71:8080 $ neofs-s3-gw -p 192.168.130.72:8080 -p 192.168.130.71:8080
``` ```
If you want some specific load distribution proportions, use weights, but keep it in mind that they If you want some specific load distribution proportions, use weights and priorities, they
can only be specified via environment variables: can only be specified via environment variables or configuration file.
``` ### Wallet
$ S3_GW_PEERS_0_ADDRESS=192.168.130.72:8080 S3_GW_PEERS_0_WEIGHT=9 \
S3_GW_PEERS_1_ADDRESS=192.168.130.71:8080 S3_GW_PEERS_1_WEIGHT=1 neofs-s3-gw
```
This command will make gateway use 192.168.130.72 for 90% of the requests and
192.168.130.71 for the remaining 10%.
## Key Wallet (`--wallet`) is a mandatory parameter. It is a path to a wallet file. You can provide a passphrase to decrypt
a wallet via env variable or conf file, or you will be asked to enter a password interactively.
You can also specify an account address to use from a wallet using the `--address` parameter.
Wallet (`--wallet`) is a mandatory parameter. It is a path to a wallet file. You can provide password to decrypt a wallet ### Listening on address and TLS
via `S3_GW_WALLET_PASSPHRASE` variable or you will be asked to enter a password interactively.
You can also specify an account address to use from a wallet using `--address` parameter.
## Binding and TLS Gateway listens on `0.0.0.0:8080` by default, and you can change that with the `--listen_address` option.
Gateway binds to `0.0.0.0:8080` by default, and you can change that with
`--listen_address` option.
It can also provide TLS interface for its users, just specify paths to the key and It can also provide TLS interface for its users, just specify paths to the key and
certificate files via `--tls.key_file` and `--tls.cert_file` parameters. Note certificate files via `--tls.key_file` and `--tls.cert_file` parameters. Note
@ -39,92 +53,77 @@ that using these options makes gateway TLS-only, if you need to serve both TLS
and plain text you either have to run two gateway instances or use some and plain text you either have to run two gateway instances or use some
external redirecting solution. external redirecting solution.
Example to bind to `192.168.130.130:443` and serve TLS there (keys and nodes Example to bind to `192.168.130.130:443` and serve TLS there (keys and nodes are
omitted): omitted):
``` ```shell
$ neofs-s3-gw --listen_address 192.168.130.130:443 \ $ neofs-s3-gw --listen_address 192.168.130.130:443 \
--tls.key_file=key.pem --tls.cert_file=cert.pem --tls.key_file=key.pem --tls.cert_file=cert.pem
``` ```
## Monitoring and metrics ### RPC endpoint and resolving of bucket names
To set RPC endpoint specify a value of parameter `-r` or `--rpc-endpoint`. The parameter is **required if** another
parameter's `--resolve-order` value contains `nns`.
```shell
$ neofs-s3-gw --rpc-endpoint http://morph-chain.neofs.devenv:30333/ --resolve-order nns,dns
```
### Processing of requests
Maximum number of clients whose requests can be handled by the gateway can be specified by the value of
`--max_clients_count` parameter, the default value is 100.
`--max_clients_deadline` defines deadline after which the gate sends error `RequestTimeout` to a client, default value
is 30 seconds.
```shell
$ neofs-s3-gw --max_clients_count 150 --max_clients_deadline 1m
```
### Connection to NeoFS
Timeout to connect to NeoFS nodes can be set with `--connect_timeout` (default 30s)
and timeout to check node health during rebalance`--request_timeout` (default 15s).
Also, interval to check node health can be specified by `--rebalance_timer` value, default value is 15s.
```shell
$ neofs-s3-gw --request_timeout 15s --connect_timeout 1m --rebalance_timer 1h
```
### Monitoring and metrics
Pprof and Prometheus are integrated into the gateway, but not enabled by Pprof and Prometheus are integrated into the gateway, but not enabled by
default. To enable them, use `--pprof` and `--metrics` flags or default. To enable them, use `--pprof` and `--metrics` flags or
`S3_GW_PPROF`/`S3_GW_METRICS` environment variables. `S3_GW_PPROF`/`S3_GW_METRICS` environment variables.
## Yaml file ## YAML file and environment variables
Configuration file is optional and can be used instead of environment variables/other parameters.
It can be specified with `--config` parameter: Example of YAML configuration file: [.yaml-example](/config/config.yaml)
``` Examples of environment variables: [.env-example](/config/config.env).
A path to a configuration file can be specified with `--config` parameter:
```shell
$ neofs-s3-gw --config your-config.yaml $ neofs-s3-gw --config your-config.yaml
``` ```
Configuration file example: Parameters of the following groups can be configured via `.yaml` file or environment variables only:
``` 1. logging -- logging level
listen_address: 0.0.0.0:8084 2. caching -- lifetime and size for each cache
3. notifications
4. CORS
5. default policy of placing containers in NeoFS
wallet: ### Notifications
passphrase: 123456
logger: You can turn on notifications about successful completions of basic operations, and the gateway will send notifications
level: debug via NATS JetStream.
peers: To enable notifications you need:
0: 1. to configure the NATS server with JetStream
address: s01.neofs.devenv:8080 2. to specify NATS parameters for the S3 GW. It's ***necessary*** to define a values of `nats.enable` or
weight: 1 `S3_GW_NATS_ENABLED` as `True`
``` 3. to configure notifications in a bucket
To know the nesting level of the variable, you need to cut off the prefix `S3_GW` from the variable and split the rest parts by `_`.
For example, variable `S3_GW_PEERS_0_WEIGHT=1` will be transformed to:
```
peers:
0:
weight: 1
```
If a parameter doesn't support environment variable (e.g. `--listen_address 0.0.0.0:8084`) form, it is used as:
```
listen_address: 0.0.0.0:8084
```
### Default policy of placing containers in NeoFS
If a user sends a request `CreateBucket` and doesn't define policy for placing of a container in NeoFS, the S3 Gateway
will put the container with default policy. It can be specified via environment variable, e.g.:
```
S3_GW_DEFAULT_POLICY=REP 1 CBF 1 SELECT 1 FROM *
```
or via `.yaml` config file, e.g.:
```
default_policy: REP 1
```
If the value is not set at all it will be set as `REP 3`.
### Cache parameters
Parameters for caches in s3-gw can be specified in a .yaml config file. E.g.:
```
cache:
objects:
lifetime: 300s
size: 150
list:
lifetime: 1m
size: 100
names:
lifetime: 1m
size: 1000
buckets:
lifetime: 1m
size: 500
system:
lifetime: 2m
size: 1000
accessbox:
lifetime: 5m
size: 10
```
If invalid values are set, the gateway will use default values instead.