Docker Engine 29.10: Check Your Local Registry Configuration Before Upgrading

Docker Engine 29.10 changes loopback registry defaults. Learn how to migrate local registries without weakening transport security.

Cloud Infrastructure & Security•~8 min read•November 16, 2026•By QZ-L Editorial
#Docker#container security#registries#DevOps
Looking for related guides? Start with the qz-l Learning Center and explore more tutorials in this topic cluster.

Docker Engine 29.10.0 includes a small configuration change with a very practical consequence: a local registry that worked before the upgrade may stop accepting pulls or pushes after it.

The change affects installations that explicitly configure insecure-registries. In that case, Docker no longer automatically adds all loopback addresses as insecure registries. A registry at localhost, 127.0.0.1, or ::1 may therefore need an explicit entry, or—preferably—a trusted TLS certificate.

This is not a reason to make every registry insecure. It is a reason to inspect how your daemon is configured, decide whether HTTP is really necessary, and make any exception as narrow as possible.

What changed in Docker Engine 29.10.0

Docker documents two relevant modes:

  • If insecure-registries is omitted, loopback registries retain their default insecure behavior.
  • If insecure-registries is explicitly configured, Docker treats that configuration as authoritative instead of appending the loopback ranges 127.0.0.0/8 and ::1/128.

The second case is the one that can surprise an upgrade. Many development setups use a private registry over HTTP, or use TLS with a certificate that the Docker daemon does not trust. Before 29.10.0, such a registry could benefit from Docker's implicit loopback exception. After the upgrade, the pull or push can fail unless the exact registry endpoint is included in the explicit configuration.

The change also makes it possible to opt out of the loopback defaults entirely with an empty JSON array:

{
  "insecure-registries": []
}

That is useful when an administrator wants Docker to reject insecure registry connections, including local ones. The Moby change that implements this behavior notes an important detail: the command-line --insecure-registry option cannot currently represent an empty value, so the JSON configuration is the way to express this opt-out.

Docker Engine 29.10.0 was released on November 16, 2026. If you maintain a development workstation, CI runner, or private host with a local registry, review this setting as part of the upgrade rather than waiting for the first failed build.

First choice: use trusted TLS

An insecure registry is not merely “a registry on a private network.” In Docker's terminology, the setting permits registry communication over HTTP or with certificates that are not trusted by the daemon. A private network can still be misconfigured, monitored, or reached by an unintended machine.

For a registry that matters beyond a throwaway local experiment, configure TLS with a certificate trusted by the Docker daemon. That may mean using a certificate from a public or internal certificate authority and installing the appropriate CA certificate on each Docker host. The exact certificate installation steps depend on the operating system and registry implementation, so do not copy a host-specific command into production without checking its documentation.

Trusted TLS addresses the transport problem: the daemon can authenticate the registry endpoint and encrypt the connection. It does not, by itself, prove who built an image or whether a mutable tag now points at the image you reviewed. Keep transport security and image provenance as separate decisions.

If HTTP is unavoidable, make the exception narrow

There are legitimate development cases for an insecure local registry: a disposable test environment, an offline lab, or a short-lived integration test where setting up a CA would cost more than the test itself. If you accept that trade-off, list the exact host and port rather than a broad address range.

For example, a daemon configuration might contain:

{
  "insecure-registries": [
    "localhost:5000"
  ]
}

This example is intentionally narrow. It does not authorize every address in 127.0.0.0/8, and it does not make unrelated registries insecure. Use the actual endpoint that your tooling contacts. If your clients use a hostname rather than localhost, configure and test the name they actually use.

Do not treat this setting as a substitute for protecting the Docker daemon itself. The insecure-registries option controls registry connections made by the daemon; it does not make a remote Docker API safe. Docker documents SSH and mutual TLS for remote daemon access and warns that Docker client keys provide powerful control over the host. A registry exception and a daemon-socket exposure are different boundaries, and both need deliberate protection.

A safer upgrade workflow

The following checklist is designed for a host that may be upgraded to Docker Engine 29.10.0. It is a procedure to run in your environment, not a test performed for this article.

1. Inventory the endpoints

