Skip to content

Update docs regarding the testjob change #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
feichashao wants to merge 2 commits into
base: main
Choose a base branch
from
+47 −33
Open

Update docs regarding the testjob change #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e859cf3
update docs regarding the testjob change
feichashao Aug 18, 2026
8ab9751
address comments
feichashao Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,26 @@ 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 <stage-cluster-id>
# Log in to a non-production cluster with cluster-admin (normal IDP login; no backplane login needed)
# Replace the API URL with your cluster's.
oc login https://api.example.openshift.com:6443

# Test a script
ocm backplane testjob create [-p var1=val1]
# 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 > test-job.yaml

@bmeng bmeng Aug 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we use oc login above, how can we run ocm backplane command here?

@feichashao feichashao Aug 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bmeng thanks for reviewing!

This is kind of intentional. We want to disable the /backplane/testscript endpoint which the ocm backplane testjob create used previously. The previous testjob create command needs to interact with backplane.

Then, we deprecated the ocm backplane testjob create command, and provided a helper command ocm backplane testjob render as an alternative. The render command is pure client side, which translates the user's draft script and metadata file to a yaml file, then the user can perform oc apply -f yaml-file to run create the SA/role/rolebinding/pod on a cluster to test the script.

The user can create a test cluster with cluster-admin access (via IDP), and create the yaml resources directly. Or, if the user have backplane elevation access, they can use backplane elevation to create those resources.

As long as the user have access to a cluster, it is not a must to have backplane login.


# Check status and logs
ocm backplane testjob get <job-id>
ocm backplane testjob logs <job-id>
# Review, then apply
oc apply -f test-job.yaml

# 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 example-test-job-pod

# Clean up
oc delete -f test-job.yaml
```

## Architecture and Structure
Expand Down
54 changes: 30 additions & 24 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -60,44 +60,50 @@ All pre-existing scripts can be found [here](https://github.com/openshift/manage

## Testing the Script

1. **Ensure You Are Using the Stage API**
```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
```
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.

2. **Connect to a Stage Cluster**
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).
Comment thread
coderabbitai[bot] marked this conversation as resolved.
- Replace `https://api.example.openshift.com:6443` with your cluster's API URL.
```sh
ocm backplane login <stage-cluster-id>
oc login https://api.example.openshift.com:6443

@bmeng bmeng Aug 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, how can we run ocm backplane testjob without ocm backplane login?

@xiaoyu74 xiaoyu74 Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, how can we run ocm backplane testjob without ocm backplane login?

fwiw: openshift/backplane-cli#986 (comment)

```

3. **Run a Test Job**
2. **Render the Test Job YAML**
- Run this from the script directory (which contains `metadata.yaml` and the script).
```sh
ocm backplane testjob create [-p var1=val1]
cd scripts/CEE/new-script
ocm backplane testjob render > test-job.yaml
```
Example Output:
- If your script requires parameters, pass them with `-p` (repeatable):
```sh
ocm backplane testjob render -p var1=value > test-job.yaml
```
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
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. **Review and Apply the YAML**
```sh
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**
- Replace `example-test-job-pod` with the pod name from the previous step.
```sh
oc -n openshift-backplane-managed-scripts logs example-test-job-pod
```

6. **Clean Up**
```sh
ocm backplane testjob logs openshift-job-dev-7m755
oc delete -f test-job.yaml
```

## Deploying the Script to Production
Expand Down