github.com/clly/consul@v1.4.5/website/source/api/agent/connect.html.md (about) 1 --- 2 layout: api 3 page_title: Connect - Agent - HTTP API 4 sidebar_current: api-agent-connect 5 description: |- 6 The /agent/connect endpoints interact with Connect with agent-local operations. 7 --- 8 9 # Connect - Agent HTTP API 10 11 The `/agent/connect` endpoints interact with [Connect](/docs/connect/index.html) 12 with agent-local operations. 13 14 These endpoints may mirror the [non-agent Connect endpoints](/api/connect.html) 15 in some cases. Almost all agent-local Connect endpoints perform local caching 16 to optimize performance of Connect without having to make requests to the server. 17 18 ## Authorize 19 20 This endpoint tests whether a connection attempt is authorized between 21 two services. This is the primary API that must be implemented by 22 [proxies](/docs/connect/proxies.html) or 23 [native integrations](/docs/connect/native.html) 24 that wish to integrate with Connect. Prior to calling this API, it is expected 25 that the client TLS certificate has been properly verified against the 26 current CA roots. 27 28 The implementation of this API uses locally cached data 29 and doesn't require any request forwarding to a server. Therefore, the 30 response typically occurs in microseconds to impose minimal overhead on the 31 connection attempt. 32 33 | Method | Path | Produces | 34 | ------ | ---------------------------- | -------------------------- | 35 | `POST` | `/agent/connect/authorize` | `application/json` | 36 37 The table below shows this endpoint's support for 38 [blocking queries](/api/index.html#blocking-queries), 39 [consistency modes](/api/index.html#consistency-modes), 40 [agent caching](/api/index.html#agent-caching), and 41 [required ACLs](/api/index.html#acls). 42 43 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 44 | ---------------- | ----------------- | -------------------- | --------------- | 45 | `NO` | `none` | `background refresh` | `service:write` | 46 47 ### Parameters 48 49 - `Target` `(string: <required>)` - The name of the service that is being 50 requested. 51 52 - `ClientCertURI` `(string: <required>)` - The unique identifier for the 53 requesting client. This is currently the URI SAN from the TLS client 54 certificate. 55 56 - `ClientCertSerial` `(string: <required>)` - The colon-hex-encoded serial 57 number for the requesting client cert. This is used to check against 58 revocation lists. 59 60 ### Sample Payload 61 62 ```json 63 { 64 "Target": "db", 65 "ClientCertURI": "spiffe://dc1-7e567ac2-551d-463f-8497-f78972856fc1.consul/ns/default/dc/dc1/svc/web", 66 "ClientCertSerial": "04:00:00:00:00:01:15:4b:5a:c3:94" 67 } 68 ``` 69 70 ### Sample Request 71 72 ```text 73 $ curl \ 74 --request POST \ 75 --data @payload.json \ 76 http://127.0.0.1:8500/v1/agent/connect/authorize 77 ``` 78 79 ### Sample Response 80 81 ```json 82 { 83 "Authorized": true, 84 "Reason": "Matched intention: web => db (allow)" 85 } 86 ``` 87 88 ## Certificate Authority (CA) Roots 89 90 This endpoint returns the trusted certificate authority (CA) root certificates. 91 This is used by [proxies](/docs/connect/proxies.html) or 92 [native integrations](/docs/connect/native.html) to verify served client 93 or server certificates are valid. 94 95 This is equivalent to the [non-Agent Connect endpoint](/api/connect.html), 96 but the response of this request is cached locally at the agent. This allows 97 for very fast response times and for fail open behavior if the server is 98 unavailable. This endpoint should be used by proxies and native integrations. 99 100 | Method | Path | Produces | 101 | ------ | ---------------------------- | -------------------------- | 102 | `GET` | `/agent/connect/ca/roots` | `application/json` | 103 104 The table below shows this endpoint's support for 105 [blocking queries](/api/index.html#blocking-queries), 106 [consistency modes](/api/index.html#consistency-modes), 107 [agent caching](/api/index.html#agent-caching), and 108 [required ACLs](/api/index.html#acls). 109 110 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 111 | ---------------- | ----------------- | -------------------- | ------------ | 112 | `YES` | `all` | `background refresh` | `none` | 113 114 ### Sample Request 115 116 ```text 117 $ curl \ 118 http://127.0.0.1:8500/v1/connect/ca/roots 119 ``` 120 121 ### Sample Response 122 123 ```json 124 { 125 "ActiveRootID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7", 126 "Roots": [ 127 { 128 "ID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7", 129 "Name": "Consul CA Root Cert", 130 "SerialNumber": 7, 131 "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", 132 "NotBefore": "2018-05-21T16:33:28Z", 133 "NotAfter": "2028-05-18T16:33:28Z", 134 "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", 135 "IntermediateCerts": null, 136 "Active": true, 137 "CreateIndex": 8, 138 "ModifyIndex": 8 139 } 140 ] 141 } 142 ``` 143 144 ## Service Leaf Certificate 145 146 This endpoint returns the leaf certificate representing a single service. 147 This certificate is used as a server certificate for accepting inbound 148 connections and is also used as the client certificate for establishing 149 outbound connections to other services. 150 151 The agent generates a CSR locally and calls the 152 [CA sign API](/api/connect/ca.html) to sign it. The resulting certificate 153 is cached and returned by this API until it is near expiry or the root 154 certificates change. 155 156 This API supports blocking queries. The blocking query will block until 157 a new certificate is necessary because the existing certificate will expire 158 or the root certificate is being rotated. This blocking behavior allows 159 clients to efficiently wait for certificate rotations. 160 161 | Method | Path | Produces | 162 | ------ | ---------------------------- | -------------------------- | 163 | `GET` | `/agent/connect/ca/leaf/:service` | `application/json` | 164 165 The table below shows this endpoint's support for 166 [blocking queries](/api/index.html#blocking-queries), 167 [consistency modes](/api/index.html#consistency-modes), 168 [agent caching](/api/index.html#agent-caching), and 169 [required ACLs](/api/index.html#acls). 170 171 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 172 | ---------------- | ----------------- | -------------------- | --------------- | 173 | `YES` | `all` | `background refresh` | `service:write` | 174 175 ### Parameters 176 177 - `Service` `(string: <required>)` - The name of the service for the leaf 178 certificate. This is specified in the URL. The service does not need to 179 exist in the catalog, but the proper ACL permissions must be available. 180 181 ### Sample Request 182 183 ```text 184 $ curl \ 185 http://127.0.0.1:8500/v1/connect/ca/leaf/web 186 ``` 187 188 ### Sample Response 189 190 ```json 191 { 192 "SerialNumber": "08", 193 "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", 194 "PrivateKeyPEM": "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIAOGglbwY8HdD3LFX6Bc94co2pzeFTto8ebWoML5E+QfoAoGCCqGSM49\nAwEHoUQDQgAEl0upEp3VJHJwU4Vx4wc4FkpBbwcc7yNnkLx1GzAP4jBN3+i0k+Jo\n+tXMY4CLgyxoRSAMx6a83WOLLAe3cgjTyQ==\n-----END EC PRIVATE KEY-----\n", 195 "Service": "web", 196 "ServiceURI": "spiffe://11111111-2222-3333-4444-555555555555.consul/ns/default/dc/dc1/svc/web", 197 "ValidAfter": "2018-05-21T16:33:28Z", 198 "ValidBefore": "2018-05-24T16:33:28Z", 199 "CreateIndex": 5, 200 "ModifyIndex": 5 201 } 202 ``` 203 204 - `SerialNumber` `string` - Monotonically increasing 64-bit serial number 205 representing all certificates issued by this Consul cluster. 206 207 - `CertPEM` `(string)` - The PEM-encoded certificate. 208 209 - `PrivateKeyPEM` `(string)` - The PEM-encoded private key for this certificate. 210 211 - `Service` `(string)` - The name of the service that this certificate identifies. 212 213 - `ServiceURI` `(string)` - The URI SAN for this service. 214 215 - `ValidAfter` `(string)` - The time after which the certificate is valid. 216 Used with `ValidBefore` this can determine the validity period of the certificate. 217 218 - `ValidBefore` `(string)` - The time before which the certificate is valid. 219 Used with `ValidAfter` this can determine the validity period of the certificate. 220 221 ## Managed Proxy Configuration ([Deprecated](/docs/connect/proxies/managed-deprecated.html)) 222 223 This endpoint returns the configuration for a [managed 224 proxy](/docs/connect/proxies.html). Ths endpoint is only useful for _managed 225 proxies_ and not relevant for unmanaged proxies. This endpoint will be removed 226 in a future major release as part of [managed proxy 227 deprecation].(/docs/connect/proxies/managed-deprecated.html). The equivalent API 228 for use will all future proxies is the more generic ` 229 230 Managed proxy configuration is set in the service definition. When Consul 231 starts the managed proxy, it provides the service ID and ACL token. The proxy 232 is expected to call this endpoint to retrieve its configuration. It may use 233 a blocking query to detect any configuration changes. 234 235 | Method | Path | Produces | 236 | ------ | ---------------------------- | -------------------------- | 237 | `GET` | `/agent/connect/proxy/:id` | `application/json` | 238 239 The table below shows this endpoint's support for 240 [blocking queries](/api/index.html#blocking-queries), 241 [consistency modes](/api/index.html#consistency-modes), 242 [agent caching](/api/index.html#agent-caching), and 243 [required ACLs](/api/index.html#acls). 244 245 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 246 | ---------------- | ----------------- | ------------- | ---------------------------- | 247 | `YES`<sup>1</sup>| `all` | `none` | `service:write, proxy token` | 248 249 <sup>1</sup> Supports [hash-based 250 blocking](/api/index.html#hash-based-blocking-queries) only. 251 252 ### Parameters 253 254 - `ID` `(string: <required>)` - The ID (not the name) of the proxy service 255 in the local agent catalog. For managed proxies, this is provided in the 256 `CONSUL_PROXY_ID` environment variable by Consul. 257 258 ### Sample Request 259 260 ```text 261 $ curl \ 262 http://127.0.0.1:8500/v1/connect/proxy/web-proxy 263 ``` 264 265 ### Sample Response 266 267 ```json 268 { 269 "ProxyServiceID": "web-proxy", 270 "TargetServiceID": "web", 271 "TargetServiceName": "web", 272 "ContentHash": "cffa5f4635b134b9", 273 "ExecMode": "daemon", 274 "Command": [ 275 "/usr/local/bin/consul", 276 "connect", 277 "proxy" 278 ], 279 "Config": { 280 "bind_address": "127.0.0.1", 281 "bind_port": 20199, 282 "local_service_address": "127.0.0.1:8181" 283 }, 284 "Upstreams": [ 285 { 286 "DestinationType": "service", 287 "DestinationName": "db", 288 "LocalBindPort": 1234, 289 "Config": { 290 "connect_timeout_ms": 1000 291 } 292 }, 293 { 294 "DestinationType": "prepared_query", 295 "DestinationName": "geo-cache", 296 "LocalBindPort": 1235 297 } 298 ] 299 } 300 ``` 301 302 - `ProxyServiceID` `string` - The ID of the proxy service. 303 304 - `TargetServiceID` `(string)` - The ID of the target service the proxy represents. 305 306 - `TargetServiceName` `(string)` - The name of the target service the proxy represents. 307 308 - `ContentHash` `(string)` - The content hash of the response used for hash-based 309 blocking queries. 310 311 - `ExecMode` `(string)` - The execution mode of the managed proxy. 312 313 - `Command` `(array<string>)` - The command for the managed proxy. 314 315 - `Config` `(map<string|any>)` - The configuration for the managed proxy. This 316 is a map of primitive values (including arrays and maps) that is set by the 317 user. 318 319 - `Upstreams` `(array<Upstream>)` - The configured upstreams for the proxy. See 320 [Upstream Configuration Reference](/docs/connect/proxies.html#upstream-configuration-reference) 321 for more details on the format.