diff --git a/Makefile b/Makefile index f9d9b08d72..d501cbcfc1 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,12 @@ all: build .PHONY: all +# Set the packages to build +GO_BUILD_PACKAGES := ./cmd/... + # Include the library makefile include $(addprefix ./vendor/github.com/openshift/build-machinery-go/make/, \ + golang.mk \ targets/openshift/deps-gomod.mk \ targets/openshift/images.mk \ targets/openshift/bindata.mk \ diff --git a/README.md b/README.md index 91466f3d60..360d70b6ac 100644 --- a/README.md +++ b/README.md @@ -1,247 +1,152 @@ # Console Operator -An operator for OpenShift Console. +The OpenShift Console Operator is a Kubernetes operator that manages the OpenShift web console deployment. It handles the installation, configuration, and lifecycle management of the OpenShift Console and its associated components. -The console-operator installs and maintains the web console on a cluster. +## Overview -## Run on a 4.0.0 Cluster +The Console Operator is responsible for: +- Deploying and managing the OpenShift web console +- Managing console downloads deployment +- Configuring console authentication and authorization +- Handling console customization (logos, branding, etc.) +- Managing console routes and services +- Ensuring console availability and health -The console operator is installed by default and will automatically maintain a console. +## Quick Start -## Development Setup +### Prerequisites -* Install Go 1.15.2 -- https://golang.org/dl/ -* GVM is recommended but not required -- https://github.com/moovweb/gvm - * On MacOS you may need to execute `go env -w GO111MODULE=auto` after installing the main go binary before you can install other versions via GVM +- Go 1.23.0 or later +- Docker +- OpenShift CLI (`oc`) +- Access to an OpenShift cluster -## Clone the Repo & Build Locally +### Clone the Repo & Build Locally -To avoid some of the standard quirks of `gopath`, the recommended way to clone and -work with this repository is to do the following: - -### Cloning the Repo - -Rather than ~/go for everything, provide separate gopaths. For this example we will -use $HOME/gopaths as the root of our projects and consoleoperator as our project directory. - - -```bash -mkdir -p $HOME/gopaths/consoleoperator -``` - -Now get the repository from github. - -```bash -cd $HOME/gopaths/consoleoperator -export GOPATH=`pwd` -go get github.com/openshift/console-operator -``` - -You may see a message like `package github.com/openshift/console-operator: no Go files in $HOME/gopaths/consoleoperator/src/github.com/openshift/console-operator` -and you can safely ignore it. - -You may now add your fork to the repo as a remote. ```bash -cd src/github.com/openshift/console-operator/ -git remote rename origin upstream -git remote add origin {Your fork url} -``` - -### Gopath - -Note that we created `$HOME/gopaths`. This implies that each project will have -its own gopath, so you will need to set that while working: - -```bash -export GOPATH=$HOME/gopaths/consoleoperator -``` - -If you have multiple goprojects and don't want to fuss with maintaining this when -you `cd` to different projects, give [this script](https://www.jtolio.com/2017/01/magic-gopath/) -a try. It will add a command called `calc_gopath` to your `prompt_command` and -set your gopath appropriately depending on the current working directory. - -(At some point `golang` will fix `$GOPATH` and this won't be necessary) - -### Development & Building the Binary - -Running the `make` command will build the binary: - -```bash -make -``` - -The binary output will be: - -```bash -./_output/local/bin///console -``` - -You may want to add this to your path or symlink it: - -```bash -# if your ~/bin is in your path: -ln -s ./_output/local/bin///console ~/bin/console -``` - -However, it is no longer recommended to run the operator locally. Instead, you -should be building a docker image and deploying it into a development cluster. -Continue below for instructions to do this with a reasonable feedback loop. - -### Verify Source Code +# Clone the repository +git clone https://github.com/openshift/console-operator.git +cd console-operator -Test `gofmt` and other verification tools: - -```bash -make verify -``` - -Let `gofmt` automatically update your source: +# Build the operator binary +make -```bash -gofmt -w ./pkg -gofmt -w ./cmd +# Build for specific platform (e.g., Linux AMD64) +GOOS=linux GOARCH=amd64 make ``` -### Run Unit Tests +### Running Tests ```bash +# Run unit tests make test-unit -``` -It is suggested to run `integration` and `e2e` tests with CI. This is automatic when opening a PR. +# Run end-to-end tests +# It is suggested to run `integration` and `e2e` tests with CI. This is automatic when opening a PR. +make test-e2e +# Run all tests +make test -### Development Against a 4.0 Dev Cluster +# Verify code formatting and linting +make verify +``` -The approach here is to build & deploy your code in a new container on a development cluster. Don't -be put off by the need to redeploy your container, this is intended to provide a quick feedback loop. +## Development -#### Create a Cluster -To develop features for the `console-operator`, you will need to run your code against a dev cluster. -The `console-operator` expects to be running in a container. It is difficult to fake a local -environment, and the debuggin experience is not like debugging a real container. Instead, do the following -to set yourself up to build your binary & deploy a new container quickly and frequently. +### Local Development Setup -Visit [https://try.openshift.com/](https://try.openshift.com/), download the installer and create -a cluster. [Instructions](https://cloud.openshift.com/clusters/install) (including pull secret) -are maintained here. +For detailed development instructions, see [DEVELOPMENT.md](DEVELOPMENT.md). -```bash -# create a directory for your install config -# aws is recommended -mkdir ~/openshift/aws/us-east -cd ~/openshift/aws/us-east -# generate configs using the wizard -openshift-install create install-config -# then run the installer to get a cluster -openshift-install create cluster --dir ~/openshift/aws/us-east --log-level debug -``` +#### Quick Development Workflow -If successful, you should have gotten instructions to set `KUBECONFIG`, login to the console, etc. +1. **Build and deploy to a development cluster**: + ```bash + # Build Docker image + # Note: Ensure the image architecture matches your target platform + # For multi-arch builds, use: docker buildx build --platform linux/amd64,linux/arm64 + docker build -f Dockerfile.rhel7 -t quay.io/your-username/console-operator:latest . -#### Shut down CVO & the Default Console Operator + + # Push to registry + docker push quay.io/your-username/console-operator:latest + + ``` -We don't want the default `console-operator` to run if we are going to test our own. Therefore, do -the following: +2. **Update image paths in the deployment configuration**: + ```bash + # Edit the deployment file to use your custom images + # Update both the operator image and console image paths + vim examples/07-operator-alt-image.yaml + ``` + + **Important**: Before running the deployment script, you must update the following in `examples/07-operator-alt-image.yaml`: + + - **Operator Image**: Change `quay.io//console-operator:latest` to your custom operator image path + - **Console Image**: Change `quay.io//console:latest` to your custom console image path (if you have one) + + Example configuration: + ```yaml + # In examples/07-operator-alt-image.yaml + containers: + - name: console-operator + image: quay.io/your-username/console-operator:latest # ← Update this + # ... other config ... + env: + - name: CONSOLE_IMAGE + value: quay.io/your-username/console:latest # ← Update this if needed + ``` -```bash -# Instruct CVO to stop managing the console operator -# CVO's job is to ensure all of the operators are functioning correctly -# if we want to make changes to the operator, we need to tell CVO to stop caring. -oc apply -f examples/cvo-unmanage-operator.yaml -# Then, scale down the default console-operator -oc scale --replicas 0 deployment console-operator --namespace openshift-console-operator -``` -Note that you can also simply delete the CVO namespace if you want to turn it off completely (for all operators). +3. **Deploy using the custom operator script**: + ```bash + # Make the script executable + chmod +x deploy-custom-operator.sh + + # Run the deployment script + ./deploy-custom-operator.sh + ``` + + The script will: + - Verify your custom images are accessible + - Disable CVO management of the console operator + - Scale down the default operator + - Deploy your custom operator + - Wait for the deployment to be ready + - Show deployment status and logs -Now we should be ready to build & deploy the operator with our changes. -#### Preparation to Deploy Operator Changes Quickly +If you prefer the manual way, that works too. Here are the manual steps to disable CVO management of the console operator: -Typically to build your binary you will use the `make` command: +1. **Instruct CVO to stop managing the console operator:** -```bash -# this will build for your platform: -make -# if you are running OSX, you will need to build for linux doing something like: -OS_DEBUG=true OS_BUILD_PLATFORMS=linux/amd64 make -# note that you can build for mulitiple platforms with: -make build-cross -``` -But the `make` step is included in the `Dockerfile`, so this does not need to be done manually. -You can instead simply build the container image and push the it to your own registry: - -```bash -# the pattern is: -docker build -t //console-operator: . -# following: docker.io/openshift/origin-console-operator:latest -# for development, you are going to push to an alternate registry. -# specifically it can look something like this: -docker build -f Dockerfile.rhel7 -t quay.io/benjaminapetersen/console-operator:latest . -``` -You can optionally build a specific version. + Apply the provided override manifest to tell the Cluster Version Operator (CVO) to stop managing the console operator resources: -Then, push your image: + ```bash + oc apply -f examples/cvo-unmanage-operator.yaml + ``` -```bash -docker push //console-operator: -# Be sure your repository is public else the image will not be able to be pulled later -docker push quay.io/benjaminapetersen/console-operator:latest -``` -Then, you will want to deploy your new container. This means duplicating the `manifests/07-operator.yaml` -and updating the line `image: docker.io/openshift/origin-console-operator:latest` to instead use the -image you just pushed. + This manifest sets the `unmanaged: true` flag for the console-operator deployment and related resources. -```bash -# duplicate the operator manifest to /examples or your ~/ home dir -cp manifests/07-operator.yaml ~/07-operator-alt-image.yaml -``` -Then, update the image & replicas in your `07-operator-alt-image.yaml` file: - -```yaml -# before -replicas: 2 -image: docker.io/openshift/origin-console-operator:latest -# after -# image: //console-operator: -replicas: 1 -image: quay.io/benjaminapetersen/console-operator:latest -``` -And ensure that the `imagePullPolicy` is still `Always`. This will ensure a fast development feedback loop. +2. **Scale down the default console operator:** -```yaml -imagePullPolicy: Always -``` + After disabling CVO management, scale down the default console operator deployment so it does not interfere with your custom operator: -#### Deploying + ```bash + oc scale --replicas 0 deployment console-operator --namespace openshift-console-operator + ``` -At this point, your pattern will be + This ensures the default operator is not running while you deploy your custom version. -- Change code -- Build a new docker image - - This will automatically & implicitly `make build` a new binary -- Push the image to your repository -- Delete the running `console-operator` pod - - This will cause the Deployment to pull the image again before deploying a new pod +Once these steps are complete, you can proceed to build, push, and deploy your custom operator image as described above. -Which looks like the following: -```bash -# build binary + container -docker build -t quay.io/benjaminapetersen/console-operator:latest . -# push container -docker push quay.io/benjaminapetersen/console-operator:latest -# delete pod, trigger a new pull & deploy -oc delete pod console-operator --namespace openshift-console-operator -``` -Docker containers are layered, so there should not be a significant time delay in between your pushes. +### Manifest Changes -#### Manifest changes +If you need to make changes to the operator's deployment manifest (for example, to update environment variables, add volumes, or change resource limits), you should edit your custom manifest file (such as `examples/07-operator-alt-image.yaml`). -If you are making changes to the manifests, you will need to `oc apply` the manifest. +After making your changes, apply the updated manifest to your cluster. -#### Debugging +### Helpful Debugging Commands ```bash # inspect the clusteroperator object @@ -256,29 +161,18 @@ oc describe pod console-operator- -n openshift-console-operator oc logs -f console-operator- -n openshift-console-operator # exec into the pod oc exec -it console-operator- -- /bin/bash -``` -## Tips + ``` -If you don't know where your `kubeconfig` is due to running against multiple clusters this can be handy: +**⚠️ Important Notes**: +- Ensure your custom images are built and pushed to a registry before running the script +- The script will prompt for confirmation that you've updated the image paths +- Make sure you have cluster admin permissions to modify operator deployments +- The deployment may take several minutes to complete -```bash -# just a high number -oc whoami --loglevel=100 -# likely output will be $HOME/.kube/config -``` -If you need to know information about your cluster: +**Troubleshooting**: +- If the deployment fails, check the operator logs: `oc logs -n openshift-console-operator -l name=console-operator` +- To revert to the default operator: `oc apply -f examples/cvo-manage-operator.yaml` -```bash -# this will list all images, associated github repo, and the commit # currently running. -# very useful to see if the image is running current code...or not. -oc adm release info --commits -# get just the list of images & sha256 digest -oc adm release info -# coming soon... -oc adm release extract -``` -## Quick Starts + -See the [Quick Starts README](quickstarts/README.md) for contributing console -quick starts. diff --git a/deploy-custom-operator.sh b/deploy-custom-operator.sh new file mode 100755 index 0000000000..f557225195 --- /dev/null +++ b/deploy-custom-operator.sh @@ -0,0 +1,148 @@ +#!/bin/bash + +set -e + +echo "Openshift Console Operator Custom Deployment Script" +echo "=============================================" + +# Check if we're connected to a cluster +if ! oc whoami >/dev/null 2>&1; then + echo "Error: Not connected to OpenShift cluster. Please run 'oc login' first." + exit 1 +fi + +echo "Connected to OpenShift cluster as: $(oc whoami)" + +# Check if the user has built and pushed their custom operator image +echo "Custom Image Verification" +echo "============================" + +# Extract image names from the YAML file +OPERATOR_IMAGE=$(grep -E '^\s*image:\s*quay\.io' examples/07-operator-alt-image.yaml | head -1 | sed 's/.*image:\s*//') +CONSOLE_IMAGE=$(grep -E '^\s*value:\s*quay\.io' examples/07-operator-alt-image.yaml | head -1 | sed 's/.*value:\s*//') + +echo "Detected images from examples/07-operator-alt-image.yaml:" +echo " Operator Image: $OPERATOR_IMAGE" +echo " Console Image: $CONSOLE_IMAGE" +echo "" + +echo "Before proceeding, please confirm:" +echo "1. You have built your custom operator image" +echo "2. You have pushed it to your registry (any registry, not just Docker Hub)" +echo "3. The image path you provided is accessible" +echo "4. You have updated the image path in examples/07-operator-alt-image.yaml" +echo "5. You have updated the console image path in examples/07-operator-alt-image.yaml if you needed?" +echo "" +read -p "Have you done all the above? (y/N): " CONFIRM_BUILD + + +if [[ ! "$CONFIRM_BUILD" =~ ^[Yy]$ ]]; then + echo "Please build and push your custom operator image first:" + echo " docker build -t $CUSTOM_IMAGE_PATH ." + echo " docker push $CUSTOM_IMAGE_PATH" + echo " and update the image path in examples/07-operator-alt-image.yaml" + echo " Then run this script again." + exit 1 +fi + + + +# Get cluster ID dynamically +echo "📋 Getting cluster ID..." +CLUSTER_ID=$(oc get clusterversion version -o jsonpath='{.spec.clusterID}') +if [ -z "$CLUSTER_ID" ]; then + echo "Error: Could not retrieve cluster ID" + exit 1 +fi +echo "Cluster ID: $CLUSTER_ID" + +# Create temporary CVO unmanage configuration +echo "Creating CVO unmanage configuration..." +TEMP_CVO_CONFIG=$(mktemp) +cat > "$TEMP_CVO_CONFIG" << EOF +apiVersion: config.openshift.io/v1 +kind: ClusterVersion +metadata: + name: version +spec: + clusterID: $CLUSTER_ID + overrides: + - kind: Deployment + name: console-operator + namespace: openshift-console-operator + unmanaged: true + group: apps + - kind: ClusterRole + name: console-operator + namespace: "" + unmanaged: true + group: rbac.authorization.k8s.io +EOF + +# Step 1: Disable CVO management of console operator +echo "" +echo "Step 1: Disabling CVO management of console operator..." +oc apply -f "$TEMP_CVO_CONFIG" +echo "CVO management disabled" + +# Clean up temporary file +rm "$TEMP_CVO_CONFIG" + +# Step 2: Scale down the default console operator +echo "" +echo "Step 2: Scaling down default console operator..." +oc scale --replicas 0 deployment console-operator --namespace openshift-console-operator +echo "Default console operator scaled down" + +# Step 3: Deploy the custom operator +echo "" +echo "Step 3: Deploying custom console operator..." +oc apply -f examples/07-operator-alt-image.yaml +echo "Custom console operator deployed" + +# Step 4: Wait for the operator to be ready +echo "" +echo "Step 4: Waiting for operator to be ready..." +echo "This may take a few minutes..." + +# Wait for deployment to be available +oc rollout status deployment/console-operator -n openshift-console-operator --timeout=300s + +# Wait for pod to be ready +echo "Waiting for pod to be ready..." +oc wait --for=condition=ready pod -l name=console-operator -n openshift-console-operator --timeout=300s + +echo "Operator is ready!" + +# Step 5: Show status +echo "" +echo "Step 5: Checking operator status..." +echo "" +echo "Pod status:" +oc get pods -n openshift-console-operator -l name=console-operator + +echo "" +echo "Operator logs (last 10 lines):" +oc logs -n openshift-console-operator -l name=console-operator --tail=10 + +echo "" +echo "ClusterOperator status:" +oc describe clusteroperator console + +echo "" +echo "Deployment complete!" +echo "" +echo "Next steps:" +echo " - Monitor logs: oc logs -f -n openshift-console-operator -l name=console-operator" +echo " - Check operator status: oc describe clusteroperator console" +echo " - To update your operator:" +echo " 1. Make code changes" +echo " 2. Rebuild: make" +echo " 3. Rebuild amd64 binary: GOOS=linux GOARCH=amd64 go build -mod=vendor -trimpath -ldflags '...' -o console-amd64 github.com/openshift/console-operator/cmd/console" +echo " 4. Rebuild image: docker build --platform linux/amd64 -f Dockerfile.local -t quay.io/rh-ee-leoli/console-operator:latest ." +echo " 5. Push image: docker push quay.io/rh-ee-leoli/console-operator:latest" +echo " 6. Restart pod: oc delete pod -n openshift-console-operator -l name=console-operator" +echo "" +echo "To revert to default operator:" +echo " - oc apply -f examples/cvo-manage-operator.yaml" +echo " - oc scale --replicas 1 deployment console-operator --namespace openshift-console-operator" \ No newline at end of file diff --git a/examples/07-operator-alt-image.yaml b/examples/07-operator-alt-image.yaml index 38b8a0cb8c..5850e6bb8e 100644 --- a/examples/07-operator-alt-image.yaml +++ b/examples/07-operator-alt-image.yaml @@ -44,6 +44,8 @@ spec: value: docker.io/openshift/origin-console:latest - name: OPERATOR_NAME value: "console-operator" + - name: CONSOLE_IMAGE + value: quay.io//console:latest volumes: - name: config configMap: