diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index 7a0a4dbbbf..8c1a024f33 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -54,16 +54,15 @@ techdocs: # Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise. googleGcs: - # An API key is required to write to a storage bucket. + # (Required) Cloud Storage Bucket Name + bucketName: 'techdocs-storage' + + # (Optional) An API key is required to write to a storage bucket. + # If missing, GOOGLE_APPLICATION_CREDENTIALS environment variable will be used. + # https://cloud.google.com/docs/authentication/production credentials: $file: '/path/to/google_application_credentials.json' - # Your GCP Project ID where the Cloud Storage Bucket is hosted. - projectId: 'gcp-project-id' - - # Cloud Storage Bucket Name - bucketName: 'techdocs-storage' - # Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise. awsS3: diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index c05346ca4a..42e8d83f29 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -30,20 +30,34 @@ techdocs: type: 'googleGcs' ``` -**2. GCP (Google Cloud Platform) Project** +**2. GCS Bucket** -Create or choose a dedicated GCP project. Set -`techdocs.publisher.googleGcs.projectId` to the project ID. +Create a dedicated Google Cloud Storage bucket for TechDocs sites. +techdocs-backend will publish documentation to this bucket. TechDocs will fetch +files from here to serve documentation in Backstage. Note that the bucket names +are globally unique. + +Set the name of the bucket to `techdocs.publisher.googleGcs.bucketName`. ```yaml techdocs: publisher: type: 'googleGcs' - googleGcs: - projectId: 'gcp-project-id' + googleGcs: + bucketName: 'name-of-techdocs-storage-bucket' ``` -**3. Service account API key** +**3a. (Recommended) Authentication using environment variable** + +The GCS Node.js client will automatically use the environment variable +`GOOGLE_APPLICATION_CREDENTIALS` to authenticate with Google Cloud. It might +already be set in Compute Engine, Google Kubernetes Engine, etc. Read +https://cloud.google.com/docs/authentication/production for more details. + +**3b. Authentication using app-config.yaml** + +If you do not prefer (3a) and optionally like to use a service account, you can +follow these steps. Create a new Service Account and a key associated with it. In roles of the service account, use "Storage Admin". @@ -65,34 +79,29 @@ techdocs: publisher: type: 'googleGcs' googleGcs: - projectId: 'gcp-project-id' + bucketName: 'name-of-techdocs-storage-bucket' credentials: $file: '/path/to/google_application_credentials.json' ``` -**4. GCS Bucket** - -Create a dedicated bucket for TechDocs sites. techdocs-backend will publish -documentation to this bucket. TechDocs will fetch files from here to serve -documentation in Backstage. - -Set the name of the bucket to `techdocs.publisher.googleGcs.bucketName`. +Note: If you are finding it difficult to make the file +`google_application_credentials.json` available on a server, you could use the +file's content and set as an environment variable. And then use ```yaml techdocs: publisher: type: 'googleGcs' googleGcs: - projectId: 'gcp-project-id' - credentials: - $file: '/path/to/google_application_credentials.json' bucketName: 'name-of-techdocs-storage-bucket' + credentials: + $env: TECHDOCS_GCS_CREDENTIALS ``` -**5. That's it!** +**4. That's it!** Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to -store the static generated documentation files. +store and read the static generated documentation files. ## Configuring AWS S3 Bucket with TechDocs @@ -113,9 +122,8 @@ techdocs: **2. AWS Policies** AWS Policies lets you **control access** to Amazon Web Services (AWS) products -and resources. -Here we will use a user policy **and** a bucket policy to show you the different -possibilities you have but you can use only one. +and resources. Here we will use a user policy **and** a bucket policy to show +you the different possibilities you have but you can use only one. AWS S3 @@ -135,9 +143,9 @@ and the **user** policy. **2.1.1 Create an Admin user** (if you don't have one yet) Create an **administrator user** account `ADMIN_USER` and grant it administrator -privileges by attaching a user policy giving the account **full access**. -Note down the Admin User credentials and IAM User Sign-In URL as you will need -to use this information in the next step. +privileges by attaching a user policy giving the account **full access**. Note +down the Admin User credentials and IAM User Sign-In URL as you will need to use +this information in the next step. **2.1.2 Create an AWS S3 Bucket** @@ -171,9 +179,9 @@ In the IAM console, do the following: **2.2 Attach policies** -Remember that you can use Bucket policy **or** User policy. -Just make sure that you grant all the permissions to the TechDocs user: -`3:PutObject`, `s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`. +Remember that you can use Bucket policy **or** User policy. Just make sure that +you grant all the permissions to the TechDocs user: `3:PutObject`, +`s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`. **2.2.1 Create the bucket policy** @@ -209,9 +217,9 @@ section: - The first statement grants **TechDocs User** the bucket operation permissions `s3:GetBucketLocation` and `s3:ListBucket` which are permissions required by the console. -- The second statement grants the `s3:GetObject` permission. - (**NOTE :** if you do not use the user policy defined below you must also add - the `s3:PutObject` permission to allow the TechDocs user to add objects.) +- The second statement grants the `s3:GetObject` permission. (**NOTE :** if you + do not use the user policy defined below you must also add the `s3:PutObject` + permission to allow the TechDocs user to add objects.) **2.2.2 Create the user policy**