Advanced usage

The processes and steps described in this page should not be applicable to the vast majority of s3gw deployments. However, depending on circumstance, one might need to perform some of these for testing or debugging.

The following sections rely on podman for examples. Using docker instead should work in the same way, although option names may need to be adjusted on occasion.

Running the container

One might need to run the container standalone, in which case it's important to understand how to properly configure it. Running the container with --help will provide some insight.

podman run -it quay.io/s3gw/s3gw:latest --help

Which should result in something like the following, minus eventual changes not reflected in this example:

usage: /s3gw/bin/entrypoint.sh [options... -- args]

options:
--help                Shows this message.
--id ID               Specifies a custom instance ID (default: s3gw).
--cert FILE KEY       Specifies SSL certificate. Expects a .crt as first
                      argument, and a .key as second argument.
--dns-name VALUE      For vhost style buckets, VALUE should be the DNS domain
                      to be used.
--debug LEVEL         Runs with debug. Levels available: "high", "medium",
                      "low", "none" (default: none).
--no-telemetry        Disable telemetry.
--telemetry-url URL   Specifies telemetry URL.
--with-status         Enables status frontend at port 9090.

args:
Any option supported by RADOS Gateway. For advanced use only.

env variables:
S3GW_ID           Specifies a custom instance ID.
S3GW_DNS_NAME     Specifies a DNS domain to be used for vhost style buckets.
S3GW_DEBUG        Specifies the debug level to be used.
S3GW_CERT_FILE    Specifies the SSL certificate file.
S3GW_CERT_KEY     Specifies the SSL certificate key file.

Keep in mind that to access the service, one needs to expose the required ports. For s3gw these are port 7480 for non-SSL access, and port 7481 for SSL access. This can be achieved with:

podman run -it -p 7480:7480 quay.io/s3gw/s3gw:latest

In the following sections, we will be describing some of the available options.

Using vhost style buckets

S3 supports two styles of bucket access: path and vhost. The former considers the buckets will be part of the address path, like in my.domain.tld/my-bucket/, whereas the latter assumes the bucket will be part of the vhost, my-bucket.my.domain.tld.

By default, s3gw runs with path style buckets. One can enable vhost style buckets by providing the DNS domain name to be used for the service. For example,

podman run -it -p 7480:7480 \
    quay.io/s3gw/s3gw:latest \
    --dns-name my.domain.tld

Specifying certificates

s3gw supports running with SSL, but will require a certificate to be provided. The location of this certificate must be local to the container namespace, and thus should be bind mounted into the container.

podman run -it -p 7481:7481 \
    -v ./my-cert.crt:/data/my-cert.crt \
    -v ./my-cert.key:/data/my-cert.key \
    quay.io/s3gw/s3gw:latest \
    --cert /data/my-cert.crt /data/my-cert.key

The s3gw service should now be available on the host's port 7481 with SSL enabled.

Debugging output

s3gw supports four different log levels: none, low, medium, and high. By default, s3gw runs with none.

The vast majority of deployments will only require none or low, for as long as they are behaving nicely. In case of misbehavior, it is reasonable to look towards the logs for indication of what the problem might be. In this case, the typical deployment will rely on medium. Only in very exceptional situations will a high be useful. Keep in mind that at a high debug level, the system will be put under a lot of strain from the amount of outputted messages, and the value of additional verbosity may not be significant.

Running with debug only requires specifying the --debug LEVEL argument to the container, such as

podman run -it -p 7480:7480 \
    quay.io/s3gw/s3gw:latest \
    --debug medium

Environment variables

The available environment variables reflect the arguments accepted by the container. These can be provided to the container using the --env VAR=VALUE argument to podman run. For example,

podman run -it -p 7480:7480 \
    --env S3GW_DEBUG=medium \
    quay.io/s3gw/s3gw:latest

Additional arguments

The container accepts additional arguments, that will be passed directly to the underlying RADOS Gateway binary. These should be used only if one knows what they are doing. To obtain a small subset of the option supported, running with -- --help will provide some information. Please note that not all the options provided in this help message will be applicable.