2018-05-29 21:07:40 +00:00
|
|
|
---
|
|
|
|
layout: api
|
|
|
|
page_title: Connect - Agent - HTTP API
|
2020-04-07 18:55:19 +00:00
|
|
|
description: >-
|
2023-05-05 17:41:40 +00:00
|
|
|
The /agent/connect endpoints interact with agent-local service mesh
|
2020-04-07 18:55:19 +00:00
|
|
|
operations.
|
2018-05-29 21:07:40 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Connect - Agent HTTP API
|
|
|
|
|
2023-05-05 17:41:40 +00:00
|
|
|
The `/agent/connect` endpoints interact with
|
|
|
|
with agent-local [service mesh](/consul/docs/connect) operations.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2023-05-05 17:41:40 +00:00
|
|
|
These endpoints may mirror the [non-agent service mesh endpoints](/consul/api-docs/connect)
|
|
|
|
in some cases. Almost all agent-local service mesh endpoints perform local caching
|
|
|
|
to optimize performance of the mesh without having to make requests to the server.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
## Authorize
|
|
|
|
|
2020-10-14 15:23:05 +00:00
|
|
|
-> **Note:** This endpoint will always treat intentions with `Permissions`
|
2020-12-08 23:24:36 +00:00
|
|
|
defined as _deny_ intentions during evaluation, as this endpoint is only suited
|
|
|
|
for networking layer 4 (e.g. TCP) integration.
|
2020-10-14 15:23:05 +00:00
|
|
|
For performance and reliability reasons it is desirable to implement intention
|
|
|
|
enforcement by listing [intentions that match the
|
2023-01-25 16:52:43 +00:00
|
|
|
destination](/consul/api-docs/connect/intentions#list-matching-intentions) and representing
|
2020-10-14 15:23:05 +00:00
|
|
|
them in the native configuration of the proxy itself (such as RBAC for Envoy).
|
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
This endpoint tests whether a connection attempt is authorized between
|
|
|
|
two services. This is the primary API that must be implemented by
|
2023-01-25 16:52:43 +00:00
|
|
|
[proxies](/consul/docs/connect/proxies) or
|
|
|
|
[native integrations](/consul/docs/connect/native)
|
2023-05-05 17:41:40 +00:00
|
|
|
that wish to integrate with the service mesh. Prior to calling this API, it is expected
|
2018-05-29 21:07:40 +00:00
|
|
|
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.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------------- | ------------------ |
|
|
|
|
| `POST` | `/agent/connect/authorize` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 16:52:43 +00:00
|
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------- | --------------- |
|
|
|
|
| `NO` | `none` | `background refresh` | `service:write` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2022-05-10 15:51:11 +00:00
|
|
|
### Query Parameters
|
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the target service.
|
|
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
|
|
|
|
### JSON Request Body Schema
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
- `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
|
2021-03-18 18:39:25 +00:00
|
|
|
number for the requesting client cert.
|
2020-04-06 20:27:35 +00:00
|
|
|
|
2020-04-23 22:13:18 +00:00
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
2022-05-10 15:51:11 +00:00
|
|
|
the target service. This field takes precedence over the `ns` query parameter,
|
|
|
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### 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
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
2018-08-28 16:07:15 +00:00
|
|
|
http://127.0.0.1:8500/v1/agent/connect/authorize
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### 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.
|
2023-01-25 16:52:43 +00:00
|
|
|
This is used by [proxies](/consul/docs/connect/proxies) or
|
|
|
|
[native integrations](/consul/docs/connect/native) to verify served client
|
2018-05-29 21:07:40 +00:00
|
|
|
or server certificates are valid.
|
|
|
|
|
2023-05-05 17:41:40 +00:00
|
|
|
This is equivalent to the [non-Agent service mesh endpoint](/consul/api-docs/connect),
|
2018-05-29 21:07:40 +00:00
|
|
|
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.
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------------------- | ------------------ |
|
|
|
|
| `GET` | `/agent/connect/ca/roots` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 16:52:43 +00:00
|
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------- | ------------ |
|
|
|
|
| `YES` | `all` | `background refresh` | `none` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2019-04-26 11:53:20 +00:00
|
|
|
http://127.0.0.1:8500/v1/agent/connect/ca/roots
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### 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,
|
2019-09-23 17:52:35 +00:00
|
|
|
"SigningKeyID": "1f:91:ca:41:8f:ac:67:bf:59:c2:fa:4e:75:5c:d8:f0:55:de:be:75:b8:33:31:d5:24:b0:04:b3:e8:97:5b:7e",
|
|
|
|
"ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4",
|
2018-05-29 21:07:40 +00:00
|
|
|
"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,
|
2019-11-01 13:20:26 +00:00
|
|
|
"PrivateKeyType": "ec",
|
|
|
|
"PrivateKeyBits": 256,
|
2018-05-29 21:07:40 +00:00
|
|
|
"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
|
2023-01-25 16:52:43 +00:00
|
|
|
[CA sign API](/consul/api-docs/connect/ca) to sign it. The resulting certificate
|
2018-05-29 21:07:40 +00:00
|
|
|
is cached and returned by this API until it is near expiry or the root
|
|
|
|
certificates change.
|
|
|
|
|
2021-12-03 18:44:36 +00:00
|
|
|
Non blocking queries to this endpoint will always check that the leaf certificate is not expired
|
|
|
|
and that the root certificates have not changed. Otherwise, a new leaf certificate is generated.
|
|
|
|
|
|
|
|
This API supports blocking queries. The blocking query will block until
|
|
|
|
a new certificate is necessary (because the existing certificate will expire, is expired,
|
|
|
|
or the root certificate is being rotated), or until the query timeout is reached. The current
|
|
|
|
query timeout is set to 10 minutes. This blocking behavior allows clients to
|
|
|
|
wait for certificate rotations.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------------- | ------------------ |
|
|
|
|
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 16:52:43 +00:00
|
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------- | --------------- |
|
|
|
|
| `YES` | `all` | `background refresh` | `service:write` |
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2022-05-10 15:51:11 +00:00
|
|
|
### Path Parameters
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2022-05-10 15:51:11 +00:00
|
|
|
- `service` `(string: <required>)` - The name of the service for the leaf certificate.
|
|
|
|
The service does not need to exist in the catalog, but the proper ACL permissions must be available.
|
2018-05-29 21:07:40 +00:00
|
|
|
|
2022-05-10 15:51:11 +00:00
|
|
|
### Query Parameters
|
|
|
|
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the leaf certificate you request.
|
|
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
2021-08-02 18:55:23 +00:00
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
### Sample Request
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
```shell-session
|
2018-05-29 21:07:40 +00:00
|
|
|
$ curl \
|
2019-04-26 11:53:20 +00:00
|
|
|
http://127.0.0.1:8500/v1/agent/connect/ca/leaf/web
|
2018-05-29 21:07:40 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### 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",
|
2021-08-02 18:55:23 +00:00
|
|
|
"Namespace": "default",
|
2018-05-29 21:07:40 +00:00
|
|
|
"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.
|
2022-05-10 15:51:11 +00:00
|
|
|
|
|
|
|
## Methods to Specify Namespace <EnterpriseAlert inline />
|
|
|
|
|
2023-05-05 17:41:40 +00:00
|
|
|
Local agent service mesh endpoints
|
2022-05-10 15:51:11 +00:00
|
|
|
support several methods for specifying the namespace of resources
|
|
|
|
with the following order of precedence:
|
|
|
|
1. `Namespace` field of the JSON request body -
|
|
|
|
only applies to the [register](#register-check) endpoint
|
|
|
|
1. `ns` query parameter
|
|
|
|
1. `X-Consul-Namespace` request header
|
|
|
|
1. Namespace is inherited from the namespace of the request's ACL token (if any)
|
|
|
|
1. The `default` namespace
|