Outbound Connections and Air-Gapped Deployments¶

Teams that run lakeFS inside a restricted network or a fully air-gapped environment need to know exactly which external hosts the server contacts, so that they can write firewall rules once and audit them with confidence. lakeFS needs no internet access to run, and as long as its license is configured as a token, none of the connections described on this page are required for it to work. Three of them are enabled by default, though, so an installation that runs without internet access should turn them off in its configuration before it is deployed.

This page lists every connection that the lakeFS server opens to a host you did not configure yourself, describes what each connection sends, and gives the setting that turns it off. Every other connection the server makes goes to a system that you configure, such as the database, the object storage behind each blockstore along with its cloud provider's authentication endpoints, an identity provider for single sign-on, or the targets of any webhooks defined in your repositories.

Outbound Connections Made by the lakeFS Server¶

Usage Statistics (stats.lakefs.io)¶

When the server starts, it sends a POST request to https://stats.lakefs.io/installation that describes the installation: its installation ID, the lakeFS and Go versions, the operating system and CPU architecture, the type of key-value database and object storage it uses, whether it runs in Docker or Kubernetes, and when it was set up. While it runs, the server sends POST requests to https://stats.lakefs.io/events with counts of the API operations that were called, every stats.flush_interval or once stats.flush_size records have accumulated, along with an hourly heartbeat.

The statistics never include object data, object paths, or credentials. Repository names, branch names, and user identifiers are included only when stats.extended is enabled, which is the default in lakeFS Enterprise, and even then each one is replaced by a hash of its value. When stats.extended is disabled, which is the default in lakeFS Community, those fields are removed before anything is sent.

To turn usage statistics off, set the following in the configuration file, or set the environment variable LAKEFS_STATS_ENABLED=false:

stats:
  enabled: false

Security Advisory Check (audit.lakefs.io)¶

Once at startup and then every security.audit_check_interval, which defaults to 24 hours, the server sends a GET request to https://audit.lakefs.io/audit with only its lakeFS version and installation ID as query parameters. The response lists any published security advisories that affect that version, and the server logs each one as a warning and reports an upgrade recommendation in the version information that the web UI displays.

To turn the security advisory check off, set its URL to an empty string in the configuration file:

security:
  audit_check_url: ""

This setting must go in the configuration file, because the server ignores environment variables whose value is empty, so setting LAKEFS_SECURITY_AUDIT_CHECK_URL="" has no effect.

Latest Release Check (api.github.com)¶

When a client asks the server for its version information, which the web UI does each time it loads, the server sends a GET request to https://api.github.com/repos/treeverse/lakeFS/releases/latest to find the latest public release and show an upgrade notice when the running version is older. The request carries no information about the installation, and its result, including a failed lookup, is cached for security.check_latest_version_cache, which defaults to one hour.

To turn the latest release check off, set the following in the configuration file, or set the environment variable LAKEFS_SECURITY_CHECK_LATEST_VERSION=false:

security:
  check_latest_version: false

Running lakectl --version makes the same lookup from the machine where it runs, so a machine that runs lakectl inside the restricted network will also try to reach api.github.com when that flag is used. Every other lakectl command talks only to the lakeFS server and, when it transfers objects with presigned URLs, to the object storage those URLs point to.

License Activation (team.lakefs.cloud)¶

A lakeFS Enterprise server can take its license either as a token, through license.path or license.contents, or as an activation key through license.activation_key. A token is verified locally against public keys built into the server, so it needs no network access and is the right choice for an air-gapped deployment. An activation key is exchanged for a license by a POST request to license.activation_endpoint, which defaults to https://team.lakefs.cloud/license, when the server starts without a valid cached license and again once a day to renew it.

To run without this connection, configure the license as a token, as described in License Configuration in lakeFS Enterprise, and leave license.activation_key unset.

Configuring lakeFS for an Air-Gapped Deployment¶

The following configuration turns off every connection on this page, and it keeps the license check fully offline by reading the license token from a file:

stats:
  enabled: false
security:
  audit_check_url: ""
  check_latest_version: false
license:
  path: /path/to/license.txt

With this configuration, the lakeFS server opens connections only to the systems you configure for it.

Logging of Outbound Connections¶

Apart from the warnings it logs for security advisories that affect the running version, the server does not write these connections to its log at the default log level, whether they succeed or fail. A failed usage statistics request, security advisory check, or latest release check is logged only at the DEBUG level, so the log of a server without internet access is not filled with connection errors. Because of this, the lakeFS log is not a record of the server's network activity, and the reliable way to confirm that no outbound connections remain is to monitor the network at the host or firewall level after applying the configuration above. To see failed attempts in the log while you verify a deployment, set logging.level to DEBUG as described in the configuration reference.

Summary¶

A lakeFS server runs without internet access, and it contacts external hosts only for usage statistics, the security advisory check, the latest release check, and, in lakeFS Enterprise, license activation. Turning off the first three in the configuration and supplying the license as a token removes every one of those connections, which leaves the server talking only to the database, object storage, and other systems you configure. For the full list of server settings, see the configuration reference, and for the rest of the security model, see the security overview.