Elastic Package Registry (EPR)

API

Endpoints:

• /: Info about the registry
• /health: Health of the service. Returns 200 if service is ready.
• /search: Search for packages. By default returns all the most recent packages available.
• /categories: List of the existing package categories and how many packages are in each category.
• /package/{name}/{version}: Info about a package
• /epr/{name}/{name}-{version}.zip: Download a package

/search

The /search API endpoint has few additional query parameters. More might be added in the future, but for now these are:

• kibana.version: Filters out all the packages which are not compatible with the given Kibana version. If it is set to 7.3.1 and a package requires 7.4, the package will not be returned or an older compatible package will be shown. By default this endpoint always returns only the newest compatible package.
• category: Filters the package by the given category. Available categories can be seen when going to /categories endpoint.
• package: Filters by a specific package name, for example mysql. Returns the most recent version.
• all: This can be set to true to list all package versions. This is set to false by default.
• type: Filters by a specific package type, for example input.
• capabilities: Filters the packages according to the given capabilities. This query parameter accepts a comma-separated list.
• spec.min and spec.max: Filters the packages by their format_version field given the version (major and minor numbers) set in the query parameter. It is not required to set both parameters. Examples:
  • ?spec.min=2.2&spec.max=3.3
  • ?spec.max=3.3
  • ?spec.min=3.0
• discovery: Returns the packages that define the discovery setting and fulfill the conditions in the query parameter. There are two different options:
  • Based on fields: Packages must include discovery fields in their manifest and all of fields must be included in the list included in the request
    • Example: Packages that contain both process.pid and host.os.name fields: ?discovery=fields:process.pid,host.os.name
  • Based on datasets: Packages must include discovery datasets in their manifest and at least one of the datasets must be included in the list included in the request:
    • Example: Packages that contain at least one of nginx.access or nginx.error datasets: ?discovery=datasets:nginx.access,nginx.error
• prerelease: This can be set to true to list prerelease versions of packages. Versions are considered prereleases if they are not stable according to semantic versioning, that is, if they are 0.x versions, or if they contain a prerelease tag. This is set to false by default.
• experimental (deprecated): This can be set to true to list packages considered to be experimental. This is set to false by default.

The different query parameters above can be combined, so ?package=mysql&kibana.version=7.3.0 will return all mysql package versions which are compatible with 7.3.0.

/categories

The /categories API endpoint has two additional query parameters.

• prerelease: This can be set to true to list prerelease versions of packages. Versions are considered prereleases if they are not stable according to semantic versioning, that is, if they are 0.x versions, or if they contain a prerelease tag. This is set to false by default.
• experimental (deprecated): This can be set to true to list categories from experimental packages. This is set to false by default.
• include_policy_templates: This can be set to true to include categories from policy templates. This is set to false by default.
• capabilities: List categories filtering the packages according to the given capabilities. This query parameter accepts a comma-separated list.
• spec.min and spec.max: List categories filtering the packages by their format_version field given the version (major and minor numbers) set in the query parameter. It is not required to set both parameters. Examples:
  • ?spec.min=2.2&spec.max=3.3
  • ?spec.max=3.3
  • ?spec.min=3.0
• discovery: List categories filtering the packages that define the discovery setting and fulfill the conditions in the query parameter. These query parameter follow the same syntax and behaviour to obtain the corresponding categories as in /search endpoint.

Package structure

The package structure has been formalized and described using package specification. If you need to modify the structure and corresponding implementation of the Package Registry, remember to adjust the spec first.

Architecture

There are 2 main parts to the package registry:

• Generation of package and content
• Serving content through a simple http endpoint

As much of the endpoints as possible is generated in advance. All package data is pregenerate and is statically served. The only exceptions here are the /categories and /search endpoint as they allow query parameters which leads to many variations and will also get more complex over time.

Directories

• testdata/package: Contains the packages for testing.

Running

There are several options to run this for development purposes.

Go command

We recommend using GVM, same as done in the CI. This tool allows you to install multiple versions of Go, setting the Go environment in consequence: eval "$(gvm 1.25.1)"

To use the correct golang version, run:

gvm use $(cat .go-version)

Afterwards the service can be started for development with:

go run .

Single binary

You can build the package-registry binary using mage:

mage build

Once built, the Package Registry can be run as ./package-registry. Find below more details about the available configuration options.

Docker

Deployment

The following active endpoints exist:

• prod, CDN: https://epr.elastic.co

Additionally, the following frozen endpoints exist and are no longer updated:

• staging, CDN: https://epr-staging.elastic.co
• snapshot, CDN: https://epr-snapshot.elastic.co/
• experimental, CDN: https://epr-experimental.elastic.co
• 7.9, CDN: https://epr-7-9.elastic.co

General

mage dockerBuild main
docker run --rm -it -p 8080:8080 docker.elastic.co/package-registry/package-registry:main

Testing service with local packages - Default configuration used in the image: config.docker.yml:

docker run --rm -it -p 8080:8080 \
  -v /path/to/local/packages:/packages/package-registry \
  docker.elastic.co/package-registry/package-registry:main

[!IMPORTANT] When you mount local package directories into the container (e.g., -v /path/to/packages:/packages/package-registry), ensure the mounted directory has proper filesystem permissions allowing UID 1000 to read the files. Alternatively, you can run the container as root using docker run --user 0 ... if you encounter permission issues.

