mirror of https://github.com/status-im/consul.git
Starting Docs (#46)
* website: first stab at Connect docs * website: lots more various stuff (bad commit messages) * website: getting started page for Connect * website: intentions * website: intention APIs * website: agent API docs * website: document agent/catalog proxy kind service values * website: /v1/catalog/connect/:service * website: intention CLI docs * website: custom proxy docs * website: remove dedicated getting started guide * website: add docs for CA API endpoints * website: add docs for connect ca commands * website: add proxy CLI docs * website: clean up proxy command, add dev docs * website: todo pages * website: connect security
This commit is contained in:
Mitchell Hashimoto
Jack Pearkes
parent
ab4a9a94f4
commit
097856c515
|
|
@ -0,0 +1,36 @@
|
|||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<dfxml xmloutputversion='1.0'>
|
||||
<metadata
|
||||
xmlns='http://afflib.org/tcpflow/'
|
||||
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
||||
xmlns:dc='http://purl.org/dc/elements/1.1/'>
|
||||
<dc:type>Feature Extraction</dc:type>
|
||||
</metadata>
|
||||
<creator version='1.0'>
|
||||
<program>TCPFLOW</program>
|
||||
<version>1.4.5</version>
|
||||
<build_environment>
|
||||
<compiler>4.2.1 (4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.37))</compiler>
|
||||
<CPPFLAGS>-D_THREAD_SAFE -pthread -I/usr/local/include -I/usr/local/include -DUTC_OFFSET=+0100 </CPPFLAGS>
|
||||
<CFLAGS>-g -D_THREAD_SAFE -pthread -g -O3 -MD -Wpointer-arith -Wmissing-declarations -Wmissing-prototypes -Wshadow -Wwrite-strings -Wcast-align -Waggregate-return -Wbad-function-cast -Wcast-qual -Wundef -Wredundant-decls -Wdisabled-optimization -Wfloat-equal -Wmultichar -Wc++-compat -Wmissing-noreturn -Wall -Wstrict-prototypes -MD -D_FORTIFY_SOURCE=2 -Wpointer-arith -Wmissing-declarations -Wmissing-prototypes -Wshadow -Wwrite-strings -Wcast-align -Waggregate-return -Wbad-function-cast -Wcast-qual -Wundef -Wredundant-decls -Wdisabled-optimization -Wfloat-equal -Wmultichar -Wc++-compat -Wmissing-noreturn -Wall -Wstrict-prototypes</CFLAGS>
|
||||
<CXXFLAGS>-g -D_THREAD_SAFE -pthread -g -O3 -Wall -MD -D_FORTIFY_SOURCE=2 -Wpointer-arith -Wshadow -Wwrite-strings -Wcast-align -Wredundant-decls -Wdisabled-optimization -Wfloat-equal -Wmultichar -Wmissing-noreturn -Woverloaded-virtual -Wsign-promo -funit-at-a-time -Weffc++ -std=c++11 -Wall -MD -D_FORTIFY_SOURCE=2 -Wpointer-arith -Wshadow -Wwrite-strings -Wcast-align -Wredundant-decls -Wdisabled-optimization -Wfloat-equal -Wmultichar -Wmissing-noreturn -Woverloaded-virtual -Wsign-promo -funit-at-a-time -Weffc++ </CXXFLAGS>
|
||||
<LDFLAGS>-L/usr/local/lib -L/usr/local/lib </LDFLAGS>
|
||||
<LIBS>-lpcap -lbz2 -lexpat -lsqlite3 -lssl -lcrypto -lssl -lcrypto -ldl -lz </LIBS>
|
||||
<compilation_date>2017-09-21T17:38:31</compilation_date>
|
||||
<library name="boost" version="106501"/>
|
||||
<library name="sqlite" version="3.19.3" source_id="2017-06-27 16:48:08 2b0954060fe10d6de6d479287dd88890f1bef6cc1beca11bc6cdb79f72e2377b"/>
|
||||
</build_environment>
|
||||
<execution_environment>
|
||||
<os_sysname>Darwin</os_sysname>
|
||||
<os_release>17.5.0</os_release>
|
||||
<os_version>Darwin Kernel Version 17.5.0: Fri Apr 13 19:32:32 PDT 2018; root:xnu-4570.51.2~1/RELEASE_X86_64</os_version>
|
||||
<host>Mitchells-MacBook-Pro.local</host>
|
||||
<arch>x86_64</arch>
|
||||
<command_line>tcpflow -i lo0 -c port 8181</command_line>
|
||||
<uid>0</uid>
|
||||
<start_time>2018-05-23T20:06:07Z</start_time>
|
||||
</execution_environment>
|
||||
</creator>
|
||||
<configuration>
|
||||
</configuration>
|
||||
<tdelta>0</tdelta>
|
||||
|
|
@ -0,0 +1,293 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Connect - Agent - HTTP API
|
||||
sidebar_current: api-agent-connect
|
||||
description: |-
|
||||
The /agent/connect endpoints interact with Connect with agent-local operations.
|
||||
---
|
||||
|
||||
# Connect - Agent HTTP API
|
||||
|
||||
The `/agent/connect` endpoints interact with [Connect](/docs/connect/index.html)
|
||||
with agent-local operations.
|
||||
|
||||
These endpoints may mirror the [non-agent Connect endpoints](/api/connect.html)
|
||||
in some cases. Almost all agent-local Connect endpoints perform local caching
|
||||
to optimize performance of Connect without having to make requests to the server.
|
||||
|
||||
## Authorize
|
||||
|
||||
This endpoint tests whether a connection attempt is authorized between
|
||||
two services. This is the primary API that must be implemented by
|
||||
[proxies](/docs/connect/proxies.html) or
|
||||
[native integrations](/docs/connect/native.html)
|
||||
that wish to integrate with Connect. Prior to calling this API, it is expected
|
||||
that the client TLS certificate has been properly verified against the
|
||||
current CA roots.
|
||||
|
||||
The implementation of this API uses locally cached data
|
||||
and doesn't require any request forwarding to a server. Therefore, the
|
||||
response typically occurs in microseconds to impose minimal overhead on the
|
||||
connection attempt.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/agent/connect/authorize` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------------------ |
|
||||
| `NO` | `none` | `service:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Target` `(string: <required>)` - The name of the service that is being
|
||||
requested.
|
||||
|
||||
- `ClientCertURI` `(string: <required>)` - The unique identifier for the
|
||||
requesting client. This is currently the URI SAN from the TLS client
|
||||
certificate.
|
||||
|
||||
- `ClientCertSerial` `(string: <required>)` - The colon-hex-encoded serial
|
||||
number for the requesting client cert. This is used to check against
|
||||
revocation lists.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Target": "db",
|
||||
"ClientCertURI": "spiffe://dc1-7e567ac2-551d-463f-8497-f78972856fc1.consul/ns/default/dc/dc1/svc/web",
|
||||
"ClientCertSerial": "04:00:00:00:00:01:15:4b:5a:c3:94"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://consul.rocks/v1/agent/connect/authorize
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Authorized": true,
|
||||
"Reason": "Matched intention: web => db (allow)"
|
||||
}
|
||||
```
|
||||
|
||||
## Certificate Authority (CA) Roots
|
||||
|
||||
This endpoint returns the trusted certificate authority (CA) root certificates.
|
||||
This is used by [proxies](/docs/connect/proxies.html) or
|
||||
[native integrations](/docs/connect/native.html) to verify served client
|
||||
or server certificates are valid.
|
||||
|
||||
This is equivalent to the [non-Agent Connect endpoint](/api/connect.html),
|
||||
but the response of this request is cached locally at the agent. This allows
|
||||
for very fast response times and for fail open behavior if the server is
|
||||
unavailable. This endpoint should be used by proxies and native integrations.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/agent/connect/ca/roots` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | -------------------------- |
|
||||
| `YES` | `all` | `none` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/ca/roots
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ActiveRootID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7",
|
||||
"Roots": [
|
||||
{
|
||||
"ID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7",
|
||||
"Name": "Consul CA Root Cert",
|
||||
"SerialNumber": 7,
|
||||
"SigningKeyID": "31:66:3a:39:31:3a:63:61:3a:34:31:3a:38:66:3a:61:63:3a:36:37:3a:62:66:3a:35:39:3a:63:32:3a:66:61:3a:34:65:3a:37:35:3a:35:63:3a:64:38:3a:66:30:3a:35:35:3a:64:65:3a:62:65:3a:37:35:3a:62:38:3a:33:33:3a:33:31:3a:64:35:3a:32:34:3a:62:30:3a:30:34:3a:62:33:3a:65:38:3a:39:37:3a:35:62:3a:37:65",
|
||||
"NotBefore": "2018-05-21T16:33:28Z",
|
||||
"NotAfter": "2028-05-18T16:33:28Z",
|
||||
"RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0yODA1MTgxNjMzMjhaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAER0qlxjnRcMEr\niSGlH7G7dYU7lzBEmLUSMZkyBbClmyV8+e8WANemjn+PLnCr40If9cmpr7RnC9Qk\nGTaLnLiF16OCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1OTpjMjpmYTo0ZTo3\nNTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToyNDpiMDowNDpiMzpl\nODo5Nzo1Yjo3ZTBqBgNVHSMEYzBhgF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1\nOTpjMjpmYTo0ZTo3NTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToy\nNDpiMDowNDpiMzplODo5Nzo1Yjo3ZTA/BgNVHREEODA2hjRzcGlmZmU6Ly8xMjRk\nZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgisxMjRkZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIQDzkkI7R+0U12a+zq2EQhP/n2mHmta+\nfs2hBxWIELGwTAIgLdO7RRw+z9nnxCIA6kNl//mIQb+PGItespiHZKAz74Q=\n-----END CERTIFICATE-----\n",
|
||||
"IntermediateCerts": null,
|
||||
"Active": true,
|
||||
"CreateIndex": 8,
|
||||
"ModifyIndex": 8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Service Leaf Certificate
|
||||
|
||||
This endpoint returns the leaf certificate representing a single service.
|
||||
This certificate is used as a server certificate for accepting inbound
|
||||
connections and is also used as the client certificate for establishing
|
||||
outbound connections to other services.
|
||||
|
||||
The agent generates a CSR locally and calls the
|
||||
[CA sign API](/api/connect/ca.html) to sign it. The resulting certificate
|
||||
is cached and returned by this API until it is near expiry or the root
|
||||
certificates change.
|
||||
|
||||
This API supports blocking queries. The blocking query will block until
|
||||
a new certificate is necessary because the existing certificate will expire
|
||||
or the root certificate is being rotated. This blocking behavior allows
|
||||
clients to efficiently wait for certificate rotations.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | -------------------------- |
|
||||
| `YES` | `all` | `service:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Service` `(string: <required>)` - The name of the service for the leaf
|
||||
certificate. This is specified in the URL. The service does not need to
|
||||
exist in the catalog, but the proper ACL permissions must be available.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/ca/leaf/web
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"SerialNumber": "08",
|
||||
"CertPEM": "-----BEGIN CERTIFICATE-----\nMIIChjCCAi2gAwIBAgIBCDAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0xODA1MjQxNjMzMjhaMA4xDDAKBgNVBAMT\nA3dlYjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJdLqRKd1SRycFOFceMHOBZK\nQW8HHO8jZ5C8dRswD+IwTd/otJPiaPrVzGOAi4MsaEUgDMemvN1jiywHt3II08mj\nggFyMIIBbjAOBgNVHQ8BAf8EBAMCA7gwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsG\nAQUFBwMBMAwGA1UdEwEB/wQCMAAwaAYDVR0OBGEEXzFmOjkxOmNhOjQxOjhmOmFj\nOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRlOmJlOjc1OmI4OjMz\nOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMGoGA1UdIwRjMGGAXzFmOjkx\nOmNhOjQxOjhmOmFjOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRl\nOmJlOjc1OmI4OjMzOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMFkGA1Ud\nEQRSMFCGTnNwaWZmZTovLzExMTExMTExLTIyMjItMzMzMy00NDQ0LTU1NTU1NTU1\nNTU1NS5jb25zdWwvbnMvZGVmYXVsdC9kYy9kYzEvc3ZjL3dlYjAKBggqhkjOPQQD\nAgNHADBEAiBS8kH3UERhBPHM/CQV/jXKLr0kReLqCdq1jZxc8Aq7hQIgFIus/ZX0\nOM/X3Yc1xb/qJiiEVzXcaz3oVFULOzrNAwk=\n-----END CERTIFICATE-----\n",
|
||||
"PrivateKeyPEM": "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIAOGglbwY8HdD3LFX6Bc94co2pzeFTto8ebWoML5E+QfoAoGCCqGSM49\nAwEHoUQDQgAEl0upEp3VJHJwU4Vx4wc4FkpBbwcc7yNnkLx1GzAP4jBN3+i0k+Jo\n+tXMY4CLgyxoRSAMx6a83WOLLAe3cgjTyQ==\n-----END EC PRIVATE KEY-----\n",
|
||||
"Service": "web",
|
||||
"ServiceURI": "spiffe://11111111-2222-3333-4444-555555555555.consul/ns/default/dc/dc1/svc/web",
|
||||
"ValidAfter": "2018-05-21T16:33:28Z",
|
||||
"ValidBefore": "2018-05-24T16:33:28Z",
|
||||
"CreateIndex": 5,
|
||||
"ModifyIndex": 5
|
||||
}
|
||||
```
|
||||
|
||||
- `SerialNumber` `string` - Monotonically increasing 64-bit serial number
|
||||
representing all certificates issued by this Consul cluster.
|
||||
|
||||
- `CertPEM` `(string)` - The PEM-encoded certificate.
|
||||
|
||||
- `PrivateKeyPEM` `(string)` - The PEM-encoded private key for this certificate.
|
||||
|
||||
- `Service` `(string)` - The name of the service that this certificate identifies.
|
||||
|
||||
- `ServiceURI` `(string)` - The URI SAN for this service.
|
||||
|
||||
- `ValidAfter` `(string)` - The time after which the certificate is valid.
|
||||
Used with `ValidBefore` this can determine the validity period of the certificate.
|
||||
|
||||
- `ValidBefore` `(string)` - The time before which the certificate is valid.
|
||||
Used with `ValidAfter` this can determine the validity period of the certificate.
|
||||
|
||||
## Managed Proxy Configuration
|
||||
|
||||
This endpoint returns the configuration for a
|
||||
[managed proxy](/docs/connect/proxies.html).
|
||||
Ths endpoint is only useful for _managed proxies_ and not relevant
|
||||
for unmanaged proxies.
|
||||
|
||||
Managed proxy configuration is set in the service definition. When Consul
|
||||
starts the managed proxy, it provides the service ID and ACL token. The proxy
|
||||
is expected to call this endpoint to retrieve its configuration. It may use
|
||||
a blocking query to detect any configuration changes.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/agent/connect/proxy/:id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | -------------------------- |
|
||||
| `YES` | `all` | `service:write, proxy token` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `ID` `(string: <required>)` - The ID (not the name) of the proxy service
|
||||
in the local agent catalog. For managed proxies, this is provided in the
|
||||
`CONSUL_PROXY_ID` environment variable by Consul.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/proxy/web-proxy
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ProxyServiceID": "web-proxy",
|
||||
"TargetServiceID": "web",
|
||||
"TargetServiceName": "web",
|
||||
"ContentHash": "cffa5f4635b134b9",
|
||||
"ExecMode": "daemon",
|
||||
"Command": [
|
||||
"/usr/local/bin/consul",
|
||||
"connect",
|
||||
"proxy"
|
||||
],
|
||||
"Config": {
|
||||
"bind_address": "127.0.0.1",
|
||||
"bind_port": 20199,
|
||||
"local_service_address": "127.0.0.1:8181"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `ProxyServiceID` `string` - The ID of the proxy service.
|
||||
|
||||
- `TargetServiceID` `(string)` - The ID of the target service the proxy represents.
|
||||
|
||||
- `TargetServiceName` `(string)` - The name of the target service the proxy represents.
|
||||
|
||||
- `ContentHash` `(string)` - The content hash of the response used for hash-based
|
||||
blocking queries.
|
||||
|
||||
- `ExecMode` `(string)` - The execution mode of the managed proxy.
|
||||
|
||||
- `Command` `(array<string>)` - The command for the managed proxy.
|
||||
|
||||
- `Config` `(map<string|any>)` - The configuration for the managed proxy. This
|
||||
is a map of primitive values (including arrays and maps) that is set by the
|
||||
user.
|
||||
|
|
@ -70,6 +70,9 @@ The agent is responsible for managing the status of its local services, and for
|
|||
sending updates about its local services to the servers to keep the global
|
||||
catalog in sync.
|
||||
|
||||
For "connect-proxy" kind services, the `service:write` ACL for the
|
||||
`ProxyDestination` value is also required to register the service.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `PUT` | `/agent/service/register` | `application/json` |
|
||||
|
|
@ -104,6 +107,16 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `Port` `(int: 0)` - Specifies the port of the service.
|
||||
|
||||
- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
|
||||
typical Consul service. This value may also be "connect-proxy" for
|
||||
services that are [Connect-capable](/docs/connect/index.html)
|
||||
proxies representing another service.
|
||||
|
||||
- `ProxyDestination` `(string: "")` - For "connect-proxy" `Kind` services,
|
||||
this must be set to the name of the service that the proxy represents. This
|
||||
service doesn't need to be registered, but the caller must have an ACL token
|
||||
with permissions for this service.
|
||||
|
||||
- `Check` `(Check: nil)` - Specifies a check. Please see the
|
||||
[check documentation](/api/agent/check.html) for more information about the
|
||||
accepted fields. If you don't provide a name or id for the check then they
|
||||
|
|
|
|||
|
|
@ -479,6 +479,86 @@ $ curl \
|
|||
|
||||
- `ServiceTags` is a list of tags for the service
|
||||
|
||||
- `ServiceKind` is the kind of service, usually "". See the Agent
|
||||
registration API for more information.
|
||||
|
||||
- `ServiceProxyDestination` is the name of the service that is being proxied,
|
||||
for "connect-proxy" type services.
|
||||
|
||||
## List Nodes for Connect-capable Service
|
||||
|
||||
This endpoint returns the nodes providing a
|
||||
[Connect-capable](/docs/connect/index.html) service in a given datacenter.
|
||||
This will include both proxies and native integrations. A service may
|
||||
register both Connect-capable and incapable services at the same time,
|
||||
so this endpoint may be used to filter only the Connect-capable endpoints.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/catalog/connect/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------------------ |
|
||||
| `YES` | `all` | `node:read,service:read` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `service` `(string: <required>)` - Specifies the name of the service for which
|
||||
to list nodes. This is specified as part of the URL.
|
||||
|
||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
||||
the datacenter of the agent being queried. This is specified as part of the
|
||||
URL as a query parameter.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/catalog/connect/my-service
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
||||
"Node": "foobar",
|
||||
"Address": "192.168.10.10",
|
||||
"Datacenter": "dc1",
|
||||
"TaggedAddresses": {
|
||||
"lan": "192.168.10.10",
|
||||
"wan": "10.0.10.10"
|
||||
},
|
||||
"NodeMeta": {
|
||||
"somekey": "somevalue"
|
||||
},
|
||||
"CreateIndex": 51,
|
||||
"ModifyIndex": 51,
|
||||
"ServiceAddress": "172.17.0.3",
|
||||
"ServiceEnableTagOverride": false,
|
||||
"ServiceID": "32a2a47f7992:nodea:5000",
|
||||
"ServiceName": "foobar",
|
||||
"ServiceKind": "connect-proxy",
|
||||
"ServiceProxyDestination": "my-service",
|
||||
"ServicePort": 5000,
|
||||
"ServiceMeta": {
|
||||
"foobar_meta_value": "baz"
|
||||
},
|
||||
"ServiceTags": [
|
||||
"tacos"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
The fields are the same as listing nodes for a service.
|
||||
|
||||
## List Services for Node
|
||||
|
||||
This endpoint returns the node's registered services.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Connect - HTTP API
|
||||
sidebar_current: api-connect
|
||||
description: |-
|
||||
The `/connect` endpoints provide access to Connect-related operations for intentions and the certificate authority.
|
||||
---
|
||||
|
||||
# Connect HTTP Endpoint
|
||||
|
||||
The `/connect` endpoints provide access to
|
||||
[Connect-related](/docs/connect/index.html) operations for
|
||||
intentions and the certificate authority.
|
||||
|
||||
There are also Connect-related endpoints in the
|
||||
[Agent](/api/agent.html) and [Catalog](/api/catalog.html) APIs. For example,
|
||||
the API for requesting a TLS certificate for a service is part of the agent
|
||||
APIs. And the catalog API has an endpoint for finding all Connect-capable
|
||||
services in the catalog.
|
||||
|
||||
Please choose a sub-section in the navigation for more information.
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Certificate Authority - Connect - HTTP API
|
||||
sidebar_current: api-connect-ca
|
||||
description: |-
|
||||
The /connect/ca endpoints provide tools for interacting with Connect's
|
||||
Certificate Authority mechanism via Consul's HTTP API.
|
||||
---
|
||||
|
||||
# Certificate Authority (CA) - Connect HTTP API
|
||||
|
||||
The `/connect/ca` endpoints provide tools for interacting with Connect's
|
||||
Certificate Authority mechanism.
|
||||
|
||||
## List CA Root Certificates
|
||||
|
||||
This endpoint returns the current list of trusted CA root certificates in
|
||||
the cluster.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/connect/ca/roots` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------- |
|
||||
| `YES` | `all` | `operator:read` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/ca/roots
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ActiveRootID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
|
||||
"TrustDomain": "7f42f496-fbc7-8692-05ed-334aa5340c1e.consul",
|
||||
"Roots": [
|
||||
{
|
||||
"ID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
|
||||
"Name": "Consul CA Root Cert",
|
||||
"SerialNumber": 7,
|
||||
"SigningKeyID": "32:64:3a:30:39:3a:35:64:3a:38:34:3a:62:39:3a:38:39:3a:34:62:3a:64:64:3a:65:33:3a:38:38:3a:62:62:3a:39:63:3a:65:32:3a:62:32:3a:36:39:3a:38:31:3a:31:66:3a:34:62:3a:61:36:3a:66:64:3a:34:64:3a:64:66:3a:65:65:3a:37:34:3a:36:33:3a:66:33:3a:37:34:3a:35:35:3a:63:61:3a:62:30:3a:62:35:3a:36:35",
|
||||
"NotBefore": "2018-05-25T21:39:23Z",
|
||||
"NotAfter": "2028-05-22T21:39:23Z",
|
||||
"RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjUyMTM5MjNaFw0yODA1MjIyMTM5MjNaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEq4S32Pu0/VL4\nG75gvdyQuAhqMZFsfBRwD3pgvblgZMeJc9KDosxnPR+W34NXtMD/860NNVJIILln\n9lLhIjWPQqOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDplMzo4ODpiYjo5Yzpl\nMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2MzpmMzo3NDo1NTpj\nYTpiMDpiNTo2NTBqBgNVHSMEYzBhgF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDpl\nMzo4ODpiYjo5YzplMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2\nMzpmMzo3NDo1NTpjYTpiMDpiNTo2NTA/BgNVHREEODA2hjRzcGlmZmU6Ly83ZjQy\nZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgis3ZjQyZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIBBBDOWXWApx4S6bHJ49AW87Nw8uQ/gJ\nJ6lvm3HzEQw2AiEA4PVqWt+z8fsQht0cACM42kghL97SgDSf8rgCqfLYMng=\n-----END CERTIFICATE-----\n",
|
||||
"IntermediateCerts": null,
|
||||
"Active": true,
|
||||
"CreateIndex": 8,
|
||||
"ModifyIndex": 8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Get CA Configuration
|
||||
|
||||
This endpoint returns the current CA configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/connect/ca/configuration` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | --------------- |
|
||||
| `YES` | `all` | `operator:read` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/ca/configuration
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Provider": "consul",
|
||||
"Config": {
|
||||
"PrivateKey": null,
|
||||
"RootCert": null,
|
||||
"RotationPeriod": "2160h"
|
||||
},
|
||||
"CreateIndex": 5,
|
||||
"ModifyIndex": 5
|
||||
}
|
||||
```
|
||||
|
||||
## Update CA Configuration
|
||||
|
||||
This endpoint updates the configuration for the CA. If this results in a
|
||||
new root certificate being used, the [Root Rotation]
|
||||
(/docs/guides/connect-ca.html#rotation) process will be triggered.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `PUT` | `/connect/ca/configuration` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | --------------- |
|
||||
| `NO` | `none` | `operator:write`|
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Provider` `(string: <required>)` - Specifies the CA provider type to use.
|
||||
|
||||
- `Config` `(map[string]string: <required>)` - The raw configuration to use
|
||||
for the chosen provider. For more information on configuring the Connect CA
|
||||
providers, see [Provider Config](/docs/connect/ca.html).
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Provider": "consul",
|
||||
"Config": {
|
||||
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----...",
|
||||
"RootCert": "-----BEGIN CERTIFICATE-----...",
|
||||
"RotationPeriod": "720h"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://consul.rocks/v1/connect/ca/configuration
|
||||
```
|
||||
|
|
@ -0,0 +1,383 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Intentions - Connect - HTTP API
|
||||
sidebar_current: api-connect-intentions
|
||||
description: |-
|
||||
The /connect/intentions endpoint provide tools for managing intentions via
|
||||
Consul's HTTP API.
|
||||
---
|
||||
|
||||
# Intentions - Connect HTTP API
|
||||
|
||||
The `/connect/intentions` endpoint provide tools for managing
|
||||
[intentions](/docs/connect/intentions.html).
|
||||
|
||||
## Create Intention
|
||||
|
||||
This endpoint creates a new intention and returns its ID if it was created
|
||||
successfully.
|
||||
|
||||
The name and destination pair must be unique. If another intention matches
|
||||
the name and destination, the creation will fail. You must either update the
|
||||
existing intention or delete it prior to creating a new one.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/connect/intentions` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------- |
|
||||
| `NO` | `none` | `service:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `SourceName` `(string: <required>)` - The source of the intention.
|
||||
For a `SourceType` of `consul` this is the name of a Consul service. The
|
||||
service doesn't need to be registered.
|
||||
|
||||
- `DestinationName` `(string: <required>)` - The destination of the intention.
|
||||
The intention destination is always a Consul service, unlike the source.
|
||||
The service doesn't need to be registered.
|
||||
|
||||
- `SourceType` `(string: <required>)` - The type for the `SourceName` value.
|
||||
This can be only "consul" today to represent a Consul service.
|
||||
|
||||
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
|
||||
the action that should be taken if this intention matches a request.
|
||||
|
||||
- `Description` `(string: nil)` - Description for the intention. This is not
|
||||
used for anything by Consul, but is presented in API responses to assist
|
||||
tooling.
|
||||
|
||||
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"SourceName": "web",
|
||||
"DestinationName": "db",
|
||||
"SourceType": "consul",
|
||||
"Action": "allow"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://consul.rocks/v1/connect/intentions
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
|
||||
}
|
||||
```
|
||||
|
||||
## Read Specific Intention
|
||||
|
||||
This endpoint reads a specific intention.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | --------------- |
|
||||
| `YES` | `all` | `service:read` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
||||
"Description": "",
|
||||
"SourceNS": "default",
|
||||
"SourceName": "web",
|
||||
"DestinationNS": "default",
|
||||
"DestinationName": "db",
|
||||
"SourceType": "consul",
|
||||
"Action": "allow",
|
||||
"DefaultAddr": "",
|
||||
"DefaultPort": 0,
|
||||
"Meta": {},
|
||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
||||
"CreateIndex": 11,
|
||||
"ModifyIndex": 11
|
||||
}
|
||||
```
|
||||
|
||||
## List Intentions
|
||||
|
||||
This endpoint lists all intentions.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/connect/intentions` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | --------------- |
|
||||
| `YES` | `all` | `service:read` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/intentions
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
||||
"Description": "",
|
||||
"SourceNS": "default",
|
||||
"SourceName": "web",
|
||||
"DestinationNS": "default",
|
||||
"DestinationName": "db",
|
||||
"SourceType": "consul",
|
||||
"Action": "allow",
|
||||
"DefaultAddr": "",
|
||||
"DefaultPort": 0,
|
||||
"Meta": {},
|
||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
||||
"CreateIndex": 11,
|
||||
"ModifyIndex": 11
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Update Intention
|
||||
|
||||
This endpoint updates an intention with the given values.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------- |
|
||||
| `NO` | `none` | `service:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
|
||||
is specified as part of the URL.
|
||||
|
||||
- Other parameters are identical to creating an intention.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"SourceName": "web",
|
||||
"DestinationName": "other-db",
|
||||
"SourceType": "consul",
|
||||
"Action": "allow"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data @payload.json \
|
||||
https://consul.rocks/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
||||
```
|
||||
|
||||
## Delete Intention
|
||||
|
||||
This endpoint deletes a specific intention.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| `DELETE` | `/connect/intentions/:uuid` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------- |
|
||||
| `NO` | `none` | `service:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to delete. This
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
https://consul.rocks/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
||||
```
|
||||
|
||||
## Check Intention Result
|
||||
|
||||
This endpoint evaluates the intentions for a specific source and destination
|
||||
and returns whether the connection would be authorized or not given the
|
||||
current Consul configuration and set of intentions.
|
||||
|
||||
This endpoint will work even if the destination service has
|
||||
`intention = "deny"` specifically set, because the resulting API response
|
||||
does not contain any information about the intention itself.
|
||||
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/connect/intentions/check` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------- |
|
||||
| `NO` | `none` | `service:read` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `source` `(string: <required>)` - Specifies the source service. This
|
||||
is specified as part of the URL.
|
||||
|
||||
- `destination` `(string: <required>)` - Specifies the destination service. This
|
||||
is specified as part of the URL.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/intentions/check?source=web&destination=db
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Allowed": true
|
||||
}
|
||||
```
|
||||
|
||||
- `Allowed` is true if the connection would be allowed, false otherwise.
|
||||
|
||||
## List Matching Intentions
|
||||
|
||||
This endpoint lists the intentions that match a given source or destination.
|
||||
The intentions in the response are in evaluation order.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------ | -------------------------- |
|
||||
| `GET` | `/connect/intentions/match` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries),
|
||||
[consistency modes](/api/index.html#consistency-modes), and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | --------------- |
|
||||
| `NO` | `none` | `service:read` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `by` `(string: <required>)` - Specifies whether to match the "name" value
|
||||
by "source" or "destination".
|
||||
|
||||
- `name` `(string: <required>)` - Specifies a name to match. This parameter
|
||||
can be repeated for batching multiple matches.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://consul.rocks/v1/connect/intentions/match?by=source&name=web
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"web": [
|
||||
{
|
||||
"ID": "ed16f6a6-d863-1bec-af45-96bbdcbe02be",
|
||||
"Description": "",
|
||||
"SourceNS": "default",
|
||||
"SourceName": "web",
|
||||
"DestinationNS": "default",
|
||||
"DestinationName": "db",
|
||||
"SourceType": "consul",
|
||||
"Action": "deny",
|
||||
"DefaultAddr": "",
|
||||
"DefaultPort": 0,
|
||||
"Meta": {},
|
||||
"CreatedAt": "2018-05-21T16:41:33.296693825Z",
|
||||
"UpdatedAt": "2018-05-21T16:41:33.296694288Z",
|
||||
"CreateIndex": 12,
|
||||
"ModifyIndex": 12
|
||||
},
|
||||
{
|
||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
||||
"Description": "",
|
||||
"SourceNS": "default",
|
||||
"SourceName": "web",
|
||||
"DestinationNS": "default",
|
||||
"DestinationName": "*",
|
||||
"SourceType": "consul",
|
||||
"Action": "allow",
|
||||
"DefaultAddr": "",
|
||||
"DefaultPort": 0,
|
||||
"Meta": {},
|
||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
||||
"CreateIndex": 11,
|
||||
"ModifyIndex": 11
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -60,7 +60,7 @@
|
|||
h3,
|
||||
h4 {
|
||||
color: $body-font-color;
|
||||
margin-top: 54px;
|
||||
margin-top: 35px;
|
||||
margin-bottom: $font-size;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -57,8 +57,8 @@ we can instead use `foo.node.consul.` This convention allows for terse
|
|||
syntax where appropriate while supporting queries of nodes in remote
|
||||
datacenters as necessary.
|
||||
|
||||
For a node lookup, the only records returned are A and AAAA records
|
||||
containing the IP address, and TXT records containing the
|
||||
For a node lookup, the only records returned are A and AAAA records
|
||||
containing the IP address, and TXT records containing the
|
||||
`node_meta` values of the node.
|
||||
|
||||
```text
|
||||
|
|
@ -85,9 +85,9 @@ foo.node.consul. 0 IN TXT "value only"
|
|||
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
|
||||
```
|
||||
|
||||
By default the TXT records value will match the node's metadata key-value
|
||||
pairs according to [RFC1464](https://www.ietf.org/rfc/rfc1464.txt).
|
||||
Alternatively, the TXT record will only include the node's metadata value when the
|
||||
By default the TXT records value will match the node's metadata key-value
|
||||
pairs according to [RFC1464](https://www.ietf.org/rfc/rfc1464.txt).
|
||||
Alternatively, the TXT record will only include the node's metadata value when the
|
||||
node's metadata key starts with `rfc1035-`.
|
||||
|
||||
## Service Lookups
|
||||
|
|
@ -207,6 +207,27 @@ Both A and SRV records are supported. SRV records provide the port that a servic
|
|||
registered on, enabling clients to avoid relying on well-known ports. SRV records are
|
||||
only served if the client specifically requests them.
|
||||
|
||||
### Connect-Capable Service Lookups
|
||||
|
||||
To find Connect-capable services:
|
||||
|
||||
<service>.connect.<domain>
|
||||
|
||||
This will find all [Connect-capable](/docs/connect/index.html)
|
||||
endpoints for the given `service`. A Connect-capable endpoint may be
|
||||
both a proxy for a service or a natively integrated Connect application.
|
||||
The DNS interface does not differentiate the two.
|
||||
|
||||
Most services will use a [proxy](/docs/connect/proxies.html) that handles
|
||||
service discovery automatically and therefore won't use this DNS format.
|
||||
This DNS format is primarily useful for [Connect-native](/docs/connect/native.html)
|
||||
applications.
|
||||
|
||||
This endpoint currently only finds services within the same datacenter
|
||||
and doesn't support tags. This DNS interface will be expanded over time.
|
||||
If you need more complex behavior, please use the
|
||||
[catalog API](/api/catalog.html).
|
||||
|
||||
### UDP Based DNS Queries
|
||||
|
||||
When the DNS query is performed using UDP, Consul will truncate the results
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Connect"
|
||||
sidebar_current: "docs-commands-connect"
|
||||
---
|
||||
|
||||
# Consul Connect
|
||||
|
||||
Command: `consul connect`
|
||||
|
||||
The `connect` command is used to interact with Connect
|
||||
[Connect](/docs/connect/intentions.html) subsystems. It exposes commands for
|
||||
running the built-in mTLS proxy and viewing/updating the Certificate Authority
|
||||
(CA) configuration. This command is available in Consul 1.2 and later.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul connect <subcommand>`
|
||||
|
||||
For the exact documentation for your Consul version, run `consul connect -h` to view
|
||||
the complete list of subcommands.
|
||||
|
||||
```text
|
||||
Usage: consul connect <subcommand> [options] [args]
|
||||
|
||||
This command has subcommands for interacting with Consul Connect.
|
||||
|
||||
Here are some simple examples, and more detailed examples are available
|
||||
in the subcommands or the documentation.
|
||||
|
||||
Run the built-in Connect mTLS proxy
|
||||
|
||||
$ consul connect proxy
|
||||
|
||||
For more examples, ask for subcommand help or view the documentation.
|
||||
|
||||
Subcommands:
|
||||
ca Interact with the Consul Connect Certificate Authority (CA)
|
||||
proxy Runs a Consul Connect proxy
|
||||
```
|
||||
|
||||
For more information, examples, and usage about a subcommand, click on the name
|
||||
of the subcommand in the sidebar.
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Connect CA"
|
||||
sidebar_current: "docs-commands-connect-ca"
|
||||
description: >
|
||||
The connect CA subcommand is used to view and modify the Connect Certificate
|
||||
Authority (CA) configuration.
|
||||
---
|
||||
|
||||
# Consul Connect Certificate Authority (CA)
|
||||
|
||||
Command: `consul connect ca`
|
||||
|
||||
The CA connect command is used to interact with Consul Connect's Certificate Authority
|
||||
subsystem. The command can be used to view or modify the current CA configuration. See the
|
||||
[Connect CA Guide](/docs/guides/connect-ca.html) for more information.
|
||||
|
||||
```text
|
||||
Usage: consul connect ca <subcommand> [options] [args]
|
||||
|
||||
This command has subcommands for interacting with Consul Connect's
|
||||
Certificate Authority (CA).
|
||||
|
||||
Here are some simple examples, and more detailed examples are available
|
||||
in the subcommands or the documentation.
|
||||
|
||||
Get the configuration:
|
||||
|
||||
$ consul connect ca get-config
|
||||
|
||||
Update the configuration:
|
||||
|
||||
$ consul connect ca set-config -config-file ca.json
|
||||
|
||||
For more examples, ask for subcommand help or view the documentation.
|
||||
|
||||
Subcommands:
|
||||
get-config Display the current Connect Certificate Authority (CA) configuration
|
||||
set-config Modify the current Connect CA configuration
|
||||
```
|
||||
|
||||
## get-config
|
||||
|
||||
This command displays the current CA configuration.
|
||||
|
||||
Usage: `consul connect ca get-config [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
<%= partial "docs/commands/http_api_options_server" %>
|
||||
|
||||
The output looks like this:
|
||||
|
||||
```
|
||||
{
|
||||
"Provider": "consul",
|
||||
"Config": {
|
||||
"PrivateKey": null,
|
||||
"RootCert": null,
|
||||
"RotationPeriod": "2160h"
|
||||
},
|
||||
"CreateIndex": 5,
|
||||
"ModifyIndex": 197
|
||||
}
|
||||
```
|
||||
|
||||
## set-config
|
||||
|
||||
Modifies the current CA configuration. If this results in a new root certificate
|
||||
being used, the [Root Rotation](/docs/guides/connect-ca.html#rotation) process
|
||||
will be triggered.
|
||||
|
||||
Usage: `consul connect ca set-config [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
<%= partial "docs/commands/http_api_options_server" %>
|
||||
|
||||
#### Command Options
|
||||
|
||||
* `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration.
|
||||
|
||||
The output looks like this:
|
||||
|
||||
```
|
||||
Configuration updated!
|
||||
```
|
||||
|
||||
The return code will indicate success or failure.
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Connect Proxy"
|
||||
sidebar_current: "docs-commands-connect-proxy"
|
||||
description: >
|
||||
The connect proxy subcommand is used to run the built-in mTLS proxy for Connect.
|
||||
---
|
||||
|
||||
# Consul Connect Proxy
|
||||
|
||||
Command: `consul connect proxy`
|
||||
|
||||
The connect proxy command is used to run Consul's built-in mTLS proxy for
|
||||
use with Connect. This can be used in production to enable a Connect-unaware
|
||||
application to accept and establish Connect-based connections. This proxy
|
||||
can also be used in development to establish Connect-based connections.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul connect proxy [options]`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
<%= partial "docs/commands/http_api_options_server" %>
|
||||
|
||||
#### Proxy Options
|
||||
|
||||
* `-service` - Name of the service this proxy is representing. This service
|
||||
doesn't need to actually exist in the Consul catalog, but proper ACL
|
||||
permissions (`service:write`) are required.
|
||||
|
||||
* `-upstream` - Upstream service to support connecting to. The format should be
|
||||
'name:addr', such as 'db:8181'. This will make 'db' available on port 8181.
|
||||
When a regular TCP connection is made to port 8181, the proxy will service
|
||||
discover "db" and establish a Connect mTLS connection identifying as
|
||||
the `-service` value. This flag can be repeated multiple times.
|
||||
|
||||
* `-listen` - Address to listen for inbound connections to the proxied service.
|
||||
Must be specified with -service and -service-addr. If this isn't specified,
|
||||
an inbound listener is not started.
|
||||
|
||||
* `-service-addr` - Address of the local service to proxy. Required for
|
||||
`-listen`.
|
||||
|
||||
* `-register` - Self-register with the local Consul agent, making this
|
||||
proxy available as Connect-capable service in the catalog. This is only
|
||||
useful with `-listen`.
|
||||
|
||||
* `-register-id` - Optional ID suffix for the service when `-register` is set
|
||||
to disambiguate the service ID. By default the service ID is "<service>-proxy"
|
||||
where `<service>` is the `-service` value.
|
||||
|
||||
* `-log-level` - Specifies the log level.
|
||||
|
||||
* `-pprof-addr` - Enable debugging via pprof. Providing a host:port (or just ':port')
|
||||
enables profiling HTTP endpoints on that address.
|
||||
|
||||
* `-proxy-id` - The proxy's ID on the local agent. This is only useful to
|
||||
test the managed proxy mode.
|
||||
|
||||
## Examples
|
||||
|
||||
The example below shows how to start a local proxy for establishing outbound
|
||||
connections to "db" representing the frontend service. Once running, any
|
||||
process that creates a TCP connection to the specified port (8181) will
|
||||
establish a mutual TLS connection to "db" identified as "frontend".
|
||||
|
||||
```text
|
||||
$ consul connect proxy -service frontend -upstream db:8181
|
||||
```
|
||||
|
||||
The next example starts a local proxy that also accepts inbound connections
|
||||
on port 8443, authorizes the connection, then proxies it to port 8080:
|
||||
|
||||
```text
|
||||
$ consul connect proxy \
|
||||
-service frontend \
|
||||
-service-addr 127.0.0.1:8080 \
|
||||
-listen ':8443'
|
||||
```
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention"
|
||||
sidebar_current: "docs-commands-intention"
|
||||
---
|
||||
|
||||
# Consul Intention
|
||||
|
||||
Command: `consul intention`
|
||||
|
||||
The `intention` command is used to interact with Connect
|
||||
[intentions](/docs/connect/intentions.html). It exposes commands for
|
||||
creating, updating, reading, deleting, checking, and managing intentions.
|
||||
This command is available in Consul 1.2 and later.
|
||||
|
||||
Intentions may also be managed via the [HTTP API](/api/connect/intentions.html).
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul intention <subcommand>`
|
||||
|
||||
For the exact documentation for your Consul version, run `consul intention -h` to view
|
||||
the complete list of subcommands.
|
||||
|
||||
```text
|
||||
Usage: consul intention <subcommand> [options] [args]
|
||||
|
||||
...
|
||||
|
||||
Subcommands:
|
||||
check Check whether a connection between two services is allowed.
|
||||
create Create intentions for service connections.
|
||||
delete Delete an intention.
|
||||
get Show information about an intention.
|
||||
match Show intentions that match a source or destination.
|
||||
```
|
||||
|
||||
For more information, examples, and usage about a subcommand, click on the name
|
||||
of the subcommand in the sidebar.
|
||||
|
||||
## Basic Examples
|
||||
|
||||
Create an intention to allow "web" to talk to "db":
|
||||
|
||||
$ consul intention create web db
|
||||
|
||||
Test whether a "web" is allowed to connect to "db":
|
||||
|
||||
$ consul intention check web db
|
||||
|
||||
Find all intentions for communicating to the "db" service:
|
||||
|
||||
$ consul intention match db
|
||||
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention Check"
|
||||
sidebar_current: "docs-commands-intention-check"
|
||||
---
|
||||
|
||||
# Consul Intention Check
|
||||
|
||||
Command: `consul intention check`
|
||||
|
||||
The `intention check` command checks whether a connection attempt between
|
||||
two services would be authorized given the current set of intentions and
|
||||
Consul configuration.
|
||||
|
||||
This command requires less ACL permissions than other intention-related
|
||||
tasks because no information about the intention is revealed. Therefore,
|
||||
callers only need to have `service:read` access for the destination. Richer
|
||||
commands like [match](/docs/commands/intention/match.html) require full
|
||||
intention read permissions and don't evaluate the result.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul intention check [options] SRC DST`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
## Examples
|
||||
|
||||
```text
|
||||
$ consul intention check web db
|
||||
Denied
|
||||
|
||||
$ consul intention check web billing
|
||||
Allowed
|
||||
```
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention Create"
|
||||
sidebar_current: "docs-commands-intention-create"
|
||||
---
|
||||
|
||||
# Consul Intention Create
|
||||
|
||||
Command: `consul intention create`
|
||||
|
||||
The `intention create` command creates or updates an intention.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul intention create [options] SRC DST`
|
||||
Usage: `consul intention create [options] -f FILE...`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Intention Create Options
|
||||
|
||||
* `-allow` - Set the action to "allow" for intentions. This is the default.
|
||||
|
||||
* `-deny` - Set the action to "deny" for intentions. This cannot be specified
|
||||
with `-allow`.
|
||||
|
||||
* `-file` - Read intention data one or more files specified by the command
|
||||
line arguments, instead of source/destination pairs.
|
||||
|
||||
* `-meta key=value` - Specify arbitrary KV metadata to associate with the
|
||||
intention.
|
||||
|
||||
* `-replace` - Replace any matching intention. The replacement is done
|
||||
atomically per intention.
|
||||
|
||||
## Examples
|
||||
|
||||
Create an intention `web => db`:
|
||||
|
||||
$ consul intention create web db
|
||||
|
||||
Create intentions from a set of files:
|
||||
|
||||
$ consul intention create -file one.json two.json
|
||||
|
||||
Create intentions from a directory using shell expansion:
|
||||
|
||||
$ consul intention create -file intentions/*.json
|
||||
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention Delete"
|
||||
sidebar_current: "docs-commands-intention-delete"
|
||||
---
|
||||
|
||||
# Consul Intention Delete
|
||||
|
||||
Command: `consul intention delete`
|
||||
|
||||
The `intention delete` command deletes a matching intention.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage:
|
||||
|
||||
* `consul intention delete [options] SRC DST`
|
||||
* `consul intention delete [options] ID`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
## Examples
|
||||
|
||||
Delete an intention from "web" to "db" with any action:
|
||||
|
||||
```text
|
||||
$ consul intention delete web db
|
||||
```
|
||||
|
||||
Delete an intention by unique ID:
|
||||
|
||||
```text
|
||||
$ consul intention delete 4ffed935-439c-695d-4f51-f4fc0b12a7a7
|
||||
```
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention Get"
|
||||
sidebar_current: "docs-commands-intention-get"
|
||||
---
|
||||
|
||||
# Consul Intention Get
|
||||
|
||||
Command: `consul intention get`
|
||||
|
||||
The `intention get` command shows a single intention.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage:
|
||||
|
||||
* `consul intention get [options] SRC DST`
|
||||
* `consul intention get [options] ID`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
## Examples
|
||||
|
||||
```text
|
||||
$ consul intention get web db
|
||||
Source: web
|
||||
Destination: db
|
||||
Action: deny
|
||||
ID: 20edfa56-9cd4-51db-8c22-db09fdec61ef
|
||||
Created At: Thursday, 24-May-18 17:07:49 PDT
|
||||
```
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Intention Match"
|
||||
sidebar_current: "docs-commands-intention-match"
|
||||
---
|
||||
|
||||
# Consul Intention Match
|
||||
|
||||
Command: `consul intention match`
|
||||
|
||||
The `intention match` command shows the list of intentions that match
|
||||
a given source or destination. The list of intentions is listed in evaluation
|
||||
order: the first intention that matches a request would be evaluated.
|
||||
|
||||
The [check](/docs/commands/intention/check.html) command can be used to
|
||||
check whether a connection would be authorized between any two services.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul intention match [options] SRC_OR_DST`
|
||||
|
||||
#### API Options
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### Intention Match Options
|
||||
|
||||
* `-destination` - Match by destination.
|
||||
|
||||
* `-source` - Match by source.
|
||||
|
||||
## Examples
|
||||
|
||||
```text
|
||||
$ consul intention match -source web
|
||||
web => db (deny)
|
||||
web => * (allow)
|
||||
```
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Certificate Management"
|
||||
sidebar_current: "docs-connect-ca"
|
||||
description: |-
|
||||
TODO
|
||||
---
|
||||
|
||||
# Connect Certificate Management
|
||||
|
||||
TODO
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Configuration"
|
||||
sidebar_current: "docs-connect-config"
|
||||
description: |-
|
||||
A Connect-aware proxy enables unmodified applications to use Connect. A per-service proxy sidecar transparently handles inbound and outbound service connections, automatically wrapping and verifying TLS connections.
|
||||
---
|
||||
|
||||
# Connect Configuration
|
||||
|
||||
There are many configuration options exposed for Connect. The only option
|
||||
that must be set is the "enabled" option on Consul Servers to enable Connect.
|
||||
All other configurations are optional and have reasonable defaults.
|
||||
|
||||
## Enable Connect on the Cluster
|
||||
|
||||
The first step to use Connect is to enable Connect for your Consul
|
||||
cluster. By default, Connect is disabled. Enabling Connect requires changing
|
||||
the configuration of only your Consul _servers_ (not client agents). To enable
|
||||
Connect, add the following to a new or existing
|
||||
[server configuration file](/docs/agent/options.html). In HCL:
|
||||
|
||||
```hcl
|
||||
connect {
|
||||
enabled = true
|
||||
}
|
||||
```
|
||||
|
||||
This will enable Connect and configure your Consul cluster to use the
|
||||
built-in certificate authority for creating and managing certificates.
|
||||
You may also configure Consul to use an external
|
||||
[certificate management system](/docs/connect/ca.html), such as
|
||||
[Vault](https://vaultproject.io).
|
||||
|
||||
No agent-wide configuration is necessary for non-server agents. Services
|
||||
and proxies may always register with Connect settings, but they will fail to
|
||||
retrieve or verify any TLS certificates. This causes all Connect-based
|
||||
connection attempts to fail until Connect is enabled on the server agents.
|
||||
|
||||
-> **Note:** Connect is enabled by default when running Consul in
|
||||
dev mode with `consul agent -dev`.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Development and Debugging"
|
||||
sidebar_current: "docs-connect-dev"
|
||||
description: |-
|
||||
It is often necessary to connect to a service for development or debugging. If a service only exposes a Connect listener, then we need a way to establish a mutual TLS connection to the service. The `consul connect proxy` command can be used for this task on any machine with access to a Consul agent (local or remote).
|
||||
---
|
||||
|
||||
# Developing and Debugging Connect Services
|
||||
|
||||
It is often necessary to connect to a service for development or debugging.
|
||||
If a service only exposes a Connect listener, then we need a way to establish
|
||||
a mutual TLS connection to the service. The
|
||||
[`consul connect proxy` command](/docs/commands/connect/proxy.html) can be used
|
||||
for this task on any machine with access to a Consul agent (local or remote).
|
||||
|
||||
Restricting access to services only via Connect ensures that the only way to
|
||||
connect to a service is through valid authorization of the
|
||||
[intentions](/docs/connect/intentions.html). This can extend to developers
|
||||
and operators, too.
|
||||
|
||||
## Connecting to Connect-only Services
|
||||
|
||||
As an example, let's assume that we have a PostgreSQL database running that
|
||||
we want to connect to via `psql`, but the only non-loopback listener is
|
||||
via Connect. Let's also assume that we have an ACL token to identify as
|
||||
`operator-mitchellh`. We can start a local proxy:
|
||||
|
||||
```sh
|
||||
$ consul connect proxy \
|
||||
-service operator-mitchellh \
|
||||
-upstream postgresql:8181
|
||||
```
|
||||
|
||||
This works because the source `-service` does not need to be registered
|
||||
in the local Consul catalog. However, to retrieve a valid identifying
|
||||
certificate, the ACL token must have `service:write` permissions. This
|
||||
can be used as a sort of "virtual service" to represent people, too. In
|
||||
the example above, the proxy is identifying as `operator-mitchellh`.
|
||||
|
||||
With the proxy running, we can now use `psql` like normal:
|
||||
|
||||
```
|
||||
$ psql -h 127.0.0.1 -p 8181 -U mitchellh mydb
|
||||
>
|
||||
```
|
||||
|
||||
This `psql` session is now happening through our local proxy via an
|
||||
authorized mutual TLS connection to the PostgreSQL service in our Consul
|
||||
catalog.
|
||||
|
||||
### Masquerading as a Service
|
||||
|
||||
You can also easily masquerade as any source service by setting the
|
||||
`-service` value to any service. Note that the proper ACL permissions are
|
||||
required to perform this task.
|
||||
|
||||
For example, if you have an ACL token that allows `service:write` for
|
||||
`web` and you want to connect to the `postgresql` service as "web", you
|
||||
can start a proxy like so:
|
||||
|
||||
```sh
|
||||
$ consul connect proxy \
|
||||
-service web \
|
||||
-upstream postgresql:8181
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect (Service Segmentation)"
|
||||
sidebar_current: "docs-connect-index"
|
||||
description: |-
|
||||
Consul Connect provides service-to-service connection authorization and encryption using mutual TLS.
|
||||
---
|
||||
|
||||
# Connect
|
||||
|
||||
Consul Connect provides service-to-service connection authorization
|
||||
and encryption using mutual TLS. Applications can use
|
||||
[sidecar proxies](/docs/connect/proxies.html)
|
||||
to automatically establish TLS connections for inbound and outbound connections
|
||||
without being aware of Connect at all. Applications may also
|
||||
[natively integrate with Connect](/docs/connect/native.html)
|
||||
for optimal performance and security.
|
||||
|
||||
## How it Works
|
||||
|
||||
TODO
|
||||
|
||||
## Eliminating East-West Firewalls
|
||||
|
||||
East-west firewalls are the typical tool for network security in a static world.
|
||||
East-west is the transfer of data from server to server within a datacenter,
|
||||
versus North-south traffic which describes end user to server communications.
|
||||
|
||||
These firewalls wrap services with ingress/egress policies. This perimeter-based
|
||||
approach is difficult to scale in a dynamic world with dozens or hundreds of
|
||||
services or where machines may be frequently created or destroyed. Firewalls
|
||||
create a sprawl of rules for each service instance that quickly becomes
|
||||
overly difficult to maintain.
|
||||
|
||||
Service security in a dynamic world is best solved through service-to-service
|
||||
authentication and authorization. Instead of IP-based network security,
|
||||
services can be deployed to low-trust networks and rely on service-identity
|
||||
based security over in-transit data encryption.
|
||||
|
||||
Connect enables service segmentation by securing service-to-service
|
||||
communications through mutual TLS and transparent proxying on zero-trust
|
||||
networks. This allows direct service communication without relying on firewalls
|
||||
for east-west traffic security.
|
||||
|
|
@ -0,0 +1,134 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Intentions"
|
||||
sidebar_current: "docs-connect-intentions"
|
||||
description: |-
|
||||
Intentions define access control for services via Connect and are used to control which services may establish connections. Intentions can be managed via the API, CLI, or UI.
|
||||
---
|
||||
|
||||
# Intentions
|
||||
|
||||
Intentions define access control for services via Connect and are used
|
||||
to control which services may establish connections. Intentions can be
|
||||
managed via the API, CLI, or UI.
|
||||
|
||||
Intentions are enforced by the [proxy](/docs/connect/proxies.html)
|
||||
or [natively integrated application](/docs/connect/native.html) on
|
||||
inbound connections. After verifying the TLS client certificate, the
|
||||
[authorize API endpoint](#) is called which verifies the connection
|
||||
is allowed by testing the intentions. If authorize returns false the
|
||||
connection must be terminated.
|
||||
|
||||
The default intention behavior is defined by the default
|
||||
[ACL policy](/docs/guides/acls.html). If the default ACL policy is "allow all",
|
||||
then all Connect connections are allowed by deafult. If the default ACL policy
|
||||
is "deny all", then all Connect connections are denied by default.
|
||||
|
||||
## Intention Basics
|
||||
|
||||
Intentions can be managed via the
|
||||
[API](#),
|
||||
[CLI](#),
|
||||
or UI. Please see the respective documentation for each for full details
|
||||
on options, flags, etc.
|
||||
Below is an example of a basic intention to show the basic attributes
|
||||
of an intention. The full data model of an intention can be found in the
|
||||
[API documentation](#).
|
||||
|
||||
```
|
||||
$ consul intention create -deny web db
|
||||
Created: web => db (deny)
|
||||
```
|
||||
|
||||
The intention above is a deny intention with a source of "web" and
|
||||
destination of "db". This says that connections from web to db are not
|
||||
allowed and the connection will be rejected.
|
||||
|
||||
### Wildcard Intentions
|
||||
|
||||
An intention source or destination may also be the special wildcard
|
||||
value `*`. This matches _any_ value and is used as a catch-all. Example:
|
||||
|
||||
```
|
||||
$ consul intention create -deny web '*'
|
||||
Created: web => * (deny)
|
||||
```
|
||||
|
||||
This example says that the "web" service cannot connect to _any_ service.
|
||||
|
||||
### Metadata
|
||||
|
||||
Arbitrary string key/value data may be associated with intentions. This
|
||||
is unused by Consul but can be used by external systems or for visibility
|
||||
in the UI.
|
||||
|
||||
```
|
||||
$ consul intention create \
|
||||
-deny \
|
||||
-meta description='Hello there' \
|
||||
web db
|
||||
...
|
||||
|
||||
$ consul intention get web db
|
||||
Source: web
|
||||
Destination: db
|
||||
Action: deny
|
||||
ID: 31449e02-c787-f7f4-aa92-72b5d9b0d9ec
|
||||
Meta[description]: Hello there
|
||||
Created At: Friday, 25-May-18 02:07:51 CEST
|
||||
```
|
||||
|
||||
## Precedence and Match Order
|
||||
|
||||
Intentions are matched in an implicit order based on specificity, preferring
|
||||
deny over allow. The full precedence table is shown below and is evaluated
|
||||
top to bottom.
|
||||
|
||||
TODO
|
||||
|
||||
## Intention Management Permissions
|
||||
|
||||
Intention management can be protected by [ACLs](/docs/guides/acls.html).
|
||||
Permissions for intentions are _destination-oriented_, meaning the ACLs
|
||||
for managing intentions are looked up based on the destination value
|
||||
of the intention, not the source.
|
||||
|
||||
Intention permissions are first inherited from `service` management permissions.
|
||||
For example, the ACL below would allow _read_ access to intentions with a
|
||||
destination starting with "web":
|
||||
|
||||
```hcl
|
||||
service "web" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
ACLs may also specify service-specific intention permissions. In the example
|
||||
below, the ACL token may register a "web"-prefixed service but _may not_ read or write
|
||||
intentions:
|
||||
|
||||
```hcl
|
||||
service "web" {
|
||||
policy = "read"
|
||||
intention = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
## Performance and Intention Updates
|
||||
|
||||
The intentions for services registered with a Consul agent are cached
|
||||
locally on that agent. They are then updated via a background blocking query
|
||||
against the Consul servers.
|
||||
|
||||
Connect connection attempts require only local agent
|
||||
communication for authorization and generally impose only impose microseconds
|
||||
of latency to the connection. All actions in the data path of connections
|
||||
require only local data to ensure minimal performance overhead.
|
||||
|
||||
Updates to intentions are propagated nearly instantly to agents since agents
|
||||
maintain a continuous blocking query in the background for intention updates
|
||||
for registered services.
|
||||
|
||||
Because all the intention data is cached locally, the agents can fail open.
|
||||
Even if the agents are severed completely from the Consul servers, inbound
|
||||
connection authorization continues to work for a configured amount of time.
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Native Application Integration"
|
||||
sidebar_current: "docs-connect-native"
|
||||
description: |-
|
||||
TODO
|
||||
---
|
||||
|
||||
# Connect-Native App Integration
|
||||
|
||||
TODO
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Proxies"
|
||||
sidebar_current: "docs-connect-proxies"
|
||||
description: |-
|
||||
A Connect-aware proxy enables unmodified applications to use Connect. A per-service proxy sidecar transparently handles inbound and outbound service connections, automatically wrapping and verifying TLS connections.
|
||||
---
|
||||
|
||||
# Connect Proxies
|
||||
|
||||
A Connect-aware proxy enables unmodified applications to use Connect.
|
||||
A per-service proxy sidecar transparently handles inbound and outbound
|
||||
service connections, automatically wrapping and verifying TLS connections.
|
||||
|
||||
When a proxy is used, the actual service being proxied should only accept
|
||||
connections on a loopback address. This requires all external connections
|
||||
to be established via the Connect protocol to provide authentication and
|
||||
authorization.
|
||||
|
||||
Consul supports both _managed_ and _unmanaged_ proxies. A managed proxy
|
||||
is started, configured, and stopped by Consul. An unmanaged proxy is the
|
||||
responsibility of the user, like any other Consul service.
|
||||
|
||||
## Managed Proxies
|
||||
|
||||
Managed proxies are started, configured, and stopped by Consul. They are
|
||||
enabled via basic configurations within the
|
||||
[service definition](/docs/agent/services.html).
|
||||
This is the easiest way to start a proxy and allows Consul users to begin
|
||||
using Connect with only a small configuration change.
|
||||
|
||||
Managed proxies also offer the best security. Managed proxies are given
|
||||
a unique proxy-specific ACL token that allows read-only access to Connect
|
||||
information for the specific service the proxy is representing. This ACL
|
||||
token is more restrictive than can be currently expressed manually in
|
||||
an ACL policy.
|
||||
|
||||
The default managed proxy is a basic proxy built-in to Consul and written
|
||||
in Go. Having a basic built-in proxy allows Consul to have a sane default
|
||||
with performance that is good enough for most workloads. In some basic
|
||||
benchmarks, the service-to-service communication over the built-in proxy
|
||||
could sustain 5 Gbps with a per-hop latency of less than X microseconds. Therefore,
|
||||
the performance impact of even the basic built-in proxy is minimal.
|
||||
|
||||
Consul will be
|
||||
integrating with advanced proxies in the near future to support more complex
|
||||
configurations and higher performance. The configuration below is all for
|
||||
the built-in proxy.
|
||||
|
||||
### Minimal Configuration
|
||||
|
||||
Managed proxies are configured within a
|
||||
[service definition](/docs/agent/services.html). The simplest possible
|
||||
managed proxy configuration is an empty configuration. This enables the
|
||||
default managed proxy and starts a listener for that service:
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "redis",
|
||||
"connect": { "proxy": {} }
|
||||
}
|
||||
```
|
||||
|
||||
The listener is started on random port within the configured Connect
|
||||
port range. It can be discovered using the
|
||||
[DNS interface](/docs/agent/dns.html#connect-capable-service-lookups)
|
||||
or
|
||||
[Catalog API](#).
|
||||
In most cases, service-to-service communication is established by
|
||||
a proxy configured with upstreams (described below), which handle the
|
||||
discovery transparently.
|
||||
|
||||
### Upstream Configuration
|
||||
|
||||
To transparently discover and establish Connect-based connections to
|
||||
dependencies, they must be configured with a static port on the managed
|
||||
proxy configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "web",
|
||||
"connect": {
|
||||
"proxy": {
|
||||
"config": {
|
||||
"upstreams": [{
|
||||
"destination_name": "redis",
|
||||
"local_bind_port": 1234
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above,
|
||||
"redis" is configured as an upstream with static port 1234 for service "web".
|
||||
When a TCP connection is established on port 1234, the proxy
|
||||
will find Connect-compatible "redis" services via Consul service discovery
|
||||
and establish a TLS connection identifying as "web".
|
||||
|
||||
~> **Security:** Any application that can communicate to the configured
|
||||
static port will be able to masquerade as the source service ("web" in the
|
||||
example above). You must either trust any loopback access on that port or
|
||||
use namespacing techniques provided by your operating system.
|
||||
|
||||
### Prepared Query Upstreams
|
||||
|
||||
The upstream destination may also be a
|
||||
[prepared query](/api/query.html).
|
||||
This allows complex service discovery behavior such as connecting to
|
||||
the nearest neighbor or filtering by tags.
|
||||
|
||||
For example, given a prepared query named "nearest-redis" that is
|
||||
configured to route to the nearest Redis instance, an upstream can be
|
||||
configured to route to this query. In the example below, any TCP connection
|
||||
to port 1234 will attempt a Connect-based connection to the nearest Redis
|
||||
service.
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "web",
|
||||
"connect": {
|
||||
"proxy": {
|
||||
"config": {
|
||||
"upstreams": [{
|
||||
"destination_name": "nearest-redis",
|
||||
"destination_type": "prepared_query",
|
||||
"local_bind_port": 1234
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Upstreams
|
||||
|
||||
If an application requires dynamic dependencies that are only available
|
||||
at runtime, it must currently [natively integrate](/docs/connect/native.html)
|
||||
with Connect. After natively integrating, the HTTP API or
|
||||
[DNS interface](/docs/agent/dns.html#connect-capable-service-lookups)
|
||||
can be used.
|
||||
|
||||
## Unmanaged Proxies
|
||||
|
||||
Unmanaged proxies are regular Consul services that are registered as a
|
||||
proxy type and declare the service they represent. The proxy process must
|
||||
be started, configured, and stopped manually by some external process such
|
||||
as an operator or scheduler.
|
||||
|
||||
To declare a service as a proxy, the service definition must contain
|
||||
at least two additional fields:
|
||||
|
||||
* `Kind` (string) must be set to `connect-proxy`. This declares that the
|
||||
service is a proxy type.
|
||||
|
||||
* `ProxyDestination` (string) must be set to the service that this proxy
|
||||
is representing.
|
||||
|
||||
* `Port` must be set so that other Connect services can discover the exact
|
||||
address for connections. `Address` is optional if the service is being
|
||||
registered against an agent, since it'll inherit the node address.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "redis-proxy",
|
||||
"Kind": "connect-proxy",
|
||||
"ProxyDestination": "redis",
|
||||
"Port": 8181
|
||||
}
|
||||
```
|
||||
|
||||
With this service registered, any Connect proxies searching for a
|
||||
Connect-capable endpoint for "redis" will find this proxy.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Proxy Integration"
|
||||
sidebar_current: "docs-connect-proxies-integrate"
|
||||
description: |-
|
||||
A Connect-aware proxy enables unmodified applications to use Connect. A per-service proxy sidecar transparently handles inbound and outbound service connections, automatically wrapping and verifying TLS connections.
|
||||
---
|
||||
|
||||
# Connect Custom Proxy Integration
|
||||
|
||||
Any proxy can be extended to support Connect. Consul ships with a built-in
|
||||
proxy for a good development and out of the box experience, but understand
|
||||
that production users will require other proxy solutions.
|
||||
|
||||
A proxy must serve one or both of the following two roles: it must accept
|
||||
inbound connections or establish outbound connections identified as a
|
||||
particular service. One or both of these may be implemented depending on
|
||||
the case, although generally both must be supported.
|
||||
|
||||
## Accepting Inbound Connections
|
||||
|
||||
For inbound connections, the proxy must accept TLS connections on some port.
|
||||
The certificate served should be created by the
|
||||
[`/v1/agent/connect/ca/leaf/`](/api/agent/connect.html) API endpoint.
|
||||
The client certificate should be validated against the root certificates
|
||||
provided by the
|
||||
[`/v1/agent/connect/ca/roots`](/api/agent/connect.html) endpoint.
|
||||
After validating the client certificate from the caller, the proxy should
|
||||
call the
|
||||
[`/v1/agent/connect/authorize`](/api/agent/connect.html) endpoint to
|
||||
authorize the connection.
|
||||
|
||||
All of these API endpoints operate on agent-local data that is updated
|
||||
in the background. The leaf and roots should be updated in the background
|
||||
by the proxy, but the authorize endpoint is expected to be called in the
|
||||
connection path. The endpoints introduce only microseconds of additional
|
||||
latency on the connection.
|
||||
|
||||
The leaf and root cert endpoints support blocking queries. These should be
|
||||
used if possible to get near-immediate updates for root cert rotations,
|
||||
leaf expiry, etc.
|
||||
|
||||
## Establishing Outbound Connections
|
||||
|
||||
For outbound connections, the proxy should communicate to a
|
||||
Connect-capable endpoint for a service and provide a client certificate
|
||||
from the
|
||||
[`/v1/agent/connect/ca/leaf/`](/api/agent/connect.html) API endpoint.
|
||||
The certificate served by the remote endpoint can be verified against the
|
||||
root certificates from the
|
||||
[`/v1/agent/connect/ca/roots`](/api/agent/connect.html) endpoint.
|
||||
|
||||
## Managed Mode Support
|
||||
|
||||
If the proxy could run as a managed proxy, then it should accept the following
|
||||
two environment variables that Consul populates on process startup. These
|
||||
are both required to make the necessary API requests for configuration.
|
||||
|
||||
* `CONSUL_PROXY_TOKEN` - The ACL token to use for all requests to proxy-related
|
||||
API endpoints.
|
||||
|
||||
* `CONSUL_PROXY_ID` - The service ID for requesting configuration for the
|
||||
proxy from [`/v1/agent/connect/proxy/`](/api/agent/connect.html).
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Connect - Security"
|
||||
sidebar_current: "docs-connect-security"
|
||||
description: |-
|
||||
TODO
|
||||
---
|
||||
|
||||
# Connect Security
|
||||
|
||||
Connect enables secure service-to-service communication over mutual TLS. This
|
||||
provides both in-transit data encryption as well as authorization. This page
|
||||
will document how to secure Connect. For a full security model reference,
|
||||
see the dedicated [Consul security model](/docs/internals/security.html) page.
|
||||
|
||||
Connect will function in any Consul configuration. However, unless the checklist
|
||||
below is satisfied, Connect is not providing the security guarantees it was
|
||||
built for. The checklist below can be incrementally adopted towards full
|
||||
security if you prefer to operate in less secure models initially.
|
||||
|
||||
~> **Warning**: The checklist below should not be considered exhaustive. Please
|
||||
read and understand the [Consul security model](/docs/internals/security.html)
|
||||
in depth to assess whether your deployment satisfies the security requirements
|
||||
of Consul.
|
||||
|
||||
## Checklist
|
||||
|
||||
### ACLs Enabled with Default Deny
|
||||
|
||||
Consul must be configured to use ACLs with a default deny policy. This forces
|
||||
all requests to have explicit anonymous access or provide an ACL token. The
|
||||
configuration also forces all service-to-service communication to be explicitly
|
||||
whitelisted via an allow [intention](/docs/connect/intentions.html).
|
||||
|
||||
To learn how to enable ACLs, please see the
|
||||
[guide on ACLs](/docs/guides/acl.html).
|
||||
|
||||
**If ACLs are enabled but are in default allow mode**, then services will be
|
||||
able to communicate by default. Additionally, if a proper anonymous token
|
||||
is not configured, this may allow anyone to edit intentions. We do not recommend
|
||||
this. **If ACLs are not enabled**, deny intentions will still be enforced, but anyone
|
||||
may edit intentions. This renders the security of the created intentions
|
||||
effectively useless.
|
||||
|
||||
### TCP and UDP Encryption Enabled
|
||||
|
||||
TCP and UDP encryption must be enabled to prevent plaintext communication
|
||||
between Consul agents. At a minimum, `verify_outgoing` should be enabled
|
||||
to verify server authenticity with each server having a unique TLS certificate.
|
||||
`verify_incoming` provides additional agent verification, but doesn't directly
|
||||
affect Connect since requests must also always contain a valid ACL token.
|
||||
Clients calling Consul APIs should be forced over encrypted connections.
|
||||
|
||||
See the [Consul agent encryption page](/docs/agent/encryption.html) to
|
||||
learn more about configuring agent encryption.
|
||||
|
||||
**If encryption is not enabled**, a malicious actor can sniff network
|
||||
traffic or perform a man-in-the-middle attack to steal ACL tokens, always
|
||||
authorize connections, etc.
|
||||
|
||||
### Prevent Unauthorized Access to the Config and Data Directories
|
||||
|
||||
The configuration and data directories of the Consul agent on both
|
||||
clients and servers should be protected from unauthorized access. This
|
||||
protection must be done outside of Consul via access control systems provided
|
||||
by your target operating system.
|
||||
|
||||
The [full Consul security model](/docs/internals/security.html) explains the
|
||||
risk of unauthorized access for both client agents and server agents. In
|
||||
general, the blast radius of unauthorized access for client agent directories
|
||||
is much smaller than servers. However, both must be protected against
|
||||
unauthorized access.
|
||||
|
||||
### Prevent Non-Connect Traffic to Services
|
||||
|
||||
For services that are using
|
||||
[proxies](/docs/connect/proxies.html)
|
||||
(are not [natively integrated](/docs/connect/native.html)),
|
||||
network access via their unencrypted listeners must be restricted
|
||||
to only the proxy. This requires at a minimum restricting the listener
|
||||
to bind to loopback only. More complex solutions may involve using
|
||||
network namespacing techniques provided by the underlying operating system.
|
||||
|
||||
For scenarios where multiple services are running on the same machine
|
||||
without isolation, these services must all be trusted. We call this the
|
||||
**trusted multi-tenenacy** deployment model. Any service could theoretically
|
||||
connect to any other service via the loopback listener, bypassing Connect
|
||||
completely. In this scenario, all services must be trusted _or_ isolation
|
||||
mechanisms must be used.
|
||||
|
||||
For developer or operator access to a service, we recommend
|
||||
using a local Connect proxy. This is documented in the
|
||||
[development and debugging guide](/docs/connect/dev.html).
|
||||
|
||||
**If non-proxy traffic can communicate with the service**, this traffic
|
||||
will not be encrypted or authorized via Connect.
|
||||
|
|
@ -0,0 +1,192 @@
|
|||
---
|
||||
layout: "intro"
|
||||
page_title: "Consul Connect"
|
||||
sidebar_current: "gettingstarted-connect"
|
||||
description: |-
|
||||
Connect is a feature of Consul that provides service-to-service connection authorization and encryption using mutual TLS. This ensures that all service communication in your datacenter is encrypted and that the rules of what services can communicate is centrally managed with Consul.
|
||||
---
|
||||
|
||||
# Connect
|
||||
|
||||
We've now registered our first service with Consul and we've shown how you
|
||||
can use the HTTP API or DNS interface to query the address and directly connect
|
||||
to that service. Consul also provides a feature called **Connect** for
|
||||
automatically connecting via an encrypted TLS connection and authorizing
|
||||
which services are allowed to connect to each other.
|
||||
|
||||
Applications do not need to be modified at all to use Connect.
|
||||
[Sidecar proxies](/docs/connect/proxies.html) can be used
|
||||
to automatically establish TLS connections for inbound and outbound connections
|
||||
without being aware of Connect at all. Applications may also
|
||||
[natively integrate with Connect](/docs/connect/native.html)
|
||||
for optimal performance and security.
|
||||
|
||||
-> **Security note:** The getting started guide will show Connect features
|
||||
and focus on ease of use with a dev-mode agent. We will _not setup_ Connect in a
|
||||
production-recommended secure way. Please read the Connect reference
|
||||
documentation on security best practices to understand the tradeoffs.
|
||||
|
||||
## Starting a Connect-unaware Service
|
||||
|
||||
Let's begin by starting a service that is unaware of Connect all. To
|
||||
keep it simple, let's just use `socat` to start a basic echo service. This
|
||||
service will accept TCP connections and echo back any data sent to it. If
|
||||
`socat` isn't installed on your machine, it should be easily available via
|
||||
a package manager.
|
||||
|
||||
```sh
|
||||
$ socat -v tcp-l:8181,fork exec:"/bin/cat"
|
||||
```
|
||||
|
||||
You can verify it is working by using `nc` to connect directly to it. Once
|
||||
connected, type some text and press enter. The text you typed should be
|
||||
echoed back:
|
||||
|
||||
```
|
||||
$ nc 127.0.0.1 8181
|
||||
hello
|
||||
hello
|
||||
echo
|
||||
echo
|
||||
```
|
||||
|
||||
`socat` is a decades-old Unix utility and our process is configured to
|
||||
only accept a basic TCP connection. It has no concept of encryption, the
|
||||
TLS protocol, etc. This can be representative of an existing service in
|
||||
your datacenter such as a database, backend web service, etc.
|
||||
|
||||
## Registering the Service with Consul and Connect
|
||||
|
||||
Next, let's register the service with Consul. We'll do this by writing
|
||||
a new service definition. This is the same as the previous step in the
|
||||
getting started guide, except this time we'll also configure Connect.
|
||||
|
||||
```sh
|
||||
$ cat <<EOF | sudo tee /etc/consul.d/socat.json
|
||||
{
|
||||
"service": {
|
||||
"name": "socat",
|
||||
"port": 8181,
|
||||
"connect": { "proxy": {} }
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
After saving this, run `consul reload` or send a `SIGHUP` signal to Consul
|
||||
so it reads the new configuration.
|
||||
|
||||
Notice the only difference is the line starting with `"connect"`. The
|
||||
existence of this empty configuration notifies Consul to manage a
|
||||
proxy process for this process.
|
||||
The proxy process represents that specific service. It accepts inbound
|
||||
connections on a dynamically allocated port, verifies and authorizes the TLS
|
||||
connection, and proxies back a standard TCP connection to the process.
|
||||
|
||||
## Connecting to the Service
|
||||
|
||||
Next, let's connect to the service. We'll first do this by using the
|
||||
`consul connect proxy` command directly. This command manually runs a local
|
||||
proxy that can represent a service. This is a useful tool for development
|
||||
since it'll let you masquerade as any service (that you have permissions for)
|
||||
and establish connections to other services via Connect.
|
||||
|
||||
The command below starts a proxy representing a service "web". We request
|
||||
an upstream dependency of "socat" (the service we previously registered)
|
||||
on port 9191. With this configuration, all TCP connections to 9191 will
|
||||
perform service discovery for a Connect-capable "socat" endpoint and establish
|
||||
a mutual TLS connection identifying as the service "web".
|
||||
|
||||
```sh
|
||||
$ consul connect proxy -service web -upstream socat:9191
|
||||
==> Consul Connect proxy starting...
|
||||
Configuration mode: Flags
|
||||
Service: web
|
||||
Upstream: socat => :9191
|
||||
Public listener: Disabled
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
With that running, we can verify it works by establishing a connection:
|
||||
|
||||
```
|
||||
$ nc 127.0.0.1 9191
|
||||
hello
|
||||
hello
|
||||
```
|
||||
|
||||
**The connection between proxies is now encrypted and authorized.**
|
||||
We're now communicating to the "socat" service via a TLS connection.
|
||||
The local connections to/from the proxy are unencrypted, but in production
|
||||
these will be loopback-only connections. Any traffic in and out of the
|
||||
machine is always encrypted.
|
||||
|
||||
## Registering a Dependent Service
|
||||
|
||||
We previously established a connection by directly running
|
||||
`consul connect proxy`. Realistically, services need to establish connections
|
||||
to dependencies over Connect. Let's register a service "web" that registers
|
||||
"socat" as an upstream dependency:
|
||||
|
||||
```sh
|
||||
$ cat <<EOF | sudo tee /etc/consul.d/web.json
|
||||
{
|
||||
"service": {
|
||||
"name": "web",
|
||||
"connect": {
|
||||
"proxy": {
|
||||
"config": {
|
||||
"upstreams": [{
|
||||
"destination_name": "db",
|
||||
"local_bind_port": 9191
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
This configures a Consul-managed proxy for the service "web" that
|
||||
is listening on port 9191 to establish connects to "db" as "web". The
|
||||
"web" service should then use that local port to talk to the DB rather than
|
||||
directly attempting to connect.
|
||||
|
||||
-> **Security note:** The Connect security model requires trusting
|
||||
loopback connections when proxies are in use. To further secure this,
|
||||
tools like network namespacing may be used.
|
||||
|
||||
## Controlling Access with Intentions
|
||||
|
||||
Intentions are used to define which services may communicate. Our connections
|
||||
above succeeded because in a development mode agent, the ACL system is "allow
|
||||
all" by default.
|
||||
|
||||
Let's insert a rule to deny access from web to socat:
|
||||
|
||||
```sh
|
||||
$ consul intention create -deny web db
|
||||
Created: web => socat (deny)
|
||||
```
|
||||
|
||||
With the proxy processes running that we setup previously, connection
|
||||
attempts now fail:
|
||||
|
||||
```sh
|
||||
$ nc 127.0.0.1 9191
|
||||
$
|
||||
```
|
||||
|
||||
Try deleting the intention (or updating it to allow) and attempting the
|
||||
connection again. Intentions allow services to be segmented via a centralized
|
||||
control plane (Consul). To learn more, read the reference documentation on
|
||||
[intentions](/docs/connect/intentions.html).
|
||||
|
||||
## Next Steps
|
||||
|
||||
We've now configured a service on a single agent and used Connect for
|
||||
automatic connection authorization and encryption. This is a great feature
|
||||
highlight but let's explore the full value of Consul by [setting up our
|
||||
first cluster](/intro/getting-started/join.html)!
|
||||
|
|
@ -22,11 +22,25 @@
|
|||
<li<%= sidebar_current("api-agent-service") %>>
|
||||
<a href="/api/agent/service.html">Services</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-agent-connect") %>>
|
||||
<a href="/api/agent/connect.html">Connect</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-catalog") %>>
|
||||
<a href="/api/catalog.html">Catalog</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-connect") %>>
|
||||
<a href="/api/connect.html">Connect</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("api-connect-ca") %>>
|
||||
<a href="/api/connect/ca.html">Certificate Authority (CA)</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-connect-intentions") %>>
|
||||
<a href="/api/connect/intentions.html">Intentions</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-coordinate") %>>
|
||||
<a href="/api/coordinate.html">Coordinates</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -70,6 +70,17 @@
|
|||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-connect") %>>
|
||||
<a href="/docs/commands/connect.html">connect</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-connect-ca") %>>
|
||||
<a href="/docs/commands/connect/ca.html">ca</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-connect-proxy") %>>
|
||||
<a href="/docs/commands/connect/proxy.html">proxy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-event") %>>
|
||||
<a href="/docs/commands/event.html">event</a>
|
||||
</li>
|
||||
|
|
@ -82,6 +93,27 @@
|
|||
<li<%= sidebar_current("docs-commands-info") %>>
|
||||
<a href="/docs/commands/info.html">info</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-intention") %>>
|
||||
<a href="/docs/commands/intention.html">intention</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-intention-check") %>>
|
||||
<a href="/docs/commands/intention/check.html">check</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-intention-create") %>>
|
||||
<a href="/docs/commands/intention/create.html">create</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-intention-delete") %>>
|
||||
<a href="/docs/commands/intention/delete.html">delete</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-intention-get") %>>
|
||||
<a href="/docs/commands/intention/get.html">get</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-intention-match") %>>
|
||||
<a href="/docs/commands/intention/match.html">match</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-join") %>>
|
||||
<a href="/docs/commands/join.html">join</a>
|
||||
</li>
|
||||
|
|
@ -216,6 +248,38 @@
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-connect") %>>
|
||||
<a href="/docs/connect/index.html">Connect (Service Segmentation)</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-connect-config") %>>
|
||||
<a href="/docs/connect/configuration.html">Configuration</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-proxies") %>>
|
||||
<a href="/docs/connect/proxies.html">Proxies</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-connect-proxies-integrate") %>>
|
||||
<a href="/docs/connect/proxies/integrate.html">Proxy Integration</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-intentions") %>>
|
||||
<a href="/docs/connect/intentions.html">Intentions</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-ca") %>>
|
||||
<a href="/docs/connect/ca.html">Certificate Management</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-native") %>>
|
||||
<a href="/docs/connect/native.html">Native App Integration</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-dev") %>>
|
||||
<a href="/docs/connect/dev.html">Develop and Debug</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-connect-security") %>>
|
||||
<a href="/docs/connect/security.html">Security</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("docs-guides") %>>
|
||||
|
|
|
|||
|
|
@ -47,6 +47,9 @@
|
|||
<li<%= sidebar_current("gettingstarted-services") %>>
|
||||
<a href="/intro/getting-started/services.html">Services</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("gettingstarted-connect") %>>
|
||||
<a href="/intro/getting-started/connect.html">Connect</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("gettingstarted-join") %>>
|
||||
<a href="/intro/getting-started/join.html">Consul Cluster</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue