frostfs-http-gw/docs/gate-configuration.md

FrostFS HTTP Gateway configuration file

This section contains detailed FrostFS HTTP Gateway configuration file description including default config values and some tips to set up configurable values.

There are some custom types used for brevity:

• duration -- string consisting of a number and a suffix. Suffix examples include s (seconds), m (minutes), ms ( milliseconds).

Reload on SIGHUP

Some config values can be reloaded on SIGHUP signal. Such parameters have special mark in tables below.

You can send SIGHUP signal to app using the following command:

$ kill -s SIGHUP <app_pid>

Example:

$ ./bin/frostfs-http-gw --config config.yaml  &> http.log &
[1] 998346

$ cat http.log
# ...
2022-10-03T09:37:25.826+0300    info    frostfs-http-gw/app.go:332        starting application    {"app_name": "frostfs-http-gw", "version": "v0.24.0"}
# ...

$ kill -s SIGHUP 998346

$ cat http.log
# ...
2022-10-03T09:38:16.205+0300    info    frostfs-http-gw/app.go:470        SIGHUP config reload completed

Structure

Section	Description
no section	General parameters
wallet	Wallet configuration
peers	Nodes configuration
logger	Logger configuration
web	Web configuration
server	Server configuration
upload-header	Upload header configuration
zip	ZIP configuration
pprof	Pprof configuration
prometheus	Prometheus configuration
tracing	Tracing configuration
runtime	Runtime configuration
frostfs	Frostfs configuration
cache	Cache configuration
resolve_bucket	Bucket name resolving configuration
index_page	Index page configuration
multinet	Multinet configuration

General section

rpc_endpoint: http://morph-chain.frostfs.devenv:30333
resolve_order:
  - nns
  - dns

connect_timeout: 5s
stream_timeout: 10s
request_timeout: 5s
rebalance_timer: 30s
pool_error_threshold: 100
reconnect_interval: 1m
worker_pool_size: 1000

Parameter	Type	SIGHUP reload	Default value	Description
rpc_endpoint	string	yes		The address of the RPC host to which the gateway connects to resolve bucket names.
resolve_order	[]string	yes	[nns, dns]	Order of bucket name resolvers to use.
connect_timeout	duration		10s	Timeout to connect to a node.
stream_timeout	duration		10s	Timeout for individual operations in streaming RPC.
request_timeout	duration		15s	Timeout to check node health during rebalance.
rebalance_timer	duration		60s	Interval to check node health.
pool_error_threshold	uint32		100	The number of errors on connection after which node is considered as unhealthy.
reconnect_interval	duration	no	1m	Listeners reconnection interval.
worker_pool_size	int	no	1000	Maximum worker count in handler's worker pool.

wallet section

wallet:
  path: /path/to/wallet.json
  address: NfgHwwTi3wHAS8aFAN243C5vGbkYDpqLHP
  passphrase: pwd

Parameter	Type	Default value	Description
path	string		Path to the wallet.
address	string		Account address to get from wallet. If omitted default one will be used.
passphrase	string		Passphrase to decrypt wallet.

peers section

# Nodes configuration
# This configuration makes the gateway use the first node (node1.frostfs:8080)
# while it's healthy. Otherwise, gateway uses the second node (node2.frostfs:8080)
# for 10% of requests and the third node (node3.frostfs:8080) for 90% of requests.
# Until nodes with the same priority level are healthy
# nodes with other priority are not used.
# The lower the value, the higher the priority.
peers:
  0:
    address: node1.frostfs:8080
    priority: 1
    weight: 1
  1:
    address: node2.frostfs:8080
    priority: 2
    weight: 0.1
  2:
    address: node3.frostfs:8080
    priority: 2
    weight: 0.9

Parameter	Type	Default value	Description
address	string		Address of storage node.
priority	int	1	It allows to group nodes and don't switch group until all nodes with the same priority will be unhealthy. The lower the value, the higher the priority.
weight	float	1	Weight of node in the group with the same priority. Distribute requests to nodes proportionally to these values.

server section

You can specify several listeners for server. For example, for http and https.

