How to deploy Fleet Server

Stack

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

For platform-specific deployment instructions, refer to:

• Deploy on-premises and self-managed Fleet Server
• Deploy Fleet Server on Kubernetes
• Deploy Fleet Server on Elastic Cloud
• Deploy Fleet Server in a mixed environment

Before deploying Fleet Server, ensure you have:

• A Fleet policy configured with the Fleet Server integration
• A service token for Fleet Server to authenticate with Elasticsearch
• TLS certificates (for production deployments)
• Network connectivity between Fleet Server and Elasticsearch, and between Elastic Agents and Fleet Server

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

Fleet Server requires configuration for two main connection types:

• Configuration for Fleet Server to communicate with Elasticsearch
• Configuration for Fleet Server to accept connections from Elastic Agents (server-side)

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

These settings configure how Fleet Server connects to Elasticsearch.

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

* Required if Elasticsearch uses certificates signed by a private or intermediate CA not publicly trusted
** Mutually exclusive with --fleet-server-service-token

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

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

elastic-agent install \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=fleet-server-policy-id \
  --fleet-server-es-ca=/path/to/elasticsearch-ca.crt
		

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

elastic-agent install \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=fleet-server-policy-id \
  --fleet-server-es-ca=/path/to/elasticsearch-ca.crt \
  --fleet-server-es-cert=/path/to/fleet-server-es-client.crt \
  --fleet-server-es-cert-key=/path/to/fleet-server-es-client.key
		

These settings configure how Fleet Server accepts connections from Elastic Agents (server-side).

The following CLI flags are available for configuring how Fleet Server accepts connections from Elastic Agents:

* If not specified, Fleet Server auto-generates a self-signed certificate. This is not recommended for production.

You can also configure these settings using environment variables instead of CLI flags:

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

elastic-agent install \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=fleet-server-policy-id \
  --fleet-server-cert=/path/to/fleet-server.crt \
  --fleet-server-cert-key=/path/to/fleet-server.key \
  --certificate-authorities=/path/to/fleet-ca.crt
		

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

elastic-agent install \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=fleet-server-policy-id \
  --fleet-server-cert=/path/to/fleet-server.crt \
  --fleet-server-cert-key=/path/to/fleet-server.key \
  --certificate-authorities=/path/to/agent-ca.crt \
  --fleet-server-client-auth=required
		

Understanding what can be configured using policy versus what must be provided using CLI or environment variables is crucial for managing Fleet Server deployments.

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

• Service token: --fleet-server-service-token or FLEET_SERVER_SERVICE_TOKEN
• Policy ID: --fleet-server-policy or FLEET_SERVER_POLICY_ID
• Elasticsearch CA trusted fingerprint: --fleet-server-es-ca-trusted-fingerprint (if using self-signed certificates)
• Fleet Server timeout: --fleet-server-timeout or FLEET_SERVER_TIMEOUT
• Fleet Server URL for bootstrap: FLEET_URL (environment variable only)

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

• Elasticsearch connection settings: Configured in the Elasticsearch output associated with the Fleet Server policy
  • Elasticsearch host URL
  • Elasticsearch CA certificate
  • mTLS client certificate and key for Elasticsearch
• Fleet Server TLS settings: Configured in Fleet settings under Fleet Server hosts
  • Fleet Server certificate and key
  • CA certificates for validating agent certificates
  • Client authentication mode
• Fleet Server binding settings: Configured in the Fleet Server integration policy
  • Host and port

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)

Settings provided using CLI or environment variables during installation are used for the initial bootstrap. After enrollment, the Fleet Server downloads its policy from Fleet, 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 Elasticsearch to verify the identity of Fleet Server in addition to Fleet Server verifying Elasticsearch.

Configure the following settings:

1. During installation (CLI or environment variables):

   • --fleet-server-es-cert / FLEET_SERVER_ES_CERT: Client certificate for Fleet Server
   • --fleet-server-es-cert-key / FLEET_SERVER_ES_CERT_KEY: Private key for client certificate
   • --fleet-server-es-ca / FLEET_SERVER_ELASTICSEARCH_CA: CA to validate Elasticsearch certificate

2. In Fleet settings (Elasticsearch output):

   • ssl.certificate: Path to client certificate (or embed certificate)
   • ssl.key: Path to private key (or embed key)
   • ssl.certificate_authorities: CA to validate Elasticsearch certificate

For more information, refer to Mutual TLS connection.

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 Fleet Server installation (CLI or environment variables):

   • --fleet-server-cert / FLEET_SERVER_CERT: Server certificate for Fleet Server
   • --fleet-server-cert-key / FLEET_SERVER_CERT_KEY: Private key for server certificate
   • --certificate-authorities / FLEET_CA: CA to validate agent client certificates
   • --fleet-server-client-auth=required / FLEET_SERVER_CLIENT_AUTH=required: Enable client authentication

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

3. In Fleet settings (Fleet Server hosts):

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

For more information, refer to Mutual TLS connection and How to deploy Elastic Agent.

The following sections provide best practices for deploying and managing Fleet Server:

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 Fleet Server certificates, include all hostnames and IP addresses that Elastic Agents will use to connect 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 installation, 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.
• If Fleet Server needs different Elasticsearch connection settings than other agents, create a dedicated Elasticsearch output for Fleet Server.

Follow these security best practices:

• Use mutual TLS for both Fleet Server to Elasticsearch and Elastic Agent to Fleet Server connections in high-security environments.
• Always use service tokens for Fleet Server authentication with Elasticsearch. Never use basic authentication credentials.
• Consider network segmentation to limit which hosts can connect to Fleet Server.
• Keep Fleet Server and Elastic Agent versions up to date to benefit from security patches.

After deploying Fleet Server, you can:

• Deploy Elastic Agents to connect to your Fleet Server
• Monitor Fleet Server to ensure it's running correctly
• Scale Fleet Server as your deployment grows
• Review Fleet Server secrets management for secure credential handling