Creating a 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 Integrations ‣ Change 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:

shell
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 log shipper like FileBeat or use the Humio CLI and just upload a file:

shell
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 Settings ‣ Packages ‣ Create 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. While you could create these files by hand, the easiest way to get started with a package is by using the Package Export Wizard.

On the export page, you’ll be asked to select the assets that you’ld like to include in your package. It will fill in some metadata about your package, such as name and description. This metadata will go into the README.md and manifest.yaml files, which will be located in the root folder of your package.

Once you have exported your package, you should unzip the file and add it to source control, so that the manifest.yaml file is at the root of the code repository. That way you can manage changes over time and collaborate with others. Alternatively, you can upload your package to a shared location like Amazon S3 and have others install from there.

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:

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

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

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

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

shell
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 User Interface

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

To install a package through the UI go to Settings ‣ Packages ‣ Installed ‣ Upload 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, read the package file formats documentation page.

Note

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

If you want to publish a package and make it available to everyone - we would love to hear from you or your company. You can contact support@humio.com for more details.

It can be a list of parsers or full set of dashboards for a specific technology, or anything really.