Adding Custom CA Certificates to Podman - A Complete Guide#

Secure communications are essential in modern infrastructure, especially in containerized environments. When working with Podman in enterprise or development settings, you’ll often need to connect to services that use certificates signed by private or internal Certificate Authorities (CAs). This guide provides comprehensive instructions for adding custom CA certificates to Podman, enabling secure connections to internal services, private registries, and other certificate-secured resources.

Understanding CA Certificates and Podman#

Before diving into implementation details, it’s important to understand why and how CA certificates work with Podman:

1
graph TD
2
    A[Podman Container] -->|Secure Request| B[Internal Service]
3
    B -->|Presents Certificate| A
4
    A -->|Verifies Against| C[CA Certificate Store]
5
    C -->|Trust Decision| A
6

7
    D[Certificate Authority] -->|Issues| E[Service Certificate]
8
    E -->|Installed On| B
9
    D -->|Root Certificate| C
10

11
    subgraph "Container Host"
12
        A
13
        C
14
    end
15

16
    subgraph "Service Host"
17
        B
18
    end

Podman relies on the host’s certificate store to validate TLS certificates presented by remote services. When connecting to services using certificates signed by custom CAs (like internal company CAs), Podman needs access to those CA certificates to establish trust.

Two Approaches to Adding CA Certificates#

There are two primary methods for adding CA certificates to Podman:

Direct Certificate Installation: Adding individual CA certificates to the host’s trust store
Integrated CA Infrastructure: Setting up a complete certificate authority infrastructure with tools like Smallstep CA

Let’s explore both approaches in detail.

Method 1: Direct Certificate Installation#

This straightforward approach involves adding CA certificates directly to the host system’s certificate store.

For Locally Running Podman (Linux)#

1
# Copy your CA certificate to the appropriate directory
2
sudo cp your-ca.crt /etc/pki/ca-trust/source/anchors/
3

4
# Update the system's trust store
5
sudo update-ca-trust

For Podman Machine (macOS/Windows)#

If you’re using Podman Machine on macOS or Windows, you’ll need to add the certificate to the virtual machine:

1
# SSH into Podman Machine
2
podman machine ssh
3

4
# Switch to root (if needed)
5
sudo su -
6

7
# Navigate to certificate directory
8
cd /etc/pki/ca-trust/source/anchors/
9

10
# Create certificate file
11
vi custom-ca.pem
12
# Paste your certificate content here
13
# Save and exit (ESC, then :wq)
14

15
# Update the trust store
16
update-ca-trust
17

18
# Exit from root and the machine
19
exit
20
exit

Downloading Certificates from a Server#

If your CA certificate is available for download:

1
# SSH into Podman Machine
2
podman machine ssh
3

4
# Switch to root (if needed)
5
sudo su -
6

7
# Navigate to certificate directory
8
cd /etc/pki/ca-trust/source/anchors/
9

10
# Download certificate
11
curl -k -o custom-ca.pem https://your-ca-server/ca.crt
12

13
# Update the trust store
14
update-ca-trust
15

16
# Exit from root and the machine
17
exit
18
exit

Method 2: Integrated CA Infrastructure with Smallstep CA#

For more advanced use cases, setting up a complete CA infrastructure provides better certificate lifecycle management, automation, and security. This approach is especially valuable for larger environments or when multiple services need certificates.

Components of an Integrated CA Solution#

1
graph TD
2
    A[Smallstep CA Server] -->|Issues Certificates| B[Services]
3
    C[Podman Hosts] -->|Trust| A
4
    C -->|Secure Connection| B
5
    D[DNS Server] -->|Name Resolution| C
6
    D -->|Name Resolution| B
7

8
    subgraph "Certificate Infrastructure"
9
        A
10
        D
11
    end

Setting Up Smallstep CA Server#

These steps outline how to set up a Smallstep CA server on a dedicated machine:

1
# Install Smallstep CA and CLI
2
wget https://github.com/smallstep/cli/releases/download/v0.24.0/step-cli_0.24.0_amd64.rpm
3
wget https://github.com/smallstep/certificates/releases/download/v0.24.0/step-ca_0.24.0_amd64.rpm
4