server:
  - address: 0.0.0.0:8080
    tls:
      enabled: false
      cert_file: /path/to/cert
      key_file: /path/to/key
  - address: 0.0.0.0:8081
    tls:
      enabled: true
      cert_file: /path/to/another/cert
      key_file: /path/to/another/key

Parameter	Type	SIGHUP reload	Default value	Description
address	string		0.0.0.0:8080	The address that the gateway is listening on.
tls.enabled	bool		false	Enable TLS or not.
tls.cert_file	string	yes		Path to the TLS certificate.
tls.key_file	string	yes		Path to the key.

logger section

logger:
  level: debug
  destination: stdout
  sampling:
    enabled: false
    initial: 100
    thereafter: 100
    interval: 1s

Parameter	Type	SIGHUP reload	Default value	Description
level	string	yes	debug	Logging level. Possible values: debug, info, warn, error, dpanic, panic, fatal.
destination	string	no	stdout	Destination for logger: stdout or journald
sampling.enabled	bool	no	false	Sampling enabling flag.
sampling.initial	int	no	'100'	Sampling count of first log entries.
sampling.thereafter	int	no	'100'	Sampling count of entries after an interval.
sampling.interval	duration	no	'1s'	Sampling interval of messaging similar entries.

web section

web:
  read_buffer_size: 4096
  write_buffer_size: 4096
  read_timeout: 10m
  write_timeout: 5m
  stream_request_body: true
  max_request_body_size: 4194304

Parameter	Type	Default value	Description
read_buffer_size	int	4096	Per-connection buffer size for requests' reading. This also limits the maximum header size.
write_buffer_size	int	4096	Per-connection buffer size for responses' writing.
read_timeout	duration	10m	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.
write_timeout	duration	5m	The maximum duration before timing out writes of the response. It is reset after the request handler has returned.
stream_request_body	bool	true	Enables request body streaming, and calls the handler sooner when given body is larger than the current limit.
max_request_body_size	int	4194304	Maximum request body size. The server rejects requests with bodies exceeding this limit.

upload-header section

upload_header:
  use_default_timestamp: false

Parameter	Type	SIGHUP reload	Default value	Description
use_default_timestamp	bool	yes	false	Create timestamp for object if it isn't provided by header.

zip section

zip:
  compression: false

Parameter	Type	SIGHUP reload	Default value	Description
compression	bool	yes	false	Enable zip compression when download files by common prefix.

pprof section

Contains configuration for the pprof profiler.

pprof:
  enabled: true
  address: localhost:8083

Parameter	Type	SIGHUP reload	Default value	Description
enabled	bool	yes	false	Flag to enable the service.
address	string	yes	localhost:8083	Address that service listener binds to.

prometheus section

Contains configuration for the prometheus metrics service.

prometheus:
  enabled: true
  address: localhost:8084

Parameter	Type	SIGHUP reload	Default value	Description
enabled	bool	yes	false	Flag to enable the service.
address	string	yes	localhost:8084	Address that service listener binds to.

tracing section

Contains configuration for the tracing service.

tracing:
  enabled: true
  exporter: "otlp_grpc"
  endpoint: "localhost:4317"
  trusted_ca: "/etc/ssl/telemetry-trusted-ca.pem"
  attributes:
    - key: key0
      value: value
    - key: key1
      value: value

Parameter	Type	SIGHUP reload	Default value	Description
enabled	bool	yes	false	Flag to enable the tracing.
exporter	string	yes		Trace collector type (stdout or otlp_grpc are supported).
endpoint	string	yes		Address of collector endpoint for OTLP exporters.
trusted_ca	string	yes		Path to certificate of a certification authority in pem format, that issued the TLS certificate of the telemetry remote server.
attributes	[]Attributes	yes		An array of configurable attributes in key-value format.

attributes subsection

  attributes:
    - key: key0
      value: value
    - key: key1
      value: value

Parameter	Type	SIGHUP reload	Default value	Description
key	string	yes		Attribute key.
value	string	yes		Attribute value.

runtime section

Contains runtime parameters.

runtime:
  soft_memory_limit: 1gb

