From 2f6a046fd9aa133934aaa782bc7fd9af2f0dec99 Mon Sep 17 00:00:00 2001 From: Olivia Payne Date: Mon, 21 Nov 2022 16:16:46 -0500 Subject: [PATCH] OSDOCS-4073: Dynamic plug-in doc updates --- _topic_maps/_topic_map.yml | 13 +- .../adding-new-extension-dynamic-plug-in.adoc | 35 - modules/adding-tab-pods-page.adoc | 47 +- modules/build-image-docker.adoc | 2 +- modules/deployment-plug-in-cluster.adoc | 96 +- modules/disabling-plug-in-browser.adoc | 2 +- modules/dynamic-plug-in-api.adoc | 1470 +++++++++++++++++ modules/dynamic-plug-in-development.adoc | 50 + modules/dynamic-plug-in-sdk-extensions.adoc | 703 ++------ modules/dynamic-plug-ins-get-started.adoc | 38 - modules/running-your-dynamic-plug-in.adoc | 58 - modules/troubleshooting-dynamic-plug-in.adoc | 45 + web_console/dynamic-plug-in/_attributes | 1 + .../deploy-plug-in-cluster.adoc | 16 + .../dynamic-plug-in-example.adoc | 11 + .../dynamic-plug-in/dynamic-plug-in.adoc | 36 +- .../dynamic-plug-ins-get-started.adoc | 11 + .../dynamic-plug-ins-reference.adoc | 19 + web_console/dynamic-plug-in/images | 1 + web_console/dynamic-plug-in/modules | 1 + web_console/dynamic-plug-in/snippets | 1 + web_console/dynamic-plug-ins.adoc | 33 - 22 files changed, 1873 insertions(+), 816 deletions(-) delete mode 100644 modules/adding-new-extension-dynamic-plug-in.adoc create mode 100644 modules/dynamic-plug-in-api.adoc create mode 100644 modules/dynamic-plug-in-development.adoc delete mode 100644 modules/dynamic-plug-ins-get-started.adoc delete mode 100644 modules/running-your-dynamic-plug-in.adoc create mode 100644 modules/troubleshooting-dynamic-plug-in.adoc create mode 120000 web_console/dynamic-plug-in/_attributes create mode 100644 web_console/dynamic-plug-in/deploy-plug-in-cluster.adoc create mode 100644 web_console/dynamic-plug-in/dynamic-plug-in-example.adoc rename modules/about-dynamic-plug-ins.adoc => web_console/dynamic-plug-in/dynamic-plug-in.adoc (62%) create mode 100644 web_console/dynamic-plug-in/dynamic-plug-ins-get-started.adoc create mode 100644 web_console/dynamic-plug-in/dynamic-plug-ins-reference.adoc create mode 120000 web_console/dynamic-plug-in/images create mode 120000 web_console/dynamic-plug-in/modules create mode 120000 web_console/dynamic-plug-in/snippets delete mode 100644 web_console/dynamic-plug-ins.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 25623e48be..39f16857e3 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -656,8 +656,19 @@ Topics: File: customizing-the-web-console Distros: openshift-enterprise,openshift-origin - Name: Dynamic plug-ins - File: dynamic-plug-ins + Dir: dynamic-plug-in Distros: openshift-enterprise,openshift-origin + Topics: + - Name: Overview of dynamic plug-ins + File: dynamic-plug-in + - Name: Getting started with dynamic plug-ins + File: dynamic-plug-ins-get-started + - Name: Deploy your plug-in on a cluster + File: deploy-plug-in-cluster + - Name: Dynamic plug-in example + File: dynamic-plug-in-example + - Name: Dynamic plug-in reference + File: dynamic-plug-ins-reference - Name: Web terminal File: odc-about-web-terminal Distros: openshift-enterprise,openshift-online diff --git a/modules/adding-new-extension-dynamic-plug-in.adoc b/modules/adding-new-extension-dynamic-plug-in.adoc deleted file mode 100644 index 5160e8a3b1..0000000000 --- a/modules/adding-new-extension-dynamic-plug-in.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/dynamic-plug-ins.adoc - -:_content-type: PROCEDURE -[id="adding-new-extension-dynamic-plugin_{context}"] -= Adding a new extension to your plug-in -You can add extensions that allow you to customize your plug-in. Those extensions are then loaded to the console at run-time. - -. Edit the `console-extensions.json` file: -+ -[source,json] ----- -[ - { - "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 plug-in. 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 plug-in’s exported modules can be used in code references. diff --git a/modules/adding-tab-pods-page.adoc b/modules/adding-tab-pods-page.adoc index 8faec66d0c..bd640e44d1 100644 --- a/modules/adding-tab-pods-page.adoc +++ b/modules/adding-tab-pods-page.adoc @@ -1,14 +1,55 @@ // Module included in the following assemblies: // -// * web_console/dynamic-plug-ins.adoc +// * web_console/dynamic-plugin-example.adoc :_content-type: PROCEDURE [id="adding-tab-to-pods-page_{context}"] = Adding a tab to the pods page -The following procedure adds a tab to the *Pod Details* page as an example extension to your plug-in. + +There are different customizations you can make to the {product-title} web console. The following procedure adds a tab to the *Pod details* page as an example extension to your plug-in. + +[NOTE] +==== +The {product-title} web console runs in a container connected to the cluster you have logged into. See "Dynamic plug-in development" for information to test the plug-in before creating your own. +==== .Procedure +. Visit the link:https://github.com/openshift/console-plugin-template[`console-plugin-template`] repository containing a template for creating plug-ins in a new tab. ++ +[IMPORTANT] +==== +Custom plug-in code is not supported by Red Hat. Only link:https://access.redhat.com/solutions/5893251[Cooperative community support] is available for your plug-in. +==== + +. Select the *Use this template* dropdown button and select *_Create new repository_* from the dropdown list to create a GitHub repository. + +. Re-name the new repository with the name of your plug-in. + +. Clone your copied repositury to your local machine so you can edit the code. + +. Edit the plug-in metadata in the `consolePlugin` declaration of `package.json`. ++ +[source,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 plug-in. +<2> Update the version. +<3> Update the display name for your plug-in. +<4> Update the description with a synopsis about your plug-in. + . Add the following to the `console-extensions.json` file: + [source,json] @@ -57,4 +98,4 @@ export default function ExampleTab() { ---- .Verification -* Visit a *Pod* page to view the added tab. +* Visit a *Pod* page to view the added tab. \ No newline at end of file diff --git a/modules/build-image-docker.adoc b/modules/build-image-docker.adoc index 19a5e56cb1..2b9a7ba004 100644 --- a/modules/build-image-docker.adoc +++ b/modules/build-image-docker.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * web_console/dynamic-plug-ins.adoc +// * web_console/deploy-plug-in-cluster.adoc :_content-type: PROCEDURE [id="build-image-with-docker_{context}"] diff --git a/modules/deployment-plug-in-cluster.adoc b/modules/deployment-plug-in-cluster.adoc index 8dbc0e47a6..47d57fe8dd 100644 --- a/modules/deployment-plug-in-cluster.adoc +++ b/modules/deployment-plug-in-cluster.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * web_console/dynamic-plug-ins.adoc +// * web_console/deploy-plug-in-cluster.adoc :_content-type: PROCEDURE [id="deploy-on-cluster_{context}"] @@ -10,32 +10,86 @@ After pushing an image with your changes to a registry, you can deploy the plug- .Procedure -. To deploy your plug-in to a cluster, instantiate your plug-in by running the following command: +. To deploy your plug-in to a cluster, install a Helm chart with the name of the plug-in as the Helm release name into a new namespace or an existing namespace as specified by the `-n` command-line option. Provide the location of the image within the `plugin.image` parameter by using the following command: + + [source,terminal] ---- -$ 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 - +$ helm upgrade -i my-plugin charts/openshift-console-plugin -n my-plugin-namespace --create-namespace --set plugin.image=my-plugin-image-location ---- -<1> Update with the name of your plug-in. -<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 plug-in. - -[IMPORTANT] -==== -`PLUGIN_NAME` must match the plug-in name you used in the `consolePlugin` declaration of `package.json`. -==== - -[start=2] -. Patch the *Console Operator* configuration to enable the plug-in by running the following command: +Where: + -[source,terminal] +-- +`n `:: Specifies an existing namespace to deploy your plug-in into. +`--create-namespace`:: Optional: If deploying to a new namespace, use this parameter. +`--set plugin.image=my-plugin-image-location`:: Specifies the location of the image within the `plugin.image` parameter. +-- +. Optional: You can specify any additional parameters by using the set of supported parameters in the `charts/openshift-console-plugin/values.yaml` file. + +[source,yaml] ---- -$ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge +plugin: + name: "" + description: "" + image: "" + imagePullPolicy: IfNotPresent + replicas: 2 + port: 9443 + securityContext: + enabled: true + podSecurityContext: + enabled: true + runAsNonRoot: true + seccompProfile: + type: RuntimeDefault + containerSecurityContext: + enabled: true + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL + resources: + requests: + cpu: 10m + memory: 50Mi + basePath: / + certificateSecretName: "" + serviceAccount: + create: true + annotations: {} + name: "" + patcherServiceAccount: + create: true + annotations: {} + name: "" + jobs: + patchConsoles: + enabled: true + image: "registry.redhat.io/openshift4/ose-tools-rhel8@sha256:e44074f21e0cca6464e50cb6ff934747e0bd11162ea01d522433a1a1ae116103" + podSecurityContext: + enabled: true + runAsNonRoot: true + seccompProfile: + type: RuntimeDefault + containerSecurityContext: + enabled: true + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL + resources: + requests: + cpu: 10m + memory: 50Mi ---- + +.Verification +You can see the list of the enabled plugins on the *Overview* page or by navigating from *Administration* -> *Cluster Settings* -> *Configuration* -> *Console* `operator.openshift.io` -> *Console plugins*. + + +[NOTE] +==== +It can take a few minutes for the new plug-in configuration to appear. If you do not see your plug-in, you might need to refresh your browser if the plugin was recently enabled. If you recieve any errors at runtime, check the JS console in browser developer tools to look for any errors in your plugin code. +==== \ No newline at end of file diff --git a/modules/disabling-plug-in-browser.adoc b/modules/disabling-plug-in-browser.adoc index 538352a773..55a216527c 100644 --- a/modules/disabling-plug-in-browser.adoc +++ b/modules/disabling-plug-in-browser.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * web_console/dynamic-plug-ins.adoc +// * web_console/deploy-plug-in-cluster.adoc :_content-type: PROCEDURE [id="disabling-your-plug-in-browser_{context}"] diff --git a/modules/dynamic-plug-in-api.adoc b/modules/dynamic-plug-in-api.adoc new file mode 100644 index 0000000000..8e84752e77 --- /dev/null +++ b/modules/dynamic-plug-in-api.adoc @@ -0,0 +1,1470 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins-reference.adoc + +:_content-type: REFERENCE +[id="dynamic-plug-in-api_{context}"] += {product-title} console API + +[discrete] +== `useActivePerspective` + +Hook that provides the currently active perspective and a callback for setting the active perspective. It returns a tuple containing the current active perspective and setter callback. + +[source,tsx] +---- +const Component: React.FC = (props) => { + const [activePerspective, setActivePerspective] = useActivePerspective(); + return +} +---- + +[discrete] +== `GreenCheckCircleIcon` + +Component for displaying a green check mark circle icon. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`className` |(optional) additional class name for the component +|`title` |(optional) icon title +|`size` |(optional) icon size: ('sm', 'md', 'lg', 'xl') +|=== + +[discrete] +== `RedExclamationCircleIcon` + +Component for displaying a red exclamation mark circle icon. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`className` |(optional) additional class name for the component +|`title` |(optional) icon title +|`size` |(optional) icon size: ('sm', 'md', 'lg', 'xl') +|=== + +[discrete] +== `YellowExclamationTriangleIcon` + +Component for displaying a yellow triangle exclamation icon. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`className` |(optional) additional class name for the component +|`title` |(optional) icon title +|`size` |(optional) icon size: ('sm', 'md', 'lg', 'xl') +|=== + +[discrete] +== `BlueInfoCircleIcon` + +Component for displaying a blue info circle icon. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`className` |(optional) additional class name for the component +|`title` |(optional) icon title +|`size` |(optional) icon size: ('sm', 'md', 'lg', 'xl') +|=== + +[discrete] +== `ErrorStatus` + +Component for displaying an error status popover. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`title` |(optional) status text +|`iconOnly` |(optional) if true, only displays icon +|`noTooltip` |(optional) if true, tooltip won't be displayed +|`className` |(optional) additional class name for the component +|`popoverTitle` |(optional) title for popover +|=== + +[discrete] +== `InfoStatus` + +Component for displaying an information status popover. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`title` |(optional) status text +|`iconOnly` |(optional) if true, only displays icon +|`noTooltip` |(optional) if true, tooltip won't be displayed +|`className` |(optional) additional class name for the component +|`popoverTitle` |(optional) title for popover +|=== + +[discrete] +== `ProgressStatus` + +Component for displaying a progressing status popover. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`title` |(optional) status text +|`iconOnly` |(optional) if true, only displays icon +|`noTooltip` |(optional) if true, tooltip won't be displayed +|`className` |(optional) additional class name for the component +|`popoverTitle` |(optional) title for popover +|=== + +[discrete] +== `SuccessStatus` + +Component for displaying a success status popover. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`title` |(optional) status text +|`iconOnly` |(optional) if true, only displays icon +|`noTooltip` |(optional) if true, tooltip won't be displayed +|`className` |(optional) additional class name for the component +|`popoverTitle` |(optional) title for popover +|=== + +[discrete] +== `checkAccess` + +Provides information about user access to a given resource. It returns an object with resource access information. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resourceAttributes` |resource attributes for access review +|`impersonate` |impersonation details +|=== + +[discrete] +== `useAccessReview` + +Hook that provides information about user access to a given resource. It returns an array with `isAllowed` and `loading` values. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resourceAttributes` |resource attributes for access review +|`impersonate` |impersonation details +|=== + +[discrete] +== `useResolvedExtensions` + +React hook for consuming Console extensions with resolved `CodeRef` properties. This hook accepts the same argument(s) as `useExtensions` hook and returns an adapted list of extension instances, resolving all code references within each extension's properties. Initially, the hook returns an empty array. Once the resolution is complete, the React component is re-rendered with the hook returning an adapted list of extensions. When the list of matching extensions changes, the resolution is restarted. The hook will continue to return the previous result until the resolution completes. The hook's result elements are guaranteed to be referentially stable across re-renders. It returns a tuple containing a list of adapted extension instances with resolved code references, a boolean flag indicating whether the resolution is complete, and a list of errors detected during the resolution. + +[source,tsx] +---- +const [navItemExtensions, navItemsResolved] = useResolvedExtensions(isNavItem); +// process adapted extensions and render your component +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`typeGuards` |A list of callbacks that each accept a dynamic plugin +extension as an argument and return a boolean flag indicating whether or +not the extension meets desired type constraints +|=== + +[discrete] +== `HorizontalNav` + +A component that creates a Navigation bar for a page.- Routing is handled as part of the component.- `console.tab/horizontalNav` can be used to add additional content to any horizontal nav. + +[source,tsx] +---- +const HomePage: React.FC = (props) => { + const page = { + href: '/home', + name: 'Home', + component: () => <>Home + } + return +} +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resource` |The resource associated with this Navigation, an object of +K8sResourceCommon type + +|`pages` |An array of page objects + +|`match` |match object provided by React Router +|=== + +[discrete] +== `VirtualizedTable` + +A component for making virtualized tables. + +[source,tsx] +---- +const MachineList: React.FC = (props) => { + return ( + + {...props} + aria-label='Machines' + columns={getMachineColumns} + Row={getMachineTableRow} + /> + ); +} +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`data` |data for table +|`loaded` |flag indicating data is loaded +|`loadError` |error object if issue loading data +|`columns` |column setup +|`Row` |row setup +|`unfilteredData` |original data without filter +|`NoDataEmptyMsg` |(optional) no data empty message component +|`EmptyMsg` |(optional) empty message component +|`scrollNode` |(optional) function to handle scroll +|`label` |(optional) label for table +|`ariaLabel` |(optional) aria label +|`gridBreakPoint` |sizing of how to break up grid for responsiveness +|`onSelect` |(optional) function for handling select of table +|`rowData` |(optional) data specific to row +|=== + +[discrete] +== `TableData` + +Component for displaying table data within a table row. + +[source,tsx] + +---- +const PodRow: React.FC> = ({ obj, activeColumnIDs }) => { + return ( + <> + + + + + + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`id` |unique id for table +|`activeColumnIDs` |active columns +|`className` |(optional) option class name for styling +|=== + +[discrete] +== `useActiveColumns` + +A hook that provides a list of user-selected active TableColumns. + +[source,tsx] +---- + // See implementation for more details on TableColumn type + const [activeColumns, userSettingsLoaded] = useActiveColumns({ + columns, + showNamespaceOverride: false, + columnManagementID, + }); + return userSettingsAreLoaded ? : null +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |Which are passed as a key-value map + +|`` |\{TableColumn[]} options.columns - An array of all available +TableColumns + +|`` |\{boolean} [options.showNamespaceOverride] - (optional) If true, a +namespace column will be included, regardless of column management +selections + +|`` |\{string} [options.columnManagementID] - (optional) A unique id +used to persist and retrieve column management selections to and from +user settings. Usually a 'group~verion~kind' string for a resource. +|=== + +A tuple containing the current user selected active columns (a subset of options.columns), and a boolean flag indicating whether user settings have been loaded. + +[discrete] +== `ListPageHeader` + +Component for generating a page header. + +[source,tsx] +---- +const exampleList: React.FC = () => { + return ( + <> + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`title` |heading title +|`helpText` |(optional) help section as react node +|`badge` |(optional) badge icon as react node +|=== + +[discrete] +== `ListPageCreate` + +Component for adding a create button for a specific resource kind that automatically generates a link to the create YAML for this resource. + +[source,tsx] +---- +const exampleList: React.FC = () => { + return ( + <> + + Create Pod + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`groupVersionKind` |the resource group/version/kind to represent +|=== + +[discrete] +== `ListPageCreateLink` + +Component for creating a stylized link. + +[source,tsx] +---- +const exampleList: React.FC = () => { + return ( + <> + + Create Item + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`to` |string location where link should direct + +|`createAccessReview` |(optional) object with namespace and kind used to +determine access + +|`children` |(optional) children for the component +|=== + +[discrete] +== `ListPageCreateButton` + +Component for creating button. + +[source,tsx] +---- +const exampleList: React.FC = () => { + return ( + <> + + Create Pod + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`createAccessReview` |(optional) object with namespace and kind used to +determine access + +|`pfButtonProps` |(optional) Patternfly Button props +|=== + +[discrete] +== `ListPageCreateDropdown` + +Component for creating a dropdown wrapped with permissions check. + +[source,tsx] +---- +const exampleList: React.FC = () => { + const items = { + SAVE: 'Save', + DELETE: 'Delete', + } + return ( + <> + + Actions + + + ); +}; +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`items` |key:ReactNode pairs of items to display in dropdown component + +|`onClick` |callback function for click on dropdown items + +|`createAccessReview` |(optional) object with namespace and kind used to +determine access + +|`children` |(optional) children for the dropdown toggle +|=== + +[discrete] +== `ListPageFilter` + +Component that generates filter for list page. + +[source,tsx] +---- + // See implementation for more details on RowFilter and FilterValue types + const [staticData, filteredData, onFilterChange] = useListPageFilter( + data, + rowFilters, + staticFilters, + ); + // ListPageFilter updates filter state based on user interaction and resulting filtered data can be rendered in an independent component. + return ( + <> + + + + + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`data` |An array of data points + +|`loaded` |indicates that data has loaded + +|`onFilterChange` |callback function for when filter is updated + +|`rowFilters` |(optional) An array of RowFilter elements that define the +available filter options + +|`nameFilterPlaceholder` |(optional) placeholder for name filter + +|`labelFilterPlaceholder` |(optional) placeholder for label filter + +|`hideLabelFilter` |(optional) only shows the name filter instead of +both name and label filter + +|`hideNameLabelFilter` |(optional) hides both name and label filter + +|`columnLayout` |(optional) column layout object + +|`hideColumnManagement` |(optional) flag to hide the column management +|=== + +[discrete] +== `useListPageFilter` + +A hook that manages filter state for the ListPageFilter component. It returns a tuple containing the data filtered by all static filters, the data filtered by all static and row filters, and a callback that updates rowFilters. + +[source,tsx] +---- + // See implementation for more details on RowFilter and FilterValue types + const [staticData, filteredData, onFilterChange] = useListPageFilter( + data, + rowFilters, + staticFilters, + ); + // ListPageFilter updates filter state based on user interaction and resulting filtered data can be rendered in an independent component. + return ( + <> + + + + + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`data` |An array of data points + +|`rowFilters` |(optional) An array of RowFilter elements that define the +available filter options + +|`staticFilters` |(optional) An array of FilterValue elements that are +statically applied to the data +|=== + +[discrete] +== `ResourceLink` + +Component that creates a link to a specific resource type with an icon badge. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`kind` |(optional) the kind of resource i.e. Pod, Deployment, Namespace + +|`groupVersionKind` |(optional) object with groupd, version, and kind + +|`className` |(optional) class style for component + +|`displayName` |(optional) display name for component, overwrites the +resource name if set + +|`inline` |(optional) flag to create icon badge and name inline with +children + +|`linkTo` |(optional) flag to create a Link object - defaults to true + +|`name` |(optional) name of resource + +|`namesapce` |(optional) specific namespace for the kind resource to +link to + +|`hideIcon` |(optional) flag to hide the icon badge + +|`title` |(optional) title for the link object (not displayed) + +|`dataTest` |(optional) identifier for testing + +|`onClick` |(optional) callback function for when component is clicked + +|`truncate` |(optional) flag to truncate the link if too long +|=== + +[discrete] +== `ResourceIcon` + +Component that creates an icon badge for a specific resource type. + +[source,tsx] +---- + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`kind` |(optional) the kind of resource i.e. Pod, Deployment, Namespace +|`groupVersionKind` |(optional) object with group, version, and kind +|`className` |(optional) class style for component +|=== + +[discrete] +== `useK8sModel` + +Hook that retrieves the k8s model for provided K8sGroupVersionKind from redux. It returns an array with the first item as k8s model and second item as `inFlight` status. + +[source,tsx] +---- +const Component: React.FC = () => { + const [model, inFlight] = useK8sModel({ group: 'app'; version: 'v1'; kind: 'Deployment' }); + return ... +} +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`groupVersionKind` |group, version, kind of k8s resource \{@link +K8sGroupVersionKind} is preferred alternatively can pass reference for +group, version, kind which is deprecated i.e `group~version~kind` +\{@link K8sResourceKindReference}. +|=== + +[discrete] +== `useK8sModels` + +Hook that retrieves all current k8s models from redux. It returns an array with the first item as the list of k8s model and second item as `inFlight` status. + +[source,tsx] +---- +const Component: React.FC = () => { + const [models, inFlight] = UseK8sModels(); + return ... +} +---- + +[discrete] +== `useK8sWatchResource` + +Hook that retrieves the k8s resource along with status for loaded and error. It returns an array with first item as resource(s), second item as loaded status and third item as error state if any. + +[source,tsx] +---- +const Component: React.FC = () => { + const watchRes = { + ... + } + const [data, loaded, error] = useK8sWatchResource(watchRes) + return ... +} +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`initResource` |options needed to watch for resource. +|=== + +[discrete] +== `useK8sWatchResources` + +Hook that retrieves the k8s resources along with their respective status for loaded and error. It returns a map where keys are as provided in initResouces and value has three properties data, loaded and error. + +[source,tsx] +---- +const Component: React.FC = () => { + const watchResources = { + 'deployment': {...}, + 'pod': {...} + ... + } + const {deployment, pod} = useK8sWatchResources(watchResources) + return ... +} +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`initResources` |resources need to be watched as key-value pair, +wherein key will be unique to resource and value will be options needed +to watch for the respective resource. +|=== + +[discrete] +== `consoleFetch` + +A custom wrapper around `fetch` that adds console specific headers and allows for retries and timeouts.It also validates the response status code and throws appropriate error or logs out the user if required. It returns a promise that resolves to the response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`url` |The URL to fetch +|`options` |The options to pass to fetch +|`timeout` |The timeout in milliseconds +|=== + +[discrete] +== `consoleFetchJSON` + +A custom wrapper around `fetch` that adds console specific headers and allows for retries and timeouts. It also validates the response status code and throws appropriate error or logs out the user if required. It returns the response as a JSON object. Uses `consoleFetch` internally. It returns a promise that resolves to the response as JSON object. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`url` |The URL to fetch + +|`method` |The HTTP method to use. Defaults to GET + +|`options` |The options to pass to fetch + +|`timeout` |The timeout in milliseconds + +|`cluster` |The name of the cluster to make the request to. Defaults to +the active cluster the user has selected +|=== + +[discrete] +== `consoleFetchText` + +A custom wrapper around `fetch` that adds console specific headers and allows for retries and timeouts. It also validates the response status code and throws appropriate error or logs out the user if required. It returns the response as a text. Uses `consoleFetch` internally. It returns a promise that resolves to the response as text. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`url` |The URL to fetch + +|`options` |The options to pass to fetch + +|`timeout` |The timeout in milliseconds + +|`cluster` |The name of the cluster to make the request to. Defaults to +the active cluster the user has selected +|=== + +[discrete] +== `getConsoleRequestHeaders` + +A function that creates impersonation and multicluster related headers for API requests using current redux state. it returns an object containing the appropriate impersonation and clustr requst headers, based on redux state. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`targetCluster` |override the current active cluster with the provided +targetCluster +|=== + +[discrete] +== `k8sGetResource` + +It fetches a resource from the cluster, based on the provided options. If the name is provided it returns one resource else it returns all the resources matching the model. It returns a promise that resolves to the response as JSON object with a resource if the name is providedelse it returns all the resources matching the +model. In case of failure, the promise gets rejected with HTTP error response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |Which are passed as key-value pairs in the map + +|`` |options.model - k8s model + +|`` |options.name - The name of the resource, if not provided then it'll +look for all the resources matching the model. + +|`` |options.ns - The namespace to look into, should not be specified +for cluster-scoped resources. + +|`` |options.path - Appends as subpath if provided + +|`` |options.queryParams - The query parameters to be included in the +URL. + +|`` |options.requestInit - The fetch init object to use. This can have +request headers, method, redirect, etc. See more (link: +https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.html) + +|=== + +[discrete] +== `k8sCreateResource` + +It creates a resource in the cluster, based on the provided options. It returns a promise that resolves to the response of the resource created. In case of failure promise gets rejected with HTTP error response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |Which are passed as key-value pairs in the map + +|`` |options.model - k8s model + +|`` |options.data - payload for the resource to be created + +|`` |options.path - Appends as subpath if provided + +|`` |options.queryParams - The query parameters to be included in the +URL. +|=== + +[discrete] +== `k8sUpdateResource` + +It updates the entire resource in the cluster, based on providedoptions. When a client needs to replace an existing resource entirely, they can use k8sUpdate. Alternatively can use k8sPatch to perform the partial update. It returns a promise that resolves to the response of the resource updated. In case of failure promise gets rejected with HTTP error response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |which are passed as key-value pair in the map + +|`` |options.model - k8s model + +|`` |options.data - payload for the k8s resource to be updated + +|`` |options.ns - namespace to look into, it should not be specified for +cluster-scoped resources. + +|`` |options.name - resource name to be updated. + +|`` |options.path - Appends as subpath if provided + +|`` |options.queryParams - The query parameters to be included in the +URL. +|=== + +[discrete] +== `k8sPatchResource` + +It patches any resource in the cluster, based on provided options. When a client needs to perform the partial update, they can use +k8sPatch. Alternatively can use k8sUpdate to replace an existing resource entirely. See more link:https://datatracker.ietf.org/doc/html/rfc6902[Data Tracker]. It returns a promise that resolves to the response of the resource patched. In case of failure promise gets rejected with HTTP error response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |Which are passed as key-value pairs in the map. + +|`` |options.model - k8s model + +|`` |options.resource - The resource to be patched. + +|`` |options.data - Only the data to be patched on existing resource +with the operation, path, and value. + +|`` |options.path - Appends as subpath if provided. + +|`` |options.queryParams - The query parameters to be included in the +URL. +|=== + +[discrete] +== `k8sDeleteResource` + +It deletes resources from the cluster, based on the provided model, resource. The garbage collection works based on 'Foreground'|'Background', can be configured with propagationPolicy property in provided model or passed in json. It returns a promise that resolves to the response of kind Status. In case of failure promise gets rejected with HTTP error response. + +.... +{ kind: 'DeleteOptions', apiVersion: 'v1', propagationPolicy } +.... + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |which are passed as key-value pair in the map. + +|`` |options.model - k8s model + +|`` |options.resource - The resource to be deleted. + +|`` |options.path - Appends as subpath if provided + +|`` |options.queryParams - The query parameters to be included in the +URL. + +|`` |options.requestInit - The fetch init object to use. This can have +request headers, method, redirect, etc. See more \{@link +https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.html +} + +|`` |options.json - Can control garbage collection of resources +explicitly if provided else will default to model's "propagationPolicy". +|=== + +[discrete] +== `k8sListResource` + +Lists the resources as an array in the cluster, based on provided options. It returns a promise that resolves to the response. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`options` |Which are passed as key-value pairs in the map + +|`` |options.model - k8s model + +|`` |options.queryParams - The query parameters to be included in the +URL and can pass label selector's as well with key "labelSelector". + +|`` |options.requestInit - The fetch init object to use. This can have +request headers, method, redirect, etc. See more \{@link +https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.html +} +|=== + +[discrete] +== `k8sListResourceItems` + +Same interface as \{@link k8sListResource} but returns the sub items. It returns the apiVersion for the model i.e `group/version`. + +[discrete] +== `getAPIVersionForModel` + +Provides apiVersion for a k8s model. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`model` |k8s model +|=== + +[discrete] +== `getGroupVersionKindForResource` + +Provides a group, version, and kind for a resource. It returns the group, version, kind for the provided resource. If the resource does not have an API group, group "core" will be returned.If the resource has an invalid apiVersion then it'll throw Error. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resource` |k8s resource +|=== + +[discrete] +== `getGroupVersionKindForModel` + +Provides a group, version, and kind for a k8s model. This returns the group, version, kind for the provided model. If the model does not have an apiGroup, group "core" will be returned. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`model` |k8s model +|=== + +[discrete] +== `StatusPopupSection` + +Component that shows the status in a popup window. Helpful component for building `console.dashboards/overview/health/resource` extensions. + +[source,tsx] +---- + + {title} + + My Example Item + + + } + secondColumn='Status' + > +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`firstColumn` |values for first column of popup +|`secondColumn` |(optional) values for second column of popup +|`children` |(optional) children for the popup +|=== + +[discrete] +== `StatusPopupItem` + +Status element used in status popup; used in `StatusPopupSection`. + +[source,tsx] +---- + + + Complete + + + Pending + + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`value` |(optional) text value to display +|`icon` |(optional) icon to display +|`children` |child elements +|=== + +[discrete] +== `Overview` + +Creates a wrapper component for a dashboard. + +[source,tsx] +---- + + + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`className` |(optional) style class for div +|`children` |(optional) elements of the dashboard +|=== + +[discrete] +== `OverviewGrid` + +Creates a grid of card elements for a dashboard; used within `Overview`. + +[source,tsx] +---- + + + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`mainCards` |cards for grid +|`leftCards` |(optional) cards for left side of grid +|`rightCards` |(optional) cards for right side of grid +|=== + +[discrete] +== `InventoryItem` + +Creates an inventory card item. + +[source,tsx] +---- + return ( + + {title} + + {loaded && } />} + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`children` |elements to render inside the item +|=== + +[discrete] +== `InventoryItemTitle` + +Creates a title for an inventory card item; used within `InventoryItem`. + +[source,tsx] +---- + return ( + + {title} + + {loaded && } />} + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`children` |elements to render inside the title +|=== + +[discrete] +== `InventoryItemBody` + +Creates the body of an inventory card; used within `InventoryCard` and can be used with `InventoryTitle`. + +[source,tsx] +---- + return ( + + {title} + + {loaded && } />} + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`children` |elements to render inside the Inventory Card or title +|`error` |elements of the div +|=== + +[discrete] +== `InventoryItemStatus` + +Creates a count and icon for an inventory card with optional link address; used within `InventoryItemBody` + +[source,tsx] +---- + return ( + + {title} + + {loaded && } />} + + + ) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`count` |count for display +|`icon` |icon for display +|`linkTo` |(optional) link address +|=== + +[discrete] +== `InventoryItemLoading` + +Creates a skeleton container for when an inventory card is loading; used with `InventoryItem` and related components + +[source,tsx] +---- +if (loadError) { + title = {t('Worker Nodes')}; +} else if (!loaded) { + title = <>{t('Worker Nodes')}; +} +return ( + + {title} + +) +---- + +[discrete] +== `useFlag` + +Hook that returns the given feature flag from FLAGS redux state. It returns the boolean value of the requested feature flag or undefined. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`flag` |The feature flag to return +|=== + +[discrete] +== `YAMLEditor` + +A basic lazy loaded YAML editor with hover help and completion. + +[source,tsx] +---- +}> + + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`value` |String representing the yaml code to render. + +|`options` |Monaco editor options. For more details, please, visit +https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.IStandaloneEditorConstructionOptions.html. + +|`minHeight` |Minimum editor height in valid CSS height values. + +|`showShortcuts` |Boolean to show shortcuts on top of the editor. + +|`toolbarLinks` |Array of ReactNode rendered on the toolbar links +section on top of the editor. + +|`onChange` |Callback for on code change event. + +|`onSave` |Callback called when the command CTRL / CMD + S is triggered. + +|`ref` |React reference to `{ editor?: IStandaloneCodeEditor }`. Using +the 'editor' property, you are able to access to all methods to control +the editor. For more information, visit +https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.IStandaloneCodeEditor.html. +|=== + +[discrete] +== `ResourceYAMLEditor` + +A lazy loaded YAML editor for Kubernetes resources with hover help and completion. The component use the YAMLEditor and add on top of it more functionality likeresource update handling, alerts, save, cancel and reload buttons, accessibility and more. Unless `onSave` callback is provided, the resource update is automatically handled.It should be +wrapped in a React.Suspense component. + +[source,tsx] +---- +}> + updateResource(content)} + /> + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`initialResource` |YAML/Object representing a resource to be shown by +the editor. This prop is used only during the inital render + +|`header` |Add a header on top of the YAML editor + +|`onSave` |Callback for the Save button. Passing it will override the +default update performed on the resource by the editor +|=== + +[discrete] +== `ResourceEventStream` + +A component to show events related to a particular resource. + +[source,tsx] +---- +const [resource, loaded, loadError] = useK8sWatchResource(clusterResource); +return +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resource` |An object whose related events should be shown. +|=== + +[discrete] +== `usePrometheusPoll` + +Sets up a poll to Prometheus for a single query. It returns a tuple containing the query response, a boolean flag indicating whether the response has completed, and any errors encountered during the request or post-processing of the request. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`` |\{PrometheusEndpoint} props.endpoint - one of the +PrometheusEndpoint (label, query, range, rules, targets) + +|`` |\{string} [props.query] - (optional) Prometheus query string. If +empty or undefined, polling is not started. + +|`` |\{number} [props.delay] - (optional) polling delay interval (ms) + +|`` |\{number} [props.endTime] - (optional) for QUERY_RANGE enpoint, end +of the query range + +|`` |\{number} [props.samples] - (optional) for QUERY_RANGE enpoint + +|`` |\{number} [options.timespan] - (optional) for QUERY_RANGE enpoint + +|`` |\{string} [options.namespace] - (optional) a search param to append + +|`` |\{string} [options.timeout] - (optional) a search param to append +|=== + +[discrete] +== `Timestamp` + +A component to render timestamp. The timestamps are synchronized between invidual instances of the Timestamp component. The provided timestamp is formatted according to user locale. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`timestamp` |the timestamp to render. Format is expected to be ISO 8601 +(used by Kubernetes), epoch timestamp, or an instance of a Date. + +|`simple` |render simple version of the component omitting icon and +tooltip. + +|`omitSuffix` |formats the date ommiting the suffix. + +|`className` |additional class name for the component. +|=== + +[discrete] +== `useModal` + +A hook to launch Modals. + +[source,tsx] +---- +const context: AppPage: React.FC = () => {
const [launchModal] = useModal();
const onClick = () => launchModal(ModalComponent);
return (

)
}
` +---- + +[discrete] +== `ActionServiceProvider` + +Component that allows to receive contributions from other plugins for the `console.action/provider` extension type. + +[source,tsx] +---- + const context: ActionContext = { 'a-context-id': { dataFromDynamicPlugin } }; + + ... + + + {({ actions, options, loaded }) => + loaded && ( + + ) + } + +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`context` |Object with contextId and optional plugin data +|=== + +[discrete] +== `NamespaceBar` + +A component that renders a horizontal toolbar with a namespace dropdown menu in the leftmost position. Additional components can be passed in as children and will be rendered to the right of the namespace dropdown. This component is designed to be used at the top of the page. It should be used on pages where the user needs to be able to change the active namespace, such as on pages with k8s resources. + +[source,tsx] +---- + const logNamespaceChange = (namespace) => console.log(`New namespace: ${namespace}`); + + ... + + + + + + + ... +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`onNamespaceChange` |(optional) A function that is executed when a +namespace option is selected. It accepts the new namespace in the form +of a string as its only argument. The active namespace is updated +automatically when an option is selected, but additional logic can be +applied via this function. When the namespace is changed, the namespace +parameter in the URL will be changed from the previous namespace to the +newly selected namespace. + +|`isDisabled` |(optional) A boolean flag that disables the namespace +dropdown if set to true. This option only applies to the namespace +dropdown and has no effect on child components. + +|`children` |(optional) Additional elements to be rendered inside the +toolbar to the right of the namespace dropdown. +|=== + +[discrete] +== `ErrorBoundaryFallbackPage` + +Creates full page ErrorBoundaryFallbackPage component to display the "Oh no! Something went wrong." message along with the stack trace and other helpful debugging information. This is to be used inconjunction with an component. + +[source,tsx] +---- +//in ErrorBoundary component + return ( + if (this.state.hasError) { + return ; + } + + return this.props.children; +) +---- + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`errorMessage` |text description of the error message +|`componentStack` |component trace of the exception +|`stack` |stack trace of the exception +|`title` |title to render as the header of the error boundary page +|=== + +[discrete] +== `PerspectiveContext` + +@deprecated - use the provided `usePerspectiveContext` insteadCreates the perspective context. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`PerspectiveContextType` |object with active perspective and setter +|=== + +[discrete] +== `useAccessReviewAllowed` + +@deprecated - Use useAccessReview from @console/dynamic-plugin-sdk instead.Hook that provides allowed status about user access to a given +resource. It returns the `isAllowed` boolean value. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`resourceAttributes` |resource attributes for access review +|`impersonate` |impersonation details +|=== + +[discrete] +== `useSafetyFirst` + +@deprecated - This hook is not related to console functionality.Hook that ensures a safe asynchronnous setting of React state in case a given +component could be unmounted. It returns an array with a pair of state value and it's set function. + +[cols=",",options="header",] +|=== +|Parameter Name |Description +|`initialState` |initial state value +|=== \ No newline at end of file diff --git a/modules/dynamic-plug-in-development.adoc b/modules/dynamic-plug-in-development.adoc new file mode 100644 index 0000000000..b1cc6b0abb --- /dev/null +++ b/modules/dynamic-plug-in-development.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins-get-started.adoc + +:_content-type: PROCEDURE +[id="dynamic-plugin-development_{context}"] += Dynamic plug-in development + +You can run the plug-in using a local development environment. The {product-title} web console runs in a container connected to the cluster you have logged into. + +.Prerequisites +* You must have an OpenShift cluster running. +* You must have the OpenShift CLI (`oc`) installed. +* You must have link:https://yarnpkg.com/[`yarn`] installed. +* You must have link:https://www.docker.com/[Docker] v3.2.0 or newer or link:https://podman.io/[Podman] installed and running. + +.Procedure + +. In your terminal, run the following command to install the dependencies for your plug-in using yarn. + ++ +[source,terminal] +---- +$ yarn install +---- + +. After installing, run the following command to start yarn. + ++ +[source,terminal] +---- +$ yarn run start +---- + +. In another terminal window, login to the {product-title} through the CLI. ++ +[source,terminal] +---- +$ oc login +---- + +. Run the {product-title} web console in a container connected to the cluster you have logged into by running the following command: ++ +[source,terminal] +---- +$ yarn run start-console +---- + +.Verification +* Visit link:http://localhost:9000/example[localhost:9000] to view the running plug-in. Inspect the value of `window.SERVER_FLAGS.consolePlugins` to see the list of plug-ins which load at runtime. diff --git a/modules/dynamic-plug-in-sdk-extensions.adoc b/modules/dynamic-plug-in-sdk-extensions.adoc index 4e1e8d42c0..3946008514 100644 --- a/modules/dynamic-plug-in-sdk-extensions.adoc +++ b/modules/dynamic-plug-in-sdk-extensions.adoc @@ -1,20 +1,16 @@ // Module is included in the following assemblies: // -// * openshift-docs/web_console/dynamic-plug-ins.adoc +// * web_console/dynamic-plug-ins-reference.adoc :_content-type: CONCEPT [id="dynamic-plug-in-sdk-extensions_{context}"] = Dynamic plug-in extension types -[[consoleactionfilter]] +[discrete] == `console.action/filter` -=== Summary - `ActionFilter` can be used to filter an action. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -28,17 +24,11 @@ remove the `ModifyCount` action from a deployment with a horizontal pod autoscaler (HPA). |=== -''''' - -[[consoleactiongroup]] +[discrete] == `console.action/group` -=== Summary - `ActionGroup` contributes an action group that can also be a submenu. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -58,17 +48,10 @@ item referenced here. For arrays, the first one found in order is used. The `insertBefore` value takes precedence. |=== -''''' - -[[consoleactionprovider]] +[discrete] == `console.action/provider` -=== Summary - -`ActionProvider` contributes a hook that returns list of actions for -specific context. - -=== Properties +`ActionProvider` contributes a hook that returns list of actions for specific context. [cols=",,,",options="header",] |=== @@ -81,17 +64,10 @@ that returns actions for the given scope. If `contextId` = `resource`, then the scope will always be a Kubernetes resource object. |=== -''''' - -[[consoleactionresource-provider]] +[discrete] == `console.action/resource-provider` -=== Summary - -`ResourceActionProvider` contributes a hook that returns list of actions -for specific resource model. - -=== Properties +`ResourceActionProvider` contributes a hook that returns list of actions for specific resource model. [cols=",,,",options="header",] |=== @@ -103,17 +79,9 @@ provider provides actions for. which returns actions for the given resource model |=== -''''' - -[[consolealert-action]] +[discrete] == `console.alert-action` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -124,17 +92,9 @@ which returns actions for the given resource model |`action` |`CodeRef<(alert: any) => void>` |no | |=== -''''' - -[[consolecatalogitem-filter]] +[discrete] == `console.catalog/item-filter` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -148,17 +108,9 @@ of a specific type. Value is a function that takes `CatalogItem[]` and returns a subset based on the filter criteria. |=== -''''' - -[[consolecatalogitem-metadata]] +[discrete] == `console.catalog/item-metadata` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -172,17 +124,9 @@ catalog this provider contributes to. |no |A hook which returns a function that will be used to provide metadata to catalog items of a specific type. |=== -''''' - -[[consolecatalogitem-provider]] +[discrete] == `console.catalog/item-provider` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -203,17 +147,9 @@ Higher priority providers may override catalog items provided by other providers. |=== -''''' - -[[consolecatalogitem-type]] +[discrete] == `console.catalog/item-type` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -234,17 +170,9 @@ the catalog item. to the catalog item. |=== -''''' - -[[consolecatalogitem-type-metadata]] +[discrete] == `console.catalog/item-type-metadata` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -257,17 +185,11 @@ the catalog item. to the catalog item. |=== -''''' - -[[consolecluster-overviewinventory-item]] +[discrete] == `console.cluster-overview/inventory-item` -=== Summary - Adds a new inventory item into cluster overview page. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -275,17 +197,11 @@ Adds a new inventory item into cluster overview page. be rendered. |=== -''''' - -[[consolecluster-overviewmultiline-utilization-item]] +[discrete] == `console.cluster-overview/multiline-utilization-item` -=== Summary - Adds a new cluster overview multi-line utilization item. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -301,17 +217,11 @@ utilization query. Top consumer popover instead of plain value |=== -''''' - -[[consolecluster-overviewutilization-item]] +[discrete] == `console.cluster-overview/utilization-item` -=== Summary - Adds a new cluster overview utilization item. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -333,17 +243,11 @@ query. consumer popover instead of plain value |=== -''''' - -[[consolecontext-provider]] +[discrete] == `console.context-provider` -=== Summary - Adds a new React context provider to the web console application root. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -351,17 +255,11 @@ Adds a new React context provider to the web console application root. |`useValueHook` |`CodeRef<() => T>` |no |Hook for the Context value. |=== -''''' - -[[consoledashboardscard]] +[discrete] == `console.dashboards/card` -=== Summary - Adds a new dashboard card. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -378,17 +276,10 @@ component. Ignored for small screens; defaults to `12`. |=== -''''' - -[[consoledashboardsoverviewactivityresource]] +[discrete] == `console.dashboards/overview/activity/resource` -=== Summary - -Adds an activity to the Activity Card of Overview Dashboard where the -triggering of activity is based on watching a Kubernetes resource. - -=== Properties +Adds an activity to the Activity Card of Overview Dashboard where the triggering of activity is based on watching a Kubernetes resource. [cols=",,,",options="header",] |=== @@ -407,16 +298,10 @@ every resource represents activity. the given action, which will be used for ordering. |=== -''''' - -[[consoledashboardsoverviewdetailitem]] +[discrete] == `console.dashboards/overview/detail/item` -=== Summary - -Adds an item to the *Details* card of *Overview* dashboard - -=== Properties +Adds an item to the *Details* card of *Overview* dashboard. [cols=",,,",options="header",] |=== @@ -425,17 +310,11 @@ Adds an item to the *Details* card of *Overview* dashboard on the `DetailItem` component |=== -''''' - -[[consoledashboardsoverviewhealthoperator]] +[discrete] == `console.dashboards/overview/health/operator` -=== Summary - Adds a health subsystem to the status card of the *Overview* dashboard, where the source of status is a Kubernetes REST API. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -456,17 +335,10 @@ provided, then a list page of the first resource from resources prop is used. |=== -''''' - -[[consoledashboardsoverviewhealthprometheus]] +[discrete] == `console.dashboards/overview/health/prometheus` -=== Summary - -Adds a health subsystem to the status card of Overview dashboard where -the source of status is Prometheus. - -=== Properties +Adds a health subsystem to the status card of Overview dashboard where the source of status is Prometheus. [cols=",,,",options="header",] |=== @@ -492,17 +364,10 @@ link, which opens a pop-up menu with the given content. topology for which the subsystem should be hidden. |=== -''''' - -[[consoledashboardsoverviewhealthresource]] +[discrete] == `console.dashboards/overview/health/resource` -=== Summary - -Adds a health subsystem to the status card of Overview dashboard where -the source of status is a Kubernetes Resource. - -=== Properties +Adds a health subsystem to the status card of Overview dashboard where the source of status is a Kubernetes Resource. [cols=",,,",options="header",] |=== @@ -521,17 +386,10 @@ opens a pop-up menu with the given content. |`popupTitle` |`string` |yes |The title of the popover. |=== -''''' - -[[consoledashboardsoverviewhealthurl]] +[discrete] == `console.dashboards/overview/health/url` -=== Summary - -Adds a health subsystem to the status card of Overview dashboard where -the source of status is a Kubernetes REST API. - -=== Properties +Adds a health subsystem to the status card of Overview dashboard where the source of status is a Kubernetes REST API. [cols=",,,",options="header",] |=== @@ -556,17 +414,11 @@ represented as a link which opens popup with given content. |`popupTitle` |`string` |yes |The title of the popover. |=== -''''' - -[[consoledashboardsoverviewinventoryitem]] +[discrete] == `console.dashboards/overview/inventory/item` -=== Summary - Adds a resource tile to the overview inventory card. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -580,17 +432,11 @@ various statuses to groups. resources which will be fetched and passed to the `mapper` function. |=== -''''' - -[[consoledashboardsoverviewinventoryitemgroup]] +[discrete] == `console.dashboards/overview/inventory/item/group` -=== Summary - Adds an inventory status group. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -601,17 +447,11 @@ Adds an inventory status group. |no |React component representing the status group icon. |=== -''''' - -[[consoledashboardsoverviewinventoryitemreplacement]] +[discrete] == `console.dashboards/overview/inventory/item/replacement` -=== Summary - Replaces an overview inventory card. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -624,17 +464,10 @@ various statuses to groups. resources which will be fetched and passed to the `mapper` function. |=== -''''' - -[[consoledashboardsoverviewprometheusactivityresource]] +[discrete] == `console.dashboards/overview/prometheus/activity/resource` -=== Summary - -Adds an activity to the Activity Card of Prometheus Overview Dashboard -where the triggering of activity is based on watching a Kubernetes resource. - -=== Properties +Adds an activity to the Activity Card of Prometheus Overview Dashboard where the triggering of activity is based on watching a Kubernetes resource. [cols=",,,",options="header",] |=== @@ -649,17 +482,11 @@ where the triggering of activity is based on watching a Kubernetes resource. action. If not defined, every resource represents activity. |=== -''''' - -[[consoledashboardsprojectoverviewitem]] +[discrete] == `console.dashboards/project/overview/item` -=== Summary - Adds a resource tile to the project overview inventory card. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -673,17 +500,11 @@ various statuses to groups. resources which will be fetched and passed to the `mapper` function. |=== -''''' - -[[consoledashboardstab]] +[discrete] == `console.dashboards/tab` -=== Summary - Adds a new dashboard tab, placed after the *Overview* tab. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -695,17 +516,9 @@ and when adding cards to this tab. |`title` |`string` |no |The title of the tab. |=== -''''' - -[[consolefile-upload]] +[discrete] == `console.file-upload` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -715,51 +528,32 @@ and when adding cards to this tab. file drop action. |=== -''''' - -[[consoleflag]] +[discrete] == `console.flag` -=== Summary - Gives full control over the web console feature flags. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description |`handler` |`CodeRef` |no |Used to set or unset arbitrary feature flags. |=== -''''' - -[[consoleflaghookprovider]] +[discrete] == `console.flag/hookProvider` -=== Summary - Gives full control over the web console feature flags with hook handlers. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description |`handler` |`CodeRef` |no |Used to set or unset arbitrary feature flags. |=== -''''' - -[[consoleflagmodel]] +[discrete] == `console.flag/model` -=== Summary - -Adds a new web console feature flag driven by the presence of a CRD on the -cluster. - -=== Properties +Adds a new web console feature flag driven by the presence of a CRD on the cluster. [cols=",,,",options="header",] |=== @@ -770,17 +564,9 @@ cluster. `CustomResourceDefinition`. |=== -''''' - -[[consoleglobal-config]] +[discrete] == `console.global-config` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -796,17 +582,10 @@ config resource. instance. |=== -''''' - -[[consolemodel-metadata]] +[discrete] == `console.model-metadata` -=== Summary - -Customize the display of models by overriding values retrieved and -generated through API discovery. - -=== Properties +Customize the display of models by overriding values retrieved and generated through API discovery. [cols=",,,",options="header",] |=== @@ -829,17 +608,9 @@ provided. uppercase characters in `kind`, up to 4 characters long. Requires that `kind` is provided. |=== -''''' - -[[consolenavigationhref]] +[discrete] == `console.navigation/href` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -873,17 +644,9 @@ item referenced here. For arrays, the first one found in order is used. |`prefixNamespaced` |`boolean` |yes |If `true`, adds `/k8s/ns/active-namespace` to the beginning |=== -''''' - -[[consolenavigationresource-cluster]] +[discrete] == `console.navigation/resource-cluster` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -915,17 +678,9 @@ item referenced here. For arrays, the first one found in order is used. name of the link will equal the plural value of the model. |=== -''''' - -[[consolenavigationresource-ns]] +[discrete] == `console.navigation/resource-ns` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -957,17 +712,9 @@ item referenced here. For arrays, the first one found in order is used. name of the link will equal the plural value of the model. |=== -''''' - -[[consolenavigationsection]] +[discrete] == `console.navigation/section` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -990,17 +737,9 @@ item referenced here. For arrays, the first one found in order is used. separator will be shown above the section. |=== -''''' - -[[consolenavigationseparator]] +[discrete] == `console.navigation/separator` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1023,17 +762,9 @@ item referenced here. For arrays, the first one found in order is used. `insertBefore` takes precedence. |=== -''''' - -[[consolepageresourcedetails]] +[discrete] == `console.page/resource/details` -=== Summary - -Adds a new resource details page to the web console router. - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1045,17 +776,11 @@ resource page links to. |no |The component to be rendered when the route matches. |=== -''''' - -[[consolepageresourcelist]] +[discrete] == `console.page/resource/list` -=== Summary - Adds new resource list page to Console router. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1067,18 +792,11 @@ resource page links to. |no |The component to be rendered when the route matches. |=== -''''' - -[[consolepageroute]] +[discrete] == `console.page/route` -=== Summary - Adds a new page to the web console router. See link:https://v5.reactrouter.com/[React Router]. - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1096,18 +814,10 @@ belongs to. If not specified, contributes to all perspectives. the `location.pathname` exactly. |=== -''''' - -[[consolepageroutestandalone]] +[discrete] == `console.page/route/standalone` -=== Summary - -Adds a new standalone page, rendered outside the common page layout, to -the web console router. See link:https://v5.reactrouter.com/[React Router]. - - -=== Properties +Adds a new standalone page, rendered outside the common page layout, to the web console router. See link:https://v5.reactrouter.com/[React Router]. [cols=",,,",options="header",] |=== @@ -1123,17 +833,9 @@ the web console router. See link:https://v5.reactrouter.com/[React Router]. the `location.pathname` exactly. |=== -''''' - -[[consoleperspective]] +[discrete] == `console.perspective` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1160,17 +862,11 @@ the nav |The hook to detect default perspective |=== -''''' - -[[consoleproject-overviewinventory-item]] +[discrete] == `console.project-overview/inventory-item` -=== Summary - Adds a new inventory item into the *Project Overview* page. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1178,17 +874,11 @@ Adds a new inventory item into the *Project Overview* page. |no |The component to be rendered. |=== -''''' - -[[consoleproject-overviewutilization-item]] +[discrete] == `console.project-overview/utilization-item` -=== Summary - Adds a new project overview utilization item. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1212,17 +902,9 @@ query. |`CodeRef>` |yes |Shows the top consumer popover instead of plain value. |=== -''''' - -[[consolepvcalert]] +[discrete] == `console.pvc/alert` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1230,17 +912,9 @@ query. |no |The alert component. |=== -''''' - -[[consolepvccreate-prop]] +[discrete] == `console.pvc/create-prop` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1248,17 +922,9 @@ query. |`path` |`string` |no |Path for the create prop action. |=== -''''' - -[[consolepvcdelete]] +[discrete] == `console.pvc/delete` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1272,17 +938,9 @@ query. |no |Alert component to show additional information. |=== -''''' - -[[consolepvcstatus]] +[discrete] == `console.pvc/status` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1295,17 +953,10 @@ query. |Predicate that tells whether to render the status component or not. |=== -''''' - -[[consoleredux-reducer]] +[discrete] == `console.redux-reducer` -=== Summary - -Adds new reducer to Console Redux store which operates on -`plugins.` substate. - -=== Properties +Adds new reducer to Console Redux store which operates on `plugins.` substate. [cols=",,,",options="header",] |=== @@ -1317,17 +968,9 @@ substate within the Redux state object. function, operating on the reducer-managed substate. |=== -''''' - -[[consoleresourcecreate]] +[discrete] == `console.resource/create` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1339,17 +982,9 @@ resource page will be rendered. component to be rendered when the model matches |=== -''''' - -[[consolestorage-provider]] +[discrete] == `console.storage-provider` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1360,17 +995,9 @@ component to be rendered when the model matches |no | |=== -''''' - -[[consoletabhorizontalnav]] +[discrete] == `console.tab/horizontalNav` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1385,17 +1012,9 @@ horizontal tab. It takes tab name as name and href of the tab |no |The component to be rendered when the route matches. |=== -''''' - -[[consoletelemetrylistener]] +[discrete] == `console.telemetry/listener` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1403,17 +1022,10 @@ horizontal tab. It takes tab name as name and href of the tab events |=== -''''' - -[[consoletopologyadapterbuild]] +[discrete] == `console.topology/adapter/build` -=== Summary - -`BuildAdapter` contributes an adapter to adapt element to data that can be -used by the `Build` component. - -=== Properties +`BuildAdapter` contributes an adapter to adapt element to data that can be used by the `Build` component. [cols=",,,",options="header",] |=== @@ -1423,17 +1035,10 @@ used by the `Build` component. |no | |=== -''''' - -[[consoletopologyadapternetwork]] +[discrete] == `console.topology/adapter/network` -=== Summary - -`NetworkAdapater` contributes an adapter to adapt element to data that can -be used by the `Networking` component. - -=== Properties +`NetworkAdapater` contributes an adapter to adapt element to data that can be used by the `Networking` component. [cols=",,,",options="header",] |=== @@ -1443,17 +1048,10 @@ be used by the `Networking` component. |no | |=== -''''' - -[[consoletopologyadapterpod]] +[discrete] == `console.topology/adapter/pod` -=== Summary - -`PodAdapter` contributes an adapter to adapt element to data that can be -used by the `Pod` component. - -=== Properties +`PodAdapter` contributes an adapter to adapt element to data that can be used by the `Pod` component. [cols=",,,",options="header",] |=== @@ -1463,34 +1061,22 @@ used by the `Pod` component. |no | |=== -''''' - -[[consoletopologycomponentfactory]] +[discrete] == `console.topology/component/factory` -=== Summary - Getter for a `ViewComponentFactory`. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description |`getFactory` |`CodeRef` |no |Getter for a `ViewComponentFactory`. |=== -''''' - -[[consoletopologycreateconnector]] +[discrete] == `console.topology/create/connector` -=== Summary - Getter for the create connector function. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1498,17 +1084,11 @@ Getter for the create connector function. the create connector function. |=== -''''' - -[[consoletopologydatafactory]] +[discrete] == `console.topology/data/factory` -=== Summary - Topology Data Model Factory Extension -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1532,17 +1112,11 @@ for function to determine if a resource is depicted by this model factory. |Getter for function to reconcile data model after all extensions' models have loaded. |=== -''''' - -[[consoletopologydecoratorprovider]] +[discrete] == `console.topology/decorator/provider` -=== Summary - Topology Decorator Provider Extension -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1552,17 +1126,10 @@ Topology Decorator Provider Extension |`decorator` |`CodeRef` |no | |=== -''''' - -[[consoletopologydetailsresource-alert]] +[discrete] == `console.topology/details/resource-alert` -=== Summary - -`DetailsResourceAlert` contributes an alert for specific topology context -or graph element. - -=== Properties +`DetailsResourceAlert` contributes an alert for specific topology context or graph element. [cols=",,,",options="header",] |=== @@ -1575,17 +1142,10 @@ alert should not be shown after dismissed. |no |Hook to return the contents of the alert. |=== -''''' - -[[consoletopologydetailsresource-link]] +[discrete] == `console.topology/details/resource-link` -=== Summary - -`DetailsResourceLink` contributes a link for specific topology context or -graph element. - -=== Properties +`DetailsResourceLink` contributes a link for specific topology context or graph element. [cols=",,,",options="header",] |=== @@ -1598,17 +1158,11 @@ graph element. chance to create the link. |=== -''''' - -[[consoletopologydetailstab]] +[discrete] == `console.topology/details/tab` -=== Summary - `DetailsTab` contributes a tab for the topology details panel. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1624,17 +1178,11 @@ item referenced here. For arrays, the first one found in order is used. The `insertBefore` value takes precedence. |=== -''''' - -[[consoletopologydetailstab-section]] +[discrete] == `console.topology/details/tab-section` -=== Summary - `DetailsTabSection` contributes a section for a specific tab in the topology details panel. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1660,17 +1208,11 @@ item referenced here.For arrays, the first one found in order is used. The `insertBefore` value takes precedence. |=== -''''' - -[[consoletopologydisplayfilters]] +[discrete] == `console.topology/display/filters` -=== Summary - Topology Display Filters Extension -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1678,17 +1220,11 @@ Topology Display Filters Extension |`applyDisplayOptions` |`CodeRef` |no | |=== -''''' - -[[consoletopologyrelationshipprovider]] +[discrete] == `console.topology/relationship/provider` -=== Summary - Topology relationship provider connector extension -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1698,17 +1234,9 @@ Topology relationship provider connector extension |`priority` |`number` |no | |=== -''''' - -[[consoleuser-preferencegroup]] +[discrete] == `console.user-preference/group` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1723,17 +1251,9 @@ this group should be placed this group should be placed |=== -''''' - -[[consoleuser-preferenceitem]] +[discrete] == `console.user-preference/item` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1757,17 +1277,11 @@ this item should be placed this item should be placed |=== -''''' - -[[consoleyaml-template]] +[discrete] == `console.yaml-template` -=== Summary - YAML templates for editing resources via the yaml editor. -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1779,17 +1293,9 @@ YAML templates for editing resources via the yaml editor. to mark this as the default template. |=== -''''' - -[[dev-consoleaddaction]] +[discrete] == `dev-console.add/action` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1810,17 +1316,9 @@ action would belong to. access review to control the visibility or enablement of the action. |=== -''''' - -[[dev-consoleaddaction-group]] +[discrete] == `dev-console.add/action-group` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1835,17 +1333,9 @@ group should be placed should be placed |=== -''''' - -[[dev-consoleimportenvironment]] +[discrete] == `dev-console.import/environment` -=== Summary - -(not available) - -=== Properties - [cols=",,,",options="header",] |=== |Name |Value Type |Optional |Description @@ -1857,17 +1347,10 @@ custom environment variables for |`environments` |`ImageEnvironment[]` |no |List of environment variables |=== -''''' - -[[consolepageresourcetab]] +[discrete] == `console.page/resource/tab` -=== Summary [DEPRECATED] - -Deprecated. Use `console.tab/horizontalNav` instead. Adds a new resource -tab page to Console router. - -=== Properties +Deprecated. Use `console.tab/horizontalNav` instead. Adds a new resource tab page to Console router. [cols=",,,",options="header",] |=== diff --git a/modules/dynamic-plug-ins-get-started.adoc b/modules/dynamic-plug-ins-get-started.adoc deleted file mode 100644 index 5104aa8d62..0000000000 --- a/modules/dynamic-plug-ins-get-started.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/dynamic-plug-ins.adoc - -:_content-type: PROCEDURE -[id="getting-started-with-dynamic-plugins_{context}"] -= Getting started with dynamic plug-ins - -To get started using the dynamic plug-in, you must set up your environment to write a new OpenShift Console dynamic plug-in. - -.Prerequisites -* Ensure you have link:https://nodejs.org/en/[`Node.js`] installed. -* Ensure you have link:https://yarnpkg.com/[`yarn`] installed. - -.Procedure - -. Edit the plug-in metadata in the `consolePlugin` declaration of `package.json`. -+ -[source,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 plug-in. -<2> Update the version. -<3> Update the display name for your plug-in. -<4> Update the description with a synopsis about your plug-in. diff --git a/modules/running-your-dynamic-plug-in.adoc b/modules/running-your-dynamic-plug-in.adoc deleted file mode 100644 index bcff9ae0c2..0000000000 --- a/modules/running-your-dynamic-plug-in.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/dynamic-plug-ins.adoc - -:_content-type: PROCEDURE -[id="running-your-dynamic-plugin_{context}"] -= Running your dynamic plug-in - -You can run the plug-in using a local development environment. The {product-title} web console runs in a container connected to the cluster you have logged into. - -.Prerequisites -* You must have the OpenShift CLI (`oc`) installed. -* You must have an OpenShift cluster running. -* You must have link:https://www.docker.com/[Docker] or at least v3.2.0 of link:https://podman.io/[Podman] installed. - -.Procedure - -. Build a plug-in and generate the output to the `dist` directory by running -+ -[source,terminal] ----- -$ yarn build ----- - -. Start an HTTP server by running -+ -[source,terminal] ----- -$ yarn http-server ----- - -. The HTTP server, which runs on port 9001, generates the following assets with `caching` disabled and `CORS` enabled. -+ -[source,terminal] ----- -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 ----- - -. Direct `bridge` to proxy requests to your local plug-in asset server by running -+ -[source,terminal] ----- -$ ./bin/bridge -plugins console-demo-plugin=http://localhost:9001/ ----- - -.Verification -* Visit link:http://localhost:9000/example[local host] to view the running plug-in. Inspect the value of `window.SERVER_FLAGS.consolePlugins` to see the list of plug-ins which load at runtime. diff --git a/modules/troubleshooting-dynamic-plug-in.adoc b/modules/troubleshooting-dynamic-plug-in.adoc new file mode 100644 index 0000000000..c43c3a290a --- /dev/null +++ b/modules/troubleshooting-dynamic-plug-in.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * web_console/dynamic-plug-ins-reference.adoc + +:_content-type: REFERENCE +[id="troubleshooting-dynamic-plug-in_{context}"] += Troubleshooting your dynamic plug-in + +Refer to this list of troubleshooting tips if you run into issues loading your plug-in. + +* Verify that you have enabled your plug-in in the console Operator configuration and your plug-in name is the output by running the following command: ++ +[source,terminal] +==== +$ oc get console.operator.openshift.io cluster -o jsonpath='{.spec.plugins}' +==== + +** Verify the enabled plug-ins on the status card of the *Overview* page in the *Administrator perspective*. You will need to refresh your browser if the plug-in was recently enabled. + +* Verify your plug-in service is healthy by: +** Verifying your plug-in pod status is running and your containers are ready. +** Verifying the service label selector matches the pod and the target port is correct. +** Curl the `plugin-manifest.json` from the service in a terminal on the console pod or another pod on the cluster. + +* Verify your `ConsolePlugin` resource name (`consolePlugin.name`) matches the plug-in name used in `package.json`. + +* Verify your service name, namespace, port, and path are declared correctly in the `ConsolePlugin` resource. + +* Verify your plug-in service uses HTTPS and service serving certificates. + +* Verify any certificates or connection errors in the console pod logs. + +* Verify the feature flag your plug-in relys on is not disabled. + +* Verify your plug-in does not have any `consolePlugin.dependencies` in `package.json` that are not met. +** This can include console version dependencies or dependencies on other plug-ins. Filter the JS console in your browser for your plug-in's name to see messages that are logged. + +* Verify there are no typos in the nav extension perspective or section IDs. +** Your plug-in may be loaded, but nav items missing if IDs are incorrect. Try navigating to a plug-in page directly by editing the URL. + +* Verify there are no network policies that are blocking traffic from the console pod to your plug-in service. +** If necessary, adjust network policies to allow console pods in the openshift-console namespace to make requests to your service. + +* Verify the list of dynamic plug-ins to be loaded in your browser in the *Console* tab of the developer tools browser. +** Evaluate `window.SERVER_FLAGS.consolePlugins` to see the dynamic plug-in on the Console frontend. \ No newline at end of file diff --git a/web_console/dynamic-plug-in/_attributes b/web_console/dynamic-plug-in/_attributes new file mode 120000 index 0000000000..f27fd275ea --- /dev/null +++ b/web_console/dynamic-plug-in/_attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/web_console/dynamic-plug-in/deploy-plug-in-cluster.adoc b/web_console/dynamic-plug-in/deploy-plug-in-cluster.adoc new file mode 100644 index 0000000000..cdb43c6963 --- /dev/null +++ b/web_console/dynamic-plug-in/deploy-plug-in-cluster.adoc @@ -0,0 +1,16 @@ +:_content-type: ASSEMBLY +[id="deploy-plug-in-cluster_{context}"] += Deploy your plug-in on a cluster +include::_attributes/common-attributes.adoc[] +:context: deploy-plug-in-cluster + +toc::[] + +You can deploy the plug-in to a {product-title} cluster. + +include::modules/build-image-docker.adoc[leveloffset=+1] + +include::modules/deployment-plug-in-cluster.adoc[leveloffset=+1] + +include::modules/disabling-plug-in-browser.adoc[leveloffset=+1] + diff --git a/web_console/dynamic-plug-in/dynamic-plug-in-example.adoc b/web_console/dynamic-plug-in/dynamic-plug-in-example.adoc new file mode 100644 index 0000000000..72b6a056f6 --- /dev/null +++ b/web_console/dynamic-plug-in/dynamic-plug-in-example.adoc @@ -0,0 +1,11 @@ +:_content-type: ASSEMBLY +[id="dynamic-plugin-example_{context}"] += Dynamic plug-in example +include::_attributes/common-attributes.adoc[] +:context: dynamic-plug-in-example + +toc::[] + +Before working through the example, verify that the plug-in is working by following the steps in xref:../../web_console/dynamic-plug-in/dynamic-plug-ins-get-started.adoc#dynamic-plugin-development_dynamic-plug-ins-get-started[Dynamic plug-in development] + +include::modules/adding-tab-pods-page.adoc[leveloffset=+1] diff --git a/modules/about-dynamic-plug-ins.adoc b/web_console/dynamic-plug-in/dynamic-plug-in.adoc similarity index 62% rename from modules/about-dynamic-plug-ins.adoc rename to web_console/dynamic-plug-in/dynamic-plug-in.adoc index 5c2ea9a71d..b9c303e304 100644 --- a/modules/about-dynamic-plug-ins.adoc +++ b/web_console/dynamic-plug-in/dynamic-plug-in.adoc @@ -1,10 +1,13 @@ -// Module is included in the following assemblies: -// -// * openshift-docs/web_console/dynamic-plug-ins.adoc +:_content-type: ASSEMBLY +[id="overview-of-dynamic-plug-ins_{context}"] += Overview of dynamic plug-ins +include::_attributes/common-attributes.adoc[] +:context: overview-of-dynamic-plug-ins -:_content-type: CONCEPT -[id="about-dynamic-plugins_{context}"] -= About dynamic plug-ins +toc::[] + +[id="dynamic-plug-in-overview"] +== About dynamic plug-ins A dynamic plug-in allows you to add custom pages and other extensions to your interface at runtime. The `ConsolePlugin` custom resource registers plug-ins with the console, and a cluster administrator enables plug-ins in the `console-operator` configuration. @@ -14,20 +17,15 @@ A dynamic plug-in allows you to add custom pages and other extensions to your in A dynamic plug-in allows you to make the following customizations to the {product-title} experience: * Add custom pages. -* Add perspectives and update navigation items. +* Add perspectives beyond administrator and developer. +* Add navigation items. * Add tabs and actions to resource pages. -== PatternFly 4 guidelines -When creating your plug-in, follow these guidelines for using PatternFly: - -* Use link:https://www.patternfly.org/v4/[PatternFly4] components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables will help your plug-in look consistent in future console versions. -* Make your plug-in accessible by following link:https://www.patternfly.org/v4/accessibility/accessibility-fundamentals/[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. - [id="general-plug-in-guidelines"] == General guidelines When creating your plug-in, follow these general guidelines: +* link:https://nodejs.org/en/[`Node.js`] and link:https://yarnpkg.com/[`yarn`] are required to build and run your plug-in. * Prefix your CSS class names with your plug-in 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 link:https://www.i18next.com/[react-i18next] localization guidelines when creating your plug-in. You can use the `useTranslation` hook like the one in the following example: @@ -40,4 +38,12 @@ conster Header: React.FC = () => { }; ---- -* _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 plug-in. Avoid selectors like element selectors that could affect markup outside of your plug-in’s components. +* Avoid selectors that could affect markup outside of your plug-ins components, such as element selectors. These are not APIs and are subject to change. Using them might break your plug-in. Avoid selectors like element selectors that could affect markup outside of your plug-ins components. + +[discrete] +== PatternFly 4 guidelines +When creating your plug-in, follow these guidelines for using PatternFly: + +* Use link:https://www.patternfly.org/v4/[PatternFly4] components and PatternFly CSS variables. Core PatternFly components are available through the SDK. Using PatternFly components and variables help your plug-in look consistent in future console versions. +* Make your plug-in accessible by following link:https://www.patternfly.org/v4/accessibility/accessibility-fundamentals/[PatternFly's accessibility fundamentals]. +* Avoid using other CSS libraries such as Bootstrap or Tailwind. They can conflict with PatternFly and will not match the console look and feel. \ No newline at end of file diff --git a/web_console/dynamic-plug-in/dynamic-plug-ins-get-started.adoc b/web_console/dynamic-plug-in/dynamic-plug-ins-get-started.adoc new file mode 100644 index 0000000000..ced6bd8125 --- /dev/null +++ b/web_console/dynamic-plug-in/dynamic-plug-ins-get-started.adoc @@ -0,0 +1,11 @@ +:_content-type: ASSEMBLY +[id="getting-started-with-dynamic-plugins_{context}"] += Getting started with dynamic plug-ins +include::_attributes/common-attributes.adoc[] +:context: dynamic-plug-ins-get-started + +toc::[] + +To get started using the dynamic plug-in, you must set up your environment to write a new {product-title} dynamic plug-in. For an example of how to write a new plug-in, see xref:../../web_console/dynamic-plug-in/dynamic-plug-in-example.html#adding-tab-to-pods-page_dynamic-plug-in-example[Adding a tab to the pods page]. + +include::modules/dynamic-plug-in-development.adoc[leveloffset=+1] diff --git a/web_console/dynamic-plug-in/dynamic-plug-ins-reference.adoc b/web_console/dynamic-plug-in/dynamic-plug-ins-reference.adoc new file mode 100644 index 0000000000..4fba9fe124 --- /dev/null +++ b/web_console/dynamic-plug-in/dynamic-plug-ins-reference.adoc @@ -0,0 +1,19 @@ +:_content-type: ASSEMBLY +[id="dynamic-plugins-reference_{context}"] += Dynamic plug-in reference +include::_attributes/common-attributes.adoc[] +:context: dynamic-plug-ins-reference + +toc::[] + +You can add extensions that allow you to customize your plug-in. Those extensions are then loaded to the console at run-time. + +include::modules/dynamic-plug-in-sdk-extensions.adoc[leveloffset=+1] + +include::modules/dynamic-plug-in-api.adoc[leveloffset=+1] + +include::modules/troubleshooting-dynamic-plug-in.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +xref:../../security/certificates/service-serving-certificate.adoc#understanding-service-serving_service-serving-certificate[Understanding service serving certificates] \ No newline at end of file diff --git a/web_console/dynamic-plug-in/images b/web_console/dynamic-plug-in/images new file mode 120000 index 0000000000..e4c5bd02a1 --- /dev/null +++ b/web_console/dynamic-plug-in/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/web_console/dynamic-plug-in/modules b/web_console/dynamic-plug-in/modules new file mode 120000 index 0000000000..43aab75b53 --- /dev/null +++ b/web_console/dynamic-plug-in/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/web_console/dynamic-plug-in/snippets b/web_console/dynamic-plug-in/snippets new file mode 120000 index 0000000000..9f5bc7e4dd --- /dev/null +++ b/web_console/dynamic-plug-in/snippets @@ -0,0 +1 @@ +../snippets \ No newline at end of file diff --git a/web_console/dynamic-plug-ins.adoc b/web_console/dynamic-plug-ins.adoc deleted file mode 100644 index b8bb2d11c4..0000000000 --- a/web_console/dynamic-plug-ins.adoc +++ /dev/null @@ -1,33 +0,0 @@ -:_content-type: ASSEMBLY -[id="adding-dynamic-plugin-to-console"] -= Adding a dynamic plug-in to the {product-title} web console -include::_attributes/common-attributes.adoc[] -:context: dynamic-plugins - -toc::[] - -You can create and deploy a dynamic plug-in on your cluster that is loaded at run-time. - -:FeatureName: Creating a dynamic plug-in -include::snippets/technology-preview.adoc[leveloffset=+1] -// - -include::modules/about-dynamic-plug-ins.adoc[leveloffset=+1] - -include::modules/enabling-plug-in-browser.adoc[leveloffset=+1] - -include::modules/dynamic-plug-ins-get-started.adoc[leveloffset=+1] - -include::modules/running-your-dynamic-plug-in.adoc[leveloffset=+1] - -include::modules/adding-new-extension-dynamic-plug-in.adoc[leveloffset=+1] - -include::modules/dynamic-plug-in-sdk-extensions.adoc[leveloffset=+2] - -include::modules/adding-tab-pods-page.adoc[leveloffset=+2] - -include::modules/build-image-docker.adoc[leveloffset=+1] - -include::modules/deployment-plug-in-cluster.adoc[leveloffset=+1] - -include::modules/disabling-plug-in-browser.adoc[leveloffset=+1]