第35章 Web コンソールのカスタマイズ

管理者は拡張機能を使用して Web コンソールをカスタマイズできます。拡張機能でスクリプトを実行すると、Web コンソールを読み込む際にカスタムスタイルシートを読み込むことができます。拡張スクリプトによって、Web コンソールのデフォルト動作を上書きし、必要に応じてカスタマイズできます。

たとえば、拡張スクリプトを使用して、自社独自のブランディングを追加したり、自社固有の機能を追加したりすることができます。この使用例として一般的なのは、さまざまな環境のリブランディングやホワイトラベリングです。同じ拡張コードを使用しながら、Web コンソールを変更する設定を指定できます。

OpenShift Container Platform 3.9 では、拡張スクリプトとスタイルシートは、URL がブラウザーからアクセス可能であれば、任意の https:// URL でホストできます。ファイルは、パブリックにアクセスできるルートを使用してプラットフォーム上の Pod からや OpenShift Container Platform 外部の別のサーバー上の Pod からホストできます。

スクリプトとスタイルシートを追加するには、openshift-web-console namespace で webconsole-configConfigMap を編集します。Web コンソール設定は ConfigMap の webconsole-config.yaml キーにあります。

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

スクリプトを追加するには、extensions.scriptURLs プロパティーを更新します。値は URL の配列です。

スタイルシートを追加するには、extensions.stylesheetURLs プロパティーを更新します。値は URL の配列です。

apiVersion: v1
kind: ConfigMap
data:
  webconsole-config.yaml: |
    apiVersion: webconsole.config.openshift.io/v1
    extensions:
      scriptURLs:
        - https://example.com/scripts/menu-customization.js
        - https://example.com/scripts/nav-customization.js
      stylesheetURLs:
        - https://example.com/styles/logo.css
        - https://example.com/styles/custom-styles.css
    [...]

ConfigMap を保存した後、Web コンソールコンテナーは数分以内に新規の拡張ファイルについて自動的に更新されます。

最良の実践例として、拡張スクリプトを Immediately Invoked Function Expression (IIFE) でラップすることができます。これにより、Web コンソールや他の拡張で使用される名前と競合するグローバル変数を作成することを防ぐことができます。以下は例になります。

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

以降のセクションの例では、Web コンソールをカスタマイズする一般的な方法を示します。

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

apiVersion: v1
kind: ConfigMap
data:
  webconsole-config.yaml: |
    apiVersion: webconsole.config.openshift.io/v1
    extensions:
      [...]
      properties:
        doc_url: https://docs.openshift.com
        key1: value1
        key2: value2
    [...]

window.OPENSHIFT_EXTENSION_PROPERTIES = {
  doc_url: "https://docs.openshift.com",
  key1: "value1",
  key2: "value2"
}

OpenShift Container Platform 3.6 には、OpenShift Container Platform の EFK ロギングスタックを使用しなくても外部ロギングソリューションにリンクできる拡張オプションがあります。

'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");

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

ユーザーの特定ブラウザーへの初回ログイン時に、ガイド付きツアーが表示されます。新規ユーザーに対して auto_launch を有効にできます。

window.OPENSHIFT_CONSTANTS.GUIDED_TOURS.landing_page_tour.auto_launch = true;

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

ランディングページのドキュメントリンクはカスタマイズできます。window.OPENSHIFT_CONSTANTS.CATALOG_HELP_RESOURCES はタイトルと href を含むオブジェクトの配列で、これらはリンクに変換されます。この配列を完全に上書きしたり、追加のリンクをプッシュまたはポップしたり、既存のリンクの属性を変更したりすることができます。以下は例になります。

window.OPENSHIFT_CONSTANTS.CATALOG_HELP_RESOURCES.push({
  title: 'Blog',
  href: 'https://blog.openshift.com'
});

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

以下のスタイルでは、Web コンソールヘッダーのロゴを変更します。

#header-logo {
  background-image: url("https://www.example.com/images/logo.png");
  width: 190px;
  height: 20px;
}

example.com URL を実際のイメージへの URL に置換して、幅と高さを調整します。理想的な高さは 20px です。

