How to deploy Elastic Agent

Stack

This guide provides comprehensive information about deploying Elastic Agent, including configuration flags, environment variables, mutual TLS (mTLS) setup, and best practices for managing configuration through policies versus command-line interface (CLI).

For platform-specific installation instructions, refer to:

• Install Fleet-managed Elastic Agents
• Install Elastic Agents in containers
• Install standalone Elastic Agents

Before deploying Elastic Agent, ensure you have:

• A running Fleet Server accessible to your Elastic Agent
• An enrollment token from Fleet for the agent policy you want to use
• TLS certificates (if Fleet Server uses custom certificates)
• Network connectivity between Elastic Agent and Fleet Server, and between Elastic Agent and output destinations (Elasticsearch, Logstash, and so on)

For more information about prerequisites, refer to the platform-specific installation guides listed above.

Elastic Agent requires configuration for two main connection types:

• Configuration for Elastic Agent to enroll and communicate with Fleet Server
• Configuration for Elastic Agent to send data to output destinations

The following sections organize all configuration flags and environment variables by connection type.

These settings configure how Elastic Agent connects to Fleet Server.

The following CLI flags are available for configuring the connection from Elastic Agent to Fleet Server:

* Required if Fleet Server uses certificates signed by a private or intermediate CA not publicly trusted

You can also configure the connection using environment variables instead of CLI flags:

For one-way TLS (Elastic Agent validates Fleet Server certificate, but Fleet Server does not validate Elastic Agent certificate), use the following command:

elastic-agent install \
  --url=https://fleet-server:8220 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \
  --certificate-authorities=/path/to/fleet-ca.crt
		