Search compose files, build scripts, CI variables, and developer documentation for registry names. Record whether each endpoint uses:

  • A public registry with normal trusted TLS.
  • A private registry with a trusted internal CA.
  • HTTP.
  • TLS with a certificate that the daemon does not trust.
  • A loopback name or address such as localhost:5000.

Do not assume that “local” means the same thing everywhere. A CI runner's localhost is the runner itself, while a developer's localhost is a workstation.

2. Inspect the daemon configuration

Find the active daemon.json and check whether it contains insecure-registries. Also check how the daemon is started; a command-line option can affect the result even when the JSON file looks harmless.

If there is no explicit setting and all required registries use trusted TLS, there may be nothing to migrate. If there is an explicit list, compare it with the endpoints from the inventory. Remember that 29.10.0 no longer appends loopback defaults in this configuration mode.

3. Prefer a trusted certificate

For a persistent private registry, install a CA that the Docker daemon trusts and move the registry to HTTPS. Coordinate the certificate change with every host that pulls or pushes images. A certificate that is trusted by a browser is not automatically trusted by the Docker daemon, so verify the daemon's certificate configuration for your platform.

4. Validate before restarting

Docker's dockerd reference documents a --validate option for checking daemon configuration. Use the validation command and configuration-file path appropriate for your installation before scheduling a restart. A successful configuration parse does not prove that the registry is reachable; it only removes one class of avoidable error.

Keep a copy of the previous configuration and use your operating system's normal service-management procedure. Do not paste a full daemon configuration from another host: unrelated options such as storage, networking, or logging can be environment-specific.

5. Run a controlled pull and push

After the upgrade or configuration change, perform a small test against each required registry. Pull a known test image, tag it for the private endpoint, and push it only if your environment permits that test. Confirm the result from the daemon that production or CI will actually use.

If a test fails, classify the error before adding an insecure exception. Common categories include:

  • The registry endpoint was omitted from an explicit insecure-registries list.
  • The registry uses HTTPS but its CA is not trusted.
  • The hostname in the certificate does not match the hostname in the image reference.
  • The client is reaching a different localhost than expected.
  • The daemon is using a different configuration file or command-line setting.

Adding a broad insecure CIDR can hide the diagnosis while expanding the trust boundary.

What this change does not solve

Allowing a registry connection is not the same as trusting the image contents. Docker's Content Trust documentation describes signed tags and publisher/integrity verification as a separate feature. Docker also says that its Notary v1 service is scheduled to shut down on December 8, 2026. That makes it especially important not to present legacy Content Trust as a complete, future-proof supply-chain plan.

For current image workflows, use the provenance and signing controls that your registry and build platform actively support, and pin deployment inputs by digest where practical. A digest helps ensure that a deployment refers to the exact image bytes selected during review; it does not replace access control, vulnerability review, or a secure build pipeline.

The same principle applies to the Docker daemon socket. Even a perfectly configured registry can be undermined if untrusted users can control dockerd. Restrict local socket permissions, avoid exposing an unauthenticated TCP daemon, and use SSH or mutually authenticated TLS for legitimate remote administration.

The practical takeaway

Docker Engine 29.10.0 turns an implicit local-registry exception into an explicit configuration decision whenever insecure-registries is set. That is a useful security direction, but it can look like a breaking change during an upgrade.

Before upgrading:

  1. List every registry endpoint used by developers and automation.
  2. Remove insecure transport where a trusted TLS setup is practical.
  3. If an exception is temporary, list only the exact host and port.
  4. Use an empty insecure-registries array when you intentionally want no loopback defaults.
  5. Validate the daemon configuration and run a controlled pull/push test on the real host.

The safest configuration is the one that makes the registry's transport and trust assumptions visible instead of relying on a convenient default.

References

Related Posts

Catch Secrets Before Merge: GitHub's New Copilot Review Path

Use GitHub's preview secret scanning in Copilot security review to catch credentials in code changes before they reach a pull request.

Stop Asyncio Subprocess Pipe Deadlocks Before They Stall Your Tooling

Choose safe asyncio subprocess patterns for captured output, streaming logs, pipe deadlocks, and shell-command security.

Kubernetes OCI Seccomp Profiles: Ship Syscall Policies with Your Workload

Kubernetes 1.38 adds an alpha path for digest-pinned OCI seccomp profiles. Learn the runtime flow, safeguards, and rollout limits.