@abgov/nx-oc

Nx plugin for generating and applying OpenShift manifests for Government of Alberta applications.

The plugin provides generators for CI/CD pipeline setup and per-application deployment configuration, and an executor for running oc apply against an OpenShift cluster.

Prerequisites

• OpenShift CLI (oc) installed and on PATH
• An active OpenShift login: oc login <url> --token=<token>
• Separate OpenShift projects provisioned for build infrastructure and each runtime environment (dev, test, prod)

Installation

npm i -D @abgov/nx-oc

Quick Start

# 1. Create workspace and install plugin
npx create-nx-workspace my-workspace
npm i -D @abgov/nx-oc

# 2. Login to OpenShift
oc login <url> --token=<token>

# 3. Generate pipeline infrastructure manifests
npx nx g @abgov/nx-oc:pipeline my-pipeline \
  --infra my-infra-project \
  --envs "my-dev my-test my-prod" \
  --registry ghcr.io/my-org

# 4. Apply the generated infrastructure manifests to the cluster
npx nx g @abgov/nx-oc:apply-infra

# 5. Add deployment manifests to each application
npx nx g @abgov/nx-oc:deployment my-app --appType node --env dev

Generators

pipeline

Generates OpenShift manifests for a CI/CD pipeline, including shared build infrastructure resources used across all environments.

npx nx g @abgov/nx-oc:pipeline my-pipeline \
  --infra my-infra-project \
  --envs "my-dev my-test my-prod" \
  --registry ghcr.io/my-org \
  --type actions

apply-infra

Applies the OpenShift infrastructure manifests that were generated by pipeline. Takes no options — reads the generated pipeline configuration from the workspace.

npx nx g @abgov/nx-oc:apply-infra

Use apply-infra as a follow-up to pipeline when you want to defer cluster provisioning, or as a re-apply step after editing the generated manifests.

deployment

Adds OpenShift deployment manifests (Deployment, Service, Route, etc.) to an existing Nx project for a specific environment.

npx nx g @abgov/nx-oc:deployment my-app --appType node --env dev

Run the generator once per environment per application. For a typical three-environment setup, run it three times with --env dev, --env test, and --env prod.

deployment writes .openshift/<project>/<project>.yml; sandbox writes .openshift/<project>/<project>.sandbox.yml alongside it and shares the same .openshift/<project>/Dockerfile (identical either way). A project can have both — a real CI-driven pipeline deployment and a sandbox for local experimentation — at the same time; running one never touches the other's manifest. Every object either renders also carries a deployment-mode: pipeline/sandbox label (alongside the existing app label), so the teardown-<env> and sandbox-teardown targets' label-selector deletes can never remove the other mode's resources even if they ever land in the same namespace.

Executor: apply

Runs oc apply to deploy an application's OpenShift manifests. Configure it as a target in the project's project.json:

{
  "targets": {
    "deploy": {
      "executor": "@abgov/nx-oc:apply",
      "options": {
        "ocProject": "my-dev-project"
      }
    }
  }
}

Then run:

npx nx run my-app:deploy

Options

ocProject accepts three forms:

// Single project
{ "ocProject": "my-dev" }

// Multiple projects
{ "ocProject": ["my-dev", "my-test"] }

// Tagged deployments
{ "ocProject": [{ "project": "my-dev", "tag": "v1.2.3" }] }

Sandbox deployment (local build)

For rapid iteration, the sandbox generator wires a per-app deploy that builds the image locally with podman, pushes it to a container registry (GHCR), and imports it into your OpenShift namespace — no git push or CI wait. (Requires the Nx 23 line, @abgov/nx-oc 13.x.)

sandbox writes .openshift/<project>/<project>.sandbox.yml, alongside deployment's .openshift/<project>/<project>.yml — the two share the same .openshift/<project>/Dockerfile (identical either way) but never touch each other's manifest. A project can have both — a real CI-driven pipeline deployment and a sandbox for local experimentation — at the same time.

# Add the sandbox targets to a project (run once per app)
npx nx g @abgov/nx-oc:sandbox my-app --sandboxProject=<namespace> --registry=ghcr.io/<org>

# Build → podman → push → import → roll out
npx nx run my-app:sandbox

# Tear down the sandbox resources + delete the pushed image
npx nx run my-app:sandbox-teardown

Prerequisites: podman (machine started on macOS), oc logged in to the cluster, and gh authenticated as an account with write:packages on the registry org (the deploy reads gh auth token for the push and pull secret — no PAT is stored, so that account must be the active gh account).

The deploy is the @abgov/nx-oc:sandbox executor, so its logic is versioned in the plugin (fixes reach every project on npm update). It:

• preflights oc/gh/podman and fails fast with actionable messages before the build;
• retries oc import-image to absorb the oc tag reconcile race;
• auto-detects the database (from an adsp:database:* project tag, or a drizzle db:migrate target) and provisions a shared Postgres/Mongo instance + the per-app database + migrate init container — no --database flag needed;
• for a frontend, ensures each paired backend's Service exists and warns if the backend has no running pods (proxied /api calls would 502); pass --deployBackend to deploy the backend in the same run;
• supports --skipBuild / --skipPush to resume a partial deploy.

Running the generator also writes .openshift/<app>/SANDBOX.md — a deploy/troubleshooting runbook (preflight fixes, resume flags, a manual-completion sequence, quota/auth/CrashLoopBackOff guidance).

Typical workflow

Production pipeline

1. Run pipeline once per workspace to generate shared build infrastructure manifests.
2. Run apply-infra (or pass --apply to pipeline) to provision the resources on the cluster.
3. Run deployment for each application and environment combination.
4. Add an apply executor target to each application's project.json.
5. In your GitHub Actions or Jenkins pipeline, call npx nx run my-app:deploy to apply manifests during CI/CD.

Sandbox iteration

1. Run sandbox for each application, passing --sandboxProject and --database as needed.
2. Run npx nx run my-app:sandbox to build, push, and deploy. Repeat on every change.