Skip to content

Commit 2773210

Browse files
dvdksndvdksn
authored
Merge pull request #21284 from dvdksn/docker-zscaler-guide
guides: add docker+zscaler guide
2 parents b9833dd + e9cc831 commit 2773210

File tree

2 files changed

+143
-0
lines changed

2 files changed

+143
-0
lines changed

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ OCI
9999
OTel
100100
Okta
101101
PAT
102+
PEM
102103
Postgres
103104
PowerShell
104105
Python
@@ -140,6 +141,7 @@ WSL
140141
Wasm
141142
Windows
142143
WireMock
144+
Zscaler
143145
Zsh
144146
[Bb]uildx
145147
[Cc]odenames?

‎content/guides/zscaler/index.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Using Docker with Zscaler
3+
tags: [networking, admin]
4+
summary: |
5+
This guide explains how to embed Zscaler’s root certificate into Docker
6+
images, allowing containers to operate securely with Zscaler proxies and
7+
avoid SSL errors.
8+
params:
9+
time: 10 minutes
10+
---
11+
12+
In many corporate environments, network traffic is intercepted and monitored
13+
using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance
14+
and network control, it can cause issues for developers using Docker,
15+
particularly during build processes, where SSL certificate validation errors
16+
might occur. This guide outlines how to configure Docker containers and builds
17+
to properly handle Zscaler's custom certificates, ensuring smooth operation in
18+
monitored environments.
19+
20+
## The role of certificates in Docker
21+
22+
When Docker builds or runs containers, it often needs to fetch resources from
23+
the internet—whether it's pulling a base image from a registry, downloading
24+
dependencies, or communicating with external services. In a proxied
25+
environment, Zscaler intercepts HTTPS traffic and replaces the remote server's
26+
certificate with its own. However, Docker doesn't trust this Zscaler
27+
certificate by default, leading to SSL errors.
28+
29+
```plaintext
30+
x509: certificate signed by unknown authority
31+
```
32+
33+
These errors occur because Docker cannot verify the validity of the certificate
34+
presented by Zscaler. To avoid this, you must configure Docker to trust
35+
Zscaler's certificate.
36+
37+
## Configure Zscaler proxy for Docker Desktop
38+
39+
Depending on how Zscaler is deployed, you may need to configure Docker Desktop
40+
proxy settings manually to use the Zscaler proxy.
41+
42+
If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector),
43+
all traffic on the device is automatically routed through Zscaler, so Docker
44+
Desktop uses the Zscaler proxy automatically with no additional configuration
45+
necessary.
46+
47+
If you are not using Zscaler as a system-level proxy, manually configure proxy
48+
settings in Docker Desktop. Set up proxy settings for all clients in the
49+
organization using [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md),
50+
or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](/manuals/desktop/settings.md#proxies).
51+
52+
## Install root certificates in Docker images
53+
54+
To enable containers to use and trust the Zscaler proxy, embed the certificate
55+
in the image and configure the image's trust store. Installing certificates at
56+
image build time is the preferred approach, as it removes the need for
57+
configuration during startup and provides an auditable, consistent environment.
58+
59+
### Obtaining the root certificate
60+
61+
The easiest way to obtain the root certificate is to export it from a machine
62+
where an administrator has already installed it. You can use either a web
63+
browser or the system's certificate management service (for example, Windows
64+
Certificate Store).
65+
66+
#### Example: Exporting the certificate using Google Chrome
67+
68+
1. In Google Chrome, navigate to `chrome://certificate-manager/`.
69+
2. Under **Local certificates**, select **View imported certificates**.
70+
3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**.
71+
4. Open the certificate details and select **Export**.
72+
5. Save the certificate in ASCII PEM format.
73+
6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
74+
75+
When you have obtained the certificate, store it in an accessible repository,
76+
such as JFrog Artifactory or a Git repository. Alternatively, use generic
77+
storage like AWS S3.
78+
79+
### Building with the certificate
80+
81+
To install these certificates when building images, copy the certificate into
82+
the build container and update the trust store. An example Dockerfile looks
83+
like this:
84+
85+
```dockerfile
86+
FROM debian:bookworm
87+
COPY zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem
88+
RUN apt-get update && \
89+
apt-get install -y ca-certificates && \
90+
update-ca-certificates
91+
```
92+
93+
Here, `zscaler-cert.pem` is the root certificate, located at the root of the
94+
build context (often within the application's Git repository).
95+
96+
If you use an artifact repository, you can fetch the certificate directly using
97+
the `ADD` instruction. You can also use the `--checksum` flag to verify that
98+
the content digest of the certificate is correct.
99+
100+
```dockerfile
101+
FROM debian:bookworm
102+
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \
103+
https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem
104+
RUN apt-get update && \
105+
apt-get install -y ca-certificates && \
106+
update-ca-certificates
107+
```
108+
109+
#### Using multi-stage builds
110+
111+
For multi-stage builds where certificates are needed in the final runtime
112+
image, ensure the certificate installation occurs in the final stage.
113+
114+
```dockerfile
115+
FROM debian:bookworm AS build
116+
WORKDIR /build
117+
RUN apt-get update && apt-get install -y \
118+
build-essential \
119+
cmake \
120+
curl \
121+
git
122+
RUN --mount=target=. cmake -B output/
123+
124+
FROM debian:bookworm-slim AS final
125+
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \
126+
https://artifacts.example/certs/zscaler-cert.pem /usr/local/share/ca-certificates/zscaler-cert.pem
127+
RUN apt-get update && \
128+
apt-get install -y ca-certificates && \
129+
update-ca-certificates
130+
WORKDIR /app
131+
COPY --from=build /build/output/bin .
132+
ENTRYPOINT ["/app/bin"]
133+
```
134+
135+
## Conclusion
136+
137+
Embedding the Zscaler root certificate directly into your Docker images ensures
138+
that containers run smoothly within Zscaler-proxied environments. By using this
139+
approach, you reduce potential runtime errors and create a consistent,
140+
auditable configuration that allows for smooth Docker operations within a
141+
monitored network.

0 commit comments

Comments
 (0)