Connect-Native Integration with Go

    We provide a library that makes it drop-in simple to integrate Connect with most Go applications. This page shows examples of integrating this library for accepting or establishing Connect-based connections. For most Go applications, Connect can be natively integrated in just a single line of code excluding imports and struct initialization.

    In addition to this, please read and understand the . In particular, after integrating applications with Connect, they must declare that they accept Connect-based connections via their service definitions.

    Any server that supports TLS (HTTP, gRPC, net/rpc, etc.) can begin accepting Connect-based connections in just a few lines of code. For most existing applications, converting the server to accept Connect-based connections will require only a one-line change excluding imports and structure initialization.

    The Go library exposes a *tls.Config that automatically communicates with Consul to load certificates and authorize inbound connections during the TLS handshake. This also automatically starts goroutines to update any changing certs.

    Example, followed by more details:

    The first step is to create a Consul API client. This is almost always the default configuration with an ACL token set, since you want to communicate to the local agent. The default configuration will also read the ACL token from environment variables if set. The Go library will use this client to request certificates, authorize connections, and more.

    Next, connect.NewService is called to create a service structure representing the currently running service. This structure maintains all the state for accepting and establishing connections. An application should generally create one service and reuse that one service for all servers and clients.

    Since the service returns a standard *tls.Config, any server that supports TLS can be configured. This includes gRPC, net/rpc, basic TCP, and more. Another example is shown below with just a plain TLS listener:

    For Go applications that need to Connect to HTTP-based upstream dependencies, the Go library can construct an *http.Client that automatically establishes Connect-based connections as long as Consul-based service discovery is used.

    Example, followed by more details:

    The first step is to create a Consul API client and service. These are the same steps as accepting connections and are explained in detail in the section above. If your application is both a client and server, both the API client and service structure can be shared and reused.

    Next, we call svc.HTTPClient() to return a specially configured . This client will automatically established Connect-based connections using Consul service discovery.

    Finally, we perform an HTTP GET request to a hypothetical userinfo service. The HTTP client configuration automatically sends the correct client certificate, verifies the server certificate, and manages background goroutines for updating our certificates as necessary.

    If the application already uses a manually constructed *http.Client, the svc.HTTPDialTLS function can be used to configure the http.Transport.DialTLS field to achieve equivalent behavior.

    • The scheme must be https://.
    • It must be a Consul DNS name in one of the following forms:
    • Tag filters for services are not currently supported (i.e. tag1.web.service.consul) however the same behavior can be achieved using a prepared query.
    • External DNS names, raw IP addresses and so on will cause an error and should be fetched using a separate .

    For a raw net.Conn TLS connection, the svc.Dial function can be used. This will establish a connection to the desired service via Connect and return the net.Conn. This connection can then be used as desired.

    Example:

    This uses a familiar Dial-like function to establish raw net.Conn values. The second parameter to dial is an implementation of the connect.Resolver interface. The example above uses the *connect.ConsulResolver implementation to perform Consul-based service discovery. This also automatically determines the correct certificate metadata we expect the remote service to serve.

    In the raw TLS connection example, you see the use of a connect.Resolver implementation. This interface can be implemented to perform address resolution. This must return the address and also the URI SAN expected in the TLS certificate served by the remote service.

    The Go library provides two built-in resolvers:

    • can be used for static addresses where no service discovery is required. The expected cert URI SAN must be manually specified.

    • *connect.ConsulResolver which resolves services and prepared queries via the Consul API. This also automatically determines the expected cert URI SAN.