Repository navigation
[Internal]: Document how to add S3-compatible repository CA certificate to the JVM-wide truststore #8493
Description
Description
The S3 repository docs state:
By default Elasticsearch communicates with your storage system using HTTPS, and validates the repository's certificate chain using the JVM-wide truststore. Ensure that the JVM-wide truststore includes an entry for your repository.
This tells users what they need to do but not how to do it. There are no steps showing how to actually import a repository's CA certificate into the JVM-wide truststore. This is a common gap for users connecting to self-hosted or on-prem S3-compatible storage (e.g., MinIO, Ceph) that use a private/internal CA, since without these steps Elasticsearch will fail certificate validation against the repository.
Requesting that the docs add a procedure covering:
-
Back up the existing cacerts file (i.e. truststore) first, e.g.:
cp /usr/share/elasticsearch/jdk/lib/security/cacerts /usr/share/elasticsearch/jdk/lib/security/cacerts.bkp -
Importing the repository's CA certificate into the JVM truststore (cacerts) using keytool:
/usr/share/elasticsearch/jdk/bin/keytool -keystore /usr/share/elasticsearch/jdk/lib/security/cacerts -storepass changeit -noprompt -importcert -file ca.crt -alias s3cacert -trustcacerts -
Updating jvm.options if the truststore password differs from the default:
-Djavax.net.ssl.trustStore=/usr/share/elasticsearch/jdk/lib/security/cacerts -Djavax.net.ssl.keyStorePassword=changeit -
Confirm the certificate was imported correctly:
keytool -list -v -keystore /usr/share/elasticsearch/jdk/lib/security/cacerts -storepass changeit -alias s3cacert -
This change must be applied on every node in the cluster and requires a node restart to take effect.
Resources
Existing doc section: https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore/s3-repository#repository-s3-compatible-services
Related: JVM cacerts truststore is bundled with the Elasticsearch-provided JDK at $ES_HOME/jdk/lib/security/cacerts
Which deployment methods does this change impact?
Elastic On-Prem only (ECE, ECK, or self-managed)
Feature differences
No response
What Elastic Stack release is this request related to?
N/A
Serverless release
No response
Collaboration model
The documentation team will create the first draft
Point of contact.
Main contact:
Stakeholders:
Activity
github-actions commentedon Sep 23, 2026
Elastic Docs AI Menu
Check one box to run an AI workflow for this issue.
docs-scope). Status: not started.Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.
eedugon commentedon Oct 22, 2026
There are multiple use cases where the user needs to customize the default JVM trust store, and we have recently documented some.
Customizing the JVM truststore is something that the user can do in self-managed, ECK, and ECE.
Let's consider this opportunity to create a new good base document to update the JVM trust store for all deployment types, and link to that from the S3 document where applicable, instead of adding a procedure in an already long document that has nothing to do with snapshots or S3 repositories.
Last PR example: #8758 where we documented this in a very nice way: https://www.elastic.co/docs/explore-analyze/elastic-inference/external-inference-private-ca
Note that the latest PR suggests using a new file instead of overriding the JVM
cacerts, in order to not lose the changes after an upgrade.georgewallace commentedon Oct 29, 2026
Related to #9040. Determine if this should be closed and merged into the other issue.