assetConfig:
...
extensionScripts:
- /path/to/script1.js
- /path/to/script2.js
- ...
extensionStylesheets:
- /path/to/stylesheet1.css
- /path/to/stylesheet2.css
- ...
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.
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:
|
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. |
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",
}
As of OpenShift Container Platform 3.6, there is an extension option to link to external logging solutions instead of using OpenShift Container Platform’s EFK logging stack:
'use strict'; angular.module("mylinkextensions", ['openshiftConsole']) .run(function(extensionRegistry) { extensionRegistry.add('log-links', _.spread(function(resource, options) { return { type: 'dom', node: '<span><a href="https://extension-point.example.com">' + resource.metadata.name + '</a><span class="action-divider">|</span></span>' }; })); }); hawtioPluginLoader.addModule("mylinkextensions");
The URL to the logging stack you are wanting to accessAD master configuration file. Then, restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
A guided tour will pop up the first time a user logs in on a particular browser.
You can enable the auto_launch
for new users:
window.OPENSHIFT_CONSTANTS.GUIDED_TOURS.landing_page_tour.auto_launch = true;
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.
{ title: 'Blog', href: 'https://blog.openshift.com' }
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
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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
and version.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
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
The top navigation bar of the web console contains the help icon and the user dropdown menus. You can add additional menu items to these using the angular-extension-registry.
The available extension points are:
nav-help-dropdown
- the help icon dropdown menu, visible at desktop screen widths
nav-user-dropdown
- the user dropdown menu, visible at desktop screen widths
nav-dropdown-mobile
- the single menu for top navigation items at mobile screen widths
The following example extends the nav-help-dropdown
menu, with a name of
<myExtensionModule>
:
|
angular
.module('<myExtensionModule>', ['openshiftConsole'])
.run([
'extensionRegistry',
function(extensionRegistry) {
extensionRegistry
.add('nav-help-dropdown', function() {
return [
{
type: 'dom',
node: '<li><a href="http://www.example.com/report" target="_blank">Report a Bug</a></li>'
}, {
type: 'dom',
node: '<li class="divider"></li>' // If you want a horizontal divider to appear in the menu
}, {
type: 'dom',
node: '<li><a href="http://www.example.com/status" target="_blank">System Status</a></li>'
}
];
});
}
]);
hawtioPluginLoader.addModule('<myExtensionModule>');
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.
Create the configuration scripts within a file (for example, applicationLauncher.js):
// Add items to the application launcher dropdown menu.
window.OPENSHIFT_CONSTANTS.APP_LAUNCHER_NAVIGATION = [{
title: "Dashboard", // The text label
iconClass: "fa fa-dashboard", // The icon you want to appear
href: "http://example.com/dashboard", // Where to go when this item is clicked
tooltip: 'View dashboard' // Optional tooltip to display on hover
}, {
title: "Manage Account",
iconClass: "pficon pficon-user",
href: "http://example.com/account",
tooltip: "Update email address or password."
}];
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/applicationLauncher.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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.
Create the configuration scripts within a file (for example, systemStatusBadge.js):
'use strict';
angular
.module('mysystemstatusbadgeextension', ['openshiftConsole'])
.run([
'extensionRegistry',
function(extensionRegistry) {
// Replace http://status.example.com/ with your domain
var system_status_elem = $('<a href="http://status.example.com/"' +
'target="_blank" class="nav-item-iconic system-status"><span title="' +
'System Status" class="fa status-icon pficon-warning-triangle-o">' +
'</span></a>');
// Add the extension point to the registry so the badge appears
// To disable the badge, comment this block out
extensionRegistry
.add('nav-system-status', function() {
return [{
type: 'dom',
node: system_status_elem
}];
});
}
]);
hawtioPluginLoader.addModule('mysystemstatusbadgeextension');
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/systemStatusBadge.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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. |
Create the configuration scripts within a file (for example, navigation.js):
// Append a new primary nav item. This is a simple direct navigation item
// with no secondary menu.
window.OPENSHIFT_CONSTANTS.PROJECT_NAVIGATION.push({
label: "Dashboard", // The text label
iconClass: "fa fa-dashboard", // The icon you want to appear
href: "/dashboard" // Where to go when this nav item is clicked.
// Relative URLs are pre-pended with the path
// '/project/<project-name>'
});
// Splice a primary nav item to a specific spot in the list. This primary item has
// a secondary menu.
window.OPENSHIFT_CONSTANTS.PROJECT_NAVIGATION.splice(2, 0, { // Insert at the third spot
label: "Git",
iconClass: "fa fa-code",
secondaryNavSections: [ // Instead of an href, a sub-menu can be defined
{
items: [
{
label: "Branches",
href: "/git/branches",
prefixes: [
"/git/branches/" // Defines prefix URL patterns that will cause
// this nav item to show the active state, so
// tertiary or lower pages show the right context
]
}
]
},
{
header: "Collaboration", // Sections within a sub-menu can have an optional header
items: [
{
label: "Pull Requests",
href: "/git/pull-requests",
prefixes: [
"/git/pull-requests/"
]
}
]
}
]
});
// Add a primary item to the top of the list. This primary item is shown conditionally.
window.OPENSHIFT_CONSTANTS.PROJECT_NAVIGATION.unshift({
label: "Getting Started",
iconClass: "pficon pficon-screen",
href: "/getting-started",
prefixes: [ // Primary nav items can also specify prefixes to trigger
"/getting-started/" // active state
],
isValid: function() { // Primary or secondary items can define an isValid
return isNewUser; // function. If present it will be called to test whether
// the item should be shown, it should return a boolean
}
});
// Modify an existing menu item
var applicationsMenu = _.find(window.OPENSHIFT_CONSTANTS.PROJECT_NAVIGATION, { label: 'Applications' });
applicationsMenu.secondaryNavSections.push({ // Add a new secondary nav section to the Applications menu
// my secondary nav section
});
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/navigation.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
The web console has an optional list of featured application links in its landing page catalog. These appear near the top of the page and can have an icon, a title, a short description, and a link.
Create the following configuration scripts within a file (for example, featured-applications.js):
// Add featured applications to the top of the catalog.
window.OPENSHIFT_CONSTANTS.SAAS_OFFERINGS = [{
title: "Dashboard", // The text label
icon: "fa fa-dashboard", // The icon you want to appear
url: "http://example.com/dashboard", // Where to go when this item is clicked
description: "Open application dashboard." // Short description
}, {
title: "System Status",
icon: "fa fa-heartbeat",
url: "http://example.com/status",
description: "View system alerts and outages."
}, {
title: "Manage Account",
icon: "pficon pficon-user",
url: "http://example.com/account",
description: "Update email address or password."
}];
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/featured-applications.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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. |
Create the following configuration scripts within a file (for example, catalog-categories.js):
// Find the Languages category.
var category = _.find(window.OPENSHIFT_CONSTANTS.SERVICE_CATALOG_CATEGORIES,
{ id: 'languages' });
// Add Go as a new subcategory under Languages.
category.subCategories.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.
icon: "icon-go-gopher",
// Required. Items matching any tag will appear in this subcategory.
tags: [
"go",
"golang"
]
});
// Add a Featured category as the first category tab.
window.OPENSHIFT_CONSTANTS.SERVICE_CATALOG_CATEGORIES.unshift({
// Required. Must be unique.
id: "featured",
// Required
label: "Featured",
subCategories: [
{
// Required. Must be unique.
id: "go",
// Required.
label: "Go",
// Optional. If specified, defines a unique icon for this item.
icon: "icon-go-gopher",
// Required. Items matching any tag will appear in this subcategory.
tags: [
"go",
"golang"
]
},
{
// Required. Must be unique.
id: "jenkins",
// Required.
label: "Jenkins",
// Optional. If specified, defines a unique icon for this item.
icon: "icon-jenkins",
// Required. Items matching any tag will appear in this subcategory.
tags: [
"jenkins"
]
}
]
});
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/catalog-categories.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
Whenever a user reaches a quota, a quota notification is put into the notification drawer. A custom quota notification message, per quota resource type, can be added to the notification. For example: "Your project is over quota. It is using 200% of 2 cores CPU (Limit). Upgrade to <a href='http://www.openshift.com'> OpenShift Pro</a> if you need additional resources.". The "Upgrade to…" part of the notification is the custom message and may contain HTML such as links to additional resources.
Create the following configuration scripts within a file (for example, quota-messages.js):
// Set custom notification messages per quota type/key
window.OPENSHIFT_CONSTANTS.QUOTA_NOTIFICATION_MESSAGE = {
"pods": 'Upgrade to <a href="http://www.openshift.com">OpenShift Pro</a> if you need additional resources.',
"limits.memory": 'Upgrade to <a href="http://www.openshift.com">OpenShift Online Pro</a> if you need additional resources.'
}
Save the file and add it to the master configuration at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/quota-messages.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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:
|
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.yaml:
assetConfig:
...
extensionScripts:
- /path/to/create-from-url-whitelist.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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.
Create the following configuration scripts within a file (for example, disable-copy-login.js):
// Do not copy the user's access token in the copy login command.
window.OPENSHIFT_CONSTANTS.DISABLE_COPY_LOGIN_COMMAND = true;
Save the file and add it to the master configuration file at /etc/origin/master/master-config.yaml:
assetConfig:
...
extensionScripts:
- /path/to/disable-copy-login.js
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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
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
Restart the master host:
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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
Restart the master host:
# systemctl restart origin-master-api origin-master-controllers # systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
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");
}
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.
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.
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.
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.
During advanced installations, many modifications to the web console can be configured using the following parameters, which are configurable in the inventory file:
# 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