Deprecations
Versioned replacement and removal contracts for Sockguard configuration.
This is the canonical removal schedule. A deprecation warning doesn't disable the setting. No removals listed here take effect on the v2.2, v2.3 or v2.4 lines.
| Setting or behavior | Deprecated since | Accepted through | Replacement | Removal target | Status |
|---|---|---|---|---|---|
upstream.endpoints[].insecure_skip_tls_verify | v2.1.0 | All v2.x | Verify the daemon certificate with tls.ca_file; retain client cert/key when required. | v3.0.0 | Planned breaking change; not implemented. |
Non-empty DOCKER_TLS with empty/unset DOCKER_TLS_VERIFY | v2.1.0 | All v2.x | Set DOCKER_TLS_VERIFY=1 and provide the daemon CA through Docker's certificate-directory resolution. | v3.0.0 | Planned breaking change; not implemented. |
insecure_accept_opaque_buildkit_tunnels | v1.7.0 | All current v2 lines | Configure per-client request_body.buildkit mediation. | Future major, exact version undecided | Still accepted with a startup warning; mutually exclusive with mediation. |
DOCKER_TLS_VERIFY uses Docker's non-empty semantics: even 0 or false
enables verification and takes precedence over DOCKER_TLS. Follow
Migration and Multi-host
for CA and optional client-certificate configuration.
GRPC/SESSION compatibility variables currently generate the opaque BuildKit
acknowledgment unless a mediation policy is configured. Their replacement and
validation behavior must be decided alongside that acknowledgment's removal.
An exact removal version hasn't been chosen; this isn't an additional v3.0.0
promise.
v3.0.0 removal checklist
v3 is a planned compatibility boundary, without a scheduled feature release. Before cutting it:
- Reject the deprecated endpoint skip-verification setting with migration guidance. Continue to validate verified TLS and per-endpoint CA/client certs.
- Reject the unverified
DOCKER_TLSfallback, preserving verifiedDOCKER_TLS_VERIFYprecedence and certificate-directory behavior. - Test startup, config validation, environment resolution, reload behavior, Unix/plain TCP endpoints and verified TLS through the complete server chain.
- Update warnings, configuration reference, migration examples, CLI help, README and breaking-change release notes together.
- Make an explicit version decision before including opaque BuildKit removal.
Test its legacy
GRPC/SESSIONcompatibility behavior if it joins this release.
These are future implementation tasks. v2 operators should migrate now, but v2 runtime behavior remains compatible with the accepted settings above.