Add backend README

Signed-off-by: josh <josh.timmons@hashicorp.com>

packages/backend/src/plugins/nomad.ts

@@ -18,15 +18,7 @@ import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 
 export default async function createPlugin(
-  env: PluginEnvironment,
+  props: PluginEnvironment,
 ): Promise<Router> {
-  // Here is where you will add all of the required initialization code that
-  // your backend plugin needs to be able to start!
-
-  // The env contains a lot of goodies, but our router currently only
-  // needs a logger
-  return await createRouter({
-    logger: env.logger,
-    config: env.config,
-  });
+  return await createRouter(props);
 }

plugins/nomad-backend/README.md

@@ -1,14 +1,50 @@
-# nomad
+# @backstage/plugin-nomad-backend
 
-Welcome to the nomad backend plugin!
+A backend for Nomad, this plugin exposes a service with routes that are used by the `@backstage/plugin-nomad` plugin to query Job and Group information from a Nomad API.
 
-_This plugin was created through the Backstage CLI_
+## Set Up
 
-## Getting started
+1. Install the plugin using:
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn
-start` in the root directory, and then navigating to [/nomad-backend](http://localhost:3000/nomad-backend).
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-nomad-backend
+```
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory.
+2. Create a `nomad.ts` file inside `packages/backend/src/plugins/`:
+
+```typescript
+import { createRouter } from '@backstage/plugin-nomad-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  props: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter(props);
+}
+```
+
+3. Modify your `packages/backend/src/index.ts` to include:
+
+```diff
+ ...
+
+ import { Config } from '@backstage/config';
+ import app from './plugins/app';
++import nomad from './plugins/nomad';
+ ...
+
+ async function main() {
+   ...
+
+   const authEnv = useHotMemoize(module, () => createEnv('auth'));
++  const nomadEnv = useHotMemoize(module, () => createEnv('nomad'));
+   ...
+
+   const apiRouter = Router();
+   apiRouter.use('/catalog', await catalog(catalogEnv));
++  apiRouter.use('/nomad', await nomad(nomadEnv));
+```
+
+Note: for this backend to work, the `nomad` configuration described in the README of `@backstage/plugin-nomad` must be configured.

plugins/nomad-backend/src/service/router.test.ts

@@ -18,12 +18,14 @@ import express from 'express';
 import request from 'supertest';
 
 import { createRouter } from './router';
+import { ConfigReader } from '@backstage/config';
 
 describe('createRouter', () => {
   let app: express.Express;
 
   beforeAll(async () => {
     const router = await createRouter({
+      config: new ConfigReader({}),
       logger: getVoidLogger(),
     });
     app = express().use(router);

plugins/nomad/README.md

@@ -1,6 +1,8 @@
 # @backstage/plugin-nomad
 
-This plugin is a frontend for viewing Nomad job versions and allocations.
+This is a frontend plugin is for viewing Nomad [job versions](https://developer.hashicorp.com/nomad/docs/concepts/architecture#job) and [task group allocations](https://developer.hashicorp.com/nomad/docs/concepts/architecture#allocation).
+
+This plugin has a corresponding backend plugin required to call the Nomad cluster's API: ` @backstage/plugin-nomad-backend`.
 
 ## Introduction
 
@@ -19,9 +21,11 @@ At the time of writing, this plugin provides two components:
 
 ### Requirements
 
-You will need a running Nomad cluster. You can follow [this tutorial](https://developer.hashicorp.com/nomad/tutorials/enterprise/production-deployment-guide-vm-with-consul) to learn how to deploy one.
+You will need to have the backend Nomad plugin, `@backstage/plugin-nomad-backend`, installed and running. See its README for set up instructions.
 
-If ACLs are enabled, you will need a `token` with at least [`list-jobs` and `read-jobs` capabilities](https://developer.hashicorp.com/nomad/tutorials/access-control/access-control-policies#namespace-rules). You can check [this tutorial](https://developer.hashicorp.com/nomad/tutorials/access-control/access-control-create-policy) for more info.
+You will need a running Nomad cluster with an API address that is reachable from the `@backstage/plugin-nomad/backend` plugin [running in the back end](https://backstage.io/docs/overview/architecture-overview/#third-party-backed-plugins). You can follow [this tutorial](https://developer.hashicorp.com/nomad/tutorials/enterprise/production-deployment-guide-vm-with-consul) to learn how to deploy one.
+
+If your Nomad cluster has ACLs enabled, you will need a `token` with at least [`list-jobs` and `read-jobs` capabilities](https://developer.hashicorp.com/nomad/tutorials/access-control/access-control-policies#namespace-rules). You can check [this tutorial](https://developer.hashicorp.com/nomad/tutorials/access-control/access-control-create-policy) for more info.
 
 ### Installation
 
@@ -44,18 +48,21 @@ The `token` can be excluded if [ACLs are not enabled](https://developer.hashicor
 
 ### Annotate Components
 
-There are two annotations for Components in the Service Catalog:
+Several annotations are available for Components that make use of this plugin:
 
 ```yaml
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
   annotations:
+    nomad.io/namespace: default
     nomad.io/job-id: redis
     nomad.io/group: 'redis|prometheus-collector'
 ```
 
-The `nomad.io/job-id` annotation's value is matched exactly. The `nomad.io/group` annotation's value is used as a regex pattern against `TaskGroup` using [Nomad's server-side filtering](https://developer.hashicorp.com/nomad/api-docs#filtering).
+- `nomad.io/job-id` annotation's value is matched exactly and corresponds to `JobID` in the Nomad API. It is required for the Job Versions Card but optional for the Allocations Table
+- `nomad.io/group` annotation's value is used as a regex pattern against `TaskGroup` using [Nomad's server-side filtering](https://developer.hashicorp.com/nomad/api-docs#filtering). It is optional for the [Allocations Table](#allocations-table)
+- `nomad.io/namespace` is the Namespace of the Job and Allocations of the Component. If omitted, it defaults to `default`
 
 ### Job Versions Card
 

plugins/nomad/dev/index.tsx

@@ -13,15 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import React from 'react';
 import { createDevApp } from '@backstage/dev-utils';
-import { nomadPlugin, NomadPage } from '../src/plugin';
+import { nomadPlugin } from '../src/plugin';
 
-createDevApp()
-  .registerPlugin(nomadPlugin)
-  .addPage({
-    element: <NomadPage />,
-    title: 'Root Page',
-    path: '/nomad',
-  })
-  .render();
+createDevApp().registerPlugin(nomadPlugin).render();