Customizing the web console | Web console

Adding a custom logo and product name
Creating custom links in the web console
Customizing console routes
- Customizing the console route
- Customizing the download route
Customizing the login page
Defining a template for an external log link
Creating custom notification banners
Customizing CLI downloads
Adding YAML examples to Kubernetes resources

You can customize the OKD web console to set a custom logo, product name, links, notifications, and command line downloads. This is especially helpful if you need to tailor the web console to meet specific corporate or government requirements.

Adding a custom logo and product name

You can create custom branding by adding a custom logo or custom product name. You can set both or one without the other, as these settings are independent of each other.

Prerequisites

You must have administrator privileges.
Create a file of the logo that you want to use. The logo can be a file in any common image format, including GIF, JPG, PNG, or SVG, and is constrained to a max-height of 60px.

Procedure

Import your logo file into a config map in the openshift-config namespace:

$ oc create configmap console-custom-logo --from-file /path/to/console-custom-logo.png -n openshift-config

You can alternatively apply the following YAML to create the config map:

apiVersion: v1
kind: ConfigMap
metadata:
  name: console-custom-logo
  namespace: openshift-config
binaryData:
  console-custom-logo.png: <base64-encoded_logo> ... (1)

1	Provide a valid base64-encoded logo.

Edit the web console’s Operator configuration to include customLogoFile and customProductName:

$ oc edit consoles.operator.openshift.io cluster

apiVersion: operator.openshift.io/v1
kind: Console
metadata:
  name: cluster
spec:
  customization:
    customLogoFile:
      key: console-custom-logo.png
      name: console-custom-logo
    customProductName: My Console

Once the Operator configuration is updated, it will sync the custom logo config map into the console namespace, mount it to the console pod, and redeploy.

Check for success. If there are any issues, the console cluster Operator will report a Degraded status, and the console Operator configuration will also report a CustomLogoDegraded status, but with reasons like KeyOrFilenameInvalid or NoImageProvided.

To check the clusteroperator, run:
```
$ oc get clusteroperator console -o yaml
```
To check the console Operator configuration, run:
```
$ oc get consoles.operator.openshift.io -o yaml
```

Creating custom links in the web console

Prerequisites

You must have administrator privileges.

Procedure

From Administration → Custom Resource Definitions, click on ConsoleLink.
Select Instances tab

Click Create Console Link and edit the file:

apiVersion: console.openshift.io/v1
kind: ConsoleLink
metadata:
  name: example
spec:
  href: 'https://www.example.com'
  location: HelpMenu (1)
  text: Link 1

1	Valid location settings are `HelpMenu`, `UserMenu`, `ApplicationMenu`, and `NamespaceDashboard`.

To make the custom link appear in all namespaces, follow this example:

apiVersion: console.openshift.io/v1
kind: ConsoleLink
metadata:
  name: namespaced-dashboard-link-for-all-namespaces
spec:
  href: 'https://www.example.com'
  location: NamespaceDashboard
  text: This appears in all namespaces

To make the custom link appear in only some namespaces, follow this example:

apiVersion: console.openshift.io/v1
kind: ConsoleLink
metadata:
  name: namespaced-dashboard-for-some-namespaces
spec:
  href: 'https://www.example.com'
  location: NamespaceDashboard
  # This text will appear in a box called "Launcher" under "namespace" or "project" in the web console
  text: Custom Link Text
  namespaceDashboard:
    namespaces:
    # for these specific namespaces
    - my-namespace
    - your-namespace
    - other-namespace

To make the custom link appear in the application menu, follow this example:

apiVersion: console.openshift.io/v1
kind: ConsoleLink
metadata:
  name: application-menu-link-1
spec:
  href: 'https://www.example.com'
  location: ApplicationMenu
  text: Link 1
  applicationMenu:
    section: My New Section
    # image that is 24x24 in size
    imageURL: https://via.placeholder.com/24

Click Save to apply your changes.

Customizing console routes

For console and downloads routes, custom routes functionality uses the ingress config route configuration API. If the console custom route is set up in both the ingress config and console-operator config, then the new ingress config custom route configuration takes precedent. The route configuration with the console-operator config is deprecated.

Customizing the console route

You can customize the console route by setting the custom hostname and TLS certificate in the spec.componentRoutes field of the cluster Ingress configuration.

Prerequisites

You have logged in to the cluster as a user with administrative privileges.
You have created a secret in the openshift-config namespace containing the TLS certificate and key. This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.

You can create a TLS secret by using the oc create secret tls command.

Procedure

Edit the cluster Ingress configuration:

$ oc edit ingress.config.openshift.io cluster

Set the custom hostname and optionally the serving certificate and key:

apiVersion: config.openshift.io/v1
kind: Ingress
metadata:
  name: cluster
spec:
  componentRoutes:
    - name: console
      namespace: openshift-console
      hostname: <custom_hostname> (1)
      servingCertKeyPairSecret:
        name: <secret_name> (2)

1	The custom hostname.
2	Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.

Save the file to apply the changes.

Customizing the download route

You can customize the download route by setting the custom hostname and TLS certificate in the spec.componentRoutes field of the cluster Ingress configuration.

Prerequisites

