IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elastic Docs ›Fleet and Elastic Agent Guide [8.1] ›Manage Elastic Agent integrations
« Uninstall an Elastic Agent integration Install Elastic Agents »

Air-gapped environmentsedit

There are certain environments in which network traffic restrictions are mandatory. In these environments, the Kibana instance isn’t able to reach the public Elastic Package Registry endpoints, like epr.elastic.co, to download package metadata and content.

There are two workarounds in this situation — use a proxy server as network gateway to reach the public endpoints, or deploy your own instance of the Elastic Package Registry.

Use a proxy serveredit

If you can route traffic to the public endpoint of the Elastic Package Registry through a network gateway, there is a property in Kibana that can orchestrate to use a proxy server:

xpack.fleet.registryProxyUrl: your-nat-gateway.corp.net

Host your own Elastic Package Registryedit

If routing traffic through a proxy server is not an option, you can host your own Elastic Package Registry.

The Elastic Package Registry can be deployed and hosted on-site using one of the available Docker images. These docker images include the Elastic Package Registry and a selection of packages.

There are different distributions available:

  • 8.1.3 (recommended): docker.elastic.co/package-registry/distribution:8.1.3 - Selection of packages from the production repository released with the 8.1.3 version of the Elastic Stack.
  • production: docker.elastic.co/package-registry/distribution:production - Packages available in the production registry (https://epr.elastic.co).
  • staging: docker.elastic.co/package-registry/distribution:staging - Packages available in the staging registry (https://epr-staging.elastic.co). These packages may be pending of validation.
  • snapshot: docker.elastic.co/package-registry/distribution:snapshot - Packages under development.

To update the distribution image, re-pull the image and then restart the docker container.

Every distribution contains packages that can be used by different versions of the Elastic Stack. The Elastic Package Registry API exposes a Kibana version constraint that allows for filtering packages that are compatible with a particular version.

These steps use the standard Docker CLI, but you can create a Kubernetes manifest based on this information. These images can also be used with other container runtimes compatible with Docker images.

  1. Pull the Docker image from the public Docker registry:

    docker pull docker.elastic.co/package-registry/distribution:8.1.3

  2. Save the Docker image locally:

    docker save -o package-registry-8.1.3.tar docker.elastic.co/package-registry/distribution:8.1.3

    Check the image size to ensure that you have enough disk space.

  3. Transfer the image to the air-gapped environment and load it:

    docker load -i package-registry-8.1.3.tar

  4. Run the Elastic Package Registry:

    docker run -it -p 8080:8080 docker.elastic.co/package-registry/distribution:8.1.3

  5. (Optional) You can monitor the health of your Elastic Package Registry with requests to the root path:

    docker run -it -p 8080:8080 \
    --health-cmd "curl -f -L http://127.0.0.1:8080/" \
    docker.elastic.co/package-registry/distribution:8.1.3
Connect Kibana to your hosted Elastic Package Registryedit

Use the xpack.fleet.registryUrl property in the Kibana config to set the URL of your hosted package registry. For example:

xpack.fleet.registryUrl: "http://package-registry.corp.net:8080"
TLS configuration of the Elastic Package Registryedit

You can configure the Elastic Package Registry to listen on a secure HTTPS port using TLS.

For example, given a key and a certificate pair available in /etc/ssl, you can start the Elastic Package Registry listening on the 443 port using the following command:

docker run -it -p 443:443 \
  -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:443 \
  -e EPR_TLS_KEY=/etc/ssl/package-registry.key \
  -e EPR_TLS_CERT=/etc/ssl/package-registry.crt \
  docker.elastic.co/package-registry/distribution:8.1.3

Limitations for Elastic Agent upgradesedit

The Upgrade Elastic Agents feature in technical preview does not currently support network restricted environments without access to artifacts.elastic.co. To upgrade Elastic Agents:

  1. Download the new version from the download page
  2. Place the tarball in a secure internal network location
  3. Use the upgrade command with a custom --source-uri option
Exampleedit
elastic-agent upgrade 8.1.3 --source-uri https://myinternaldomain.com/elastic-agent/elastic-agent-8.1.3-<platform>-x86_64.tar.gz
« Uninstall an Elastic Agent integration Install Elastic Agents »