github.com/outbrain/consul@v1.4.5/website/source/docs/connect/native.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Connect - Native Application Integration"
     4  sidebar_current: "docs-connect-native"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Connect-Native App Integration
    10  
    11  Applications can natively integrate with the Connect API to support
    12  accepting and establishing connections to other Connect services without
    13  the overhead of a [proxy sidecar](/docs/connect/proxies.html). This option 
    14  is especially useful for applications that may be experiencing performance issues 
    15  with the proxy sidecar deployment. This page will cover the high-level overview 
    16  of integration, registering the service, etc. For language-specific examples, 
    17  see the sidebar navigation to the left.
    18  
    19  Connect is just basic mutual TLS. This means that almost any application
    20  can easily integrate with Connect. There is no custom protocol in use;
    21  any language that supports TLS can accept and establish Connect-based
    22  connections.
    23  
    24  We currently provide an easy-to-use [Go integration](/docs/connect/native/go.html)
    25  to assist with the getting the proper certificates, verifying connections,
    26  etc. We plan to add helper libraries for other languages in the future.
    27  However, without library support, it is still possible for any major language
    28  to integrate with Connect.
    29  
    30  ## Overview
    31  
    32  The primary work involved in natively integrating with Connect is
    33  [acquiring the proper TLS certificate](/api/agent/connect.html#service-leaf-certificate),
    34  [verifying TLS certificates](/api/agent/connect.html#certificate-authority-ca-roots),
    35  and [authorizing inbound connections](/api/agent/connect.html#authorize).
    36  All of this is done using the Consul HTTP APIs linked above.
    37  
    38  An overview of the sequence is shown below. The diagram and the following
    39  details may seem complex, but this is a _regular mutual TLS connection_ with
    40  an API call to verify the incoming client certificate.
    41  
    42  <div class="center">
    43  ![Native Integration Overview](connect-native-overview.png)
    44  </div>
    45  
    46  Details on the steps are below:
    47  
    48    * **Service discovery** - This is normal service discovery using Consul,
    49      a static IP, or any other mechanism. If you're using Consul DNS, the
    50      [`<service>.connect`](/docs/agent/dns.html#connect-capable-service-lookups)
    51      syntax to find Connect-capable endpoints for a service. After service
    52      discovery, choose one address from the list of **service addresses**.
    53  
    54    * **Mutual TLS** - As a client, connect to the discovered service address
    55      over normal TLS. As part of the TLS connection, provide the
    56      [service certificate](/api/agent/connect.html#service-leaf-certificate)
    57      as the client certificate. Verify the remote certificate against the
    58      [public CA roots](/api/agent/connect.html#certificate-authority-ca-roots).
    59      As a client, if the connection is established then you've established
    60      a Connect-based connection and there are no further steps!
    61  
    62    * **Authorization** - As a server accepting connections, verify the client
    63      certificate against the
    64      [public CA roots](/api/agent/connect.html#certificate-authority-ca-roots).
    65      After verifying the certificate, parse some basic fields from it and call
    66      the [authorizing API](/api/agent/connect.html#authorize) against the local
    67      agent. If this returns successfully, complete the TLS handshake and establish
    68      the connection. If authorization fails, close the connection.
    69  
    70  -> **A note on performance:** The only API call in the connection path is
    71  the [authorization API](/api/agent/connect.html#authorize). The other API
    72  calls to acquire the leaf certificate and CA roots are expected to be done
    73  out of band and reused. The authorize API call should be called against the
    74  local Consul agent. The agent uses locally cached
    75  data to authorize the connection and typically responds in microseconds.
    76  Therefore, the impact to the TLS handshake is typically microseconds.
    77  
    78  ## Updating Certificates and Certificate Roots
    79  
    80  The leaf certificate and CA roots can be updated at any time and the
    81  natively integrated application must react to this relatively quickly
    82  so that new connections are not disrupted. This can be done through
    83  Consul blocking queries (HTTP long polling) or through periodic polling.
    84  
    85  The API calls for
    86  [acquiring a leaf TLS certificate](/api/agent/connect.html#service-leaf-certificate)
    87  and [reading CA roots](/api/agent/connect.html#certificate-authority-ca-roots)
    88  both support
    89  [blocking queries](/api/index.html#blocking-queries). By using blocking
    90  queries, an application can efficiently wait for an updated value. For example,
    91  the leaf certificate API will block until the certificate is near expiration
    92  or the signing certificates have changed and will issue and return a new
    93  certificate.
    94  
    95  In some languages, using blocking queries may not be simple. In that case,
    96  we still recommend using the blocking query parameters but with a very short
    97  `timeout` value set. Doing this is documented with
    98  [blocking queries](/api/index.html#blocking-queries). The low timeout will
    99  ensure the API responds quickly. We recommend that applications poll the
   100  certificate endpoints frequently, such as multiple times per minute.
   101  
   102  The overhead for the blocking queries (long or periodic polling) is minimal.
   103  The API calls are to the local agent and the local agent uses locally
   104  cached data multiplexed over a single TCP connection to the Consul leader.
   105  Even if a single machine has 1,000 Connect-enabled services all blocking
   106  on certificate updates, this translates to only one TCP connection to the
   107  Consul server.
   108  
   109  Some language libraries such as the
   110  [Go library](/docs/connect/native/go.html) automatically handle updating
   111  and locally caching the certificates.
   112  
   113  ## Service Registration
   114  
   115  Connect-native applications must tell Consul that they support Connect
   116  natively. This enables the service to be returned as part of service
   117  discovery for Connect-capable services, used by other Connect-native applications
   118  and client [proxies](/docs/connect/proxies.html).
   119  
   120  This can be specified directly in the [service definition](/docs/agent/services.html):
   121  
   122  ```json
   123  {
   124    "service": {
   125      "name": "redis",
   126      "port": 8000,
   127      "connect": {
   128        "native": true
   129      }
   130    }
   131  }
   132  ```
   133  
   134  Services that support Connect natively are still returned through the standard
   135  service discovery mechanisms in addition to the Connect-only service discovery
   136  mechanisms.