Backstage GitOps Clusters Plugin

GitOps Clusters brings cluster creation into Backstage. It follows GitOps. Your cluster state lives in Git. Changes move through pull requests. Automation applies them. The plugin focuses on creating Kubernetes clusters on AWS EKS using GitHub Actions as the execution path.

The plugin adds pages in Backstage where you can create a cluster from a template. You can apply standard profiles to that cluster. You can set a cluster to present or absent to handle creation or teardown. You can see each cluster with current status and a link to the runs that made the change. You stay inside Backstage while the work happens in your repos and pipelines.

This approach suits platform teams that want self service clusters for feature work or test environments. It helps teams standardize add ons and guardrails through profiles. It gives you a simple audit trail in Git for every change.

If you use Backstage today and rely on GitHub, this plugin can close a gap. It makes cluster provisioning visible and predictable for engineers. It meets you in the developer portal you already use, while keeping the source of truth in Git.

Start the GitOps API backend

Run the backend service as a Docker container. It must listen on port 3008.

Copy

docker run -d --init -p 3008:8080 chanwit/gitops-api

Install the frontend plugin in your Backstage app

From your Backstage repo root

Copy

yarn workspace app add @backstage-community/plugin-gitops-profiles

Provide the API client to your app

Create a small factory that points the plugin to the backend base URL. Add this to packages app src apis.ts

Copy

// packages/app/src/apis.ts
import { createApiFactory, configApiRef } from '@backstage/core-plugin-api';
import { apis as defaultApis } from './apis-defaults';
import {
  gitOpsApiRef,
  GitOpsRestApi,
} from '@backstage-community/plugin-gitops-profiles';

export const apis = [
  ...defaultApis,
  createApiFactory({
    api: gitOpsApiRef,
    deps: { configApi: configApiRef },
    factory: ({ configApi }) => {
      const baseUrl =
        configApi.getOptionalString('gitopsProfiles.apiBaseUrl') ??
        'http://localhost:3008';
      return new GitOpsRestApi(baseUrl);
    },
  }),
];

Add a config key so you can set the backend URL without code changes. Add this to app-config.yaml

Copy

gitopsProfiles:
  apiBaseUrl: http://localhost:3008

Add the pages and routes

Mount the pages so users can open them in the UI. Edit packages app src App.tsx

Copy

// packages/app/src/App.tsx
import React from 'react';
import { FlatRoutes, Route } from '@backstage/core-app-api';
import { apis } from './apis';
import { AppProvider } from './AppProvider';
import { AppRouter } from './components/AppRouter';

// import the plugin pages
import {
  GitopsProfilesClusterListPage,
  GitopsProfilesClusterPage,
  GitopsProfilesCreatePage,
} from '@backstage-community/plugin-gitops-profiles';

export const App = () => (
  <AppProvider apis={apis}>
    <AppRouter>
      <FlatRoutes>
        {/* your existing routes */}

        <Route path="/gitops-profiles" element={<GitopsProfilesClusterListPage />} />
        <Route path="/gitops-profiles/create" element={<GitopsProfilesCreatePage />} />
        <Route
          path="/gitops-profiles/:owner/:repo"
          element={<GitopsProfilesClusterPage />}
        />
      </FlatRoutes>
    </AppRouter>
  </AppProvider>
);

Put a link in the sidebar so users can find the page. Edit packages app src components Root.tsx or Sidebar.tsx depending on your app layout. Example for Sidebar.tsx

Copy

// packages/app/src/components/Root/Sidebar.tsx
import React from 'react';
import {
  Sidebar,
  SidebarGroup,
  SidebarItem,
  SidebarDivider,
} from '@backstage/core-components';
import GitHubIcon from '@material-ui/icons/GitHub'; // pick any icon you prefer

export const CustomSidebar = () => (
  <Sidebar>
    {/* your existing items */}
    <SidebarDivider />
    <SidebarGroup label="Operations">
      <SidebarItem to="/gitops-profiles" text="GitOps Clusters" icon={GitHubIcon} />
    </SidebarGroup>
  </Sidebar>
);

If your app uses a different sidebar component name, add the SidebarItem in the same way.

Backend for legacy and new Backstage backends

This plugin does not include a Backstage backend plugin. It calls the external GitOps API service you started with Docker. This works with the legacy backend and the new backend system. No backend code changes are needed in your Backstage server.

Notes on usage

You will need a GitHub user and a GitHub access token when creating or managing clusters. Keep those ready when using the pages

GitopsProfilesClusterListPage
GitopsProfilesCreatePage
GitopsProfilesClusterPage

The backend must be reachable at the URL you set in app config. The default above points to localhost on port 3008. Adjust it for your environment if needed.

Backstage GitOps Clusters Plugin

Installation Instructions

Start the GitOps API backend

Install the frontend plugin in your Backstage app

Provide the API client to your app

Add the pages and routes

Add a sidebar link

Backend for legacy and new Backstage backends

Notes on usage

Changelog

Breaking changes

Documentation

Maintenance

Set up Backstage in minutes with Roadie