Skip to content

Consolidate docs around customizing default JVM trust store for all deployment types #9040

Open
0 of 1 issue completed

Description

@eedugon

Background

Elasticsearch makes outbound TLS connections for several features. The trust
configuration is not consistent across all of these clients:

  • Some features expose dedicated *.ssl.certificate_authorities or
    *.ssl.truststore.path settings.
  • Other features do not expose feature-specific TLS trust settings and validate
    server certificates using the JVM-wide trust store.

Confirmed consumers of the JVM-wide trust store include:

  • External inference endpoints
  • S3 and S3-compatible snapshot repositories over HTTPS
  • The GeoIP database downloader when using a custom HTTPS endpoint
  • Read-only URL snapshot repositories over HTTPS

Examples of features with dedicated trust settings include remote reindex,
Watcher HTTP and email clients, LDAP/Active Directory/OIDC realms, remote
clusters, and monitoring exporters.

When a JVM-wide consumer connects to an endpoint whose certificate is signed by
a private CA, users must add that CA to the trust store used by the Elasticsearch
JVM. The required instructions are currently distributed across inference,
snapshot, ECK, and ECE documentation, and the documented procedures are not
fully consistent.

A custom trust store configured through javax.net.ssl.trustStore replaces the
default trust store. It should therefore normally start as a copy of the bundled
JDK's cacerts file. Directly modifying the bundled cacerts file is fragile
because Elasticsearch upgrades may replace the bundled JDK.

Proposal

Create a canonical page under Deploy and manage > Security explaining how
to trust private certificate authorities for Elasticsearch outbound TLS
connections that use the JVM-wide trust store.

The page should:

  • Explain when the global JVM trust store is used and when a feature-specific
    certificate_authorities setting should be preferred.
  • List representative consumers of each configuration model.
  • Explain the node-wide security impact.
  • State that the configuration must be applied to every relevant node and
    requires a restart.
  • Explain that hostname verification is still enforced.
  • Document the supported procedures for:
    • Self-managed installations
    • Self-managed Docker deployments
    • Elastic Cloud Enterprise
    • Elastic Cloud on Kubernetes
  • Explain the difference between:
    • Updating the bundled or operating-system trust anchors
    • Creating a separate trust store with the default public CAs plus private CAs
  • Clarify behavior across upgrades.
  • Document the availability or limitation for Elastic Cloud Hosted and
    Serverless.
  • Replace duplicated procedures in feature-specific pages with links to the
    canonical page.

Existing content to consolidate

The ECE page should also be corrected because it currently lists remote reindex
as requiring the JVM trust store, although remote reindex supports
reindex.ssl.certificate_authorities.

Activity

  1. github-actions commented on Oct 27, 2026

    @github-actions
    Contributor

    Elastic Docs AI Menu

    Check one box to run an AI workflow for this issue.

    • Scope the docs work (docs-scope). Status: not started.

    Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

  2. added
    Team:AdminIssues owned by the Admin Docs Team
    triagedTriage has been run on this issue
    and removed
    needs-teamIssues pending triage by the Docs Team
    on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Confidence: 1Scope and value are clearEffort: 0.5~2-3 days (0.5 week)Impact: 3Meaningful improvement or harmReach: 3Common task or moderate surfaceTeam:AdminIssues owned by the Admin Docs TeamtriagedTriage has been run on this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions