Creating a Humio Package

A package is a bundle of assets that can be installed in a Humio repository. They allow you to make assets reusable across multiple teams, repositories and even share your work with the Humio community. This documentation page explains how to create, install and maintain custom Humio packages.

Make sure you have IntegrationsChange Packages permission for the repository in which you’re creating a package. Otherwise, you may encounter errors due to permissions. For testing the examples here, you might use your personal Sandbox repository since there you’ll have the required permissions to manage packages. You can read more about permissions under Role Based Authorization

Preparation

The examples on this documentation page use the Humio Command-Line Interface (CLI) to perform some tasks related to authoring a package. These tasks can also be performed using the Humio User Interface, though. Still, you may want to be sure to install Humio’s CLI, if you haven’t already. See the CLI Documentation.

You can validate that humioctl is set up correctly by executing the following from the command-line:

humioctl status

It shouldn’t return an error.

Creating Package Assets

You would create the dashboards, parsers, saved queries, etc. as you would normally. There’s nothing special about them just because they’re intended to be part of a package. You may already have some of these items that you want to add to your package.

When working on your package, it can be useful to upload sample data from a file to test, maybe with a parser. You can either setup a data shipper like FileBeat or use the Humio CLI and just upload a file:

humioctl ingest <REPO> --tail <FILENAME> --parser <PARSER_NAME>

You would replace <REPO> with the name of your repository, <FILENAME> with the name of the file to upload, and <PARSER_NAME> with the name of the parser to use.

Exporting the Package

Once you have your assets ready, you can export them as a package using the Package Export Wizard. You can find it in the User Interface under SettingsPackagesCreate Custom Package.

A package is essentially a zip file with a several YAML files describing the dashboards, alerts, and other components, as well as some metadata files. The metadata goes into the README.md and manifest.yaml files, located at the root level of the package, while each type of asset gets a folder containing all assets of that type in the package.

Once you’ve exported your package, it’s prudent to unzip the file and add it to source control. The manifest.yaml file will then be at the root of the code repository. This allows you to manage changes easily and to collaborate with others.

The Developer’s Guidelines for Packages provide useful advice on standards to adopt when creating a package. These standards will help you to simplify the process of getting your packages added to the Humio marketplace, should you wish to do this. Even if you’re not considering submitting your package to the marketplace, the guidelines contain some helpful advice that you may wish to adopt when creating packages.

Installing a Package

Installing a Package is fairly easy. To make it easier, Humoi provides three tools or methods in which you may use to install a package:

  • Humio Command-Line Interface (CLI);
  • Humio User Interface; or
  • Humio MarketPlace.

The choice depends typically on your situation or needs. For instance, if you’re using a custom package to manage your Humio repository’s dashboards, the CLI is the best choice. Installing packages this way will override any manual modification made in the UI. This is equivalent to a force push in git terminology. Any changes must be exported and placed in source control.

If you decide to use the User Interface, you will be able to merge local changes with changes made in the new version of the package.

Using humioctl

Let’s install the package we just exported and unzipped:

humioctl packages install /path/to/my/packages/root/

Alternatively, if you’re maintaining your package on Github you can install from the Github URL,

humioctl packages install https://github.com/myorg/my-package/

Or you can point directly to the zip file you just created:

humioctl packages install /path/to/my/package.zip

There are a few more options that you can read about using humioctl packages install --help.

Using Humio’s UI

Alternatively, you can install your package in the UI using the Zip file upload.

To install a package through the UI go to: SettingsPackagesInstalledUpload and select your Zip file.

If a previous version of the package is already installed this will guide you through a merge process, where you are given the option to keep any modification, made. At the moment this an “all or nothing” merge where either you keep the local changes or use the new modifications coming from the package.

Maintaining a Package

You should maintain your package as a Git repository. That allows you to collaborate on changes to dashboards, parsers, etc.

You can either edit YAML files by hand, or make changes in Humio’s UI and “Export as Template” on the individual asset. There is no need to go through the “Export Package” flow again.

If you want to make changes to the YAML manually, there is a documentation section about package file formats.

Humio does not allow overwriting existing versions of a package. So remember to bump your package version number when you update the content of your package. You do this either in the manifest.yaml file or be going through the export wizard again.

Publishing a Package in Humio Marketplace

The Humio marketplace contains a set of pre-built packages created by Humio staff, customers and partners. We encourage you to join this community of package creators and publish your package via our marketplace, making it available to everyone. Your package could be a list of parsers or a full set of dashboards for a specific technology, or anything really.

The [Developer’s Guidelines for Packages]({{ page-url “developers-guidelines-for-packages.md” }}) explains the standards we would like everyone to use for marketplace packages. It will guide you through the process. Let us know if you need further assistance by emailing us via packages@humio.com or through our public Slack channel: https://community.humio.com/