For mutual TLS (both Elastic Agent and Fleet Server validate each other's certificates), use the following command:

elastic-agent install \
  --url=https://fleet-server:8220 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \
  --certificate-authorities=/path/to/fleet-ca.crt \
  --elastic-agent-cert=/path/to/agent-client.crt \
  --elastic-agent-cert-key=/path/to/agent-client.key
		

These settings configure how Elastic Agent sends data to output destinations (Elasticsearch, Logstash, Kafka, and so on).

Output configuration for Fleet-managed Elastic Agents is primarily managed through Fleet settings and agent policies, not CLI flags. However, some settings can be configured using environment variables for containerized deployments.

The following environment variables can be used for output configuration:

For one-way TLS (Elastic Agent validates the output's certificate, but the output does not validate Elastic Agent's certificate), configure the following:

In Fleet settings (Elasticsearch output):

• Configure the output host URL

• Add CA certificate in Elasticsearch CA trusted fingerprint or advanced YAML configuration:

  ssl.certificate_authorities: ["/path/to/es-ca.crt"]
  		

Using environment variables (containerized deployments):

ELASTICSEARCH_HOST=https://elasticsearch:9200
ELASTICSEARCH_CA=/path/to/es-ca.crt
		

For mutual TLS (both Elastic Agent and output validate each other's certificates), configure the following:

In Fleet settings (Elasticsearch output - advanced YAML configuration):

ssl.certificate_authorities:
  - /path/to/es-ca.crt
ssl.certificate: /path/to/agent-client.crt
ssl.key: /path/to/agent-client.key
		

For Elastic Agent to Logstash connections, configure the output in Fleet settings as follows:

• Configure the Logstash host URL

• Configure TLS settings if required. For one-way TLS, only include ssl.certificate_authorities. For mutual TLS, also include ssl.certificate and ssl.key:

  ssl.certificate_authorities:
    - /path/to/logstash-ca.crt
  ssl.certificate: /path/to/agent-client.crt
  ssl.key: /path/to/agent-client.key
  		

For more information, refer to Configure Logstash output and Secure Logstash connections.

Understanding what can be configured using policy and what must be provided using CLI or environment variables is crucial for managing Elastic Agent deployments.

The following settings cannot be overridden by policy and must be provided during enrollment:

• Fleet Server URL: --url or FLEET_URL
• Enrollment token: --enrollment-token or FLEET_ENROLLMENT_TOKEN
• Agent ID: --id or ELASTIC_AGENT_ID (if specified)
• Replace token: --replace-token or FLEET_REPLACE_TOKEN (if replacing an agent)
• Tags: --tag or ELASTIC_AGENT_TAGS
• CA fingerprint: --ca-sha256 (if using certificate pinning)
• Insecure flag: --insecure or FLEET_INSECURE (not recommended)

The following settings can be set using CLI during enrollment, but can also be updated using policy after enrollment:

• CA certificates for Fleet Server: Configured in Fleet settings under Fleet Server hosts
• mTLS client certificates for Fleet Server: Configured in Fleet settings under Fleet Server hosts
• Output configuration: Configured in Fleet settings under Outputs
  • Output host URLs
  • Output authentication (API keys, usernames/passwords)
  • Output TLS/mTLS settings
• Proxy settings: Configured in agent policy

The configuration precedence is as follows (highest to lowest):

1. CLI flags (during installation/enrollment)
2. Environment variables (during installation/enrollment)
3. Policy configuration (after enrollment, downloaded from Fleet Server)

Settings provided using CLI or environment variables during enrollment are used for the initial connection to Fleet Server. After enrollment, the Elastic Agent downloads its policy from Fleet Server, and policy settings take precedence for most configuration options (except those listed in the Must be provided using CLI or environment variables section above).

Mutual TLS provides enhanced security by requiring both parties in a connection to authenticate using certificates.

Use this option when you need Fleet Server to verify the identity of connecting Elastic Agents in addition to Elastic Agents verifying Fleet Server.

Configure the following settings:

1. During Elastic Agent enrollment (CLI or environment variables):

   • --elastic-agent-cert / ELASTIC_AGENT_CERT: Client certificate for Elastic Agent
   • --elastic-agent-cert-key / ELASTIC_AGENT_CERT_KEY: Private key for client certificate
   • --certificate-authorities / FLEET_CA: CA to validate Fleet Server certificate

2. During Fleet Server installation (must be configured):

   • --fleet-server-client-auth=required / FLEET_SERVER_CLIENT_AUTH=required: Enable client authentication
   • --certificate-authorities / FLEET_CA: CA to validate agent client certificates

3. In Fleet settings (Fleet Server hosts):

   • Server SSL certificate authorities: CA to validate agent certificates
   • Enable client authentication: Set to required

For more information, refer to Mutual TLS connection and How to deploy Fleet Server.

Use this option when you need output destinations (Elasticsearch, Logstash) to verify the identity of Elastic Agents in addition to Elastic Agents verifying the output.

Configure the following settings:

1. In Fleet settings (Elasticsearch or Logstash output - advanced YAML configuration):

   ssl.certificate_authorities:
     - /path/to/output-ca.crt
   ssl.certificate: /path/to/agent-client.crt
   ssl.key: /path/to/agent-client.key
   		

2. On the output side (Elasticsearch or Logstash):

   • Configure the output to require client certificates
   • Ensure the CA used to sign agent certificates is trusted by the output

The following sections provide best practices for deploying and managing Elastic Agent:

Follow these best practices for managing certificates:

• Never use self-signed certificates in production. Generate certificates using a trusted CA or your organization's CA.
• When generating certificates, include all hostnames and IP addresses that will be used in the certificate's Subject Alternative Name (SAN) list.
• Store private keys securely and use appropriate file permissions. Consider using encrypted keys with passphrases.
• Plan for certificate rotation. For more information, refer to Certificate rotation.

Follow these best practices for managing configuration:

• After initial enrollment, manage most settings through Fleet policies rather than CLI flags.
• Document your configuration to keep track of which settings are configured using CLI, environment variables, and policies.
• Test policy changes in a non-production environment before applying to production.
• For containerized Elastic Agents, use environment variables to provide host-specific settings while keeping policies generic.

Follow these security best practices:

• Use mutual TLS for both Elastic Agent to Fleet Server and Fleet Server to Elastic Agent to output connections in high-security environments.
• Prefer API keys or service tokens over basic authentication for output connections.
• Consider network segmentation to limit which hosts can connect to Fleet Server and outputs.
• Keep Elastic Agent versions up to date to benefit from security patches.

After deploying Elastic Agent, you can:

• Manage Elastic Agents in Fleet to monitor and update agent configurations
• Monitor Elastic Agent to ensure it's running correctly
• Upgrade Elastic Agent to later versions
• Review Elastic Agent environment variables (for containerized deployments)