Overview

Administrators can customize the
web
console using extensions, which let you run scripts and load custom stylesheets
when the web console loads. Extension scripts allow you to override the default
behavior of the web console and customize it for your needs.

For example, extension scripts can be used to add your own
company’s branding or to add company-specific capabilities. A common use case
for this is rebranding or white-labeling for different environments. You can
use the same extension code, but provide settings that change the web console.

Take caution making extensive changes to the web console styles or behavior
that are not documented below. While you add any scripts or stylesheets,
significant customizations might need to be reworked on upgrades as the web
console markup and behavior change in future versions.

Loading Extension Scripts and Stylesheets

As of OpenShift Container Platform 3.9, extension scripts and stylesheets can be hosted at
any https:// URL as long as the URL is accessible from the browser. The files
might be hosted from a pod on the platform using a publicly accessible route,
or on another server outside of OpenShift Container Platform.

To add scripts and stylesheets, edit the webconsole-config ConfigMap in the
openshift-web-console namespace. The web console configuration is available
in the webconsole-config.yaml key of the ConfigMap.

$ oc edit configmap/webconsole-config -n openshift-web-console

To add scripts, update the extensions.scriptURLs property. The value is an
array of URLs.

To add stylesheets, update the extensions.stylesheetURLs property. The value
is an array of URLs.

After saving the ConfigMap, the web console containers will be updated
automatically for the new extension files within a few minutes.

Scripts and stylesheets must be served with the correct content type or they
will not be run by the browser. Scripts must be served with
Content-Type: application/javascript
and stylesheets with
Content-Type: text/css.

It is a best practice to wrap extension scripts in an Immediately Invoked
Function Expression (IIFE). This ensures that you do not create global
variables that conflict with the names used by the web console or by other
extensions. For example:

(function() {
// Put your extension code here...
}());

The examples in the following sections show common ways you can customize the
web console.

Additional extension examples are available in the
OpenShift
Origin repository on GitHub.

Setting Extension Properties

If you have a specific extension, but want to use different text in it for each
of the environments, you can define the environment in the
web console configuration, and use the same extension script across environments.

To add extension properties, edit the webconsole-config ConfigMap in the
openshift-web-console namespace. The web console configuration is available
in the webconsole-config.yaml key of the ConfigMap.

$ oc edit configmap/webconsole-config -n openshift-web-console

Update the extensions.properties value, which is a map of key-value pairs.

Customizing Documentation Links

Documentation links on the landing page are customizable.
window.OPENSHIFT_CONSTANTS.CATALOG_HELP_RESOURCES is an array of objects
containing a title and an href. These will be turned into links. You can
completely override the array, push or pop additional links, or modify the
attributes of existing links. For example:

Adding or Changing Links to Download the CLI

The About page in the web console provides download links for the
command line interface (CLI) tools. These
links can be configured by providing both the link text and URL, so that you can
choose to point them directly to file packages, or to an external page that
points to the actual packages.

For example, to point directly to packages that can be downloaded, where the
link text is the package platform:

Start from the version of
about.html
from the OpenShift Container Platform
release you are
using. Within the template, there are two angular scope variables available:
version.master.openshift and version.master.kubernetes.

Host the template at a URL with the correct Cross-Origin Resource Sharing
(CORS) response headers for the web console.

Set Access-Control-Allow-Origin response to allow requests from the web console domain.

Set Access-Control-Allow-Methods to include GET.

Set Access-Control-Allow-Headers to include Content-Type.

Alternatively, you can include the template directly in your JavaScript using AngularJS
$templateCache.

Application Launcher

The top navigation bar also contains an optional application launcher for
linking to other web applications. This dropdown menu is empty by default, but
when links are added, appears to the left of the help menu in the masthead.

System Status Badge

The top navigation bar can also include an optional system status badge in order
to notify users of system-wide events such as maintenance windows. To make use
of the existing styles using a yellow warning icon for the badge, follow the
example below.

Project Left Navigation

When navigating within a project, a menu appears on the left with primary and
secondary navigation. This menu structure is defined as a constant and can be
overridden or modified.

Significant customizations to the project navigation may affect the user
experience and should be done with careful consideration. You may need to update
this customization in future upgrades if you modify existing navigation items.

Configuring Catalog Categories

Catalog categories organize the display of items in the web console catalog
landing page. Each category has one or more subcategories. A builder image,
template, or service is grouped in a subcategory if it includes a tag listed in
the matching subcategory tags, and an item can appear in more than one subcategory.
Categories and subcategories only display if they contain at least one item.

Significant customizations to the catalog categories may affect the user
experience and should be done with careful consideration. You may need to update
this customization in future upgrades if you modify existing category items.

Configuring the Create From URL Namespace Whitelist

Create from URL
only works with image streams or templates from namespaces that have been
explicitly specified in OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST. To add
namespaces to the whitelist, follow these steps:

Disabling the Copy Login Command

The web console allows users to copy a login command, including the current
access token, to the clipboard from the user menu and the Command Line Tools
page. This function can be changed so that the user’s access token is not
included in the copied command.

// Do not copy the user's access token in the copy login command.
window.OPENSHIFT_CONSTANTS.DISABLE_COPY_LOGIN_COMMAND = true;

Enabling Wildcard Routes

If you enabled wildcard routes for a router, you can also enable wildcard
routes in the web console. This lets users enter hostnames starting with an
asterisk like *.example.com when creating a route. To enable wildcard routes:

Relative paths are resolved relative to the master configuration file. You must
restart the server after changing this configuration.

When there are multiple login providers configured or when the
alwaysShowProviderSelection
option in the master-config.yaml file is set to true, each time a user’s
token to OpenShift Container Platform expires, the user is presented with this custom page
before they can proceed with other tasks.

Example Usage

Custom login pages can be used to create Terms of Service information. They can
also be helpful if you use a third-party login provider, like GitHub or Google,
to show users a branded page that they trust and expect before being redirected
to the authentication provider.

Customizing the OAuth Error Page

When errors occur during authentication, you can change the page shown.

Run the following command to create a template you can modify:

$ oc adm create-error-template > error-template.html

Edit the file to change the styles or add content.

You can use the Error and ErrorCode variables in the template. To use
your custom error page, set the following option in the master configuration
file:

oauthConfig:
...templates:
error: /path/to/error-template.html

Relative paths are resolved relative to the master configuration file.

You must restart the server after changing this configuration.

Changing the Logout URL

You can change the location a console user is sent to when logging out of
the console by modifying the clusterInfo.logoutPublicURL parameter in the
webconsole-config ConfigMap.