mirror of https://github.com/status-im/consul.git
docs: all intention documentation updates (#8869)
This commit is contained in:
parent
891c4026c1
commit
f0d47ded95
|
@ -60,6 +60,7 @@ export default [
|
||||||
content: ['service-registration', 'sidecar-service'],
|
content: ['service-registration', 'sidecar-service'],
|
||||||
},
|
},
|
||||||
'intentions',
|
'intentions',
|
||||||
|
'intentions-legacy',
|
||||||
'observability',
|
'observability',
|
||||||
{
|
{
|
||||||
category: 'l7-traffic',
|
category: 'l7-traffic',
|
||||||
|
@ -195,6 +196,7 @@ export default [
|
||||||
'ingress-gateway',
|
'ingress-gateway',
|
||||||
'proxy-defaults',
|
'proxy-defaults',
|
||||||
'service-defaults',
|
'service-defaults',
|
||||||
|
'service-intentions',
|
||||||
'service-resolver',
|
'service-resolver',
|
||||||
'service-router',
|
'service-router',
|
||||||
'service-splitter',
|
'service-splitter',
|
||||||
|
|
|
@ -73,7 +73,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
||||||
create the auth method within. If not provided in the JSON body, the value of
|
create the auth method within. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
|
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
|
||||||
|
@ -252,7 +252,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the auth method to update. If not provided in the JSON body, the value of
|
the auth method to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
|
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - A set
|
||||||
|
|
|
@ -101,7 +101,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
||||||
create the binding rule. If not provided in the JSON body, the value of
|
create the binding rule. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -281,7 +281,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the binding rule to update. If not provided in the JSON body, the value of
|
the binding rule to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
|
@ -7,7 +7,7 @@ description: The /acl endpoints manage the Consul's ACL system.
|
||||||
|
|
||||||
# ACL HTTP API
|
# ACL HTTP API
|
||||||
|
|
||||||
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
|
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
|
||||||
|
|
||||||
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens) and [policies](/api/acl/policies) with the `/acl` endpoints.
|
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens) and [policies](/api/acl/policies) with the `/acl` endpoints.
|
||||||
|
|
||||||
|
@ -306,7 +306,7 @@ replication enabled.
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token, or will default to the `default` namespace. Added in Consul 1.7.0.
|
token, or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -434,7 +434,7 @@ replication enabled.
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token, or will default to the `default` namespace.
|
token, or will default to the `default` namespace.
|
||||||
|
|
||||||
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
|
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
|
||||||
|
@ -518,7 +518,7 @@ replication enabled.
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
the Auth Method to use for Login. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token, or will default to the `default` namespace.
|
token, or will default to the `default` namespace.
|
||||||
|
|
||||||
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
|
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
|
||||||
|
|
|
@ -7,7 +7,7 @@ description: The /acl/policy endpoints manage Consul's ACL policies.
|
||||||
|
|
||||||
# ACL Policy HTTP API
|
# ACL Policy HTTP API
|
||||||
|
|
||||||
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
|
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
|
||||||
|
|
||||||
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
|
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
|
||||||
[update](#update-a-policy), [list](#list-policies) and
|
[update](#update-a-policy), [list](#list-policies) and
|
||||||
|
@ -52,7 +52,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
||||||
create the policy. If not provided in the JSON body, the value of
|
create the policy. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -229,7 +229,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the policy to update. If not provided in the JSON body, the value of
|
the policy to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
|
@ -77,7 +77,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
||||||
create the role. If not provided in the JSON body, the value of
|
create the role. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -342,7 +342,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the role to update. If not provided in the JSON body, the value of
|
the role to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
|
@ -7,7 +7,7 @@ description: The /acl/token endpoints manage Consul's ACL Tokens.
|
||||||
|
|
||||||
# ACL Token HTTP API
|
# ACL Token HTTP API
|
||||||
|
|
||||||
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
|
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy).
|
||||||
|
|
||||||
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
|
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
|
||||||
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
|
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
|
||||||
|
@ -103,7 +103,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to
|
||||||
create the token. If not provided in the JSON body, the value of
|
create the token. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -364,7 +364,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the token to update. If not provided in the JSON body, the value of
|
the token to update. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
@ -452,7 +452,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the token to be cloned. If not provided in the JSON body, the value of
|
the token to be cloned. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
|
@ -18,6 +18,14 @@ to optimize performance of Connect without having to make requests to the server
|
||||||
|
|
||||||
## Authorize
|
## Authorize
|
||||||
|
|
||||||
|
-> **Note:** This endpoint will always treat intentions with `Permissions`
|
||||||
|
defined as *deny* intentions during evaluation, as this endpoint is only suited
|
||||||
|
for networking layer 4 (e.g. TCP) integration.
|
||||||
|
For performance and reliability reasons it is desirable to implement intention
|
||||||
|
enforcement by listing [intentions that match the
|
||||||
|
destination](/api/connect/intentions#list-matching-intentions) and representing
|
||||||
|
them in the native configuration of the proxy itself (such as RBAC for Envoy).
|
||||||
|
|
||||||
This endpoint tests whether a connection attempt is authorized between
|
This endpoint tests whether a connection attempt is authorized between
|
||||||
two services. This is the primary API that must be implemented by
|
two services. This is the primary API that must be implemented by
|
||||||
[proxies](/docs/connect/proxies) or
|
[proxies](/docs/connect/proxies) or
|
||||||
|
@ -61,7 +69,7 @@ The table below shows this endpoint's support for
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of
|
||||||
the target service. If not provided in the JSON body, the value of
|
the target service. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
|
@ -92,7 +92,7 @@ The table below shows this endpoint's support for
|
||||||
service and checks will be registered. This value may be provided by either the
|
service and checks will be registered. This value may be provided by either the
|
||||||
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
|
`ns` URL query parameter or in the `X-Consul-Namespace` header. Additionally,
|
||||||
the namespace may be provided within the `Service` or `Check` fields but if
|
the namespace may be provided within the `Service` or `Check` fields but if
|
||||||
present in multiple places, they must all be the same. If not provided at all,
|
present in multiple places, they must all be the same. If not provided,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
@ -204,7 +204,7 @@ The behavior of the endpoint depends on what keys are provided.
|
||||||
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which the
|
||||||
service and checks will be deregistered. If not provided in the JSON body, the value of
|
service and checks will be deregistered. If not provided in the JSON body, the value of
|
||||||
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
|
the `ns` URL query parameter or the `X-Consul-Namespace` header will be used.
|
||||||
If not provided at all, the namespace will be inherited from the request's ACL
|
If not provided, the namespace will be inherited from the request's ACL
|
||||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Payloads
|
### Sample Payloads
|
||||||
|
@ -404,7 +404,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -473,7 +473,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to use for the
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to use for the
|
||||||
query. This value may be provided by either the `ns` URL query parameter or in the
|
query. This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -677,7 +677,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -804,7 +804,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list services.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. The `*`
|
from the request's ACL token or will default to the `default` namespace. The `*`
|
||||||
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
@ -933,7 +933,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the gateway.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. The `*`
|
from the request's ACL token or will default to the `default` namespace. The `*`
|
||||||
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
wildcard may be used and then services from all namespaces will be returned. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
|
|
@ -13,7 +13,7 @@ The `/config` endpoints create, update, delete and query central configuration
|
||||||
entries registered with Consul. See the
|
entries registered with Consul. See the
|
||||||
[agent configuration](/docs/agent/options#enable_central_service_config)
|
[agent configuration](/docs/agent/options#enable_central_service_config)
|
||||||
for more information on how to enable this functionality for centrally
|
for more information on how to enable this functionality for centrally
|
||||||
configuring services and [configuration entries docs](/docs/agent/config_entries) for a description
|
configuring services and [configuration entries docs](/docs/agent/config-entries) for a description
|
||||||
of the configuration entries content.
|
of the configuration entries content.
|
||||||
|
|
||||||
## Apply Configuration
|
## Apply Configuration
|
||||||
|
@ -38,15 +38,16 @@ The table below shows this endpoint's support for
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being updated:
|
<sup>1</sup> The ACL required depends on the config entry kind being updated:
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ------------------- | ---------------- |
|
| ------------------- | ------------------ |
|
||||||
| ingress-gateway | `operator:write` |
|
| ingress-gateway | `operator:write` |
|
||||||
| proxy-defaults | `operator:write` |
|
| proxy-defaults | `operator:write` |
|
||||||
| service-defaults | `service:write` |
|
| service-defaults | `service:write` |
|
||||||
| service-resolver | `service:write` |
|
| service-intentions | `intentions:write` |
|
||||||
| service-router | `service:write` |
|
| service-resolver | `service:write` |
|
||||||
| service-splitter | `service:write` |
|
| service-router | `service:write` |
|
||||||
| terminating-gateway | `operator:write` |
|
| service-splitter | `service:write` |
|
||||||
|
| terminating-gateway | `operator:write` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
@ -61,7 +62,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace the config
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace the config
|
||||||
entry will apply to. This value may be provided by either the `ns` URL query
|
entry will apply to. This value may be provided by either the `ns` URL query
|
||||||
parameter or in the `X-Consul-Namespace` header. If not provided at all,
|
parameter or in the `X-Consul-Namespace` header. If not provided,
|
||||||
the namespace will be inherited from the request's ACL token or will default
|
the namespace will be inherited from the request's ACL token or will default
|
||||||
to the `default` namespace. Added in Consul 1.7.0.
|
to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
@ -104,15 +105,16 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ------------------- | -------------- |
|
| ------------------- | ----------------- |
|
||||||
| ingress-gateway | `service:read` |
|
| ingress-gateway | `service:read` |
|
||||||
| proxy-defaults | `<none>` |
|
| proxy-defaults | `<none>` |
|
||||||
| service-defaults | `service:read` |
|
| service-defaults | `service:read` |
|
||||||
| service-resolver | `service:read` |
|
| service-intentions | `intentions:read` |
|
||||||
| service-router | `service:read` |
|
| service-resolver | `service:read` |
|
||||||
| service-splitter | `service:read` |
|
| service-router | `service:read` |
|
||||||
| terminating-gateway | `service:read` |
|
| service-splitter | `service:read` |
|
||||||
|
| terminating-gateway | `service:read` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
@ -128,7 +130,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited from
|
||||||
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -171,15 +173,16 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
<sup>1</sup> The ACL required depends on the config entry kind being read:
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ------------------- | -------------- |
|
| ------------------- | ----------------- |
|
||||||
| ingress-gateway | `service:read` |
|
| ingress-gateway | `service:read` |
|
||||||
| proxy-defaults | `<none>` |
|
| proxy-defaults | `<none>` |
|
||||||
| service-defaults | `service:read` |
|
| service-defaults | `service:read` |
|
||||||
| service-resolver | `service:read` |
|
| service-intentions | `intentions:read` |
|
||||||
| service-router | `service:read` |
|
| service-resolver | `service:read` |
|
||||||
| service-splitter | `service:read` |
|
| service-router | `service:read` |
|
||||||
| terminating-gateway | `service:read` |
|
| service-splitter | `service:read` |
|
||||||
|
| terminating-gateway | `service:read` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
@ -192,7 +195,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited from
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited from
|
||||||
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -244,15 +247,16 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
<sup>1</sup> The ACL required depends on the config entry kind being deleted:
|
<sup>1</sup> The ACL required depends on the config entry kind being deleted:
|
||||||
|
|
||||||
| Config Entry Kind | Required ACL |
|
| Config Entry Kind | Required ACL |
|
||||||
| ------------------- | ---------------- |
|
| ------------------- | ---------------- |
|
||||||
| ingress-gateway | `operator:write` |
|
| ingress-gateway | `operator:write` |
|
||||||
| proxy-defaults | `operator:write` |
|
| proxy-defaults | `operator:write` |
|
||||||
| service-defaults | `service:write` |
|
| service-defaults | `service:write` |
|
||||||
| service-resolver | `service:write` |
|
| service-intentions | `intentions:write` |
|
||||||
| service-router | `service:write` |
|
| service-resolver | `service:write` |
|
||||||
| service-splitter | `service:write` |
|
| service-router | `service:write` |
|
||||||
| terminating-gateway | `operator:write` |
|
| service-splitter | `service:write` |
|
||||||
|
| terminating-gateway | `operator:write ` |
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
|
@ -268,7 +272,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to delete from.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to delete from.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
|
@ -12,7 +12,127 @@ description: |-
|
||||||
The `/connect/intentions` endpoint provide tools for managing
|
The `/connect/intentions` endpoint provide tools for managing
|
||||||
[intentions](/docs/connect/intentions).
|
[intentions](/docs/connect/intentions).
|
||||||
|
|
||||||
## Create Intention
|
-> **1.9.0 and later:** Reading and writing intentions has been
|
||||||
|
migrated to the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions)
|
||||||
|
config entry kind.
|
||||||
|
|
||||||
|
## Upsert Intention by Name ((#upsert-intention-by-name)) <sup>Beta</sup>
|
||||||
|
|
||||||
|
-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
|
||||||
|
|
||||||
|
This endpoint creates a new intention and returns `true` if it was created
|
||||||
|
successfully.
|
||||||
|
|
||||||
|
The name and destination pair must be unique. If another intention matches the
|
||||||
|
name and destination, the creation will replace the previous intention.
|
||||||
|
|
||||||
|
~> The intentions created by this endpoint will not be assigned the following
|
||||||
|
fields: `ID`, `CreatedAt`, `UpdatedAt`. Additionally, the `Meta` field cannot
|
||||||
|
be persisted using this endpoint and will require editing the enclosing
|
||||||
|
`service-intentions` config entry for the destination.
|
||||||
|
|
||||||
|
| Method | Path | Produces |
|
||||||
|
| ------ | --------------------------- | ------------------ |
|
||||||
|
| `PUT` | `/connect/intentions/exact` | `application/json` |
|
||||||
|
|
||||||
|
The table below shows this endpoint's support for
|
||||||
|
[blocking queries](/api/features/blocking),
|
||||||
|
[consistency modes](/api/features/consistency),
|
||||||
|
[agent caching](/api/features/caching), and
|
||||||
|
[required ACLs](/api#authentication).
|
||||||
|
|
||||||
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||||
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
|
See{' '}
|
||||||
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
|
Intention Management Permissions
|
||||||
|
</a>{' '}
|
||||||
|
for more details.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
### URL Parameters
|
||||||
|
|
||||||
|
- `source` `(string: <required>)` - Specifies the source service. This
|
||||||
|
is specified as part of the URL.
|
||||||
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
||||||
|
is specified as part of the URL.
|
||||||
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
||||||
|
If not provided, the default namespace will be inherited from the
|
||||||
|
request's ACL token or will default to the `default` namespace.
|
||||||
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
|
`X-Consul-Namespace` header.
|
||||||
|
Added in Consul 1.9.0.
|
||||||
|
|
||||||
|
### PUT Body Parameters
|
||||||
|
|
||||||
|
- `SourceType` `(string: "")` - The type for the `SourceName` value.
|
||||||
|
This can be only "consul" today to represent a Consul service. If not
|
||||||
|
provided, this will be defaulted to "consul".
|
||||||
|
|
||||||
|
- `Action` `(string: "")` - For an L4 intention this is required, and should be
|
||||||
|
set to one of "allow" or "deny" for the action that should be taken if
|
||||||
|
this intention matches a request.
|
||||||
|
|
||||||
|
This should be omitted for an L7 intention as it is mutually exclusive with
|
||||||
|
the `Permissions` field.
|
||||||
|
|
||||||
|
- `Permissions` `(array<IntentionPermission>)` - The list of all [additional L7
|
||||||
|
attributes](/docs/agent/config-entries/service-intentions#intentionpermission)
|
||||||
|
that extend the intention match criteria.
|
||||||
|
|
||||||
|
Permission precedence is applied top to bottom. For any given request the
|
||||||
|
first permission to match in the list is terminal and stops further
|
||||||
|
evaluation. As with L4 intentions, traffic that fails to match any of the
|
||||||
|
provided permissions in this intention will be subject to the default
|
||||||
|
intention behavior is defined by the default [ACL
|
||||||
|
policy](/docs/agent/options#acl_default_policy).
|
||||||
|
|
||||||
|
This should be omitted for an L4 intention as it is mutually exclusive with
|
||||||
|
the `Action` field.
|
||||||
|
|
||||||
|
- `Description` `(string: "")` - Description for the intention. This is not
|
||||||
|
used by Consul, but is presented in API responses to assist tooling.
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"SourceType": "consul",
|
||||||
|
"Action": "allow"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
true
|
||||||
|
```
|
||||||
|
|
||||||
|
## Create Intention with ID
|
||||||
|
|
||||||
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
||||||
|
[upserting by name](#upsert-intention-by-name) or editing the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entry for the destination.
|
||||||
|
|
||||||
This endpoint creates a new intention and returns its ID if it was created
|
This endpoint creates a new intention and returns its ID if it was created
|
||||||
successfully.
|
successfully.
|
||||||
|
@ -36,7 +156,7 @@ The table below shows this endpoint's support for
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -44,7 +164,17 @@ The table below shows this endpoint's support for
|
||||||
for more details.
|
for more details.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
### Parameters
|
### URL Parameters
|
||||||
|
|
||||||
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
|
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
|
||||||
|
If not provided, the default namespace will be inherited from the
|
||||||
|
request's ACL token or will default to the `default` namespace.
|
||||||
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
|
`X-Consul-Namespace` header.
|
||||||
|
Added in Consul 1.9.0.
|
||||||
|
|
||||||
|
### POST Body Parameters
|
||||||
|
|
||||||
- `SourceName` `(string: <required>)` - The source of the intention.
|
- `SourceName` `(string: <required>)` - The source of the intention.
|
||||||
For a `SourceType` of `consul` this is the name of a Consul service. The
|
For a `SourceType` of `consul` this is the name of a Consul service. The
|
||||||
|
@ -60,26 +190,18 @@ The table below shows this endpoint's support for
|
||||||
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
- `DestinationNS` `(string: "")` <EnterpriseAlert inline /> - The namespace for the
|
||||||
`DestinationName` parameter.
|
`DestinationName` parameter.
|
||||||
|
|
||||||
- `SourceType` `(string: <required>)` - The type for the `SourceName` value.
|
- `SourceType` `(string: "")` - The type for the `SourceName` value.
|
||||||
This can be only "consul" today to represent a Consul service.
|
This can be only "consul" today to represent a Consul service. If not
|
||||||
|
provided, this will be defaulted to "consul".
|
||||||
|
|
||||||
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
|
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
|
||||||
the action that should be taken if this intention matches a request.
|
the action that should be taken if this intention matches a request.
|
||||||
|
|
||||||
- `Description` `(string: "")` - Description for the intention. This is not
|
- `Description` `(string: "")` - Description for the intention. This is not
|
||||||
used for anything by Consul, but is presented in API responses to assist
|
used by Consul, but is presented in API responses to assist tooling.
|
||||||
tooling.
|
|
||||||
|
|
||||||
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
|
||||||
namespace to use when `SourceNS` or `DestinationNS` are omitted or empty.
|
|
||||||
If not provided at all, the default namespace will be inherited from the
|
|
||||||
request's ACL token or will default to the `default` namespace.
|
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
|
||||||
`X-Consul-Namespace` header.
|
|
||||||
Added in Consul 1.9.0.
|
|
||||||
|
|
||||||
### Sample Payload
|
### Sample Payload
|
||||||
|
|
||||||
```json
|
```json
|
||||||
|
@ -108,13 +230,18 @@ $ curl \
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Read Specific Intention
|
## Update Intention by ID
|
||||||
|
|
||||||
This endpoint reads a specific intention.
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
||||||
|
[upserting by name](#upsert-intention-by-name) or editing the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entry for the destination.
|
||||||
|
|
||||||
|
This endpoint updates an intention with the given values.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
| Method | Path | Produces |
|
||||||
| ------ | --------------------------- | ------------------ |
|
| ------ | --------------------------- | ------------------ |
|
||||||
| `GET` | `/connect/intentions/:uuid` | `application/json` |
|
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking),
|
[blocking queries](/api/features/blocking),
|
||||||
|
@ -122,12 +249,12 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching), and
|
[agent caching](/api/features/caching), and
|
||||||
[required ACLs](/api#authentication).
|
[required ACLs](/api#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
||||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -137,38 +264,32 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
|
||||||
is specified as part of the URL.
|
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
|
### Sample Request
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ curl \
|
$ curl \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
||||||
```
|
```
|
||||||
|
|
||||||
### Sample Response
|
## Read Specific Intention by Name ((##read-specific-intention-by-name)) <sup>Beta</sup>
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
|
||||||
"Description": "",
|
|
||||||
"SourceNS": "default",
|
|
||||||
"SourceName": "web",
|
|
||||||
"DestinationNS": "default",
|
|
||||||
"DestinationName": "db",
|
|
||||||
"SourceType": "consul",
|
|
||||||
"Action": "allow",
|
|
||||||
"Meta": {},
|
|
||||||
"Precedence": 9,
|
|
||||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
|
||||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
|
||||||
"CreateIndex": 11,
|
|
||||||
"ModifyIndex": 11
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Read Specific Intention by Name
|
|
||||||
|
|
||||||
This endpoint reads a specific intention by its unique source and destination.
|
This endpoint reads a specific intention by its unique source and destination.
|
||||||
|
|
||||||
|
@ -187,7 +308,7 @@ The table below shows this endpoint's support for
|
||||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -199,15 +320,15 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `source` `(string: <required>)` - Specifies the source service. This
|
- `source` `(string: <required>)` - Specifies the source service. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- `destination` `(string: <required>)` - Specifies the destination service. This
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
namespace to use when `source` or `destination` parameters lack namespaces.
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
||||||
If not provided at all, the default namespace will be inherited from the
|
If not provided, the default namespace will be inherited from the
|
||||||
request's ACL token or will default to the `default` namespace.
|
request's ACL token or will default to the `default` namespace.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header.
|
`X-Consul-Namespace` header.
|
||||||
|
@ -222,6 +343,68 @@ $ curl \
|
||||||
|
|
||||||
### Sample Response
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Description": "",
|
||||||
|
"SourceNS": "default",
|
||||||
|
"SourceName": "web",
|
||||||
|
"DestinationNS": "default",
|
||||||
|
"DestinationName": "db",
|
||||||
|
"SourceType": "consul",
|
||||||
|
"Action": "allow",
|
||||||
|
"Meta": {},
|
||||||
|
"Precedence": 9,
|
||||||
|
"CreateIndex": 11,
|
||||||
|
"ModifyIndex": 11
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Read Specific Intention by ID
|
||||||
|
|
||||||
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
||||||
|
[reading by name](#read-specific-intention-by-name) or by viewing the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions)
|
||||||
|
config entry for the destination.
|
||||||
|
|
||||||
|
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/features/blocking),
|
||||||
|
[consistency modes](/api/features/consistency),
|
||||||
|
[agent caching](/api/features/caching), and
|
||||||
|
[required ACLs](/api#authentication).
|
||||||
|
|
||||||
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
|
See{' '}
|
||||||
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
|
Intention Management Permissions
|
||||||
|
</a>{' '}
|
||||||
|
for more details.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to read. This
|
||||||
|
is specified as part of the URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
||||||
|
@ -260,7 +443,7 @@ The table below shows this endpoint's support for
|
||||||
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
| `YES` | `all` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -276,7 +459,7 @@ The table below shows this endpoint's support for
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the
|
||||||
namespace to list intentions from.
|
namespace to list intentions from.
|
||||||
The `*` wildcard may be used to list intentions from all namespaces.
|
The `*` wildcard may be used to list intentions from all namespaces.
|
||||||
If not provided at all, the default namespace will be inherited from the
|
If not provided, the default namespace will be inherited from the
|
||||||
request's ACL token or will default to the `default` namespace.
|
request's ACL token or will default to the `default` namespace.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header.
|
`X-Consul-Namespace` header.
|
||||||
|
@ -294,7 +477,6 @@ $ curl \
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"SourceNS": "default",
|
"SourceNS": "default",
|
||||||
"SourceName": "web",
|
"SourceName": "web",
|
||||||
|
@ -304,8 +486,6 @@ $ curl \
|
||||||
"Action": "allow",
|
"Action": "allow",
|
||||||
"Meta": {},
|
"Meta": {},
|
||||||
"Precedence": 9,
|
"Precedence": 9,
|
||||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
|
||||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
|
||||||
"CreateIndex": 11,
|
"CreateIndex": 11,
|
||||||
"ModifyIndex": 11
|
"ModifyIndex": 11
|
||||||
}
|
}
|
||||||
|
@ -331,13 +511,15 @@ the following selectors and filter operations being supported:
|
||||||
| `SourceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `SourceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
| `SourceType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
| `SourceType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
||||||
|
|
||||||
## Update Intention
|
## Delete Intention by Name ((#delete-intention-by-name)) <sup>Beta</sup>
|
||||||
|
|
||||||
This endpoint updates an intention with the given values.
|
-> **1.9.0+:** This API is available in Consul versions 1.9.0 and later.
|
||||||
|
|
||||||
| Method | Path | Produces |
|
This endpoint deletes a specific intention by its unique source and destination.
|
||||||
| ------ | --------------------------- | ------------------ |
|
|
||||||
| `PUT` | `/connect/intentions/:uuid` | `application/json` |
|
| Method | Path | Produces |
|
||||||
|
| -------- | --------------------------- | ------------------ |
|
||||||
|
| `DELETE` | `/connect/intentions/exact` | `application/json` |
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
The table below shows this endpoint's support for
|
||||||
[blocking queries](/api/features/blocking),
|
[blocking queries](/api/features/blocking),
|
||||||
|
@ -345,12 +527,12 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching), and
|
[agent caching](/api/features/caching), and
|
||||||
[required ACLs](/api#authentication).
|
[required ACLs](/api#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ------------------------------ |
|
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -360,32 +542,36 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
### Parameters
|
### Parameters
|
||||||
|
|
||||||
- `uuid` `(string: <required>)` - Specifies the UUID of the intention to update. This
|
- `source` `(string: <required>)` - Specifies the source service. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- Other parameters are identical to creating an intention.
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
||||||
|
is specified as part of the URL.
|
||||||
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
### Sample Payload
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
||||||
```json
|
If not provided, the default namespace will be inherited from the
|
||||||
{
|
request's ACL token or will default to the `default` namespace.
|
||||||
"SourceName": "web",
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
"DestinationName": "other-db",
|
`X-Consul-Namespace` header.
|
||||||
"SourceType": "consul",
|
Added in Consul 1.9.0.
|
||||||
"Action": "allow"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ curl \
|
$ curl \
|
||||||
--request PUT \
|
--request DELETE \
|
||||||
--data @payload.json \
|
http://127.0.0.1:8500/v1/connect/intentions/exact?source=web&destination=db
|
||||||
http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Delete Intention
|
## Delete Intention by ID
|
||||||
|
|
||||||
|
-> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of
|
||||||
|
[deleting by name](#delete-intention-by-name) or editing the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entry for the destination.
|
||||||
|
|
||||||
This endpoint deletes a specific intention.
|
This endpoint deletes a specific intention.
|
||||||
|
|
||||||
|
@ -404,7 +590,7 @@ The table below shows this endpoint's support for
|
||||||
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:write`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -428,8 +614,17 @@ $ curl \
|
||||||
## Check Intention Result
|
## Check Intention Result
|
||||||
|
|
||||||
This endpoint evaluates the intentions for a specific source and destination
|
This endpoint evaluates the intentions for a specific source and destination
|
||||||
and returns whether the connection would be authorized or not given the
|
and returns whether the connection would be authorized or not given the current
|
||||||
current Consul configuration and set of intentions.
|
Consul configuration and set of intentions.
|
||||||
|
|
||||||
|
-> **Note:** This endpoint will always evaulate intentions with `Permissions`
|
||||||
|
defined as *deny* intentions during. This endpoint is only suited for
|
||||||
|
networking layer 4 (e.g. TCP) integration.
|
||||||
|
|
||||||
|
For performance and reliability reasons it is desirable to implement intention
|
||||||
|
enforcement by listing [intentions that match the
|
||||||
|
destination](/api/connect/intentions#list-matching-intentions) and representing
|
||||||
|
them in the native configuration of the proxy itself (such as RBAC for Envoy).
|
||||||
|
|
||||||
This endpoint will work even if the destination service has
|
This endpoint will work even if the destination service has
|
||||||
`intention = "deny"` specifically set, because the resulting API response
|
`intention = "deny"` specifically set, because the resulting API response
|
||||||
|
@ -450,7 +645,7 @@ The table below shows this endpoint's support for
|
||||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -462,15 +657,15 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `source` `(string: <required>)` - Specifies the source service. This
|
- `source` `(string: <required>)` - Specifies the source service. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- `destination` `(string: <required>)` - Specifies the destination service. This
|
- `destination` `(string: <required>)` - Specifies the destination service. This
|
||||||
is specified as part of the URL.
|
is specified as part of the URL.
|
||||||
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
namespace to use when `source` or `destination` parameters lack namespaces.
|
namespace to use when `source` or `destination` parameters lack namespaces.
|
||||||
If not provided at all, the default namespace will be inherited from the
|
If not provided, the default namespace will be inherited from the
|
||||||
request's ACL token or will default to the `default` namespace.
|
request's ACL token or will default to the `default` namespace.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header.
|
`X-Consul-Namespace` header.
|
||||||
|
@ -508,12 +703,12 @@ The table below shows this endpoint's support for
|
||||||
[agent caching](/api/features/caching), and
|
[agent caching](/api/features/caching), and
|
||||||
[required ACLs](/api#authentication).
|
[required ACLs](/api#authentication).
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||||
| ---------------- | ----------------- | ------------- | ----------------------------- |
|
| ---------------- | ----------------- | -------------------- | ----------------------------- |
|
||||||
| `NO` | `none` | `none` | `intentions:read`<sup>1</sup> |
|
| `YES` | `all` | `background refresh` | `intentions:read`<sup>1</sup> |
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
|
<sup>1</sup> Intention ACL rules are specified as part of a <code>service</code> rule.
|
||||||
See{' '}
|
See{' '}
|
||||||
<a href="/docs/connect/intentions#intention-management-permissions">
|
<a href="/docs/connect/intentions#intention-management-permissions">
|
||||||
Intention Management Permissions
|
Intention Management Permissions
|
||||||
|
@ -528,11 +723,11 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `name` `(string: <required>)` - Specifies a name to match. This parameter
|
- `name` `(string: <required>)` - Specifies a name to match. This parameter
|
||||||
can be repeated for batching multiple matches.
|
can be repeated for batching multiple matches.
|
||||||
This can take [several forms](/docs/commands/intention#source-and-destination-naming).
|
This can take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the default
|
||||||
namespace to use when `name` parameter lacks namespaces.
|
namespace to use when `name` parameter lacks namespaces.
|
||||||
If not provided at all, the default namespace will be inherited from the
|
If not provided, the default namespace will be inherited from the
|
||||||
request's ACL token or will default to the `default` namespace.
|
request's ACL token or will default to the `default` namespace.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header.
|
`X-Consul-Namespace` header.
|
||||||
|
@ -551,7 +746,6 @@ $ curl \
|
||||||
{
|
{
|
||||||
"web": [
|
"web": [
|
||||||
{
|
{
|
||||||
"ID": "ed16f6a6-d863-1bec-af45-96bbdcbe02be",
|
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"SourceNS": "default",
|
"SourceNS": "default",
|
||||||
"SourceName": "web",
|
"SourceName": "web",
|
||||||
|
@ -560,13 +754,10 @@ $ curl \
|
||||||
"SourceType": "consul",
|
"SourceType": "consul",
|
||||||
"Action": "deny",
|
"Action": "deny",
|
||||||
"Meta": {},
|
"Meta": {},
|
||||||
"CreatedAt": "2018-05-21T16:41:33.296693825Z",
|
|
||||||
"UpdatedAt": "2018-05-21T16:41:33.296694288Z",
|
|
||||||
"CreateIndex": 12,
|
"CreateIndex": 12,
|
||||||
"ModifyIndex": 12
|
"ModifyIndex": 12
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"ID": "e9ebc19f-d481-42b1-4871-4d298d3acd5c",
|
|
||||||
"Description": "",
|
"Description": "",
|
||||||
"SourceNS": "default",
|
"SourceNS": "default",
|
||||||
"SourceName": "web",
|
"SourceName": "web",
|
||||||
|
@ -575,8 +766,6 @@ $ curl \
|
||||||
"SourceType": "consul",
|
"SourceType": "consul",
|
||||||
"Action": "allow",
|
"Action": "allow",
|
||||||
"Meta": {},
|
"Meta": {},
|
||||||
"CreatedAt": "2018-05-21T16:41:27.977155457Z",
|
|
||||||
"UpdatedAt": "2018-05-21T16:41:27.977157724Z",
|
|
||||||
"CreateIndex": 11,
|
"CreateIndex": 11,
|
||||||
"ModifyIndex": 11
|
"ModifyIndex": 11
|
||||||
}
|
}
|
||||||
|
|
|
@ -17,7 +17,7 @@ The `/discovery-chain` endpoint returns the compiled [discovery
|
||||||
chain](/docs/internals/discovery-chain) for a service.
|
chain](/docs/internals/discovery-chain) for a service.
|
||||||
|
|
||||||
This will fetch all related [configuration
|
This will fetch all related [configuration
|
||||||
entries](/docs/agent/config_entries) and render them into a form suitable
|
entries](/docs/agent/config-entries) and render them into a form suitable
|
||||||
for use by a [connect proxy](/docs/connect/proxies) implementation. This
|
for use by a [connect proxy](/docs/connect/proxies) implementation. This
|
||||||
is a key component of [L7 Traffic
|
is a key component of [L7 Traffic
|
||||||
Management](/docs/connect/l7-traffic-management).
|
Management](/docs/connect/l7-traffic-management).
|
||||||
|
|
|
@ -87,7 +87,7 @@ $ curl \
|
||||||
## List Events
|
## List Events
|
||||||
|
|
||||||
This endpoint returns the most recent events (up to 256) known by the agent. As a
|
This endpoint returns the most recent events (up to 256) known by the agent. As a
|
||||||
consequence of how the [event command](/docs/commands/event) works, each
|
consequence of how the [event command](/commands/event) works, each
|
||||||
agent may have a different view of the events. Events are broadcast using the
|
agent may have a different view of the events. Events are broadcast using the
|
||||||
[gossip protocol](/docs/internals/gossip), so they have no global ordering
|
[gossip protocol](/docs/internals/gossip), so they have no global ordering
|
||||||
nor do they make a promise of delivery.
|
nor do they make a promise of delivery.
|
||||||
|
|
|
@ -36,7 +36,7 @@ a 500 is returned as normal.
|
||||||
To allow clients to maintain fresh results in normal operation but allow stale
|
To allow clients to maintain fresh results in normal operation but allow stale
|
||||||
ones if the servers are unavailable, the `stale-if-error=<seconds>` directive
|
ones if the servers are unavailable, the `stale-if-error=<seconds>` directive
|
||||||
may be additionally provided in the `Cache-Control` header. This will return the
|
may be additionally provided in the `Cache-Control` header. This will return the
|
||||||
cached value anyway even it it's older than `max-age` (provided it's not older
|
cached value anyway even if it's older than `max-age` (provided it's not older
|
||||||
than `stale-if-error`) rather than a 500. It must be provided along with a
|
than `stale-if-error`) rather than a 500. It must be provided along with a
|
||||||
`max-age` or `must-revalidate`. The `Age` response header, if larger than
|
`max-age` or `must-revalidate`. The `Age` response header, if larger than
|
||||||
`max-age` can be used to determine if the server was unreachable and a cached
|
`max-age` can be used to determine if the server was unreachable and a cached
|
||||||
|
|
|
@ -47,7 +47,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list checks.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to list checks.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. To view
|
from the request's ACL token or will default to the `default` namespace. To view
|
||||||
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
|
checks for multiple namespaces the `*` wildcard namespace may be used. Added in Consul 1.7.0.
|
||||||
|
|
||||||
|
@ -152,7 +152,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -251,7 +251,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
@ -460,7 +460,7 @@ The table below shows this endpoint's support for
|
||||||
|
|
||||||
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
||||||
This value may be provided by either the `ns` URL query parameter or in the
|
This value may be provided by either the `ns` URL query parameter or in the
|
||||||
`X-Consul-Namespace` header. If not provided at all, the namespace will be inherited
|
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
|
||||||
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||||
|
|
||||||
### Sample Request
|
### Sample Request
|
||||||
|
|
|
@ -12,7 +12,7 @@ description: |-
|
||||||
The `/operator` endpoints provide cluster-level tools for Consul operators,
|
The `/operator` endpoints provide cluster-level tools for Consul operators,
|
||||||
such as interacting with the Raft subsystem. For a CLI to perform these
|
such as interacting with the Raft subsystem. For a CLI to perform these
|
||||||
operations manually, please check the documentation for the
|
operations manually, please check the documentation for the
|
||||||
[`consul operator`](/docs/commands/operator) command.
|
[`consul operator`](/commands/operator) command.
|
||||||
|
|
||||||
If ACLs are enabled then a token with operator privileges may be required in
|
If ACLs are enabled then a token with operator privileges may be required in
|
||||||
order to use this interface. Check the [ACL Rules documentation](/docs/acl/acl-rules#operator-rules)
|
order to use this interface. Check the [ACL Rules documentation](/docs/acl/acl-rules#operator-rules)
|
||||||
|
|
|
@ -9,7 +9,7 @@ sidebar_title: delete
|
||||||
Command: `consul config delete`
|
Command: `consul config delete`
|
||||||
|
|
||||||
The `config delete` command deletes the configuration entry specified by the
|
The `config delete` command deletes the configuration entry specified by the
|
||||||
kind and name. See the [configuration entries docs](/docs/agent/config_entries)
|
kind and name. See the [configuration entries docs](/docs/agent/config-entries)
|
||||||
for more details about configuration entries.
|
for more details about configuration entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
|
@ -13,7 +13,7 @@ system. It exposes commands for creating, updating, reading, and deleting
|
||||||
different kinds of config entries. See the
|
different kinds of config entries. See the
|
||||||
[agent configuration](/docs/agent/options#enable_central_service_config)
|
[agent configuration](/docs/agent/options#enable_central_service_config)
|
||||||
for more information on how to enable this functionality for centrally
|
for more information on how to enable this functionality for centrally
|
||||||
configuring services and [configuration entries docs](/docs/agent/config_entries) for a description
|
configuring services and [configuration entries docs](/docs/agent/config-entries) for a description
|
||||||
of the configuration entries content.
|
of the configuration entries content.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
|
@ -9,7 +9,7 @@ sidebar_title: list
|
||||||
Command: `consul config list`
|
Command: `consul config list`
|
||||||
|
|
||||||
The `config list` command lists all given config entries of the given kind.
|
The `config list` command lists all given config entries of the given kind.
|
||||||
See the [configuration entries docs](/docs/agent/config_entries) for more
|
See the [configuration entries docs](/docs/agent/config-entries) for more
|
||||||
details about configuration entries.
|
details about configuration entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
|
@ -10,7 +10,7 @@ Command: `consul config read`
|
||||||
|
|
||||||
The `config read` command reads the config entry specified by the given
|
The `config read` command reads the config entry specified by the given
|
||||||
kind and name and outputs its JSON representation. See the
|
kind and name and outputs its JSON representation. See the
|
||||||
[configuration entries docs](/docs/agent/config_entries) for more
|
[configuration entries docs](/docs/agent/config-entries) for more
|
||||||
details about configuration entries.
|
details about configuration entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
|
@ -9,7 +9,7 @@ sidebar_title: write
|
||||||
Command: `consul config write`
|
Command: `consul config write`
|
||||||
|
|
||||||
The `config write` command creates or updates a centralized config entry.
|
The `config write` command creates or updates a centralized config entry.
|
||||||
See the [configuration entries docs](/docs/agent/config_entries) for more
|
See the [configuration entries docs](/docs/agent/config-entries) for more
|
||||||
details about configuration entries.
|
details about configuration entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
|
@ -71,7 +71,7 @@ Usage: `consul connect proxy [options]`
|
||||||
- `-register-id` - Optional ID suffix for the service when `-register` is set to
|
- `-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`
|
disambiguate the service ID. By default the service ID is `<service>-proxy`
|
||||||
where `<service>` is the `-service` value. In most cases it is now preferable
|
where `<service>` is the `-service` value. In most cases it is now preferable
|
||||||
to use [`consul services register`](/docs/commands/services/register) to
|
to use [`consul services register`](/commands/services/register) to
|
||||||
register a fully configured proxy instance rather than specify config and
|
register a fully configured proxy instance rather than specify config and
|
||||||
registration via this command.
|
registration via this command.
|
||||||
|
|
||||||
|
|
|
@ -17,7 +17,7 @@ this can be used to run the `uptime` command across all machines providing
|
||||||
the `web` service.
|
the `web` service.
|
||||||
|
|
||||||
Remote execution works by specifying a job, which is stored in the KV store.
|
Remote execution works by specifying a job, which is stored in the KV store.
|
||||||
Agents are informed about the new job using the [event system](/docs/commands/event),
|
Agents are informed about the new job using the [event system](/commands/event),
|
||||||
which propagates messages via the [gossip protocol](/docs/internals/gossip).
|
which propagates messages via the [gossip protocol](/docs/internals/gossip).
|
||||||
As a result, delivery is best-effort, and there is **no guarantee** of execution.
|
As a result, delivery is best-effort, and there is **no guarantee** of execution.
|
||||||
|
|
||||||
|
|
|
@ -14,13 +14,13 @@ Command: `consul force-leave`
|
||||||
|
|
||||||
The `force-leave` command forces a member of a Consul cluster to enter the
|
The `force-leave` command forces a member of a Consul cluster to enter the
|
||||||
"left" state. The purpose of this method is to force-remove a node that has failed or
|
"left" state. The purpose of this method is to force-remove a node that has failed or
|
||||||
was shutdown without a [graceful leave](/docs/commands/leave).
|
was shutdown without a [graceful leave](/commands/leave).
|
||||||
|
|
||||||
Consul periodically tries to reconnect to "failed" nodes in case failure was due
|
Consul periodically tries to reconnect to "failed" nodes in case failure was due
|
||||||
to a network partition. After some configured amount of time (by default 72 hours),
|
to a network partition. After some configured amount of time (by default 72 hours),
|
||||||
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
|
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
|
||||||
command can be used to transition the "failed" nodes to a "left" state more
|
command can be used to transition the "failed" nodes to a "left" state more
|
||||||
quickly, as reported by [`consul members`](/docs/commands/members).
|
quickly, as reported by [`consul members`](/commands/members).
|
||||||
|
|
||||||
This can be particularly useful for a node that was running as a server,
|
This can be particularly useful for a node that was running as a server,
|
||||||
as it will eventually be removed from the Raft configuration by the leader.
|
as it will eventually be removed from the Raft configuration by the leader.
|
||||||
|
|
|
@ -15,14 +15,18 @@ Consul configuration.
|
||||||
This command requires less ACL permissions than other intention-related
|
This command requires less ACL permissions than other intention-related
|
||||||
tasks because no information about the intention is revealed. Therefore,
|
tasks because no information about the intention is revealed. Therefore,
|
||||||
callers only need to have `service:read` access for the destination. Richer
|
callers only need to have `service:read` access for the destination. Richer
|
||||||
commands like [match](/docs/commands/intention/match) require full
|
commands like [match](/commands/intention/match) require full
|
||||||
intention read permissions and don't evaluate the result.
|
intention read permissions and don't evaluate the result.
|
||||||
|
|
||||||
|
-> **Note:** This command will always treat intentions with `Permissions`
|
||||||
|
defined as *deny* intentions during evaluation, as this endpoint is only suited
|
||||||
|
for networking layer 4 (e.g. TCP) integration.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Usage: `consul intention check [options] SRC DST`
|
Usage: `consul intention check [options] SRC DST`
|
||||||
|
|
||||||
`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
|
`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
#### API Options
|
#### API Options
|
||||||
|
|
||||||
|
|
|
@ -6,16 +6,22 @@ sidebar_title: create
|
||||||
|
|
||||||
# Consul Intention Create
|
# Consul Intention Create
|
||||||
|
|
||||||
|
-> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of
|
||||||
|
using the [config entry CLI command](/commands/config/write). To create an
|
||||||
|
intention, create or modify a
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entry for the destination.
|
||||||
|
|
||||||
Command: `consul intention create`
|
Command: `consul intention create`
|
||||||
|
|
||||||
The `intention create` command creates or updates an intention.
|
The `intention create` command creates or updates an L4 intention.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Usage: `consul intention create [options] SRC DST`
|
- `consul intention create [options] SRC DST`
|
||||||
Usage: `consul intention create [options] -f FILE...`
|
- `consul intention create [options] -file FILE...`
|
||||||
|
|
||||||
`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
|
`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
#### API Options
|
#### API Options
|
||||||
|
|
||||||
|
|
|
@ -10,6 +10,11 @@ Command: `consul intention delete`
|
||||||
|
|
||||||
The `intention delete` command deletes a matching intention.
|
The `intention delete` command deletes a matching intention.
|
||||||
|
|
||||||
|
-> **Deprecated** - The one argument form of this command is deprecated in
|
||||||
|
Consul 1.9.0. Intentions no longer need IDs when represented as
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Usage:
|
Usage:
|
||||||
|
@ -17,7 +22,7 @@ Usage:
|
||||||
- `consul intention delete [options] SRC DST`
|
- `consul intention delete [options] SRC DST`
|
||||||
- `consul intention delete [options] ID`
|
- `consul intention delete [options] ID`
|
||||||
|
|
||||||
`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
|
`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
#### API Options
|
#### API Options
|
||||||
|
|
||||||
|
|
|
@ -10,6 +10,11 @@ Command: `consul intention get`
|
||||||
|
|
||||||
The `intention get` command shows a single intention.
|
The `intention get` command shows a single intention.
|
||||||
|
|
||||||
|
-> **Deprecated** - The one argument form of this command is deprecated in
|
||||||
|
Consul 1.9.0. Intentions no longer need IDs when represented as
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entries.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Usage:
|
Usage:
|
||||||
|
@ -17,7 +22,7 @@ Usage:
|
||||||
- `consul intention get [options] SRC DST`
|
- `consul intention get [options] SRC DST`
|
||||||
- `consul intention get [options] ID`
|
- `consul intention get [options] ID`
|
||||||
|
|
||||||
`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
|
`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
#### API Options
|
#### API Options
|
||||||
|
|
||||||
|
|
|
@ -13,7 +13,10 @@ The `intention` command is used to interact with Connect
|
||||||
creating, updating, reading, deleting, checking, and managing intentions.
|
creating, updating, reading, deleting, checking, and managing intentions.
|
||||||
This command is available in Consul 1.2 and later.
|
This command is available in Consul 1.2 and later.
|
||||||
|
|
||||||
Intentions may also be managed via the [HTTP API](/api/connect/intentions).
|
Intentions are managed primarily via
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entries after Consul 1.9. Intentions may also be managed via the [HTTP
|
||||||
|
API](/api/connect/intentions).
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|
|
@ -12,14 +12,14 @@ The `intention match` command shows the list of intentions that match
|
||||||
a given source or destination. The list of intentions is listed in evaluation
|
a given source or destination. The list of intentions is listed in evaluation
|
||||||
order: the first intention that matches a request would be evaluated.
|
order: the first intention that matches a request would be evaluated.
|
||||||
|
|
||||||
The [check](/docs/commands/intention/check) command can be used to
|
The [check](/commands/intention/check) command can be used to
|
||||||
check whether a connection would be authorized between any two services.
|
check whether an L4 connection would be authorized between any two services.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Usage: `consul intention match [options] SRC_OR_DST`
|
Usage: `consul intention match [options] SRC_OR_DST`
|
||||||
|
|
||||||
`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming).
|
`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming).
|
||||||
|
|
||||||
#### API Options
|
#### API Options
|
||||||
|
|
||||||
|
@ -40,5 +40,6 @@ Usage: `consul intention match [options] SRC_OR_DST`
|
||||||
```shell-session
|
```shell-session
|
||||||
$ consul intention match -source web
|
$ consul intention match -source web
|
||||||
web => db (deny)
|
web => db (deny)
|
||||||
|
web => api (2 permissions)
|
||||||
web => * (allow)
|
web => * (allow)
|
||||||
```
|
```
|
||||||
|
|
|
@ -40,11 +40,11 @@ Subcommands:
|
||||||
For more information, examples, and usage about a subcommand, click on the name
|
For more information, examples, and usage about a subcommand, click on the name
|
||||||
of the subcommand in the sidebar or one of the links below:
|
of the subcommand in the sidebar or one of the links below:
|
||||||
|
|
||||||
- [delete](/docs/commands/kv/delete)
|
- [delete](/commands/kv/delete)
|
||||||
- [export](/docs/commands/kv/export)
|
- [export](/commands/kv/export)
|
||||||
- [get](/docs/commands/kv/get)
|
- [get](/commands/kv/get)
|
||||||
- [import](/docs/commands/kv/import)
|
- [import](/commands/kv/import)
|
||||||
- [put](/docs/commands/kv/put)
|
- [put](/commands/kv/put)
|
||||||
|
|
||||||
## Basic Examples
|
## Basic Examples
|
||||||
|
|
||||||
|
|
|
@ -141,5 +141,5 @@ Success! Lock released on: redis/lock/update
|
||||||
|
|
||||||
~> **Warning!** If you are trying to build a locking mechanism with these
|
~> **Warning!** If you are trying to build a locking mechanism with these
|
||||||
low-level primitives, you may want to look at the [<tt>consul
|
low-level primitives, you may want to look at the [<tt>consul
|
||||||
lock</tt>](/docs/commands/lock) command. It provides higher-level
|
lock</tt>](/commands/lock) command. It provides higher-level
|
||||||
functionality without exposing the internal APIs of Consul.
|
functionality without exposing the internal APIs of Consul.
|
||||||
|
|
|
@ -43,6 +43,6 @@ Subcommands:
|
||||||
For more information, examples, and usage about a subcommand, click on the name
|
For more information, examples, and usage about a subcommand, click on the name
|
||||||
of the subcommand in the sidebar or one of the links below:
|
of the subcommand in the sidebar or one of the links below:
|
||||||
|
|
||||||
- [area](/docs/commands/operator/area) <EnterpriseAlert inline />
|
- [area](/commands/operator/area) <EnterpriseAlert inline />
|
||||||
- [autopilot](/docs/commands/operator/autopilot)
|
- [autopilot](/commands/operator/autopilot)
|
||||||
- [raft](/docs/commands/operator/raft)
|
- [raft](/commands/operator/raft)
|
||||||
|
|
|
@ -69,9 +69,9 @@ There are rare cases where a peer may be left behind in the Raft configuration
|
||||||
even though the server is no longer present and known to the cluster. This command
|
even though the server is no longer present and known to the cluster. This command
|
||||||
can be used to remove the failed server so that it is no longer affects the
|
can be used to remove the failed server so that it is no longer affects the
|
||||||
Raft quorum. If the server still shows in the output of the
|
Raft quorum. If the server still shows in the output of the
|
||||||
[`consul members`](/docs/commands/members) command, it is preferable to
|
[`consul members`](/commands/members) command, it is preferable to
|
||||||
clean up by simply running
|
clean up by simply running
|
||||||
[`consul force-leave`](/docs/commands/force-leave)
|
[`consul force-leave`](/commands/force-leave)
|
||||||
instead of this command.
|
instead of this command.
|
||||||
|
|
||||||
Usage: `consul operator raft remove-peer -address="IP:port"`
|
Usage: `consul operator raft remove-peer -address="IP:port"`
|
||||||
|
|
|
@ -15,7 +15,7 @@ be paired with `services register`.
|
||||||
|
|
||||||
This is just one method for service deregistration. If the service was
|
This is just one method for service deregistration. If the service was
|
||||||
registered with a configuration file, then deleting that file and
|
registered with a configuration file, then deleting that file and
|
||||||
[reloading](/docs/commands/reload) Consul is the correct method to
|
[reloading](/commands/reload) Consul is the correct method to
|
||||||
deregister. See [Service Definition](/docs/agent/services) for more
|
deregister. See [Service Definition](/docs/agent/services) for more
|
||||||
information about registering services generally.
|
information about registering services generally.
|
||||||
|
|
||||||
|
|
|
@ -13,7 +13,7 @@ registered with the [local agent](/docs/agent/basics). These provide
|
||||||
useful commands such as `register` and `deregister` for easily registering
|
useful commands such as `register` and `deregister` for easily registering
|
||||||
services in scripts, dev mode, etc.
|
services in scripts, dev mode, etc.
|
||||||
To view all services in the catalog, instead of only agent-local services,
|
To view all services in the catalog, instead of only agent-local services,
|
||||||
see the [`catalog services`](/docs/commands/catalog/services) command.
|
see the [`catalog services`](/commands/catalog/services) command.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|
|
@ -16,7 +16,7 @@ scripts, in dev mode, etc.
|
||||||
This is just one method of service registration. Services can also be
|
This is just one method of service registration. Services can also be
|
||||||
registered by placing a [service definition](/docs/agent/services)
|
registered by placing a [service definition](/docs/agent/services)
|
||||||
in the Consul agent configuration directory and issuing a
|
in the Consul agent configuration directory and issuing a
|
||||||
[reload](/docs/commands/reload). This approach is easiest for
|
[reload](/commands/reload). This approach is easiest for
|
||||||
configuration management systems that other systems that have access to
|
configuration management systems that other systems that have access to
|
||||||
the configuration directory. Clients may also use the
|
the configuration directory. Clients may also use the
|
||||||
[HTTP API](/api/agent/service) directly.
|
[HTTP API](/api/agent/service) directly.
|
||||||
|
|
|
@ -10,9 +10,9 @@ Command: `consul snapshot agent`
|
||||||
|
|
||||||
<EnterpriseAlert />
|
<EnterpriseAlert />
|
||||||
|
|
||||||
~> The [`agent`](/docs/commands/snapshot/agent) subcommand described here is
|
~> The [`agent`](/commands/snapshot/agent) subcommand described here is
|
||||||
available only in [Consul Enterprise](https://www.hashicorp.com/products/consul/)
|
available only in [Consul Enterprise](https://www.hashicorp.com/products/consul/)
|
||||||
version 0.7.1 and later. All other [snapshot subcommands](/docs/commands/snapshot)
|
version 0.7.1 and later. All other [snapshot subcommands](/commands/snapshot)
|
||||||
are available in the open source version of Consul.
|
are available in the open source version of Consul.
|
||||||
|
|
||||||
The `snapshot agent` subcommand starts a process that takes snapshots of the
|
The `snapshot agent` subcommand starts a process that takes snapshots of the
|
||||||
|
@ -49,7 +49,7 @@ in the file name when using local storage, or in the object key when using
|
||||||
remote storage.
|
remote storage.
|
||||||
|
|
||||||
Snapshots can be restored using the
|
Snapshots can be restored using the
|
||||||
[`consul snapshot restore`](/docs/commands/snapshot/restore) command, or
|
[`consul snapshot restore`](/commands/snapshot/restore) command, or
|
||||||
the [HTTP API](/api/snapshot).
|
the [HTTP API](/api/snapshot).
|
||||||
|
|
||||||
If ACLs are enabled the following privileges are required:
|
If ACLs are enabled the following privileges are required:
|
||||||
|
|
|
@ -38,10 +38,10 @@ Subcommands:
|
||||||
For more information, examples, and usage about a subcommand, click on the name
|
For more information, examples, and usage about a subcommand, click on the name
|
||||||
of the subcommand in the sidebar or one of the links below:
|
of the subcommand in the sidebar or one of the links below:
|
||||||
|
|
||||||
- [agent](/docs/commands/snapshot/agent) <EnterpriseAlert inline />
|
- [agent](/commands/snapshot/agent) <EnterpriseAlert inline />
|
||||||
- [inspect](/docs/commands/snapshot/inspect)
|
- [inspect](/commands/snapshot/inspect)
|
||||||
- [restore](/docs/commands/snapshot/restore)
|
- [restore](/commands/snapshot/restore)
|
||||||
- [save](/docs/commands/snapshot/save)
|
- [save](/commands/snapshot/save)
|
||||||
|
|
||||||
## Basic Examples
|
## Basic Examples
|
||||||
|
|
||||||
|
|
|
@ -34,6 +34,9 @@ The supported `Kind` names for configuration entries are:
|
||||||
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
|
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
|
||||||
defaults for all the instances of a given service
|
defaults for all the instances of a given service
|
||||||
|
|
||||||
|
- [`service-intentions`](/docs/agent/config-entries/service-intentions) <sup>Beta</sup> - defines
|
||||||
|
the [intentions](/docs/connect/intentions) for a destination service
|
||||||
|
|
||||||
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
|
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
|
||||||
service instances with a specific Connect upstream discovery requests
|
service instances with a specific Connect upstream discovery requests
|
||||||
|
|
||||||
|
@ -49,7 +52,7 @@ The supported `Kind` names for configuration entries are:
|
||||||
## Managing Configuration Entries
|
## Managing Configuration Entries
|
||||||
|
|
||||||
Configuration entries should be managed with the Consul
|
Configuration entries should be managed with the Consul
|
||||||
[CLI](/docs/commands/config) or [API](/api/config). Additionally, as a
|
[CLI](/commands/config) or [API](/api/config). Additionally, as a
|
||||||
convenience for initial cluster bootstrapping, configuration entries can be
|
convenience for initial cluster bootstrapping, configuration entries can be
|
||||||
specified in all of the Consul servers's
|
specified in all of the Consul servers's
|
||||||
[configuration files](/docs/agent/options#config_entries_bootstrap)
|
[configuration files](/docs/agent/options#config_entries_bootstrap)
|
||||||
|
@ -58,7 +61,7 @@ specified in all of the Consul servers's
|
||||||
|
|
||||||
#### Creating or Updating a Configuration Entry
|
#### Creating or Updating a Configuration Entry
|
||||||
|
|
||||||
The [`consul config write`](/docs/commands/config/write) command is used to
|
The [`consul config write`](/commands/config/write) command is used to
|
||||||
create and update configuration entries. This command will load either a JSON or
|
create and update configuration entries. This command will load either a JSON or
|
||||||
HCL file holding the configuration entry definition and then will push this
|
HCL file holding the configuration entry definition and then will push this
|
||||||
configuration to Consul.
|
configuration to Consul.
|
||||||
|
@ -88,7 +91,7 @@ overwriting other unknown modifications.
|
||||||
|
|
||||||
#### Reading a Configuration Entry
|
#### Reading a Configuration Entry
|
||||||
|
|
||||||
The [`consul config read`](/docs/commands/config/read) command is used to
|
The [`consul config read`](/commands/config/read) command is used to
|
||||||
read the current value of a configuration entry. The configuration entry will be
|
read the current value of a configuration entry. The configuration entry will be
|
||||||
displayed in JSON form which is how its transmitted between the CLI client and
|
displayed in JSON form which is how its transmitted between the CLI client and
|
||||||
Consul's HTTP API.
|
Consul's HTTP API.
|
||||||
|
@ -106,7 +109,7 @@ $ consul config read -kind service-defaults -name web
|
||||||
|
|
||||||
#### Listing Configuration Entries
|
#### Listing Configuration Entries
|
||||||
|
|
||||||
The [`consul config list`](/docs/commands/config/list) command is used to
|
The [`consul config list`](/commands/config/list) command is used to
|
||||||
list out all the configuration entries for a given kind.
|
list out all the configuration entries for a given kind.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
@ -120,7 +123,7 @@ db
|
||||||
|
|
||||||
#### Deleting Configuration Entries
|
#### Deleting Configuration Entries
|
||||||
|
|
||||||
The [`consul config delete`](/docs/commands/config/delete) command is used
|
The [`consul config delete`](/commands/config/delete) command is used
|
||||||
to delete an entry by specifying both its `kind` and `name`.
|
to delete an entry by specifying both its `kind` and `name`.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
|
@ -636,8 +636,7 @@ Routes = [
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
|
Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
|
||||||
field of the config entry.
|
field of the config entry.
|
||||||
|
|
|
@ -86,8 +86,7 @@ Config {
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `proxy-defaults` config entry requires no specific privileges.
|
Reading a `proxy-defaults` config entry requires no specific privileges.
|
||||||
|
|
||||||
|
|
|
@ -36,8 +36,10 @@ Protocol = "http"
|
||||||
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used
|
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used
|
||||||
by Connect proxies for things like observability features and to unlock usage
|
by Connect proxies for things like observability features and to unlock usage
|
||||||
of the [`service-splitter`](/docs/agent/config-entries/service-splitter) and
|
of the [`service-splitter`](/docs/agent/config-entries/service-splitter) and
|
||||||
[`service-router`](/docs/agent/config-entries/service-router) config
|
[`service-router`](/docs/agent/config-entries/service-router) config entries
|
||||||
entries for a service. Supported values are one of `tcp`, `http`, `http2`, or `grpc`.
|
for a service. It also unlocks the ability to define L7 intentions via
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions).
|
||||||
|
Supported values are one of `tcp`, `http`, `http2`, or `grpc`.
|
||||||
|
|
||||||
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
|
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
|
||||||
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
|
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
|
||||||
|
@ -74,10 +76,9 @@ Protocol = "http"
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `service-defaults` config entry requires `service:read` on itself.
|
Reading a `service-defaults` config entry requires `service:read` on the resource.
|
||||||
|
|
||||||
Creating, updating, or deleting a `service-defaults` config entry requires
|
Creating, updating, or deleting a `service-defaults` config entry requires
|
||||||
`service:write` on itself.
|
`service:write` on the resource.
|
||||||
|
|
|
@ -0,0 +1,329 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: 'Configuration Entry Kind: Service Intentions (beta)'
|
||||||
|
sidebar_title: service-intentions <sup>Beta</sup>
|
||||||
|
description: >-
|
||||||
|
The service-intentions config entry kind controls Connect traffic
|
||||||
|
authorization for both networking layer 4 (e.g. TCP) and networking layer 7
|
||||||
|
(e.g. HTTP).
|
||||||
|
---
|
||||||
|
|
||||||
|
# Service Intentions ((#service-intentions)) <sup>Beta</sup>
|
||||||
|
|
||||||
|
-> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer.
|
||||||
|
|
||||||
|
The `service-intentions` config entry kind controls Connect traffic
|
||||||
|
authorization for both networking layer 4 (e.g. TCP) and networking layer 7
|
||||||
|
(e.g. HTTP).
|
||||||
|
|
||||||
|
Service intentions config entries represent a collection of
|
||||||
|
[intentions](/docs/connect/intentions) sharing a specific destination. All
|
||||||
|
intentions governing access to a specific destination are stored in a single
|
||||||
|
`service-intentions` config entry.
|
||||||
|
|
||||||
|
A single config entry may define a mix of both L4 and L7 style intentions, but
|
||||||
|
for a specific source L4 and L7 intentions are mutually exclusive. Only one
|
||||||
|
will apply at a time. Default behavior for L4 is configurable (regardless of
|
||||||
|
global setting) by defining a low precedence intention for that destination.
|
||||||
|
|
||||||
|
## Interaction with other Config Entries
|
||||||
|
|
||||||
|
L7 intentions within a config entry are restricted to only destination services
|
||||||
|
that define their protocol as HTTP-based via a corresponding
|
||||||
|
[`service-defaults`](/docs/agent/config-entries/service-defaults) config entry
|
||||||
|
or globally via [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
|
||||||
|
|
||||||
|
## Sample Config Entries
|
||||||
|
|
||||||
|
Grant some clients more REST access than others:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
|
Name = "api"
|
||||||
|
Sources = [
|
||||||
|
{
|
||||||
|
Name = "admin-dashboard"
|
||||||
|
Permissions = [
|
||||||
|
{
|
||||||
|
Action = "allow"
|
||||||
|
HTTP {
|
||||||
|
PathPrefix = "/v2"
|
||||||
|
Methods = ["GET", "PUT", "POST", "DELETE", "HEAD"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Name = "report-generator"
|
||||||
|
Permissions = [
|
||||||
|
{
|
||||||
|
Action = "allow"
|
||||||
|
HTTP {
|
||||||
|
PathPrefix = "/v2/widgets"
|
||||||
|
Methods = ["GET"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
# NOTE: a default catch-all based on the default ACL policy will apply to
|
||||||
|
# unmatched connections and requests. Typically this will be DENY.
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Selectively deny some gRPC service methods. Since gRPC method calls [are
|
||||||
|
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can
|
||||||
|
use an HTTP path match rule to control traffic:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
|
Name = "billing"
|
||||||
|
Sources = [
|
||||||
|
{
|
||||||
|
Name = "frontend-web"
|
||||||
|
Permissions = [
|
||||||
|
# The frontend website can execute all billing service methods except
|
||||||
|
# issuing refunds.
|
||||||
|
{
|
||||||
|
Action = "deny"
|
||||||
|
HTTP {
|
||||||
|
PathExact = "/mycompany.BillingService/IssueRefund"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Action = "allow"
|
||||||
|
HTTP {
|
||||||
|
PathPrefix = "/mycompany.BillingService/"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Name = "support-portal"
|
||||||
|
Permissions = [
|
||||||
|
# But the support team portal page can execute all methods.
|
||||||
|
{
|
||||||
|
Action = "allow"
|
||||||
|
HTTP {
|
||||||
|
PathPrefix = "/mycompany.BillingService/"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
# NOTE: a default catch-all based on the default ACL policy will apply to
|
||||||
|
# unmatched connections and requests. Typically this will be DENY.
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
You can mix and match L4 and L7 intentions per source:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
|
Name = "api"
|
||||||
|
Sources = [
|
||||||
|
{
|
||||||
|
Name = "hackathon-project"
|
||||||
|
Action = "deny"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Name = "web"
|
||||||
|
Action = "allow"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Name = "nightly-reconciler"
|
||||||
|
Permissions = [
|
||||||
|
{
|
||||||
|
Action = "allow"
|
||||||
|
HTTP {
|
||||||
|
PathExact = "/v1/reconcile-data"
|
||||||
|
Methods = ["POST"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
# NOTE: a default catch-all based on the default ACL policy will apply to
|
||||||
|
# unmatched connections and requests. Typically this will be DENY.
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Available Fields
|
||||||
|
|
||||||
|
- `Kind` - Must be set to `service-intentions`.
|
||||||
|
|
||||||
|
- `Name` `(string: <required>)` - The destination of all intentions defined in
|
||||||
|
this config entry. This may be set to the wildcard character (`*`) to match
|
||||||
|
all services that don't otherwise have intentions defined.
|
||||||
|
|
||||||
|
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to.
|
||||||
|
This may be set to the wildcard character (`*`) to match
|
||||||
|
all services in all namespaces that don't otherwise have intentions defined.
|
||||||
|
|
||||||
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
|
||||||
|
|
||||||
|
- `Sources` `(array<SourceIntention>)` - The list of all [intention sources and
|
||||||
|
the authorization granted to those sources](#sourceintention). The order of
|
||||||
|
this list does not matter, but out of convenience Consul will always store
|
||||||
|
this reverse sorted by intention precedence, as that is the order that they
|
||||||
|
will be evaluated at enforcement time.
|
||||||
|
|
||||||
|
### `SourceIntention`
|
||||||
|
|
||||||
|
- `Name` `(string: <required>)` - The source of the intention.
|
||||||
|
For a `Type` of `consul` this is the name of a Consul service. The service
|
||||||
|
doesn't need to be registered.
|
||||||
|
|
||||||
|
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - The namespace
|
||||||
|
for the `Name` parameter.
|
||||||
|
|
||||||
|
- `Action` `(string: "")` - For an L4 intention this is required, and should be
|
||||||
|
set to one of `"allow"` or `"deny"` for the action that should be taken if
|
||||||
|
this intention matches a request.
|
||||||
|
|
||||||
|
This should be omitted for an L7 intention as it is mutually exclusive with
|
||||||
|
the `Permissions` field.
|
||||||
|
|
||||||
|
- `Permissions` `(array<IntentionPermission>)` - The list of all [additional L7
|
||||||
|
attributes](#intentionpermission) that extend the intention match criteria.
|
||||||
|
|
||||||
|
Permission precedence is applied top to bottom. For any given request the
|
||||||
|
first permission to match in the list is terminal and stops further
|
||||||
|
evaluation. As with L4 intentions, traffic that fails to match any of the
|
||||||
|
provided permissions in this intention will be subject to the default
|
||||||
|
intention behavior is defined by the default [ACL
|
||||||
|
policy](/docs/agent/options#acl_default_policy).
|
||||||
|
|
||||||
|
This should be omitted for an L4 intention as it is mutually exclusive with
|
||||||
|
the `Action` field.
|
||||||
|
|
||||||
|
- `Precedence` `(int: <read-only>)` - An [integer precedence
|
||||||
|
value](/docs/connect/intentions#precedence-and-match-order) computed from the
|
||||||
|
source and destination naming components.
|
||||||
|
|
||||||
|
- `Type` `(string: "")` - The type for the `Name` value. This can be
|
||||||
|
only "consul" today to represent a Consul service. If not provided, this
|
||||||
|
will be defaulted to "consul".
|
||||||
|
|
||||||
|
- `Description` `(string: "")` - Description for the intention. This is not
|
||||||
|
used by Consul, but is presented in API responses to assist tooling.
|
||||||
|
|
||||||
|
- `LegacyID` `(string: <read-only>)` - This is the UUID to uniquely identify
|
||||||
|
this intention in the system. Cannot be set directly and is exposed here as
|
||||||
|
an artifact of the config entry migration and is primarily used to allow
|
||||||
|
legacy intention [API](/api-docs/connect/intentions#update-intention-by-id)
|
||||||
|
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
|
||||||
|
continue to function for a period of time after [upgrading to
|
||||||
|
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
|
||||||
|
|
||||||
|
- `LegacyMeta` `(map<string|string>: <read-only>)` - Specified arbitrary KV
|
||||||
|
metadata pairs attached to the intention, rather than to the enclosing config
|
||||||
|
entry. Cannot be set directly and is exposed here as an artifact of the
|
||||||
|
config entry migration and is primarily used to allow legacy intention
|
||||||
|
[API](/api-docs/connect/intentions#update-intention-by-id)
|
||||||
|
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
|
||||||
|
continue to function for a period of time after [upgrading to
|
||||||
|
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
|
||||||
|
|
||||||
|
- `LegacyCreateTime` `(time: optional)` - The timestamp that this intention was
|
||||||
|
created. Cannot be set directly and is exposed here as an artifact of the
|
||||||
|
config entry migration and is primarily used to allow legacy intention
|
||||||
|
[API](/api-docs/connect/intentions#update-intention-by-id)
|
||||||
|
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
|
||||||
|
continue to function for a period of time after [upgrading to
|
||||||
|
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
|
||||||
|
|
||||||
|
- `LegacyUpdateTime` `(time: optional)` - The timestamp that this intention was
|
||||||
|
last updated. Cannot be set directly and is exposed here as an artifact of
|
||||||
|
the config entry migration and is primarily used to allow legacy intention
|
||||||
|
[API](/api-docs/connect/intentions#update-intention-by-id)
|
||||||
|
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
|
||||||
|
continue to function for a period of time after [upgrading to
|
||||||
|
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).
|
||||||
|
|
||||||
|
### `IntentionPermission`
|
||||||
|
|
||||||
|
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for
|
||||||
|
the action that should be taken if this permission matches a request.
|
||||||
|
|
||||||
|
- `HTTP` `(IntentionHTTPPermission: <required>)` - A set of
|
||||||
|
[HTTP-specific authorization criteria](#intentionhttppermission).
|
||||||
|
|
||||||
|
### `IntentionHTTPPermission`
|
||||||
|
|
||||||
|
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.
|
||||||
|
|
||||||
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
|
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
|
||||||
|
|
||||||
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
|
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
|
||||||
|
request path.
|
||||||
|
|
||||||
|
The syntax is [described below](#regular-expression-syntax).
|
||||||
|
|
||||||
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
|
- `Methods` `(array<string>)` - A list of HTTP methods for which this match
|
||||||
|
applies. If unspecified all HTTP methods are matched.
|
||||||
|
If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
|
||||||
|
|
||||||
|
- `Header` `(array<IntentionHTTPHeaderPermission>)` - A set of criteria that can
|
||||||
|
match on HTTP request headers. If more than one is configured all must match
|
||||||
|
for the overall match to apply.
|
||||||
|
|
||||||
|
- `Name` `(string: <required>)` - Name of the header to match.
|
||||||
|
|
||||||
|
- `Present` `(bool: false)` - Match if the header with the given name is
|
||||||
|
present with any value.
|
||||||
|
|
||||||
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
|
may be configured.
|
||||||
|
|
||||||
|
- `Exact` `(string: "")` - Match if the header with the given name is this
|
||||||
|
value.
|
||||||
|
|
||||||
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
|
may be configured.
|
||||||
|
|
||||||
|
- `Prefix` `(string: "")` - Match if the header with the given name has
|
||||||
|
this prefix.
|
||||||
|
|
||||||
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
|
may be configured.
|
||||||
|
|
||||||
|
- `Suffix` `(string: "")` - Match if the header with the given name has
|
||||||
|
this suffix.
|
||||||
|
|
||||||
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
|
may be configured.
|
||||||
|
|
||||||
|
- `Regex` `(string: "")` - Match if the header with the given name matches
|
||||||
|
this pattern.
|
||||||
|
|
||||||
|
The syntax is [described below](#regular-expression-syntax).
|
||||||
|
|
||||||
|
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present`
|
||||||
|
may be configured.
|
||||||
|
|
||||||
|
- `Invert` `(bool: false)` - Inverts the logic of the match.
|
||||||
|
|
||||||
|
## ACLs
|
||||||
|
|
||||||
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
|
|
||||||
|
Reading a `service-intentions` config entry requires `intentions:read` on the resource.
|
||||||
|
|
||||||
|
Creating, updating, or deleting a `service-intentions` config entry requires
|
||||||
|
`intentions:write` on the resource.
|
||||||
|
|
||||||
|
Intention ACL rules are specified as part of a `service` rule. See [Intention
|
||||||
|
Management Permissions](/docs/connect/intentions#intention-management-permissions) for
|
||||||
|
more details.
|
||||||
|
|
||||||
|
## Regular Expression Syntax
|
||||||
|
|
||||||
|
The actual syntax of the regular expression fields described here is entirely
|
||||||
|
proxy-specific.
|
||||||
|
|
||||||
|
When using [Envoy](/docs/connect/proxies/envoy) as a proxy, the syntax for
|
||||||
|
these fields is [RE2](https://github.com/google/re2/wiki/Syntax).
|
|
@ -241,13 +241,12 @@ referenced by their names throughout the other configuration entry kinds.
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `service-resolver` config entry requires `service:read` on itself.
|
Reading a `service-resolver` config entry requires `service:read` on the resource.
|
||||||
|
|
||||||
Creating, updating, or deleting a `service-resolver` config entry requires
|
Creating, updating, or deleting a `service-resolver` config entry requires
|
||||||
`service:write` on itself and `service:read` on any other service referenced by
|
`service:write` on the resource and `service:read` on any other service referenced by
|
||||||
name in these fields:
|
name in these fields:
|
||||||
|
|
||||||
- [`Redirect.Service`](#service)
|
- [`Redirect.Service`](#service)
|
||||||
|
|
|
@ -24,7 +24,7 @@ service of the same name.
|
||||||
Management](/docs/connect/l7-traffic-management).
|
Management](/docs/connect/l7-traffic-management).
|
||||||
|
|
||||||
- Service router config entries are restricted to only services that define
|
- Service router config entries are restricted to only services that define
|
||||||
their protocol as http-based via a corresponding
|
their protocol as HTTP-based via a corresponding
|
||||||
[`service-defaults`](/docs/agent/config-entries/service-defaults) config
|
[`service-defaults`](/docs/agent/config-entries/service-defaults) config
|
||||||
entry or globally via
|
entry or globally via
|
||||||
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
|
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
|
||||||
|
@ -102,7 +102,7 @@ Routes = [
|
||||||
```
|
```
|
||||||
|
|
||||||
Re-route a gRPC method to another service. Since gRPC method calls [are
|
Re-route a gRPC method to another service. Since gRPC method calls [are
|
||||||
HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
|
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
Kind = "service-router"
|
Kind = "service-router"
|
||||||
|
@ -142,7 +142,7 @@ Routes = [
|
||||||
match incoming L7 requests. If empty or omitted it acts as a catch-all.
|
match incoming L7 requests. If empty or omitted it acts as a catch-all.
|
||||||
|
|
||||||
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of
|
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of
|
||||||
[http-specific match criteria](#serviceroutehttpmatch).
|
[HTTP-specific match criteria](#serviceroutehttpmatch).
|
||||||
|
|
||||||
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
|
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
|
||||||
proxy](#serviceroutedestination) the matching request(s) to a
|
proxy](#serviceroutedestination) the matching request(s) to a
|
||||||
|
@ -156,7 +156,7 @@ Routes = [
|
||||||
|
|
||||||
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
|
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path.
|
||||||
|
|
||||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
|
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP
|
||||||
request path.
|
request path.
|
||||||
|
@ -165,6 +165,10 @@ Routes = [
|
||||||
|
|
||||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
|
||||||
|
|
||||||
|
- `Methods` `(array<string>)` - A list of HTTP methods for which this match
|
||||||
|
applies. If unspecified all HTTP methods are matched.
|
||||||
|
If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
|
||||||
|
|
||||||
- `Header` `(array<ServiceRouteHTTPMatchHeader>)` - A set of criteria that can
|
- `Header` `(array<ServiceRouteHTTPMatchHeader>)` - A set of criteria that can
|
||||||
match on HTTP request headers. If more than one is configured all must match
|
match on HTTP request headers. If more than one is configured all must match
|
||||||
for the overall match to apply.
|
for the overall match to apply.
|
||||||
|
@ -228,9 +232,6 @@ Routes = [
|
||||||
|
|
||||||
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
At most only one of `Exact`, `Regex`, or `Present` may be configured.
|
||||||
|
|
||||||
- `Methods` `(array<string>)` - A list of HTTP methods for which this match
|
|
||||||
applies. If unspecified all http methods are matched.
|
|
||||||
|
|
||||||
### `ServiceRouteDestination`
|
### `ServiceRouteDestination`
|
||||||
|
|
||||||
- `Service` `(string: "")` - The service to resolve instead of the default
|
- `Service` `(string: "")` - The service to resolve instead of the default
|
||||||
|
@ -258,18 +259,17 @@ Routes = [
|
||||||
- `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure
|
- `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure
|
||||||
errors to trigger a retry.
|
errors to trigger a retry.
|
||||||
|
|
||||||
- `RetryOnStatusCodes` `(array<int>)` - A flat list of http response status
|
- `RetryOnStatusCodes` `(array<int>)` - A list of HTTP response status codes
|
||||||
codes that are eligible for retry.
|
that are eligible for retry.
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `service-router` config entry requires `service:read` on itself.
|
Reading a `service-router` config entry requires `service:read` on the resource.
|
||||||
|
|
||||||
Creating, updating, or deleting a `service-router` config entry requires
|
Creating, updating, or deleting a `service-router` config entry requires
|
||||||
`service:write` on itself and `service:read` on any other service referenced by
|
`service:write` on the resource and `service:read` on any other service referenced by
|
||||||
name in these fields:
|
name in these fields:
|
||||||
|
|
||||||
- [`Routes[].Destination.Service`](#service)
|
- [`Routes[].Destination.Service`](#service)
|
||||||
|
|
|
@ -105,13 +105,12 @@ Splits = [
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `service-splitter` config entry requires `service:read` on itself.
|
Reading a `service-splitter` config entry requires `service:read` on the resource.
|
||||||
|
|
||||||
Creating, updating, or deleting a `service-splitter` config entry requires
|
Creating, updating, or deleting a `service-splitter` config entry requires
|
||||||
`service:write` on itself and `service:read` on any other service referenced by
|
`service:write` on the resource and `service:read` on any other service referenced by
|
||||||
name in these fields:
|
name in these fields:
|
||||||
|
|
||||||
- [`Splits[].Service`](#service)
|
- [`Splits[].Service`](#service)
|
||||||
|
|
|
@ -439,8 +439,7 @@ and configure default certificates for mutual TLS. Also override the SNI and CA
|
||||||
|
|
||||||
## ACLs
|
## ACLs
|
||||||
|
|
||||||
Configuration entries may be protected by
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
|
Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
|
||||||
field of the config entry.
|
field of the config entry.
|
||||||
|
|
|
@ -26,7 +26,7 @@ operations and maintain very little state of their own.
|
||||||
|
|
||||||
## Running an Agent
|
## Running an Agent
|
||||||
|
|
||||||
The agent is started with the [`consul agent`](/docs/commands/agent) command.
|
The agent is started with the [`consul agent`](/commands/agent) command.
|
||||||
This command blocks, running forever or until told to quit. You can test a
|
This command blocks, running forever or until told to quit. You can test a
|
||||||
local agent by following the
|
local agent by following the
|
||||||
[Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=consul.io&utm_medium=docs).
|
[Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=consul.io&utm_medium=docs).
|
||||||
|
@ -35,7 +35,7 @@ The agent command takes a variety of
|
||||||
[`configuration options`](/docs/agent/options#command-line-options), but most
|
[`configuration options`](/docs/agent/options#command-line-options), but most
|
||||||
have sane defaults.
|
have sane defaults.
|
||||||
|
|
||||||
When running [`consul agent`](/docs/commands/agent), you should see output
|
When running [`consul agent`](/commands/agent), you should see output
|
||||||
similar to this:
|
similar to this:
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
|
@ -55,7 +55,7 @@ $ consul agent -data-dir=/tmp/consul
|
||||||
```
|
```
|
||||||
|
|
||||||
There are several important messages that
|
There are several important messages that
|
||||||
[`consul agent`](/docs/commands/agent) outputs:
|
[`consul agent`](/commands/agent) outputs:
|
||||||
|
|
||||||
- **Node name**: This is a unique name for the agent. By default, this
|
- **Node name**: This is a unique name for the agent. By default, this
|
||||||
is the hostname of the machine, but you may customize it using the
|
is the hostname of the machine, but you may customize it using the
|
||||||
|
@ -80,7 +80,7 @@ There are several important messages that
|
||||||
This includes the ports for the HTTP and DNS interfaces. By default, this
|
This includes the ports for the HTTP and DNS interfaces. By default, this
|
||||||
binds only to localhost. If you change this address or port, you'll have to
|
binds only to localhost. If you change this address or port, you'll have to
|
||||||
specify a `-http-addr` whenever you run commands such as
|
specify a `-http-addr` whenever you run commands such as
|
||||||
[`consul members`](/docs/commands/members) to indicate how to reach the
|
[`consul members`](/commands/members) to indicate how to reach the
|
||||||
agent. Other applications can also use the HTTP address and port
|
agent. Other applications can also use the HTTP address and port
|
||||||
[to control Consul](/api).
|
[to control Consul](/api).
|
||||||
|
|
||||||
|
@ -112,7 +112,7 @@ cluster that the node has _left_.
|
||||||
When a Server is gracefully exited, the server will not be marked as _left_.
|
When a Server is gracefully exited, the server will not be marked as _left_.
|
||||||
This is to minimally impact the consensus quorum. Instead, the Server will be
|
This is to minimally impact the consensus quorum. Instead, the Server will be
|
||||||
marked as _failed_. To remove a server from the cluster, the
|
marked as _failed_. To remove a server from the cluster, the
|
||||||
[`force-leave`](/docs/commands/force-leave) command is used. Using
|
[`force-leave`](/commands/force-leave) command is used. Using
|
||||||
`force-leave` will put the server instance in a _left_ state so long as the
|
`force-leave` will put the server instance in a _left_ state so long as the
|
||||||
Server agent is not alive.
|
Server agent is not alive.
|
||||||
|
|
||||||
|
@ -139,7 +139,7 @@ with a cluster and how the cluster treats a node.
|
||||||
When an agent is first started, it does not know about any other node in the
|
When an agent is first started, it does not know about any other node in the
|
||||||
cluster.
|
cluster.
|
||||||
To discover its peers, it must _join_ the cluster. This is done with the
|
To discover its peers, it must _join_ the cluster. This is done with the
|
||||||
[`join`](/docs/commands/join)
|
[`join`](/commands/join)
|
||||||
command or by providing the proper configuration to auto-join on start. Once a
|
command or by providing the proper configuration to auto-join on start. Once a
|
||||||
node joins, this information is gossiped to the entire cluster, meaning all
|
node joins, this information is gossiped to the entire cluster, meaning all
|
||||||
nodes will eventually be aware of each other. If the agent is a server,
|
nodes will eventually be aware of each other. If the agent is a server,
|
||||||
|
|
|
@ -37,7 +37,7 @@ Consul also supports reloading configuration when it receives the
|
||||||
SIGHUP signal. Not all changes are respected, but those that are
|
SIGHUP signal. Not all changes are respected, but those that are
|
||||||
documented below in the
|
documented below in the
|
||||||
[Reloadable Configuration](#reloadable-configuration) section. The
|
[Reloadable Configuration](#reloadable-configuration) section. The
|
||||||
[reload command](/docs/commands/reload) can also be used to trigger a
|
[reload command](/commands/reload) can also be used to trigger a
|
||||||
configuration reload.
|
configuration reload.
|
||||||
|
|
||||||
You can test the following configuration options by following the
|
You can test the following configuration options by following the
|
||||||
|
@ -235,7 +235,7 @@ The options below are all specified on the command-line.
|
||||||
|
|
||||||
- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption
|
- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption
|
||||||
of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The
|
of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The
|
||||||
easiest way to create an encryption key is to use [`consul keygen`](/docs/commands/keygen).
|
easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen).
|
||||||
All nodes within a cluster must share the same encryption key to communicate. The
|
All nodes within a cluster must share the same encryption key to communicate. The
|
||||||
provided key is automatically persisted to the data directory and loaded automatically
|
provided key is automatically persisted to the data directory and loaded automatically
|
||||||
whenever the agent is restarted. This means that to encrypt Consul's gossip protocol,
|
whenever the agent is restarted. This means that to encrypt Consul's gossip protocol,
|
||||||
|
@ -381,7 +381,7 @@ The options below are all specified on the command-line.
|
||||||
- `-log-level` ((#\_log_level)) - The level of logging to show after the
|
- `-log-level` ((#\_log_level)) - The level of logging to show after the
|
||||||
Consul agent has started. This defaults to "info". The available log levels are
|
Consul agent has started. This defaults to "info". The available log levels are
|
||||||
"trace", "debug", "info", "warn", and "err". You can always connect to an agent
|
"trace", "debug", "info", "warn", and "err". You can always connect to an agent
|
||||||
via [`consul monitor`](/docs/commands/monitor) and use any log level. Also,
|
via [`consul monitor`](/commands/monitor) and use any log level. Also,
|
||||||
the log level can be changed during a config reload.
|
the log level can be changed during a config reload.
|
||||||
|
|
||||||
- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs
|
- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs
|
||||||
|
@ -899,7 +899,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
||||||
Consul servers. When these keys are provided as configuration, they will only be
|
Consul servers. When these keys are provided as configuration, they will only be
|
||||||
respected on bootstrapping. If they are not provided, the defaults will be used.
|
respected on bootstrapping. If they are not provided, the defaults will be used.
|
||||||
In order to change the value of these options after bootstrapping, you will need
|
In order to change the value of these options after bootstrapping, you will need
|
||||||
to use the [Consul Operator Autopilot](/docs/commands/operator/autopilot)
|
to use the [Consul Operator Autopilot](/commands/operator/autopilot)
|
||||||
command. For more information about Autopilot, review the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations).
|
command. For more information about Autopilot, review the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations).
|
||||||
|
|
||||||
The following sub-keys are available:
|
The following sub-keys are available:
|
||||||
|
@ -1191,7 +1191,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
|
||||||
the Consul server gains leadership. This option is only applicable to server
|
the Consul server gains leadership. This option is only applicable to server
|
||||||
nodes. Each bootstrap entry will be created only if it does not exist. When reloading,
|
nodes. Each bootstrap entry will be created only if it does not exist. When reloading,
|
||||||
any new entries that have been added to the configuration will be processed.
|
any new entries that have been added to the configuration will be processed.
|
||||||
See the [configuration entry docs](/docs/agent/config_entries) for more
|
See the [configuration entry docs](/docs/agent/config-entries) for more
|
||||||
details about the contents of each entry.
|
details about the contents of each entry.
|
||||||
|
|
||||||
- `connect` This object allows setting options for the Connect feature.
|
- `connect` This object allows setting options for the Connect feature.
|
||||||
|
|
|
@ -289,7 +289,7 @@ These metrics give insight into the health of the cluster as a whole.
|
||||||
| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | flaps / interval | counter |
|
| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | flaps / interval | counter |
|
||||||
| `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter |
|
| `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter |
|
||||||
| `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter |
|
| `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter |
|
||||||
| `consul.serf.events` | This increments when an agent processes an [event](/docs/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
|
| `consul.serf.events` | This increments when an agent processes an [event](/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
|
||||||
| `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
|
| `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
|
||||||
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge |
|
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge |
|
||||||
| `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge |
|
| `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge |
|
||||||
|
|
|
@ -23,7 +23,7 @@ with some enhancements based on other research. There are more details about
|
||||||
|
|
||||||
Network coordinates manifest in several ways inside Consul:
|
Network coordinates manifest in several ways inside Consul:
|
||||||
|
|
||||||
- The [`consul rtt`](/docs/commands/rtt) command can be used to query for the
|
- The [`consul rtt`](/commands/rtt) command can be used to query for the
|
||||||
network round trip time between any two nodes.
|
network round trip time between any two nodes.
|
||||||
|
|
||||||
- The [Catalog endpoints](/api/catalog) and
|
- The [Catalog endpoints](/api/catalog) and
|
||||||
|
|
|
@ -50,7 +50,7 @@ Root certificates can be queried with the
|
||||||
With this endpoint, you can see the list of currently trusted root certificates.
|
With this endpoint, you can see the list of currently trusted root certificates.
|
||||||
When a cluster first initializes, this will only list one trusted root. Multiple
|
When a cluster first initializes, this will only list one trusted root. Multiple
|
||||||
roots may appear as part of
|
roots may appear as part of
|
||||||
[rotation](#).
|
[rotation](#root-certificate-rotation).
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ curl http://localhost:8500/v1/connect/ca/roots
|
$ curl http://localhost:8500/v1/connect/ca/roots
|
||||||
|
|
|
@ -54,7 +54,7 @@ gRPC](/docs/agent/options#grpc_port).
|
||||||
|
|
||||||
Additionally if you plan on using the observability features of Connect, it can
|
Additionally if you plan on using the observability features of Connect, it can
|
||||||
be convenient to configure your proxies and services using [configuration
|
be convenient to configure your proxies and services using [configuration
|
||||||
entries](/docs/agent/config_entries) which you can interact with using the
|
entries](/docs/agent/config-entries) which you can interact with using the
|
||||||
CLI or API, or by creating configuration entry files. You will want to enable
|
CLI or API, or by creating configuration entry files. You will want to enable
|
||||||
[centralized service
|
[centralized service
|
||||||
configuration](/docs/agent/options#enable_central_service_config) on
|
configuration](/docs/agent/options#enable_central_service_config) on
|
||||||
|
@ -71,7 +71,7 @@ needed for a secure deployment.
|
||||||
To account for common Connect use cases where you have many instances of the
|
To account for common Connect use cases where you have many instances of the
|
||||||
same service, and many colocated sidecar proxies, Consul allows you to customize
|
same service, and many colocated sidecar proxies, Consul allows you to customize
|
||||||
the settings for all of your proxies or all the instances of a given service at
|
the settings for all of your proxies or all the instances of a given service at
|
||||||
once using [Configuration Entries](/docs/agent/config_entries).
|
once using [Configuration Entries](/docs/agent/config-entries).
|
||||||
|
|
||||||
You can override centralized configurations for individual proxy instances in
|
You can override centralized configurations for individual proxy instances in
|
||||||
their
|
their
|
||||||
|
@ -100,5 +100,5 @@ configure Connect on Nomad by reading the
|
||||||
The Consul Helm chart can automate much of Consul Connect's configuration, and
|
The Consul Helm chart can automate much of Consul Connect's configuration, and
|
||||||
makes it easy to automatically inject Envoy sidecars into new pods when they are
|
makes it easy to automatically inject Envoy sidecars into new pods when they are
|
||||||
deployed. Learn about the [Helm chart](/docs/platform/k8s/helm) in general,
|
deployed. Learn about the [Helm chart](/docs/platform/k8s/helm) in general,
|
||||||
or if you are already familiar with it, check out it's
|
or if you are already familiar with it, check out its
|
||||||
[connect specific configurations](/docs/platform/k8s/connect).
|
[connect specific configurations](/docs/platform/k8s/connect).
|
||||||
|
|
|
@ -37,13 +37,15 @@ to this, the client provides its own client certificate to show its
|
||||||
identity to the destination service. If the connection handshake succeeds,
|
identity to the destination service. If the connection handshake succeeds,
|
||||||
the connection is encrypted and authorized.
|
the connection is encrypted and authorized.
|
||||||
|
|
||||||
The destination service verifies the client certificate
|
The destination service verifies the client certificate against the [public CA
|
||||||
against the [public CA bundle](/api/connect/ca#list-ca-root-certificates).
|
bundle](/api/connect/ca#list-ca-root-certificates). After verifying the
|
||||||
After verifying the certificate, it must also call the
|
certificate, the next step depends upon the configured application protocol of
|
||||||
[authorization API](/api/agent/connect#authorize) to authorize
|
the destination service. TCP (L4) services must authorize incoming _connections_
|
||||||
the connection against the configured set of Consul [intentions](/docs/connect/intentions).
|
against the configured set of Consul [intentions](/docs/connect/intentions),
|
||||||
If the authorization API responds successfully, the connection is established.
|
whereas HTTP (L7) services must authorize incoming _requests_ against those same
|
||||||
Otherwise, the connection is rejected.
|
intentions. If the intention check responds successfully, the
|
||||||
|
connection/request is established. Otherwise the connection/request is
|
||||||
|
rejected.
|
||||||
|
|
||||||
To generate and distribute certificates, Consul has a built-in CA that
|
To generate and distribute certificates, Consul has a built-in CA that
|
||||||
requires no other dependencies, and
|
requires no other dependencies, and
|
||||||
|
@ -59,12 +61,12 @@ in-memory data.
|
||||||
|
|
||||||
## Agent Caching and Performance
|
## Agent Caching and Performance
|
||||||
|
|
||||||
To enable fast responses on [agent Connect API
|
To enable fast responses on endpoints such as the [agent Connect
|
||||||
endpoints](/api/agent/connect), the Consul agent locally caches most
|
API](/api/agent/connect), the Consul agent locally caches most Connect-related
|
||||||
Connect-related data and sets up background [blocking
|
data and sets up background [blocking queries](/api/features/blocking) against
|
||||||
queries](/api/features/blocking) against the server to update the cache in
|
the server to update the cache in the background. This allows most API calls
|
||||||
the background. This allows most API calls such as retrieving certificates or
|
such as retrieving certificates or authorizing connections to use in-memory
|
||||||
authorizing connections to use in-memory data and respond very quickly.
|
data and respond very quickly.
|
||||||
|
|
||||||
All data cached locally by the agent is populated on demand. Therefore, if
|
All data cached locally by the agent is populated on demand. Therefore, if
|
||||||
Connect is not used at all, the cache does not store any data. On first request,
|
Connect is not used at all, the cache does not store any data. On first request,
|
||||||
|
@ -94,16 +96,16 @@ a long period of inactivity (3 days by default), the cache will empty itself.
|
||||||
|
|
||||||
## Connections Across Datacenters
|
## Connections Across Datacenters
|
||||||
|
|
||||||
Sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
|
A sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
|
||||||
may specify an alternative datacenter or a prepared query that can address services
|
may specify an alternative datacenter or a prepared query that can address services
|
||||||
in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) pattern).
|
in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) pattern).
|
||||||
|
|
||||||
[Intentions](/docs/connect/intentions) verify connections between services by
|
[Intentions](/docs/connect/intentions) verify connections between services by
|
||||||
source and destination name seamlessly across datacenters.
|
source and destination name seamlessly across datacenters.
|
||||||
|
|
||||||
Connections can be made via gateways to enable when communicating across
|
Connections can be made via gateways to enable communicating across network
|
||||||
network topologies allowing connections between services in each datacenter
|
topologies, allowing connections between services in each datacenter without
|
||||||
without externally routable IPs at the service level.
|
externally routable IPs at the service level.
|
||||||
|
|
||||||
## Intention Replication
|
## Intention Replication
|
||||||
|
|
||||||
|
|
|
@ -15,7 +15,7 @@ description: >-
|
||||||
It is often necessary to connect to a service for development or debugging.
|
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
|
If a service only exposes a Connect listener, then we need a way to establish
|
||||||
a mutual TLS connection to the service. The
|
a mutual TLS connection to the service. The
|
||||||
[`consul connect proxy` command](/docs/commands/connect/proxy) can be used
|
[`consul connect proxy` command](/commands/connect/proxy) can be used
|
||||||
for this task on any machine with access to a Consul agent (local or remote).
|
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
|
Restricting access to services only via Connect ensures that the only way to
|
||||||
|
|
|
@ -44,7 +44,7 @@ from the gateway to the destination service.
|
||||||
|
|
||||||
When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk.
|
When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk.
|
||||||
To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances
|
To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances
|
||||||
with the same [name](https://www.consul.io/docs/commands/connect/envoy#service) provides additional fault tolerance
|
with the same [name](/commands/connect/envoy#service) provides additional fault tolerance
|
||||||
as well as the ability to perform rolling restarts.
|
as well as the ability to perform rolling restarts.
|
||||||
|
|
||||||
-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS.
|
-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS.
|
||||||
|
@ -99,12 +99,12 @@ must also provide `agent:read` for its node's name in order to discover the agen
|
||||||
|
|
||||||
Linking services to a terminating gateway is done with a `terminating-gateway`
|
Linking services to a terminating gateway is done with a `terminating-gateway`
|
||||||
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the
|
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the
|
||||||
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
|
[CLI](/commands/config/write) or [API](/api/config#apply-configuration).
|
||||||
|
|
||||||
Gateways with the same name in Consul's service catalog are configured with a single configuration entry.
|
Gateways with the same name in Consul's service catalog are configured with a single configuration entry.
|
||||||
This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry.
|
This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry.
|
||||||
Adding replicas of a gateway that routes to a particular set of services requires running the
|
Adding replicas of a gateway that routes to a particular set of services requires running the
|
||||||
[envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
|
[envoy subcommand](/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
|
||||||
the same gateway name with the `service` flag.
|
the same gateway name with the `service` flag.
|
||||||
|
|
||||||
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
||||||
|
|
|
@ -0,0 +1,193 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Service-to-service permissions - Intentions (Legacy Mode)
|
||||||
|
sidebar_title: Service-to-service permissions - Intentions (Legacy Mode)
|
||||||
|
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 in Legacy Mode
|
||||||
|
|
||||||
|
~> **1.8.x and earlier:** This document only applies in Consul versions 1.8.x
|
||||||
|
and before. If you are using version 1.9.0 or later please use the updated
|
||||||
|
documentation [here](/docs/connect/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)
|
||||||
|
or [natively integrated application](/docs/connect/native) on
|
||||||
|
inbound connections. After verifying the TLS client certificate, the
|
||||||
|
[authorize API endpoint](/api-docs/agent/connect#authorize) 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/agent/options#acl_default_policy). If the default ACL policy is
|
||||||
|
"allow all", then all Connect connections are allowed by default. 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](/api-docs/connect/intentions),
|
||||||
|
[CLI](/commands/intention), 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](/api-docs/connect/intentions).
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ 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.
|
||||||
|
|
||||||
|
When an intention is modified, existing connections will not be affected.
|
||||||
|
This means that changing a connection from "allow" to "deny" today
|
||||||
|
_will not_ kill the connection. Addressing this shortcoming is on
|
||||||
|
the near term roadmap for Consul.
|
||||||
|
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ 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.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ 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. Specificity is determined by whether a value is an exact
|
||||||
|
specified value or is the wildcard value `*`.
|
||||||
|
The full precedence table is shown below and is evaluated
|
||||||
|
top to bottom, with larger numbers being evaluated first.
|
||||||
|
|
||||||
|
| Source Namespace | Source Name | Destination Namespace | Destination Name | Precedence |
|
||||||
|
| ---------------- | ----------- | --------------------- | ---------------- | ---------- |
|
||||||
|
| Exact | Exact | Exact | Exact | 9 |
|
||||||
|
| Exact | `*` | Exact | Exact | 8 |
|
||||||
|
| `*` | `*` | Exact | Exact | 7 |
|
||||||
|
| Exact | Exact | Exact | `*` | 6 |
|
||||||
|
| Exact | `*` | Exact | `*` | 5 |
|
||||||
|
| `*` | `*` | Exact | `*` | 4 |
|
||||||
|
| Exact | Exact | `*` | `*` | 3 |
|
||||||
|
| Exact | `*` | `*` | `*` | 2 |
|
||||||
|
| `*` | `*` | `*` | `*` | 1 |
|
||||||
|
|
||||||
|
The precedence value can be read from the [API](/api/connect/intentions)
|
||||||
|
after an intention is created.
|
||||||
|
Precedence cannot be manually overridden today. This is a feature that will
|
||||||
|
be added in a later version of Consul.
|
||||||
|
|
||||||
|
In the case the two precedence values match, Consul will evaluate
|
||||||
|
intentions based on lexicographical ordering of the destination then
|
||||||
|
source name. In practice, this is a moot point since authorizing a connection
|
||||||
|
has an exact source and destination value so its impossible for two
|
||||||
|
valid non-wildcard intentions to match.
|
||||||
|
|
||||||
|
The numbers in the table above are not stable. Their ordering will remain
|
||||||
|
fixed but the actual number values may change in the future.
|
||||||
|
|
||||||
|
-> **Consul Enterprise** - Namespaces are an Enterprise feature. In Consul OSS any of the rows in
|
||||||
|
the table with a `*` for either the source namespace or destination namespace are not applicable.
|
||||||
|
|
||||||
|
## Intention Management Permissions
|
||||||
|
|
||||||
|
Intention management can be protected by [ACLs](/docs/security/acl).
|
||||||
|
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 by default implicitly granted at `read` level
|
||||||
|
when granting `service:read` or `service:write`. This is because a
|
||||||
|
service registered that wants to use Connect needs `intentions:read`
|
||||||
|
for its own service name in order to know whether or not to authorize
|
||||||
|
connections. The following ACL policy will implicitly grant `intentions:read`
|
||||||
|
(note _read_) for service `web`.
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
service "web" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
It is possible to explicitly specify intention permissions. For example,
|
||||||
|
the following policy will allow a service to be discovered without granting
|
||||||
|
access to read intentions for it.
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
service "web" {
|
||||||
|
policy = "read"
|
||||||
|
intentions = "deny"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that `intentions:read` is required for a token that a Connect-enabled
|
||||||
|
service uses to register itself or its proxy. If the token used does not
|
||||||
|
have `intentions:read` then the agent will be unable to resolve intentions
|
||||||
|
for the service and so will not be able to authorize any incoming connections.
|
||||||
|
|
||||||
|
~> **Security Note:** Explicitly allowing `intentions:write` on the token you
|
||||||
|
provide to a service instance at registration time opens up a significant
|
||||||
|
additional vulnerability. Although you may trust the service _team_ to define
|
||||||
|
which inbound connections they accept, using a combined token for registration
|
||||||
|
allows a compromised instance to to redefine the intentions which allows many
|
||||||
|
additional attack vectors and may be hard to detect. We strongly recommend only
|
||||||
|
delegating `intentions:write` using tokens that are used by operations teams or
|
||||||
|
orchestrators rather than spread via application config, or only manage
|
||||||
|
intentions with management tokens.
|
||||||
|
|
||||||
|
## 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 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 static.
|
||||||
|
Even if the agents are severed completely from the Consul servers, inbound
|
||||||
|
connection authorization continues to work for a configured amount of time.
|
||||||
|
Changes to intentions will not be picked up until the partition heals, but
|
||||||
|
will then automatically take effect when connectivity is restored.
|
|
@ -4,85 +4,141 @@ page_title: Service-to-service permissions - Intentions
|
||||||
sidebar_title: Service-to-service permissions - Intentions
|
sidebar_title: Service-to-service permissions - Intentions
|
||||||
description: >-
|
description: >-
|
||||||
Intentions define access control for services via Connect and are used to
|
Intentions define access control for services via Connect and are used to
|
||||||
control which services may establish connections. Intentions can be managed
|
control which services may establish connections or make requests.
|
||||||
via the API, CLI, or UI.
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# Intentions
|
# Intentions
|
||||||
|
|
||||||
Intentions define access control for services via Connect and are used
|
-> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and
|
||||||
to control which services may establish connections. Intentions can be
|
later. The documentation for the legacy intentions system is
|
||||||
managed via the API, CLI, or UI.
|
[here](/docs/connect/intentions-legacy).
|
||||||
|
|
||||||
Intentions are enforced by the [proxy](/docs/connect/proxies)
|
Intentions define access control for services via Connect and are used to
|
||||||
or [natively integrated application](/docs/connect/native) on
|
control which services may establish connections or make requests. Intentions
|
||||||
inbound connections. After verifying the TLS client certificate, the
|
can be managed via the API, CLI, or UI.
|
||||||
[authorize API endpoint](/api-docs/agent/connect#authorize) 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
|
Intentions are enforced on inbound connections or requests by the
|
||||||
[ACL policy](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). If the default ACL policy is "allow all",
|
[proxy](/docs/connect/proxies) or within a [natively integrated
|
||||||
then all Connect connections are allowed by default. If the default ACL policy
|
application](/docs/connect/native).
|
||||||
is "deny all", then all Connect connections are denied by default.
|
|
||||||
|
Depending upon the [protocol] in use by the destination service, you can define
|
||||||
|
intentions to control Connect traffic authorization either at networking layer
|
||||||
|
4 (e.g. TCP) and networking layer 7 (e.g. HTTP):
|
||||||
|
|
||||||
|
* **Identity-based** - All intentions may enforce access based on identities
|
||||||
|
encoded within [TLS
|
||||||
|
certificates](/docs/connect/connect-internals#mutual-transport-layer-security-mtls).
|
||||||
|
This allows for coarse all-or-nothing access control between pairs of
|
||||||
|
services. These work with for services with any [protocol] as they only
|
||||||
|
require awareness of the TLS handshake that wraps the opaque TCP connection.
|
||||||
|
These can also be thought of as **L4 intentions**.
|
||||||
|
|
||||||
|
* **Application-aware** - Some intentions may additionally enforce access based
|
||||||
|
on [L7 request
|
||||||
|
attributes](/docs/agent/config-entries/service-intentions#permissions) in
|
||||||
|
addition to connection identity. These may only be defined for services with
|
||||||
|
a [protocol] that is HTTP-based. These can also be thought of as **L7
|
||||||
|
intentions**.
|
||||||
|
|
||||||
|
At any given point in time, between any pair of services **only one intention
|
||||||
|
controls authorization**. This may be either an L4 intention or an L7
|
||||||
|
intention, but at any given point in time only one of those applies.
|
||||||
|
|
||||||
|
The [intention match API](/api/connect/intentions#list-matching-intentions)
|
||||||
|
should be periodically called to retrieve all relevant intentions for the
|
||||||
|
target destination. After verifying the TLS client certificate, the cached
|
||||||
|
intentions should be consulted for each incoming connection/request to
|
||||||
|
determine if it should be accepted or rejected.
|
||||||
|
|
||||||
|
The default intention behavior is defined by the default [ACL
|
||||||
|
policy](/docs/agent/options#acl_default_policy). If the default ACL policy is
|
||||||
|
"allow all", then all Connect connections are allowed by default. If the
|
||||||
|
default ACL policy is "deny all", then all Connect connections or requests are
|
||||||
|
denied by default.
|
||||||
|
|
||||||
## Intention Basics
|
## Intention Basics
|
||||||
|
|
||||||
Intentions can be managed via the [API](#), [CLI](#),
|
Intentions are managed primarily via
|
||||||
or UI. Please see the respective documentation for each for full details
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
on options, flags, etc.
|
entries or the UI. Some simpler tasks can also be achieved with the older
|
||||||
Below is an example of a basic intention to show the basic attributes
|
[API](/api-docs/connect/intentions) or [CLI](/commands/intention). Please see
|
||||||
of an intention. The full data model of an intention can be found in the
|
the respective documentation for each for full details on options, flags, etc.
|
||||||
[API documentation](#).
|
|
||||||
|
|
||||||
```shell-session
|
Below is an example of a basic
|
||||||
$ consul intention create -deny web db
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
Created: web => db (deny)
|
entry representing two simple intentions. The full data model complete with
|
||||||
|
more examples can be found in the
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entry documentation.
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
|
Name = "db"
|
||||||
|
Sources = [
|
||||||
|
{
|
||||||
|
Name = "web"
|
||||||
|
Action = "deny"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
Name = "api"
|
||||||
|
Action = "allow"
|
||||||
|
}
|
||||||
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
The intention above is a deny intention with a source of "web" and
|
This config entry defines two intentions with a common destination of "db". The
|
||||||
destination of "db". This says that connections from web to db are not
|
first intention above is a deny intention with a source of "web". This says
|
||||||
allowed and the connection will be rejected.
|
that connections from web to db are not allowed and the connection will be
|
||||||
|
rejected. The second intention is an allow intention with a source of "api".
|
||||||
When an intention is modified, existing connections will not be affected.
|
This says that connections from api to db are allowed and connections will be
|
||||||
This means that changing a connection from "allow" to "deny" today
|
accepted.
|
||||||
_will not_ kill the connection. Addressing this shortcoming is on
|
|
||||||
the near term roadmap for Consul.
|
|
||||||
|
|
||||||
### Wildcard Intentions
|
### Wildcard Intentions
|
||||||
|
|
||||||
An intention source or destination may also be the special wildcard
|
An intention source or destination may also be the special wildcard
|
||||||
value `*`. This matches _any_ value and is used as a catch-all. Example:
|
value `*`. This matches _any_ value and is used as a catch-all.
|
||||||
|
|
||||||
```shell-session
|
This example says that the "web" service cannot connect to _any_ service:
|
||||||
$ consul intention create -deny web '*'
|
|
||||||
Created: web => * (deny)
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
|
Name = "*"
|
||||||
|
Sources = [
|
||||||
|
{
|
||||||
|
Name = "web"
|
||||||
|
Action = "deny"
|
||||||
|
}
|
||||||
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
This example says that the "web" service cannot connect to _any_ service.
|
And this example says that _no_ service can connect to the "db" service:
|
||||||
|
|
||||||
### Metadata
|
```hcl
|
||||||
|
Kind = "service-intentions"
|
||||||
Arbitrary string key/value data may be associated with intentions. This
|
Name = "db"
|
||||||
is unused by Consul but can be used by external systems or for visibility
|
Sources = [
|
||||||
in the UI.
|
{
|
||||||
|
Name = "*"
|
||||||
```shell-session
|
Action = "deny"
|
||||||
$ 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Enforcement
|
||||||
|
|
||||||
|
For services that define their [protocol] as TCP, intentions mediate the
|
||||||
|
ability to **establish new connections**. When an intention is modified,
|
||||||
|
existing connections will not be affected. This means that changing a
|
||||||
|
connection from "allow" to "deny" today _will not_ kill the connection.
|
||||||
|
|
||||||
|
For services that define their protocol as HTTP-based, intentions mediate the
|
||||||
|
ability to **issue new requests**.
|
||||||
|
|
||||||
|
When an intention is modified, requests received after the modification will
|
||||||
|
use the latest intention rules to enforce access. This means that though
|
||||||
|
changing a connection from "allow" to "deny" today will not kill the
|
||||||
|
connection, it will correctly block new requests from being processed.
|
||||||
|
|
||||||
## Precedence and Match Order
|
## Precedence and Match Order
|
||||||
|
|
||||||
Intentions are matched in an implicit order based on specificity, preferring
|
Intentions are matched in an implicit order based on specificity, preferring
|
||||||
|
@ -103,26 +159,21 @@ top to bottom, with larger numbers being evaluated first.
|
||||||
| Exact | `*` | `*` | `*` | 2 |
|
| Exact | `*` | `*` | `*` | 2 |
|
||||||
| `*` | `*` | `*` | `*` | 1 |
|
| `*` | `*` | `*` | `*` | 1 |
|
||||||
|
|
||||||
The precedence value can be read from the [API](/api/connect/intentions)
|
The precedence value can be read from a
|
||||||
after an intention is created.
|
[field](/docs/agent/config-entries/service-intentions#precedence) on the
|
||||||
Precedence cannot be manually overridden today. This is a feature that will
|
`service-intentions` config entry after it is modified. Precedence cannot be
|
||||||
be added in a later version of Consul.
|
manually overridden today.
|
||||||
|
|
||||||
In the case the two precedence values match, Consul will evaluate
|
|
||||||
intentions based on lexicographical ordering of the destination then
|
|
||||||
source name. In practice, this is a moot point since authorizing a connection
|
|
||||||
has an exact source and destination value so its impossible for two
|
|
||||||
valid non-wildcard intentions to match.
|
|
||||||
|
|
||||||
The numbers in the table above are not stable. Their ordering will remain
|
The numbers in the table above are not stable. Their ordering will remain
|
||||||
fixed but the actual number values may change in the future.
|
fixed but the actual number values may change in the future.
|
||||||
|
|
||||||
-> **Consul Enterprise** - Namespaces are an Enterprise feature. In Consul OSS any of the rows in
|
-> <EnterpriseAlert inline /> - Namespaces are an Enterprise feature. In Consul
|
||||||
the table with a `*` for either the source namespace or destination namespace are not applicable.
|
OSS the only allowable value for either namespace field is `"default"`. Other
|
||||||
|
rows in this table are not applicable.
|
||||||
|
|
||||||
## Intention Management Permissions
|
## Intention Management Permissions
|
||||||
|
|
||||||
Intention management can be protected by [ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
Intention management can be protected by [ACLs](/docs/security/acl).
|
||||||
Permissions for intentions are _destination-oriented_, meaning the ACLs
|
Permissions for intentions are _destination-oriented_, meaning the ACLs
|
||||||
for managing intentions are looked up based on the destination value
|
for managing intentions are looked up based on the destination value
|
||||||
of the intention, not the source.
|
of the intention, not the source.
|
||||||
|
@ -152,7 +203,7 @@ service "web" {
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that `intentions:read` is required for a token that a Connect-enabled
|
Note that `intentions:read` is required for a token that a Connect-enabled
|
||||||
service uses to register itself or it's proxy. If the token used does not
|
service uses to register itself or its proxy. If the token used does not
|
||||||
have `intentions:read` then the agent will be unable to resolve intentions
|
have `intentions:read` then the agent will be unable to resolve intentions
|
||||||
for the service and so will not be able to authorize any incoming connections.
|
for the service and so will not be able to authorize any incoming connections.
|
||||||
|
|
||||||
|
@ -172,17 +223,23 @@ The intentions for services registered with a Consul agent are cached
|
||||||
locally on that agent. They are then updated via a background blocking query
|
locally on that agent. They are then updated via a background blocking query
|
||||||
against the Consul servers.
|
against the Consul servers.
|
||||||
|
|
||||||
Connect connection attempts require only local agent
|
Supported [proxies] (such as [Envoy]) also cache this data within their own
|
||||||
communication for authorization and generally impose only impose microseconds
|
configuration so that inbound connections or requests require no Consul agent
|
||||||
of latency to the connection. All actions in the data path of connections
|
involvement during authorization. All actions in the data path of connections
|
||||||
require only local data to ensure minimal performance overhead.
|
happen within the proxy.
|
||||||
|
|
||||||
Updates to intentions are propagated nearly instantly to agents since agents
|
Updates to intentions are propagated nearly instantly to agents since agents
|
||||||
maintain a continuous blocking query in the background for intention updates
|
maintain a continuous blocking query in the background for intention updates
|
||||||
for registered services.
|
for registered services. Proxies similarly use blocking queries to update
|
||||||
|
their local configurations quickly.
|
||||||
|
|
||||||
Because all the intention data is cached locally, the agents can fail static.
|
Because all the intention data is cached locally, the agents or proxies can
|
||||||
Even if the agents are severed completely from the Consul servers, inbound
|
fail static. Even if the agents are severed completely from the Consul servers,
|
||||||
connection authorization continues to work for a configured amount of time.
|
or the proxies are severed completely from their local Consul agent, inbound
|
||||||
Changes to intentions will not be picked up until the partition heals, but
|
connection authorization continues to work indefinitely. Changes to intentions
|
||||||
will then automatically take effect when connectivity is restored.
|
will not be picked up until the partition heals, but will then automatically
|
||||||
|
take effect when connectivity is restored.
|
||||||
|
|
||||||
|
[protocol]: /docs/agent/config-entries/service-defaults#protocol
|
||||||
|
[proxies]: /docs/connect/proxies
|
||||||
|
[Envoy]: /docs/connect/proxies/envoy
|
||||||
|
|
|
@ -19,7 +19,7 @@ integrations](/docs/connect/proxies/integrate).
|
||||||
The service discovery process can be modeled as a "discovery chain" which
|
The service discovery process can be modeled as a "discovery chain" which
|
||||||
passes through three distinct stages: routing, splitting, and resolution. Each
|
passes through three distinct stages: routing, splitting, and resolution. Each
|
||||||
of these stages is controlled by a set of [configuration
|
of these stages is controlled by a set of [configuration
|
||||||
entries](/docs/agent/config_entries). By configuring different phases of
|
entries](/docs/agent/config-entries). By configuring different phases of
|
||||||
the discovery chain a user can control how proxy upstreams are ultimately
|
the discovery chain a user can control how proxy upstreams are ultimately
|
||||||
resolved to specific instances for load balancing.
|
resolved to specific instances for load balancing.
|
||||||
|
|
||||||
|
|
|
@ -37,7 +37,7 @@ traffic.
|
||||||
![diagram showing l7 traffic discovery stages: routing to splitting to resolution](/img/l7-traffic-stages.svg)
|
![diagram showing l7 traffic discovery stages: routing to splitting to resolution](/img/l7-traffic-stages.svg)
|
||||||
|
|
||||||
Each stage of this discovery process can be dynamically reconfigured via various
|
Each stage of this discovery process can be dynamically reconfigured via various
|
||||||
[configuration entries](/docs/agent/config_entries). When a configuration
|
[configuration entries](/docs/agent/config-entries). When a configuration
|
||||||
entry is missing, that stage will fall back on reasonable default behavior.
|
entry is missing, that stage will fall back on reasonable default behavior.
|
||||||
|
|
||||||
### Routing
|
### Routing
|
||||||
|
|
|
@ -11,6 +11,10 @@ description: >-
|
||||||
|
|
||||||
# Connect-Native Integration with Go
|
# Connect-Native Integration with Go
|
||||||
|
|
||||||
|
-> **Note:** When calling `ConnectAuthorize()` on incoming connections this library
|
||||||
|
will return *deny* if `Permissions` are defined on the matching intention.
|
||||||
|
The method is currently only suited for networking layer 4 (e.g. TCP) integration.
|
||||||
|
|
||||||
We provide a library that makes it drop-in simple to integrate Connect
|
We provide a library that makes it drop-in simple to integrate Connect
|
||||||
with most [Go](https://golang.org/) applications. This page shows examples
|
with most [Go](https://golang.org/) applications. This page shows examples
|
||||||
of integrating this library for accepting or establishing Connect-based
|
of integrating this library for accepting or establishing Connect-based
|
||||||
|
@ -178,7 +182,7 @@ the following specific limitations:
|
||||||
- `<name>.query[.<datacenter>].consul` to discover an instance via
|
- `<name>.query[.<datacenter>].consul` to discover an instance via
|
||||||
[Prepared Query](/api/query).
|
[Prepared Query](/api/query).
|
||||||
- The top-level domain _must_ be `.consul` even if your cluster has a custom
|
- The top-level domain _must_ be `.consul` even if your cluster has a custom
|
||||||
`domain` configured for it's DNS interface. This might be relaxed in the
|
`domain` configured for its DNS interface. This might be relaxed in the
|
||||||
future.
|
future.
|
||||||
- Tag filters for services are not currently supported (i.e.
|
- Tag filters for services are not currently supported (i.e.
|
||||||
`tag1.web.service.consul`) however the same behaviour can be achieved using a
|
`tag1.web.service.consul`) however the same behaviour can be achieved using a
|
||||||
|
@ -194,8 +198,8 @@ return the `net.Conn`. This connection can then be used as desired.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
````go
|
```go
|
||||||
import(
|
import (
|
||||||
"context"
|
"context"
|
||||||
|
|
||||||
"github.com/hashicorp/consul/api"
|
"github.com/hashicorp/consul/api"
|
||||||
|
@ -241,4 +245,3 @@ The Go library provides two built-in resolvers:
|
||||||
* `*connect.ConsulResolver` which resolves services and prepared queries
|
* `*connect.ConsulResolver` which resolves services and prepared queries
|
||||||
via the Consul API. This also automatically determines the expected
|
via the Consul API. This also automatically determines the expected
|
||||||
cert URI SAN.
|
cert URI SAN.
|
||||||
````
|
|
||||||
|
|
|
@ -35,7 +35,8 @@ to integrate with Connect.
|
||||||
The primary work involved in natively integrating with Connect is
|
The primary work involved in natively integrating with Connect is
|
||||||
[acquiring the proper TLS certificate](/api/agent/connect#service-leaf-certificate),
|
[acquiring the proper TLS certificate](/api/agent/connect#service-leaf-certificate),
|
||||||
[verifying TLS certificates](/api/agent/connect#certificate-authority-ca-roots),
|
[verifying TLS certificates](/api/agent/connect#certificate-authority-ca-roots),
|
||||||
and [authorizing inbound connections](/api/agent/connect#authorize).
|
and [authorizing inbound connections or requests](/api/connect/intentions#list-matching-intentions).
|
||||||
|
|
||||||
All of this is done using the Consul HTTP APIs linked above.
|
All of this is done using the Consul HTTP APIs linked above.
|
||||||
|
|
||||||
An overview of the sequence is shown below. The diagram and the following
|
An overview of the sequence is shown below. The diagram and the following
|
||||||
|
@ -44,6 +45,9 @@ an API call to verify the incoming client certificate.
|
||||||
|
|
||||||
![Native Integration Overview](/img/connect-native-overview.png)
|
![Native Integration Overview](/img/connect-native-overview.png)
|
||||||
|
|
||||||
|
-> **Note:** This diagram depicts the simpler networking layer 4 (e.g. TCP) [integration
|
||||||
|
mechanism](/api/agent/connect#authorize).
|
||||||
|
|
||||||
Details on the steps are below:
|
Details on the steps are below:
|
||||||
|
|
||||||
- **Service discovery** - This is normal service discovery using Consul,
|
- **Service discovery** - This is normal service discovery using Consul,
|
||||||
|
@ -61,20 +65,32 @@ Details on the steps are below:
|
||||||
a Connect-based connection and there are no further steps!
|
a Connect-based connection and there are no further steps!
|
||||||
|
|
||||||
- **Authorization** - As a server accepting connections, verify the client
|
- **Authorization** - As a server accepting connections, verify the client
|
||||||
certificate against the
|
certificate against the [public CA
|
||||||
[public CA roots](/api/agent/connect#certificate-authority-ca-roots).
|
roots](/api/agent/connect#certificate-authority-ca-roots). After verifying
|
||||||
After verifying the certificate, parse some basic fields from it and call
|
the certificate, parse some basic fields from it and use those to determine
|
||||||
the [authorizing API](/api/agent/connect#authorize) against the local
|
if the connection should be allowed. How this is done is dependent on
|
||||||
agent. If this returns successfully, complete the TLS handshake and establish
|
the level of integration desired:
|
||||||
the connection. If authorization fails, close the connection.
|
|
||||||
|
|
||||||
-> **A note on performance:** The only API call in the connection path is
|
- **Simple integration (TCP-only)** - Call the [authorizing
|
||||||
the [authorization API](/api/agent/connect#authorize). The other API
|
API](/api/agent/connect#authorize) against the local agent. If this returns
|
||||||
calls to acquire the leaf certificate and CA roots are expected to be done
|
successfully, complete the TLS handshake and establish the connection. If
|
||||||
out of band and reused. The authorize API call should be called against the
|
authorization fails, close the connection.
|
||||||
local Consul agent. The agent uses locally cached
|
|
||||||
data to authorize the connection and typically responds in microseconds.
|
-> **NOTE:** This API call is expected to be called in the connection path,
|
||||||
Therefore, the impact to the TLS handshake is typically microseconds.
|
so if the local Consul agent is down or unresponsive it will effect the
|
||||||
|
success rate of new connections. The agent uses locally cached data to
|
||||||
|
authorize the connection and typically responds in microseconds. Therefore,
|
||||||
|
the impact to the TLS handshake is typically microseconds.
|
||||||
|
|
||||||
|
- **Complete integration** - Like how the calls to acquire the leaf
|
||||||
|
certificate and CA roots are expected to be done out of band and reused, so
|
||||||
|
should the [intention match
|
||||||
|
API](/api/connect/intentions#list-matching-intentions). With all of the
|
||||||
|
relevant intentions cached for the destination, all enforcement operations
|
||||||
|
can be done entirely by the service without calling any Consul APIs in the
|
||||||
|
connection or request path. If the service is networking layer 7 (e.g.
|
||||||
|
HTTP) aware it can safely enforce intentions per _request_ instead of the
|
||||||
|
coarser per _connection_ model.
|
||||||
|
|
||||||
## Updating Certificates and Certificate Roots
|
## Updating Certificates and Certificate Roots
|
||||||
|
|
||||||
|
|
|
@ -53,10 +53,10 @@ for the built-in proxy.
|
||||||
|
|
||||||
All fields are optional with a sane default.
|
All fields are optional with a sane default.
|
||||||
|
|
||||||
- `bind_address` - The address the proxy will bind it's
|
- `bind_address` - The address the proxy will bind its
|
||||||
_public_ mTLS listener to. It defaults to the same address the agent binds to.
|
_public_ mTLS listener to. It defaults to the same address the agent binds to.
|
||||||
|
|
||||||
- `bind_port` - The port the proxy will bind it's _public_
|
- `bind_port` - The port the proxy will bind its _public_
|
||||||
mTLS listener to. If not provided, the agent will attempt to assign one from its
|
mTLS listener to. If not provided, the agent will attempt to assign one from its
|
||||||
[configured proxy port range](/docs/agent/options#sidecar_min_port) if available.
|
[configured proxy port range](/docs/agent/options#sidecar_min_port) if available.
|
||||||
By default the range is [20000, 20255] and the port is selected at random from
|
By default the range is [20000, 20255] and the port is selected at random from
|
||||||
|
@ -69,7 +69,7 @@ All fields are optional with a sane default.
|
||||||
dial the proxy over loopback. For more complex configurations where agent and proxy
|
dial the proxy over loopback. For more complex configurations where agent and proxy
|
||||||
communicate over a bridge for example, this configuration can be used to specify
|
communicate over a bridge for example, this configuration can be used to specify
|
||||||
a different _address_ (but not port) for the agent to use for health checks if
|
a different _address_ (but not port) for the agent to use for health checks if
|
||||||
it can't talk to the proxy over localhost or it's publicly advertised port. The
|
it can't talk to the proxy over localhost or its publicly advertised port. The
|
||||||
check always uses the same port that the proxy is bound to.
|
check always uses the same port that the proxy is bound to.
|
||||||
|
|
||||||
- `disable_tcp_check` - If true, this disables a
|
- `disable_tcp_check` - If true, this disables a
|
||||||
|
|
|
@ -13,19 +13,19 @@ optionally exposing a gRPC service on the local agent that serves [Envoy's xDS
|
||||||
configuration
|
configuration
|
||||||
API](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).
|
API](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).
|
||||||
|
|
||||||
Consul can configure Envoy sidecars to proxy http/1.1, http2 or gRPC traffic at
|
Consul can configure Envoy sidecars to proxy http/1.1, http2, or gRPC traffic at
|
||||||
L7 or any other tcp-based protocol at L4. Prior to Consul 1.5.0 Envoy proxies
|
L7 or any other tcp-based protocol at L4. Prior to Consul 1.5.0 Envoy proxies
|
||||||
could only proxy tcp at L4.
|
could only proxy tcp at L4.
|
||||||
|
|
||||||
Configuration of some [L7 features](/docs/connect/l7-traffic-management)
|
Configuration of some [L7 features](/docs/connect/l7-traffic-management)
|
||||||
is possible via [configuration entries](/docs/agent/config_entries). If
|
is possible via [configuration entries](/docs/agent/config-entries). If
|
||||||
you wish to use an Envoy feature not currently exposed through these config
|
you wish to use an Envoy feature not currently exposed through these config
|
||||||
entries as an interim solution, you can add [custom Envoy
|
entries as an interim solution, you can add [custom Envoy
|
||||||
configuration](#advanced-configuration) in the [proxy service
|
configuration](#advanced-configuration) in the [proxy service
|
||||||
definition](/docs/connect/registration/service-registration) allowing you
|
definition](/docs/connect/registration/service-registration) allowing you
|
||||||
to use the more powerful features of Envoy.
|
to use the more powerful features of Envoy.
|
||||||
|
|
||||||
~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/docs/commands/connect/envoy)
|
~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/commands/connect/envoy)
|
||||||
Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0.
|
Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0.
|
||||||
|
|
||||||
## Supported Versions
|
## Supported Versions
|
||||||
|
@ -33,22 +33,27 @@ Envoy must be run with the `--max-obj-name-len` option set to `256` or greater f
|
||||||
Consul's Envoy support was added in version 1.3.0. The following table shows
|
Consul's Envoy support was added in version 1.3.0. The following table shows
|
||||||
compatible Envoy versions.
|
compatible Envoy versions.
|
||||||
|
|
||||||
| Consul Version | Compatible Envoy Versions |
|
| Consul Version | Compatible Envoy Versions |
|
||||||
| ------------------- | -------------------------------- |
|
| ------------------- | --------------------------------- |
|
||||||
| 1.9.x | 1.15.0, 1.14.4, 1.13.4, 1.12.6 |
|
| 1.9.x | 1.15.0, 1.14.4‡, 1.13.4‡, 1.12.6‡ |
|
||||||
| 1.8.x | 1.14.4, 1.13.4, 1.12.6, 1.11.2 |
|
| 1.8.x | 1.14.4, 1.13.4, 1.12.6, 1.11.2 |
|
||||||
| 1.7.x | 1.13.1, 1.12.3, 1.11.2, 1.10.0\* |
|
| 1.7.x | 1.13.1, 1.12.3, 1.11.2, 1.10.0\* |
|
||||||
| 1.5.2, 1.5.3, 1.6.x | 1.11.1, 1.10.0, 1.9.1, 1.8.0† |
|
| 1.6.x, 1.5.3, 1.5.2 | 1.11.1, 1.10.0, 1.9.1, 1.8.0† |
|
||||||
| 1.5.0, 1.5.1 | 1.9.1, 1.8.0† |
|
| 1.5.1, 1.5.0 | 1.9.1, 1.8.0† |
|
||||||
| 1.3.x, 1.4.x | 1.9.1, 1.8.0†, 1.7.0† |
|
| 1.4.x, 1.3.x | 1.9.1, 1.8.0†, 1.7.0† |
|
||||||
|
|
||||||
~> † Envoy versions lower than 1.9.1 are vulnerable to
|
~> ‡ To ensure that intention enforcement is updated as quickly as possible
|
||||||
|
after any changes, it is advised to run Consul 1.9.0 with Envoy 1.15.0+ due to a
|
||||||
|
[listener update improvement](https://github.com/envoyproxy/envoy/pull/10662).<br/><br/>
|
||||||
|
† Envoy versions lower than 1.9.1 are vulnerable to
|
||||||
[CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and
|
[CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and
|
||||||
[CVE-2019-9901](https://github.com/envoyproxy/envoy/issues/6435). Both are
|
[CVE-2019-9901](https://github.com/envoyproxy/envoy/issues/6435). Both are
|
||||||
related to HTTP request parsing and so only affect Consul Connect users if they
|
related to HTTP request parsing and so only affect Consul Connect users if they
|
||||||
have configured HTTP routing rules via the ["escape
|
have configured HTTP routing rules. Still, we recommend that you use the most
|
||||||
hatch"](#escape-hatch-overrides). Still, we recommend that you use the most
|
recent supported Envoy for your Consul version where possible.<br/><br/>
|
||||||
recent supported Envoy for your Consul version where possible.<br/><br/>\* Envoy 1.10.0 requires setting [`-envoy-version`](/docs/commands/connect/envoy#envoy-version) in the `consul connect envoy` command. This was introduced in Consul 1.7.0.
|
\* Envoy 1.10.0 requires setting
|
||||||
|
[`-envoy-version`](/commands/connect/envoy#envoy-version) in the `consul
|
||||||
|
connect envoy` command. This was introduced in Consul 1.7.0.
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
|
@ -62,14 +67,15 @@ configuration_ and dynamic configuration that is discovered from a "management
|
||||||
server", in this case Consul.
|
server", in this case Consul.
|
||||||
|
|
||||||
The bootstrap configuration at a minimum needs to configure the proxy with an
|
The bootstrap configuration at a minimum needs to configure the proxy with an
|
||||||
identity (node id) and the location of it's local Consul agent from which it
|
identity (node id) and the location of its local Consul agent from which it
|
||||||
discovers all of it's dynamic configuration. See [Bootstrap
|
discovers all of its dynamic configuration. See [Bootstrap
|
||||||
Configuration](#bootstrap-configuration) for more details.
|
Configuration](#bootstrap-configuration) for more details.
|
||||||
|
|
||||||
The dynamic configuration Consul Connect provides to each Envoy instance includes:
|
The dynamic configuration Consul Connect provides to each Envoy instance includes:
|
||||||
|
|
||||||
- TLS certificates and keys to enable mutual authentication and keep certificates
|
- TLS certificates and keys to enable mutual authentication and keep certificates
|
||||||
rotating.
|
rotating.
|
||||||
|
- [Intentions] to enforce service-to-service authorization rules.
|
||||||
- Service-discovery results for upstreams to enable each sidecar proxy to load-balance
|
- Service-discovery results for upstreams to enable each sidecar proxy to load-balance
|
||||||
outgoing connections.
|
outgoing connections.
|
||||||
- L7 configuration including timeouts and protocol-specific options.
|
- L7 configuration including timeouts and protocol-specific options.
|
||||||
|
@ -87,11 +93,21 @@ users to provide low-level raw Envoy config syntax for some sub-components in ea
|
||||||
Envoy instance. This allows operators to have full control over and
|
Envoy instance. This allows operators to have full control over and
|
||||||
responsibility for correctly configuring Envoy and ensuring version support etc.
|
responsibility for correctly configuring Envoy and ensuring version support etc.
|
||||||
|
|
||||||
|
## Intention Enforcement
|
||||||
|
|
||||||
|
[Intentions] are enforced using Envoy's RBAC filters. Depending upon the
|
||||||
|
configured [protocol] of the proxied service these are either enforced
|
||||||
|
per-connection (L4) using a network filter or per-request (L7) using an HTTP
|
||||||
|
filter.
|
||||||
|
|
||||||
|
-> **Note:** Prior to Consul 1.9.0 intentions were exclusively enforced
|
||||||
|
per-connection (L4) using an `ext_authz` network filter.
|
||||||
|
|
||||||
## Bootstrap Configuration
|
## Bootstrap Configuration
|
||||||
|
|
||||||
Envoy requires an initial bootstrap configuration file. The easiest way to
|
Envoy requires an initial bootstrap configuration file. The easiest way to
|
||||||
create this is using the [`consul connect envoy`
|
create this is using the [`consul connect envoy`
|
||||||
command](/docs/commands/connect/envoy). The command can either output the
|
command](/commands/connect/envoy). The command can either output the
|
||||||
bootstrap configuration directly to stdout or can generate it and then `exec`
|
bootstrap configuration directly to stdout or can generate it and then `exec`
|
||||||
the Envoy binary as a convenience wrapper.
|
the Envoy binary as a convenience wrapper.
|
||||||
|
|
||||||
|
@ -179,7 +195,7 @@ definition](/docs/connect/registration/service-registration) that is
|
||||||
actually registered.
|
actually registered.
|
||||||
|
|
||||||
To learn about other options that can be configured centrally see the
|
To learn about other options that can be configured centrally see the
|
||||||
[Configuration Entries](/docs/agent/config_entries) docs.
|
[Configuration Entries](/docs/agent/config-entries) docs.
|
||||||
|
|
||||||
### Proxy Config Options
|
### Proxy Config Options
|
||||||
|
|
||||||
|
@ -461,12 +477,12 @@ definition](/docs/connect/registration/service-registration) or
|
||||||
is used in place of [the default
|
is used in place of [the default
|
||||||
template](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L87)
|
template](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L87)
|
||||||
when generating bootstrap via [`consul connect envoy`
|
when generating bootstrap via [`consul connect envoy`
|
||||||
command](/docs/commands/connect/envoy). The variables that are available
|
command](/commands/connect/envoy). The variables that are available
|
||||||
to be interpolated are [documented
|
to be interpolated are [documented
|
||||||
here](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L5).
|
here](https://github.com/hashicorp/consul/blob/b64bda880843afaaf44591c3200f921626716849/command/connect/envoy/bootstrap_tpl.go#L5).
|
||||||
This offers complete control of the proxy's bootstrap although major
|
This offers complete control of the proxy's bootstrap although major
|
||||||
deviations from the default template may break Consul's ability to correctly
|
deviations from the default template may break Consul's ability to correctly
|
||||||
manage the proxy or enforce it's security model.
|
manage the proxy or enforce its security model.
|
||||||
- `envoy_public_listener_json` - Specifies a complete
|
- `envoy_public_listener_json` - Specifies a complete
|
||||||
[Listener](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/api/v2/lds.proto)
|
[Listener](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/api/v2/lds.proto)
|
||||||
to be delivered in place of the main public listener that the proxy used to
|
to be delivered in place of the main public listener that the proxy used to
|
||||||
|
@ -510,3 +526,7 @@ warning.
|
||||||
to be delivered in place of the discovered upstream cluster. This allows
|
to be delivered in place of the discovered upstream cluster. This allows
|
||||||
customization of timeouts, circuit breaking, rate limits, load balancing
|
customization of timeouts, circuit breaking, rate limits, load balancing
|
||||||
strategy etc.
|
strategy etc.
|
||||||
|
|
||||||
|
[protocol]: /docs/agent/config-entries/service-defaults#protocol
|
||||||
|
[intentions]: /docs/connect/intentions
|
||||||
|
[Intentions]: /docs/connect/intentions
|
||||||
|
|
|
@ -11,46 +11,130 @@ description: >-
|
||||||
# Connect Custom Proxy Integration
|
# Connect Custom Proxy Integration
|
||||||
|
|
||||||
Any proxy can be extended to support Connect. Consul ships with a built-in
|
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
|
proxy for a good development and out of the box experience, but production
|
||||||
that production users will require other proxy solutions.
|
users will require other proxy solutions.
|
||||||
|
|
||||||
A proxy must serve one or both of the following two roles: it must accept
|
A proxy must serve one or both of the following two roles: it must accept
|
||||||
inbound connections or establish outbound connections identified as a
|
inbound connections or establish outbound connections identified as a
|
||||||
particular service. One or both of these may be implemented depending on
|
particular service. One or both of these may be implemented depending on the
|
||||||
the case, although generally both must be supported.
|
case, although generally both must be supported for full sidecar functionality.
|
||||||
|
|
||||||
|
There are also two different levels of compatibility as a sidecar: L4 or L7.
|
||||||
|
L4 integration is simpler and adequate to secure all traffic but treats all
|
||||||
|
traffic as TCP so no advanced routing or metrics features can be supported.
|
||||||
|
Full L7 support is built on top of L4 support and includes supporting most or
|
||||||
|
all of the L7 traffic routing features in Connect by dynamically configuring
|
||||||
|
routing, retries and more L7 features. Currently The built-in proxy only
|
||||||
|
supports L4 while Envoy supports the full L7 feature set.
|
||||||
|
|
||||||
|
Places where the integration approach diverges for L4/L7 support is indicated
|
||||||
|
below.
|
||||||
|
|
||||||
## Accepting Inbound Connections
|
## Accepting Inbound Connections
|
||||||
|
|
||||||
For inbound connections, the proxy must accept TLS connections on some port.
|
For inbound connections, the proxy must accept TLS connections on some port.
|
||||||
The certificate served should be created by the
|
The certificate served should be obtained from the
|
||||||
[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
|
[`/v1/agent/connect/ca/leaf/`] API endpoint. The client certificate should be
|
||||||
The client certificate should be validated against the root certificates
|
validated against the root certificates provided by the
|
||||||
provided by the
|
[`/v1/agent/connect/ca/roots`] endpoint. After validating the client
|
||||||
[`/v1/agent/connect/ca/roots`](/api/agent/connect) endpoint.
|
certificate from the caller, depending upon the [protocol] of the proxied
|
||||||
After validating the client certificate from the caller, the proxy should
|
service service the proxy must either authorize the entire connection (L4) or
|
||||||
call the
|
each request (L7).
|
||||||
[`/v1/agent/connect/authorize`](/api/agent/connect) endpoint to
|
|
||||||
authorize the connection.
|
|
||||||
|
|
||||||
All of these API endpoints operate on agent-local data that is updated
|
Connection authorization can be performed one of two ways:
|
||||||
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
|
1. The first is by calling the
|
||||||
used if possible to get near-immediate updates for root cert rotations,
|
[`/v1/agent/connect/authorize`](/api/agent/connect) endpoint. The authorize
|
||||||
leaf expiry, etc.
|
endpoint is expected to be called in the connection path, so if the local
|
||||||
|
Consul agent is down or unresponsive it will impact the success rate of new
|
||||||
|
connections. The agent uses locally cached data to authorize the connection
|
||||||
|
and typically responds in microseconds. Therefore, the impact to the TLS
|
||||||
|
handshake is typically microseconds.
|
||||||
|
|
||||||
|
~> **Note:** This endpoint is only suited for networking layer 4 (e.g. TCP)
|
||||||
|
integration. The endpoint will always treat intentions with Permissions
|
||||||
|
defined (i.e., layer 7 criteria) as deny intentions during evaluation.
|
||||||
|
|
||||||
|
2. Alternatively, proxies may list intentions that match the destination by
|
||||||
|
querying the [intention match
|
||||||
|
API](/api/connect/intentions#list-matching-intentions) endpoint, and
|
||||||
|
represent them in the native configuration of the proxy itself (such as RBAC
|
||||||
|
for Envoy). For performance and reliability reasons this is the desirable
|
||||||
|
method for implementing intention enforcement. The cached intentions should
|
||||||
|
be consulted for each incoming connection (L4) or request (L7) to determine
|
||||||
|
if the should be accepted or rejected.
|
||||||
|
|
||||||
|
All of these API endpoints operate on agent-local data that is updated in the
|
||||||
|
background. The leaf, roots, and intentions should be updated in the background
|
||||||
|
by the proxy.
|
||||||
|
|
||||||
|
The leaf cert, root cert, and intentions endpoints support [blocking
|
||||||
|
queries](/api/features/blocking), which should be used to get near-immediate
|
||||||
|
updates for root key rotations, new leaf certs before expiry, and intention
|
||||||
|
changes.
|
||||||
|
|
||||||
|
Although Consul follows the SPIFFE spec for certificates, some currently
|
||||||
|
supported CA providers don't allow strict adherence. For example, CA
|
||||||
|
certificates may not have the correct trust-domain SPIFFE URI SAN for the
|
||||||
|
cluster. If SPIFFE validation is performed in the proxy, be aware that it
|
||||||
|
should be possible to opt out, otherwise certain CA providers supported by
|
||||||
|
Consul will not be compatible with the use of that proxy. Currently neither
|
||||||
|
Envoy nor the built-in proxy validate the SPIFFE URI of the chain beyond the
|
||||||
|
leaf certificate.
|
||||||
|
|
||||||
|
### Connection Authorization
|
||||||
|
|
||||||
|
Authentication is based on "service identity" (TLS), and is implemented at the
|
||||||
|
transport layer. Depending upon the [protocol] of the proxied service,
|
||||||
|
authorization is performed either on a per-connection (L4) or per-request (L7)
|
||||||
|
basis.
|
||||||
|
|
||||||
|
-> **Note:** Features like (local) rate limiting or max connections are
|
||||||
|
configurations that we expect to push into proxies and have them enforce
|
||||||
|
separately to the AuthZ call based on the state they already have about request
|
||||||
|
rates etc.
|
||||||
|
|
||||||
|
#### Persistent TCP Connections and Intentions
|
||||||
|
|
||||||
|
For a proxied service configured with a [protocol] of TCP, potentially
|
||||||
|
long-lived TCP connections will be authorized only when they are established.
|
||||||
|
Since many services (e.g. databases) typically use persistent connection pools,
|
||||||
|
a change in intentions that newly denies access currently does not terminate
|
||||||
|
existing connections in violation of the updated intention. In this case it may
|
||||||
|
appear as if the intention is not being enforced.
|
||||||
|
|
||||||
|
Consul eventually may support a mechanism for tracking specific connections in
|
||||||
|
the agent and then allow the agent to tell the proxy to close those connections
|
||||||
|
when their authorization state changes, but for now that is not on the roadmap.
|
||||||
|
|
||||||
|
It is recommended therefore to do one of the following:
|
||||||
|
|
||||||
|
1. Have connections terminate after a configurable maximum lifetime of say
|
||||||
|
several hours. This balances the overhead of establishing new connections
|
||||||
|
while keeping an upper bound on how long after Intention changes existing
|
||||||
|
connections remain open.
|
||||||
|
2. Periodically re-authorize every open connection. The AuthZ call itself is
|
||||||
|
not expensive and should be a local, in-memory operation so authorizing
|
||||||
|
thousands of open connections once every minute or so is likely to be
|
||||||
|
negligible overhead, but enforces a tighter upper bound on how long it takes
|
||||||
|
to enforce Intention changes without affecting protocol efficiency of
|
||||||
|
persistent connections.
|
||||||
|
|
||||||
|
#### Certificate Serial in AuthZ
|
||||||
|
|
||||||
|
Intentions currently utilize TLS' URI Subject Alternative Name (SAN) for
|
||||||
|
enforcement. In the future, Consul will support revoking specific certificates
|
||||||
|
by serial number. The AuthZ API in the Go SDK has a field to pass the serial
|
||||||
|
number ([`consul/connect/tls.go`]). Proxies may provide this value during
|
||||||
|
authorization.
|
||||||
|
|
||||||
## Establishing Outbound Connections
|
## Establishing Outbound Connections
|
||||||
|
|
||||||
For outbound connections, the proxy should communicate to a
|
For outbound connections, the proxy should communicate to a Connect-capable
|
||||||
Connect-capable endpoint for a service and provide a client certificate
|
endpoint for a service and provide a client certificate from the
|
||||||
from the
|
[`/v1/agent/connect/ca/leaf/`] API endpoint. The certificate served by the
|
||||||
[`/v1/agent/connect/ca/leaf/`](/api/agent/connect) API endpoint.
|
remote endpoint may be verified against the root certificates from the
|
||||||
The certificate served by the remote endpoint can be verified against the
|
[`/v1/agent/connect/ca/roots`] endpoint.
|
||||||
root certificates from the
|
|
||||||
[`/v1/agent/connect/ca/roots`](/api/agent/connect) endpoint.
|
|
||||||
|
|
||||||
## Configuration Discovery
|
## Configuration Discovery
|
||||||
|
|
||||||
|
@ -59,11 +143,102 @@ instance using the
|
||||||
[`/v1/agent/service/:service_id`](/api/agent/service#get-service-configuration)
|
[`/v1/agent/service/:service_id`](/api/agent/service#get-service-configuration)
|
||||||
API endpoint.
|
API endpoint.
|
||||||
|
|
||||||
The [discovery chain](/docs/internals/discovery-chain) for each upstream
|
This endpoint supports hash-based blocking, enabling long-polling for changes
|
||||||
service should be fetched from the
|
to the registration/configuration. Any changes to the registration/config will
|
||||||
[`/v1/discovery-chain/:service_id`](/api/discovery-chain) API endpoint.
|
result in the new config being returned immediately. An example implementation
|
||||||
|
may be found in our [built-in proxy](/docs/connect/proxies/built-in) which
|
||||||
|
utilizes our Go SDK, and uses the HTTP "pull" API (via our `watch` package):
|
||||||
|
[`consul/connect/proxy/config.go`].
|
||||||
|
|
||||||
For each [target](/docs/internals/discovery-chain#targets) in the
|
The [discovery chain] for each upstream service should be fetched from the
|
||||||
resulting discovery chain, a list of healthy endpoints can be fetched from the
|
[`/v1/discovery-chain/:service_id`](/api/discovery-chain#read-compiled-discovery-chain)
|
||||||
[`/v1/health/connect/:service_id`](/api/health#list-nodes-for-connect-capable-service)
|
API endpoint. This will return a compiled graph of configurations needed by
|
||||||
API endpoint.
|
sidecars for a particular upstream service. If you are only implementing L4
|
||||||
|
support in your proxy, set the
|
||||||
|
[`OverrideProtocol`](/api/discovery-chain#overrideprotocol) value to "tcp" when
|
||||||
|
fetching the discovery chain so that L7 features such as HTTP routing rules are
|
||||||
|
not returned.
|
||||||
|
|
||||||
|
For each [target](/docs/internals/discovery-chain#targets) in the resulting
|
||||||
|
discovery chain, a list of healthy, Connect-capable endpoints may be fetched
|
||||||
|
from the [`/v1/health/connect/:service_id`] API endpoint per the [Service
|
||||||
|
Discovery](#service-discovery) section below.
|
||||||
|
|
||||||
|
The rest of the nodes in the chain include configurations that should be
|
||||||
|
translated into the nearest equivalent for things like HTTP routing, connection
|
||||||
|
timeouts, connection pool settings, rate limits, etc. See the full [discovery
|
||||||
|
chain] documentation and relevant [config entry](/docs/agent/config-entries)
|
||||||
|
documentation for details of supported configuration parameters.
|
||||||
|
|
||||||
|
We expect config here to evolve reasonably rapidly. While we do not intend to
|
||||||
|
make backwards incompatible API changes, there are likely to be new
|
||||||
|
configurations and features added regularly. Some proxies may not be able to
|
||||||
|
support all features or may have differing semantics with the way they support
|
||||||
|
them. We intend to find a suitable format to document the behavior differences
|
||||||
|
between proxy implementations as they mature.
|
||||||
|
|
||||||
|
### Service Discovery
|
||||||
|
|
||||||
|
Proxies can use Consul's service discovery API
|
||||||
|
[`/v1/health/connect/:service_id`] to return all available, Connect-capable
|
||||||
|
endpoints for a given service. This endpoint supports a `?cached` parameter
|
||||||
|
which makes use of [agent caching](/api/features/caching) and thus has
|
||||||
|
performance benefits. The API package provides a [`UseCache`] query option to
|
||||||
|
leverage this. In addition to performance improvements, use of the cache makes
|
||||||
|
the mesh more resilient to Consul server outages - the mesh "fails static" with
|
||||||
|
the last known set of service instances still used rather than errors on new
|
||||||
|
connections.
|
||||||
|
|
||||||
|
Proxies can decide whether to perform just-in-time queries to the API when a
|
||||||
|
new connection needs to be routed, or to use blocking queries to load the
|
||||||
|
current set of endpoints for a service and keep that list updated. The SDK and
|
||||||
|
built-in proxy currently use just-in-time resolution however many existing
|
||||||
|
proxies are likely to find it easier to integrate by pulling the set of
|
||||||
|
endpoints and maintaining it in local memory using blocking queries.
|
||||||
|
|
||||||
|
Upstreams can be defined with Prepared Query target types. These upstreams
|
||||||
|
should use Consul's [prepared query](/api/query) API. It's worth noting that
|
||||||
|
the PreparedQuery API does not support blocking, so proxies choosing to
|
||||||
|
populate endpoints in memory will need to poll the endpoint at a suitable and
|
||||||
|
ideally configurable frequency.
|
||||||
|
|
||||||
|
-> **Note:** Long-term the [`service-resolver` config
|
||||||
|
entries](/docs/agent/config-entries/service-resolver) are intended to replace
|
||||||
|
Prepared Queries in Consul entirely, but for now these are still used in some
|
||||||
|
configurations.
|
||||||
|
|
||||||
|
## Sidecar instantiation
|
||||||
|
|
||||||
|
Consul does not start or manage sidecar proxies processes. Proxies running on a
|
||||||
|
physical host or VM are designed to be started and run by process supervisor
|
||||||
|
systems such as init, systemd, supervisord, etc. Or, if deployed within a
|
||||||
|
cluster scheduler (Kubernetes, Nomad) running as a sidecar container in the
|
||||||
|
same namespace.
|
||||||
|
|
||||||
|
The proxy will use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and
|
||||||
|
[`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to
|
||||||
|
contact Consul to fetch certificates, provided the `CONSUL_HTTP_TOKEN`
|
||||||
|
environment variable contains a Consul ACL that has the necessary permissions
|
||||||
|
to read configuration for that service. If you use our Go [`api` package] then
|
||||||
|
those environment variables will be read and the client configured for you
|
||||||
|
automatically.
|
||||||
|
|
||||||
|
The ID of the proxy service comes from the user. See [`consul connect
|
||||||
|
envoy`](/commands/connect/envoy) as an example. You may start it with the
|
||||||
|
`-proxy-id` flag and pass the ID of the proxy service you registered elsewhere.
|
||||||
|
A nicer UX is available for end-users using the `-sidecar-for=<service>`
|
||||||
|
argument, which causes the command to query Consul for a proxy that is
|
||||||
|
registered as a sidecar for the specified `<service>`. If there is exactly one
|
||||||
|
such proxy, that ID will be used to start the proxy. Your controller only needs
|
||||||
|
to accept `-proxy-id` as an argument; the Consul CLI will handle resolving the
|
||||||
|
ID for the name specified in `-sidecar-for`.
|
||||||
|
|
||||||
|
[`/v1/agent/connect/ca/leaf/`]: /api/agent/connect#service-leaf-certificate
|
||||||
|
[`/v1/agent/connect/ca/roots`]: /api/agent/connect#certificate-authority-ca-roots
|
||||||
|
[`/v1/health/connect/:service_id`]: /api/health#list-nodes-for-connect-capable-service
|
||||||
|
[`api` package]: https://github.com/hashicorp/consul/tree/master/api
|
||||||
|
[`consul/connect/proxy/config.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/proxy/config.go#L187
|
||||||
|
[`consul/connect/tls.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/tls.go#L232-L237
|
||||||
|
[discovery chain]: /docs/connect/l7-traffic/discovery-chain
|
||||||
|
[`UseCache`]: https://github.com/hashicorp/consul/blob/v1.8.3/api/api.go#L99-L102
|
||||||
|
[protocol]: /docs/agent/config-entries/service-defaults#protocol
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
layout: docs
|
layout: docs
|
||||||
page_title: Connect - Deprecated Managed Proxies
|
page_title: Connect - Deprecated Managed Proxies
|
||||||
description: |-
|
description: |-
|
||||||
Consul 1.2 launched it's Connect Beta period with a feature named Managed
|
Consul 1.2 launched its Connect Beta period with a feature named Managed
|
||||||
Proxies which are now deprecated. This page describes how they worked and why
|
Proxies which are now deprecated. This page describes how they worked and why
|
||||||
they are no longer supported.
|
they are no longer supported.
|
||||||
---
|
---
|
||||||
|
@ -89,7 +89,7 @@ from the agent so if the agent crashes or is restarted for an upgrade, the
|
||||||
managed proxy instances will _not_ be stopped.
|
managed proxy instances will _not_ be stopped.
|
||||||
|
|
||||||
Note that this behaviour while desirable in production might leave proxy
|
Note that this behaviour while desirable in production might leave proxy
|
||||||
processes running indefinitely if you manually stop the agent and clear it's
|
processes running indefinitely if you manually stop the agent and clear its
|
||||||
data dir during testing.
|
data dir during testing.
|
||||||
|
|
||||||
To terminate a managed proxy cleanly you need to deregister the service that
|
To terminate a managed proxy cleanly you need to deregister the service that
|
||||||
|
@ -269,7 +269,7 @@ Managed proxies have both stdout and stderr captured in log files in the agent's
|
||||||
`data_dir`. They can be found in
|
`data_dir`. They can be found in
|
||||||
`<data_dir>/proxy/logs/<proxy_service_id>-std{err,out}.log`.
|
`<data_dir>/proxy/logs/<proxy_service_id>-std{err,out}.log`.
|
||||||
|
|
||||||
The built-in proxy will inherit it's log level from the agent so if the agent is
|
The built-in proxy will inherit its log level from the agent so if the agent is
|
||||||
configured with `log_level = DEBUG`, a proxy it starts will also output `DEBUG`
|
configured with `log_level = DEBUG`, a proxy it starts will also output `DEBUG`
|
||||||
level logs showing service discovery, certificate and authorization information.
|
level logs showing service discovery, certificate and authorization information.
|
||||||
|
|
||||||
|
|
|
@ -180,7 +180,7 @@ service's ID. This enables the following behavior.
|
||||||
- If a service registration removes the nested `sidecar_service` then the
|
- If a service registration removes the nested `sidecar_service` then the
|
||||||
previously registered sidecar for that service will be deregistered
|
previously registered sidecar for that service will be deregistered
|
||||||
automatically.
|
automatically.
|
||||||
- When reloading the configuration files, if a service definition changes it's
|
- When reloading the configuration files, if a service definition changes its
|
||||||
ID, then a new service instance _and_ a new sidecar instance will be
|
ID, then a new service instance _and_ a new sidecar instance will be
|
||||||
registered. The old ones will be removed since they are no longer found in
|
registered. The old ones will be removed since they are no longer found in
|
||||||
the config files.
|
the config files.
|
||||||
|
|
|
@ -369,7 +369,7 @@ delimit service tags.
|
||||||
## Service Definition Parameter Case
|
## Service Definition Parameter Case
|
||||||
|
|
||||||
For historical reasons Consul's API uses `CamelCased` parameter names in
|
For historical reasons Consul's API uses `CamelCased` parameter names in
|
||||||
responses, however it's configuration file uses `snake_case` for both HCL and
|
responses, however its configuration file uses `snake_case` for both HCL and
|
||||||
JSON representations. For this reason the registration _HTTP APIs_ accept both
|
JSON representations. For this reason the registration _HTTP APIs_ accept both
|
||||||
name styles for service definition parameters although APIs will return the
|
name styles for service definition parameters although APIs will return the
|
||||||
listings using `CamelCase`.
|
listings using `CamelCase`.
|
||||||
|
|
|
@ -29,7 +29,7 @@ Learn.
|
||||||
## Accessing the KV store
|
## Accessing the KV store
|
||||||
|
|
||||||
The KV store can be accessed by the [consul kv CLI
|
The KV store can be accessed by the [consul kv CLI
|
||||||
subcommands](/docs/commands/kv), [HTTP API](/api/kv), and Consul UI.
|
subcommands](/commands/kv), [HTTP API](/api/kv), and Consul UI.
|
||||||
To restrict access, enable and configure
|
To restrict access, enable and configure
|
||||||
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
||||||
Once the ACL system has been bootstrapped, users and services, will need a
|
Once the ACL system has been bootstrapped, users and services, will need a
|
||||||
|
@ -41,7 +41,7 @@ application.
|
||||||
|
|
||||||
The datastore itself is located on the Consul servers in the [data
|
The datastore itself is located on the Consul servers in the [data
|
||||||
directory](/docs/agent/options#_data_dir). To ensure data is not lost in
|
directory](/docs/agent/options#_data_dir). To ensure data is not lost in
|
||||||
the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore) feature to backup the data.
|
the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data.
|
||||||
|
|
||||||
## Using Consul KV
|
## Using Consul KV
|
||||||
|
|
||||||
|
|
|
@ -25,7 +25,7 @@ Watches can be configured as part of the [agent's configuration](/docs/agent/opt
|
||||||
causing them to run once the agent is initialized. Reloading the agent configuration
|
causing them to run once the agent is initialized. Reloading the agent configuration
|
||||||
allows for adding or removing watches dynamically.
|
allows for adding or removing watches dynamically.
|
||||||
|
|
||||||
Alternatively, the [watch command](/docs/commands/watch) enables a watch to be
|
Alternatively, the [watch command](/commands/watch) enables a watch to be
|
||||||
started outside of the agent. This can be used by an operator to inspect data in Consul
|
started outside of the agent. This can be used by an operator to inspect data in Consul
|
||||||
or to easily pipe data into processes without being tied to the agent lifecycle.
|
or to easily pipe data into processes without being tied to the agent lifecycle.
|
||||||
|
|
||||||
|
@ -422,7 +422,7 @@ An example of the output of this command:
|
||||||
### Type: event ((#event))
|
### Type: event ((#event))
|
||||||
|
|
||||||
The "event" watch type is used to monitor for custom user
|
The "event" watch type is used to monitor for custom user
|
||||||
events. These are fired using the [consul event](/docs/commands/event) command.
|
events. These are fired using the [consul event](/commands/event) command.
|
||||||
It takes only a single optional "name" parameter which restricts
|
It takes only a single optional "name" parameter which restricts
|
||||||
the watch to only events with the given name.
|
the watch to only events with the given name.
|
||||||
|
|
||||||
|
|
|
@ -36,4 +36,4 @@ datacenter backups include (but are not limited to):
|
||||||
For more experience leveraging Consul's snapshot functionality, we suggest you look through our HashiCorp
|
For more experience leveraging Consul's snapshot functionality, we suggest you look through our HashiCorp
|
||||||
Learn tutorial for [Datacenter Backups in Consul](https://learn.hashicorp.com/tutorials/consul/backup-and-restore).
|
Learn tutorial for [Datacenter Backups in Consul](https://learn.hashicorp.com/tutorials/consul/backup-and-restore).
|
||||||
For detailed configuration information on configuring the Consul Enterprise's snapshot agent, review the
|
For detailed configuration information on configuring the Consul Enterprise's snapshot agent, review the
|
||||||
[Consul Snapshot Agent documentation](/docs/commands/snapshot/agent).
|
[Consul Snapshot Agent documentation](/commands/snapshot/agent).
|
||||||
|
|
|
@ -54,7 +54,7 @@ forwarded to the leading server via the RPC forwarding functionality.
|
||||||
Below are your two options for setting the license file.
|
Below are your two options for setting the license file.
|
||||||
|
|
||||||
You can set the license via the
|
You can set the license via the
|
||||||
[API](/api/operator/license) or the [CLI](/docs/commands/license). When
|
[API](/api/operator/license) or the [CLI](/commands/license). When
|
||||||
you first start Consul, a 30-minute temporary license is available to allow you
|
you first start Consul, a 30-minute temporary license is available to allow you
|
||||||
time to license the datacenter. You should set the license within ten minutes of
|
time to license the datacenter. You should set the license within ten minutes of
|
||||||
starting the first Consul process to allow time for the license to propagate.
|
starting the first Consul process to allow time for the license to propagate.
|
||||||
|
|
|
@ -25,7 +25,7 @@ For more information on how to use namespaces with Consul Enterprise please revi
|
||||||
|
|
||||||
## Namespace Definition
|
## Namespace Definition
|
||||||
|
|
||||||
Namespaces are managed exclusively through the [HTTP API](/api/namespaces) and the [Consul CLI](/docs/commands/namespace).
|
Namespaces are managed exclusively through the [HTTP API](/api/namespaces) and the [Consul CLI](/commands/namespace).
|
||||||
The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
|
The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
|
||||||
|
|
||||||
An example namespace definition looks like the following:
|
An example namespace definition looks like the following:
|
||||||
|
|
|
@ -17,7 +17,7 @@ description: |-
|
||||||
|
|
||||||
Consul Network Segments enables operators to create separate LAN gossip segments
|
Consul Network Segments enables operators to create separate LAN gossip segments
|
||||||
in one Consul cluster. Agents in a segment are only able to join and communicate
|
in one Consul cluster. Agents in a segment are only able to join and communicate
|
||||||
with other agents in it's network segment. This functionality is useful for
|
with other agents in its network segment. This functionality is useful for
|
||||||
clusters that have multiple tenants that should not be able to communicate
|
clusters that have multiple tenants that should not be able to communicate
|
||||||
with each other.
|
with each other.
|
||||||
|
|
||||||
|
|
|
@ -31,4 +31,4 @@ capabilities.
|
||||||
|
|
||||||
For more information, review the HashiCorp Learn tutorial on
|
For more information, review the HashiCorp Learn tutorial on
|
||||||
[Redundancy Zones](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#redundancy-zones),
|
[Redundancy Zones](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#redundancy-zones),
|
||||||
as well as the documentation for [Consul Autopilot](/docs/commands/operator/autopilot).
|
as well as the documentation for [Consul Autopilot](/commands/operator/autopilot).
|
||||||
|
|
|
@ -21,4 +21,4 @@ currently in a cluster. When an equal amount of new server nodes are joined runn
|
||||||
will be demoted to non voting members. Demotion of legacy server nodes will not occur until the voting members on the new version match.
|
will be demoted to non voting members. Demotion of legacy server nodes will not occur until the voting members on the new version match.
|
||||||
Once this demotion occurs, the previous versioned servers can be removed from the cluster safely.
|
Once this demotion occurs, the previous versioned servers can be removed from the cluster safely.
|
||||||
|
|
||||||
You can review more information about this functionality in the [Consul operator autopilot](/docs/commands/operator/autopilot) documentation as well as on the HashiCorp Learn [Automated Upgrade](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#upgrade-migrations) tutorial.
|
You can review more information about this functionality in the [Consul operator autopilot](/commands/operator/autopilot) documentation as well as on the HashiCorp Learn [Automated Upgrade](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#upgrade-migrations) tutorial.
|
||||||
|
|
|
@ -230,7 +230,7 @@ The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token
|
||||||
|
|
||||||
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
||||||
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
||||||
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
|
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
|
||||||
|
|
||||||
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
||||||
|
|
||||||
|
@ -738,7 +738,7 @@ Event rules are keyed by the event name prefix they apply to, using the longest
|
||||||
In the example above, the rules allow read-only access to any event, and firing of any event that
|
In the example above, the rules allow read-only access to any event, and firing of any event that
|
||||||
starts with "deploy".
|
starts with "deploy".
|
||||||
|
|
||||||
The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
|
The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
|
||||||
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
||||||
give agents a token with access to this event prefix, in addition to configuring
|
give agents a token with access to this event prefix, in addition to configuring
|
||||||
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
||||||
|
|
|
@ -112,7 +112,7 @@ restart during
|
||||||
upgrades](/docs/upgrading#standard-upgrades).
|
upgrades](/docs/upgrading#standard-upgrades).
|
||||||
|
|
||||||
Stop the first server by running the following [leave
|
Stop the first server by running the following [leave
|
||||||
command](/docs/commands/leave).
|
command](/commands/leave).
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ consul leave
|
$ consul leave
|
||||||
|
@ -234,7 +234,7 @@ $ consul connect envoy -mesh-gateway -register \
|
||||||
### Configure Sidecar Proxies to use Gateways
|
### Configure Sidecar Proxies to use Gateways
|
||||||
|
|
||||||
Next, create a [centralized
|
Next, create a [centralized
|
||||||
configuration](/docs/agent/config_entries/proxy-defaults)
|
configuration](/docs/agent/config-entries/proxy-defaults)
|
||||||
file for all the sidecar proxies in both datacenters called
|
file for all the sidecar proxies in both datacenters called
|
||||||
`proxy-defaults.json`. This file will instruct the sidecar proxies to send all
|
`proxy-defaults.json`. This file will instruct the sidecar proxies to send all
|
||||||
their inter-datacenter traffic through the gateways. It should contain the
|
their inter-datacenter traffic through the gateways. It should contain the
|
||||||
|
|
|
@ -434,7 +434,7 @@ environment.
|
||||||
[img-screenshot2]: /static/img/consul/connect-getting-started/screenshot2.png
|
[img-screenshot2]: /static/img/consul/connect-getting-started/screenshot2.png
|
||||||
[intention]: https://www.consul.io/docs/connect/intentions
|
[intention]: https://www.consul.io/docs/connect/intentions
|
||||||
[services-api]: https://www.consul.io/api/agent/service#register-service
|
[services-api]: https://www.consul.io/api/agent/service#register-service
|
||||||
[services-cli]: https://www.consul.io/docs/commands/services
|
[services-cli]: https://www.consul.io/commands/services
|
||||||
[services-config]: https://www.consul.io/docs/agent/services#service-definition
|
[services-config]: https://www.consul.io/docs/agent/services#service-definition
|
||||||
[services-nomad]: https://www.nomadproject.io/docs/job-specification/service
|
[services-nomad]: https://www.nomadproject.io/docs/job-specification/service
|
||||||
[sidecar]: https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar
|
[sidecar]: https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar
|
||||||
|
|
|
@ -278,7 +278,7 @@ When a previously stopped server container is restarted using `docker start <con
|
||||||
|
|
||||||
### Backing-up Data
|
### Backing-up Data
|
||||||
|
|
||||||
You can back-up your Consul datacenter using the [consul snapshot](/docs/commands/snapshot) command.
|
You can back-up your Consul datacenter using the [consul snapshot](/commands/snapshot) command.
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ docker exec <container_id> consul snapshot save backup.snap
|
$ docker exec <container_id> consul snapshot save backup.snap
|
||||||
|
@ -290,7 +290,7 @@ This will leave the `backup.snap` snapshot file inside of your container. If you
|
||||||
$ docker cp <container_id>:backup.snap ./
|
$ docker cp <container_id>:backup.snap ./
|
||||||
```
|
```
|
||||||
|
|
||||||
Users running the Consul Enterprise Docker containers can run the [consul snapshot agent](/docs/commands/snapshot/agent) to save backups automatically. Consul Enterprise's snapshot agent also allows you to save snapshots to Amazon S3 and Azure Blob Storage.
|
Users running the Consul Enterprise Docker containers can run the [consul snapshot agent](/commands/snapshot/agent) to save backups automatically. Consul Enterprise's snapshot agent also allows you to save snapshots to Amazon S3 and Azure Blob Storage.
|
||||||
|
|
||||||
### Environment Variables
|
### Environment Variables
|
||||||
|
|
||||||
|
|
|
@ -366,4 +366,4 @@ To learn more about the configuration options in Consul that enable layer 7
|
||||||
metrics collection with or without Kubernetes, refer to [our
|
metrics collection with or without Kubernetes, refer to [our
|
||||||
documentation](/docs/connect/proxies/envoy). For more information on
|
documentation](/docs/connect/proxies/envoy). For more information on
|
||||||
centrally configuring Consul, take a look at the [centralized configuration
|
centrally configuring Consul, take a look at the [centralized configuration
|
||||||
documentation](/docs/agent/config_entries).
|
documentation](/docs/agent/config-entries).
|
||||||
|
|
|
@ -222,7 +222,7 @@ the clients.
|
||||||
|
|
||||||
First, create the policy that will grant write privileges to only the
|
First, create the policy that will grant write privileges to only the
|
||||||
"dashboard" service. This means the "dashboard" service can register
|
"dashboard" service. This means the "dashboard" service can register
|
||||||
itself, update it's health checks, and write any of the fields in the [service
|
itself, update its health checks, and write any of the fields in the [service
|
||||||
definition](/docs/agent/services).
|
definition](/docs/agent/services).
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
|
@ -448,4 +448,4 @@ node_prefix "" {
|
||||||
|
|
||||||
In this guide you bootstrapped the ACL system for consul and applied tokens to agents and services. You assigned tokens for DNS, Consul KV, and the Consul UI.
|
In this guide you bootstrapped the ACL system for consul and applied tokens to agents and services. You assigned tokens for DNS, Consul KV, and the Consul UI.
|
||||||
|
|
||||||
To learn more about Consul’s security model read the [internals documentation](/docs/internals/security). You can find commands relating to ACLs in our [reference documentation](/docs/commands/acl).
|
To learn more about Consul’s security model read the [internals documentation](/docs/internals/security). You can find commands relating to ACLs in our [reference documentation](/commands/acl).
|
||||||
|
|
|
@ -93,10 +93,10 @@ Since a join operation is symmetric, it does not matter which node initiates it.
|
||||||
|
|
||||||
### Verifying the Cluster and Connect the Clients
|
### Verifying the Cluster and Connect the Clients
|
||||||
|
|
||||||
As a sanity check, the [`consul info`](/docs/commands/info) command
|
As a sanity check, the [`consul info`](/commands/info) command
|
||||||
is a useful tool. It can be used to verify the `raft.num_peers`
|
is a useful tool. It can be used to verify the `raft.num_peers`
|
||||||
and to view the latest log index under `raft.last_log_index`. When
|
and to view the latest log index under `raft.last_log_index`. When
|
||||||
running [`consul info`](/docs/commands/info) on the followers, you
|
running [`consul info`](/commands/info) on the followers, you
|
||||||
should see `raft.last_log_index` converge to the same value once the
|
should see `raft.last_log_index` converge to the same value once the
|
||||||
leader begins replication. That value represents the last log entry that
|
leader begins replication. That value represents the last log entry that
|
||||||
has been stored on disk.
|
has been stored on disk.
|
||||||
|
|
|
@ -103,7 +103,7 @@ $ consul agent -retry-join "provider=azure tag_key=... tag_value=... tenant_id=.
|
||||||
- `provider` (required) - the name of the provider ("azure" in this case).
|
- `provider` (required) - the name of the provider ("azure" in this case).
|
||||||
- `tenant_id` (required) - the tenant to join machines in.
|
- `tenant_id` (required) - the tenant to join machines in.
|
||||||
- `client_id` (required) - the client to authenticate with.
|
- `client_id` (required) - the client to authenticate with.
|
||||||
- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in it's value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='`
|
- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in its value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='`
|
||||||
|
|
||||||
Variables can also be provided by environmental variables:
|
Variables can also be provided by environmental variables:
|
||||||
|
|
||||||
|
|
|
@ -58,7 +58,7 @@ Here are links to resources, documentation, examples and best practices to guide
|
||||||
**Firewall**
|
**Firewall**
|
||||||
|
|
||||||
- [Consul Connect Intentions](/docs/connect/intentions)
|
- [Consul Connect Intentions](/docs/connect/intentions)
|
||||||
- [Consul Connect Intentions Command Line](/docs/commands/intention)
|
- [Consul Connect Intentions Command Line](/commands/intention)
|
||||||
- [Consul Connect Intentions API](/api/connect/intentions)
|
- [Consul Connect Intentions API](/api/connect/intentions)
|
||||||
|
|
||||||
**API Gateway**
|
**API Gateway**
|
||||||
|
@ -92,7 +92,7 @@ Here are links to resources, documentation, examples and best practices to guide
|
||||||
|
|
||||||
**Logging**
|
**Logging**
|
||||||
|
|
||||||
- [Consul Monitor Command Line](/docs/commands/monitor)
|
- [Consul Monitor Command Line](/commands/monitor)
|
||||||
- [Enable syslog via CLI](/docs/agent/options#enable_syslog)
|
- [Enable syslog via CLI](/docs/agent/options#enable_syslog)
|
||||||
- [Enable syslog via config file](/docs/agent/options#_syslog)
|
- [Enable syslog via config file](/docs/agent/options#_syslog)
|
||||||
|
|
||||||
|
|
|
@ -290,6 +290,6 @@ If you have tried the above troubleshooting steps and are still stuck, DataWire
|
||||||
[install]: https://www.getambassador.io/user-guide/consul-connect-ambassador/
|
[install]: https://www.getambassador.io/user-guide/consul-connect-ambassador/
|
||||||
[ambassador-service.yaml]: https://www.getambassador.io/yaml/ambassador/ambassador-service.yaml
|
[ambassador-service.yaml]: https://www.getambassador.io/yaml/ambassador/ambassador-service.yaml
|
||||||
[request access]: https://d6e.co/slack
|
[request access]: https://d6e.co/slack
|
||||||
[intention-check]: /docs/commands/intention/check
|
[intention-check]: /commands/intention/check
|
||||||
[install consul]: /docs/install
|
[install consul]: /docs/install
|
||||||
[enable connect]: /docs/connect#getting-started-with-connect
|
[enable connect]: /docs/connect#getting-started-with-connect
|
||||||
|
|
|
@ -177,7 +177,7 @@ then you will need to manually renew or rotate the Vault token before it expires
|
||||||
|
|
||||||
Once the cluster is running, subsequent changes to the `ca_provider` config are **ignored**–even if `consul reload` is run or the servers are restarted.
|
Once the cluster is running, subsequent changes to the `ca_provider` config are **ignored**–even if `consul reload` is run or the servers are restarted.
|
||||||
|
|
||||||
To update any settings under this key, you must use Consul's [Update CA Configuration](/api/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](https://www.consul.io/docs/commands/connect/ca#set-config) command.
|
To update any settings under this key, you must use Consul's [Update CA Configuration](/api/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](/commands/connect/ca#set-config) command.
|
||||||
|
|
||||||
#### Renewing Vault Token
|
#### Renewing Vault Token
|
||||||
|
|
||||||
|
|
|
@ -161,7 +161,7 @@ $ kubectl exec static-client -- curl -s http://127.0.0.1:1234/
|
||||||
```
|
```
|
||||||
|
|
||||||
We can control access to the server using [intentions](/docs/connect/intentions).
|
We can control access to the server using [intentions](/docs/connect/intentions).
|
||||||
If you use the Consul UI or [CLI](/docs/commands/intention/create) to
|
If you use the Consul UI or [CLI](/commands/intention/create) to
|
||||||
create a deny [intention](/docs/connect/intentions) between
|
create a deny [intention](/docs/connect/intentions) between
|
||||||
"static-client" and "static-server", connections are immediately rejected
|
"static-client" and "static-server", connections are immediately rejected
|
||||||
without updating either of the running pods. You can then remove this
|
without updating either of the running pods. You can then remove this
|
||||||
|
@ -249,7 +249,7 @@ Annotations can be used to configure the injection behavior.
|
||||||
```
|
```
|
||||||
|
|
||||||
- `consul.hashicorp.com/connect-service-protocol` - For pods that will be
|
- `consul.hashicorp.com/connect-service-protocol` - For pods that will be
|
||||||
registered with Consul's [central configuration](/docs/agent/config_entries)
|
registered with Consul's [central configuration](/docs/agent/config-entries)
|
||||||
feature, information about the protocol the service uses is required. Users
|
feature, information about the protocol the service uses is required. Users
|
||||||
can define the protocol directly using this annotation on the pod spec, or by
|
can define the protocol directly using this annotation on the pod spec, or by
|
||||||
defining a default value for all services using the Helm chart's
|
defining a default value for all services using the Helm chart's
|
||||||
|
|
|
@ -541,7 +541,7 @@ and consider if they're appropriate for your deployment.
|
||||||
type: RollingUpdate
|
type: RollingUpdate
|
||||||
```
|
```
|
||||||
|
|
||||||
- `snapshotAgent` ((#v-client-snapshotagent)) <EnterpriseAlert inline /> - Values for setting up and running [snapshot agents](/docs/commands/snapshot/agent)
|
- `snapshotAgent` ((#v-client-snapshotagent)) <EnterpriseAlert inline /> - Values for setting up and running [snapshot agents](/commands/snapshot/agent)
|
||||||
within the Consul clusters. They are required to be co-located with Consul clients,
|
within the Consul clusters. They are required to be co-located with Consul clients,
|
||||||
so will inherit the clients' nodeSelector, tolerations and affinity.
|
so will inherit the clients' nodeSelector, tolerations and affinity.
|
||||||
|
|
||||||
|
@ -552,7 +552,7 @@ and consider if they're appropriate for your deployment.
|
||||||
to run.
|
to run.
|
||||||
|
|
||||||
- `configSecret` ((#v-client-snapshotagent-configsecret)) - A Kubernetes secret that should be
|
- `configSecret` ((#v-client-snapshotagent-configsecret)) - A Kubernetes secret that should be
|
||||||
manually created to contain the entire config to be used on the snapshot agent. This is the preferred method of configuration since there are usually storage credentials present. Please see [Snapshot agent config](/docs/commands/snapshot/agent#config-file-options) for details.
|
manually created to contain the entire config to be used on the snapshot agent. This is the preferred method of configuration since there are usually storage credentials present. Please see [Snapshot agent config](/commands/snapshot/agent#config-file-options) for details.
|
||||||
|
|
||||||
- secretName ((#v-client-snapshotagent-configsecret-secretname)) `(string: null)` - The name of the Kubernetes secret.
|
- secretName ((#v-client-snapshotagent-configsecret-secretname)) `(string: null)` - The name of the Kubernetes secret.
|
||||||
|
|
||||||
|
@ -828,7 +828,7 @@ and consider if they're appropriate for your deployment.
|
||||||
|
|
||||||
- `secretKey` ((#v-connectinject-aclinjecttoken-secretkey)) `(string: null)` - The key within the Kubernetes secret that holds the acl token.
|
- `secretKey` ((#v-connectinject-aclinjecttoken-secretkey)) `(string: null)` - The key within the Kubernetes secret that holds the acl token.
|
||||||
|
|
||||||
- `centralConfig` ((#v-connectinject-centralconfig)) - Values that configure Consul's [central configuration](/docs/agent/config_entries)
|
- `centralConfig` ((#v-connectinject-centralconfig)) - Values that configure Consul's [central configuration](/docs/agent/config-entries)
|
||||||
feature (requires Consul v1.5+ and consul-k8s v0.8.1+).
|
feature (requires Consul v1.5+ and consul-k8s v0.8.1+).
|
||||||
|
|
||||||
- `enabled` ((#v-connectinject-centralconfig-enabled)) (`boolean: true`) - Turns on the central
|
- `enabled` ((#v-connectinject-centralconfig-enabled)) (`boolean: true`) - Turns on the central
|
||||||
|
|
|
@ -11,7 +11,7 @@ description: >-
|
||||||
|
|
||||||
# ACL System in Legacy Mode
|
# ACL System in Legacy Mode
|
||||||
|
|
||||||
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system)
|
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system).
|
||||||
|
|
||||||
~> **Alert: Deprecation Notice**
|
~> **Alert: Deprecation Notice**
|
||||||
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
|
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
|
||||||
|
@ -242,7 +242,7 @@ The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token
|
||||||
|
|
||||||
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
||||||
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
||||||
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
|
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
|
||||||
|
|
||||||
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
||||||
|
|
||||||
|
@ -750,7 +750,7 @@ Event rules are keyed by the event name prefix they apply to, using the longest
|
||||||
In the example above, the rules allow read-only access to any event, and firing of any event that
|
In the example above, the rules allow read-only access to any event, and firing of any event that
|
||||||
starts with "deploy".
|
starts with "deploy".
|
||||||
|
|
||||||
The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
|
The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
|
||||||
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
||||||
give agents a token with access to this event prefix, in addition to configuring
|
give agents a token with access to this event prefix, in addition to configuring
|
||||||
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
||||||
|
|
|
@ -84,7 +84,7 @@ have.
|
||||||
The simplest and most automatic strategy is to create one new policy for every
|
The simplest and most automatic strategy is to create one new policy for every
|
||||||
existing token. This is easy to automate, but may result in a lot of policies
|
existing token. This is easy to automate, but may result in a lot of policies
|
||||||
with exactly the same rules and with non-human-readable names which will make
|
with exactly the same rules and with non-human-readable names which will make
|
||||||
managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create) command with
|
managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/commands/acl/policy/create) command with
|
||||||
`-from-token` option.
|
`-from-token` option.
|
||||||
|
|
||||||
| Pros | Cons |
|
| Pros | Cons |
|
||||||
|
@ -113,7 +113,7 @@ semantics of the old ACL system.
|
||||||
|
|
||||||
To assist with this approach, there is a CLI tool and corresponding API that can
|
To assist with this approach, there is a CLI tool and corresponding API that can
|
||||||
translate a legacy ACL token's rules into a new ACL policy that is exactly
|
translate a legacy ACL token's rules into a new ACL policy that is exactly
|
||||||
equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules).
|
equivalent. See [`consul acl translate-rules`](/commands/acl/translate-rules).
|
||||||
|
|
||||||
| Pros | Cons |
|
| Pros | Cons |
|
||||||
| ------------------------------------------------- | ------------------------------------------------------------------ |
|
| ------------------------------------------------- | ------------------------------------------------------------------ |
|
||||||
|
@ -129,7 +129,7 @@ needed for a legacy token, you can update the token via the CLI or API to use
|
||||||
those policies.
|
those policies.
|
||||||
|
|
||||||
After updating, the token is no longer considered "legacy" and will have all the
|
After updating, the token is no longer considered "legacy" and will have all the
|
||||||
properties of a new token, however it keeps it's `SecretID` (the secret part of
|
properties of a new token, however it keeps its `SecretID` (the secret part of
|
||||||
the token used in API calls) so clients already using that token will continue
|
the token used in API calls) so clients already using that token will continue
|
||||||
to work. It is assumed that the policies you attach continue to grant the
|
to work. It is assumed that the policies you attach continue to grant the
|
||||||
necessary access for existing clients; this is up to the operator to ensure.
|
necessary access for existing clients; this is up to the operator to ensure.
|
||||||
|
@ -142,7 +142,7 @@ endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty
|
||||||
|
|
||||||
#### Update via CLI
|
#### Update via CLI
|
||||||
|
|
||||||
Use the [`consul acl token update`](/docs/commands/acl/token/update)
|
Use the [`consul acl token update`](/commands/acl/token/update)
|
||||||
command to update the token. Specifically you need to use `-upgrade-legacy`
|
command to update the token. Specifically you need to use `-upgrade-legacy`
|
||||||
which will ensure that legacy rules are removed as well as the new policies
|
which will ensure that legacy rules are removed as well as the new policies
|
||||||
added.
|
added.
|
||||||
|
|
|
@ -11,7 +11,7 @@ description: >-
|
||||||
|
|
||||||
# ACL Rules
|
# ACL Rules
|
||||||
|
|
||||||
-> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
|
-> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy).
|
||||||
|
|
||||||
Consul provides an optional Access Control List (ACL) system which can be used
|
Consul provides an optional Access Control List (ACL) system which can be used
|
||||||
to control access to data and APIs. To learn more about Consul's ACL review the
|
to control access to data and APIs. To learn more about Consul's ACL review the
|
||||||
|
@ -214,7 +214,7 @@ event "deploy" {
|
||||||
Event rules are segmented by the event name they apply to. In the example above, the rules allow
|
Event rules are segmented by the event name they apply to. In the example above, the rules allow
|
||||||
read-only access to any event, and firing of the "deploy" event.
|
read-only access to any event, and firing of the "deploy" event.
|
||||||
|
|
||||||
The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
|
The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during
|
||||||
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
||||||
give agents a token with access to this event prefix, in addition to configuring
|
give agents a token with access to this event prefix, in addition to configuring
|
||||||
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
|
||||||
|
|
|
@ -11,7 +11,7 @@ description: >-
|
||||||
|
|
||||||
# ACL System
|
# ACL System
|
||||||
|
|
||||||
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
|
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy).
|
||||||
|
|
||||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
|
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
|
||||||
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
|
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
|
||||||
|
@ -58,7 +58,7 @@ may benefit from additional components in the ACL system:
|
||||||
|
|
||||||
ACL tokens, policies, roles, auth methods, and binding rules are managed by
|
ACL tokens, policies, roles, auth methods, and binding rules are managed by
|
||||||
Consul operators via Consul's [ACL API](/api/acl/acl),
|
Consul operators via Consul's [ACL API](/api/acl/acl),
|
||||||
[ACL CLI](/docs/commands/acl), or systems like
|
[ACL CLI](/commands/acl), or systems like
|
||||||
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
|
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
|
||||||
|
|
||||||
If the ACL system becomes inoperable, you can follow the
|
If the ACL system becomes inoperable, you can follow the
|
||||||
|
@ -316,7 +316,7 @@ The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special toke
|
||||||
|
|
||||||
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
|
||||||
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
|
||||||
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
|
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands
|
||||||
|
|
||||||
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
|
||||||
|
|
||||||
|
|
|
@ -119,7 +119,7 @@ applied.
|
||||||
## OIDC Authentication
|
## OIDC Authentication
|
||||||
|
|
||||||
Consul includes two built-in OIDC login flows: the Consul UI, and the CLI using
|
Consul includes two built-in OIDC login flows: the Consul UI, and the CLI using
|
||||||
[`consul login`](/docs/commands/login).
|
[`consul login`](/commands/login).
|
||||||
|
|
||||||
### Redirect URIs
|
### Redirect URIs
|
||||||
|
|
||||||
|
@ -172,7 +172,7 @@ These are typically not required to be set:
|
||||||
|
|
||||||
The callback listener defaults to listen on `localhost:8550`. If you want to
|
The callback listener defaults to listen on `localhost:8550`. If you want to
|
||||||
customize that use the optional flag
|
customize that use the optional flag
|
||||||
[`-oidc-callback-listen-addr=<host:port>`](/docs/commands/login#oidc-callback-listen-addr).
|
[`-oidc-callback-listen-addr=<host:port>`](/commands/login#oidc-callback-listen-addr).
|
||||||
|
|
||||||
## OIDC Configuration Troubleshooting
|
## OIDC Configuration Troubleshooting
|
||||||
|
|
||||||
|
|
|
@ -26,7 +26,7 @@ starting the Consul agent. The key can be set via the `encrypt` parameter.
|
||||||
~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters.
|
~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters.
|
||||||
|
|
||||||
The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the
|
The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the
|
||||||
[`consul keygen`](/docs/commands/keygen) command to generate a
|
[`consul keygen`](/commands/keygen) command to generate a
|
||||||
cryptographically suitable key:
|
cryptographically suitable key:
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
|
@ -35,7 +35,7 @@ pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
|
||||||
```
|
```
|
||||||
|
|
||||||
With that key, you can enable encryption on the agent. If encryption is enabled,
|
With that key, you can enable encryption on the agent. If encryption is enabled,
|
||||||
the output of [`consul agent`](/docs/commands/agent) will include "Encrypt: true":
|
the output of [`consul agent`](/commands/agent) will include "Encrypt: true":
|
||||||
|
|
||||||
```shell-session
|
```shell-session
|
||||||
$ cat encrypt.json
|
$ cat encrypt.json
|
||||||
|
|
|
@ -91,7 +91,7 @@ non-default options that potentially present additional security risks.
|
||||||
1.1.1, and 1.2.4 [as described here](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations).
|
1.1.1, and 1.2.4 [as described here](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations).
|
||||||
|
|
||||||
- **Remote exec enabled.** Consul includes a [`consul exec`
|
- **Remote exec enabled.** Consul includes a [`consul exec`
|
||||||
feature](/docs/commands/exec) allowing execution of arbitrary commands
|
feature](/commands/exec) allowing execution of arbitrary commands
|
||||||
across the cluster. This is disabled by default since 0.8.0. We recommend
|
across the cluster. This is disabled by default since 0.8.0. We recommend
|
||||||
leaving it disabled. If enabled, extreme care must be taken to ensure correct
|
leaving it disabled. If enabled, extreme care must be taken to ensure correct
|
||||||
ACLs restrict access, for example any management token grants access to
|
ACLs restrict access, for example any management token grants access to
|
||||||
|
|
|
@ -150,7 +150,7 @@ You have installed an Enterprise version of Consul. If you are an Enterprise cus
|
||||||
[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting
|
[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting
|
||||||
[node_name]: /docs/agent/options#node_name
|
[node_name]: /docs/agent/options#node_name
|
||||||
[retry_join]: /docs/agent/options#retry-join
|
[retry_join]: /docs/agent/options#retry-join
|
||||||
[license]: /docs/commands/license
|
[license]: /commands/license
|
||||||
[releases]: https://releases.hashicorp.com/consul/
|
[releases]: https://releases.hashicorp.com/consul/
|
||||||
[files]: https://easyengine.io/tutorials/linux/increase-open-files-limit
|
[files]: https://easyengine.io/tutorials/linux/increase-open-files-limit
|
||||||
[certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates
|
[certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates
|
||||||
|
|
|
@ -72,7 +72,7 @@ Version 1
|
||||||
This will ensure you have a safe fallback option in case something goes wrong. Store
|
This will ensure you have a safe fallback option in case something goes wrong. Store
|
||||||
this snapshot somewhere safe. More documentation on snapshot usage is available here:
|
this snapshot somewhere safe. More documentation on snapshot usage is available here:
|
||||||
|
|
||||||
- https://www.consul.io/docs/commands/snapshot
|
- https://www.consul.io/commands/snapshot
|
||||||
- https://learn.hashicorp.com/tutorials/consul/backup-and-restore
|
- https://learn.hashicorp.com/tutorials/consul/backup-and-restore
|
||||||
|
|
||||||
**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level)
|
**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level)
|
||||||
|
|
|
@ -20,8 +20,62 @@ upgrade flow.
|
||||||
The [`enable_central_service_config`](/docs/agent/options#enable_central_service_config)
|
The [`enable_central_service_config`](/docs/agent/options#enable_central_service_config)
|
||||||
configuration now defaults to `true`.
|
configuration now defaults to `true`.
|
||||||
|
|
||||||
|
### Changes to Intentions
|
||||||
|
|
||||||
|
#### Migration
|
||||||
|
|
||||||
|
Upgrading to Consul 1.9.0 will trigger a one-time background migration of
|
||||||
|
[intentions](/docs/connect/intentions) into an equivalent set of
|
||||||
|
[`service-intentions`](/docs/agent/config-entries/service-intentions) config
|
||||||
|
entries. This process will wait until all of the Consul servers in the primary
|
||||||
|
datacenter are running Consul 1.9.0+.
|
||||||
|
|
||||||
|
All write requests via either the [Intentions
|
||||||
|
API](/api-docs/connect/intentions) endpoints or [Config Entry
|
||||||
|
API](/api-docs/config) endpoints for a `service-intentions` kind will be
|
||||||
|
blocked until the migration process is complete after the upgrade. Reads will
|
||||||
|
function normally throughout the migration, so authorization enforcement will
|
||||||
|
be unaffected.
|
||||||
|
|
||||||
|
Secondary datacenters will perform their own one-time migration operations
|
||||||
|
after the primary datacenter completes its migration and all of the Consul
|
||||||
|
servers in the secondary datacenter are running Consul 1.9.0+. It is safe to
|
||||||
|
upgrade the datacenters in any order.
|
||||||
|
|
||||||
|
#### Deprecated Fields
|
||||||
|
|
||||||
|
All old ID-based [Intentions API](/api-docs/connect/intentions) CRUD endpoints
|
||||||
|
will retain all of their prior fields _as long as those endpoints are
|
||||||
|
exclusively used to edit intentions_. Once the underlying config entry
|
||||||
|
representation is edited it will transition the intention into the newer format
|
||||||
|
where some fields are no longer present. Once this transition occurs those
|
||||||
|
intentions can no longer be used with the ID-based endpoints unless they are
|
||||||
|
re-created via the old endpoints. Fields that are being removed or changing
|
||||||
|
behavior:
|
||||||
|
|
||||||
|
- `Intention.ID` after migration is stored in the
|
||||||
|
[`LegacyID`](/docs/agent/config-entries/service-intentions#legacyid) field.
|
||||||
|
After transitioning this field is cleared.
|
||||||
|
|
||||||
|
- `Intention.CreatedAt` after migration is stored in the
|
||||||
|
[`LegacyCreateTime`](/docs/agent/config-entries/service-intentions#legacycreatetime)
|
||||||
|
field. After transitioning this field is cleared.
|
||||||
|
|
||||||
|
- `Intention.UpdatedAt` after migration is stored in the
|
||||||
|
[`LegacyUpdateTime`](/docs/agent/config-entries/service-intentions#legacyupdatetime)
|
||||||
|
field. After transitioning this field is cleared.
|
||||||
|
|
||||||
|
- `Intention.Meta` after migration is stored in the
|
||||||
|
[`LegacyMeta`](/docs/agent/config-entries/service-intentions#legacymeta)
|
||||||
|
field. To complete the transition, this field **must be cleared manually**
|
||||||
|
and the metadata moved up to the enclosing config entry's
|
||||||
|
[`Meta`](/docs/agent/config-entries/service-intentions#meta) field. This is
|
||||||
|
not done automatically since it is potentially a lossy operation.
|
||||||
|
|
||||||
## Consul 1.8.0
|
## Consul 1.8.0
|
||||||
|
|
||||||
|
#### Removal of Deprecated Features
|
||||||
|
|
||||||
The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8)
|
The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8)
|
||||||
configuration has been removed (with version 8 ACL support by being on by
|
configuration has been removed (with version 8 ACL support by being on by
|
||||||
default).
|
default).
|
||||||
|
@ -125,7 +179,7 @@ procedure](/docs/upgrading#standard-upgrades).
|
||||||
|
|
||||||
When a 1.4.0 server first starts, it runs in "Legacy ACL mode". In this mode,
|
When a 1.4.0 server first starts, it runs in "Legacy ACL mode". In this mode,
|
||||||
bootstrap requests and new ACL APIs will not be functional yet and will return
|
bootstrap requests and new ACL APIs will not be functional yet and will return
|
||||||
an error. The server advertises it's ability to support 1.4.0 ACLs via gossip
|
an error. The server advertises its ability to support 1.4.0 ACLs via gossip
|
||||||
and waits.
|
and waits.
|
||||||
|
|
||||||
In the primary datacenter, the servers all wait in legacy ACL mode until they
|
In the primary datacenter, the servers all wait in legacy ACL mode until they
|
||||||
|
@ -282,7 +336,7 @@ soon as they are stable, allowing Autopilot to remove old servers in a safer
|
||||||
way.
|
way.
|
||||||
|
|
||||||
When upgrading from Consul 1.0, you may need to manually
|
When upgrading from Consul 1.0, you may need to manually
|
||||||
[force-leave](/docs/commands/force-leave) old servers as part of a rolling
|
[force-leave](/commands/force-leave) old servers as part of a rolling
|
||||||
update to Consul 1.0.1.
|
update to Consul 1.0.1.
|
||||||
|
|
||||||
## Consul 1.0
|
## Consul 1.0
|
||||||
|
@ -584,7 +638,7 @@ agents would have to wait to contact a Consul server before learning that.
|
||||||
The default for
|
The default for
|
||||||
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) was
|
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) was
|
||||||
changed to "true", so now operators need to opt-in to having agents support
|
changed to "true", so now operators need to opt-in to having agents support
|
||||||
running commands remotely via [`consul exec`](/docs/commands/exec).
|
running commands remotely via [`consul exec`](/commands/exec).
|
||||||
|
|
||||||
#### Raft Protocol Version Compatibility
|
#### Raft Protocol Version Compatibility
|
||||||
|
|
||||||
|
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue