conster Header: React.FC = () => {
const { t } = useTranslation('plugin__console-demo-plugin');
return <h1>{t('Hello, World!')}</h1>;
};
You can create and deploy a dynamic plugin on your cluster that is loaded at run-time.
Creating a dynamic plugin is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope. |
A dynamic plugin allows you to add custom pages and other extensions to your interface at runtime. The ConsolePlugin
custom resource registers plugins with the console, and a cluster administrator enables plugins in the console-operator
configuration.
A dynamic plugin allows you to make the following customizations to the OpenShift Container Platform experience:
Add custom pages.
Add perspectives and update navigation items.
Add tabs and actions to resource pages.
When creating your plugin, follow these guidelines for using PatternFly:
Use PatternFly4 components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables will help your plugin look consistent in future console versions.
Make your plugin accessible by following PatternFly’s accessibility fundamentals.
Do not use other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel.
When creating your plugin, follow these general guidelines:
Prefix your CSS class names with your plugin name to avoid collisions. For example, my-plugin__heading
and my-plugin_\_icon
.
Maintain a consistent look, feel, and behavior with other console pages.
Follow react-i18next localization guidelines when creating your plugin. You can use the useTranslation
hook like the one in the following example:
conster Header: React.FC = () => {
const { t } = useTranslation('plugin__console-demo-plugin');
return <h1>{t('Hello, World!')}</h1>;
};
Do not use console CSS classes in your markup or override console CSS classes. These are not APIs and are subject to change. Using them might break your plugin. Avoid selectors like element selectors that could affect markup outside of your plugin’s components.
Cluster administrators can enable plugins in the web console browser. Dynamic plugins are disabled by default. In order to enable, a cluster administrator will need to enable them in the console-operator
configuration.
In the Administration → Cluster Settings page of the web console, click the Configuration tab.
Click the Console
operator.openshift.io
configuration resource.
From there, click the Console plugins tab to view the dynamic plugins running.
In the Status
column, click Enable console plugin
in the pop-over menu, which will launch the Console plugin enablement
modal.
Click Enable
and Save
.
Refresh the browser to view the enabled plugin.
To get started using the dynamic plugin, you must set up your environment to write a new OpenShift Console dynamic plugin.
Edit the plugin metadata in the consolePlugin
declaration of package.json
.
"consolePlugin": {
"name": "my-plugin", (1)
"version": "0.0.1", (2)
"displayName": "My Plugin", (3)
"description": "Enjoy this shiny, new console plugin!", (4)
"exposedModules": {
"ExamplePage": "./components/ExamplePage"
},
"dependencies": {
"@console/pluginAPI": "*"
}
}
1 | Update the name of your plugin. |
2 | Update the version. |
3 | Update the display name for your plugin. |
4 | Update the description with a synopsis about your plugin. |
You can run the plugin using a local development environment. The OpenShift Container Platform web console runs in a container connected to the cluster you have logged into.
Build a plugin and generate the output to the dist
directory by running
$ yarn build
Start an HTTP server by running
$ yarn http-server
The HTTP server, which runs on port 9001, generates the following assets with caching
disabled and CORS
enabled.
Starting up http-server, serving ./dist
Available on:
http://127.0.0.1:9001
http://192.168.1.190:9001
http://10.40.192.80:9001
Hit CTRL-C to stop the server
Optional: Add additional server options to the script by running
$ yarn http-server -a <server name>
Direct bridge
to proxy requests to your local plugin asset server by running
$ ./bin/bridge -plugins console-demo-plugin=http://localhost:9001/
Visit local host to view the running plugin. Inspect the value of window.SERVER_FLAGS.consolePlugins
to see the list of plugins which load at runtime.
You can add extensions that allow you to customize your plugin. Those extensions are then loaded to the console at run-time.
Edit the console-extensions.json
file:
[
{
"type": "console.flag", (1)
"properties": {
"handler": { "$codeRef": "barUtils.testHandler" } (2)
}
},
{
"type": "console.flag/model",
"properties": {
"flag": "EXAMPLE",
"model": {
"group": "kubevirt.io",
"version": "v1alpha3",
"kind": "ExampleModel"
}
}
}
]
1 | Add the extension type(s) you want to include with this plugin. You can include multiple extensions separated with a comma. |
2 | The $codeRef value should be formatted as either moduleName.exportName for a named export or moduleName for the default export. Only the plugin’s exported modules can be used in code references. |
console.action/filter
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The context ID helps to narrow the scope of
contributed actions to a particular area of the application. Examples include |
|
|
no |
A
function that will filter actions based on some conditions. |
console.action/group
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
ID used to identify the action section. |
|
|
yes |
The label to display in the UI. Required for submenus. |
|
|
yes |
Whether this group should be displayed as submenu. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is
used. The |
console.action/provider
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The context ID helps to narrow the scope of
contributed actions to a particular area of the application. Examples include |
|
|
no |
A React hook
that returns actions for the given scope. If |
console.action/resource-provider
console.catalog/item-filter
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The unique identifier for the catalog this provider contributes to. |
|
|
no |
Type ID for the catalog item type. |
|
|
no |
Filters items
of a specific type. Value is a function that takes |
console.catalog/item-metadata
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The unique identifier for the catalog this provider contributes to. |
|
|
no |
Type ID for the catalog item type. |
|
|
no |
A hook which returns a function that will be used to provide metadata to catalog items of a specific type. |
console.catalog/item-provider
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The unique identifier for the catalog this provider contributes to. |
|
|
no |
Type ID for the catalog item type. |
|
|
no |
Title for the catalog item provider |
|
|
no |
Fetch items and normalize it for the catalog. Value is a react effect hook. |
|
|
yes |
Priority for this provider. Defaults to |
console.catalog/item-type
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Type for the catalog item. |
|
|
no |
Title for the catalog item. |
|
|
yes |
Description for the type specific catalog. |
|
|
yes |
Description for the catalog item type. |
|
|
yes |
Custom filters specific to the catalog item. |
|
|
yes |
Custom groupings specific to the catalog item. |
console.cluster-overview/multiline-utilization-item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The title of the utilization item. |
|
|
no |
Prometheus utilization query. |
|
|
no |
Convert Prometheus data to human-readable form. |
|
|
yes |
Shows Top consumer popover instead of plain value |
console.cluster-overview/utilization-item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The title of the utilization item. |
|
|
no |
Prometheus utilization query. |
|
|
no |
Convert Prometheus data to human-readable form. |
|
|
yes |
Prometheus total query. |
|
|
yes |
Prometheus request query. |
|
|
yes |
Prometheus limit query. |
|
|
yes |
Shows Top consumer popover instead of plain value |
console.dashboards/card
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The ID of the dashboard tab to which the card will be added. |
|
|
no |
The grid position of the card on the dashboard. |
|
|
no |
Dashboard card component. |
|
|
yes |
Card’s vertical span in the column.
Ignored for small screens; defaults to |
console.dashboards/overview/activity/resource
Adds an activity to the Activity Card of Overview Dashboard where the triggering of activity is based on watching a Kubernetes resource.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The utilization item to be replaced. |
|
|
no |
The action component. |
|
|
yes |
Function which determines if the given resource represents the action. If not defined, every resource represents activity. |
|
|
yes |
Time stamp for the given action, which will be used for ordering. |
console.dashboards/overview/health/operator
Adds a health subsystem to the status card of the Overview dashboard, where the source of status is a Kubernetes REST API.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Title of Operators section in the pop-up menu. |
|
|
no |
Kubernetes resources
which will be fetched and passed to |
|
|
yes |
Resolves status for the Operators. |
|
|
yes |
Loader for pop-up row component. |
|
|
yes |
Links to all resources page. If not provided, then a list page of the first resource from resources prop is used. |
console.dashboards/overview/health/prometheus
Adds a health subsystem to the status card of Overview dashboard where the source of status is Prometheus.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The display name of the subsystem. |
|
|
no |
The Prometheus queries |
|
|
no |
Resolve the subsystem’s health. |
|
|
yes |
Additional
resource which will be fetched and passed to |
|
|
yes |
Loader for pop-up menu content. If defined, a health item is represented as a link, which opens a pop-up menu with the given content. |
|
|
yes |
The title of the popover. |
|
|
yes |
Control plane topology for which the subsystem should be hidden. |
console.dashboards/overview/health/resource
Adds a health subsystem to the status card of Overview dashboard where the source of status is a Kubernetes Resource.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The display name of the subsystem. |
|
|
no |
Kubernetes resources
that will be fetched and passed to |
|
|
no |
Resolve the subsystem’s health. |
|
|
yes |
Loader for pop-up menu content. If defined, a health item is represented as a link, which opens a pop-up menu with the given content. |
|
|
yes |
The title of the popover. |
console.dashboards/overview/health/url
Adds a health subsystem to the status card of Overview dashboard where the source of status is a Kubernetes REST API.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The display name of the subsystem. |
|
|
no |
The URL to fetch data from. It will be prefixed with base Kubernetes URL. |
|
`CodeRef<URLHealthHandler<T, K8sResourceCommon |
K8sResourceCommon[]>>` |
no |
Resolve the subsystem’s health. |
|
|
yes |
Additional
resource which will be fetched and passed to |
|
|
yes |
Loader for popup content. If defined, a health item will be represented as a link which opens popup with given content. |
|
|
yes |
console.dashboards/overview/inventory/item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model for |
|
|
yes |
Function which maps various statuses to groups. |
|
|
yes |
Additional
resources which will be fetched and passed to the |
console.dashboards/overview/inventory/item/replacement
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model for |
|
|
yes |
Function which maps various statuses to groups. |
|
|
yes |
Additional
resources which will be fetched and passed to the |
console.dashboards/overview/prometheus/activity/resource
Adds an activity to the Activity Card of Prometheus Overview Dashboard where the triggering of activity is based on watching a Kubernetes resource.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Queries to watch |
|
|
no |
The action component. |
|
|
yes |
Function which determines if the given resource represents the action. If not defined, every resource represents activity. |
console.dashboards/project/overview/item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model for |
|
|
yes |
Function which maps various statuses to groups. |
|
|
yes |
Additional
resources which will be fetched and passed to the |
console.global-config
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Unique identifier for the cluster config resource instance. |
|
|
no |
The name of the cluster config resource instance. |
|
|
no |
The model which refers to a cluster config resource. |
|
|
no |
The namespace of the cluster config resource instance. |
console.model-metadata
Customize the display of models by overriding values retrieved and generated through API discovery.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model to customize. May specify only a group, or optional version and kind. |
|
|
yes |
Whether to consider this model reference as Technology Preview or Developer Preview. |
|
|
yes |
The color to associate to this model. |
|
|
yes |
Override the label. Requires |
|
|
yes |
Override the plural label. Requires
|
|
|
yes |
Customize the abbreviation. Defaults to all
uppercase characters in |
console.navigation/href
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this item. |
|
|
no |
The name of this item. |
|
|
no |
The link href value. |
|
|
yes |
The perspective ID to which this item belongs to. If not specified, contributes to the default perspective. |
|
|
yes |
Navigation section to which this item belongs to. If not specified, render this item as a top level link. |
|
|
yes |
Adds data attributes to the DOM. |
|
|
yes |
Mark this item as active when the URL starts with one of these paths. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is used.
|
|
|
yes |
If |
|
|
yes |
If |
console.navigation/resource-cluster
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this item. |
|
|
no |
The model for which this navigation item links to. |
|
|
yes |
The perspective ID to which this item belongs to. If not specified, contributes to the default perspective. |
|
|
yes |
Navigation section to which this item belongs to. If not specified, render this item as a top-level link. |
|
|
yes |
Adds data attributes to the DOM. |
|
|
yes |
Mark this item as active when the URL starts with one of these paths. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is used.
|
|
|
yes |
Overrides the default name. If not supplied the name of the link will equal the plural value of the model. |
console.navigation/resource-ns
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this item. |
|
|
no |
The model for which this navigation item links to. |
|
|
yes |
The perspective ID to which this item belongs to. If not specified, contributes to the default perspective. |
|
|
yes |
Navigation section to which this item belongs to. If not specified, render this item as a top-level link. |
|
|
yes |
Adds data attributes to the DOM. |
|
|
yes |
Mark this item as active when the URL starts with one of these paths. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is used.
|
|
|
yes |
Overrides the default name. If not supplied the name of the link will equal the plural value of the model. |
console.navigation/section
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this item. |
|
|
yes |
The perspective ID to which this item belongs to. If not specified, contributes to the default perspective. |
|
|
yes |
Adds data attributes to the DOM. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is used.
|
|
|
yes |
Name of this section. If not supplied, only a separator will be shown above the section. |
console.navigation/separator
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this item. |
|
|
yes |
The perspective ID to which this item belongs to. If not specified, contributes to the default perspective. |
|
|
yes |
Navigation section to which this item belongs to. If not specified, render this item as a top level link. |
|
|
yes |
Adds data attributes to the DOM. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is used.
|
console.page/route
Adds a new page to the web console router. See React Router.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The component to be rendered when the route matches. |
|
|
no |
Valid URL path or array of paths that
|
|
|
yes |
The perspective to which this page belongs to. If not specified, contributes to all perspectives. |
|
|
yes |
When true, will only match if the path matches
the |
console.page/route/standalone
Adds a new standalone page, rendered outside the common page layout, to the web console router. See React Router.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The component to be rendered when the route matches. |
|
|
no |
Valid URL path or array of paths that
|
|
|
yes |
When true, will only match if the path matches
the |
console.perspective
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The perspective identifier. |
|
|
no |
The perspective display name. |
|
|
no |
The perspective display icon. |
|
|
no |
The function to get perspective landing page URL. |
|
|
no |
The function to get redirect URL for import flow. |
|
|
yes |
Whether the perspective is the default. There can only be one default. |
|
|
yes |
Default pinned resources on the nav |
|
|
yes |
The hook to detect default perspective |
console.project-overview/utilization-item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The title of the utilization item. |
|
|
no |
Prometheus utilization query. |
|
|
no |
Convert Prometheus data to human-readable form. |
|
|
yes |
Prometheus total query. |
|
|
yes |
Prometheus request query. |
|
|
yes |
Prometheus limit query. |
|
|
yes |
Shows the top consumer popover instead of plain value. |
console.pvc/delete
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Predicate that tells whether to use the extension or not. |
|
|
no |
Method for the PVC delete operation. |
|
|
no |
Alert component to show additional information. |
console.pvc/status
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Priority for the status component. A larger value means higher priority. |
|
|
no |
The status component. |
|
|
no |
Predicate that tells whether to render the status component or not. |
console.tab/horizontalNav
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model for which this provider show tab. |
|
|
no |
The page to be show in horizontal tab. It takes tab name as name and href of the tab |
|
|
no |
The component to be rendered when the route matches. |
console.topology/adapter/build
console.topology/adapter/network
console.topology/adapter/pod
console.topology/data/factory
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
Unique ID for the factory. |
|
|
no |
Priority for the factory |
|
|
yes |
Resources to be fetched from useK8sWatchResources hook. |
|
|
yes |
Keys in resources containing workloads. |
|
|
yes |
Getter for the data model factory. |
|
|
yes |
Getter for function to determine if a resource is depicted by this model factory. |
|
|
yes |
Getter for function to reconcile data model after all extensions' models have loaded. |
console.topology/details/tab
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this details tab. |
|
|
no |
The tab label to display in the UI. |
|
|
yes |
Insert this item before the item referenced here. For arrays, the first one found in order is used. |
|
|
yes |
Insert this item after the
item referenced here. For arrays, the first one found in order is
used. The |
console.topology/details/tab-section
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
A unique identifier for this details tab section. |
|
|
no |
The parent tab ID that this section should contribute to. |
|
|
no |
A hook that returns a component, or if null or undefined renders in the topology sidebar.SDK component: <Section title=\{}>… padded area |
|
`CodeRef<(element: GraphElement, renderNull?: () ⇒ null) ⇒ React.Component |
undefined>` |
no |
@deprecated Fallback if no provider is defined. renderNull is a no-op already. |
|
|
yes |
Insert this item before the item referenced here.For arrays, the first one found in order is used. |
|
|
yes |
console.user-preference/group
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
ID used to identify the user preference group. |
|
|
no |
The label of the user preference group |
|
|
yes |
ID of user preference group before which this group should be placed |
|
|
yes |
ID of user preference group after which this group should be placed |
console.user-preference/item
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
ID used to identify the user preference item and referenced in insertAfter and insertBefore to define the item order. |
|
|
no |
The label of the user preference |
|
|
no |
The description of the user preference. |
|
|
no |
The input field options used to render the values to set the user preference. |
|
|
yes |
IDs used to identify the user preference groups the item would belong to. |
|
|
yes |
ID of user preference item before which this item should be placed |
|
|
yes |
ID of user preference item after which this item should be placed |
dev-console.add/action
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
ID used to identify the action. |
|
|
no |
The label of the action |
|
|
no |
The description of the action. |
|
|
no |
The href to navigate to. |
|
|
yes |
IDs used to identify the action groups the action would belong to. |
|
|
yes |
The perspective display icon. |
|
|
yes |
Optional access review to control the visibility or enablement of the action. |
dev-console.add/action-group
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
ID used to identify the action group. |
|
|
no |
The title of the action group |
|
|
yes |
ID of action group before which this group should be placed |
|
|
yes |
ID of action group after which this group should be placed |
console.page/resource/tab
Deprecated. Use console.tab/horizontalNav
instead. Adds a new resource
tab page to Console router.
Name | Value Type | Optional | Description |
---|---|---|---|
|
|
no |
The model for which this resource page links to. |
|
|
no |
The component to be rendered when the route matches. |
|
|
no |
The name of the tab. |
|
|
yes |
The optional href for the tab link. If not
provided, the first |
|
|
yes |
When true, will only match if the path matches
the |
The following procedure adds a tab to the Pod Details page as an example extension to your plugin.
Add the following to the console-extensions.json
file:
{
"type": "console.tab/horizontalNav",
"properties": {
"page": {
"name": "Example Tab",
"href": "example"
},
"model": {
"group": "core",
"version": "v1",
"kind": "Pod"
},
"component": { "$codeRef": "ExampleTab" }
}
}
Edit the package.json
file to include the following changes:
"exposedModules": {
"ExamplePage": "./components/ExamplePage",
"ExampleTab": "./components/ExampleTab"
}
Write a message to display on a new custom tab on the Pods page by creating a new file src/components/ExampleTab.tsx
and adding the following script:
import * as React from 'react';
export default function ExampleTab() {
return (
<p>This is a custom tab added to a resource using a dynamic plugin.</p>
);
}
Visit a Pod page to view the added tab.
To deploy your plugin on a cluster, you need to build an image and push it to an image registry.
Build the image with the following command:
$ docker build -t quay.io/my-repositroy/my-plugin:latest .
Optional: If you want to test your image, run the following command:
$ docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest
Push the image by running the following command:
$ docker push quay.io/my-repository/my-plugin:latest
After pushing an image with your changes to a registry, you can deploy the plugin to a cluster.
To deploy your plugin to a cluster, instantiate your plugin by running the following command:
$ oc process -f template.yaml \
-p PLUGIN_NAME=my-plugin \ (1)
-p NAMESPACE=my-plugin-namespace \ (2)
-p IMAGE=quay.io/my-repository/my-plugin:latest \ (3)
| oc create -f -
1 | Update with the name of your plugin. |
2 | Update with the namespace. |
3 | Update with the name of the image you created. |
This command runs a light-weight NGINX HTTP server to serve the assets for your plugin.
|
Patch the Console Operator configuration to enable the plugin by running the following command:
$ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge
Console users can use the disable-plugins
query parameter to disable specific or all dynamic plugins that would normally get loaded at run-time.
To disable a specific plugin(s), remove the plugin you want to disable from the comma-separated list of plugin names.
To disable all plugins, leave an empty string in the disable-plugins
query parameter.
Cluster administrators can disable plugins in the Cluster Settings page of the web console |