{"id":13546381,"url":"https://github.com/openshift/console-plugin-template","last_synced_at":"2025-03-29T19:01:39.623Z","repository":{"id":44657901,"uuid":"438008186","full_name":"openshift/console-plugin-template","owner":"openshift","description":"Minimal template for writing OpenShift console plugins","archived":false,"fork":false,"pushed_at":"2025-03-14T00:31:57.000Z","size":806,"stargazers_count":45,"open_issues_count":5,"forks_count":62,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-21T23:38:05.908Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openshift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-13T20:00:55.000Z","updated_at":"2025-03-14T00:04:59.000Z","dependencies_parsed_at":"2024-01-16T17:51:34.953Z","dependency_job_id":"474bce23-9cc9-418c-bc81-721f23726972","html_url":"https://github.com/openshift/console-plugin-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fconsole-plugin-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fconsole-plugin-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fconsole-plugin-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fconsole-plugin-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openshift","download_url":"https://codeload.github.com/openshift/console-plugin-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246230518,"owners_count":20744347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:00:36.152Z","updated_at":"2025-03-29T19:01:39.600Z","avatar_url":"https://github.com/openshift.png","language":"TypeScript","readme":"# OpenShift Console Plugin Template\n\nThis project is a minimal template for writing a new OpenShift Console dynamic\nplugin.\n\n[Dynamic plugins](https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk)\nallow you to extend the\n[OpenShift UI](https://github.com/openshift/console)\nat runtime, adding custom pages and other extensions. They are based on\n[webpack module federation](https://webpack.js.org/concepts/module-federation/).\nPlugins are registered with console using the `ConsolePlugin` custom resource\nand enabled in the console operator config by a cluster administrator.\n\nUsing the latest `v1` API version of `ConsolePlugin` CRD, requires OpenShift 4.12\nand higher. For using old `v1alpha1` API version us OpenShift version 4.10 or 4.11.\n\nFor an example of a plugin that works with OpenShift 4.11, see the `release-4.11` branch.\nFor a plugin that works with OpenShift 4.10, see the `release-4.10` branch.\n\n[Node.js](https://nodejs.org/en/) and [yarn](https://yarnpkg.com) are required\nto build and run the example. To run OpenShift console in a container, either\n[Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io) and\n[oc](https://console.redhat.com/openshift/downloads) are required.\n\n## Getting started\n\n\u003e [!IMPORTANT]  \n\u003e To use this template, **DO NOT FORK THIS REPOSITORY**! Click **Use this template**, then select\n\u003e [**Create a new repository**](https://github.com/new?template_name=networking-console-plugin\u0026template_owner=openshift)\n\u003e to create a new repository.\n\u003e\n\u003e ![A screenshot showing where the \"Use this template\" button is located](https://i.imgur.com/AhaySbU.png)\n\u003e\n\u003e **Forking this repository** for purposes outside of contributing to this repository\n\u003e **will cause issues**, as users cannot have more than one fork of a template repository\n\u003e at a time. This could prevent future users from forking and contributing to your plugin.\n\u003e \n\u003e Your fork would also behave like a template repository, which might be confusing for\n\u003e contributiors, because it is not possible for repositories generated from a template\n\u003e repository to contribute back to the template.\n\nAfter cloning your instantiated repository, you must update the plugin metadata, such as the\nplugin name in the `consolePlugin` declaration of [package.json](package.json).\n\n```json\n\"consolePlugin\": {\n  \"name\": \"console-plugin-template\",\n  \"version\": \"0.0.1\",\n  \"displayName\": \"My Plugin\",\n  \"description\": \"Enjoy this shiny, new console plugin!\",\n  \"exposedModules\": {\n    \"ExamplePage\": \"./components/ExamplePage\"\n  },\n  \"dependencies\": {\n    \"@console/pluginAPI\": \"*\"\n  }\n}\n```\n\nThe template adds a single example page in the Home navigation section. The\nextension is declared in the [console-extensions.json](console-extensions.json)\nfile and the React component is declared in\n[src/components/ExamplePage.tsx](src/components/ExamplePage.tsx).\n\nYou can run the plugin using a local development environment or build an image\nto deploy it to a cluster.\n\n## Development\n\n### Option 1: Local\n\nIn one terminal window, run:\n\n1. `yarn install`\n2. `yarn run start`\n\nIn another terminal window, run:\n\n1. `oc login` (requires [oc](https://console.redhat.com/openshift/downloads) and an [OpenShift cluster](https://console.redhat.com/openshift/create))\n2. `yarn run start-console` (requires [Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io))\n\nThis will run the OpenShift console in a container connected to the cluster\nyou've logged into. The plugin HTTP server runs on port 9001 with CORS enabled.\nNavigate to \u003chttp://localhost:9000/example\u003e to see the running plugin.\n\n#### Running start-console with Apple silicon and podman\n\nIf you are using podman on a Mac with Apple silicon, `yarn run start-console`\nmight fail since it runs an amd64 image. You can workaround the problem with\n[qemu-user-static](https://github.com/multiarch/qemu-user-static) by running\nthese commands:\n\n```bash\npodman machine ssh\nsudo -i\nrpm-ostree install qemu-user-static\nsystemctl reboot\n```\n\n### Option 2: Docker + VSCode Remote Container\n\nMake sure the\n[Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\nextension is installed. This method uses Docker Compose where one container is\nthe OpenShift console and the second container is the plugin. It requires that\nyou have access to an existing OpenShift cluster. After the initial build, the\ncached containers will help you start developing in seconds.\n\n1. Create a `dev.env` file inside the `.devcontainer` folder with the correct values for your cluster:\n\n```bash\nOC_PLUGIN_NAME=console-plugin-template\nOC_URL=https://api.example.com:6443\nOC_USER=kubeadmin\nOC_PASS=\u003cpassword\u003e\n```\n\n2. `(Ctrl+Shift+P) =\u003e Remote Containers: Open Folder in Container...`\n3. `yarn run start`\n4. Navigate to \u003chttp://localhost:9000/example\u003e\n\n## Docker image\n\nBefore you can deploy your plugin on a cluster, you must build an image and\npush it to an image registry.\n\n1. Build the image:\n\n   ```sh\n   docker build -t quay.io/my-repository/my-plugin:latest .\n   ```\n\n2. Run the image:\n\n   ```sh\n   docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest\n   ```\n\n3. Push the image:\n\n   ```sh\n   docker push quay.io/my-repository/my-plugin:latest\n   ```\n\nNOTE: If you have a Mac with Apple silicon, you will need to add the flag\n`--platform=linux/amd64` when building the image to target the correct platform\nto run in-cluster.\n\n## Deployment on cluster\n\nA [Helm](https://helm.sh) chart is available to deploy the plugin to an OpenShift environment.\n\nThe following Helm parameters are required:\n\n`plugin.image`: The location of the image containing the plugin that was previously pushed\n\nAdditional parameters can be specified if desired. Consult the chart [values](charts/openshift-console-plugin/values.yaml) file for the full set of supported parameters.\n\n### Installing the Helm Chart\n\nInstall the chart using the name of the plugin as the Helm release name into a new namespace or an existing namespace as specified by the `plugin_console-plugin-template` parameter and providing the location of the image within the `plugin.image` parameter by using the following command:\n\n```shell\nhelm upgrade -i  my-plugin charts/openshift-console-plugin -n my-namespace --create-namespace --set plugin.image=my-plugin-image-location\n```\n\nNOTE: When deploying on OpenShift 4.10, it is recommended to add the parameter `--set plugin.securityContext.enabled=false` which will omit configurations related to Pod Security.\n\nNOTE: When defining i18n namespace, adhere `plugin__\u003cname-of-the-plugin\u003e` format. The name of the plugin should be extracted from the `consolePlugin` declaration within the [package.json](package.json) file.\n\n## i18n\n\nThe plugin template demonstrates how you can translate messages in with [react-i18next](https://react.i18next.com/). The i18n namespace must match\nthe name of the `ConsolePlugin` resource with the `plugin__` prefix to avoid\nnaming conflicts. For example, the plugin template uses the\n`plugin__console-plugin-template` namespace. You can use the `useTranslation` hook\nwith this namespace as follows:\n\n```tsx\nconster Header: React.FC = () =\u003e {\n  const { t } = useTranslation('plugin__console-plugin-template');\n  return \u003ch1\u003e{t('Hello, World!')}\u003c/h1\u003e;\n};\n```\n\nFor labels in `console-extensions.json`, you can use the format\n`%plugin__console-plugin-template~My Label%`. Console will replace the value with\nthe message for the current language from the `plugin__console-plugin-template`\nnamespace. For example:\n\n```json\n  {\n    \"type\": \"console.navigation/section\",\n    \"properties\": {\n      \"id\": \"admin-demo-section\",\n      \"perspective\": \"admin\",\n      \"name\": \"%plugin__console-plugin-template~Plugin Template%\"\n    }\n  }\n```\n\nRunning `yarn i18n` updates the JSON files in the `locales` folder of the\nplugin template when adding or changing messages.\n\n## Linting\n\nThis project adds prettier, eslint, and stylelint. Linting can be run with\n`yarn run lint`.\n\nThe stylelint config disallows hex colors since these cause problems with dark\nmode (starting in OpenShift console 4.11). You should use the\n[PatternFly global CSS variables](https://patternfly-react-main.surge.sh/developer-resources/global-css-variables#global-css-variables)\nfor colors instead.\n\nThe stylelint config also disallows naked element selectors like `table` and\n`.pf-` or `.co-` prefixed classes. This prevents plugins from accidentally\noverwriting default console styles, breaking the layout of existing pages. The\nbest practice is to prefix your CSS classnames with your plugin name to avoid\nconflicts. Please don't disable these rules without understanding how they can\nbreak console styles!\n\n## Reporting\n\nSteps to generate reports\n\n1. In command prompt, navigate to root folder and execute the command `yarn run cypress-merge`\n2. Then execute command `yarn run cypress-generate`\nThe cypress-report.html file is generated and should be in (/integration-tests/screenshots) directory\n\n## References\n\n- [Console Plugin SDK README](https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk)\n- [Customization Plugin Example](https://github.com/spadgett/console-customization-plugin)\n- [Dynamic Plugin Enhancement Proposal](https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md)\n","funding_links":[],"categories":["Awesome OpenShift Console Plugins"],"sub_categories":["What are Dynamic Plugins?"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift%2Fconsole-plugin-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenshift%2Fconsole-plugin-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift%2Fconsole-plugin-template/lists"}