5
# Install the packages
6
rpm -ivh step-cli_0.24.0_amd64.rpm
7
rpm -ivh step-ca_0.24.0_amd64.rpm
8

9
# Initialize the CA (save password and fingerprint!)
10
step ca init --name "Enterprise CA" \
11
  --dns ca.example.com \
12
  --address :443 \
13
  --provisioner admin
14

15
# Create password file (for automated startup)
16
echo "your_secure_password_here" > /etc/step-ca.env
17
chmod 600 /etc/step-ca.env
18

19
# Create systemd service
20
cat << EOF > /etc/systemd/system/step-ca.service
21
[Unit]
22
Description=Smallstep Certificates CA
23
Documentation=https://smallstep.com/docs/step-ca
24
After=network.target
25

26
[Service]
27
Type=simple
28
User=root
29
EnvironmentFile=/etc/step-ca.env
30
ExecStart=/bin/bash -c 'echo "$STEPCA_PASSWORD" | step-ca /root/.step/config/ca.json --password-file /dev/stdin'
31
Restart=on-failure
32

33
[Install]
34
WantedBy=multi-user.target
35
EOF
36

37
# Start and enable service
38
systemctl daemon-reload
39
systemctl start step-ca
40
systemctl enable step-ca

Setting Up CoreDNS (Optional but Recommended)#

A DNS server makes certificate management easier by providing consistent naming:

1
# Create Corefile configuration
2
cat << EOF > /etc/coredns/Corefile
3
.:53 {
4
    forward . 8.8.8.8
5
    log
6
    errors
7
}
8

9
example.com:53 {
10
    file /etc/coredns/example.com.db
11
    log
12
    errors
13
}
14
EOF
15

16
# Create zone file
17
cat << EOF > /etc/coredns/example.com.db
18
\$ORIGIN example.com.
19
@       3600 IN SOA  ca.example.com. admin.example.com. (
20
        2024061501 ; serial
21
        7200       ; refresh
22
        3600       ; retry
23
        1209600    ; expire
24
        3600       ; minimum
25
)
26

27
@       3600 IN NS  ca.example.com.
28

29
ca        IN A     192.168.1.10
30
registry  IN A     192.168.1.20
31
EOF
32

33
# Create CoreDNS service
34
cat << EOF > /etc/systemd/system/coredns.service
35
[Unit]
36
Description=CoreDNS DNS server
37
Documentation=https://coredns.io
38
After=network.target
39

40
[Service]
41
ExecStart=/path/to/coredns -conf /etc/coredns/Corefile
42
Restart=on-failure
43

44
[Install]
45
WantedBy=multi-user.target
46
EOF
47

48
# Start and enable CoreDNS
49
systemctl daemon-reload
50
systemctl start coredns
51
systemctl enable coredns

Adding CA Certificates to Podman#

Once your CA infrastructure is set up, add the root certificate to your Podman hosts:

1
# SSH into Podman Machine
2
podman machine ssh
3

4
# Switch to root (if needed)
5
sudo su -
6

7
# Navigate to certificate directory
8
cd /etc/pki/ca-trust/source/anchors/
9

10
# Download certificate from CA server
11
curl -k -o enterprise-ca.pem https://ca.example.com/root_ca.crt
12

13
# Update the trust store
14
update-ca-trust
15

16
# Exit
17
exit
18
exit

Configuring Podman to Use Your CA Infrastructure#

After adding certificates, you may want to configure Podman to work seamlessly with your internal services:

1
# SSH into Podman Machine
2
podman machine ssh
3

4
# Configure registries
5
sudo vi /etc/containers/registries.conf
6

7
# Add your internal registry to the search list
8
[registries.search]
9
registries = ['docker.io', 'registry.example.com']
10

11
# Exit and reload
12
exit

Testing Your Certificate Configuration#

To verify your certificates are properly installed and trusted:

1
# Test pulling from a private registry
2
podman pull registry.example.com/myapp:latest
3

4
# Test with curl to verify TLS works
5
podman run --rm registry.example.com/myapp curl https://secure-service.example.com

Comparing the Two Approaches#

