From 5abc2fd4d648316e5ed063222599da4a86975627 Mon Sep 17 00:00:00 2001 From: Sabrina Lo Date: Wed, 30 Aug 2023 15:14:48 -0700 Subject: [PATCH] feat(catalog-backend-module-aws): add transformer to create the (Resource) entity for a cluster Signed-off-by: Sabrina Lo --- .changeset/twenty-masks-exist.md | 5 ++ .../catalog-backend-module-aws/api-report.md | 26 ++++++-- .../src/constants.ts | 28 +++++++++ .../catalog-backend-module-aws/src/index.ts | 1 + .../src/lib/defaultTransformers.ts | 60 ++++++++++++++++++ .../src/lib/index.ts | 16 +++++ .../src/processors/AwsEKSClusterProcessor.ts | 62 +++++++------------ .../src/processors/index.ts | 1 + .../src/processors/types.ts | 27 ++++++++ 9 files changed, 183 insertions(+), 43 deletions(-) create mode 100644 .changeset/twenty-masks-exist.md create mode 100644 plugins/catalog-backend-module-aws/src/constants.ts create mode 100644 plugins/catalog-backend-module-aws/src/lib/defaultTransformers.ts create mode 100644 plugins/catalog-backend-module-aws/src/lib/index.ts create mode 100644 plugins/catalog-backend-module-aws/src/processors/types.ts diff --git a/.changeset/twenty-masks-exist.md b/.changeset/twenty-masks-exist.md new file mode 100644 index 0000000000..c864f705d7 --- /dev/null +++ b/.changeset/twenty-masks-exist.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend-module-aws': minor +--- + +AwsEksClusterProcessor supports Entity callback function diff --git a/plugins/catalog-backend-module-aws/api-report.md b/plugins/catalog-backend-module-aws/api-report.md index 83b072061b..5fa59d417f 100644 --- a/plugins/catalog-backend-module-aws/api-report.md +++ b/plugins/catalog-backend-module-aws/api-report.md @@ -8,7 +8,9 @@ import { AwsCredentialsManager } from '@backstage/integration-aws-node'; import { CatalogProcessor } from '@backstage/plugin-catalog-node'; import { CatalogProcessorEmit } from '@backstage/plugin-catalog-node'; import { CatalogProcessorParser } from '@backstage/plugin-catalog-node'; +import type { Cluster } from '@aws-sdk/client-eks'; import { Config } from '@backstage/config'; +import type { Entity } from '@backstage/catalog-model'; import { EntityProvider } from '@backstage/plugin-catalog-node'; import { EntityProviderConnection } from '@backstage/plugin-catalog-node'; import { LocationSpec } from '@backstage/plugin-catalog-common'; @@ -17,6 +19,12 @@ import { PluginTaskScheduler } from '@backstage/backend-tasks'; import { TaskRunner } from '@backstage/backend-tasks'; import { UrlReader } from '@backstage/backend-common'; +// @public +export const ANNOTATION_AWS_ACCOUNT_ID: string; + +// @public +export const ANNOTATION_AWS_ARN: string; + // @public export type AWSCredentialFactory = ( awsAccountId: string, @@ -24,17 +32,21 @@ export type AWSCredentialFactory = ( // @public export class AwsEKSClusterProcessor implements CatalogProcessor { - constructor(options: { + constructor(options?: { credentialsFactory?: AWSCredentialFactory; credentialsManager?: AwsCredentialsManager; + clusterEntityTransformer?: EKSClusterEntityTransformer; }); // (undocumented) - static fromConfig(configRoot: Config): AwsEKSClusterProcessor; + static fromConfig( + configRoot: Config, + options?: { + clusterEntityTransformer?: EKSClusterEntityTransformer; + }, + ): AwsEKSClusterProcessor; // (undocumented) getProcessorName(): string; // (undocumented) - normalizeName(name: string): string; - // (undocumented) readLocation( location: LocationSpec, _optional: boolean, @@ -93,4 +105,10 @@ export class AwsS3EntityProvider implements EntityProvider { // (undocumented) refresh(logger: Logger): Promise; } + +// @public +export type EKSClusterEntityTransformer = ( + cluster: Cluster, + accountId: string, +) => Promise; ``` diff --git a/plugins/catalog-backend-module-aws/src/constants.ts b/plugins/catalog-backend-module-aws/src/constants.ts new file mode 100644 index 0000000000..7756031ed7 --- /dev/null +++ b/plugins/catalog-backend-module-aws/src/constants.ts @@ -0,0 +1,28 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Annotation for specifying AWS account id + * + * @public + */ +export const ANNOTATION_AWS_ACCOUNT_ID: string = 'amazonaws.com/account-id'; +/** + * Annotation for specifying AWS arn + * + * @public + */ +export const ANNOTATION_AWS_ARN: string = 'amazonaws.com/arn'; diff --git a/plugins/catalog-backend-module-aws/src/index.ts b/plugins/catalog-backend-module-aws/src/index.ts index 212308edaa..72ddc6386a 100644 --- a/plugins/catalog-backend-module-aws/src/index.ts +++ b/plugins/catalog-backend-module-aws/src/index.ts @@ -23,3 +23,4 @@ export * from './processors'; export * from './providers'; export * from './types'; +export * from './constants'; diff --git a/plugins/catalog-backend-module-aws/src/lib/defaultTransformers.ts b/plugins/catalog-backend-module-aws/src/lib/defaultTransformers.ts new file mode 100644 index 0000000000..9d1fef8ca8 --- /dev/null +++ b/plugins/catalog-backend-module-aws/src/lib/defaultTransformers.ts @@ -0,0 +1,60 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import type { EKSClusterEntityTransformer } from '../processors/types'; +import { type Cluster } from '@aws-sdk/client-eks'; +import { + ANNOTATION_KUBERNETES_API_SERVER, + ANNOTATION_KUBERNETES_API_SERVER_CA, + ANNOTATION_KUBERNETES_AUTH_PROVIDER, +} from '@backstage/plugin-kubernetes-common'; +import { ANNOTATION_AWS_ACCOUNT_ID, ANNOTATION_AWS_ARN } from '../constants'; + +/** + * Default transformer for EKS Cluster to Resource Entity + * @public + */ +export const defaultEKSClusterTransformer: EKSClusterEntityTransformer = async ( + cluster: Cluster, + accountId: string, +) => { + const { arn, endpoint, certificateAuthority, name } = cluster; + return { + apiVersion: 'backstage.io/v1alpha1', + kind: 'Resource', + metadata: { + annotations: { + [ANNOTATION_AWS_ACCOUNT_ID]: accountId, + [ANNOTATION_AWS_ARN]: arn || '', + [ANNOTATION_KUBERNETES_API_SERVER]: endpoint || '', + [ANNOTATION_KUBERNETES_API_SERVER_CA]: certificateAuthority?.data || '', + [ANNOTATION_KUBERNETES_AUTH_PROVIDER]: 'aws', + }, + name: normalizeName(name as string), + namespace: 'default', + }, + spec: { + type: 'kubernetes-cluster', + owner: 'unknown', + }, + }; +}; + +function normalizeName(name: string): string { + return name + .trim() + .toLocaleLowerCase('en-US') + .replace(/[^a-zA-Z0-9\-]/g, '-'); +} diff --git a/plugins/catalog-backend-module-aws/src/lib/index.ts b/plugins/catalog-backend-module-aws/src/lib/index.ts new file mode 100644 index 0000000000..1dc70c98f3 --- /dev/null +++ b/plugins/catalog-backend-module-aws/src/lib/index.ts @@ -0,0 +1,16 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +export * from './defaultTransformers'; diff --git a/plugins/catalog-backend-module-aws/src/processors/AwsEKSClusterProcessor.ts b/plugins/catalog-backend-module-aws/src/processors/AwsEKSClusterProcessor.ts index 4a19b9eb7f..c5d48a7690 100644 --- a/plugins/catalog-backend-module-aws/src/processors/AwsEKSClusterProcessor.ts +++ b/plugins/catalog-backend-module-aws/src/processors/AwsEKSClusterProcessor.ts @@ -19,11 +19,6 @@ import { CatalogProcessorEmit, } from '@backstage/plugin-catalog-node'; import { LocationSpec } from '@backstage/plugin-catalog-common'; -import { - ANNOTATION_KUBERNETES_API_SERVER, - ANNOTATION_KUBERNETES_API_SERVER_CA, - ANNOTATION_KUBERNETES_AUTH_PROVIDER, -} from '@backstage/plugin-kubernetes-common'; import { EKS } from '@aws-sdk/client-eks'; import { AWSCredentialFactory } from '../types'; import { AwsCredentialIdentity, Provider } from '@aws-sdk/types'; @@ -33,8 +28,8 @@ import { } from '@backstage/integration-aws-node'; import { Config } from '@backstage/config'; -const ACCOUNTID_ANNOTATION: string = 'amazonaws.com/account-id'; -const ARN_ANNOTATION: string = 'amazonaws.com/arn'; +import type { EKSClusterEntityTransformer } from './types'; +import { defaultEKSClusterTransformer } from '../lib'; /** * A processor for automatic discovery of resources from EKS clusters. Handles the @@ -46,34 +41,39 @@ const ARN_ANNOTATION: string = 'amazonaws.com/arn'; export class AwsEKSClusterProcessor implements CatalogProcessor { private credentialsFactory?: AWSCredentialFactory; private credentialsManager?: AwsCredentialsManager; + private readonly clusterEntityTransformer: EKSClusterEntityTransformer; - static fromConfig(configRoot: Config): AwsEKSClusterProcessor { + static fromConfig( + configRoot: Config, + options?: { + clusterEntityTransformer?: EKSClusterEntityTransformer; + }, + ): AwsEKSClusterProcessor { const awsCredentaislManager = DefaultAwsCredentialsManager.fromConfig(configRoot); return new AwsEKSClusterProcessor({ credentialsManager: awsCredentaislManager, + ...options, }); } - constructor(options: { + constructor(options?: { credentialsFactory?: AWSCredentialFactory; credentialsManager?: AwsCredentialsManager; + clusterEntityTransformer?: EKSClusterEntityTransformer; }) { - this.credentialsFactory = options.credentialsFactory; - this.credentialsManager = options.credentialsManager; + this.credentialsFactory = options?.credentialsFactory; + this.credentialsManager = options?.credentialsManager; + + // If the callback function is not passed in, then default to the one upstream is using + this.clusterEntityTransformer = + options?.clusterEntityTransformer || defaultEKSClusterTransformer; } getProcessorName(): string { return 'aws-eks'; } - normalizeName(name: string): string { - return name - .trim() - .toLocaleLowerCase('en-US') - .replace(/[^a-zA-Z0-9\-]/g, '-'); - } - async readLocation( location: LocationSpec, _optional: boolean, @@ -119,27 +119,11 @@ export class AwsEKSClusterProcessor implements CatalogProcessor { .map(async describedClusterPromise => { const describedCluster = await describedClusterPromise; if (describedCluster.cluster) { - const entity = { - apiVersion: 'backstage.io/v1alpha1', - kind: 'Resource', - metadata: { - annotations: { - [ACCOUNTID_ANNOTATION]: accountId, - [ARN_ANNOTATION]: describedCluster.cluster.arn || '', - [ANNOTATION_KUBERNETES_API_SERVER]: - describedCluster.cluster.endpoint || '', - [ANNOTATION_KUBERNETES_API_SERVER_CA]: - describedCluster.cluster.certificateAuthority?.data || '', - [ANNOTATION_KUBERNETES_AUTH_PROVIDER]: 'aws', - }, - name: this.normalizeName(describedCluster.cluster.name as string), - namespace: 'default', - }, - spec: { - type: 'kubernetes-cluster', - owner: 'unknown', - }, - }; + const entity = await this.clusterEntityTransformer( + describedCluster.cluster, + accountId, + ); + emit({ type: 'entity', entity, diff --git a/plugins/catalog-backend-module-aws/src/processors/index.ts b/plugins/catalog-backend-module-aws/src/processors/index.ts index 63b8a47139..e5bf93ceaf 100644 --- a/plugins/catalog-backend-module-aws/src/processors/index.ts +++ b/plugins/catalog-backend-module-aws/src/processors/index.ts @@ -17,3 +17,4 @@ export { AwsEKSClusterProcessor } from './AwsEKSClusterProcessor'; export { AwsOrganizationCloudAccountProcessor } from './AwsOrganizationCloudAccountProcessor'; export { AwsS3DiscoveryProcessor } from './AwsS3DiscoveryProcessor'; +export * from './types'; diff --git a/plugins/catalog-backend-module-aws/src/processors/types.ts b/plugins/catalog-backend-module-aws/src/processors/types.ts new file mode 100644 index 0000000000..f8c3b05efe --- /dev/null +++ b/plugins/catalog-backend-module-aws/src/processors/types.ts @@ -0,0 +1,27 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import type { Cluster } from '@aws-sdk/client-eks'; +import type { Entity } from '@backstage/catalog-model'; + +/** + * Options for the eks cluster entity callback function + * + * @public + */ +export type EKSClusterEntityTransformer = ( + cluster: Cluster, + accountId: string, +) => Promise;