Merge pull request backstage#4663 from backstage/mob/scaffolder-beta2

scaffolder-backend: initial support for beta2 templates, and refactored form schema creation

.changeset/brown-hotels-study.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Move logic for constructing the template form to the backend, using a new `./parameter-schema` endpoint that returns the form schema for a given template.

.changeset/fluffy-elephants-suffer.md

@@ -0,0 +1,7 @@
+---
+'@backstage/catalog-model': patch
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Add version `backstage.io/v1beta2` schema for Template entities.

.changeset/slimy-singers-return.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Fixed file path resolution for templates with a file location

packages/catalog-model/src/kinds/TemplateEntityV1beta2.test.ts

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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 {
+  TemplateEntityV1beta2,
+  templateEntityV1beta2Validator as validator,
+} from './TemplateEntityV1beta2';
+
+describe('templateEntityV1beta2Validator', () => {
+  let entity: TemplateEntityV1beta2;
+
+  beforeEach(() => {
+    entity = {
+      apiVersion: 'backstage.io/v1beta2',
+      kind: 'Template',
+      metadata: {
+        name: 'test',
+      },
+      spec: {
+        type: 'website',
+        parameters: {
+          required: ['storePath', 'owner'],
+          properties: {
+            owner: {
+              type: 'string',
+              title: 'Owner',
+              description: 'Who is going to own this component',
+            },
+            storePath: {
+              type: 'string',
+              title: 'Store path',
+              description: 'GitHub store path in org/repo format',
+            },
+          },
+        },
+        steps: [
+          {
+            id: 'fetch',
+            name: 'Fetch',
+            action: 'fetch:plan',
+            parameters: {
+              url: './template',
+            },
+          },
+        ],
+        output: {
+          fetchUrl: '{{ steps.fetch.output.targetUrl }}',
+        },
+      },
+    };
+  });
+
+  it('happy path: accepts valid data', async () => {
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('ignores unknown apiVersion', async () => {
+    (entity as any).apiVersion = 'backstage.io/v1beta0';
+    await expect(validator.check(entity)).resolves.toBe(false);
+  });
+
+  it('ignores unknown kind', async () => {
+    (entity as any).kind = 'Wizard';
+    await expect(validator.check(entity)).resolves.toBe(false);
+  });
+
+  it('rejects missing type', async () => {
+    delete (entity as any).spec.type;
+    await expect(validator.check(entity)).rejects.toThrow(/type/);
+  });
+
+  it('accepts any other type', async () => {
+    (entity as any).spec.type = 'hallo';
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('accepts missing parameters', async () => {
+    delete (entity as any).spec.parameters;
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('accepts missing outputs', async () => {
+    delete (entity as any).spec.outputs;
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('rejects empty type', async () => {
+    (entity as any).spec.type = '';
+    await expect(validator.check(entity)).rejects.toThrow(/type/);
+  });
+
+  it('rejects missing steps', async () => {
+    delete (entity as any).spec.steps;
+    await expect(validator.check(entity)).rejects.toThrow(/steps/);
+  });
+
+  it('accepts step with missing id', async () => {
+    delete (entity as any).spec.steps[0].id;
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('accepts step with missing name', async () => {
+    delete (entity as any).spec.steps[0].name;
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('rejects step with missing action', async () => {
+    delete (entity as any).spec.steps[0].action;
+    await expect(validator.check(entity)).rejects.toThrow(/action/);
+  });
+});

packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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 { Entity, EntityMeta } from '../entity/Entity';
+import schema from '../schema/kinds/Template.v1beta2.schema.json';
+import entitySchema from '../schema/Entity.schema.json';
+import entityMetaSchema from '../schema/EntityMeta.schema.json';
+import commonSchema from '../schema/shared/common.schema.json';
+import { ajvCompiledJsonSchemaValidator } from './util';
+import { JsonObject } from '@backstage/config';
+
+const API_VERSION = ['backstage.io/v1beta2'] as const;
+const KIND = 'Template' as const;
+
+export interface TemplateEntityV1beta2 extends Entity {
+  apiVersion: typeof API_VERSION[number];
+  kind: typeof KIND;
+  metadata: EntityMeta & {
+    title?: string;
+  };
+  spec: {
+    type: string;
+    parameters?: JsonObject | JsonObject[];
+    steps: Array<{
+      id?: string;
+      name?: string;
+      action: string;
+      parameters?: JsonObject;
+    }>;
+    output?: { [name: string]: string };
+  };
+}
+
+export const templateEntityV1beta2Validator = ajvCompiledJsonSchemaValidator(
+  KIND,
+  API_VERSION,
+  schema,
+  [commonSchema, entityMetaSchema, entitySchema],
+);

packages/catalog-model/src/kinds/index.ts

@@ -57,6 +57,8 @@ export type {
   TemplateEntityV1alpha1 as TemplateEntity,
   TemplateEntityV1alpha1,
 } from './TemplateEntityV1alpha1';
+export { templateEntityV1beta2Validator } from './TemplateEntityV1beta2';
+export type { TemplateEntityV1beta2 } from './TemplateEntityV1beta2';
 export { userEntityV1alpha1Validator } from './UserEntityV1alpha1';
 export type {
   UserEntityV1alpha1 as UserEntity,

packages/catalog-model/src/schema/kinds/Template.v1beta2.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "TemplateV1beta1",
+  "description": "A Template describes a scaffolding task for use with the Scaffolder. It describes the required parameters as well as a series of steps that will be taken to execute the scaffolding task.",
+  "examples": [
+    {
+      "apiVersion": "backstage.io/v1beta1",
+      "kind": "Template",
+      "metadata": {
+        "name": "react-ssr-template",
+        "title": "React SSR Template",
+        "description": "Next.js application skeleton for creating isomorphic web applications.",
+        "tags": ["recommended", "react"]
+      },
+      "spec": {
+        "owner": "artist-relations-team",
+        "type": "website",
+        "parameters": {
+          "required": ["name", "description"],
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "description": "Unique name of the component"
+            },
+            "description": {
+              "title": "Description",
+              "type": "string",
+              "description": "Description of the component"
+            }
+          }
+        },
+        "steps": [
+          {
+            "id": "fetch",
+            "name": "Fetch",
+            "action": "fetch:plain",
+            "parameters": {
+              "url": "./template"
+            }
+          },
+          {
+            "id": "publish",
+            "name": "Publish to GitHub",
+            "action": "publish:github",
+            "parameters": {
+              "repoUrl": "{{ parameters.repoUrl }}"
+            }
+          }
+        ],
+        "output": {
+          "catalogInfoUrl": "{{ steps.publish.output.catalogInfoUrl }}"
+        }
+      }
+    }
+  ],
+  "allOf": [
+    {
+      "$ref": "Entity"
+    },
+    {
+      "type": "object",
+      "required": ["spec"],
+      "properties": {
+        "apiVersion": {
+          "enum": ["backstage.io/v1beta2"]
+        },
+        "kind": {
+          "enum": ["Template"]
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "description": "The nice display name for the template.",
+              "examples": ["React SSR Template"],
+              "minLength": 1
+            }
+          }
+        },
+        "spec": {
+          "type": "object",
+          "required": ["type", "steps"],
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "The type of component. This field is optional but recommended. The software catalog accepts any type value, but an organization should take great care to establish a proper taxonomy for these. Tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites.",
+              "examples": ["service", "website", "library"],
+              "minLength": 1
+            },
+            "parameters": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "description": "The JSONSchema describing the inputs for the template."
+                },
+                {
+                  "type": "array",
+                  "description": "A list of separate forms to collect parameters.",
+                  "items": {
+                    "type": "object",
+                    "description": "The JSONSchema describing the inputs for the template."
+                  }
+                }
+              ]
+            },
+            "steps": {
+              "type": "array",
+              "description": "A list of steps to execute.",
+              "items": {
+                "type": "object",
+                "description": "A description of the step to execute.",
+                "required": ["action"],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "The ID of the step, which can be used to refer to its outputs."
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "The name of the step, which will be displayed in the UI during the scaffolding process."
+                  },
+                  "action": {
+                    "type": "string",
+                    "description": "The name of the action to execute."
+                  },
+                  "parameters": {
+                    "type": "object",
+                    "description": "A templated object describing the inputs to the action."
+                  }
+                }
+              }
+            },
+            "output": {
+              "type": "object",
+              "description": "A templated object describing the outputs of the scaffolding task.",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts

@@ -45,6 +45,7 @@ import {
   SystemEntity,
   systemEntityV1alpha1Validator,
   templateEntityV1alpha1Validator,
+  templateEntityV1beta2Validator,
   UserEntity,
   userEntityV1alpha1Validator,
 } from '@backstage/catalog-model';
@@ -59,6 +60,7 @@ export class BuiltinKindsEntityProcessor implements CatalogProcessor {
     groupEntityV1alpha1Validator,
     locationEntityV1alpha1Validator,
     templateEntityV1alpha1Validator,
+    templateEntityV1beta2Validator,
     userEntityV1alpha1Validator,
     systemEntityV1alpha1Validator,
     domainEntityV1alpha1Validator,