Skip to content

Commit 7dd13ea

Browse files
opayne1opayne1
committed
[WIP] OSDOCS:2475 Adds new assembly for the dynamic plugin TP
1 parent 719acbd commit 7dd13ea

9 files changed

+299
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -570,6 +570,9 @@ Topics:
570570
- Name: Customizing the web console
571571
File: customizing-the-web-console
572572
Distros: openshift-enterprise,openshift-origin
573+
- Name: Dynamic plug-ins
574+
File: dynamic-plug-ins
575+
Distros: openshift-enterprise,openshift-origin
573576
- Name: Developer perspective
574577
File: odc-about-developer-perspective
575578
- Name: Web terminal

‎modules/about-dynamic-plug-ins.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * openshift-docs/web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="about-dynamic-plugins_{context}"]
7+
= About dynamic plug-ins
8+
9+
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.
10+
11+
[id="dynamic-plugins-features"]
12+
== Key features
13+
14+
A dynamic plug-in allows you to make the following customizations to the {product-title} experience:
15+
16+
* Add custom pages.
17+
* Add perspectives and update navigation items.
18+
* Add tabs and actions to resource pages.
19+
20+
== PatternFly 4 guidelines
21+
When creating your plug-in, follow these guidelines for using PatternFly:
22+
23+
* 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.
24+
* Make your plug-in accessible by following link:https://www.patternfly.org/v4/accessibility/accessibility-fundamentals/[PatternFly's accessibility fundamentals].
25+
* _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.
26+
27+
[id="general-plug-in-guidelines"]
28+
== General guidelines
29+
When creating your plug-in, follow these general guidelines:
30+
31+
* Prefix your CSS class names with your plug-in name to avoid collisions. For example, `my-plugin_\_heading` and `my-plugin_\_icon`.
32+
* Maintain a consistent look, feel, and behavior with other console pages.
33+
* Use link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md#localization[react-i18next] for localization.
34+
* _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.

‎modules/adding-new-extension-dynamic-plug-in.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="adding-new-extension-dynamic-plugin_{context}"]
7+
= Adding a new extension to your plug-in
8+
You can add extensions to your plug-in that are loaded at runtime.

‎modules/adding-tab-pods-page.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="adding-tab-to-pods-page_{context}"]
7+
= Adding a tab to the pods page
8+
The following procedure adds a tab to the *Pod Details* page as an example extension to your plug-in.
9+
10+
.Procedure
11+
12+
. Add the following to the `console-extensions.json` file:
13+
+
14+
[source,json]
15+
16+
----
17+
{
18+
"type": "console.page/resource/tab",
19+
"properties": {
20+
"name": "Example Tab",
21+
"href": "example",
22+
"model": {
23+
"group": "core",
24+
"version": "v1",
25+
"kind": "Pod"
26+
},
27+
"component": { "$codeRef": "ExampleTab" }
28+
}
29+
----
30+
31+
. Edit the `package.json` file to include the following changes:
32+
+
33+
[source,json]
34+
35+
----
36+
"exposedModules": {
37+
"ExamplePage": "./components/ExamplePage",
38+
"ExampleTab": "./components/ExampleTab"
39+
}
40+
----
41+
42+
. Write a message to display on a new custom tab on the *Pods* page by creating a new file `src/components/ExampleTab.tsx` and adding the following script:
43+
+
44+
[source,tsx]
45+
46+
----
47+
import * as React from 'react';
48+
49+
export default function ExampleTab() {
50+
return (
51+
<p>This is a custom tab added to a resource using a dynamic plug-in.</p>
52+
);
53+
}
54+
----
55+
56+
.Verification
57+
* Visit a *Pod* page to view the added tab.

‎modules/build-image-docker.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="build-image-with-docker_{context}"]
7+
= Build an image with Docker
8+
9+
To deploy your plug-in on a cluster, you need to build an image and push it to an image registry.
10+
11+
.Procedure
12+
13+
. Build the image with the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ docker build -t quay.io/my-repositroy/my-plugin:latest .
18+
----
19+
20+
. Optional: If you want to test your image, run the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest
25+
----
26+
27+
. Push the image by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ docker push quay.io/my-repository/my-plugin:latest
32+
----

‎modules/deployment-plug-in-cluster.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="deploy-on-cluster_{context}"]
7+
= Deploy your plug-in on a cluster
8+
9+
After pushing an image with your changes to a registry, you can deploy the plug-in to a cluster.
10+
11+
.Procedure
12+
13+
. To deploy your plug-in to a cluster, instantiate the link:https://github.com/spadgett/console-plugin-template/blob/main/template.yaml[template] by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc process -f template.yaml \
18+
-p PLUGIN_NAME=my-plugin \ <1>
19+
-p NAMESPACE=my-plugin-namespace \ <2>
20+
-p IMAGE=quay.io/my-repository/my-plugin:latest \ <3>
21+
| oc create -f -
22+
----
23+
<1> Update with the name of your plug-in.
24+
<2> Update with the namespace.
25+
<3> Update with the name of the image you created.
26+
+
27+
This command runs a light-weight NGINX HTTP server to serve the assets for your plug-in.
28+
29+
IMPORTANT: `PLUGIN_NAME` must match the plug-in name you used in the `consolePlugin` declaration of `package.json`.
30+
31+
[start=2]
32+
. Patch the *Console Operator* configuration to enable the plug-in by running the following command:
33+
+
34+
[source,terminal]
35+
36+
----
37+
$ oc patch consoles.operator.openshift.io cluster --patch '{ "spec": { "plugins": ["my-plugin"] } }' --type=merge
38+
----

