Use custom icons for your OpenShift Templates

OpenShift provides a powerful mechanism for easily creating new related Kubernetes objects allowing parameterization in a single action : it is called Templates. Templates serve the same purpose as Helm Charts ; however they’re tightly integrated with OpenShift web console and oc CLI tool so that they make things easily consumable for developers.

Templates are grouped and categorized within a catalog with fancy icons for those embedded within the platform or provided through Red Hat Middleware.

A recurring question from users bringing their own template is “how to customize my own template icons?”. Though I know it was feasible, I didn’t actually make it until today and found documentation was not straightforward… So the reason of this post ;-)

This post is a walkthrough how to bring your own custom template icon into OpenShift. We’ll use the Microcks project I’m working on as a show case on how to do that. This method has been tested on OpenShift 3.9 cluster and should also work for latest versions.

Custom CSS preparation

First step of this how-to is to create a CSS file and class for referencing your custom icon and its display options. For convenience, you may want to encode your PNG or SVG icon image into a base64 string that will be embedded directly into your CSS.

In order to do that, prepare a resized version of your image (if you are using PNG) that could fit into a 50x50 square and use a service like https://www.base64-image.de/ to get encoded version of your image.

Here, I have named my CSS class icon-microcks and because it is not squared, I have forced width and height attributes to be different to not change the proportions of the icon.

.icon-microcks {
background-image: url('data:image/png;base64,iVBO[...]Jggg==');
width: 50px;
height: 44px;
display: block;
float: left;
}

Now, make sure to make this CSS file available by publishing it onto the we server of your choice. I have published my CSS file at https://microcks.github.io/assets/css/openshift-console.css on the GitHub Pages site for Microcks.

Attention : be sure to publish your CSS on a server that treat it as a text/css content. I first try just publishing on regular GitHub repository and retrieve it as a raw.githubusercontent.com content but this does not work as GitHub just returns text/plain informations.

Web Console extension

Second step is to edit the webconsole-config ConfigMap of the openshift-web-console namespace. You’ll need cluster-admin privileges for that. Into this ConfigMap, find the stylesheetURLs attribute in the webconsole-config.yaml key and just add your URL for custom CSS file.

extensions:
properties: {}
scriptURLs: []
stylesheetURLs:
https://microcks.github.io/assets/css/openshift-console.css

Save your modification and now — assuming you’re logged into the cluster and on the openshift-web-console project — just delete the Web Console Pod to force refreshing the CSS extension. This can be done using :

oc delete pod `oc get pods | grep webconsole | awk '{print $1}'`

A new Pod will take a few second to be restarted by OpenShift.

Template update

Third and last step is now to edit your Template object and to add an iconClass attribute to the annotations of its metadata block. This attribute value just have to reference the name of the CSS class you previously define.

So for example, in the case of the Microcks template, we’ll found:

metadata:
annotations:
description: 'Template for Microcks application (see http://microcks.github.io)'
iconClass: icon-microcks
tags: instant-app
name: microcks-persistent

Just save your modifications into OpenShift by saving if you direct edit it of applying new template version.

After this last edit, make sure to force refresh your browser tab so that it reloads new CSS definitions from Web Console and new Template definitions from Service Catalog.

Final test

Launch a new component creation through the Add to Project action button and just see your new customized fancy icon appear. Tadam! 😃