Document the --id and --replace-token flags and their respective environment variables (#3414)

This PR documents the `--id` and `--replace-token` flags in the [Elastic
Agent command
reference](https://www.elastic.co/docs/reference/fleet/agent-command-reference#elastic-agent-install-command)
doc and their respective environment variables in the [Elastic Agent
environment
variables](https://www.elastic.co/docs/reference/fleet/agent-environment-variables)
doc.

Resolves #2491

## Development issues

elastic/elastic-agent#6361
elastic/fleet-server#4226

Author: vishaangelova

reference/fleet/agent-command-reference.md

@@ -146,10 +146,12 @@ elastic-agent enroll --url <string>
                      [--force]
                      [--header <strings>]
                      [--help]
+                     [--id <string>]
                      [--insecure ]
                      [--proxy-disabled]
                      [--proxy-header <strings>]
                      [--proxy-url <string>]
+                     [--replace-token <string>]
                      [--staging <string>]
                      [--tag <string>]
                      [global-flags]
@@ -298,6 +300,13 @@ For more information about custom certificates, refer to [Configure SSL/TLS for
 `--help`
 :   Show help for the `enroll` command.
 
+`--id <string>`
+:   Specifies the unique identifier (agent ID) to use when enrolling the {{agent}} with {{fleet-server}}. This setting is useful when restoring a previously enrolled agent or in stateless environments where the agent cannot persist enrollment data between redeployments.
+
+    :::{note}
+    If an agent with the same ID is already enrolled in {{fleet}}, enrollment will fail unless a valid replacement token is provided using the `--replace-token` flag.
+    :::
+
 `--insecure`
 :   Allow the {{agent}} to connect to {{fleet-server}} over insecure connections. This setting is required in the following situations:
 
@@ -317,6 +326,13 @@ For more information about custom certificates, refer to [Configure SSL/TLS for
 `--proxy-url <string>`
 :   Configures the proxy URL.
 
+`--replace-token <string>`
+:   Specifies a token that can be used to replace the {{agent}} after its enrollment in {{fleet-server}}. The token must be provided when enrolling an agent with a specific agent ID for the first time. Subsequently, the agent can be replaced by enrolling another agent using the same agent ID and replacement token. Once replaced, the original agent can no longer communicate with {{fleet}}.
+
+    :::{note}
+    If an {{agent}} is enrolled without a replacement token, it cannot be replaced by another agent with the same ID. This mechanism prevents accidental or malicious takeovers by requiring the replacement token to match the hashed token stored in {{fleet}}.
+    :::
+
 `--staging <string>`
 :   Configures agent to download artifacts from a staging build.
 
@@ -380,6 +396,16 @@ elastic-agent enroll --url=https://fleet-server:8220 \
   --certificate-authorities=/path/to/ca.crt
 ```
 
+Replace an {{agent}} enrolled in {{fleet-server}} with a specific agent ID and a replacement token:
+
+```shell
+elastic-agent enroll \
+  --url=https://fleet-server:8220 \
+  --enrollment-token=ENROLLMENT_TOKEN_HASH \
+  --id=MY_AGENT_ID \
+  --replace-token=REPLACEMENT_TOKEN_HASH
+```
+
 
 ## elastic-agent help [elastic-agent-help-command]
 

reference/fleet/agent-environment-variables.md

@@ -86,11 +86,13 @@ Settings used to enroll an {{agent}} into a {{fleet-server}}.
 | $$$env-enroll-elastic-agent-cert$$$<br>`ELASTIC_AGENT_CERT`<br> | (string) The path to the mutual TLS client certificate that {{agent}} will use to connect to {{fleet-server}}.<br> |
 | $$$env-enroll-elastic-agent-cert-key$$$<br>`ELASTIC_AGENT_CERT_KEY`<br> | (string) The path to the mutual TLS private key that {{agent}} will use to connect to {{fleet-server}}.<br> |
 | $$$env-enroll-elastic-agent-cert-key-passphrase$$$<br>`ELASTIC_AGENT_CERT_KEY_PASSPHRASE`<br> | (string) The path to the file that contains the passphrase for the mutual TLS private key that {{agent}} will use to connect to {{fleet-server}}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters.<br><br>This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use.<br> |
+| $$$env-enroll-elastic-agent-id$$$<br>`ELASTIC_AGENT_ID`<br> | (string) The unique identifier (agent ID) to use when enrolling the {{agent}} with {{fleet-server}}. This setting is useful when restoring a previously enrolled agent or in stateless containerized environments where the agent cannot persist enrollment data between redeployments.<br><br>If an agent with the same ID is already enrolled in {{fleet}}, enrollment will fail unless a valid replacement token is provided using the `FLEET_REPLACE_TOKEN` environment variable.<br><br>**Default:** `""`<br> |
 | $$$env-enroll-elastic-agent-tag$$$<br>`ELASTIC_AGENT_TAGS`<br> | (string) A comma-separated list of tags to apply to {{fleet}}-managed {{agent}}s. You can use these tags to filter the list of agents in {{fleet}}.<br> |
 | $$$env-enroll-fleet-enroll$$$<br>`FLEET_ENROLL`<br> | (bool) Set to `1` to enroll the {{agent}} into {{fleet-server}}.<br><br>**Default:** `false`<br> |
 | $$$env-enroll-fleet-force$$$<br>`FLEET_FORCE`<br> | (bool) Set to `true` to force overwrite of the current {{agent}} configuration without prompting for confirmation. This flag is helpful when using automation software or scripted deployments.<br><br>**Default:** `false`<br> |
 | $$$env-enroll-fleet-url$$$<br>`FLEET_URL`<br> | (string) URL to enroll the {{fleet-server}} into.<br><br>**Default:** `""`<br> |
 | $$$env-enroll-fleet-enrollment-token$$$<br>`FLEET_ENROLLMENT_TOKEN`<br> | (string) The token to use for enrollment.<br><br>**Default:** `""`<br> |
+| $$$env-enroll-fleet-replace-token$$$<br>`FLEET_REPLACE_TOKEN`<br> | (string) The token that can be used to replace the {{agent}} after it is enrolled in {{fleet-server}}. The `FLEET_REPLACE_TOKEN` environment variable must be provided when enrolling an agent with a specific agent ID for the first time. Subsequently, the agent can be replaced by enrolling another agent using the same `ELASTIC_AGENT_ID` and `FLEET_REPLACE_TOKEN` environment variables. Once replaced, the original agent can no longer communicate with {{fleet}}.<br><br>If an {{agent}} is enrolled without a replacement token, it cannot be replaced by another agent with the same ID. This mechanism prevents accidental or malicious takeovers by requiring the replacement token to match the hashed token stored in {{fleet}}.<br><br>**Default:** `""`<br> |
 | $$$env-enroll-fleet-token-name$$$<br>`FLEET_TOKEN_NAME`<br> | (string) The token name to use to fetch the token from {{kib}}.<br><br>**Default:** `""`<br> |
 | $$$env-enroll-fleet-token-policy-name$$$<br>`FLEET_TOKEN_POLICY_NAME`<br> | (string) The token policy name to use to fetch the token from {{kib}}.<br><br>**Default:** `false`<br> |
 | $$$env-enroll-fleet-ca$$$<br>`FLEET_CA`<br> | (string) The path to a certificate authority. Overrides `ELASTICSEARCH_CA` when set.<br><br>By default, {{agent}} uses the list of trusted certificate authorities (CA) from the operating system where it is running. If the certificate authority that signed your node certificates is not in the host system’s trusted certificate authorities list, use this config to add the path to the `.pem` file that contains your CA’s certificate.<br><br>**Default:** `false`<br> |