Skip to content

Headlamp Plugin Development#

This document describes how we develop Headlamp plugins. While you don't have to use Visual Studio Code, it is the recommended way due to the many useful plugins to help you write code with correct linting and syntax.

Prerequisites#

  1. Install Visual Studio Code
  2. Install the Headlamp Desktop app

Install Visual Studio Code Extensions#

  • ESLint
  • JavaScript (ES6) code snippets
  • Node.js Modules Intellisense
  • npm Intellisense
  • Path Intellisense
  • Prettier - Code Formatter
  • Search node_modules

Set up a Headlamp plugin project#

  1. Initialize project with 
    npx --yes @kinvolk/headlamp-plugin create <Name of plugin>
  2. Add .gitignore file 
    # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.

# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# production
/build
/dist

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

# The output for npm run storybook-book, static html built storybook for the plugin
storybook-static
  3. Add CI pipeline .gitlab-ci.yml 
    include:
  project: it-common-platform/tenant-support/ci-templates
  file: pipelines/headlamp-build.yml
  4. Edit the description of your plugin in package.json.
  5. Create a blank GitLab project under headlamp-plugins without initializing a repository with a README. Most plugins will be public.
  6. Run commands to initialize git for your local directory and push it to the new project (instructions are on the GitLab page after creating the blank project).
  7. Enable CI/CD under Settings -> General -> Visibility, project features, permimssions.
  8. Enable the it-common-platform-runner Kubernetes runner for the project under Settings -> CI/CD -> Runners.
  9. Protect the main branch under Settings -> Repository -> Protected branches with no one able to merge to main.

Develop#

Continuing work on an existing project

If you are not creating a new project, but continuing an existing one, you will likely need to run npm install in order to populate all the necessary dependencies to continue the steps below.

  1. Run npm run start in the root directory of your plugin.
  2. Open Headlamp from a local install.
  3. Every time you make a change and save in Visual Studio Code, Headlamp should refresh automatically with the changes.

Deploy#

When you are ready to add your plugin to a dvlp instance of Headlamp, add to the list under the plugins.cfg configmap. The first field is the plugin name, second is the project number, and third is the version in package.json.

Headlamp tenant in on-prem DVLP

Resources#