Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.x] Add steps to configure a PGP key for agent upgrade (backport #984) #1655

Merged
merged 1 commit into from
Jan 29, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ As an alterative, you can do one of the following:
* <<fleet-agent-proxy-support,Configure a proxy server>> for standalone {agent} to access the {artifact-registry}.
* <<host-artifact-registry,Host your own artifact registry>> for standalone {agent} to access binary downloads.

As well, starting from version 8.9.0, during the upgrade process {agent} needs to download a PGP/GPG key. Refer to <<air-gapped-pgp-fleet>> for the steps to configure the key download location in an air-gapped environment.

Refer to <<air-gapped,Air-gapped environments>> for more details.

[[upgrade-standalone-verify-package]]
Expand Down
45 changes: 45 additions & 0 deletions docs/en/ingest-management/fleet/air-gapped.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,51 @@ Set the following property in {kib} to enable air-gapped mode in {fleet}. This a
xpack.fleet.isAirGapped: true
----

[discrete]
[[air-gapped-pgp-fleet]]
== Configure {agents} to download a PGP/GPG key from {fleet-server}

Starting from version 8.9.0, when {agent} tries to perform an upgrade, it first verifies the binary signature with the key bundled in the agent. This process has a backup mechanism that will use the key coming from `https://artifacts.elastic.co/GPG-KEY-elastic-agent` instead of the one it already has.

In an air-gapped environment, an {agent} which doesn't have access to a PGP/GPG key from `https://artifacts.elastic.co/GPG-KEY-elastic-agent` would fail to be upgraded.
For versions 8.9.0 to 8.10.3, you can resolve this problem following the steps described in the associated link:https://www.elastic.co/guide/en/fleet/8.9/release-notes-8.9.0.html#known-issues-8.9.0[known issue] documentation.

Starting in version 8.10.4, you can resolve this problem by configuring {agents} to download the PGP/GPG key from {fleet-server}.

Starting in version 8.10.4, {agent} will:

. Verify the binary signature with the key bundled in the agent.
. If the verification doesn't pass, the agent will download the PGP/GPG key from `https://artifacts.elastic.co/GPG-KEY-elastic-agent` and verify it.
. If that verification doesn't pass, the agent will download the PGP/GPG key from {fleet-server} and verify it.
. If that verification doesn't pass, the upgrade is blocked.

By default, {fleet-server} serves {agents} with the key located in `FLEETSERVER_BINARY_DIR/elastic-agent-upgrade-keys/default.pgp`.
The key is served through the {fleet-server} endpoint `GET /api/agents/upgrades/{major}.{minor}.{patch}/pgp-public-key`.

If there isn't a `default.pgp` key in the `FLEETSERVER_BINARY_DIR/elastic-agent-upgrade-keys/default.pgp` directory, {fleet-server} instead will attempt to retrieve a PGP/GPG key from the URL that you can specify with the `server.pgp.upstream_url` setting.

You can prevent {fleet} from downloading the PGP/GPG key from `server.pgp.upstream_url` by manually downloading it from `https://artifacts.elastic.co/GPG-KEY-elastic-agent` and storing it at `FLEETSERVER_BINARY_DIR/elastic-agent-upgrade-keys/default.pgp`.

To set a custom URL for {fleet-server} to access a PGP/GPG key and make it available to {agents}:

. In {kib}, go to *Management > {fleet} > Agent policies*.
. Select a policy for the agents that you want to upgrade.
. On the policy page, in the **Actions** menu for the {fleet-server} integration, select **Edit integration**.
. In the {fleet-server} settings section expand **Change defaults** and **Advanced options**.
. In the **Custom fleet-server configurations** field, add the setting `server.pgp.upstream_url` with the full URL where the PGP/GPG key can be accessed. For example:

[source,yaml]
----
server.pgp.upstream_url: <http://my-web-server:8080/default.pgp>
----

The setting `server.pgp.upstream_url` must point to a web server hosting the PGP/GPG key, which must be reachable by the host where {fleet-server} is installed.

Note that:

* `server.pgp.upstream_url` may be specified as an `http` endpoint (instead of `https`).
* For an `https` endpoint, the CA for {fleet-server} to connect to `server.pgp.upstream_url` must be trusted by {fleet-server} using the `--certificate-authorities` setting that is used globally for {agent}.

[discrete]
[[air-gapped-proxy-server]]
== Use a proxy server to access the {package-registry}
Expand Down