diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md new file mode 100644 index 00000000..ae486ac4 --- /dev/null +++ b/docs/advanced-usage.md @@ -0,0 +1,121 @@ +# 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. diff --git a/docs/config-s3gw.md b/docs/config-s3gw.md index afc8215e..3062e5d7 100644 --- a/docs/config-s3gw.md +++ b/docs/config-s3gw.md @@ -207,15 +207,18 @@ set up a node-local volume for testing if you do not have Longhorn. ## Log settings The log verbosity can also be configured for the s3gw pod. Set the `logLevel` -property to a number, with `"0"` being the least verbose and higher numbers -being more verbose: +property to one of `none`, `low`, `medium`, or `high`: ```yaml -logLevel: "1" +logLevel: "none" ``` -The highest `logLevel` that we recommend is 10, however, any integer required -is valid. +Generally speaking, `none` or `low` should be fine for most deployments, unless +there is reason to believe it's misbehaving. In that case, the highest +`logLevel` we recommend is `medium`. Higher log levels should be used only in +case the system is misbehaving significantly and there's a suspicion more +verbose debugging might be necessary. Please note that at `high` the system may +be impacted. ## Developer options diff --git a/mkdocs.yml b/mkdocs.yml index 90c999ee..35c8f368 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,7 @@ nav: - Installing k3s for s3gw: "s3gw-with-k3s.md" - Installing s3gw with Helm charts: "helm-charts.md" - Configuring the s3gw: "config-s3gw.md" + - Advanced usage: "advanced-usage.md" - Troubleshooting the s3gw: "troubleshoot-s3gw.md" - "Development Manual": - Developing the S3gw: "developing.md"