Air-gapped environments

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 server

edit

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 Registry

edit

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:

7.17.25 (recommended): docker.elastic.co/package-registry/distribution:7.17.25 - Selection of packages from the production repository released with the 7.17.25 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.

Pull the Docker image from the public Docker registry:

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

Save the Docker image locally:

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

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

Transfer the image to the air-gapped environment and load it:
```
docker load -i package-registry-7.17.25.tar
```

Run the Elastic Package Registry:

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

(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/health" \
    docker.elastic.co/package-registry/distribution:7.17.25

Connect Kibana to your hosted Elastic Package Registry

edit

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 Registry

edit

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:7.17.25

Using custom CA certificates

edit

If you are using self-signed certificates or certificates issued by a custom Certificate Authority (CA), you need to set the file path to your CA in the NODE_EXTRA_CA_CERTS environment variable in the Kibana startup files.

NODE_EXTRA_CA_CERTS="/etc/kibana/certs/ca-cert.pem"

Limitations for Elastic Agent upgrades

edit

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:

Download the new version from the download page
Place the tarball in a secure internal network location
Use the upgrade command with a custom --source-uri option

Example

edit

elastic-agent upgrade 7.17.25 --source-uri https://myinternaldomain.com/elastic-agent/elastic-agent-7.17.25-<platform>-x86_64.tar.gz

« Uninstall an Elastic Agent integration Install Elastic Agents »