Resolving TLS Certificate Verification Errors When Pulling Docker Images from a Private Repository

Introduction:

Docker has revolutionized containerization, allowing developers to package and distribute applications seamlessly. When working with private repositories, you might encounter TLS certificate verification errors, such as the one below:

Error response from daemon: Get "https://private-repository.company.com/v2/": tls: failed to verify certificate: x509: certificate signed by unknown authority

This error typically occurs when Docker cannot verify the authenticity of the TLS certificate presented by the private repository. Here, we’ll explore various solutions to help you overcome this challenge.

1. Verify Certificate and Root CA:

Before diving into complex solutions, ensure that the certificate presented by the private repository is valid and signed by a recognized Certificate Authority (CA). Additionally, make sure you have the root CA certificate in your system.

a) Retrieve the CA certificate directly from the provided repository URL using the following command.

openssl s_client -showcerts -connect private-repository.company.com:443 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.crt

b) Copy this certificate in the path /usr/local/share/ca-certificates

cp cert.crt /usr/local/share/ca-certificates/

c) To refresh the ca-certificates datastore, execute the provided command. If lacking root permissions, add the command with sudo. Proceed directly to step 5 once these instructions are followed. If the issue persists, proceed to Step 2 and follow to the subsequent steps.

update-ca-certificates

2. Update Docker Configuration:

Add the root CA certificate to Docker’s trusted certificate store. Locate the certificate file and copy it to the following directory:

/etc/docker/certs.d/private-repository.company.com/

3. Disable TLS Verification (Not Recommended):

While it’s not recommended for security reasons, you can temporarily disable TLS verification to allow Docker to pull images without certificate checks. Use this only for debugging purposes, and never in production environments:

docker --insecure-registry=private-repository.company.com pull your-image

4. Updating the Docker Daemon Configuration:

Edit the Docker daemon configuration file, usually located at /etc/docker/daemon.json. Add the private repository URL to the “insecure-registries” section:

{
  "insecure-registries": ["private-repository.company.com"]
}

5. Restart Docker service

Restart the Docker daemon to apply the changes:

sudo systemctl restart docker

6. Regenerate and Distribute Certificates:

If you manage your Docker infrastructure with tools like Docker Swarm or Kubernetes, regenerate the certificates and distribute them to all nodes. Ensure that the certificates are valid and signed by a trusted CA.

Conclusion:

TLS certificate verification issues can be challenging, but with careful examination and the right configuration adjustments, you can successfully pull Docker images from private repositories. Always prioritize security and consider the implications of any workaround, using them judiciously based on your specific development or debugging needs.