docs: document advanced container usage

Fixes: aquarist-labs/s3gw#754

Signed-off-by: Joao Eduardo Luis <[email protected]>

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/run-s3gw.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.

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
 

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"