Parameter	Type	SIGHUP reload	Default value	Description
soft_memory_limit	size	yes	maxint64	Soft memory limit for the runtime. Zero or no value stands for no limit. If GOMEMLIMIT environment variable is set, the value from the configuration file will be ignored.

frostfs section

Contains parameters of requests to FrostFS.

frostfs:
  client_cut: false
  buffer_max_size_for_put: 1048576 # 1mb
  tree_pool_max_attempts: 0

Parameter	Type	SIGHUP reload	Default value	Description
client_cut	bool	yes	false	This flag enables client side object preparing.
buffer_max_size_for_put	uint64	yes	1048576	Sets max buffer size for read payload in put operations.
tree_pool_max_attempts	uint32	no	0	Sets max attempt to make successful tree request. Value 0 means the number of attempts equals to number of nodes in pool.

cache section

cache:
  buckets:
    lifetime: 1m
    size: 1000

Parameter	Type	Default value	Description
buckets	Cache config	lifetime: 60s size: 1000	Cache which contains mapping of bucket name to bucket info.

cache subsection

lifetime: 1m
size: 1000

Parameter	Type	Default value	Description
lifetime	duration	depends on cache	Lifetime of entries in cache.
size	int	depends on cache	LRU cache size.

resolve_bucket section

Bucket name resolving parameters from and to container ID.

resolve_bucket:
  namespace_header: X-Frostfs-Namespace
  default_namespaces: [ "", "root" ]

Parameter	Type	SIGHUP reload	Default value	Description
namespace_header	string	yes	X-Frostfs-Namespace	Header to determine zone to resolve bucket name.
default_namespaces	[]string	yes	["","root"]	Namespaces that should be handled as default.

index_page section

Parameters for index HTML-page output. Activates if GetObject request returns not found. Two index page modes available:

• s3 mode uses tree service for listing objects,
• native sends requests to nodes via native protocol. If request pass S3-bucket name instead of CID, s3 mode will be used, otherwise native.

index_page:
  enabled: false
  template_path: ""

Parameter	Type	SIGHUP reload	Default value	Description
enabled	bool	yes	false	Flag to enable index_page return if no object with specified S3-name was found.
template_path	string	yes	""	Path to .gotmpl file with html template for index_page.

cors section

Parameters for CORS (used in OPTIONS requests and responses in all handlers). If values are not set, headers will not be included to response.

cors:
  allow_origin: "*"
  allow_methods: ["GET", "HEAD"]
  allow_headers: ["Authorization"]
  expose_headers: ["*"]
  allow_credentials: false
  max_age: 600

Parameter	Type	SIGHUP reload	Default value	Description
allow_origin	string	yes		Values for Access-Control-Allow-Origin headers.
allow_methods	[]string	yes		Values for Access-Control-Allow-Methods headers.
allow_headers	[]string	yes		Values for Access-Control-Allow-Headers headers.
expose_headers	[]string	yes		Values for Access-Control-Expose-Headers headers.
allow_credentials	bool	yes	false	Values for Access-Control-Allow-Credentials headers.
max_age	int	yes	600	Values for Access-Control-Max-Age headers.

multinet section

Configuration of multinet support.

multinet:
   enabled: false
   balancer: roundrobin
   restrict: false
   fallback_delay: 300ms
   subnets:
      - mask: 1.2.3.4/24
        source_ips:
           - 1.2.3.4
           - 1.2.3.5

Parameter	Type	SIGHUP reload	Default value	Description
enabled	bool	yes	false	Enables multinet setting to manage source ip of outcoming requests.
balancer	string	yes	""	Strategy to pick source IP. By default picks first address. Supports roundrobin setting.
restrict	bool	yes	false	Restricts requests to an undefined subnets.
fallback_delay	duration	yes	300ms	Delay between IPv6 and IPv4 fallback stack switch.
subnets	[]Subnet	yes		Set of subnets to apply multinet dial settings.

subnet subsection

- mask: 1.2.3.4/24
  source_ips:
    - 1.2.3.4
    - 1.2.3.5

Parameter	Type	SIGHUP reload	Default value	Description
mask	string	yes		Destination subnet.
source_ips	[]string	yes		Array of source IP addresses to use when dialing destination subnet.