「拡張スクリプトとスタイルシートの読み込み」で説明されているスタイルシートを追加します。

メンバーシップページのデフォルトのホワイトリストには、admin、basic-user、edit などのクラスターロールのサブセットだけでなく、プロジェクト内に定義されているカスタムロールが表示されます。

たとえば、ホワイトリストに、独自のカスタムのクラスターロールセットを追加します。

window.OPENSHIFT_CONSTANTS.MEMBERSHIP_WHITELIST = [
  "admin",
  "basic-user",
  "edit",
  "system:deployer",
  "system:image-builder",
  "system:image-puller",
  "system:image-pusher",
  "view",
  "custom-role-1",
  "custom-role-2"
];

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

Web コンソールのさまざまなセクションに、外部ドキュメントへのリンクが表示されます。以下の例では、ドキュメントへの指定された 2 つのリンクの URL を変更します。

window.OPENSHIFT_CONSTANTS.HELP['get_started_cli']      = "https://example.com/doc1.html";
window.OPENSHIFT_CONSTANTS.HELP['basic_cli_operations'] = "https://example.com/doc2.html";

または、すべてのドキュメントリンクのベース URL を変更できます。

この例では、デフォルトのヘルプ URL https://example.com/docs/welcome/index.html が作成されます。

window.OPENSHIFT_CONSTANTS.HELP_BASE_URL = "https://example.com/docs/"; 1

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

Web コンソールの About ページには、コマンドラインインターフェース (CLI) ツールのダウンロードリンクがあります。これらのリンクはリンクテキストと URL の両方を提供して設定でき、それらをファイルパッケージに直接ポイントさせるか、または実際のパッケージを指す外部ページにポイントさせることを選択できます。

ダウンロードできるパッケージを直接ポイントするには、以下を実行します。ここでリンクテキストはパッケージプラットフォームになります。

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"
};

または、実際のダウンロードパッケージにリンクするページをポイントするには、以下を実行します。ここでは、Latest Release をリンクテキストに指定しています。

window.OPENSHIFT_CONSTANTS.CLI = {
  "Latest Release": "https://<cdn>/openshift-client-tools/latest.html"
};

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

Web コンソールのランディングページカタログには、主要アプリケーションへのリンクの (オプションの) 一覧があります。これらはページ上部近くに表示され、アイコン、タイトル、簡単な説明およびリンクを指定できます。

// 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."
}];

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

カタログカテゴリーは、Web コンソールカタログのランディングページ内の項目の表示を整理します。各カテゴリーには 1 つ以上のサブカテゴリーがあります。一致するサブカテゴリータグに含まれるタグがある場合、ビルダーイメージ、テンプレート、またはサービスがサブカテゴリーにグループ化されます。また、1 つの項目を複数のサブカテゴリーに表示することができます。カテゴリーとサブカテゴリーは、1 つ以上の項目がある場合にのみ表示されます。

// 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"
      ]
    }
  ]
});

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

ユーザーがクォータに達すると、クォータ通知が通知ドロワーに追加されます。カスタムクォータ通知メッセージ (クォータリソースタイプ別) を通知に追加できます。以下は例になります。

Your project is over quota. It is using 200% of 2 cores CPU (Limit). Upgrade
to <a href='https://www.openshift.com'>OpenShift Online Pro</a> if you need
additional resources.

通知の「Upgrade to…​」の部分はカスタムメッセージで、追加リソースへのリンクなどの HTML を指定できます。

window.OPENSHIFT_CONSTANTS.QUOTA_NOTIFICATION_MESSAGE プロパティーを拡張スクリプトに設定して、各リソースについてメッセージをカスタマイズします。

// Set custom notification messages per quota type/key
window.OPENSHIFT_CONSTANTS.QUOTA_NOTIFICATION_MESSAGE = {
  'pods': 'Upgrade to <a href="https://www.openshift.com">OpenShift Online Pro</a> if you need additional resources.',
  'limits.memory': 'Upgrade to <a href="https://www.openshift.com">OpenShift Online Pro</a> if you need additional resources.'
};

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

