Chapter 32. Customizing the Web Console
32.1. 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-labelling for different environments. You can use the same extension code, but provide settings that change the web console. You can change the look and feel of nearly any aspect of the user interface in this way.
32.2. Loading Extension Scripts and Stylesheets
To add scripts and stylesheets, edit the master configuration file. The scripts and stylesheet files must exist on the Asset Server and are added with the following options:
assetConfig: ... extensionScripts: - /path/to/script1.js - /path/to/script2.js - ... extensionStylesheets: - /path/to/stylesheet1.css - /path/to/stylesheet2.css - ...
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... }());
Relative paths are resolved relative to the master configuration file. To pick up configuration changes, restart the server.
Custom scripts and stylesheets are read once at server start time. To make developing extensions easier, you can reload scripts and stylesheets on every request by enabling development mode with the following setting:
assetConfig: ... extensionDevelopment: true
When set, the web console reloads any changes to existing extension script or stylesheet files when you refresh the page in your browser. You still must restart the server when adding new extension stylesheets or scripts, however. This setting is only recommended for testing changes and not for production.
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.
32.2.1. 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 master-config.yaml file, and use the same extension script across environments. Pass settings from the master-config.yaml file to be used by the extension using the extensionProperties
mechanism:
assetConfig: extensionDevelopment: true extensionProperties: doc_url: https://docs.openshift.com key1: value1 key2: value2 extensionScripts:
This results in a global variable that can be accessed by the extension, as if the following code was executed:
window.OPENSHIFT_EXTENSION_PROPERTIES = { doc_url: "https://docs.openshift.com", key1: "value1", key2: "value2", }
32.3. Customizing the Logo
The following style changes the logo in the web console header:
#header-logo { background-image: url("https://www.example.com/images/logo.png"); width: 190px; height: 20px; }
Replace the example.com URL with a URL to an actual image, and adjust the width and height. The ideal height is 20px.
Save the style to a file (for example, logo.css) and add it to the master configuration file:
assetConfig: ... extensionStylesheets: - /path/to/logo.css
32.4. Changing Links to Documentation
Links to external documentation are shown in various sections of the web console. The following example changes the URL for two given links to the documentation:
window.OPENSHIFT_CONSTANTS.HELP['get_started_cli'] = "https://example.com/doc1.html"; window.OPENSHIFT_CONSTANTS.HELP['basic_cli_operations'] = "https://example.com/doc2.html";
Alternatively, you can change the base URL for all documentation links.
This example would result in the default help URL https://example.com/docs/welcome/index.html
:
window.OPENSHIFT_CONSTANTS.HELP_BASE_URL = "https://example.com/docs/"; 1
- 1
- The path must end in a
/
.
Save this script to a file (for example, help-links.js) and add it to the master configuration file:
assetConfig: ... extensionScripts: - /path/to/help-links.js
32.5. 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:
window.OPENSHIFT_CONSTANTS.CLI = { "Linux (32 bits)": "https://<cdn>/openshift-client-tools-linux-32bit.tar.gz", "Linux (64 bits)": "https://<cdn>/openshift-client-tools-linux-64bit.tar.gz", "Windows": "https://<cdn>/openshift-client-tools-windows.zip", "Mac OS X": "https://<cdn>/openshift-client-tools-mac.zip" };
Alternatively, to point to a page that links the actual download packages, with the Latest Release link text:
window.OPENSHIFT_CONSTANTS.CLI = { "Latest Release": "https://<cdn>/openshift-client-tools/latest.html" };
Save this script to a file (for example, cli-links.js) and add it to the master configuration file:
assetConfig: ... extensionScripts: - /path/to/cli-links.js
32.5.1. Customizing the About Page
To provide a custom About page for the web console:
Write an extension that looks like:
angular .module('aboutPageExtension', ['openshiftConsole']) .config(function($routeProvider) { $routeProvider .when('/about', { templateUrl: 'extensions/about/about.html', controller: 'AboutController' }); } ); hawtioPluginLoader.addModule('aboutPageExtension');
- Save the script to a file (for example, about/about.js).
Write a customized template.
-
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
andversion.master.kubernetes
. - Save the custom template to a file (for example, about/about.html).
Modify the master configuration file:
assetConfig: ... extensionScripts: - about/about.js ... extensions: - name: about sourceDirectory: /path/to/about
-
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:
32.7. Configuring Catalog Categories
Catalog categories organize the display of builder images and templates on the Add to Project page on the OpenShift Container Platform web console. A builder image or template is grouped in a category if it includes a tag with the same name of the category or category alias. Categories only display if one or more builder images or templates with matching tags are present in the catalog.
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.
Create the following configuration scripts within a file (for example, catalog-categories.js):
// Add Go to the Languages category var category = _.find(window.OPENSHIFT_CONSTANTS.CATALOG_CATEGORIES, { id: 'languages' }); category.items.splice(2,0,{ // Insert at the third spot // Required. Must be unique id: "go", // Required label: "Go", // Optional. If specified, defines a unique icon for this item iconClass: "font-icon icon-go-gopher", // Optional. If specified, enables matching other tag values to this category // item categoryAliases: [ "golang" ] }); // Add a Featured category section at the top of the catalog window.OPENSHIFT_CONSTANTS.CATALOG_CATEGORIES.unshift({ // Required. Must be unique id: "featured", // Required label: "Featured", // Optional. If specified, each item in the category will utilize this icon // as a default iconClassDefault: "fa fa-code", items: [ { // Required. Must be unique id: "go", // Required label: "Go", // Optional. If specified, defines a unique icon for this item iconClass: "font-icon icon-go-gopher", // Optional. If specified, enables matching other tag values to this // category item categoryAliases: [ "golang" ], // Optional. If specified, will display below the item label description: "An open source programming language developed at Google in " + "2007 by Robert Griesemer, Rob Pike, and Ken Thompson." }, { // Required. Must be unique id: "jenkins", // Required label: "Jenkins", // Optional. If specified, defines a unique icon for this item iconClass: "font-icon icon-jenkins", // Optional. If specified, will display below the item label description: "An open source continuous integration tool written in Java." } ] });
Save the file and add it to the master configuration at /etc/origin/master/master-config.yml:
assetConfig: ... extensionScripts: - /path/to/catalog-categories.js
Restart the master host:
# systemctl restart atomic-openshift-master
32.8. 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:
openshift
is included in the whitelist by default. Do not remove it.
Create the following configuration scripts within a file (for example, create-from-url-whitelist.js):
// Add a namespace containing the image streams and/or templates window.OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST.push( 'shared-stuff' );
Save the file and add it to the master configuration file at /etc/origin/master/master-config.yml:
assetConfig: ... extensionScripts: - /path/to/create-from-url-whitelist.js
Restart the master host:
# systemctl restart atomic-openshift-master
32.8.1. 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:
Save this script to a file (for example, enable-wildcard-routes.js):
window.OPENSHIFT_CONSTANTS.DISABLE_WILDCARD_ROUTES = false;
Add it to the master configuration file:
assetConfig: ... extensionScripts: - /path/to/enable-wildcard-routes.js
Learn how to configure HAProxy routers to allow 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:
Save this script to a file (for example, enable-wildcard-routes.js):
window.OPENSHIFT_CONSTANTS.DISABLE_WILDCARD_ROUTES = false;
Add it to the master configuration file:
assetConfig: ... extensionScripts: - /path/to/enable-wildcard-routes.js
Learn how to configure HAProxy routers to allow wildcard routes.
32.9. Enabling Features in Technology Preview
Sometimes features are available in Technology Preview. By default, these features are disabled and hidden in the web console.
To enable a Technology Preview feature:
Save this script to a file (for example, tech-preview.js):
window.OPENSHIFT_CONSTANTS.ENABLE_TECH_PREVIEW_FEATURE.<feature_name> = true;
Add it to the master configuration file:
assetConfig: ... extensionScripts: - /path/to/tech-preview.js
32.10. Serving Static Files
You can serve other files from the Asset Server as well. For example, you might want to make the CLI executable available for download from the web console or add images to use in a custom stylesheet.
Add the directory with the files you want using the following configuration option:
assetConfig: ... extensions: - name: images sourceDirectory: /path/to/my_images
The files under the /path/to/my_images directory will be available under the URL /<context>/extensions/images in the web console.
To reference these files from a stylesheet, you should generally use a relative path. For example:
#header-logo { background-image: url("../extensions/images/my-logo.png"); }
32.10.1. Enabling HTML5 Mode
The web console has a special mode for supporting certain static web applications that use the HTML5 history API:
assetConfig: ... extensions: - name: my_extension sourceDirectory: /path/to/myExtension html5Mode: true
Setting html5Mode
to true enables two behaviors:
- Any request for a non-existent file under /<context>/extensions/my_extension/ instead serves /path/to/myExtension/index.html rather than a "404 Not Found" page.
-
The element
<base href="/">
will be rewritten in /path/to/myExtension/index.html to use the actual base depending on the asset configuration; only this exact string is rewritten.
This is needed for JavaScript frameworks such as AngularJS that require base
to be set in index.html.
32.11. Customizing the Login Page
You can also change the login page, and the login provider selection page for the web console. Run the following commands to create templates you can modify:
$ oc adm create-login-template > login-template.html $ oc adm create-provider-selection-template > provider-selection-template.html
Edit the file to change the styles or add content, but be careful not to remove any required parameters inside the curly brackets.
To use your custom login page or provider selection page, set the following options in the master configuration file:
oauthConfig: ... templates: login: /path/to/login-template.html providerSelection: /path/to/provider-selection-template.html
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.
32.11.1. 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.
32.12. 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
andErrorCode
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.
32.13. Changing the Logout URL
You can change the location a console user is sent to when logging out of the console by modifying the logoutURL
parameter in the /etc/origin/master/master-config.yaml file:
... assetConfig: logoutURL: "http://www.example.com" ...
This can be useful when authenticating with Request Header and OAuth or OpenID identity providers, which require visiting an external URL to destroy single sign-on sessions.
32.14. Configuring Web Console Customizations with Ansible
During advanced installations, many modifications to the web console can be configured using the following parameters, which are configurable in the inventory file:
Example Web Console Customization with Ansible
# Configure logoutURL in the master config for console customization # See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#changing-the-logout-url #openshift_master_logout_url=http://example.com # Configure extensionScripts in the master config for console customization # See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets #openshift_master_extension_scripts=['/path/on/host/to/script1.js','/path/on/host/to/script2.js'] # Configure extensionStylesheets in the master config for console customization # See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets #openshift_master_extension_stylesheets=['/path/on/host/to/stylesheet1.css','/path/on/host/to/stylesheet2.css'] # Configure extensions in the master config for console customization # See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#serving-static-files #openshift_master_extensions=[{'name': 'images', 'sourceDirectory': '/path/to/my_images'}] # Configure extensions in the master config for console customization # See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#serving-static-files #openshift_master_oauth_template=/path/on/host/to/login-template.html # Configure metricsPublicURL in the master config for cluster metrics. Ansible is also able to configure metrics for you. # See: https://docs.openshift.com/enterprise/latest/install_config/cluster_metrics.html #openshift_master_metrics_public_url=https://hawkular-metrics.example.com/hawkular/metrics # Configure loggingPublicURL in the master config for aggregate logging. Ansible is also able to install logging for you. # See: https://docs.openshift.com/enterprise/latest/install_config/aggregate_logging.html #openshift_master_logging_public_url=https://kibana.example.com