Air-gapped environments | Fleet and Elastic Agent Guide [8.7]

IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

« Installation layout Use a proxy server with Elastic Agent and Fleet »

Air-gapped environmentsedit

When running Elastic Agents in a restricted or closed network, you need to take extra steps to make sure:

Kibana is able to reach the Elastic Package Registry to download package metadata and content.
Elastic Agents are able to download binaries during upgrades.

When upgrading all the components in an air-gapped environment, it is recommended that you upgrade in the following order:

Upgrade the Elastic Package Registry.
Upgrade the Elastic Stack including Kibana.
Upgrade the Elastic artifact registry and ensure the latest Elastic Agent binaries are available.
Upgrade the on-premise Fleet Server.
In Fleet, issue an upgrade for all the Elastic Agents.

Use a proxy server to access the Elastic Package Registryedit

By default Kibana downloads package metadata and content from the public Elastic Package Registry at epr.elastic.co.

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

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

For more information, refer to Use a proxy server with Elastic Agent and Fleet.

Host your own Elastic Package Registryedit

The Elastic Package Registry packages include signatures used in package verification. By default, Fleet uses the Elastic public GPG key to verify package signatures. If you ever need to change this GPG key, use the xpack.fleet.packageVerification.gpgKeyPath setting in kibana.yml. For more information, refer to Fleet settings.

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 onsite 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.7.1 (recommended): docker.elastic.co/package-registry/distribution:8.7.1 - Selection of packages from the production repository released with Elastic Stack 8.7.1.
lite-8.7.1: docker.elastic.co/package-registry/distribution:lite-8.7.1 - Subset of the most commonly used packages from the production repository released with Elastic Stack 8.7.1. This image is a good candidate to start using Fleet in air-gapped environments.
production: docker.elastic.co/package-registry/distribution:production - Packages available in the production registry (https://epr.elastic.co).
lite: docker.elastic.co/package-registry/distribution:lite - Subset of the most commonly used packages available in the production registry (https://epr.elastic.co).

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

Save the Docker image locally:

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

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-8.7.1.tar
```

Run the Elastic Package Registry:

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

(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:8.7.1

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.7.1

Using custom CA certificatesedit

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"

Host your own artifact registry for binary downloadsedit

Elastic Agents must be able to access the Elastic artifact registry to download binaries during upgrades. By default Elastic Agents download artifacts from https://artifacts.elastic.co/downloads/.

To make binaries available in an air-gapped environment, you can host your own custom artifact registry, and then configure Elastic Agents to download binaries from it.

Create a custom artifact registry in a location accessible to your Elastic Agents:

Download the latest release artifacts from the public Elastic artifact registry at https://artifacts.elastic.co/downloads/. For example, the following cURL commands download all the artifacts that may be needed to upgrade Elastic Agents running on Linux. The exact list depends on which integrations you’re using.

curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.7.1-linux-x86_64.tar.gz.asc
curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.7.1-linux-x86_64.tar.gz
curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.7.1-linux-x86_64.tar.gz.sha512
curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.7.1-linux-x86_64.tar.gz.asc

On your HTTP file server, group the artifacts into directories and sub-directories that follow the same convention used by the Elastic artifact registry:
```
<source_uri>/<artifact_type>/<artifact_name>-<version>-<arch>-<package_type>
```
Where <artifact_type> may be beats/elastic-agent, beats/filebeat, fleet-server, endpoint-dev, and so on.

Make sure you have a plan or automation in place to update your artifact registry when new versions of Elastic Agent are available.

Add the agent binary download location to Fleet settings:
1. In Kibana, go to Fleet → Settings.
2. Under Agent Binary Download, click Add agent binary source to add the location of your artifact registry. For more detail about these settings, refer to Agent binary download settings. If you want all Elastic Agents to download binaries from this location, set it as the default.
If your artifact registry is not the default, edit your agent policies to override the default:
1. Go to Fleet → Agent policies and click the policy name to edit it.
2. Click Settings.
3. Under Agent Binary Download, select your artifact registry.
  
  When you trigger an upgrade for any Elastic Agents enrolled in the policy, the binaries are downloaded from your artifact registry instead of the public repository.

Not using Fleet? For standalone Elastic Agents, you can set the binary download location under agent.download.sourceURI in the elastic-agent.yml file, or run the elastic-agent upgrade command with the --source-uri flag specified.

« Installation layout Use a proxy server with Elastic Agent and Fleet »