docs: add documentation for using custom CA certificates with Jenkins in Docker and Kubernetes

[Piyush0049]

Description

This documentation covers secure ways to add custom CA certificates to Jenkins running in Docker or Kubernetes.

What's Added

Added new documentation page: content/doc/book/installing/_custom-ca-certificates.adoc

This documentation covers three secure approaches for custom CA certificates:

1. Docker Compose with init container (recommended for Docker users)
2. Kubernetes/Helm with init container (for K8s deployments)
3. Custom Dockerfile (for static certificate requirements)

Why This Documentation

This documentation complements security improvements in jenkinsci/docker where we removed the insecure runtime certificate import feature that gave the Jenkins user write access to the system truststore.

Users still need a way to add custom CA certificates for:

• Corporate proxies
• Internal Git/Maven repositories
• Self-signed certificates
• Internal services

This documentation provides secure, tested patterns that maintain the principle of keeping the system truststore immutable and root-owned.

Key Features

✅ Complete working examples for all three approaches
✅ Security-first design - system truststore remains root-owned
✅ Certificate format requirements and conversion examples
✅ Troubleshooting guide for common issues
✅ Security warnings prominently displayed
✅ Links to related resources (Helm charts, Docker images)

Security

All documented approaches maintain security by:

• Keeping the system truststore root-owned and immutable
• Using init containers that run as root to prepare custom truststores
• Mounting prepared truststores as read-only in Jenkins containers
• Never giving the Jenkins user write access to certificate stores

Testing

All examples have been tested and verified:

• Docker Compose example works with official images
• Kubernetes examples compatible with official Helm chart
• Custom Dockerfile builds successfully

Related

• Related discussion in jenkinsci/docker PR (link to your docker PR when it's created)
• Addresses community requests for secure CA certificate handling
• Follows Jenkins documentation standards

Checklist

• Documentation follows jenkins.io style guide
• All code examples are tested
• Security considerations included
• AsciiDoc formatting correct
• Links to external resources included

[lemeurherve]

Ref:

• chore: update CA cert import in README and test jenkinsci/docker#2251 (comment)

[lemeurherve]

@Piyush0049 same as jenkinsci/docker#2251 (comment), please stop merging master branch in your PRs, no need to run again and again CI.

[krisstern]

@dduportal @lemeurherve would it be possible to get some input from you guys on this PR?

[dduportal]

The technical content looks good to me!

The only feedback I have would be to be a bit more clear in the title + introduction that this page is only for Custom CA certificates for Jenkins running in containers (e.g. Docker / Kubernetes).

The reason is that it's far from being the main way to run Jenkins and we don't want non Docker/Kubernetes Jenkins admins to land on this page while they use native Linux packages.

@krisstern It also means that you might want to link this page, once merged, from the the Docker / Kubernetes pages if any (I can't recall the exact documentation page tree)

[Piyush0049]

@dduportal @krisstern I’ve updated the title and intro to clearly scope this to Jenkins running in Docker/Kubernetes containers only. Please let me know if any further changes are required.

[krisstern]

@krisstern It also means that you might want to link this page, once merged, from the the Docker / Kubernetes pages if any (I can't recall the exact documentation page tree)

@dduportal will do

[welcome]

Congratulations on getting your very first jenkins.io pull request merged 🎉🥳

This is a fantastic achievement, and we're thrilled to have you as part of our community! Thank you for your valuable input, and we look forward to seeing more of your contributions in the future!

We would like to invite you to join the community chats and forums to meet other Jenkins contributors 😊
Don't forget to check out the participation page to learn more about how to contribute to Jenkins.

[Piyush0049]

Thank you so much for the reviews, guidance, and merge! I learned a lot from this PR and really appreciate everyone’s help.

[krisstern]

@Piyush0049 that's good to know. If you are interested you can link this up to both the Docker and Kubernetes documentation, that is the last step to make your work here visible.

[Piyush0049]

Definitely, I’m working on it.

[krisstern]

That's great! We appreciate it

[Piyush0049]

I’ve opened a new PR for the follow-up linking changes from the Docker and Kubernetes docs. Please let me know if anything else is needed.