Create from URL は、明示的に OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST に指定される namespace からのイメージストリームまたはテンプレートとのみ機能します。namespace をホワイトリストに追加するには、以下の手順に従います。

// Add a namespace containing the image streams and/or templates
window.OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST.push(
  'shared-stuff'
);

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

Web コンソールではユーザーは、現在のアクセストークンなどのログインコマンドをユーザーメニューおよび Command Line Tools ページからクリップボードにコピーできます。この機能は、ユーザーのアクセストークンがコピーされたコマンドに含まれないように変更することができます。

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

「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。

window.OPENSHIFT_CONSTANTS.DISABLE_WILDCARD_ROUTES = false;

Web コンソールのログインページおよびログインプロバイダー選択ページも変更できます。以下のコマンドを実行して、変更可能なテンプレートを作成します。

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

ファイルを編集して、スタイルを変更するか、または内容を追加します。ただし、波括弧内の必須パラメーターを削除しないよう注意してください。

カスタムログインページまたはプロバイダー選択ページを使用するには、以下のオプションをマスター設定ファイルに設定します。

oauthConfig:
  ...
  templates:
    login: /path/to/login-template.html
    providerSelection: /path/to/provider-selection-template.html

相対パスは、マスター設定ファイルを基準にして解決されます。この設定を変更したらサーバーを再起動する必要があります。

複数のログインプロバイダーが設定されている場合、または master-config.yaml ファイルの alwaysShowProviderSelection オプションが true に設定されている場合、OpenShift Container Platform へのユーザーのトークンが期限切れになるたびに、このカスタムページが他のタスクに進む前にユーザーに表示されます。

認証中にエラーが発生した場合に表示されるページを変更できます。

webconsole-config ConfigMap の clusterInfo.logoutPublicURL パラメーターを変更すると、コンソールをログアウトしたときにコンソールユーザーに表示される場所を変更できます。

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

以下の例では、ログアウト URL を https://www.example.com/logout に変更しています。

apiVersion: v1
kind: ConfigMap
data:
  webconsole-config.yaml: |
    apiVersion: webconsole.config.openshift.io/v1
    clusterInfo:
      [...]
      logoutPublicURL: "https://www.example.com/logout"
    [...]

これは、要求ヘッダーおよび OAuth または OpenID アイデンティティープロバイダーで認証する場合に便利です。この場合、外部 URL にアクセスしてシングルサインオンセッションを破棄する必要があるからです。

通常インストール (Advanced installation) の実行中に、Web コンソールへの多数の変更を以下のパラメーターを使用して設定できます。これらのパラメーターはインベントリーファイルで設定可能です。

# Configure `clusterInfo.logoutPublicURL` in the web console configuration
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#changing-the-logout-url
#openshift_master_logout_url=https://example.com/logout

# Configure extension scripts for web console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets
#openshift_web_console_extension_script_urls=['https://example.com/scripts/menu-customization.js','https://example.com/scripts/nav-customization.js']

# Configure extension stylesheets for web console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets
#openshift_web_console_extension_stylesheet_urls=['https://example.com/styles/logo.css','https://example.com/styles/custom-styles.css']

# Configure a custom login template in the master config
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#customizing-the-login-page
#openshift_master_oauth_templates={'login': '/path/to/login-template.html'}

# Configure `clusterInfo.metricsPublicURL` in the web console configuration 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 `clusterInfo.loggingPublicURL` in the web console configuration 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

ユーザーが Web コンソール URL にアクセスする際にカスタム証明書が提供されるようにするには、証明書および URL を master-config.yaml ファイルの namedCertificates セクションに追加します。詳細は、「Web コンソールまたは CLI のカスタム証明書の設定」を参照してください。

Web コンソールのリダイレクト URL を設定または変更するには、openshift-web-console oauthclient を変更します。

$ oc edit oauthclient openshift-web-console

ユーザーが適切にリダイレクトされるようにするには、openshift-web-console configmap の PublicUrls を更新します。

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

次に、consolePublicURL の値を更新します。