Feature	Direct Installation	Integrated CA Infrastructure
Complexity	Low	Moderate to High
Scalability	Limited	High
Certificate Management	Manual	Automated
Certificate Rotation	Manual process	Automated renewal
Security Controls	Basic	Advanced (revocation, policies)
Audit Capability	Limited	Comprehensive
Best For	Small environments	Enterprise/production

Advantages of Smallstep CA Over Manual Certificate Management#

Centralized certificate management
Automated certificate lifecycle (issuance, renewal, revocation)
Built-in PKI best practices
API-driven workflow
Easy certificate rotation
Better audit trails and logging
Integration capabilities with other services

Advanced Integration Examples#

Automating Certificate Distribution#

Create an automated script to distribute CA certificates to all Podman hosts:

1
#!/bin/bash
2
# save as distribute-certs.sh
3

4
# Variables
5
CA_SERVER="ca.example.com"
6
CA_FINGERPRINT="your-fingerprint-here"
7
HOSTS=("podman1.example.com" "podman2.example.com" "podman3.example.com")
8

9
# Get the CA certificate
10
curl -k -o root_ca.crt https://$CA_SERVER/root_ca.crt
11

12
# Distribute to all hosts
13
for host in "${HOSTS[@]}"; do
14
  echo "Distributing to $host..."
15
  scp root_ca.crt root@$host:/tmp/
16
  ssh root@$host "cp /tmp/root_ca.crt /etc/pki/ca-trust/source/anchors/ && update-ca-trust"
17
done
18

19
echo "Distribution complete!"

Setting Up Automatic Certificate Renewal#

For services that need certificates:

1
# Request initial certificate
2
step ca certificate service.example.com service.crt service.key
3

4
# Create renewal script
5
cat << EOF > /usr/local/bin/renew-cert.sh
6
#!/bin/bash
7
step ca renew --force service.crt service.key
8
systemctl reload nginx  # Restart service to use new cert
9
EOF
10
chmod +x /usr/local/bin/renew-cert.sh
11

12
# Add to crontab for automatic renewal
13
(crontab -l 2>/dev/null; echo "0 0 1 * * /usr/local/bin/renew-cert.sh") | crontab -

Troubleshooting Certificate Issues#

Certificate Not Trusted#

If Podman doesn’t trust your certificates:

1
# Check if certificate is properly installed
2
ls -l /etc/pki/ca-trust/source/anchors/your-ca.pem
3

4
# Verify certificate format
5
openssl x509 -in /etc/pki/ca-trust/source/anchors/your-ca.pem -text -noout
6

7
# Check if trust update worked
8
podman run --rm alpine cat /etc/ssl/certs/ca-certificates.crt | grep "Your CA Name"

Connection Issues#

For troubleshooting connection problems:

1
# Test DNS resolution
2
podman run --rm alpine nslookup registry.example.com
3

4
# Test TLS connection with verbose output
5
podman run --rm alpine sh -c "apk add --no-cache curl && curl -v https://registry.example.com"

Registry Authentication Problems#

If you’re having issues with registry authentication:

1
# Test registry authentication
2
podman login registry.example.com
3

4
# Check registry configuration
5
cat /etc/containers/registries.conf

Security Best Practices#

Protect CA private keys: Never share or expose private keys
Rotate certificates regularly: Implement automated certificate rotation
Implement certificate revocation: Set up CRLs or OCSP for certificate revocation
Audit certificate issuance: Regularly review which certificates have been issued
Backup CA data: Maintain secure backups of CA configuration and keys
Document procedures: Create detailed documentation for certificate operations
Monitor expiration dates: Set up alerts for expiring certificates

Conclusion#

Adding custom CA certificates to Podman enables secure connections to internal services and private registries, which is essential in enterprise environments. Depending on your needs, you can choose between direct certificate installation for simpler use cases or setting up a complete certificate authority infrastructure with Smallstep CA for more comprehensive certificate management.

For most production environments, the integrated CA approach offers significant advantages in terms of security, automation, and management capabilities. However, for simpler development environments, direct certificate installation may be sufficient.

By following the steps outlined in this guide, you can establish a robust certificate infrastructure that seamlessly integrates with your Podman environment, ensuring secure communications between containers and services across your infrastructure.