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
should work in the same way, although option names may need to be adjusted on
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
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
whereas the latter assumes the bucket will be part of the vhost,
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
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.
s3gw supports four different log levels:
default, s3gw runs with
The vast majority of deployments will only require
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
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
The available environment variables reflect the arguments accepted by the
container. These can be provided to the container using the
podman run. For example,
podman run -it -p 7480:7480 \ --env S3GW_DEBUG=medium \ quay.io/s3gw/s3gw:latest
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.