docs(gcs): mention external accounts

docs/Configuration.md

@@ -87,11 +87,12 @@ configuration variables
 
 * `SCCACHE_BUCKET` s3 bucket to be used
 * `SCCACHE_ENDPOINT` s3 endpoint
-* `SCCACHE_REGION` s3 region
+* `SCCACHE_REGION` s3 region, required if using AWS S3
 * `SCCACHE_S3_USE_SSL` s3 endpoint requires TLS, set this to `true`
 
 The endpoint used then becomes `${SCCACHE_BUCKET}.s3-{SCCACHE_REGION}.amazonaws.com`.
-If `SCCACHE_REGION` is undefined, it will default to `us-east-1`.
+If you are not using the default endpoint and `SCCACHE_REGION` is undefined, it
+will default to `us-east-1`.
 
 #### cloudflare r2
 

docs/Gcs.md

@@ -1,31 +1,26 @@
 # Google Cloud Storage
 
-To use [Google Cloud Storage](https://cloud.google.com/storage/), you need to set the `SCCACHE_GCS_BUCKET` environment variable to the name of the GCS bucket.
+To use [Google Cloud Storage](https://cloud.google.com/storage/), you need to set
+the `SCCACHE_GCS_BUCKET` environment variable to the name of the GCS bucket.
 
-By default, SCCACHE on GCS will be read-only. To change this, set `SCCACHE_GCS_RW_MODE` to either `READ_ONLY` or `READ_WRITE`.
+By default, SCCACHE on GCS will be read-only. To change this, set `SCCACHE_GCS_RW_MODE`
+to either `READ_ONLY` or `READ_WRITE`.
 
-You can also define a prefix that will be prepended to the keys of all cache objects created and read within the GCS bucket, effectively creating a scope. To do that use the `SCCACHE_GCS_KEY_PREFIX` environment variable. This can be useful when sharing a bucket with another application.
-
-To create such account, in GCP, go in `APIs and Services` => `Cloud Storage` => `Create credentials` => `Service account`. Then, once created, click on the account then `Keys` => `Add key` => `Create new key`. Select the JSON format and here it is. This JSON file is what `SCCACHE_GCS_KEY_PATH` expects.
-The service account needs `Storage Object Admin` permissions on the bucket (otherwise, sccache will fail with a simple `Permission denied`).
-
-To verify that it works, run:
-
-```
-export SCCACHE_GCS_BUCKET=<bucket name in GCP>
-export SCCACHE_GCS_KEY_PATH=secret-gcp-storage.json
-./sccache --show-stats
-# you should see
-[...]
-Cache location                  GCS, bucket: Bucket(name=<bucket name in GCP>), key_prefix: (none)
-```
+You can also define a prefix that will be prepended to the keys of all cache objects
+created and read within the GCS bucket, effectively creating a scope. To do that
+use the `SCCACHE_GCS_KEY_PREFIX` environment variable. This can be useful when
+sharing a bucket with another application.
 
 ## Credentials
 
 Sccache is able to load credentials from various sources. Including:
 
-- User Input: If `SCCACHE_GCS_KEY_PATH` has been set, we will load from key path first.
-- [Task Cluster](https://taskcluster.net/): If `SCCACHE_GCS_CREDENTIALS_URL` has been set, we will load token from this url first.
+- User Input: If `SCCACHE_GCS_KEY_PATH` has been set, we will load from this file
+  first.
+  - Service accounts JSONs
+  - External accounts JSONs
+- [Task Cluster](https://taskcluster.net/): If `SCCACHE_GCS_CREDENTIALS_URL` has
+  been set, we will load token from this url first.
 - Static: `GOOGLE_APPLICATION_CREDENTIALS`
 - Well-known locations:
   - Windows: `%APPDATA%\gcloud\application_default_credentials.json`
@@ -34,6 +29,45 @@ Sccache is able to load credentials from various sources. Including:
     - `$HOME/.config/gcloud/application_default_credentials.json`
 - VM Metadata: Fetch token will the specified service account.
 
+### Service accounts
+
+To create such account, in GCP, go in `APIs and Services` => `Cloud Storage` =>
+`Create credentials` => `Service account`. Then, once created, click on the account
+then `Keys` => `Add key` => `Create new key`. Select the JSON format and here it
+is. This JSON file is what `SCCACHE_GCS_KEY_PATH` expects.
+
+The service account needs `Storage Object Admin` permissions on the bucket
+(otherwise, sccache will fail with a simple `Permission denied`).
+
+### External accounts
+
+Such accounts require creating a [Workload Identity Pool and Workload Identity Provider].
+This approach allows the environment (Azure, Aws, or other OIDC providers like Github)
+to create a temporary service account grant without having to share a service account
+JSON, which can be pretty powerful. An example on how to create such accounts is
+[Google's guide on how to use it with Github].
+
+After generating the external account JSON file, you may pass its path to `SCCACHE_GCS_KEY_PATH`.
+
+Service accounts used by the pool must have `Storage Object Admin` permissions on
+bucket as well.
+
+## Verifying it works
+
+To verify that it works, run:
+
+```
+export SCCACHE_GCS_BUCKET=<bucket name in GCP>
+export SCCACHE_GCS_KEY_PATH=secret-gcp-storage.json
+./sccache --show-stats
+# you should see
+[...]
+Cache location                  GCS, bucket: Bucket(name=<bucket name in GCP>), key_prefix: (none)
+```
+
 ## Deprecation
 
 `SCCACHE_GCS_OAUTH_URL` have been deprecated and not supported, please use `SCCACHE_GCS_SERVICE_ACCOUNT` instead.
+
+[Workload Identity Pool and Workload Identity Provider]: https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers
+[Google's guide on how to use it with Github]: https://cloud.google.com/blog/products/identity-security/enabling-keyless-authentication-from-github-actions

docs/S3.md

@@ -2,7 +2,7 @@
 
 If you want to use S3 storage for the sccache cache, you need to set the `SCCACHE_BUCKET` environment variable to the name of the S3 bucket to use.
 
-You can configure the region using the `SCCACHE_REGION` environment variable, or specify the `region` key in `~/.aws/credentials`. Alternatively you can specify the endpoint URL using the `SCCACHE_ENDPOINT` environment variable. To connect to a minio storage for example you can set `SCCACHE_ENDPOINT=<ip>:<port>`.
+If using the default endpoint, you **must** configure the region using the `SCCACHE_REGION` environment variable, or specify the `region` key in `~/.aws/credentials`. Alternatively you can specify the endpoint URL using the `SCCACHE_ENDPOINT` environment variable. To connect to a minio storage for example you can set `SCCACHE_ENDPOINT=<ip>:<port>`.
 
 If your endpoint requires HTTPS/TLS, set `SCCACHE_S3_USE_SSL=true`. If you don't need a secure network layer, HTTP (`SCCACHE_S3_USE_SSL=false`) might be better for performance.
 
@@ -12,9 +12,9 @@ You can also define a prefix that will be prepended to the keys of all cache obj
 
 Cloudflare R2 is an S3-compatible object storage and works with the same configuration options as above. To use R2, you **must** define `SCCACHE_ENDPOINT`, otherwise sccache 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 `SCCACHE_ENDPOINT` or `SCCACHE_S3_USE_SSL=true` can be used, if the protocol is omitted. There are no regions in R2, so `SCCACHE_REGION` must point to `auto`. The below environment variables are recommended.
 
-* `SCCACHE_BUCKET` is the name of your R2 bucket.
-* `SCCACHE_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](https://developers.cloudflare.com/fundamentals/get-started/basic-tasks/find-account-and-zone-ids/).
-* `SCCACHE_REGION` should be set to `auto`.
+- `SCCACHE_BUCKET` is the name of your R2 bucket.
+- `SCCACHE_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](https://developers.cloudflare.com/fundamentals/get-started/basic-tasks/find-account-and-zone-ids/).
+- `SCCACHE_REGION` should be set to `auto`.
 
 ## Credentials
 

src/cache/s3.rs

@@ -29,11 +29,16 @@ impl S3Cache {
     ) -> Result<Operator> {
         let mut builder = S3::default();
         builder.bucket(bucket);
-        builder.region(region.unwrap_or("us-east-1"));
         builder.root(key_prefix);
+
+        if let Some(region) = region {
+            builder.region(region);
+        }
+
         if no_credentials {
             builder.disable_config_load();
         }
+
         if let Some(endpoint) = endpoint {
             builder.endpoint(&endpoint_resolver(endpoint, use_ssl)?);
         }

tests/sccache_args.rs

@@ -79,6 +79,7 @@ fn test_s3_invalid_args() -> Result<()> {
     cmd.arg("--start-server")
         .env("SCCACHE_LOG", "debug")
         .env("SCCACHE_BUCKET", "test")
+        .env("SCCACHE_REGION", "us-east-1")
         .env("AWS_ACCESS_KEY_ID", "invalid_ak")
         .env("AWS_SECRET_ACCESS_KEY", "invalid_sk");