Creating a plugin

Cortex launched plugins to give users even more customization power. With plugins, users can bring in data from any source, expose custom metrics, customize the Cortex UI to match other internal tools, and more.

You’ll notice a new tab in Cortex for Plugins:

But to create a plugin of our own, we’re going to start with the Scaffolder. A Cortex Plugin Template has been made automatically available in your workspace — click here to set up a new plugin from scratch.

You’ll be prompted to enter some metadata about your plugin repository. Through the Scaffolder, Cortex will automatically set up a React + TypeScript repository for you with the basic setup for your plugin to make it easy to get started. Once you’ve finished filling out the template form, press Create service to finish setting up the repository.

Note: for simplicity, we’ll be using yarn for operating commands and dependencies within our plugin repository, but npm also works – if you desire, substitute commands as appropriate.

Clone the repository locally and install dependencies via yarn, then run yarn build to generate a single HTML file representing your plugin (output at ./dist/ui.html). If you want to make any changes to the plugin, modify the code before running (or re-running) the build command.

In Cortex, navigate to Plugins and press Register plugin. Once you’ve filled out some basic display information about the plugin (e.g. name and description), you can start deciding where the plugin gets executed inside of Cortex. In the Plugin context field of the add/edit plugin workflow, you have a number of choices about where the plugin displays.

Above is an example of a plugin configured to show up both in the global context (via the “Include in global context” toggle) as well as for all services. If desired, you may apply standard entity filtering to determine which entities of a given type the plugin should show up for (e.g. “only resources with type `s3-bucket`”).

Plugins set to appear globally will show up under the All tab on the Plugins page. To see your plugin in an entity context, select Plugins from the menu on the left. You can customize exactly where your plugins appear on entity pages, as well.

Upload the ui.html file (from the `yarn build` command) to see a preview of the plugin. If your plugin is configured to run in multiple contexts, you can use the dropdown on the left to preview how it might appear in those contexts. This is a good place to iterate on any changes you might want to make using the preview. When you’re satisfied with the output, press Save plugin to complete registration.

Let’s take a look at a sample plugin executing successfully:

In this example, the plugin displays the execution context, so you can easily see where it’s running, as well as a form that can retrieve license information about a GitHub repository. As our plugin can be configured to use a proxy (setup to be detailed later), this plugin could have access to inspect private repositories. As you can see in the Context section, our plugin is being executed in the global context.

Customizing where plugins appear

Admins will have the option in settings under Appearance to adjust plugin display. Under Header plugins, you can make any plugins with a global context directly accessible in the main header. 

Through Dev homepage plugins, you can make sure any plugins with global context display on the Developer Homepage.

And, under Entity overview tabs and Entity side nav, you can configure entity plugins to display on the entity’s page, or on the side navigation menu. 

Proxies

On the Plugins page, you’ll see a tab for proxies. In our earlier example, our plugin fetched licensing information from a private repository. It’s able to do that because we configured this plugin to use a proxy that adds an authentication token to requests to GitHub.

To use this feature with sensitive information (such as an access token), first set up a secret in Settings. In our example, we have a personal access token in our Secrets, as well as a GitHub proxy that’s associated with the plugin (via plugin configuration). Our proxy is configured so that any requests through the proxy to `https://api.github.com**` have an appended header — in this case, it’ll append the auth header seen above, which inserts the access token, thus enabling data to display.

Make sure to take a look at our docs on plugins for a deeper look at creating plugins, including a sample plugin proxy configuration and sample plugin code.