CONTRIBUTING.md

Contributing to Backplane-Managed Scripts

This document presents some guidleines and best-practices to remember while contributing to managed-scripts.

Overview

Managed-Scripts enable backplane users to execute predefined scripts while adhering to the permissions defined within the script's scope.

Terminology

Managed Script

A script file and its associated metadata file, stored in the managed-scripts repository.

Managed Job

A running instance of the Managed Script in an OSD/ROSA cluster.

Prerequisites

Before creating, testing, or deploying new scripts, ensure you have the following:

1. VPN connectivity
2. OCM CLI Binary
3. Backplane CLI Binary
4. A non-production cluster where you have cluster-admin access to test on

All pre-existing scripts can be found here for reference.

Creating a New Script

1. Fork the Managed Scripts Repository

   • Create your fork of the Managed Scripts Repository.

2. Create a new branch

   • Do not use the main or master branch for PRs.
   • Name the branch based on the JIRA card, feature or subject matter.
   • Refer to GitHub's guide on creating branches.

3. Clone the Repository

   git clone https://github.com/<git_user>/managed-scripts.git

4. Create a New Folder for the Script

   cd <path-to-folder>/managed-scripts/scripts/CEE
   mkdir -p new-script

5. Add Metadata File (metadata.yaml)

   • Follow the metadata schema.
   • Example metadata file: etcd-health-check.
   • Define allowedGroups (e.g., CEE, SREP) with applicable RBAC permissions.

6. Create the Script File (script.sh)

   tree new-script
   new-script
   ├── metadata.yaml
   └── script.sh

Testing the Script

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).
   • Replace https://api.example.openshift.com:6443 with your cluster's API URL.

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

   cd scripts/CEE/new-script
   ocm backplane testjob render > test-job.yaml

   • If your script requires parameters, pass them with -p (repeatable):

   ocm backplane testjob render -p var1=value > 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. Review and Apply the YAML

   oc apply -f test-job.yaml

4. Check Job Status

   oc -n openshift-backplane-managed-scripts get pods

5. View Logs

   • Replace example-test-job-pod with the pod name from the previous step.

   oc -n openshift-backplane-managed-scripts logs example-test-job-pod

6. Clean Up

   oc delete -f test-job.yaml

Deploying the Script to Production

• PR Review & Merge Process

  • Once your changes are well tested and pushed, create a PR containing a brief information about the script's utility and usage.
  • The script must be reviewed and approved by the SRE team.
  • Use Slack channel #sre-operators or #sd-ims-backplane and tag @managed-scripts for discussions.

• **Promote the script using ops-sop/v4/util/promote-managed-scripts.sh

• Validate Production Deployment

  1. Connect to the Backplane Production API.
  2. Log in to a production cluster.
  3. List available managed scripts:

     ocm backplane script list