chore(coder plugin): make template names optional (#103)

* wip: update type definitions and parsing logic for config values * refactor: update some code for clarity * fix: update property names in top-level config * wip: commit progress on link update * chore: finish updates for CreateWorkspaceLink * chore: add new test case for disabled state * fix: cleanup markup and text for EntityDataReminder * chore: add readEntityData as context value * refactor: rename DataEntityReminder to ReminderAcoordionItem * chore: extract core accordion item logic to parent * chore: finish initial version of ReminderAccordion * wip: commit test stubs for ReminderAccordion * chore: rename isReadingEntityData prop * chore: update mock context values in tests * wip: commit test stub for hiding cta button when there is no repo URL * chore: hide CTA button when there is no repo URL * chore: rename AccordionItem to Disclosure * chore: update tests for Disclosure * chore: remove needless hasAssertions calls * fix: update conditional logic for ReminderAccordion * fix: more accordion bug fixes * chore: finish another test case * chore: add another accordion test case * refactor: rename props for clarity * refactor: simplify condition for entity reminder * refactor: update prop for Disclosure * chore: finish all tests for accordion * refactor: update type definition for mock config * refactor: polish up accordion tests * chore: finish up all tests * fix: add missing property to mock setup to help compiler pass * refactor: move isReadingEntityData property to workspaces config * fix: add overflow-y and max height behavior to accordion * chore: polish styling for accordion * fix: add reminder accordion as exported plugin component * refactor: rename imported component to reduce visual noise when reading * fix: make no-link message more clear for button * fix: update text to account for new tooltip * docs: add page about catalog-info * docs: finish all docs updates for coder plugin * docs: add docs section for ReminderAccordion * fix: update link for documentation in UI
coder · Apr 4, 2024 · ece362a · ece362a
1 parent 6c050f1
commit ece362a
Show file tree

Hide file tree

Showing 30 changed files with 989 additions and 314 deletions.
diff --git a/packages/app/src/components/catalog/EntityPage.tsx b/packages/app/src/components/catalog/EntityPage.tsx
@@ -137,8 +137,8 @@ const coderAppConfig: CoderAppConfig = {
   },
 
   workspaces: {
-    templateName: 'devcontainers',
-    mode: 'manual',
+    defaultTemplateName: 'devcontainers',
+    defaultMode: 'manual',
     repoUrlParamKeys: ['custom_repo', 'repo_url'],
     params: {
       repo: 'custom',

diff --git a/plugins/backstage-plugin-coder/README.md b/plugins/backstage-plugin-coder/README.md
@@ -28,22 +28,23 @@ the Dev Container.
    yarn --cwd packages/app add @coder/backstage-plugin-coder
    ```
 
-1. Add the proxy key to your `app-config.yaml`:
+2. Add the proxy key to your `app-config.yaml`:
 
    ```yaml
    proxy:
      endpoints:
        '/coder':
-         # Replace with your Coder deployment access URL and a trailing /
+         # Replace with your Coder deployment access URL (add a trailing slash)
          target: 'https://coder.example.com/'
+
          changeOrigin: true
-         allowedMethods: ['GET']
+         allowedMethods: ['GET'] # Additional methods will be supported soon!
          allowedHeaders: ['Authorization', 'Coder-Session-Token']
          headers:
            X-Custom-Source: backstage
    ```
 
-1. Add the `CoderProvider` to the application:
+3. Add the `CoderProvider` to the application:
 
    ```tsx
    // In packages/app/src/App.tsx
@@ -58,14 +59,16 @@ the Dev Container.
      },
 
      // Set the default template (and parameters) for
-     // catalog items. This can be overridden in the
-     // catalog-info.yaml for specific items.
+     // catalog items. Individual properties can be overridden
+     // by a repo's catalog-info.yaml file
      workspaces: {
-       templateName: 'devcontainers',
-       mode: 'manual',
-       // This parameter is used to filter Coder workspaces
-       // by a repo URL parameter.
+       defaultTemplateName: 'devcontainers',
+       defaultMode: 'manual',
+
+       // This property defines which parameters in your Coder
+       // workspace templates are used to store repository links
        repoUrlParamKeys: ['custom_repo', 'repo_url'],
+
        params: {
          repo: 'custom',
          region: 'eu-helsinki',
@@ -88,7 +91,7 @@ the Dev Container.
 
    **Note:** You can also wrap a single page or component with `CoderProvider` if you only need Coder in a specific part of your app. See our [API reference](./docs/README.md) (particularly the section on [the `CoderProvider` component](./docs/components.md#coderprovider)) for more details.
 
-1. Add the `CoderWorkspacesCard` card to the entity page in your app:
+4. Add the `CoderWorkspacesCard` card to the entity page in your app:
 
    ```tsx
    // In packages/app/src/components/catalog/EntityPage.tsx
@@ -101,6 +104,33 @@ the Dev Container.
    </Grid>;
    ```
 
+### `app-config.yaml` files
+
+In addition to the above, you can define additional properties on your specific repo's `catalog-info.yaml` file.
+
+Example:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: python-project
+spec:
+  type: other
+  lifecycle: unknown
+  owner: pms
+
+  # Properties for the Coder plugin are placed here
+  coder:
+    templateName: 'devcontainers'
+    mode: 'auto'
+    params:
+      repo: 'custom'
+      region: 'us-pittsburgh'
+```
+
+You can find more information about what properties are available (and how they're applied) in our [`catalog-info.yaml` file documentation](./docs/catalog-info.md).
+
 ## Roadmap
 
 This plugin is in active development. The following features are planned:

diff --git a/plugins/backstage-plugin-coder/dev/DevPage.tsx b/plugins/backstage-plugin-coder/dev/DevPage.tsx
@@ -24,8 +24,8 @@ const appConfig: CoderAppConfig = {
   },
 
   workspaces: {
-    templateName: 'devcontainers',
-    mode: 'manual',
+    defaultTemplateName: 'devcontainers',
+    defaultMode: 'manual',
     repoUrlParamKeys: ['custom_repo', 'repo_url'],
     params: {
       repo: 'custom',

diff --git a/plugins/backstage-plugin-coder/docs/catalog-info.md b/plugins/backstage-plugin-coder/docs/catalog-info.md
@@ -0,0 +1,59 @@
+# `catalog-info.yaml` files
+
+This file provides documentation for all properties that the Coder plugin recognizes from Backstage's [`catalog-info.yaml` files](https://backstage.io/docs/features/software-catalog/descriptor-format/).
+
+## Example file
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: python-project
+spec:
+  type: other
+  lifecycle: unknown
+  owner: pms
+
+  # Properties for the Coder plugin are placed here
+  coder:
+    templateName: 'devcontainers'
+    mode: 'auto'
+    params:
+      repo: 'custom'
+      region: 'us-pittsburgh'
+```
+
+All config properties are placed under the `spec.coder` property.
+
+## Where these properties are used
+
+At present, there are two main areas where these values are used:
+
+- [`CoderWorkspacesCard`](./components.md#coderworkspacescard) (and all sub-components)
+- [`useCoderWorkspacesConfig`](./hooks.md#usecoderworkspacesconfig)
+
+## Property listing
+
+### `templateName`
+
+**Type:** Optional `string`
+
+This defines the name of the Coder template you would like to use when creating new workspaces from Backstage.
+
+**Note:** This value has overlap with the `defaultTemplateName` property defined in [`CoderAppConfig`](types.md#coderappconfig). In the event that both values are present, the YAML file's `templateName` property will always be used instead.
+
+### `templateName`
+
+**Type:** Optional union of `manual` or `auto`
+
+This defines the workspace creation mode that will be embedded as a URL parameter in any outgoing links to make new workspaces in your Coder deployment. (e.g.,`useCoderWorkspacesConfig`'s `creationUrl` property)
+
+**Note:** This value has overlap with the `defaultMode` property defined in [`CoderAppConfig`](types.md#coderappconfig). In the event that both values are present, the YAML file's `mode` property will always be used instead.
+
+### `params`
+
+**Type:** Optional JSON object of string values (equivalent to TypeScript's `Record<string, string | undefined>`)
+
+This allows you to define additional Coder workspace parameter values that should be passed along to any outgoing URLs for making new workspaces in your Coder deployment. These values are fully dynamic, and unfortunately, cannot have much type safety.
+
+**Note:** The properties from the `params` property are automatically merged with the properties defined via `CoderAppConfig`'s `params` property. In the event of any key conflicts, the params from `catalog-info.yaml` will always win.