You have logged in to the cluster as a user with administrative privileges.
You have created a secret in the openshift-config namespace containing the TLS certificate and key. This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.

You can create a TLS secret by using the oc create secret tls command.

Procedure

Edit the cluster Ingress configuration:

$ oc edit ingress.config.openshift.io cluster

Set the custom hostname and optionally the serving certificate and key:

apiVersion: config.openshift.io/v1
kind: Ingress
metadata:
  name: cluster
spec:
  componentRoutes:
    - name: downloads
      namespace: openshift-console
      hostname: <custom_hostname> (1)
      servingCertKeyPairSecret:
        name: <secret_name> (2)

1	The custom hostname.
2	Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.

Save the file to apply the changes.

Create Terms of Service information with custom login pages. Custom login pages can also be helpful if you use a third-party login provider, such as GitHub or Google, to show users a branded page that they trust and expect before being redirected to the authentication provider. You can also render custom error pages during the authentication process.

Customizing the error template is limited to identity providers (IDPs) that use redirects, such as request header and OIDC-based IDPs. It does not have an effect on IDPs that use direct password authentication, such as LDAP and htpasswd.

Prerequisites

You must have administrator privileges.

Procedure

Run the following commands to create templates you can modify:

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

$ oc adm create-provider-selection-template > providers.html

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

Create the secrets:

$ oc create secret generic login-template --from-file=login.html -n openshift-config

$ oc create secret generic providers-template --from-file=providers.html -n openshift-config

$ oc create secret generic error-template --from-file=errors.html -n openshift-config

Run:
```
$ oc edit oauths cluster
```

Update the specification:

spec:
  templates:
    error:
        name: error-template
    login:
        name: login-template
    providerSelection:
        name: providers-template

Run oc explain oauths.spec.templates to understand the options.

Defining a template for an external log link

If you are connected to a service that helps you browse your logs, but you need to generate URLs in a particular way, then you can define a template for your link.

Prerequisites

You must have administrator privileges.

Procedure

From Administration → Custom Resource Definitions, click on ConsoleExternalLogLink.
Select Instances tab

Click Create Console External Log Link and edit the file:

apiVersion: console.openshift.io/v1
kind: ConsoleExternalLogLink
metadata:
  name: example
spec:
  hrefTemplate: >-
    https://example.com/logs?resourceName=${resourceName}&containerName=${containerName}&resourceNamespace=${resourceNamespace}&podLabels=${podLabels}
  text: Example Logs

Creating custom notification banners

Prerequisites

You must have administrator privileges.

Procedure

From Administration → Custom Resource Definitions, click on ConsoleNotification.
Select Instances tab

Click Create Console Notification and edit the file:

apiVersion: console.openshift.io/v1
kind: ConsoleNotification
metadata:
  name: example
spec:
  text: This is an example notification message with an optional link.
  location: BannerTop (1)
  link:
    href: 'https://www.example.com'
    text: Optional link text
  color: '#fff'
  backgroundColor: '#0088ce'

1	Valid location settings are `BannerTop`, `BannerBottom`, and `BannerTopBottom`.

Click Create to apply your changes.

Customizing CLI downloads

You can configure links for downloading the CLI with custom link text and URLs, which can point directly to file packages or to an external page that provides the packages.

Prerequisites

You must have administrator privileges.

Procedure

Navigate to Administration → Custom Resource Definitions.
Select ConsoleCLIDownload from the list of Custom Resource Definitions (CRDs).

Click the YAML tab, and then make your edits:

apiVersion: console.openshift.io/v1
kind: ConsoleCLIDownload
metadata:
  name: example-cli-download-links-for-foo
spec:
  description: |
    This is an example of download links for foo
  displayName: example-foo
  links:
  - href: 'https://www.example.com/public/foo.tar'
    text: foo for linux
  - href: 'https://www.example.com/public/foo.mac.zip'
    text: foo for mac
  - href: 'https://www.example.com/public/foo.win.zip'
    text: foo for windows

Click the Save button.

Adding YAML examples to Kubernetes resources

You can dynamically add YAML examples to any Kubernetes resources at any time.

Prerequisites

You must have cluster administrator privileges.

Procedure

From Administration → Custom Resource Definitions, click on ConsoleYAMLSample.

Click YAML and edit the file:

apiVersion: console.openshift.io/v1
kind: ConsoleYAMLSample
metadata:
  name: example
spec:
  targetResource:
    apiVersion: batch/v1
    kind: Job
  title: Example Job
  description: An example Job YAML sample
  yaml: |
    apiVersion: batch/v1
    kind: Job
    metadata:
      name: countdown
    spec:
      template:
        metadata:
          name: countdown
        spec:
          containers:
          - name: counter
            image: centos:7
            command:
            - "bin/bash"
            - "-c"
            - "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"
          restartPolicy: Never

Use spec.snippet to indicate that the YAML sample is not the full YAML resource definition, but a fragment that can be inserted into the existing YAML document at the user’s cursor.

Click Save.

Customizing the web console in OKD

Adding a custom logo and product name

Creating custom links in the web console

Customizing console routes

Customizing the console route

Customizing the download route

Customizing the login page

Defining a template for an external log link

Creating custom notification banners

Customizing CLI downloads

Adding YAML examples to Kubernetes resources