第36章 Web コンソールのカスタマイズ
36.1. 概要
管理者は拡張機能を使用して Web コンソールをカスタマイズできます。拡張機能でスクリプトを実行すると、Web コンソールを読み込む際にカスタムスタイルシートを読み込むことができます。拡張スクリプトによって、Web コンソールのデフォルト動作を上書きし、必要に応じてカスタマイズできます。
たとえば、拡張スクリプトを使用して、自社独自のブランディングを追加したり、自社固有の機能を追加したりすることができます。この使用例として一般的なのは、さまざまな環境のリブランディングやホワイトラベリングです。同じ拡張コードを使用しながら、Web コンソールを変更する設定を指定できます。
Web コンソールのスタイルや動作に対して、以下に記載されていないような広範な変更を実行するには注意が必要です。スクリプトやスタイルシートを追加することはできますが、大幅にカスタマイズすると、今後のバージョンで Web コンソールのマークアップや動作が変更された場合に、アップグレード時に再作業が必要になる可能性があります。
36.2. 拡張スクリプトとスタイルシートの読み込み
OpenShift Container Platform 3.9 では、拡張スクリプトとスタイルシートは、URL がブラウザーからアクセス可能であれば、任意の https://
URL でホストできます。ファイルは、パブリックにアクセスできるルートを使用してプラットフォーム上の Pod からや OpenShift Container Platform 外部の別のサーバー上の Pod からホストできます。
スクリプトとスタイルシートを追加するには、openshift-web-console
namespace で webconsole-config
ConfigMap を編集します。Web コンソール設定は ConfigMap の webconsole-config.yaml
キーにあります。
$ oc edit configmap/webconsole-config -n openshift-web-console
スクリプトを追加するには、extensions.scriptURLs
プロパティーを更新します。値は URL の配列です。
スタイルシートを追加するには、extensions.stylesheetURLs
プロパティーを更新します。値は URL の配列です。
extensions.stylesheetURLs
設定の例
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 コンソールコンテナーは数分以内に新規の拡張ファイルについて自動的に更新されます。
スクリプトとスタイルシートは正しいコンテンツタイプで提供する必要があります。そうしないと、それらはブラウザーで実行されません。スクリプトは Content-Type: application/javascript
、スタイルシートは Content-Type: text/css
で提供する必要があります。
最良の実践例として、拡張スクリプトを Immediately Invoked Function Expression (IIFE) でラップすることができます。これにより、Web コンソールや他の拡張で使用される名前と競合するグローバル変数を作成することを防ぐことができます。以下は例になります。
(function() { // Put your extension code here... }());
以降のセクションの例では、Web コンソールをカスタマイズする一般的な方法を示します。
拡張の他の例については、GitHub の OpenShift Origin リポジトリーを参照してください。
36.2.1. 拡張プロパティーの設定
特定の拡張について環境ごとに異なるテキストを使用する場合、Web コンソール設定で環境を定義し、同じ拡張スクリプトを環境全体で使用できます。
拡張プロパティーを追加するには、openshift-web-console
namespace で webconsole-config
ConfigMap を 編集します。Web コンソール設定は ConfigMap の webconsole-config.yaml
キーにあります。
$ oc edit configmap/webconsole-config -n openshift-web-console
extensions.properties
の値を更新します。これはキーと値のペアのマップです。
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" }
36.3. 外部ロギングソリューションの拡張オプション
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");
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.4. ガイド付きツアーのカスタマイズと無効化
ユーザーの特定ブラウザーへの初回ログイン時に、ガイド付きツアーが表示されます。新規ユーザーに対して auto_launch
を有効にできます。
window.OPENSHIFT_CONSTANTS.GUIDED_TOURS.landing_page_tour.auto_launch = true;
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.5. ドキュメントリンクのカスタマイズ
ランディングページのドキュメントリンクはカスタマイズできます。window.OPENSHIFT_CONSTANTS.CATALOG_HELP_RESOURCES
はタイトルと href
を含むオブジェクトの配列で、これらはリンクに変換されます。この配列を完全に上書きしたり、追加のリンクをプッシュまたはポップしたり、既存のリンクの属性を変更したりすることができます。以下は例になります。
window.OPENSHIFT_CONSTANTS.CATALOG_HELP_RESOURCES.push({ title: 'Blog', href: 'https://blog.openshift.com' });
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.6. ロゴのカスタマイズ
以下のスタイルでは、Web コンソールヘッダーのロゴを変更します。
#header-logo { background-image: url("https://www.example.com/images/logo.png"); width: 190px; height: 20px; }
example.com URL を実際のイメージへの URL に置換して、幅と高さを調整します。理想的な高さは 20px です。
「拡張スクリプトとスタイルシートの読み込み」で説明されているスタイルシートを追加します。
36.7. メンバーシップのホワイトリストのカスタマイズ
メンバーシップページのデフォルトのホワイトリストには、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" ];
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.8. ドキュメントへのリンクの変更
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
- 1
- パスの末尾は
/
にする必要があります。
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.9. CLI をダウンロードするリンクの追加または変更
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" };
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.9.1. About ページのカスタマイズ
Web コンソールの About ページをカスタマイズするには、以下の手順に従います。
以下のような拡張を作成します。
angular .module('aboutPageExtension', ['openshiftConsole']) .config(function($routeProvider) { $routeProvider .when('/about', { templateUrl: 'https://example.com/extensions/about/about.html', controller: 'AboutController' }); } ); hawtioPluginLoader.addModule('aboutPageExtension');
カスタムテンプレートを作成します。
使用している OpenShift Container Platform リリースの about.html のバージョンから開始します。テンプレート内には 2 つの angular スコープ変数、
version.master.openshift
およびversion.master.kubernetes
があります。Web コンソールの適切な Cross-Origin Resource Sharing (CORS) 応答ヘッダーを持つ URL でテンプレートをホストします。
-
Web コンソールドメインからの要求を許可するように
Access-Control-Allow-Origin
応答を設定します。 -
GET
を含めるようにAccess-Control-Allow-Methods
を設定します。 -
Content-Type
を含めるようにAccess-Control-Allow-Headers
を設定します。
-
Web コンソールドメインからの要求を許可するように
または、AngularJS $templateCache を使用すると、テンプレートを JavaScript に直接含めることができます。
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.11. 主要アプリケーションの設定
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." }];
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.12. カタログカテゴリーの設定
カタログカテゴリーは、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" ] } ] });
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.13. クォータ通知メッセージの設定
ユーザーがクォータに達すると、クォータ通知が通知ドロワーに追加されます。カスタムクォータ通知メッセージ (クォータリソースタイプ別) を通知に追加できます。以下は例になります。
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 を指定できます。
クォータメッセージは HTML マークアップなので、特殊文字はすべて 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.' };
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.14. Create From URL namespace ホワイトリストの設定
Create from URL は、明示的に OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST
に指定される namespace からのイメージストリームまたはテンプレートとのみ機能します。namespace をホワイトリストに追加するには、以下の手順に従います。
openshift
はデフォルトでホワイトリストに含まれています。これは削除しないでください。
// Add a namespace containing the image streams and/or templates window.OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST.push( 'shared-stuff' );
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.15. Copy Login コマンドの無効化
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;
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.15.1. ワイルドカードルートの有効化
ワイルドカードルートをルーターで有効にした場合、Web コンソールでもワイルドカードルートを有効にできます。これによりユーザーはルートを作成するときに、*.example.com
などのアスタリスクで始まるホスト名を入力できます。ワイルドカードルートを有効にするには、以下を実行します。
window.OPENSHIFT_CONSTANTS.DISABLE_WILDCARD_ROUTES = false;
「拡張スクリプトとスタイルシートの読み込み」で説明されているようにスクリプトを追加します。
36.16. ログインページのカスタマイズ
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 へのユーザーのトークンが期限切れになるたびに、このカスタムページが他のタスクに進む前にユーザーに表示されます。
36.16.1. 使用例
サービス利用規約情報はカスタムログインページを使用して作成できます。このようなページは、GitHub や Google などのサードパーティーログインプロバイダーを使用している場合にも、ユーザーが信頼し、予想できるブランドのページを提示して、その後にユーザーを認証プロバイダーにリダイレクトする際に役立ちます。
36.17. OAuth エラーページのカスタマイズ
認証中にエラーが発生した場合に表示されるページを変更できます。
以下のコマンドを実行して、変更可能なテンプレートを作成します。
$ oc adm create-error-template > error-template.html
ファイルを編集して、スタイルを変更するか、または内容を追加します。
テンプレートで
Error
変数およびErrorCode
変数を使用できます。カスタムエラーページを使用するには、以下のオプションをマスター設定ファイルに設定します。oauthConfig: ... templates: error: /path/to/error-template.html
相対パスは、マスター設定ファイルを基準にして解決されます。
- この設定を変更したらサーバーを再起動する必要があります。
36.18. ログアウト URL の変更
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 にアクセスしてシングルサインオンセッションを破棄する必要があるからです。
36.19. Ansible による Web コンソールカスタマイズの設定
クラスターのインストール時に、以下のパラメーターを使用して、Web コンソールへの変更を多数設定できます。これらのパラメーターは、インベントリーファイルで設定可能です。
Ansible による 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
36.20. Web コンソール URL ポートおよび証明書の変更
ユーザーが 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
の値を更新します。