From 24bcdd0829cb7aa27203008737d3df3f58eaa983 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Wed, 9 Dec 2020 18:58:12 +0100 Subject: [PATCH] techdocs: Use googleGcs for publisher type instead of google_gcs --- .changeset/six-mugs-camp.md | 2 +- app-config.yaml | 2 +- docs/features/techdocs/configuration.md | 8 +-- docs/features/techdocs/using-cloud-storage.md | 20 ++++---- .../src/stages/publish/googleStorage.test.ts | 4 +- .../src/stages/publish/googleStorage.ts | 12 ++--- .../src/stages/publish/publish.test.ts | 4 +- .../src/stages/publish/publish.ts | 2 +- .../src/stages/publish/types.ts | 2 +- .../techdocs-backend/src/service/router.ts | 4 +- plugins/techdocs/package.json | 50 ++++++++++++------- 11 files changed, 61 insertions(+), 49 deletions(-) diff --git a/.changeset/six-mugs-camp.md b/.changeset/six-mugs-camp.md index a27a25a15b..373edd340a 100644 --- a/.changeset/six-mugs-camp.md +++ b/.changeset/six-mugs-camp.md @@ -17,4 +17,4 @@ instead of An instance of `publisher` can either be a local filesystem publisher or a Google Cloud Storage publisher. Read more about the configs here https://backstage.io/docs/features/techdocs/configuration -(You will also have to update `techdocs.storage.type` to `local` or `google_gcs`. And `techdocs.builder` to either `local` or `external`.) +(You will also have to update `techdocs.storage.type` to `local` or `googleGcs`. And `techdocs.builder` to either `local` or `external`.) diff --git a/app-config.yaml b/app-config.yaml index 81538d8f61..3a21faf418 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -76,7 +76,7 @@ techdocs: generators: techdocs: 'docker' # Alternatives - 'local' publisher: - type: 'local' # Alternatives - 'google_gcs'. Read documentation for using alternatives. + type: 'local' # Alternatives - 'googleGcs'. Read documentation for using alternatives. sentry: organization: my-company diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index f3be54a4de..eac6799317 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -50,16 +50,16 @@ techdocs: publisher: - # techdocs.publisher.type can be - 'local' or 'google_gcs' (aws_s3, azure_storage, etc. to be available as well). + # techdocs.publisher.type can be - 'local' or 'googleGcs' (awsS3, azureStorage, etc. to be available as well). # When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files. - # When set to 'google_gcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files. + # When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files. type: 'local' - # Required when techdocs.publisher.type is set to 'google_gcs'. Skip otherwise. + # Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise. - google: + googleGcs: # An API key is required to write to a storage bucket. pathToKey: '/path/to/google_application_credentials.json', diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index 07b2982e18..12e3acd1bf 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -22,24 +22,24 @@ for the latest instructions on the following steps involving GCP. **1. Set `techdocs.publisher.type` config in your `app-config.yaml`** -Set `techdocs.publisher.type` to `'google_gcs'`. +Set `techdocs.publisher.type` to `'googleGcs'`. ```yaml techdocs: publisher: - type: 'google_gcs' + type: 'googleGcs' ``` **2. GCP (Google Cloud Platform) Project** Create or choose a dedicated GCP project. Set -`techdocs.publisher.google.projectId` to the project ID. +`techdocs.publisher.googleGcs.projectId` to the project ID. ```yaml techdocs: publisher: - type: 'google_gcs' - google: + type: 'googleGcs' + googleGcs: projectId: 'gcp-project-id ``` @@ -58,13 +58,13 @@ IAM & Admin console), and create a new key. Use JSON format for the key. A `.json` file will be downloaded. This is the secret key TechDocs will use to make API calls. Make it available in your Backstage server and/or your local development server and set it in the app config -`techdocs.publisher.google.pathToKey`. +`techdocs.publisher.googleGcs.pathToKey`. ```yaml techdocs: publisher: - type: 'google_gcs' - google: + type: 'googleGcs' + googleGcs: projectId: 'gcp-project-id' pathToKey: '/path/to/google_application_credentials.json' ``` @@ -80,8 +80,8 @@ Set the name of the bucket to `techdocs.publisher ```yaml techdocs: publisher: - type: 'google_gcs' - google: + type: 'googleGcs' + googleGcs: projectId: 'gcp-project-id' pathToKey: '/path/to/google_application_credentials.json' bucketName: 'name-of-techdocs-storage-bucket' diff --git a/packages/techdocs-common/src/stages/publish/googleStorage.test.ts b/packages/techdocs-common/src/stages/publish/googleStorage.test.ts index e618f7edc7..fa7bddc648 100644 --- a/packages/techdocs-common/src/stages/publish/googleStorage.test.ts +++ b/packages/techdocs-common/src/stages/publish/googleStorage.test.ts @@ -49,8 +49,8 @@ beforeEach(() => { techdocs: { requestUrl: 'http://localhost:7000', publisher: { - type: 'google_gcs', - google: { + type: 'googleGcs', + googleGcs: { pathToKey: '/path/to/google-application-credentials.json', projectId: 'gcp-project-id', bucketName: 'bucketName', diff --git a/packages/techdocs-common/src/stages/publish/googleStorage.ts b/packages/techdocs-common/src/stages/publish/googleStorage.ts index 3449a7e6e3..c9b4ffd3db 100644 --- a/packages/techdocs-common/src/stages/publish/googleStorage.ts +++ b/packages/techdocs-common/src/stages/publish/googleStorage.ts @@ -29,13 +29,13 @@ export class GoogleGCSPublish implements PublisherBase { let projectId = ''; let bucketName = ''; try { - pathToKey = config.getString('techdocs.publisher.google.pathToKey'); - projectId = config.getString('techdocs.publisher.google.projectId'); - bucketName = config.getString('techdocs.publisher.google.bucketName'); + pathToKey = config.getString('techdocs.publisher.googleGcs.pathToKey'); + projectId = config.getString('techdocs.publisher.googleGcs.projectId'); + bucketName = config.getString('techdocs.publisher.googleGcs.bucketName'); } catch (error) { throw new Error( - "Since techdocs.publisher.type is set to 'google_gcs' in your app config, " + - 'pathToKey, projectId and bucketName are required in techdocs.publisher.google ' + + "Since techdocs.publisher.type is set to 'googleGcs' in your app config, " + + 'pathToKey, projectId and bucketName are required in techdocs.publisher.googleGcs ' + 'required to authenticate with Google Cloud Storage.', ); } @@ -59,7 +59,7 @@ export class GoogleGCSPublish implements PublisherBase { logger.error( `Could not retrieve metadata about the GCS bucket ${bucketName} in the GCP project ${projectId}. ` + 'Make sure the GCP project and the bucket exists and the access key located at the path ' + - "techdocs.publisher.google.pathToKey defined in app config has the role 'Storage Object Creator'. " + + "techdocs.publisher.googleGcs.pathToKey defined in app config has the role 'Storage Object Creator'. " + 'Refer to https://backstage.io/docs/features/techdocs/using-cloud-storage', ); throw new Error(`from GCS client library: ${reason.message}`); diff --git a/packages/techdocs-common/src/stages/publish/publish.test.ts b/packages/techdocs-common/src/stages/publish/publish.test.ts index 002719997b..16e2225e46 100644 --- a/packages/techdocs-common/src/stages/publish/publish.test.ts +++ b/packages/techdocs-common/src/stages/publish/publish.test.ts @@ -77,8 +77,8 @@ describe('Publisher', () => { techdocs: { requestUrl: 'http://localhost:7000', publisher: { - type: 'google_gcs', - google: { + type: 'googleGcs', + googleGcs: { pathToKey: '/path/to/google-application-credentials.json', projectId: 'gcp-project-id', bucketName: 'bucketName', diff --git a/packages/techdocs-common/src/stages/publish/publish.ts b/packages/techdocs-common/src/stages/publish/publish.ts index c91ebe8bb3..04a9d89996 100644 --- a/packages/techdocs-common/src/stages/publish/publish.ts +++ b/packages/techdocs-common/src/stages/publish/publish.ts @@ -36,7 +36,7 @@ export class Publisher { ) ?? 'local') as PublisherType; switch (publisherType) { - case 'google_gcs': + case 'googleGcs': logger.info('Creating Google Storage Bucket publisher for TechDocs'); return GoogleGCSPublish.fromConfig(config, logger); case 'local': diff --git a/packages/techdocs-common/src/stages/publish/types.ts b/packages/techdocs-common/src/stages/publish/types.ts index fae61241b2..6722f6c221 100644 --- a/packages/techdocs-common/src/stages/publish/types.ts +++ b/packages/techdocs-common/src/stages/publish/types.ts @@ -19,7 +19,7 @@ import express from 'express'; /** * Key for all the different types of TechDocs publishers that are supported. */ -export type PublisherType = 'local' | 'google_gcs'; +export type PublisherType = 'local' | 'googleGcs'; export type PublishRequest = { entity: Entity; diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index a13f25790a..a64f581a1e 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -115,7 +115,7 @@ export async function createRouter({ } catch (err) { throw new Error( 'Unable to get techdocs.publisher.type in your app config. Set it to either ' + - "'local', 'google_gcs' or other support storage providers. Read more here " + + "'local', 'googleGcs' or other support storage providers. Read more here " + 'https://backstage.io/docs/features/techdocs/architecture', ); } @@ -136,7 +136,7 @@ export async function createRouter({ if (!(await docsBuilder.docsUpToDate())) { await docsBuilder.build(); } - } else if (publisherType === 'google_gcs') { + } else if (publisherType === 'googleGcs') { // This block should be valid for all external storage implementations. So no need to duplicate in future, // add the publisher type in the list here. if (!(await publisher.hasDocsBeenGenerated(entity))) { diff --git a/plugins/techdocs/package.json b/plugins/techdocs/package.json index 9c6e010f63..da4c239f36 100644 --- a/plugins/techdocs/package.json +++ b/plugins/techdocs/package.json @@ -85,32 +85,44 @@ "visibility": "frontend" }, "publisher": { - "type": "object", - "properties": { - "type": { - "type": "string", - "visibility": "backend" - }, - "google": { + "oneOf": [ + { "type": "object", "properties": { - "pathToKey": { + "type": { "type": "string", - "visibility": "secret" + "const": "local", + "visibility": "backend" + } + } + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "googleGcs", + "visibility": "backend" }, - "projectId": { - "type": "string", - "visibility": "secret" - }, - "bucketName": { - "type": "string", - "visibility": "secret" + "googleGcs": { + "type": "object", + "properties": { + "pathToKey": { + "type": "string", + "visibility": "secret" + }, + "projectId": { + "type": "string", + "visibility": "secret" + }, + "bucketName": { + "type": "string", + "visibility": "secret" + } + } } } } - }, - "required": [ - "type" ] } },