diff --git a/reference/fleet/add-fleet-server-cloud.md b/reference/fleet/add-fleet-server-cloud.md index 9bfb279f10..b25d287286 100644 --- a/reference/fleet/add-fleet-server-cloud.md +++ b/reference/fleet/add-fleet-server-cloud.md @@ -2,6 +2,8 @@ navigation_title: Deploy on Elastic Cloud mapped_pages: - https://www.elastic.co/guide/en/fleet/current/add-fleet-server-cloud.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -13,6 +15,10 @@ To use {{fleet}} for central management, a [{{fleet-server}}](/reference/fleet/f {{fleet-server}} can be provisioned and hosted on {{ecloud}}. When the Cloud deployment is created, a highly available set of {{fleet-server}}s is provisioned automatically. +::::{note} +For comprehensive information about {{fleet-server}} configuration flags, environment variables, mutual TLS (mTLS) setup, and policy vs CLI precedence, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). This guide provides detailed configuration organized by connection type. +:::: + This approach might be right for you if you want to reduce on-prem compute resources and you’d like Elastic to take care of provisioning and life cycle management of your deployment. With this approach, multiple {{fleet-server}}s are automatically provisioned to satisfy the chosen instance size (instance sizes are modified to satisfy the scale requirement). You can also choose the resources allocated to each {{fleet-server}} and whether you want each {{fleet-server}} to be deployed in multiple availability zones. If you choose multiple availability zones to address your fault-tolerance requirements, those instances are also utilized to balance the load. diff --git a/reference/fleet/add-fleet-server-kubernetes.md b/reference/fleet/add-fleet-server-kubernetes.md index aa09ee441c..095bde65f8 100644 --- a/reference/fleet/add-fleet-server-kubernetes.md +++ b/reference/fleet/add-fleet-server-kubernetes.md @@ -1,5 +1,7 @@ --- navigation_title: Deploy on Kubernetes +applies_to: + stack: ga mapped_pages: - https://www.elastic.co/guide/en/fleet/current/add-fleet-server-kubernetes.html products: @@ -25,6 +27,10 @@ This guide assumes familiarity with Kubernetes concepts and resources, such as ` To use {{fleet}} for central management, a [{{fleet-server}}](/reference/fleet/fleet-server.md) must be running and accessible to your hosts. +::::{note} +For comprehensive information about {{fleet-server}} configuration flags, environment variables, mutual TLS (mTLS) setup, and policy vs CLI precedence, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). This guide provides detailed configuration organized by connection type. +:::: + You can deploy {{fleet-server}} on Kubernetes and manage it yourself. In this deployment model, you are responsible for high-availability, fault-tolerance, and lifecycle management of the {{fleet-server}}. To deploy a {{fleet-server}} on Kubernetes and register it into {{fleet}} you will need the following details: @@ -72,7 +78,7 @@ Before deploying {{fleet-server}}, you need to: ### {{fleet-server}} and SSL/TLS certificates considerations [add-fleet-server-kubernetes-cert-prereq] -This section shows the minimum requirements in terms of Transport Layer Security (TLS) certificates for the {{fleet-server}}, assuming no mutual TLS (mTLS) is needed. Refer to [One-way and mutual TLS certifications flow](/reference/fleet/tls-overview.md) and [{{agent}} deployment models with mutual TLS](/reference/fleet/mutual-tls.md) for more information about the configuration needs of both approaches. +This section shows the minimum requirements in terms of Transport Layer Security (TLS) certificates for the {{fleet-server}}, assuming no mutual TLS (mTLS) is needed. Refer to [One-way and mutual TLS certifications flow](/reference/fleet/tls-overview.md) and [{{agent}} deployment models with mutual TLS](/reference/fleet/mutual-tls.md) for more information about the configuration needs of both approaches. For detailed configuration information organized by connection type, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md). There are two main traffic flows for {{fleet-server}}, each with different TLS requirements: diff --git a/reference/fleet/add-fleet-server-mixed.md b/reference/fleet/add-fleet-server-mixed.md index d94f2e6ba9..b78da7d3ca 100644 --- a/reference/fleet/add-fleet-server-mixed.md +++ b/reference/fleet/add-fleet-server-mixed.md @@ -1,6 +1,8 @@ --- mapped_pages: - https://www.elastic.co/guide/en/fleet/current/add-fleet-server-mixed.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -12,6 +14,10 @@ To use {{fleet}} for central management, a [{{fleet-server}}](/reference/fleet/f Another approach is to deploy a cluster of {{fleet-server}}s on-premises and connect them back to {{ecloud}} with access to {{es}} and {{kib}}. In this [deployment model](/reference/fleet/deployment-models.md), you are responsible for high-availability, fault-tolerance, and lifecycle management of {{fleet-server}}. +::::{note} +For comprehensive information about {{fleet-server}} configuration flags, environment variables, mutual TLS (mTLS) setup, and policy vs CLI precedence, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). This guide provides detailed configuration organized by connection type. +:::: + This approach might be right for you if you would like to limit the control plane traffic out of your data center. For example, you might take this approach if you are a managed service provider or a larger enterprise that segregates its networks. This approach might *not* be right for you if you don’t want to manage the life cycle of an extra compute resource in your environment for {{fleet-server}} to reside on. diff --git a/reference/fleet/add-fleet-server-on-prem.md b/reference/fleet/add-fleet-server-on-prem.md index f614532fc4..e71ee621dc 100644 --- a/reference/fleet/add-fleet-server-on-prem.md +++ b/reference/fleet/add-fleet-server-on-prem.md @@ -2,6 +2,8 @@ navigation_title: Deploy on-premises and self-managed mapped_pages: - https://www.elastic.co/guide/en/fleet/current/add-fleet-server-on-prem.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -13,6 +15,10 @@ To use {{fleet}} for central management, a [{{fleet-server}}](/reference/fleet/f You can deploy {{fleet-server}} on-premises and manage it yourself. In this [deployment model](/reference/fleet/deployment-models.md), you are responsible for high-availability, fault-tolerance, and lifecycle management of {{fleet-server}}. +::::{note} +For comprehensive information about {{fleet-server}} configuration flags, environment variables, mutual TLS (mTLS) setup, and policy vs CLI precedence, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). This guide provides detailed configuration organized by connection type. +:::: + This approach might be right for you if you would like to limit the control plane traffic out of your data center or have requirements for fully air-gapped operations. For example, you might take this approach if you need to satisfy data governance requirements or you want agents to only have access to a private segmented network. This approach might *not* be right for you if you don’t want to manage the life cycle of your Elastic environment and instead would like that to be handled by Elastic. @@ -107,13 +113,14 @@ To add a {{fleet-server}}: * Use **Advanced** if you want to either: * **Use your own {{fleet-server}} policy.** {{fleet-server}} policies manage and configure the {{agent}} running on {{fleet-server}} hosts to launch a {{fleet-server}} process. You can create a new {{fleet-server}} policy or select an existing one. Alternatively you can [create a {{fleet-server}} policy without using the UI](/reference/fleet/create-policy-no-ui.md), and then select the policy here. - * **Use your own TLS certificates.** TLS certificates encrypt traffic between {{agent}}s and {{fleet-server}}. To learn how to generate certs, refer to [Configure SSL/TLS for self-managed {{fleet-server}}s](/reference/fleet/secure-connections.md). + * **Use your own TLS certificates.** TLS certificates encrypt traffic between {{agent}}s and {{fleet-server}}. To learn how to generate certs, refer to [Configure SSL/TLS for self-managed {{fleet-server}}s](/reference/fleet/secure-connections.md). For detailed information about configuring TLS and mTLS connections, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md). ::::{note} If you are providing your own certificates: * Before running the `install` command, make sure you replace the values in angle brackets. * The URL specified by `--url` must match the DNS name used to generate the certificate specified by `--fleet-server-cert`. + * For comprehensive configuration details, including all available flags and environment variables, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md). :::: @@ -127,8 +134,8 @@ To add a {{fleet-server}}: ::::{note} * The fields to configure {{fleet-server}} hosts are not available if the hosts are already configured outside of {{fleet}}. For more information, refer to [{{fleet}} settings in {{kib}}](kibana://reference/configuration-reference/fleet-settings.md). - * When using the **Advanced** option, it’s recommended to generate a unique service token for each {{fleet-server}}. For other ways to generate service tokens, refer to [`elasticsearch-service-tokens`](elasticsearch://reference/elasticsearch/command-line-tools/service-tokens-command.md). - * If you’ve configured a non-default port for {{fleet-server}} in the {{fleet-server}} integration, you need to include the `--fleet-server-host` and `--fleet-server-port` options in the `elastic-agent install` command. Refer to the [install command documentation](/reference/fleet/agent-command-reference.md#elastic-agent-install-command) for details. + * When using the **Advanced** option, it's recommended to generate a unique service token for each {{fleet-server}}. For other ways to generate service tokens, refer to [`elasticsearch-service-tokens`](elasticsearch://reference/elasticsearch/command-line-tools/service-tokens-command.md). + * If you've configured a non-default port for {{fleet-server}} in the {{fleet-server}} integration, you need to include the `--fleet-server-host` and `--fleet-server-port` options in the `elastic-agent install` command. For detailed information about all available configuration flags and environment variables, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md). :::: diff --git a/reference/fleet/deploy-elastic-agent.md b/reference/fleet/deploy-elastic-agent.md new file mode 100644 index 0000000000..1c2f9c779d --- /dev/null +++ b/reference/fleet/deploy-elastic-agent.md @@ -0,0 +1,327 @@ +--- +navigation_title: How to deploy Elastic Agent +mapped_pages: + - https://www.elastic.co/guide/en/fleet/current/deploy-elastic-agent.html +applies_to: + stack: ga +products: + - id: fleet + - id: elastic-agent +--- + +# How to deploy {{agent}} [deploy-elastic-agent] + +This guide provides comprehensive information about deploying {{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 {{agent}}s](/reference/fleet/install-fleet-managed-elastic-agent.md) +- [Install {{agent}}s in containers](/reference/fleet/install-elastic-agents-in-containers.md) +- [Install standalone {{agent}}s](/reference/fleet/install-standalone-elastic-agent.md) + +## Prerequisites [deploy-elastic-agent-prereq] + +Before deploying {{agent}}, ensure you have: + +* A running {{fleet-server}} accessible to your {{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 {{agent}} and {{fleet-server}}, and between {{agent}} and output destinations ({{es}}, {{ls}}, and so on) + +For more information about prerequisites, refer to the platform-specific installation guides listed above. + +## Configuration overview [deploy-elastic-agent-config-overview] + +{{agent}} requires configuration for two main connection types: + +* [Configuration for {{agent}} to enroll and communicate with {{fleet-server}}](#deploy-elastic-agent-ea-to-fs) +* [Configuration for {{agent}} to send data to output destinations](#deploy-elastic-agent-ea-to-outputs) + +The following sections organize all configuration flags and environment variables by connection type. + +## {{agent}} to {{fleet-server}} [deploy-elastic-agent-ea-to-fs] + +These settings configure how {{agent}} connects to {{fleet-server}}. + +### CLI flags [deploy-elastic-agent-ea-to-fs-cli] + +The following CLI flags are available for configuring the connection from {{agent}} to {{fleet-server}}: + +| Flag | Purpose | Required | Can be overridden by policy? | +| --- | --- | --- | --- | +| `--url` | {{fleet-server}} URL to enroll into | Yes | No - must be CLI or environment variable | +| `--enrollment-token` | Enrollment token for the agent policy | Yes | No - must be CLI or environment variable | +| `--certificate-authorities` | CA certificates to validate {{fleet-server}} certificate | Optional* | Yes - configured in {{fleet}} settings | +| `--ca-sha256` | SHA-256 fingerprint of CA for certificate pinning | Optional* | No - must be CLI | +| `--elastic-agent-cert` | Client certificate for mTLS connection to {{fleet-server}} | Optional (mTLS only) | Yes - configured in {{fleet}} settings | +| `--elastic-agent-cert-key` | Private key for mTLS client certificate | Optional (mTLS only) | Yes - configured in {{fleet}} settings | +| `--elastic-agent-cert-key-passphrase` | Path to passphrase file for encrypted private key | Optional | Yes - configured in {{fleet}} settings | +| `--insecure` | Deactivate certificate verification (not recommended) | No - not recommended | No - must be CLI or environment variable | +| `--id` | Unique agent identifier | Optional | No - must be CLI or environment variable | +| `--replace-token` | Token to replace an existing agent with same ID | Optional | No - must be CLI or environment variable | +| `--tag` | Comma-separated list of tags for the agent | Optional | No - must be CLI or environment variable | +| `--proxy-url` | Proxy URL for {{fleet-server}} connections | Optional | Yes - configured in agent policy | +| `--proxy-disabled` | Deactivate proxy support | Optional | No - must be CLI | +| `--proxy-header` | Additional headers for proxy CONNECT requests | Optional | No - must be CLI | + +\* Required if {{fleet-server}} uses certificates signed by a private or intermediate CA not publicly trusted + +### Environment variables [deploy-elastic-agent-ea-to-fs-env] + +You can also configure the connection using environment variables instead of CLI flags: + +| Environment variable | Purpose | CLI flag equivalent | Can be overridden by policy? | +| --- | --- | --- | --- | +| `FLEET_URL` | {{fleet-server}} URL | `--url` | No - must be CLI or environment variable | +| `FLEET_ENROLLMENT_TOKEN` | Enrollment token | `--enrollment-token` | No - must be CLI or environment variable | +| `FLEET_CA` | Path to CA certificate | `--certificate-authorities` | Yes - configured in {{fleet}} settings | +| `ELASTIC_AGENT_CERT` | Path to client certificate for mTLS | `--elastic-agent-cert` | Yes - configured in {{fleet}} settings | +| `ELASTIC_AGENT_CERT_KEY` | Path to private key for mTLS | `--elastic-agent-cert-key` | Yes - configured in {{fleet}} settings | +| `ELASTIC_AGENT_CERT_KEY_PASSPHRASE` | Path to passphrase file | `--elastic-agent-cert-key-passphrase` | Yes - configured in {{fleet}} settings | +| `FLEET_INSECURE` | Deactivate certificate verification | `--insecure` | No - must be CLI or environment variable | +| `ELASTIC_AGENT_ID` | Unique agent identifier | `--id` | No - must be CLI or environment variable | +| `FLEET_REPLACE_TOKEN` | Token to replace existing agent | `--replace-token` | No - must be CLI or environment variable | +| `ELASTIC_AGENT_TAGS` | Comma-separated tags | `--tag` | No - must be CLI or environment variable | + +### One-way TLS configuration [deploy-elastic-agent-ea-to-fs-one-way] + +For one-way TLS ({{agent}} validates {{fleet-server}} certificate, but {{fleet-server}} does not validate {{agent}} certificate), use the following command: + +```shell +elastic-agent install \ + --url=https://fleet-server:8220 \ + --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \ + --certificate-authorities=/path/to/fleet-ca.crt +``` + +### Mutual TLS configuration [deploy-elastic-agent-ea-to-fs-mtls] + +For mutual TLS (both {{agent}} and {{fleet-server}} validate each other's certificates), use the following command: + +```shell +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 +``` + +::::{note} +When using mTLS between {{agent}} and {{fleet-server}}, the {{fleet-server}} must be configured with `--fleet-server-client-auth=required` (or `optional`) and the corresponding CA certificates. For more information, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). +:::: + +## {{agent}} to {{es}}, {{ls}} or other outputs [deploy-elastic-agent-ea-to-outputs] + +These settings configure how {{agent}} sends data to output destinations ({{es}}, {{ls}}, Kafka, and so on). + +### Configuration method [deploy-elastic-agent-ea-to-outputs-method] + +Output configuration for {{fleet}}-managed {{agent}}s is primarily managed through {{fleet}} settings and agent policies, not CLI flags. However, some settings can be configured using environment variables for containerized deployments. + +### Environment variables [deploy-elastic-agent-ea-to-outputs-env] + +The following environment variables can be used for output configuration: + +| Environment variable | Purpose | Can be overridden by policy? | +| --- | --- | --- | +| `ELASTICSEARCH_HOST` | {{es}} host URL | Yes - configured in {{es}} output | +| `ELASTICSEARCH_USERNAME` | Basic authentication username | Yes - configured in {{es}} output | +| `ELASTICSEARCH_PASSWORD` | Basic authentication password | Yes - configured in {{es}} output | +| `ELASTICSEARCH_API_KEY` | API key for authentication | Yes - configured in {{es}} output | +| `ELASTICSEARCH_CA` | Path to CA certificate | Yes - configured in {{es}} output | + +::::{note} +Environment variables are typically used for containerized deployments or when using the [env provider](/reference/fleet/env-provider.md) to reference values in policies. + +For standalone {{agent}}s, output configuration is done in the `elastic-agent.yml` file. For more information, refer to [Configure outputs for standalone {{agent}}s](/reference/fleet/elastic-agent-output-configuration.md). +:::: + +### One-way TLS configuration [deploy-elastic-agent-ea-to-outputs-one-way] + +For one-way TLS ({{agent}} validates the output's certificate, but the output does not validate {{agent}}'s certificate), configure the following: + +**In {{fleet}} settings ({{es}} output)**: +- Configure the output host URL +- Add CA certificate in {{es}} CA trusted fingerprint or advanced YAML configuration: + + ```yaml + ssl.certificate_authorities: ["/path/to/es-ca.crt"] + ``` + +**Using environment variables** (containerized deployments): + +```shell +ELASTICSEARCH_HOST=https://elasticsearch:9200 +ELASTICSEARCH_CA=/path/to/es-ca.crt +``` + +### Mutual TLS configuration [deploy-elastic-agent-ea-to-outputs-mtls] + +For mutual TLS (both {{agent}} and output validate each other's certificates), configure the following: + +**In {{fleet}} settings ({{es}} output - advanced YAML configuration)**: + +```yaml +ssl.certificate_authorities: + - /path/to/es-ca.crt +ssl.certificate: /path/to/agent-client.crt +ssl.key: /path/to/agent-client.key +``` + +::::{important} +When configuring mTLS for {{agent}} to {{es}} connections: +* The certificate and key paths must be available on all hosts running {{agent}}s. Alternatively, you can embed the certificates directly in the YAML configuration. +* The CA used to sign the agent certificate must be trusted by {{es}}. + +For more information, refer to [Mutual TLS connection](/reference/fleet/mutual-tls.md#mutual-tls-on-premise) and [Output SSL options](/reference/fleet/tls-overview.md#output-ssl-options). +:::: + +### {{ls}} output configuration [deploy-elastic-agent-ea-to-outputs-logstash] + +For {{agent}} to {{ls}} connections, configure the output in {{fleet}} settings as follows: + +- Configure the {{ls}} 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`: + + ```yaml + 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 {{ls}} output](/reference/fleet/ls-output-settings.md) and [Secure {{ls}} connections](/reference/fleet/secure-logstash-connections.md). + +## Policy and CLI precedence [deploy-elastic-agent-policy-precedence] + +Understanding what can be configured using policy and what must be provided using CLI or environment variables is crucial for managing {{agent}} deployments. + +### Must be provided using CLI or environment variables [deploy-elastic-agent-must-cli] + +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) + +### Can be overridden by policy [deploy-elastic-agent-can-override] + +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 + +### Configuration hierarchy [deploy-elastic-agent-config-hierarchy] + +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 {{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](#deploy-elastic-agent-must-cli) section above). + +::::{note} +If the agent policy contains mTLS configuration settings, those settings take precedence over those used during enrollment. This includes both the mTLS settings used for connectivity between {{agent}} and {{fleet-server}}, and the settings used between {{agent}} and its specified output. + +The initial TLS, mTLS, or proxy configuration settings specified when {{agent}} is enrolled cannot be removed through the agent policy; they can only be updated. +:::: + +## Mutual TLS (mTLS) configuration [deploy-elastic-agent-mtls] + +Mutual TLS provides enhanced security by requiring both parties in a connection to authenticate using certificates. + +### mTLS between {{agent}} and {{fleet-server}} [deploy-elastic-agent-mtls-ea-fs] + +Use this option when you need {{fleet-server}} to verify the identity of connecting {{agent}}s in addition to {{agent}}s verifying {{fleet-server}}. + +Configure the following settings: + +1. **During {{agent}} enrollment** (CLI or environment variables): + * `--elastic-agent-cert` / `ELASTIC_AGENT_CERT`: Client certificate for {{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](/reference/fleet/mutual-tls.md#mutual-tls-on-premise) and [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md). + +### mTLS between {{agent}} and {{es}}/{{ls}} [deploy-elastic-agent-mtls-ea-outputs] + +Use this option when you need output destinations ({{es}}, {{ls}}) to verify the identity of {{agent}}s in addition to {{agent}}s verifying the output. + +Configure the following settings: + +1. **In {{fleet}} settings** ({{es}} or {{ls}} output - advanced YAML configuration): + + ```yaml + 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** ({{es}} or {{ls}}): + * Configure the output to require client certificates + * Ensure the CA used to sign agent certificates is trusted by the output + +::::{note} +For {{es}} outputs, mTLS configuration is done in the output settings. For {{ls}} outputs, mTLS configuration is also done in the output settings, but you might also need to configure {{ls}} itself to require client certificates. + +For more information, refer to [Mutual TLS connection](/reference/fleet/mutual-tls.md#mutual-tls-on-premise) and [Secure {{ls}} connections](/reference/fleet/secure-logstash-connections.md). +:::: + +## Best practices [deploy-elastic-agent-best-practices] + +The following sections provide best practices for deploying and managing {{agent}}: + +### Certificate management [deploy-elastic-agent-best-practices-certs] + +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](/reference/fleet/certificates-rotation.md). + +### Configuration management [deploy-elastic-agent-best-practices-config] + +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 {{agent}}s, use environment variables to provide host-specific settings while keeping policies generic. + +### Security considerations [deploy-elastic-agent-best-practices-security] + +Follow these security best practices: + +* Use mutual TLS for both {{agent}} to {{fleet-server}} and {{fleet-server}} to {{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 {{agent}} versions up to date to benefit from security patches. + +## Next steps [deploy-elastic-agent-next] + +After deploying {{agent}}, you can: + +* [Manage {{agent}}s in {{fleet}}](/reference/fleet/manage-elastic-agents-in-fleet.md) to monitor and update agent configurations +* [Monitor {{agent}}](/reference/fleet/monitor-elastic-agent.md) to ensure it's running correctly +* [Upgrade {{agent}}](/reference/fleet/upgrade-elastic-agent.md) to later versions +* Review [{{agent}} environment variables](/reference/fleet/agent-environment-variables.md) (for containerized deployments) \ No newline at end of file diff --git a/reference/fleet/deploy-fleet-server.md b/reference/fleet/deploy-fleet-server.md new file mode 100644 index 0000000000..bb30bbfe89 --- /dev/null +++ b/reference/fleet/deploy-fleet-server.md @@ -0,0 +1,312 @@ +--- +navigation_title: How to deploy Fleet Server +mapped_pages: + - https://www.elastic.co/guide/en/fleet/current/deploy-fleet-server.html +applies_to: + stack: ga +products: + - id: fleet + - id: elastic-agent +--- + +# How to deploy {{fleet-server}} [deploy-fleet-server] + +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}}](/reference/fleet/add-fleet-server-on-prem.md) +* [Deploy {{fleet-server}} on {{k8s}}](/reference/fleet/add-fleet-server-kubernetes.md) +* [Deploy {{fleet-server}} on {{ecloud}}](/reference/fleet/add-fleet-server-cloud.md) +* [Deploy {{fleet-server}} in a mixed environment](/reference/fleet/add-fleet-server-mixed.md) + +## Prerequisites [deploy-fleet-server-prereq] + +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 {{es}} +* TLS certificates (for production deployments) +* Network connectivity between {{fleet-server}} and {{es}}, and between {{agent}}s and {{fleet-server}} + +For more information about prerequisites, refer to the platform-specific deployment guides listed above. + +## Configuration overview [deploy-fleet-server-config-overview] + +{{fleet-server}} requires configuration for two main connection types: + +* [Configuration for {{fleet-server}} to communicate with {{es}}](#deploy-fleet-server-fs-to-es) +* [Configuration for {{fleet-server}} to accept connections from {{agent}}s (server-side)](#deploy-fleet-server-ea-to-fs) + +The following sections organize all configuration flags and environment variables by connection type. + +## {{fleet-server}} to {{es}} [deploy-fleet-server-fs-to-es] + +These settings configure how {{fleet-server}} connects to {{es}}. + +### CLI flags [deploy-fleet-server-fs-to-es-cli] + +The following CLI flags are available for configuring the connection from {{fleet-server}} to {{es}}: + +| Flag | Purpose | Required | Can be overridden by policy? | +| --- | --- | --- | --- | +| `--fleet-server-es` | {{es}} URL where {{fleet-server}} should connect | Yes | Yes - configured in {{es}} output associated with the policy | +| `--fleet-server-es-ca` | Path to CA certificate to validate {{es}} certificate | Optional* | Yes - configured in {{es}} output | +| `--fleet-server-es-ca-trusted-fingerprint` | SHA-256 fingerprint of CA used to sign {{es}} certificates | Optional* | No - must be CLI | +| `--fleet-server-es-cert` | Client certificate for mTLS connection to {{es}} | Optional (mTLS only) | Yes - configured in {{es}} output | +| `--fleet-server-es-cert-key` | Private key for mTLS client certificate | Optional (mTLS only) | Yes - configured in {{es}} output | +| `--fleet-server-es-insecure` | Deactivate certificate verification (not recommended) | No - not recommended | No - must be CLI | +| `--fleet-server-service-token` | Service token for {{fleet-server}} to authenticate with {{es}} | Yes | No - must be CLI or environment variable | +| `--fleet-server-service-token-path` | Path to file containing service token | Yes** | No - must be CLI or environment variable | + +\* Required if {{es}} uses certificates signed by a private or intermediate CA not publicly trusted +\** Mutually exclusive with `--fleet-server-service-token` + +### Environment variables [deploy-fleet-server-fs-to-es-env] + +You can also configure the connection using environment variables instead of CLI flags: + +| Environment Variable | Purpose | CLI Flag Equivalent | Can be overridden by policy? | +| --- | --- | --- | --- | +| `FLEET_SERVER_ELASTICSEARCH_HOST` | {{es}} host URL | `--fleet-server-es` | Yes - configured in {{es}} output | +| `FLEET_SERVER_ELASTICSEARCH_CA` | Path to CA certificate | `--fleet-server-es-ca` | Yes - configured in {{es}} output | +| `FLEET_SERVER_ES_CERT` | Path to client certificate for mTLS | `--fleet-server-es-cert` | Yes - configured in {{es}} output | +| `FLEET_SERVER_ES_CERT_KEY` | Path to private key for mTLS | `--fleet-server-es-cert-key` | Yes - configured in {{es}} output | +| `FLEET_SERVER_SERVICE_TOKEN` | Service token value | `--fleet-server-service-token` | No - must be CLI or environment variable | +| `FLEET_SERVER_SERVICE_TOKEN_PATH` | Path to service token file | `--fleet-server-service-token-path` | No - must be CLI or environment variable | + +::::{important} +The {{es}} host URL and CA information must be configured in both the {{es}} output associated with the {{fleet-server}} policy AND in the environment variables or CLI flags provided during {{fleet-server}} installation. The environment variables are only used during the bootstrap process. After bootstrap, the {{fleet-server}} uses the configuration from the policy's {{es}} output. + +If the URL that {{fleet-server}} will use to access {{es}} is different from the {{es}} URL used by other clients, create a dedicated {{es}} output for {{fleet-server}}. +:::: + +### One-way TLS configuration [deploy-fleet-server-fs-to-es-one-way] + +For one-way TLS ({{fleet-server}} validates {{es}} certificate, but {{es}} does not validate {{fleet-server}}), use the following command: + +```shell +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 +``` + +### Mutual TLS configuration [deploy-fleet-server-fs-to-es-mtls] + +For mutual TLS (both {{fleet-server}} and {{es}} validate each other's certificates), use the following command: + +```shell +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 +``` + +::::{note} +When configuring mTLS for {{fleet-server}} to {{es}}, you must also configure the corresponding settings in the {{es}} output in {{fleet}} settings. For more information, refer to [Output SSL options](/reference/fleet/tls-overview.md#output-ssl-options). +:::: + +## {{agent}} to {{fleet-server}} [deploy-fleet-server-ea-to-fs] + +These settings configure how {{fleet-server}} accepts connections from {{agent}}s (server-side). + +### CLI flags [deploy-fleet-server-ea-to-fs-cli] + +The following CLI flags are available for configuring how {{fleet-server}} accepts connections from {{agent}}s: + +| Flag | Purpose | Required | Can be overridden by policy? | +| --- | --- | --- | --- | +| `--fleet-server-cert` | TLS certificate {{fleet-server}} presents to {{agent}}s | Optional* | Yes - configured in {{fleet}} settings | +| `--fleet-server-cert-key` | Private key for {{fleet-server}} certificate | Optional* | Yes - configured in {{fleet}} settings | +| `--fleet-server-cert-key-passphrase` | Path to passphrase file for encrypted private key | Optional | Yes - configured in {{fleet}} settings | +| `--certificate-authorities` | CA certificates to validate {{agent}} client certificates (for mTLS) | Optional (mTLS only) | Yes - configured in {{fleet}} settings | +| `--fleet-server-client-auth` | Client authentication mode: `none`, `optional`, or `required` | Optional | Yes - configured in {{fleet}} settings | +| `--fleet-server-host` | Binding host for {{fleet-server}} HTTP endpoint | Optional | Yes - configured in {{fleet-server}} integration policy | +| `--fleet-server-port` | Binding port for {{fleet-server}} HTTP endpoint | Optional | Yes - configured in {{fleet-server}} integration policy | +| `--fleet-server-timeout` | Timeout waiting for {{fleet-server}} to be ready | Optional | No - must be CLI or environment variable | + +\* If not specified, {{fleet-server}} auto-generates a self-signed certificate. This is not recommended for production. + +### Environment variables [deploy-fleet-server-ea-to-fs-env] + +You can also configure these settings using environment variables instead of CLI flags: + +| Environment Variable | Purpose | CLI Flag Equivalent | Can be overridden by policy? | +| --- | --- | --- | --- | +| `FLEET_SERVER_CERT` | Path to TLS certificate | `--fleet-server-cert` | Yes - configured in {{fleet}} settings | +| `FLEET_SERVER_CERT_KEY` | Path to private key | `--fleet-server-cert-key` | Yes - configured in {{fleet}} settings | +| `FLEET_SERVER_CERT_KEY_PASSPHRASE` | Path to passphrase file | `--fleet-server-cert-key-passphrase` | Yes - configured in {{fleet}} settings | +| `FLEET_CA` | Path to CA certificate for validating agent certificates | `--certificate-authorities` | Yes - configured in {{fleet}} settings | +| `FLEET_SERVER_CLIENT_AUTH` | Client authentication mode | `--fleet-server-client-auth` | Yes - configured in {{fleet}} settings | +| `FLEET_SERVER_HOST` | Binding host | `--fleet-server-host` | Yes - configured in {{fleet-server}} integration | +| `FLEET_SERVER_PORT` | Binding port | `--fleet-server-port` | Yes - configured in {{fleet-server}} integration | +| `FLEET_SERVER_TIMEOUT` | Timeout for {{fleet-server}} readiness | `--fleet-server-timeout` | No - must be CLI or environment variable | +| `FLEET_URL` | URL that {{fleet-server}} uses to access itself during bootstrap | N/A | No - must be CLI or environment variable | + +::::{important} +The `FLEET_URL` environment variable is used by {{fleet-server}} during its bootstrap process to access its own endpoint. This URL must match the hostname used in the {{fleet-server}} certificate's Subject Alternative Name (SAN) list. In {{k8s}} environments, if the service is not immediately available, you might need to use `https://localhost:8220` and ensure `localhost` is included in the certificate's SAN. +:::: + +### One-way TLS configuration [deploy-fleet-server-ea-to-fs-oneway] + +For one-way TLS ({{agent}}s validate {{fleet-server}} certificate, but {{fleet-server}} does not validate {{agent}} certificates), use the following command: + +```shell +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 +``` + +### Mutual TLS configuration [deploy-fleet-server-ea-to-fs-mtls] + +For mutual TLS (both {{fleet-server}} and {{agent}}s validate each other's certificates), use the following command: + +```shell +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 +``` + +::::{note} +When `--fleet-server-client-auth` is set to `optional` or `required`, {{fleet-server}} will verify client certificates presented by {{agent}}s using the CA certificates specified in `--certificate-authorities`. The {{agent}}s must be enrolled with the corresponding client certificates using `--elastic-agent-cert` and `--elastic-agent-cert-key` flags. For more information, refer to [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md). +:::: + +## Policy and CLI precedence [deploy-fleet-server-policy-precedence] + +Understanding what can be configured using policy versus what must be provided using CLI or environment variables is crucial for managing {{fleet-server}} deployments. + +### Must be provided using CLI or environment variables [deploy-fleet-server-must-cli] + +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` +* **{{es}} 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) + +### Can be overridden by policy [deploy-fleet-server-can-override] + +The following settings can be set using CLI during installation, but can also be updated using policy after enrollment: + +* **{{es}} connection settings**: Configured in the {{es}} output associated with the {{fleet-server}} policy + * {{es}} host URL + * {{es}} CA certificate + * mTLS client certificate and key for {{es}} +* **{{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 + +### Configuration hierarchy [deploy-fleet-server-config-hierarchy] + +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](#deploy-fleet-server-must-cli) section above). + +## Mutual TLS (mTLS) configuration [deploy-fleet-server-mtls] + +Mutual TLS provides enhanced security by requiring both parties in a connection to authenticate using certificates. + +### mTLS between {{fleet-server}} and {{es}} [deploy-fleet-server-mtls-fs-es] + +Use this option when you need {{es}} to verify the identity of {{fleet-server}} in addition to {{fleet-server}} verifying {{es}}. + +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 {{es}} certificate + +2. **In {{fleet}} settings** ({{es}} 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 {{es}} certificate + +For more information, refer to [Mutual TLS connection](/reference/fleet/mutual-tls.md#mutual-tls-on-premise). + +### mTLS between {{agent}} and {{fleet-server}} [deploy-fleet-server-mtls-ea-fs] + +Use this option when you need {{fleet-server}} to verify the identity of connecting {{agent}}s in addition to {{agent}}s 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 {{agent}} enrollment** (CLI or environment variables): + * `--elastic-agent-cert` / `ELASTIC_AGENT_CERT`: Client certificate for {{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](/reference/fleet/mutual-tls.md#mutual-tls-on-premise) and [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md). + +## Best practices [deploy-fleet-server-best-practices] + +The following sections provide best practices for deploying and managing {{fleet-server}}: + +### Certificate management [deploy-fleet-server-best-practices-certs] + +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 {{agent}}s 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](/reference/fleet/certificates-rotation.md). + +### Configuration management [deploy-fleet-server-best-practices-config] + +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 {{es}} connection settings than other agents, create a dedicated {{es}} output for {{fleet-server}}. + +### Security considerations [deploy-fleet-server-best-practices-security] + +Follow these security best practices: + +* Use mutual TLS for both {{fleet-server}} to {{es}} and {{agent}} to {{fleet-server}} connections in high-security environments. +* Always use service tokens for {{fleet-server}} authentication with {{es}}. Never use basic authentication credentials. +* Consider network segmentation to limit which hosts can connect to {{fleet-server}}. +* Keep {{fleet-server}} and {{agent}} versions up to date to benefit from security patches. + +## Next steps [deploy-fleet-server-next] + +After deploying {{fleet-server}}, you can: + +* [Deploy {{agents}}](/reference/fleet/deploy-elastic-agent.md) to connect to your {{fleet-server}} +* [Monitor {{fleet-server}}](/reference/fleet/fleet-server-monitoring.md) to ensure it's running correctly +* [Scale {{fleet-server}}](/reference/fleet/fleet-server-scalability.md) as your deployment grows +* Review [{{fleet-server}} secrets management](/reference/fleet/fleet-server-secrets.md) for secure credential handling + diff --git a/reference/fleet/deployment-models.md b/reference/fleet/deployment-models.md index f8cd7fb99b..3749fa092e 100644 --- a/reference/fleet/deployment-models.md +++ b/reference/fleet/deployment-models.md @@ -1,6 +1,8 @@ --- mapped_pages: - https://www.elastic.co/guide/en/fleet/current/fleet-deployment-models.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -23,7 +25,7 @@ The requirements for setting up {{fleet-server}} differ, depending on your parti {{ech}} with {{fleet-server}} on-premise : When you use an {{ech}} deployment you may still choose to run {{fleet-server}} on-premise. For details about this deployment model and set up instructions, refer to [Deploy {{fleet-server}} on-premises and {{es}} on Cloud](/reference/fleet/add-fleet-server-mixed.md). -Docker and Kubernetes +Docker and {{k8s}} : You can deploy {{fleet}}-managed {{agent}} in Docker or on Kubernetes. Refer to [Run {{agent}} in a container](/reference/fleet/elastic-agent-container.md) or [Run {{agent}} on Kubernetes managed by {{fleet}}](/reference/fleet/running-on-kubernetes-managed-by-fleet.md) for all of the configuration instructions. For a Kubernetes install we also have a [Helm chart](/reference/fleet/install-on-kubernetes-using-helm.md) available to simplify the installation. Details for configuring {{fleet-server}} are included with the {{agent}} install steps. {{eck}} diff --git a/reference/fleet/install-fleet-managed-elastic-agent.md b/reference/fleet/install-fleet-managed-elastic-agent.md index beedd529b3..4e966c7ef7 100644 --- a/reference/fleet/install-fleet-managed-elastic-agent.md +++ b/reference/fleet/install-fleet-managed-elastic-agent.md @@ -1,6 +1,8 @@ --- mapped_pages: - https://www.elastic.co/guide/en/fleet/current/install-fleet-managed-elastic-agent.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -13,6 +15,10 @@ products: :::: +::::{note} +For comprehensive information about {{agent}} configuration flags, environment variables, mutual TLS (mTLS) setup, and policy versus CLI precedence, refer to [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md). This guide provides detailed configuration organized by connection type. +:::: + ## Where to start [get-started] @@ -35,9 +41,9 @@ You will always need: * **[{{fleet-server}}](/reference/fleet/fleet-server.md) running in a location accessible to {{agent}}.** {{agent}} must have a direct network connection to {{fleet-server}} and {{es}}. If you’re using {{ecloud}}, {{fleet-server}} is already available as part of the {{integrations-server}}. For self-managed deployments, refer to [Deploy on-premises and self-managed](/reference/fleet/add-fleet-server-on-prem.md). * **Internet connection for {{kib}} to download integration packages from the {{package-registry}}.** Make sure the {{kib}} server can connect to `https://epr.elastic.co` on port `443`. If your environment has network traffic restrictions, there are ways to work around this requirement. See [Air-gapped environments](/reference/fleet/air-gapped.md) for more information. -If you are using a {{fleet-server}} that uses your organization’s certificate, you will also need: +If you are using a {{fleet-server}} that uses your organization's certificate, you will also need: -* **A Certificate Authority (CA) certificate to configure Transport Layer Security (TLS) to encrypt traffic.** If your organization already uses the {{stack}}, you may already have a CA certificate. If you do not have a CA certificate, you can read more about generating one in [Configure SSL/TLS for self-managed {{fleet-server}}s](/reference/fleet/secure-connections.md). +* **A Certificate Authority (CA) certificate to configure Transport Layer Security (TLS) to encrypt traffic.** If your organization already uses the {{stack}}, you may already have a CA certificate. If you do not have a CA certificate, you can read more about generating one in [Configure SSL/TLS for self-managed {{fleet-server}}s](/reference/fleet/secure-connections.md). For detailed information about configuring TLS and mTLS connections for {{agent}}, refer to [How to deploy Elastic Agent](/reference/fleet/deploy-elastic-agent.md). If you’re running {{agent}} 7.9 or earlier, stop the agent and manually remove it from your host. @@ -66,7 +72,7 @@ To install an {{agent}} and enroll it in {{fleet}}: 3. Make sure **Enroll in Fleet** is selected. 4. Download, install, and enroll the {{agent}} on your host by selecting your host operating system and following the **Install {{agent}} on your host** step. The commands shown are for AMD platforms, but ARM packages are also available. Refer to the {{agent}} [downloads page](https://www.elastic.co/downloads/elastic-agent) for the full list of available packages. - 1. If you are enrolling the agent in a {{fleet-server}} that uses your organization’s certificate you *must* add the `--certificate-authorities` option to the command provided in the in-product instructions. If you do not include the certificate, you will see the following error: "x509: certificate signed by unknown authority". + 1. If you are enrolling the agent in a {{fleet-server}} that uses your organization's certificate you *must* add the `--certificate-authorities` option to the command provided in the in-product instructions. If you do not include the certificate, you will see the following error: "x509: certificate signed by unknown authority". For comprehensive information about all available configuration flags and environment variables, refer to [How to deploy Elastic Agent](/reference/fleet/deploy-elastic-agent.md). 2. Beginning with version 9.0, {{agent}} packages are available in multiple flavors. The default, "basic" flavor contains the components required for most use data collection use cases. A "servers" flavor is also available with additional components. You can adjust the `elastic-agent install` command as required to choose a different flavor. Refer to [{{agent}} installation flavors](./install-elastic-agents.md#elastic-agent-installation-flavors) for details. diff --git a/reference/fleet/mutual-tls.md b/reference/fleet/mutual-tls.md index 35e6f6d9f4..66576f5b69 100644 --- a/reference/fleet/mutual-tls.md +++ b/reference/fleet/mutual-tls.md @@ -1,6 +1,8 @@ --- mapped_pages: - https://www.elastic.co/guide/en/fleet/current/mutual-tls.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -8,7 +10,11 @@ products: # Elastic Agent deployment models with mutual TLS [mutual-tls] -Mutual Transport Layer Security (mTLS) provides a higher level of security and trust compared to one-way TLS, where only the server presents a certificate. It ensures that not only the server is who it claims to be, but the client is also authenticated. This is particularly valuable in scenarios where both parties need to establish trust and validate each other’s identities, such as in secure API communication, web services, or remote authentication. +Mutual Transport Layer Security (mTLS) provides a higher level of security and trust compared to one-way TLS, where only the server presents a certificate. It ensures that not only the server is who it claims to be, but the client is also authenticated. This is particularly valuable in scenarios where both parties need to establish trust and validate each other's identities, such as in secure API communication, web services, or remote authentication. + +For comprehensive deployment information including all mTLS configuration flags, environment variables, and setup instructions organized by connection type, refer to: +- [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md) - includes mTLS configuration for {{fleet-server}} to {{es}} and {{agent}} to {{fleet-server}} (server-side) +- [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md) - includes mTLS configuration for {{agent}} to {{fleet-server}} and {{agent}} to {{es}}/{{ls}} For a summary of flow by which TLS is established between components using either one-way or mutual TLS, refer to [One-way and mutual TLS certifications flow](/reference/fleet/tls-overview.md). @@ -40,8 +46,7 @@ When mTLS is required, the secure setup between {{agent}}, {{fleet}}, and {{flee 2. The initial mTLS connection between {{agent}} and {{fleet-server}} is configured when {{agent}} is enrolled, using the parameters passed through the `elastic-agent install` or `elastic-agent enroll` command. 3. Once enrollment has completed, {{agent}} downloads the initial {{agent}} policy from {{fleet-server}}. - 1. If the {{agent}} policy contains mTLS configuration settings, those settings will take precedence over those used during enrollment: This includes both the mTLS settings used for connectivity between {{agent}} and {{fleet-server}} (and the {{fleet}} application in {{kib}}, for {{fleet}}-managed {{agent}}), and the settings used between {{agent}} and it’s specified output. - 2. If the {{agent}} policy does not contain any TLS, mTLS, or proxy configuration settings, these settings will remain as they were specified when {{agent}} enrolled. The initial TLS, mTLS, or proxy configuration settings can not be removed through the {{agent}} policy; they can only be updated. +For information about policy and CLI precedence for mTLS configuration, refer to [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md#deploy-elastic-agent-policy-precedence) and [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md#deploy-fleet-server-policy-precedence). ::::{important} @@ -65,7 +70,7 @@ During {{agent}} installation on premise use the following options: | | | | --- | --- | -| `--certificate-authorities` | List of CA certificates that are trusted when {{fleet-server}} connects to {{agent}} | +| `--certificate-authorities` | List of CA certificates that are trusted when {{agent}} connects to {{fleet-server}} | | `--elastic-agent-cert` | {{agent}} certificate to present to {{fleet-server}} during authentication | | `--elastic-agent-cert-key` | {{agent}} certificate key to present to {{fleet-server}} | | `--elastic-agent-cert-key-passphrase` | The path to the file that contains the passphrase for the mutual TLS private key that {{agent}} will use to connect to {{fleet-server}} | diff --git a/reference/fleet/secure-connections.md b/reference/fleet/secure-connections.md index 397c4f5118..29d4568030 100644 --- a/reference/fleet/secure-connections.md +++ b/reference/fleet/secure-connections.md @@ -1,6 +1,8 @@ --- mapped_pages: - https://www.elastic.co/guide/en/fleet/current/secure-connections.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -8,7 +10,11 @@ products: # Configure SSL/TLS for self-managed Fleet Servers [secure-connections] -If you’re running a self-managed cluster, configure Transport Layer Security (TLS) to encrypt traffic between {{agent}}s, {{fleet-server}}, and other components in the {{stack}}. +If you're running a self-managed cluster, configure Transport Layer Security (TLS) to encrypt traffic between {{agent}}s, {{fleet-server}}, and other components in the {{stack}}. + +For comprehensive deployment information including all configuration flags, environment variables, and mTLS setup organized by connection type, refer to: +- [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md) +- [How to deploy Elastic Agent](/reference/fleet/deploy-elastic-agent.md) For the install settings specific to mutual TLS, as opposed to one-way TLS, refer to [{{agent}} deployment models with mutual TLS](/reference/fleet/mutual-tls.md). @@ -87,6 +93,10 @@ This section describes how to use the `certutil` tool provided by {{es}}, but yo Use the CLI to configure SSL or TLS when installing or enrolling {{fleet-server}}. This method gives you granular control over certificate paths, verification modes, and authentication behavior. +::::{note} +For comprehensive information about all available CLI flags and environment variables organized by connection type, refer to [How to deploy {{fleet-server}}](/reference/fleet/deploy-fleet-server.md) and [How to deploy {{agent}}](/reference/fleet/deploy-elastic-agent.md). +:::: + ### Encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}} [_encrypt_traffic_between_agents_fleet_server_and_es] {{fleet-server}} needs a CA certificate or the CA fingerprint to connect securely to {{es}}. It also needs to expose a {{fleet-server}} certificate so other {{agent}}s can connect to it securely. @@ -168,11 +178,6 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: The following command installs {{agent}} as a service, enrolls it in the {{fleet-server}} policy, and starts the service. - ::::{note} - If you’re using DEB or RPM, or already have the {{agent}} installed, use the `enroll` command along with the following options, then start the service as described in [Start {{agent}}](/reference/fleet/start-stop-elastic-agent.md#start-elastic-agent-service). - :::: - - ```shell sudo ./elastic-agent install \ --url=https://192.0.2.1:8220 \ @@ -192,55 +197,6 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: --fleet-server-client-auth=required ``` - Where: - - `url` - : {{fleet-server}} URL. - - `fleet-server-es` - : {{es}} URL - - `fleet-server-service-token` - : Service token to use to communicate with {{es}}. - - `fleet-server-policy` - : The specific policy that {{fleet-server}} will use. - - `fleet-server-es-ca` - : CA certificate that the current {{fleet-server}} uses to connect to {{es}}. - - `certificate-authorities` - : List of paths to PEM-encoded CA certificate files that should be trusted for the other {{agents}} to connect to this {{fleet-server}} - - `fleet-server-cert` - : The path for the PEM-encoded certificate (or certificate chain) which is associated with the fleet-server-cert-key to expose this {{fleet-server}} HTTPS endpoint to the other {{agents}} - - `fleet-server-cert-key` - : Private key to use to expose this {{fleet-server}} HTTPS endpoint to the other {{agents}} - - `elastic-agent-cert` - : The certificate to use as the client certificate for {{agent}}'s connections to {{fleet-server}}. - - `elastic-agent-cert-key` - : The path to the private key to use as for {{agent}}'s connections to {{fleet-server}}. - - `elastic-agent-cert-key-passphrase` - : 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. This option is only used if the `elastic-agent-cert-key` is encrypted and requires a passphrase to use. - - `fleet-server-es-cert` - : The path to the client certificate that {{fleet-server}} will use when connecting to {{es}}. - - `fleet-server-es-cert-key` - : The path to the private key that {{fleet-server}} will use when connecting to {{es}}. - - `fleet-server-client-auth` - : One of `none`, `optional`, or `required`. Defaults to `none`. {{fleet-server}}'s client_authentication option for client mTLS connections. If `optional` or `required` is specified, client certificates are verified using CAs specified in the `--certificate-authorities` flag. - - Additionally an optional passphrase for the private key may be specified with: - - `fleet-server-cert-key-passphrase` - : Passphrase file used to decrypt {{fleet-server}}'s private key. - What happens if you enroll {{fleet-server}} without specifying certificates? If the certificates are managed by your organization and installed at the system level, they will be used to encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}. If system-level certificates don’t exist, {{fleet-server}} automatically generates self-signed certificates. Traffic between {{fleet-server}} and {{agent}}s over HTTPS is encrypted, but the certificate chain cannot be verified. Any {{agent}}s enrolling in {{fleet-server}} will need to pass the `--insecure` flag to acknowledge that the certificate chain is not verified. @@ -259,18 +215,7 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: --certificate-authorities=/path/to/ca.crt ``` - Where: - - `url` - : {{fleet-server}} URL to use to enroll the {{agent}} into {{fleet}}. - - `enrollment-token` - : The enrollment token for the policy that will be applied to the {{agent}}. - - `certificate-authorities` - : CA certificate to use to connect to {{fleet-server}}. This is the CA used to [generate a certificate and key](#generate-fleet-server-certs) for {{fleet-server}}. - - Don’t have an enrollment token? On the **Agents** tab in {{fleet}}, select **Add agent**. Under **Enroll and start the Elastic Agent**, follow the in-product installation steps, making sure that you add the `--certificate-authorities` option before you run the command. + Don't have an enrollment token? On the **Agents** tab in {{fleet}}, select **Add agent**. Under **Enroll and start the Elastic Agent**, follow the in-product installation steps, making sure that you add the `--certificate-authorities` option before you run the command. ## Configure SSL/TLS using {{kib}} [fleet-server-ssl-ui-settings] diff --git a/reference/fleet/toc.yml b/reference/fleet/toc.yml index fe02ce3623..a295228285 100644 --- a/reference/fleet/toc.yml +++ b/reference/fleet/toc.yml @@ -8,6 +8,7 @@ toc: - file: deployment-models.md children: - file: fleet-server.md + - file: deploy-fleet-server.md - file: add-fleet-server-cloud.md - file: add-fleet-server-on-prem.md - file: add-fleet-server-mixed.md @@ -20,6 +21,7 @@ toc: - file: install-elastic-agents.md children: - file: fleet-agent-release-process.md + - file: deploy-elastic-agent.md - file: install-fleet-managed-elastic-agent.md - file: install-standalone-elastic-agent.md children: