What does adding a registry host to the `insecure-registries` list in the Docker daemon's `daemon.json` actually change, and what would you do instead for a production internal registry?

## What the setting does ```json { "insecure-registries": ["registry.internal:5000", "10.4.0.0/16"] } ``` For any registry in this list the Docker daemon will: 1. Attempt HTTPS **without verifying** the server certificate — expired, self-signed, wrong-hostname all pass. 2. If HTTPS is unavailable, **fall back to plain HTTP**. Entries are matched by host and port, or by CIDR for IP-addressed registries. The file lives at `/etc/docker/daemon.json` (Linux) and changes take effect only after `systemctl reload docker` or a daemon restart. `docker info` prints the effective list, which is the quickest way to confirm what a node actually believes. Crucially, this is **per node**. A cluster of fifty machines needs the setting on all fifty, applied by configuration management — which is one practical reason it ages badly. ## What you actually lose TLS gives three things: confidentiality, integrity, and server authentication. Turning verification off surrenders all three for that host. - **Credential exposure.** Registry auth sends the username and secret as HTTP Basic to the token endpoint. Over plain HTTP that is a plaintext credential on the wire; with unverified TLS, any machine that can intercept the connection presents its own certificate and reads it. - **Image substitution.** The content-addressable design protects you *after* you know the digest you want, but a `pull` by tag asks the server which digest the tag points to. A man-in-the-middle answers with its own manifest, and the client happily verifies the layers against *that* manifest's digests. The chain of trust starts at the connection, and you just removed it. - **No server authentication.** DNS spoofing, ARP poisoning, a rogue host on the VLAN, or a typo'd hostname that someone else registered are all sufficient. "It's internal" assumes the internal network is trusted, which is precisely the assumption modern network design abandons. A secondary annoyance: the setting is invisible in your image references, so a pull that works on a configured node fails on a fresh one with a certificate error, and the failure looks like a registry outage. ## What to do instead **Trust the CA, don't disable verification.** If the registry uses a certificate from an internal CA or a self-signed one, install the issuing certificate rather than switching checking off: - Per-registry, Docker-specific: place the PEM at `/etc/docker/certs.d/<host>:<port>/ca.crt`. Docker reads this directory per pull, so no daemon restart is needed. The directory name must match the registry reference exactly, port included. - System-wide: add the CA to the OS trust store (`/usr/local/share/ca-certificates` + `update-ca-certificates` on Debian-family, `/etc/pki/ca-trust/source/anchors` + `update-ca-trust` on RHEL-family). This also fixes every other tool on the host. The same directory can hold a client certificate and key (`client.cert` / `client.key`) when the registry uses mutual TLS. **Give the registry a real certificate.** Internal PKI, an ACME-issued certificate from a public CA for a resolvable name, or a load balancer terminating TLS with a managed certificate. This is usually less work than maintaining an exception on every node forever. **Bound the blast radius when you cannot avoid it.** Legitimate temporary uses exist: a `registry:2` container on a laptop for local experiments, an air-gapped lab, a throwaway CI fixture. Keep the exception to `localhost`/`127.0.0.1` (which Docker already treats as insecure-capable) or a single lab host, never a CIDR covering a production network, and never combined with real credentials you also use elsewhere. ## Things candidates commonly get wrong - **It is not an authentication switch.** It does not bypass `docker login`; an insecure registry can still require credentials, and a secure one can be anonymous. Access-denied errors are never fixed by this setting. - **It is not enough on its own for HTTP.** Some clients and mirrors need matching configuration too, and a registry served over HTTP behind an HTTPS-only proxy will still fail. - **It configures the Docker daemon only.** Other runtimes read their own configuration files, and orchestrators that use a different runtime will not honour `daemon.json` at all. Migrating a node from Docker to another runtime silently loses the exception. - **Restart required.** Editing the file without reloading the daemon produces confusing "I already fixed that" reports.