website: connect native overview
This commit is contained in:
Mitchell Hashimoto
Jack Pearkes
parent
692f1ef357
commit
ce5e2a9ed2
Binary file not shown.
|
|
@ -8,4 +8,121 @@ description: |-
|
|||
|
||||
# Connect-Native App Integration
|
||||
|
||||
TODO
|
||||
Applications can natively integrate with the Connect API to support
|
||||
accepting and establishing connections to other Connect services without
|
||||
the overhead of a [proxy sidecar](/docs/connect/proxies.html). This page
|
||||
will cover the high-level overview of integration, registering the service,
|
||||
etc. For language-specific examples, see the sidebar navigation to the left.
|
||||
|
||||
Connect is just basic mutual TLS. This means that almost any application
|
||||
can easily integrate with Connect. There is no custom protocol in use;
|
||||
any language that supports TLS can accept and establish Connect-based
|
||||
connections.
|
||||
|
||||
## Overview
|
||||
|
||||
The primary work involved in natively integrating with Connect is
|
||||
[acquiring the proper TLS certificate](/api/agent/connect.html#service-leaf-certificate),
|
||||
[verifying TLS certificates](/api/agent/connect.html#certificate-authority-ca-roots),
|
||||
and [authorizing inbound connections](/api/agent/connect.html#authorize).
|
||||
All of this is done using Consul's HTTP API using the previously-linked APIs.
|
||||
|
||||
An overview of the sequence is shown below. The diagram and the following
|
||||
details may seem complex, but this is a _regular mutual TLS connection_ with
|
||||
an API call to verify the incoming client certificate.
|
||||
|
||||
<div class="center">
|
||||
|
||||
</div>
|
||||
|
||||
Details on the steps are below:
|
||||
|
||||
* **Service discovery** - This is normal service discovery using Consul,
|
||||
a static IP, or any other mechanism. If you're using Consul DNS, the
|
||||
[`<service>.connect`](/docs/agent/dns.html#connect-capable-service-lookups)
|
||||
syntax to find Connect-capable endpoints for a service. After service
|
||||
discovery, choose one address from the list of **service addresses**.
|
||||
|
||||
* **Mutual TLS** - As a client, connect to the discovered service address
|
||||
over normal TLS. As part of the TLS connection, provide the
|
||||
[service certificate](/api/agent/connect.html#service-leaf-certificate)
|
||||
as the client certificate. Verify the remote certificate against the
|
||||
[public CA roots](/api/agent/connect.html#certificate-authority-ca-roots).
|
||||
As a client, if the connection is established then you've established
|
||||
a Connect-based connection and there are no further steps!
|
||||
|
||||
* **Authorization** - As a server accepting connections, verify the client
|
||||
certificate against the
|
||||
[public CA roots](/api/agent/connect.html#certificate-authority-ca-roots).
|
||||
After verifying the certificate, parse some basic fields from it and call
|
||||
the [authorizing API](/api/agent/connect.html#authorize) against the local
|
||||
agent. If this returns successfully, complete the TLS handshake and establish
|
||||
the connection. If authorization fails, close the connection.
|
||||
|
||||
-> **A note on performance:** The only API call in the connection path is
|
||||
the [authorization API](/api/agent/connect.html#authorize). The other API
|
||||
calls to acquire the leaf certificate and CA roots are expected to be done
|
||||
out of band and reused. The authorize API call should be called against the
|
||||
local Consul agent. The agent uses locally cached
|
||||
data to authorize the connection and typically responds in microseconds.
|
||||
Therefore, the impact to the TLS handshake is typically microseconds.
|
||||
|
||||
## Updating Certificates and Certificate Roots
|
||||
|
||||
The leaf certificate and CA roots can be updated at any time and the
|
||||
natively integrated application must react to this relatively quickly
|
||||
so that new connections are not disrupted. This can be done through
|
||||
Consul blocking queries (HTTP long polling) or through periodic polling.
|
||||
|
||||
The API calls for
|
||||
[acquiring a leaf TLS certificate](/api/agent/connect.html#service-leaf-certificate)
|
||||
and [reading CA roots](/api/agent/connect.html#certificate-authority-ca-roots)
|
||||
both support
|
||||
[blocking queries](/api/index.html#blocking-queries). By using blocking
|
||||
queries, an application can efficiently wait for an updated value. For example,
|
||||
the leaf certificate API will block until the certificate is near expiration
|
||||
or the signing certificates have changed and will issue and return a new
|
||||
certificate.
|
||||
|
||||
In some languages, using blocking queries may not be simple. In that case,
|
||||
we still recommend using the blocking query parameters but with a very short
|
||||
`timeout` value set. Doing this is documented with
|
||||
[blocking queries](/api/index.html#blocking-queries). The low timeout will
|
||||
ensure the API responds quickly. We recommend that applications poll the
|
||||
certificate endpoints frequently, such as multiple times per minute.
|
||||
|
||||
The overhead for the blocking queries (long or periodic polling) is minimal.
|
||||
The API calls are to the local agent and the local agent uses locally
|
||||
cached data multiplexed over a single TCP connection to the Consul leader.
|
||||
Even if a single machine has 1,000 Connect-enabled services all blocking
|
||||
on certificate updates, this translates to only one TCP connection to the
|
||||
Consul server.
|
||||
|
||||
Some language libraries such as the
|
||||
[Go library](/docs/connect/native/go.html) automatically handle updating
|
||||
and locally caching the certificates.
|
||||
|
||||
## Service Registration
|
||||
|
||||
Connect-native applications must tell Consul that they support Connect
|
||||
natively. This enables the service to be returned as part of service
|
||||
discovery for Connect-capable services, used by other Connect-native applications
|
||||
and client [proxies](/docs/connect/proxies.html).
|
||||
|
||||
This can be specified directly in the [service definition](/docs/agent/services.html):
|
||||
|
||||
```json
|
||||
{
|
||||
"service": {
|
||||
"name": "redis",
|
||||
"port": 8000,
|
||||
"connect": {
|
||||
"native": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Services that support Connect natively are still returned through the standard
|
||||
service discovery mechanisms in addition to the Connect-only service discovery
|
||||
mechanisms.
|
||||
|
|
|
|||
|
|
@ -270,6 +270,11 @@
|
|||
</li>
|
||||
<li<%= sidebar_current("docs-connect-native") %>>
|
||||
<a href="/docs/connect/native.html">Native App Integration</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-connect-native-go") %>>
|
||||
<a href="/docs/connect/native/go.html">Go Integration</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-dev") %>>
|
||||
<a href="/docs/connect/dev.html">Develop and Debug</a>
|
||||
|
|
|
|||
Loading…
Reference in New Issue