feat: action create backend, organization, project, workspace

.changeset/slick-ghosts-retire.md

@@ -0,0 +1,5 @@
+---
+'backend': patch
+---
+
+add package @kusionstack/plugin-scaffolder-backend-module-kusion.

.changeset/tricky-files-smash.md

@@ -0,0 +1,5 @@
+---
+'@kusionstack/plugin-scaffolder-backend-module-kusion': minor
+---
+
+add create action for backend, organization, project, and workspace.

app-config.yaml

@@ -94,6 +94,11 @@ catalog:
       rules:
         - allow: [User, Group]
 
+    - type: file
+      target: ../../examples/template/scaffolder.yaml
+      rules:
+        - allow: [Template]
+
     ## Uncomment these lines to add more example data
     # - type: url
     #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml
@@ -111,3 +116,7 @@ kubernetes:
 permission:
   # setting this to `false` will disable permissions
   enabled: true
+
+# kusion
+kusion:
+  baseUrl: ${KUSION_BASE_URL}

examples/template/scaffolder.yaml

@@ -0,0 +1,65 @@
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: create-kusion-backend
+  title: Create Kusion Backend
+  description: Template to create a new Kusion Backend.
+spec:
+  owner: KusionStack
+  type: service
+
+  parameters:
+    - title: Backend Information
+      required:
+        - name
+        - backendType
+      properties:
+        name:
+          title: Backend Name
+          type: string
+          description: The name of the backend to create.
+          pattern: ^[a-zA-Z0-9_-]+$
+
+        description:
+          title: Backend Description
+          type: string
+          description: A description for the backend.
+        backendType:
+          title: Backend Type
+          type: string
+          description: The type of backend (e.g., local, s3, etc).
+          enum:
+            - local
+            - oss
+            - s3
+            - google
+        markdown:
+          type: 'null' # Needs to be quoted
+          description: |
+            ### ❗ **Important**: Please fill in the backend configs according to the backend type.
+            * [Kusion Backend concepts](https://www.kusionstack.io/docs/concepts/backend/overview)
+        backendConfigs:
+          title: Backend Configs
+          type: object
+          additionalProperties:
+            type: string
+          description: Key-value pairs for backend configuration.
+
+  steps:
+    - id: createBackend
+      name: Create Backend
+      action: kusion:backend:create
+      input:
+        name: ${{ parameters.name }}
+        description: ${{ parameters.description }}
+        backendConfig:
+          type: ${{ parameters.backendType }}
+          configs: ${{ parameters.backendConfigs }}
+
+  output:
+    text:
+      - title: Information
+        content: |
+          * success: ${{ steps.createBackend.output.success }}
+          * message: ${{ steps.createBackend.output.message }}
+          * data: ${{ steps.createBackend.output.data }}

package.json

@@ -9,6 +9,8 @@
     "dev": "yarn workspaces foreach -A --include backend --include app --parallel -v -i run start",
     "start": "yarn workspace app start",
     "start-backend": "yarn workspace backend start",
+    "build:api-reports": "yarn build:api-reports:only --tsc",
+    "build:api-reports:only": "LANG=en_US.UTF-8 NODE_OPTIONS=--max-old-space-size=8192 backstage-repo-tools api-reports --sql-reports --allow-warnings 'plugins/*' -o ae-undocumented,ae-wrong-input-file-type --validate-release-tags",
     "build:backend": "yarn workspace backend build",
     "build:all": "backstage-cli repo build --all",
     "build-image": "yarn workspace backend build-image",
@@ -33,6 +35,7 @@
   "devDependencies": {
     "@backstage/cli": "^0.29.0",
     "@backstage/e2e-test-utils": "^0.1.1",
+    "@backstage/repo-tools": "^0.13.2",
     "@changesets/cli": "^2.29.4",
     "@octokit/rest": "^21.1.1",
     "@playwright/test": "^1.32.3",

packages/backend/package.json

@@ -39,6 +39,7 @@
     "@backstage/plugin-search-backend-module-techdocs": "^0.3.2",
     "@backstage/plugin-search-backend-node": "^1.3.5",
     "@backstage/plugin-techdocs-backend": "^1.11.2",
+    "@kusionstack/plugin-scaffolder-backend-module-kusion": "^0.0.0",
     "app": "link:../app",
     "better-sqlite3": "^9.0.0",
     "node-gyp": "^10.0.0",

packages/backend/src/index.ts

@@ -51,4 +51,7 @@ backend.add(import('@backstage/plugin-search-backend-module-techdocs'));
 // kubernetes
 backend.add(import('@backstage/plugin-kubernetes-backend'));
 
+// kusion
+backend.add(import('@kusionstack/plugin-scaffolder-backend-module-kusion'));
+
 backend.start();

plugins/scaffolder-backend-module-kusion/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/scaffolder-backend-module-kusion/README.md

@@ -0,0 +1,85 @@
+# Backstage Scaffolder Backend Module for Kusion
+
+## Overview
+
+This plugin integrates [KusionStack](https://github.com/KusionStack/kusion) with Backstage's scaffolder backend, enabling you to create and manage Kusion backends directly from Backstage templates.
+
+---
+
+## Prerequisites
+
+- A running [Kusion Server](https://github.com/KusionStack/kusion)
+- A Backstage instance (see [Backstage documentation](https://backstage.io/docs/getting-started/))
+
+---
+
+## Installation
+
+From your Backstage root directory, install the plugin:
+
+```bash
+yarn add --cwd packages/backend @kusionstack/plugin-scaffolder-backend-module-kusion
+```
+
+---
+
+## Configuration
+
+Add the following configuration to your `app-config.yaml` to specify the Kusion server endpoint:
+
+```yaml
+backend:
+  kusion:
+    baseUrl: 'http://localhost:3000' # Replace with your Kusion server URL
+```
+
+---
+
+## Backend Integration
+
+Import and register the plugin in your Backstage backend:
+
+Edit `packages/backend/src/index.ts`:
+
+```typescript
+// Import and register the Kusion scaffolder backend module
+backend.add(import('@kusionstack/plugin-scaffolder-backend-module-kusion'));
+```
+
+---
+
+## Usage Example
+
+### Kusion Backend Creation Template.
+
+`kusion:backend:create`
+
+```yaml
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: create-kusion-backend
+  title: Create Kusion Backend
+  description: Template to create a new Kusion Backend.
+spec:
+  owner: KusionStack
+  type: service
+  steps:
+    - id: createBackend
+      name: Create Backend
+      action: kusion:backend:create
+      input:
+        name: ${{ parameters.name }}
+        description: ${{ parameters.description }}
+        backendConfig:
+          type: ${{ parameters.backendType }}
+          configs: ${{ parameters.backendConfigs }}
+
+  output:
+    text:
+      - title: Information
+        content: |
+          * success: ${{ steps.createBackend.output.success }}
+          * message: ${{ steps.createBackend.output.message }}
+          * data: ${{ steps.createBackend.output.data }}
+```

plugins/scaffolder-backend-module-kusion/catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-plugin-scaffolder-backend-module-kusion
+  title: '@kusionstack/plugin-scaffolder-backend-module-kusion'
+  description: The kusion backend module for the scaffolder plugin provide by KusionStack team
+spec:
+  lifecycle: experimental
+  type: backstage-backend-plugin-module
+  owner: maintainers

plugins/scaffolder-backend-module-kusion/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@kusionstack/plugin-scaffolder-backend-module-kusion",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "homepage": "https://kusionstack.io",
+  "author": {
+    "email": "[email protected]",
+    "name": "hoangndst"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module",
+    "pluginId": "scaffolder",
+    "pluginPackage": "@backstage/plugin-scaffolder-backend"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KusionStack/kusion-backstage-plugin",
+    "directory": "plugins/scaffolder-backend-module-kusion"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "^1.0.2",
+    "@backstage/config": "^1.3.0",
+    "@backstage/plugin-scaffolder-node": "^0.6.0",
+    "@kusionstack/kusion-api-client-sdk": "^1.1.5",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.29.0",
+    "@backstage/plugin-scaffolder-node-test-utils": "^0.1.15"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/scaffolder-backend-module-kusion/report.api.md

@@ -0,0 +1,11 @@
+## API Report File for "@kusionstack/plugin-scaffolder-backend-module-kusion"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
+
+// @public
+const kusionModule: BackendFeature;
+export default kusionModule;
+```

plugins/scaffolder-backend-module-kusion/src/actions/backend/createBackend.example.test.ts

@@ -0,0 +1,36 @@
+import { examples } from './createBackend.example';
+import yaml from 'yaml';
+
+describe('createBackend.example', () => {
+  it('should export the correct example', () => {
+    expect(Array.isArray(examples)).toBe(true);
+    expect(examples.length).toBe(1);
+    const example = examples[0];
+    expect(example.description).toBe('Create a backend in Kusion');
+
+    // Parse the YAML to verify its structure
+    const parsed = yaml.parse(example.example);
+    expect(parsed).toHaveProperty('steps');
+    expect(Array.isArray(parsed.steps)).toBe(true);
+    expect(parsed.steps[0]).toMatchObject({
+      id: 'create-backend',
+      action: 'kusion:backend:create',
+      name: 'Create backend',
+      input: {
+        name: 'my-backend',
+        description: 'This is my backend',
+        backendConfig: {
+          type: 's3',
+          configs: {
+            region: 'string',
+            endpoint: 'string',
+            accessKeyID: 'string',
+            accessKeySecret: 'string',
+            bucket: 'string',
+            prefix: 'string',
+          },
+        },
+      },
+    });
+  });
+});

plugins/scaffolder-backend-module-kusion/src/actions/backend/createBackend.example.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2025 KusionStack
+ *
+ * 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 { TemplateExample } from '@backstage/plugin-scaffolder-node';
+import yaml from 'yaml';
+
+export const examples: TemplateExample[] = [
+  {
+    description: 'Create a backend in Kusion',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'create-backend',
+          action: 'kusion:backend:create',
+          name: 'Create backend',
+          input: {
+            name: 'my-backend',
+            description: 'This is my backend',
+            backendConfig: {
+              configs: {
+                region: 'string',
+                endpoint: 'string',
+                accessKeyID: 'string',
+                accessKeySecret: 'string',
+                bucket: 'string',
+                prefix: 'string',
+              },
+              type: 's3',
+            },
+          },
+        },
+      ],
+    }),
+  },
+];