backstage/plugins/nomad/README.md

@backstage/plugin-nomad

This is a frontend plugin is for viewing Nomad job versions and task group allocations.

This plugin has a corresponding backend plugin required to call the Nomad cluster's API: @backstage/plugin-nomad-backend.

Introduction

Nomad

A simple and flexible scheduler and orchestrator to deploy and manage containers and non-containerized applications across on-prem and clouds at scale.

Features

At the time of writing, this plugin provides two components:

• a table to view recent job versions
• a table to view allocations for a job and/or group

Getting Started

Requirements

You will need to have the backend Nomad plugin, @backstage/plugin-nomad-backend, installed and running. See its README for set up instructions.

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. You can follow this tutorial 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. You can check this tutorial for more info.

Installation

# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-nomad

Configuration

Add configuration to your app-config.yaml. For example:

nomad:
  addr: http://localhost:4646
  token: 70d707b6-3d45-472e-8639-6b15770c19b8

The token can be excluded if ACLs are not enabled.

Annotate Components

Several annotations are available for Components that make use of this plugin:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  annotations:
    nomad.io/namespace: default
    nomad.io/job-id: redis
    nomad.io/group: 'redis|prometheus-collector'

• 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. It is optional for the 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

The snippet below adds a card to the overview tab on the EntityPage. It shows versions of a Nomad job associated with a Component in the Catalog.

// In packages/app/src/components/catalog/EntityPage.tsx

import { EntityNomadJobVersionListCard, isNomadJobIDAvailable } from '@backstage/plugin-nomad';

const overviewContent = (
  ...
  <EntitySwitch>
    <EntitySwitch.Case if={isNomadJobIDAvailable}>
      <Grid item md={6} xs={12}>
        <EntityNomadJobVersionListCard />
      </Grid>
    </EntitySwitch.Case>
  </EntitySwitch>
);

Requirements

• the nomad.io/job-id annotation must be set

Allocations Table

The snippet below adds a /nomad tab to the EntityPage that displays all allocations associated the nomad.io/job-id and/or nomad.io/group of Component's annotations.

// In packages/app/src/components/catalog/EntityPage.tsx

import { EntityNomadAllocationListTable, isNomadAllocationsAvailable } from '@backstage/plugin-nomad';

const serviceEntityPage = (
    ...
    <EntityLayout.Route
      if={isNomadAllocationsAvailable}
      path="/nomad"
      title="Nomad"
    >
      <EntityNomadAllocationListTable />
    </EntityLayout.Route>
)

Requirements

• nomad.io/job-id and/or nomad.io/group annotations must be set