From c0f49cec7737e0c2a0a3af4cbb7ae273d6d59165 Mon Sep 17 00:00:00 2001 From: josh Date: Sun, 4 Jun 2023 18:32:19 -0400 Subject: [PATCH] Add backend README Signed-off-by: josh --- packages/backend/src/plugins/nomad.ts | 12 +---- plugins/nomad-backend/README.md | 54 +++++++++++++++---- .../nomad-backend/src/service/router.test.ts | 2 + plugins/nomad/README.md | 17 ++++-- plugins/nomad/dev/index.tsx | 12 +---- 5 files changed, 63 insertions(+), 34 deletions(-) diff --git a/packages/backend/src/plugins/nomad.ts b/packages/backend/src/plugins/nomad.ts index 68e4344f98..111cbfbf0d 100644 --- a/packages/backend/src/plugins/nomad.ts +++ b/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 { - // 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); } diff --git a/plugins/nomad-backend/README.md b/plugins/nomad-backend/README.md index 1a670bd9a8..3a25df2a72 100644 --- a/plugins/nomad-backend/README.md +++ b/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 { + 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. diff --git a/plugins/nomad-backend/src/service/router.test.ts b/plugins/nomad-backend/src/service/router.test.ts index c10dc8ba0e..d94948cbbd 100644 --- a/plugins/nomad-backend/src/service/router.test.ts +++ b/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); diff --git a/plugins/nomad/README.md b/plugins/nomad/README.md index c1fc81886e..ef83b34fe1 100644 --- a/plugins/nomad/README.md +++ b/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 diff --git a/plugins/nomad/dev/index.tsx b/plugins/nomad/dev/index.tsx index 07d294c019..73eaffb8e0 100644 --- a/plugins/nomad/dev/index.tsx +++ b/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: , - title: 'Root Page', - path: '/nomad', - }) - .render(); +createDevApp().registerPlugin(nomadPlugin).render();