From e859cf3cd9b8ed57ee9e25865ac80082528c2a60 Mon Sep 17 00:00:00 2001 From: Siu Wa Wu Date: Tue, 18 Aug 2026 16:18:28 +1000 Subject: [PATCH 1/2] update docs regarding the testjob change --- CLAUDE.md | 24 +++++++++++++++--------- CONTRIBUTING.md | 46 +++++++++++++++++++++++----------------------- 2 files changed, 38 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 342acc32..2d0725fa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,18 +16,24 @@ This is the OpenShift Dedicated managed-scripts repository, containing scripts e - `make pyflakes` - Run pyflakes on all .py files ### Testing with Backplane -Scripts are tested using the Backplane CLI: +The `testjob create`, `get`, and `logs` subcommands are deprecated. Use `ocm backplane testjob render` to generate Kubernetes YAML (ServiceAccount, RBAC, and Pod) locally, then apply it with `oc` on a non-production cluster where you have `cluster-admin` access: ```bash -# Connect to stage environment -ocm backplane config set url https://api.stage.backplane.openshift.com -ocm backplane login +# Log in to a non-production cluster with cluster-admin (normal IDP login; no backplane login needed) +oc login -# Test a script -ocm backplane testjob create [-p var1=val1] +# Render the test job YAML from the script directory (contains metadata.yaml + the script) +cd scripts/CEE/new-script +ocm backplane testjob render [-p var1=val1] > test-job.yaml -# Check status and logs -ocm backplane testjob get -ocm backplane testjob logs +# Review, then apply +oc apply -f test-job.yaml + +# Watch / inspect with standard oc +oc -n openshift-backplane-managed-scripts get pods +oc -n openshift-backplane-managed-scripts logs + +# Clean up +oc delete -f test-job.yaml ``` ## Architecture and Structure diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec62b2d2..cf18e3ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,44 +60,44 @@ All pre-existing scripts can be found [here](https://github.com/openshift/manage ## Testing the Script -1. **Ensure You Are Using the Stage API** +The `ocm backplane testjob create`, `get`, and `logs` commands are deprecated. Use `ocm backplane testjob render` instead, which generates the Kubernetes YAML (ServiceAccount, RBAC, and Pod) for your draft script locally — no backplane API call is made. You then apply it directly with `oc` on a non-production cluster where you have `cluster-admin` access, and use plain `oc` to watch, inspect, and clean up. + +1. **Log In to a Non-Production Cluster** + - Use a normal IDP login to a non-production cluster where you have `cluster-admin` access (no `ocm backplane login` needed). ```sh - ocm backplane config set url https://api.stage.backplane.openshift.com - ocm backplane config get url - ``` - Output: - ``` - url: https://api.stage.backplane.openshift.com + oc login ``` -2. **Connect to a Stage Cluster** +2. **Render the Test Job YAML** + - Run this from the script directory (which contains `metadata.yaml` and the script). ```sh - ocm backplane login + cd scripts/CEE/new-script + ocm backplane testjob render [-p var1=val1] > test-job.yaml ``` + Useful flags: + - `-p`/`--params` - script parameter, repeatable. + - `-s`/`--source-dir` - script source directory (defaults to the current directory). + - `-i`/`--base-image-override` - override the base image (defaults to the latest managed-scripts image resolved from GitHub). + - `-o`/`--output` - write to a file instead of stdout. -3. **Run a Test Job** +3. **Review and Apply the YAML** ```sh - ocm backplane testjob create [-p var1=val1] - ``` - Example Output: - ``` - Test job openshift-job-dev-7m755 created successfully - Run "ocm backplane testjob get openshift-job-dev-7m755" for details - Run "ocm backplane testjob logs openshift-job-dev-7m755" for job logs + oc apply -f test-job.yaml ``` 4. **Check Job Status** ```sh - ocm backplane testjob get openshift-job-dev-7m755 - ``` - Example Output: - ``` - TestId: openshift-job-dev-7m755, Status: Succeeded + oc -n openshift-backplane-managed-scripts get pods ``` 5. **View Logs** ```sh - ocm backplane testjob logs openshift-job-dev-7m755 + oc -n openshift-backplane-managed-scripts logs + ``` + +6. **Clean Up** + ```sh + oc delete -f test-job.yaml ``` ## Deploying the Script to Production From 8ab97510b6d442bfab2c15bf59fab06d473f506c Mon Sep 17 00:00:00 2001 From: Siu Wa Wu Date: Tue, 18 Aug 2026 16:59:40 +1000 Subject: [PATCH 2/2] address comments --- CLAUDE.md | 10 ++++++---- CONTRIBUTING.md | 14 ++++++++++---- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2d0725fa..be481c79 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,18 +19,20 @@ This is the OpenShift Dedicated managed-scripts repository, containing scripts e The `testjob create`, `get`, and `logs` subcommands are deprecated. Use `ocm backplane testjob render` to generate Kubernetes YAML (ServiceAccount, RBAC, and Pod) locally, then apply it with `oc` on a non-production cluster where you have `cluster-admin` access: ```bash # Log in to a non-production cluster with cluster-admin (normal IDP login; no backplane login needed) -oc login +# Replace the API URL with your cluster's. +oc login https://api.example.openshift.com:6443 # Render the test job YAML from the script directory (contains metadata.yaml + the script) +# If the script requires parameters, add them with -p (repeatable), e.g. -p var1=value cd scripts/CEE/new-script -ocm backplane testjob render [-p var1=val1] > test-job.yaml +ocm backplane testjob render > test-job.yaml # Review, then apply oc apply -f test-job.yaml -# Watch / inspect with standard oc +# Watch / inspect with standard oc (replace the pod name with the one from the previous step) oc -n openshift-backplane-managed-scripts get pods -oc -n openshift-backplane-managed-scripts logs +oc -n openshift-backplane-managed-scripts logs example-test-job-pod # Clean up oc delete -f test-job.yaml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf18e3ac..7766873e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Before creating, testing, or deploying new scripts, ensure you have the followin 1. VPN connectivity 2. [OCM CLI Binary](https://github.com/openshift-online/ocm-cli) 3. [Backplane CLI Binary](https://source.redhat.com/groups/public/sre/wiki/setup_backplane_cli) -4. Access to the [Stage API](https://api.stage.backplane.openshift.com) +4. A non-production cluster where you have `cluster-admin` access to test on All pre-existing scripts can be found [here](https://github.com/openshift/managed-scripts/tree/main/scripts) for reference. @@ -64,15 +64,20 @@ The `ocm backplane testjob create`, `get`, and `logs` commands are deprecated. U 1. **Log In to a Non-Production Cluster** - Use a normal IDP login to a non-production cluster where you have `cluster-admin` access (no `ocm backplane login` needed). + - Replace `https://api.example.openshift.com:6443` with your cluster's API URL. ```sh - oc login + oc login https://api.example.openshift.com:6443 ``` 2. **Render the Test Job YAML** - Run this from the script directory (which contains `metadata.yaml` and the script). ```sh cd scripts/CEE/new-script - ocm backplane testjob render [-p var1=val1] > test-job.yaml + ocm backplane testjob render > test-job.yaml + ``` + - If your script requires parameters, pass them with `-p` (repeatable): + ```sh + ocm backplane testjob render -p var1=value > test-job.yaml ``` Useful flags: - `-p`/`--params` - script parameter, repeatable. @@ -91,8 +96,9 @@ The `ocm backplane testjob create`, `get`, and `logs` commands are deprecated. U ``` 5. **View Logs** + - Replace `example-test-job-pod` with the pod name from the previous step. ```sh - oc -n openshift-backplane-managed-scripts logs + oc -n openshift-backplane-managed-scripts logs example-test-job-pod ``` 6. **Clean Up**