An operator for OpenShift Console.
The console-operator installs and maintains the web console on a cluster.
Run on a 4.0.0 Cluster
The console operator is installed by default and will automatically maintain a console.
- Install Go 1.12 -- https://golang.org/dl/
- GVM is recommended but not required -- https://github.com/moovweb/gvm
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 mkdir $HOME/gopaths
It is fine to have
~/gopaths next to
~/go if you have some legacy projects.
Now, create a
~gopaths to hold the project:
The name of this directory doesn't matter much, but the child directories are important in order to install dependencies and build the project appropriately.
bin dir is expected:
mkdir $HOME/gopaths/consoleoperator/src mkdir $HOME/gopaths/consoleoperator/bin
Then the familiar path for source code
# specifically for this repo mkdir -p $HOME/gopaths/consoleoperator/src/github.com/openshift cd $HOME/gopaths/consoleoperator/src/github.com/openshift
Now clone (or fork, then clone) into this directory:
git clone email@example.com:openshift/console-operator.git # or your fork git clone firstname.lastname@example.org:<your-fork>/console-operator.git
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:
If you have multiple goprojects and don't want to fuss with maintaining this when
cd to different projects, give this script
a try. It will add a command called
calc_gopath to your
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
make command will build the binary:
The binary output will be:
You may want to add this to your path or symlink it:
# if your ~/bin is in your path: ln -s ./_output/local/bin/<os>/<arch>/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
gofmt and other verification tools:
gofmt automatically update your source:
gofmt -w ./pkg gofmt -w ./cmd
Run Unit Tests
It is suggested to run
e2e tests with CI. This is automatic when opening a PR.
Development Against a 4.0 Dev Cluster
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.
Create a Cluster
To develop features for the
console-operator, you will need to run your code against a dev cluster.
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.
# 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
If successful, you should have gotten instructions to set
KUBECONFIG, login to the console, etc.
Shut down CVO & the Default Console Operator
We don't want the default
console-operator to run if we are going to test our own. Therefore, do
# 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).
Now we should be ready to build & deploy the operator with our changes.
Preparation to Deploy Operator Changes Quickly
Typically to build your binary you will use the
# 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
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:
# the pattern is: docker build -t <registry>/<your-username>/console-operator:<version> . # 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 -t quay.io/benjaminapetersen/console-operator:latest .
You can optionally build a specific version.
Then, push your image:
docker push <registry>/<your-username>/console-operator:<version> # 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
and updating the line
image: docker.io/openshift/origin-console-operator:latest to instead use the
image you just pushed.
# 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
# before replicas: 2 image: docker.io/openshift/origin-console-operator:latest # after # image: <registry>/<your-username>/console-operator:<version> 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.
At this point, your pattern will be
- Change code
- Build a new docker image
- This will automatically & implicitly
make builda new binary
- This will automatically & implicitly
- Push the image to your repository
- Delete the running
- This will cause the Deployment to pull the image again before deploying a new pod
Which looks like the following:
# 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.
If you are making changes to the manifests, you will need to
oc apply the manifest.
# inspect the clusteroperator object oc describe clusteroperator console # get all events in openshift-console-operator namespace oc get events -n openshift-console-operator # retrieve deployment info (including related events) oc describe deployment console-operator -n openshift-console-operator # retrieve pod info (including related events) oc describe pod console-operator-<sha> -n openshift-console-operator # watch the logs of the operator pod (scale down to 1, no need for mulitple during dev) oc logs -f console-operator-<sha> -n openshift-console-operator # exec into the pod oc exec -it console-operator-<sha> -- /bin/bash
If you don't know where your
kubeconfig is due to running against multiple clusters this can be handy:
# just a high number oc whoami --loglevel=100 # likely output will be $HOME/.kube/config
If you need to know information about your cluster:
# 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
See the Quick Starts README for contributing console quick starts.