‎modules/dynamic-plug-ins-get-started.adoc‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="getting-started-with-dynamic-plugins_{context}"]
7+
= Getting started with dynamic plug-ins
8+
9+
To get started using the dynamic plug-in, you must set up your environment to write a new OpenShift Console dynamic plug-in.
10+
11+
.Prerequisites
12+
* Ensure you have link:https://nodejs.org/en/[`Node.js`] installed.
13+
* Ensure you have link:https://yarnpkg.com/[`yarn`] installed.
14+
15+
.Procedure
16+
17+
. Visit this link:https://github.com/spadgett/console-plugin-template[repository] containing a template for creating plug-ins.
18+
19+
. Select `Use this Template` from the *<> Code* tab to create a GitHub repository.
20+
21+
. Re-name the template with the name of your plug-in.
22+
23+
. From your copied repository, clone it your local machine so you can edit the code.
24+
25+
. Edit the plug-in metadata in the `consolePlugin` declaration of `package.json`.
26+
+
27+
[source,json]
28+
29+
----
30+
"consolePlugin": {
31+
"name": "my-plugin", <1>
32+
"version": "0.0.1", <2>
33+
"displayName": "My Plugin", <3>
34+
"description": "Enjoy this shiny, new console plugin!", <4>
35+
"exposedModules": {
36+
"ExamplePage": "./components/ExamplePage"
37+
},
38+
"dependencies": {
39+
"@console/pluginAPI": "*"
40+
}
41+
}
42+
----
43+
<1> Update the name of your plug-in.
44+
<2> Update the version.
45+
<3> Update the display name for your plug-in.
46+
<4> Update the description with a synopsis about your plug-in.

‎modules/running-your-dynamic-plug-in.adoc‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * web_console/dynamic-plug-ins.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="running-your-dynamic-plugin_{context}"]
7+
= Running your dynamic plug-in
8+
9+
You can run the plug-in using a local development environment. The OpenShift console runs in a container connected to the cluster you have logged into.
10+
11+
.Prerequisites
12+
* You must have the OpenShift CLI (`oc`) installed.
13+
* You must have an OpenShift cluster running.
14+
* You must have link:https://www.docker.com/[Docker] or at least v3.2.0 of link:https://podman.io/[Podman] installed.
15+
16+
.Procedure
17+
18+
* Open two terminal windows in the local directory of your cloned repository.
19+
+
20+
21+
a. Run the following commands in the first terminal:
22+
+
23+
[source,terminal]
24+
----
25+
$ yarn install
26+
----
27+
+
28+
[source,terminal]
29+
----
30+
$ yarn run start
31+
----
32+
33+
b. Run the following commands in the second terminal window:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc login
38+
----
39+
+
40+
[source,terminal]
41+
----
42+
$ yarn run start-console
43+
----
44+
45+
.Verification
46+
* Visit link:http://localhost:9000/example[local host] to view the running plug-in.

‎web_console/dynamic-plug-ins.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
:_content-type: ASSEMBLY
2+
[id="adding-dynamic-plugin-to-console"]
3+
= Adding a dynamic plug-in to the {product-title} web console
4+
include::modules/common-attributes.adoc[]
5+
:context: dynamic-plugins
6+
7+
toc::[]
8+
9+
You can create and deploy a dynamic plug-in on your cluster that is loaded at run-time.
10+
11+
:FeatureName: Creating a dynamic plug-in
12+
include::snippets/technology-preview.adoc[leveloffset=+1]
13+
//
14+
15+
include::modules/about-dynamic-plug-ins.adoc[leveloffset=+1]
16+
17+
include::modules/dynamic-plug-ins-get-started.adoc[leveloffset=+1]
18+
19+
include::modules/running-your-dynamic-plug-in.adoc[leveloffset=+1]
20+
21+
include::modules/adding-tab-pods-page.adoc[leveloffset=+2]
22+
23+
include::modules/adding-new-extension-dynamic-plug-in.adoc[leveloffset=+1]
24+
25+
include::modules/build-image-docker.adoc[leveloffset=+1]
26+
27+
include::modules/deployment-plug-in-cluster.adoc[leveloffset=+1]
28+
29+
[role="_additional-resources"]
30+
[id="dynamic-plugin-additional-resources"]
31+
== Additional resources
32+
33+
* link:https://github.com/spadgett/console-customization-plugin[Console customization plug-in].
34+
* link:https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk#openshift-console-dynamic-plugins[Console plug-in SDK README]
35+
* link:https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md[Dynamic plug-in enhancement proposal]

0 commit comments

Comments
 (0)