@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

| Option | Alias | Required | Description | |--------|-------|----------|-------------| | pipeline | — | Yes | Name of the OpenShift pipeline | | infra | -i | Yes | OpenShift project name used for build infrastructure | | envs | -e | Yes | Space-separated names of the OpenShift environment projects (e.g., "my-dev my-test my-prod") | | registry | -r | Yes | Container registry to publish images to (e.g., ghcr.io/my-org) | | type | -t | No | Pipeline type: actions (default) or jenkins | | apply | -a | No | Apply the generated manifests to OpenShift immediately after generation |

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

| Option | Alias | Required | Description | |--------|-------|----------|-------------| | project | — | Yes | Name of the existing Nx project to add deployment manifests to | | appType | -t | Yes | Application type: frontend, dotnet, or node | | env | -e | Yes | ADSP environment: dev, test, or prod | | accessToken | -at | No | Access token for non-interactive retrieval of ADSP configuration |

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.

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

| Option | Required | Description | |--------|----------|-------------| | ocProject | Yes | OpenShift project(s) to apply manifests to |

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.)

# 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

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.