[#140] Improve docs

Signed-off-by: Denis Kirillov <denis@nspcc.ru>
This commit is contained in:
Denis Kirillov 2022-04-08 12:01:57 +03:00 committed by Angira Kekteeva
parent baf425453d
commit eacd7be33e
5 changed files with 175 additions and 48 deletions

View file

@ -66,7 +66,7 @@ $ HTTP_GW_PEERS_0_ADDRESS=grpcs://192.168.130.72:8080 neofs-http-gw
## Configuration
In general, everything available as CLI parameter can also be specified via
environment variables, so they're not specifically mentioned in most cases
environment variables (see [example](./config/config.env)), so they're not specifically mentioned in most cases
(see `--help` also). If you prefer a config file you can use it in yaml format.
### Nodes: weights and priorities
@ -162,18 +162,9 @@ The gateway supports downloading files by common prefix (like dir) in zip format
using config or `HTTP_GW_ZIP_COMPRESSION=true` environment variable.
### Logging
`--verbose` flag enables gRPC logging and there is a number of environment
variables to tune logging behavior:
You can specify logging level (default `info`) using variable:
```
HTTP_GW_LOGGER_FORMAT=string - Logger format
HTTP_GW_LOGGER_LEVEL=string - Logger level
HTTP_GW_LOGGER_NO_CALLER=bool - Logger don't show caller
HTTP_GW_LOGGER_NO_DISCLAIMER=bool - Logger don't show application name/version
HTTP_GW_LOGGER_SAMPLING_INITIAL=int - Logger sampling initial
HTTP_GW_LOGGER_SAMPLING_THEREAFTER=int - Logger sampling thereafter
HTTP_GW_LOGGER_TRACE_LEVEL=string - Logger show trace on level
HTTP_GW_LOGGER_LEVEL=debug
```
### Yaml file
@ -183,39 +174,7 @@ It can be specified with `--config` parameter:
$ neofs-http-gw --config your-config.yaml
```
Configuration file example:
```
listen_address: 0.0.0.0:8082
wallet:
passphrase: 123456
logger:
level: debug
peers:
0:
address: grpc://s01.neofs.devenv:8080
weight: 1
priority: 1
zip:
compression: false
```
To know nesting level of variable you need to cut off the prefix `HTTP_GW` from variable and split the rest parts by `_`.
For example variable `HTTP_GW_PEERS_0_WEIGHT=1` will be transformed to:
```
peers:
0:
weight: 1
priority: 1
```
If parameter doesn't support environment variable (e.g. `--listen_address 0.0.0.0:8082`) form it is used as is:
```
listen_address: 0.0.0.0:8082
```
See [config](./config/config.yaml) for example.
## HTTP API provided

12
app.go
View file

@ -132,6 +132,10 @@ func newApp(ctx context.Context, opt ...Option) App {
func getNeoFSKey(a *app) (*ecdsa.PrivateKey, error) {
walletPath := a.cfg.GetString(cmdWallet)
if len(walletPath) == 0 {
walletPath = a.cfg.GetString(cfgWalletPath)
}
if len(walletPath) == 0 {
a.log.Info("no wallet path specified, creating ephemeral key automatically for this run")
key, err := keys.NewPrivateKey()
@ -150,7 +154,13 @@ func getNeoFSKey(a *app) (*ecdsa.PrivateKey, error) {
pwd := a.cfg.GetString(cfgWalletPassphrase)
password = &pwd
}
return getKeyFromWallet(w, a.cfg.GetString(cmdAddress), password)
address := a.cfg.GetString(cmdAddress)
if len(address) == 0 {
address = a.cfg.GetString(cfgWalletAddress)
}
return getKeyFromWallet(w, address, password)
}
func getKeyFromWallet(w *wallet.Wallet, addrStr string, password *string) (*ecdsa.PrivateKey, error) {

80
config/config.env Normal file
View file

@ -0,0 +1,80 @@
# Wallet section.
# Path to wallet.
HTTP_GW_WALLET_PATH=/path/to/wallet.json
# Account address. If omitted default one will be used.
HTTP_GW_WALLET_ADDRESS=NfgHwwTi3wHAS8aFAN243C5vGbkYDpqLHP
# Password to decrypt wallet.
HTTP_GW_WALLET_PASSPHRASE=pwd
# Enable metrics.
HTTP_GW_METRICS=true
# Enable pprof.
HTTP_GW_PPROF=true
# Log level.
HTTP_GW_LOGGER_LEVEL=debug
# Address to bind.
HTTP_GW_LISTEN_ADDRESS=0.0.0.0:443
# Provide cert to enable TLS.
HTTP_GW_TLS_CERTIFICATE=/path/to/tls/cert
# Provide key to enable TLS.
HTTP_GW_TLS_KEY=/path/to/tls/key
# Nodes configuration.
# This configuration make gateway use the first node (grpc://s01.neofs.devenv:8080)
# while it's healthy. Otherwise, gateway use the second node (grpc://s01.neofs.devenv:8080)
# for 10% of requests and the third node for 90% of requests.
# Peer 1.
# Endpoint.
HTTP_GW_PEERS_0_ADDRESS=grpc://s01.neofs.devenv:8080
# Until nodes with the same priority level are healthy
# nodes with other priority are not used.
# Еhe lower the value, the higher the priority.
HTTP_GW_PEERS_0_PRIORITY=1
# Load distribution proportion for nodes with the same priority.
HTTP_GW_PEERS_0_WEIGHT=1
# Peer 2.
HTTP_GW_PEERS_1_ADDRESS=grpc://s02.neofs.devenv:8080
HTTP_GW_PEERS_1_PRIORITY=2
HTTP_GW_PEERS_1_WEIGHT=1
# Peer 3.
HTTP_GW_PEERS_2_ADDRESS=grpc://s03.neofs.devenv:8080
HTTP_GW_PEERS_2_PRIORITY=2
HTTP_GW_PEERS_2_WEIGHT=9
# Per-connection buffer size for requests' reading.
# This also limits the maximum header size.
HTTP_GW_WEB_READ_BUFFER_SIZE=4096
# Per-connection buffer size for responses' writing.
HTTP_GW_WRITE_BUFFER_SIZE=4096
# ReadTimeout is the amount of time allowed to read
# the full request including body. The connection's read
# deadline is reset when the connection opens, or for
# keep-alive connections after the first byte has been read.
HTTP_GW_READ_TIMEOUT=15s
# WriteTimeout is the maximum duration before timing out
# writes of the response. It is reset after the request handler
# has returned.
HTTP_GW_WRITE_TIMEOUT=1m
# StreamRequestBody enables request body streaming,
# and calls the handler sooner when given body is
# larger then the current limit.
HTTP_GW_STREAM_REQUEST_BODY=true
# Maximum request body size.
# The server rejects requests with bodies exceeding this limit.
HTTP_GW_MAX_REQUEST_BODY_SIZE=4194304
# Create timestamp for object if it isn't provided by header.
HTTP_GW_UPLOAD_HEADER_USE_DEFAULT_TIMESTAMP=false
# Timeout to dial node.
HTTP_GW_CONNECT_TIMEOUT=5s
# Timeout to check node health during rebalance.
HTTP_GW_REQUEST_TIMEOUT=5s
# Interval to check nodes health.
HTTP_GW_REBALANCE_TIMER=30s
# Enable zip compression to download files by common prefix.
HTTP_GW_ZIP_COMPRESSION=false

78
config/config.yaml Normal file
View file

@ -0,0 +1,78 @@
wallet:
path: /path/to/wallet.json # Path to wallet.
address: NfgHwwTi3wHAS8aFAN243C5vGbkYDpqLHP # Account address. If omitted default one will be used.
passphrase: pwd # Password to decrypt wallet.
metrics: true # Enable metrics.
pprof: true # Enable pprof.
logger:
level: debug # Log level.
listen_address: 0.0.0.0:443 # Address to bind.
tls_certificate: /path/to/tls/cert # Provide cert to enable TLS.
tls_key: /path/to/tls/key # Provide key to enable TLS.
# Nodes configuration.
# This configuration make gateway use the first node (grpc://s01.neofs.devenv:8080)
# while it's healthy. Otherwise, gateway use the second node (grpc://s01.neofs.devenv:8080)
# for 10% of requests and the third node for 90% of requests.
peers:
0:
# Endpoint.
address: grpc://s01.neofs.devenv:8080
# Until nodes with the same priority level are healthy
# nodes with other priority are not used.
# Еhe lower the value, the higher the priority.
priority: 1
# Load distribution proportion for nodes with the same priority.
weight: 1
1:
address: grpc://s02.neofs.devenv:8080
priority: 2
weight: 1
2:
address: grpc://s03.neofs.devenv:8080
priority: 2
weight: 9
web:
# Per-connection buffer size for requests' reading.
# This also limits the maximum header size.
read_buffer_size: 4096
# Per-connection buffer size for responses' writing.
write_buffer_size: 4096
# ReadTimeout is the amount of time allowed to read
# the full request including body. The connection's read
# deadline is reset when the connection opens, or for
# keep-alive connections after the first byte has been read.
read_timeout: 15s
# WriteTimeout is the maximum duration before timing out
# writes of the response. It is reset after the request handler
# has returned.
write_timeout: 1m
# StreamRequestBody enables request body streaming,
# and calls the handler sooner when given body is
# larger then the current limit.
stream_request_body: true
# Maximum request body size.
# The server rejects requests with bodies exceeding this limit.
max_request_body_size: 4194304
upload_header:
use_default_timestamp: false # Create timestamp for object if it isn't provided by header.
connect_timeout: 5s # Timeout to dial node.
request_timeout: 5s # Timeout to check node health during rebalance.
rebalance_timer: 30s # Interval to check nodes health.
zip:
compression: false # Enable zip compression to download files by common prefix.

View file

@ -40,6 +40,8 @@ const (
// Wallet.
cfgWalletPassphrase = "wallet.passphrase"
cfgWalletPath = "wallet.path"
cfgWalletAddress = "wallet.address"
// Uploader Header.
cfgUploaderHeaderEnableDefaultTimestamp = "upload_header.use_default_timestamp"
@ -53,7 +55,6 @@ const (
// Command line args.
cmdHelp = "help"
cmdVersion = "version"
cmdVerbose = "verbose"
cmdPprof = "pprof"
cmdMetrics = "metrics"
cmdWallet = "wallet"
@ -89,7 +90,6 @@ func settings() *viper.Viper {
flags.StringP(cmdWallet, "w", "", `path to the wallet`)
flags.String(cmdAddress, "", `address of wallet account`)
config := flags.String(cmdConfig, "", "config path")
flags.Bool(cmdVerbose, false, "debug gRPC connections")
flags.Duration(cfgConTimeout, defaultConnectTimeout, "gRPC connect timeout")
flags.Duration(cfgReqTimeout, defaultRequestTimeout, "gRPC request timeout")
flags.Duration(cfgRebalance, defaultRebalanceTimer, "gRPC connection rebalance timer")