Infrastructure Administration

This guide is for an operator administering a deployed Nexus OpenShift namespace. It uses oc and the standalone scripts in nexus-iac/scripts/openshift/; it does not require just, local Docker, or a developer .env.

The routines below work for initial enablement and continuing maintenance.

Operator workstation and access

The operator workstation needs:

• oc, node, and a checkout containing nexus-iac/scripts/openshift/;
• an authenticated OpenShift context for the intended cluster and namespace;
• the target’s digest-pinned Nexus CLI image and Nexus tenant ID; and
• permission to read the named Secret, ConfigMap, PVC, and ServiceAccount metadata, and to create, watch, read logs from, and delete Jobs in the namespace.

Set the target once per session:

export NEXUS_NAMESPACE=nexus-platform
export NEXUS_TENANT_ID=tenant_...
export NEXUS_CLI_IMAGE=registry.example/nexus-cli@sha256:<digest>
export NEXUS_CLI_SERVICE_ACCOUNT=nexus-operator
export NEXUS_IAC=/path/to/nexus-iac

oc whoami
oc project "$NEXUS_NAMESPACE"
oc get pvc nexus-state
oc get secret platform-postgres-credentials

The nexus-cli.sh runner creates a non-root, one-shot Job, mounts the deployed nexus-state PVC, uses the in-cluster Postgres Service, streams the result, and removes the Job when it finishes. The PVC mount is required: it supplies the KMS wrapping key that protects stored provider keys.

nexus_oc() {
  "$NEXUS_IAC/scripts/openshift/nexus-cli.sh" \
    --namespace "$NEXUS_NAMESPACE" \
    --service-account "$NEXUS_CLI_SERVICE_ACCOUNT" \
    "$@"
}

Use --keep-job with nexus_oc only when the completed Job must be retained for an approved change record. The default cleanup avoids accumulating operational pods and logs.

Platform provider keys

Platform keys are Nexus-managed upstream credentials for PTB. They are distinct from tenant BYOK credentials and must come from the organization’s external secret manager.

The secret manager should synchronize one provider-specific OpenShift Secret, for example provider-openai, whose data contains OPENAI_PLATFORM_API_KEY. The runner accepts the Secret’s name only; it never accepts a secret value or creates a Secret from standard input.

Initial load or replacement

nexus_oc --provider-secret provider-openai -- \
  credentials platform-keys set \
  --provider openai \
  --workspace ws_... \
  --label "secret-version=<approved-version>" \
  --secret-env OPENAI_PLATFORM_API_KEY

Scope keys as narrowly as required. Nexus resolves keys from project to organization to workspace to the tenant-wide fallback. set revokes an active key at the exact same provider/scope before writing the replacement.

Rotation, validation, and revocation

# Rotate a known key ID after the external-secret controller has updated its value.
nexus_oc --provider-secret provider-openai -- \
  credentials platform-keys rotate ppk_... \
  --secret-env OPENAI_PLATFORM_API_KEY

# Validate stored keys and inspect selection at the workspace.
nexus_oc -- credentials platform-keys validate --provider openai
nexus_oc -- credentials platform-keys validate --id ppk_... --live
nexus_oc -- credentials platform-keys list --provider openai --workspace ws_...

# Revoke a key only after traffic is intentionally disabled or moved.
nexus_oc -- credentials platform-keys rm ppk_...

--live probes OpenAI and Anthropic; other providers are decrypt-only. The current CLI does not support two active keys at the same scope, so a same-scope rotation is a cutover rather than a parallel canary. Confirm provider routing and error telemetry after the rotation.

Workspace funds and PTB eligibility

Before a workspace can spend PTB credits, its Wallet eligibility must be on at the workspace scope. The workspace switch is the master switch; organization and project settings can only make access more restrictive.

# Inspect effective eligibility down to a project.
nexus_oc -- ops wallet status \
  --workspace ws_... --org engineering --project api

