TrueCloudLab/frostfs-http-gw
18
1
Fork 17
Code Issues 9 Pull requests 4 Projects Releases 9 Activity Actions
frostfs-http-gw/docs/gate-configuration.md
Roman Loginov dc100f03a6
All checks were successful
/ Vulncheck (push) Successful in 4m45s
Details
/ Builds (push) Successful in 2m25s
Details
/ Lint (push) Successful in 3m16s
Details
/ Tests (push) Successful in 2m29s
Details
[#174] Add fallback path to search 
Fallback path to search is needed because
some software may keep FileName attribute
and ignore FilePath attribute during file
upload. Therefore, if this feature is
enabled under certain conditions (for more
information, see gate-configuration.md) a
search will be performed for the FileName
attribute.

Signed-off-by: Roman Loginov <r.loginov@yadro.com>
2024-12-16 10:43:34 +00:00

26 KiB
Raw Blame History

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
features Features 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.

features section

Contains parameters for enabling features.

features:
  enable_filepath_fallback: true
Parameter Type SIGHUP reload Default value Description
features.enable_filepath_fallback bool yes false Enable using fallback path to search for a object by attribute. If the value of the FilePath attribute in the request contains no / symbols or single leading / symbol and the object was not found, then an attempt is made to search for the object by the attribute FileName.