From 54ba8dfa0c4e3b3ac64ad0f1077806f39cfd6840 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 10 Sep 2024 11:52:05 +0200 Subject: [PATCH] engine: add instructions for using ca certs with docker Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/engine/network/ca-certs.md | 150 +++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 content/manuals/engine/network/ca-certs.md diff --git a/content/manuals/engine/network/ca-certs.md b/content/manuals/engine/network/ca-certs.md new file mode 100644 index 00000000000..7aef58ad340 --- /dev/null +++ b/content/manuals/engine/network/ca-certs.md @@ -0,0 +1,150 @@ +--- +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 +--- + +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 + +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` works, assuming Docker Desktop is configured to use the MITM proxy. + +## Add CA certificates to 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 :/tmp + ``` + +4. Attach to the container: + + ```console + $ docker exec -it 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"} + + + + Example Domain + ... + ```