From 7913c878d5eda37eae9ab85745da5abc587e1954 Mon Sep 17 00:00:00 2001 From: Jonathan Cammisuli <4332460+Cammisuli@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:28:38 -0500 Subject: [PATCH] docs(core): add information for s3 compatible providers (#28925) ## Current Behavior ## Expected Behavior ## Related Issue(s) Fixes # (cherry picked from commit 2c0592503a8f03cba820b58c85f9a1316ee69eba) --- .../powerpack-s3-cache/documents/overview.md | 30 ++++++++++++++++++- .../powerpack-s3-cache/generators/init.json | 20 +++++++++---- .../powerpack-s3-cache-plugin.md | 30 ++++++++++++++++++- 3 files changed, 73 insertions(+), 7 deletions(-) diff --git a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md index f5faddceab0a2..dafde4ab80e89 100644 --- a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md +++ b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md @@ -122,5 +122,33 @@ Regardless of how you manage your AWS authentication, you need to configure your | **Property** | **Description** | | ----------------- | --------------------------------------------------------------------------------- | | **region** | The id of the AWS region to use | -| **bucket** | The name of the AWS bucket to use | +| **bucket** | The name of the S3 bucket to use | | **encryptionKey** | Nx encryption key used to encrypt and decrypt artifacts from the cache (optional) | + +#### S3 Compatible Providers + +To use `@nx/powerpack-s3-cache` with S3 compatible providers ([MinIO](https://min.io/product/s3-compatibility), [LocalStack](https://www.localstack.cloud), [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces), [Cloudflare](https://www.cloudflare.com/developer-platform/solutions/s3-compatible-object-storage), etc..), `endpoint` will need to be provided. Some providers also need to have `forcePathStyle` set to true in the configuration. + +Below is an example on how to connect to MinIO: + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "region": "us-east-1", + "bucket": "my-bucket", + "endpoint": "https://play.min.io", + "forcePathStyle": true, + "accessKeyId": "abc1234", + "secretAccessKey": "4321cba" + } +} +``` + +| **Property** | **Description** | +| ------------------- | --------------------------------------------------------------------------------------------------------- | +| **region** | The id of the S3 compatible storage region to use | +| **bucket** | The name of the S3 compatible storage bucket to use | +| **forcePathStyle** | Changes the way artifacts are uploaded. Usually used for S3 compatible providers (MinIO, LocalStack, etc) | +| **endpoint** | The custom endpoint to upload artifacts to. If endpoint is not defined, the default AWS endpoint is used | +| **accessKeyId** | AWS Access Key ID (optional if `AWS_ACCESS_KEY_ID` is set in the environment) | +| **secretAccessKey** | AWS secret access key (optional if `AWS_SECRET_ACCESS_KEY` is set in the environment) | diff --git a/docs/external-generated/packages/powerpack-s3-cache/generators/init.json b/docs/external-generated/packages/powerpack-s3-cache/generators/init.json index c1a7e74820ac7..8f7b97f8fe7c1 100644 --- a/docs/external-generated/packages/powerpack-s3-cache/generators/init.json +++ b/docs/external-generated/packages/powerpack-s3-cache/generators/init.json @@ -9,16 +9,26 @@ "properties": { "region": { "type": "string", - "description": "The AWS region the bucket is located in", - "x-prompt": "Which AWS region is the bucket located in?" + "description": "The AWS region the bucket is located in" + }, + "accessKeyId": { + "type": "string", + "description": "The AWS Access Key ID to use to access the S3 Bucket, alternatively set the AWS_ACCESS_KEY_ID environment variable" + }, + "secretAccessKey": { + "type": "string", + "description": "The AWS Secret Access Key to use to access the S3 Bucket, alternatively set the AWS_SECRET_ACCESS_KEY environment variable" }, "bucket": { "type": "string", - "description": "The the name of the S3 Bucket to store the Nx Cache in", - "x-prompt": "What is the name of the S3 Bucket to store the Nx Cache in?" + "description": "The the name of the S3 Bucket to store the Nx Cache in" + }, + "forcePathStyle": { + "type": "boolean", + "description": "Set to true to use path style URLs for S3 objects" } }, - "required": ["region", "bucket"], + "required": [], "presets": [] }, "description": "Initialize the S3 Cache", diff --git a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md index f5faddceab0a2..dafde4ab80e89 100644 --- a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md +++ b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md @@ -122,5 +122,33 @@ Regardless of how you manage your AWS authentication, you need to configure your | **Property** | **Description** | | ----------------- | --------------------------------------------------------------------------------- | | **region** | The id of the AWS region to use | -| **bucket** | The name of the AWS bucket to use | +| **bucket** | The name of the S3 bucket to use | | **encryptionKey** | Nx encryption key used to encrypt and decrypt artifacts from the cache (optional) | + +#### S3 Compatible Providers + +To use `@nx/powerpack-s3-cache` with S3 compatible providers ([MinIO](https://min.io/product/s3-compatibility), [LocalStack](https://www.localstack.cloud), [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces), [Cloudflare](https://www.cloudflare.com/developer-platform/solutions/s3-compatible-object-storage), etc..), `endpoint` will need to be provided. Some providers also need to have `forcePathStyle` set to true in the configuration. + +Below is an example on how to connect to MinIO: + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "region": "us-east-1", + "bucket": "my-bucket", + "endpoint": "https://play.min.io", + "forcePathStyle": true, + "accessKeyId": "abc1234", + "secretAccessKey": "4321cba" + } +} +``` + +| **Property** | **Description** | +| ------------------- | --------------------------------------------------------------------------------------------------------- | +| **region** | The id of the S3 compatible storage region to use | +| **bucket** | The name of the S3 compatible storage bucket to use | +| **forcePathStyle** | Changes the way artifacts are uploaded. Usually used for S3 compatible providers (MinIO, LocalStack, etc) | +| **endpoint** | The custom endpoint to upload artifacts to. If endpoint is not defined, the default AWS endpoint is used | +| **accessKeyId** | AWS Access Key ID (optional if `AWS_ACCESS_KEY_ID` is set in the environment) | +| **secretAccessKey** | AWS secret access key (optional if `AWS_SECRET_ACCESS_KEY` is set in the environment) |