# Enable at the workspace, then optionally restrict a child scope.
nexus_oc -- ops wallet set --workspace ws_... --state on
nexus_oc -- ops wallet set --org engineering --state off
nexus_oc -- ops wallet set --org engineering --project api --state inherit

Fund a workspace with an auditable grant. Reusing the same idempotency key prevents accidental duplicate funding when a command is retried:

nexus_oc -- ops grants create \
  --workspace ws_... \
  --amount-usd 100.00 \
  --reason "approved pilot credit" \
  --idempotency-key finance-ticket-1234

nexus_oc -- ops grants list ws_...

Wallet eligibility and funds do not enable PTB by themselves. The deployed Gateway must also have PTB enabled by its approved runtime configuration, and the requested provider/model must have both a platform key and an eligible registry endpoint.

Registry updates

Registry artifacts are complete snapshots for one provider. A model omitted from the next artifact is retired unless it is pinned. Treat an artifact as release evidence: retain the source evidence, artifact SHA-256, signature key ID, generator version, plan, and resulting change-set ID.

Generate and validate outside the cluster

Generate artifacts in a controlled build environment with access to provider catalog/pricing sources and the signing key. Do not place a signing key in the Nexus namespace.

nexus-registry-generator generate \
  --provider openai \
  --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --artifact-id "openai-$(date -u +%Y%m%d)" \
  --signing-key /secure/path/registry-signing-key.txt \
  --key-id registry-production \
  --output dist/catalogs

Validate the generated bytes with the trusted public key before handing them to the cluster:

nexus registry import dist/catalogs/openai.json --check \
  --expected-key-id registry-production \
  --verifying-key-path /secure/path/registry-verifying-key.txt

Deliver immutable inputs and plan in OpenShift

registry-inputs.sh creates an immutable ConfigMap with the artifact and public verification key. It names the ConfigMap from the artifact digest and returns that name. It does not accept private keys. Use a read-only volume delivery mechanism instead when the artifact exceeds the Kubernetes ConfigMap size limit.

REGISTRY_INPUTS=$(
  "$NEXUS_IAC/scripts/openshift/registry-inputs.sh" \
    --namespace "$NEXUS_NAMESPACE" \
    --artifact dist/catalogs/openai.json \
    --verifying-key /secure/path/registry-verifying-key.txt
)

nexus_oc --registry-inputs-configmap "$REGISTRY_INPUTS" -- \
  registry import /work/registry/openai.json --check \
  --expected-key-id registry-production \
  --verifying-key-path /work/registry/registry-verifying-key.txt

nexus_oc --registry-inputs-configmap "$REGISTRY_INPUTS" -- \
  registry import /work/registry/openai.json --dry-run --format json \
  --expected-key-id registry-production \
  --verifying-key-path /work/registry/registry-verifying-key.txt

Review every retirement, price/capability change, and finding. A hard-reject finding cannot be approved; correct the source artifact and repeat the flow.

Apply and verify

nexus_oc --registry-inputs-configmap "$REGISTRY_INPUTS" -- \
  registry import /work/registry/openai.json --yes \
  --expected-key-id registry-production \
  --verifying-key-path /work/registry/registry-verifying-key.txt

nexus_oc -- registry models list

--yes is appropriate only after an approved plan identifies the exact artifact digest. Import is transactional and gateways converge through their registry poll; do not restart Gateway solely to load the new catalog. Correct a bad import with a new compensating artifact, never by modifying historical rate-card records.

Routine checks

oc get deployment,statefulset,pod -n "$NEXUS_NAMESPACE"
oc get jobs -n "$NEXUS_NAMESPACE" -l app.kubernetes.io/component=provider-maintenance
oc logs deployment/gateway -n "$NEXUS_NAMESPACE" --tail=200

nexus_oc -- credentials platform-keys list
nexus_oc -- registry models list

The CLI Job has no service-account token and needs no cluster API access. Its OpenShift ServiceAccount exists to enforce workload identity and namespace policy; the human or CI identity that invokes the runner owns the limited Job-management permissions.