Deploy Backstage to dev and prod through Nixidy #88

Open
opened 2026-11-22 13:13:43 +00:00 by martin · 0 comments
Owner

Summary

Deploy Backstage to the cluster's dev and prod environments through the existing Nixidy/ArgoCD GitOps workflow, including environment configuration, ingress, persistence, and backend-only secrets.

Context

This is the cluster-side delivery work for Personal/backstage#30, the overall secure hosting gate. The application-side Keycloak integration is tracked in Personal/backstage#32; do not duplicate that code here.

The intended public URLs are:

This repository defines applications in env/dev and env/prod, generates manifests with Nixidy, and uses encrypted SOPS SopsSecret resources for secrets. Generated manifests are committed but must not contain plaintext credentials.

Scope

  • Add Nixidy application configuration and generated manifests for Backstage in dev and prod, using a pinned image and the existing cluster routing conventions.
  • Configure the public base URL and non-secret Keycloak settings for each environment, and run hosted backends with NODE_ENV=production.
  • Store the Keycloak client secret using the cluster's encrypted SOPS workflow and expose it only to the backend. Wire any other required backend-only credentials according to the data-access decisions in #30.
  • Test access from dev and prod workloads to the existing Nidaros PostgreSQL service. Use it only if connectivity can be restricted and encrypted; otherwise select and configure a persistent alternative without exposing the database publicly.
  • Configure Backstage to use the selected persistent PostgreSQL service and verify database state survives backend pod replacement and a backup can be restored.
  • Configure the TechDocs storage connection selected under Personal/backstage#30, keeping CI write credentials and backend read credentials separate.
  • Consume image updates through Personal/backstage#62; keep deployment GitOps-driven and do not hand-edit generated manifests or encrypted SOPS files.

Acceptance criteria

  • Nixidy definitions and generated manifests deploy the pinned Backstage image in dev and prod, with each environment routed over HTTPS at its intended public URL.
  • Image updates are proposed as reviewable PRs by Personal/backstage#62; ArgoCD applies them only after merge, with no direct deployment from app CI.
  • Each backend receives its environment's BACKSTAGE_BASE_URL, AUTH_KEYCLOAK_CLIENT_ID, AUTH_KEYCLOAK_BASE_URL, AUTH_KEYCLOAK_REALM, and NODE_ENV=production values.
  • AUTH_KEYCLOAK_CLIENT_SECRET is stored in an encrypted SOPS SopsSecret, materializes as a Kubernetes Secret in the application's namespace, and is referenced only by the backend workload. No plaintext secret appears in Git or generated manifests.
  • Dev and prod Backstage can reach the selected PostgreSQL service over a restricted, encrypted connection; no database endpoint is exposed publicly.
  • Database state survives backend pod replacement and a backup restore is verified.
  • Backstage can read CI-published TechDocs from the selected durable storage after redeployment; private documentation remains subject to #30's authorization policy.
  • The cluster's Nixidy formatting, tests, and dev/prod builds pass; generated manifests are regenerated through the repository workflow.
  • ArgoCD reports the dev and prod Backstage applications healthy, and a deployment smoke check confirms the expected URL, backend API routing, and Keycloak sign-in without a guest bypass.
  • SOPS status confirms the encrypted secret has been reconciled into the expected Kubernetes Secret in each configured environment.
## Summary Deploy Backstage to the cluster's dev and prod environments through the existing Nixidy/ArgoCD GitOps workflow, including environment configuration, ingress, persistence, and backend-only secrets. ## Context This is the cluster-side delivery work for [Personal/backstage#30](https://code.martials.no/Personal/backstage/issues/30), the overall secure hosting gate. The application-side Keycloak integration is tracked in [Personal/backstage#32](https://code.martials.no/Personal/backstage/issues/32); do not duplicate that code here. The intended public URLs are: - Dev: https://backstage.dev.martials.no - Prod: https://backstage.martials.no This repository defines applications in `env/dev` and `env/prod`, generates manifests with Nixidy, and uses encrypted SOPS `SopsSecret` resources for secrets. Generated manifests are committed but must not contain plaintext credentials. ## Scope - Add Nixidy application configuration and generated manifests for Backstage in dev and prod, using a pinned image and the existing cluster routing conventions. - Configure the public base URL and non-secret Keycloak settings for each environment, and run hosted backends with `NODE_ENV=production`. - Store the Keycloak client secret using the cluster's encrypted SOPS workflow and expose it only to the backend. Wire any other required backend-only credentials according to the data-access decisions in #30. - Test access from dev and prod workloads to the existing Nidaros PostgreSQL service. Use it only if connectivity can be restricted and encrypted; otherwise select and configure a persistent alternative without exposing the database publicly. - Configure Backstage to use the selected persistent PostgreSQL service and verify database state survives backend pod replacement and a backup can be restored. - Configure the TechDocs storage connection selected under Personal/backstage#30, keeping CI write credentials and backend read credentials separate. - Consume image updates through [Personal/backstage#62](https://code.martials.no/Personal/backstage/issues/62); keep deployment GitOps-driven and do not hand-edit generated manifests or encrypted SOPS files. ## Acceptance criteria - [ ] Nixidy definitions and generated manifests deploy the pinned Backstage image in dev and prod, with each environment routed over HTTPS at its intended public URL. - [ ] Image updates are proposed as reviewable PRs by Personal/backstage#62; ArgoCD applies them only after merge, with no direct deployment from app CI. - [ ] Each backend receives its environment's `BACKSTAGE_BASE_URL`, `AUTH_KEYCLOAK_CLIENT_ID`, `AUTH_KEYCLOAK_BASE_URL`, `AUTH_KEYCLOAK_REALM`, and `NODE_ENV=production` values. - [ ] `AUTH_KEYCLOAK_CLIENT_SECRET` is stored in an encrypted SOPS `SopsSecret`, materializes as a Kubernetes Secret in the application's namespace, and is referenced only by the backend workload. No plaintext secret appears in Git or generated manifests. - [ ] Dev and prod Backstage can reach the selected PostgreSQL service over a restricted, encrypted connection; no database endpoint is exposed publicly. - [ ] Database state survives backend pod replacement and a backup restore is verified. - [ ] Backstage can read CI-published TechDocs from the selected durable storage after redeployment; private documentation remains subject to #30's authorization policy. - [ ] The cluster's Nixidy formatting, tests, and dev/prod builds pass; generated manifests are regenerated through the repository workflow. - [ ] ArgoCD reports the dev and prod Backstage applications healthy, and a deployment smoke check confirms the expected URL, backend API routing, and Keycloak sign-in without a guest bypass. - [ ] SOPS status confirms the encrypted secret has been reconciled into the expected Kubernetes Secret in each configured environment. ## Related - [Personal/backstage#30](https://code.martials.no/Personal/backstage/issues/30) — overall secure hosted deployment gate; depends on this cluster delivery. - [Personal/backstage#32](https://code.martials.no/Personal/backstage/issues/32) — Keycloak SSO implementation in the Backstage application. - [Personal/backstage#62](https://code.martials.no/Personal/backstage/issues/62) — shared Bun image publication and GitOps promotion flow.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/cluster#88
No description provided.