Elasticsearch client certificate authentication on ECK

For how ECK secures HTTP traffic and manages TLS certificates, see Manage TLS certificates on ECK.

You can configure Elasticsearch to require client certificates for HTTP authentication, enabling mutual TLS (mTLS) between clients and Elasticsearch. When enabled, clients must present a valid certificate signed by a trusted CA to communicate with Elasticsearch.

To enable client certificate authentication on Elasticsearch, set spec.http.tls.client.authentication to true:

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: quickstart
spec:
  version: 9.5.6
  nodeSets:
  - name: default
    count: 3
  http:
    tls:
      client:
        authentication: true

When client authentication is enabled, ECK sets xpack.security.http.ssl.client_authentication: required in the Elasticsearch configuration.

The supported Elastic Stack components differ by version. ECK performs the following additional steps depending on your version:

• ECK 3.5+ Elastic Cloud on Kubernetes extends Kubernetes orchestration capabilities to allow you to deploy and manage components of the Elastic Stack. Availability Generally available since 3.5 This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Automatically generates and manages client certificates for all Elastic Stack components that connect to Elasticsearch, including stack monitoring sidecars and the AutoOps agent, configuring each to present its certificate when connecting to Elasticsearch.

  Note

  Fleet Server requires version 8.13.0 or later. If the version is below 8.13.0, ECK blocks pod reconciliation and sets the agent status to red with a warning event.

• ECK 3.4 Elastic Cloud on Kubernetes extends Kubernetes orchestration capabilities to allow you to deploy and manage components of the Elastic Stack. Availability Generally available in 3.4 This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. The only supported component is Kibana. ECK automatically generates and manages a client certificate for it, configuring it to present its certificate when connecting to Elasticsearch. Other workloads that connect to Elasticsearch over HTTP are not configured automatically.

  Note

  If you have manually set xpack.security.http.ssl.client_authentication in spec.nodeSets[*].config, that value takes precedence over the ECK-managed setting and the mTLS configuration may not apply as expected.

For Fleet Server acting as the mTLS endpoint (requiring client certificates from connecting Elastic Agents), see Fleet Server client certificate authentication.

ECK automatically issues a client certificate to each component. To use your own certificate instead, set clientCertificateSecretName in the component's elasticsearchRef. When you provide a custom certificate, ECK automatically configures Elasticsearch to trust it — no additional trust configuration is required.

The referenced secret must contain tls.crt and tls.key entries:

apiVersion: v1
kind: Secret
metadata:
  name: my-custom-client-cert
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded certificate>
  tls.key: <base64-encoded private key>

Set clientCertificateSecretName in the elasticsearchRef of the Kibana resource:

apiVersion: kibana.k8s.elastic.co/v1
kind: Kibana
metadata:
  name: quickstart
spec:
  version: 9.5.6
  count: 1
  elasticsearchRef:
    name: quickstart
    clientCertificateSecretName: my-custom-client-cert

Set clientCertificateSecretName in the elasticsearchRef of the APM Server resource:

apiVersion: apm.k8s.elastic.co/v1
kind: ApmServer
metadata:
  name: quickstart
spec:
  version: 9.5.6
  count: 1
  elasticsearchRef:
    name: quickstart
    clientCertificateSecretName: my-custom-client-cert

Set clientCertificateSecretName in the elasticsearchRef of the Beats resource:

apiVersion: beat.k8s.elastic.co/v1beta1
kind: Beat
metadata:
  name: quickstart
spec:
  type: filebeat
  version: 9.5.6
  elasticsearchRef:
    name: quickstart
    clientCertificateSecretName: my-custom-client-cert

Set clientCertificateSecretName in the elasticsearchRef of the Enterprise Search resource:

apiVersion: enterprisesearch.k8s.elastic.co/v1
kind: EnterpriseSearch
metadata:
  name: quickstart
spec:
  version: 9.5.6
  count: 1
  elasticsearchRef:
    name: quickstart
    clientCertificateSecretName: my-custom-client-cert

Set clientCertificateSecretName in the elasticsearchRef of the Elastic Maps Server resource:

apiVersion: maps.k8s.elastic.co/v1alpha1
kind: ElasticMapsServer
metadata:
  name: quickstart
spec:
  version: 9.5.6
  count: 1
  elasticsearchRef:
    name: quickstart
    clientCertificateSecretName: my-custom-client-cert

Logstash supports multiple Elasticsearch references, so clientCertificateSecretName is configured for each entry in elasticsearchRefs:

apiVersion: logstash.k8s.elastic.co/v1alpha1
kind: Logstash
metadata:
  name: quickstart
spec:
  version: 9.5.6
  count: 1
  elasticsearchRefs:
    - clusterName: production
      name: quickstart
      clientCertificateSecretName: my-custom-client-cert

For standalone Elastic Agent, clientCertificateSecretName is configured for each entry in elasticsearchRefs:

apiVersion: agent.k8s.elastic.co/v1alpha1
kind: Agent
metadata:
  name: quickstart
spec:
  version: 9.5.6
  elasticsearchRefs:
    - name: quickstart
      outputName: default
      clientCertificateSecretName: my-custom-client-cert

For Fleet-managed Elastic Agents, Fleet Server automatically propagates the client certificate information to all connected agents. No additional configuration is required.

Fleet Server also connects to Elasticsearch and can be configured with a custom client certificate through elasticsearchRefs:

apiVersion: agent.k8s.elastic.co/v1alpha1
kind: Agent
metadata:
  name: fleet-server
spec:
  version: 9.5.6
  mode: fleet
  fleetServerEnabled: true
  elasticsearchRefs:
    - name: quickstart
      outputName: default
      clientCertificateSecretName: my-custom-client-cert

To turn off client certificate authentication, set spec.http.tls.client.authentication to false or remove it from the Elasticsearch resource:

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: quickstart
spec:
  http:
    tls:
      client:
        authentication: false

ECK handles the transition gracefully, deferring cleanup of mTLS resources until all pods have rolled over to ensure connectivity is maintained throughout the configuration change.