An operator for OpenShift Console.
The console-operator installs and maintains the web console on a cluster.
The console operator is installed by default and will automatically maintain a console.
- 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
- On MacOS you may need to execute
To avoid some of the standard quirks of gopath
, the recommended way to clone and
work with this repository is to do the following:
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.
mkdir -p $HOME/gopaths/consoleoperator
Now get the repository from github.
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.
cd src/github.com/openshift/console-operator/
git remote rename origin upstream
git remote add origin {Your fork url}
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:
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
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)
Running the make
command will build the binary:
make
The binary output will be:
./_output/local/bin/<os>/<arch>/console
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.
Test gofmt
and other verification tools:
make verify
Let gofmt
automatically update your source:
gofmt -w ./pkg
gofmt -w ./cmd
make test-unit
It is suggested to run integration
and e2e
tests with CI. This is automatic when opening a PR.
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.
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.
Visit https://try.openshift.com/, download the installer and create a cluster. Instructions (including pull secret) are maintained here.
# 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.
We don't want the default console-operator
to run if we are going to test our own. Therefore, do
the following:
# 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.
Typically to build your binary you will use the make
command:
# 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:
# 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 -f Dockerfile.rhel7 -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 manifests/07-operator.yaml
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 07-operator-alt-image.yaml
file:
# 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.
imagePullPolicy: Always
At this point, your pattern will be
- Change code
- Build a new docker image
- This will automatically & implicitly
make build
a new binary
- This will automatically & implicitly
- 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
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.