Skip to content

S3.md

Latest commit

 

History

History
35 lines (23 loc) · 3.35 KB

S3.md

File metadata and controls

35 lines (23 loc) · 3.35 KB

S3

If you want to use S3 storage for the rstash cache, you need to set the following environment variables:

  • RSTASH_BUCKET with the name of the S3 bucket to use;
  • RSTASH_REGION with the S3 region. If you have set RSTASH_ENDPOINT, you can set RSTASH_REGION to auto;
  • Optionally, RSTASH_ENDPOINT=<ip>:<port> with a custom URL of a server you want a use, such as MinIO or DigitalOcean storage.
  • RSTASH_S3_ENABLE_VIRTUAL_HOST_STYLE to true if you are using a custom endpoint that supports virtual host style addressing. This is required for S3 transfer acceleration and some S3-compatible storage services. If you are using AWS S3, you can leave this unset.

If your endpoint requires HTTPS/TLS, set RSTASH_S3_USE_SSL=true. If you don't need a secure network layer, HTTP (RSTASH_S3_USE_SSL=false) might be better for performance.

Enable server-side encryption with s3 managed key (SSE-S3), set RSTASH_S3_SERVER_SIDE_ENCRYPTION=true.
More details about encryption here and documentation here.

You can also define a prefix that will be prepended to the keys of all cache objects created and read within the S3 bucket, effectively creating a scope. To do that use the RSTASH_S3_KEY_PREFIX environment variable. This can be useful when sharing a bucket with another application.

R2

Cloudflare R2 is an S3-compatible object storage and works with the same configuration options as above. To use R2, you must define RSTASH_ENDPOINT, otherwise rstash will default to AWS as the endpoint to hit. R2 also requires endpoint connections to be secure, therefore https:// either needs to be included in RSTASH_ENDPOINT or RSTASH_S3_USE_SSL=true can be used, if the protocol is omitted. There are no regions in R2, so RSTASH_REGION must point to auto. The below environment variables are recommended.

  • RSTASH_BUCKET is the name of your R2 bucket.
  • RSTASH_ENDPOINT should follow the format of https://<ACCOUNT_ID>.r2.cloudflarestorage.com. It is recommended that https:// be included in this env var. Your account ID can be found here.
  • RSTASH_REGION should be set to auto.

Credentials

Rstash is able to load credentials from various sources. Including:

  • Static: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  • Profile: ~/.aws/credentials and ~/.aws/config. The AWS_PROFILE environment variable can be used to select a specific profile if multiple profiles are available.
  • EC2 Metadata Services: Via IMDSv2.
  • AssumeRole: assume role with the role specified by AWS_ROLE_ARN.
  • AssumeRoleWithWebIdentity: assume role with web webIdentity specified by AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE.

Alternatively, the RSTASH_S3_NO_CREDENTIALS environment variable can be set to use public readonly access to the S3 bucket, without the need for credentials. Valid values for this environment variable are true, 1, false, and 0. This can be useful for implementing a readonly cache for pull requests, which typically cannot be given access to credentials for security reasons.