docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

engine: add instructions for using ca certs with docker 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2024-09-10 11:52:05 +02:00
parent ed240596e9
commit 435b80df3d
2 changed files with 189 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
content/manuals/engine/network/ca-certs.md Normal file
View File

@ -0,0 +1,187 @@
---
title: Use CA certificates with Docker
linkTitle: CA certificates
description: Learn how to install and use CA certificates on the Docker host and in Linux containers
keywords: docker, networking, ca, certs, host, container, proxy
---
> [!CAUTION]
> Best practices should be followed when using Man-in-the-Middle (MITM) CA
> certificates in production containers. If compromised, attackers could
> intercept sensitive data, spoof a trusted service, or perform
> man-in-the-middle attacks. Consult your security team before you proceed.
If your company uses a proxy that inspects HTTPS traffic, you might need to add
the required root certificates to your host machine and your Docker containers
or images. This is because Docker and its containers, when pulling images or
making network requests, need to trust the proxy’s certificates.
On the host, adding the root certificate ensures that any Docker commands (like
`docker pull`) work without issues. For containers, you'll need to add the root
certificate to the container's trust store either during the build process or
at runtime. This ensures that applications running inside the containers can
communicate through the proxy without encountering security warnings or
connection failures.
## Add CA certificate to the host
The following sections describe how to install CA certificates on your macOS or
Windows host. For Linux, refer to the documentation for your distribution.
### macOS
1. Download the CA certificate for your MITM proxy software.
2. Open the **Keychain Access** app.
3. In Keychain Access, select **System**, then switch to the **Certificates** tab.
4. Drag-and-drop the downloaded certificate into the list of certificates. Enter your password if prompted.
5. Find the newly added certificate, double-click it, and expand the **Trust** section.
6. Set **Always Trust** for the certificate. Enter your password if prompted.
7. Start Docker Desktop and verify that `docker pull` works, assuming Docker Desktop is configured to use the MITM proxy.
### Windows
Choose whether you want to install the certificate using the Microsoft
Management Console (MMC) or your web browser.
{{< tabs >}}
{{< tab name="MMC" >}}
1. Download CA certificate for the MITM proxy software.
2. Open the Microsoft Management Console (`mmc.exe`).
3. Add the **Certificates Snap-In** in the MMC.
1. Select **File** → **Add/Remove Snap-in**, and then select **Certificates** → **Add >**.
2. Select **Computer Account** and then **Next**.
3. Select **Local computer** and then select **Finish**.
4. Import the CA certificate:
1. From the MMC, expand **Certificates (Local Computer)**.
2. Expand the **Trusted Root Certification Authorities** section.
3. Right-click **Certificates** and select **All Tasks** and **Import…**.
4. Follow the prompts to import your CA certificate.
5. Select **Finish** and then **Close**.
6. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server).
> [!NOTE]
> Depending on the SDK and/or runtime/framework in use, further steps may be
> required beyond adding the CA certificate to the operating system's trust
> store.
{{< /tab >}}
{{< tab name="Web browser" >}}
1. Download the CA certificate for your MITM proxy software.
2. Open your web browser, go to **Settings** and open **Manage certificates**
3. Select the **Trusted Root Certification Authorities** tab.
4. Select **Import**, then browse for the downloaded CA certificate.
5. Select **Open**, then choose **Place all certificates in the following store**.
6. Ensure **Trusted Root Certification Authorities** is selected and select **Next**.
7. Select **Finish** and then **Close**.
8. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server).
{{< /tab >}}
{{< /tabs >}}
## Add CA certificates to Linux images and containers
If you need to run containerized workloads that rely on internal or custom
certificates, such as in environments with corporate proxies or secure
services, you must ensure that the containers trust these certificates. Without
adding the necessary CA certificates, applications inside your containers may
encounter failed requests or security warnings when attempting to connect to
HTTPS endpoints.
By [adding CA certificates to images](#add-certificates-to-images) at build
time, you ensure that any containers started from the image will trust the
specified certificates. This is particularly important for applications that
require seamless access to internal APIs, databases, or other services during
production.
In cases where rebuilding the image isn't feasible, you can instead [add
certificates to containers](#add-certificates-to-containers) directly. However,
certificates added at runtime won’t persist if the container is destroyed or
recreated, so this method is typically used for temporary fixes or testing
scenarios.
## Add certificates to images
> [!NOTE]
> The following commands are for an Ubuntu base image. If your build uses a
> different Linux distribution, use equivalent commands for package management
> (`apt-get`, `update-ca-certificates`, and so on).
To add ca certificate to a container image when you're building it, add the
following instructions to your Dockerfile.
```dockerfile
# Install the ca-certificate package
RUN apt-get update && apt-get install -y ca-certificates
# Copy the CA certificate from the context to the build container
COPY your_certificate.crt /usr/local/share/ca-certificates/
# Update the CA certificates in the container
RUN update-ca-certificates
```
### Add certificates to containers
> [!NOTE]
> The following commands are for an Ubuntu-based container. If your container
> uses a different Linux distribution, use equivalent commands for package
> management (`apt-get`, `update-ca-certificates`, and so on).
To add a CA certificate to a running Linux container:
1. Download the CA certificate for your MITM proxy software.
2. If the certificate is in a format other than `.crt`, convert it to `.crt` format:
```console {title="Example command"}
$ openssl x509 -in cacert.der -inform DER -out myca.crt
```
3. Copy the certificate into the running container:
```console
$ docker cp myca.crt <containerid>:/tmp
```
4. Attach to the container:
```console
$ docker exec -it <containerid> sh
```
5. Ensure the `ca-certificates` package is installed (required for updating certificates):
```console
# apt-get update && apt-get install -y ca-certificates
```
6. Copy the certificate to the correct location for CA certificates:
```console
# cp /tmp/myca.crt /usr/local/share/ca-certificates/root_cert.crt
```
7. Update the CA certificates:
```console
# update-ca-certificates
```
```plaintext {title="Example output"}
Updating certificates in /etc/ssl/certs...
rehash: warning: skipping ca-certificates.crt, it does not contain exactly one certificate or CRL
1 added, 0 removed; done.
```
8. Verify that the container can communicate via the MITM proxy:
```console
# curl https://example.com
```
```plaintext {title="Example output"}
<!doctype html>
<html>
<head>
<title>Example Domain</title>
...
```

2
hugo_stats.json
View File

@ -75,6 +75,7 @@
"Linux",
"Local-or-Hub-storage",
"MDM",
"MMC",
"Mac",
"Mac-/-Linux",
"Mac-/-Linux-/-Git-Bash",
@ -126,6 +127,7 @@
"Vue",
"WSL-2-backend-Arm-Beta",
"WSL-2-backend-x86_64",
"Web-browser",
"What-administrative-tasks-can-I-perform-in-Docker-Hub",
"What-are-the-key-features-of-Docker-Desktop",
"What-key-features-are-included-in-Docker-Hub",