Skip to content

OCM-19812: Update development docs #559

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
bhushanthakur93 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

OCM-19812: Update development docs #559

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30ae8f0
update development docs
Nov 4, 2025
c69f102
small tweaks to the docs
Nov 24, 2025
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
92 changes: 22 additions & 70 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,11 @@
- [Testing](#testing)
- [Building](#building)
- [Build using boilerplate container](#build-using-boilerplate-container)
- [Note for macOS Developers:](#note-for-macos-developers)
- [How to run](#how-to-run)
- [Locally](#locally)
- [Run using internal cluster services](#run-using-internal-cluster-services)
- [Run using cluster routes](#run-using-cluster-routes)
- [Remotely](#remotely)
- [Trigger Reconcile](#trigger-reconcile)
- [Trigger Reconcile](#trigger-reconcile)
- [Monitoring ongoing upgrade](#monitoring-ongoing-upgrade)
- [Maintenance](#maintenance)

Expand Down Expand Up @@ -120,43 +119,31 @@ to build arm64 image `podman build --platform=linux/amd64 -t quay.io/[$PERSONAL_

## How to run

Regardless of how you choose to run the operator, before doing so ensure the `UpgradeConfig` CRD is present on your cluster:
### Locally

```shell
$ oc create -f deploy/crds/upgrade.managed.openshift.io_upgradeconfigs_crd.yaml
- Make sure you have the [operator-sdk](#operator-sdk) `$PATH`.
- Install OSD cluster using staging environment by visiting [console](https://console.redhat.com/openshift/create?env=staging). Make sure to use CCS option.
- Once the cluster installs, create a user with `cluster-admin` role and log in using `oc` client.
- Scale down existing MUO deployment
```

MUO by defaults uses in the internal services to contact prometheus and alertmanager. This enables the use of a firewall to prevent egress calls however increases local development complexity slightly.

There are now three main modes that MUO can be ran in.

1. Run in a container in cluster.
2. Run locally using port-forwards and `/etc/hosts` entries to replicate production environment.
3. Run locally using Routes to access services. This is not true production however is the most simple for local development.

Modes 2 and 3 can be executed via the `Makefile` optionally setting the `$OPERATOR_NAMESPACE` as explored in the next section.
oc scale deployment managed-upgrade-operator -n openshift-managed-upgrade-operator --replicas=0
```
- OPTIONAL: Create a project for the operator to run inside of.

```
run Wrapper around operator sdk run. Requires OPERATOR_NAMESPACE to be set. See run-standard for defaults.
run-standard Run locally with openshift-managed-upgrade-operator as OPERATOR_NAMESPACE.
run-routes Same as `run`, however will use ROUTE objects to contact prometheus and alertmanager. Use of routes is non-standard but convenient for local development. Requires OPERATOR_NAMESPACE to be set.
run-standard-routes Run locally with openshift-managed-upgrade-operator as OPERATOR_NAMESPACE and use of non-standard routes.
$ oc new-project test-managed-upgrade-operator
```

- You will need to be logged in with an account that meets the [RBAC requirements](https://github.com/openshift/managed-upgrade-operator/blob/master/deploy/cluster_role.yaml) for the MUO service account. To do that run
```
oc login $(oc get infrastructures cluster -o json | jq -r '.status.apiServerURL') --token=$(oc create token managed-upgrade-operator -n openshift-managed-upgrade-operator)
```
- Now you can run the operator with [service](#Run using internal cluster services) or [routes](#Run using cluster routes)

### Locally

- Make sure you have the [operator-sdk](#operator-sdk) `$PATH`.

- You will need to be logged in with an account that meets the [RBAC requirements](https://github.com/openshift/managed-upgrade-operator/blob/master/deploy/cluster_role.yaml) for the MUO service account.

- OPTIONAL: Create a project for the operator to run inside of.

```
$ oc new-project test-managed-upgrade-operator
```

### Run using internal cluster services
#### Run using internal cluster services

The use of internal cluster services requires some changes locally to your environment:

Expand All @@ -173,20 +160,10 @@ example: ./development/port-forwards $CONTEXT
$ ./development/port-forwards $CONTEXT
```

The operator can then be ran as follows.

```
$ oc login $(oc get infrastructures cluster -o json | jq -r '.status.apiServerURL') --token $(oc -n openshift-managed-upgrade-operator serviceaccounts get-token managed-upgrade-operator)

Logged into "https://$API_URL:6443" as "system:serviceaccount:openshift-managed-upgrade-operator:managed-upgrade-operator" using the token provided.

You don't have any projects. Contact your system administrator to request a project.
```

Then if you are using the standard namespace

```
$ make run-standard
$ make run
```

Else you can provide your own.
Expand All @@ -196,18 +173,18 @@ Else you can provide your own.
$ OPERATOR_NAMESPACE=managed-upgrade-operator make run
```

### Run using cluster routes
#### Run using cluster routes

Run locally using standard namespace and cluster routes.
Copy link

@Alcamech Alcamech Nov 14, 2025

Choose a reason for hiding this comment

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

Below should be changed to ROUTES=true make run, run-standard-routes target no longer exists.

Copy link
Author

@bhushanthakur93 bhushanthakur93 Nov 24, 2025

Choose a reason for hiding this comment

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

done!


```
$ make run-standard-routes
$ ROUTES=true make run
```

Run locally using custom namespace and cluster routes.

```
$ OPERATOR_NAMESPACE=managed-upgrade-operator make run-routes
$ ROUTES=true OPERATOR_NAMESPACE=managed-upgrade-operator make run
```

### Remotely
Expand Down Expand Up @@ -270,33 +247,8 @@ oc create -f test/deploy/managed-upgrade-operator-config.yaml
oc create -f test/deploy/operator.yaml
```

- Trigger a reconcile loop by applying an [upgradeconfig](../test/deploy/upgrade.managed.openshift.io_v1alpha1_upgradeconfig_cr.yaml) CR with your desired specs:

```shell
oc create -f - <<EOF
apiVersion: upgrade.managed.openshift.io/v1alpha1
kind: UpgradeConfig
metadata:
name: managed-upgrade-config
spec:
type: "OSD"
upgradeAt: "2020-01-01T00:00:00Z"
PDBForceDrainTimeout: 60
desired:
channel: "fast-4.7"
version: "4.7.18"
EOF
```

---

**NOTE**

Refer to [fast-4.7](https://access.redhat.com/labs/ocpupgradegraph/update_channel?channel=fast-4.7&arch=x86_64&is_show_hot_fix=false) for currently available versions in `fast-4.7` channel.

---

### Trigger Reconcile
## Trigger Reconcile

- Trigger a reconcile loop by applying an `upgradeconfig` CR with your desired specs.

Expand Down