By default, the registry requires all packages to have a .sig signature file. If your local packages are unsigned, disable this check by adding -e EPR_REQUIRE_PACKAGE_SIGNATURES=false to the docker run command.

Listening on HTTPS

docker run --rm -it -p 8443:8443 \
  -v /etc/ssl/package-registry.key:/etc/ssl/package-registry.key:ro \
  -v /etc/ssl/package-registry.crt:/etc/ssl/package-registry.crt:ro \
  -e EPR_ADDRESS=0.0.0.0:8443
  -e EPR_TLS_KEY=/etc/ssl/package-registry.key \
  -e EPR_TLS_CERT=/etc/ssl/package-registry.crt \
  docker.elastic.co/package-registry/package-registry:main

Docker images published

We publish a Docker image with each successful build commit on branches, tags, or PR. For each commit we have two docker image tags, one with the commit as tag

docker.elastic.co/package-registry/package-registry:f999b7a84d977cd19a379f0cec802aa1ef7ca379

Another Docker tag with the git branch or tag name

• docker.elastic.co/package-registry/package-registry:main
• docker.elastic.co/package-registry/package-registry:pr-111
• docker.elastic.co/package-registry/package-registry:v0.2.0

If you want to run the most recent registry for development, run the main tag.

These images contain only the package registry, they don't contain any package.

Testing with Kibana

The Docker image of Package Registry is just an empty distribution without any packages. You can test your own code with Kibana using elastic-package. For that, you need to build a new Package Registry docker image from your required branch:

1. Make sure you've built the Docker image for Package Registry (let's consider in this example main):

bash mage dockerBuild main

1. Build elastic-package changing the base image used for the Package Registry docker image (use main instead of v1.24.0):

   • Update the docker image (and docker tag) used for package-registry here.
     • Dockerfile used in elastic-package already enables the Proxy mode (more info at section).

   golang PackageRegistryBaseImage = "docker.elastic.co/package-registry/package-registry:main" - Build elastic-package (follow elastic-package instructions).

2. Now you're able to start the stack using Elastic Package (running Elasticsearch, Kibana, Agent and Fleet Server services) with your own Package Registry service: shell elastic-package stack up -v -d

Healthcheck

Availability of the service can be queried using the /health endpoint. As soon as /health returns a 200, the service is ready to handle requests.

Configuration

Package Registry needs to be configured with the source of packages. This configuration is loaded by default from the config.yml file. An example file is provided with the distribution.

Cache headers can also be configured in the configuration file. They are used to inform clients about the amount of time a resource is considered fresh. Check the reference configuration file for the available settings.

Additional runtime settings can be provided using flags, for more information about the available flags, use package-registry -help. Flags can be provided also as environment variables, in their uppercased form and prefixed by EPR_. For example, the following commands are equivalent:

EPR_DRY_RUN=true package-registry

package-registry -dry-run

Troubleshooting

Package Registry can generate debugging logs when started with the -log-level flag. For example

EPR_LOG_LEVEL=debug package-registry

package-registry -log-level debug

Or with Docker

docker run --rm -it -e "EPR_LOG_LEVEL=debug" <docker-image-identifier>

Performance monitoring

Package Registry is instrumented with the Elastic APM Go Agent. This Agent collects some system and runtime metrics, and detailed information about every request handled by the service. You can read more about the kind of information collected for requests in the APM Guide.

You can configure the agent to send the data to any APM Server using the following environment variables:

• ELASTIC_APM_SERVER_URL: Address of the APM Server. Instrumentation is disabled in Package Registry if this variable is not set.
• ELASTIC_APM_API_KEY: API key to use to authenticate with the APM Server, if needed.
• ELASTIC_APM_SECRET_TOKEN: If configured in the APM Server, this token has to be the same in the agents sending data.
• ELASTIC_APM_TRANSACTION_SAMPLE_RATE: Sample rate for transaction collection, it can be a value from 0.0 to 1.0. 1.0 is the default value, that collects all transactions.

You can find a full reference of these and other options in the Elastic APM Go Agent configuration guide.

Performance profiling

You can enable the HTTP profiler in Package Registry starting it with the -httpprof <address> flag. It will be listening in the given address.

You can read more about this profiler and the available endpoints in the pprof documentation.

Metrics

Package registry can be instrumented to expose Prometheus metrics under /metrics endpoint. By default this endpoint is disabled.

To enable this instrumentation, the required address (host and port) where this endpoint needs to run must be set using the parameter metrics-address (or the EPR_METRICS_ADDRESS environment variable). For example:

package-registry --metrics-address 0.0.0.0:9000

Proxy Mode

The Docker image of Package Registry is just an empty distribution without any packages. You can enable in Package Registry the proxy mode. This mode allows to take into account all the packages from other endpoint as part of the responses.

This mode is enabled with the parameter -feature-proxy-mode=true (or EPR_FEATURE_PROXY_MODE environment variable). And it will use by default as proxy endpoint https://epr.elastic.co. This endpoint can be customized using the parameter -proxy-to (or EPR_PROXY_TO). For example:

package-registry --feature-proxy-mode=true -proxy-to=https://epr.elastic.co

The -proxy-to endpoint must use HTTPS. To allow an