Explains how Linkerd automatically identifies connection protocols (HTTP, HTTP/2, gRPC, TLS) by inspecting the first bytes of a connection, avoiding manual configuration. Covers detection timeouts, marking ports as opaque for non-detectable protocols like MySQL and Redis, handling server-first protocols such as SMTP and SSH, troubleshooting common detection issues with CLI commands, and best practices like naming ports and pre-configuring opaque ports for known services.
Table of contents
How Protocol Detection WorksConfiguring Protocol DetectionMarking Ports as OpaqueServer-First ProtocolsProtocol Detection in PracticeTroubleshooting Protocol DetectionBest PracticesConclusionQuestions this post answers
Why is my MySQL connection through Linkerd hanging indefinitely?
MySQL is a server-first protocol, meaning the server sends data before the client does, so Linkerd's proxy waits for client data that never arrives and the connection hangs. Mark the MySQL port as opaque using the config.linkerd.io/opaque-ports annotation (e.g., set to "3306") to skip protocol detection entirely for that port. Debugging service mesh networking issues gets easier with troubleshooting guides surfaced on daily.dev.
How does Linkerd know whether a connection is HTTP, gRPC, or TCP without configuration?
Linkerd peeks at the first bytes of an incoming connection and matches them against known signatures: HTTP/1.x starts with a method like GET or POST, HTTP/2 starts with the connection preface "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n", gRPC is HTTP/2 with a content-type: application/grpc header, TLS starts with a ClientHello, and anything unmatched falls back to plain TCP. Understanding how service meshes classify traffic helps when comparing options on daily.dev.
Which ports should be marked as opaque in a Linkerd service mesh?
Ports serving protocols that cannot be detected should be marked opaque, including server-first protocols like MySQL, SMTP, FTP, and SSH, plus other binary protocols like Redis and MongoDB. Use the config.linkerd.io/opaque-ports annotation with a comma-separated port list, e.g. "3306,6379,27017", applied at the service, deployment, or namespace level. Keep configuration patterns like this handy while managing service mesh setups via daily.dev.