From 945c13236db5b8d746116ace4468bc66e7a04af2 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 12:03:57 -0700 Subject: [PATCH 01/23] converted intentions conf entry to ref CT format --- .../config-entries/service-intentions.mdx | 1212 +++++++++++------ 1 file changed, 775 insertions(+), 437 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 34c948ac1ef..eb1814075e5 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -1,40 +1,780 @@ --- layout: docs -page_title: Service Intentions - Configuration Entry Reference +page_title: Service intentions configuration entry reference description: >- - The service intentions configuration entry kind defines the communication permissions between service types. Use the reference guide to learn about `""service-intentions""` config entry parameters and how to authorize L4 and L7 communication int he service mesh with intentions. + Use the service intentions configuration entry to allow or deny traffic to services in the mesh from specific sources. Learn how to configure `service-intention` config entries --- -# Service Intentions Configuration Entry ((#service-intentions)) +# Service intentions configuration entry reference --> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer. +This topic provides reference information for the service intentions configuration entry. Intentions are configurations for controlling access between services in the service mesh. A single service intentions configuration entry specifies one destination service and one or more L4 traffic sources, L7 traffic sources, or combination of traffic sources. Refer to [Service mesh intentions overview](/consul/docs/connect/intentions/intentions) for additional information. -The `service-intentions` config entry kind (`ServiceIntentions` on Kubernetes) controls Connect traffic -authorization for both networking layer 4 (e.g. TCP) and networking layer 7 -(e.g. HTTP). +## Configuration model -Service intentions config entries represent a collection of -[intentions](/consul/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 +- [`Kind`](#kind): string | required | must be set to `service-intentions` +- [`Name`](#name): string | required +- [`Namespace`](#namespace): string | `default` | +- [`Partition`](#partition): string | `default` | +- [`Meta`](#meta): map | no default +- [`Sources`](#sources): list | no default + - [`Name`](#sources-name): string | no default + - [`Peer`](#sources-peer): string | no default + - [`Namespace`](#sources-namespace): string | no default | + - [`Partition`](#sources-partition): string | no default | + - [`Action`](#sources-action): string | no default | required for L4 intentions + - [`Permissions`](#sources-permissions): list | no default + - [`Action`](#sources-permissions-action): string | no default | required + - [`HTTP`](#sources-permissions-http): map | required + - [`PathExact`](#sources-permissions-http): string | no default + - [`PathPrefix`](#sources-permissions-http): string | no default + - [`PathRegex`](#sources-permissions-http): string | no default + - [`Methods`](#sources-permissions-http): list | no default + - [`Header`](#sources-permissions-http-header): list of maps |no default + - [`Name`](#sources-permissions-http-header): string | required + - [`Present`](#sources-permissions-http-header): boolean | `false` + - [`Exact`](#sources-permissions-http-header): string | no default + - [`Prefix`](#sources-permissions-http-header): string | no default + - [`Suffix`](#sources-permissions-http-header): string | no default + - [`Regex`](#sources-permissions-http-header): string | no default + - [`Invert`](#sources-permissions-http-header): boolean | `false` + - [`Precedence`](#sources-precedence): number | no default | _read-only_ + - [`Type`](#sources-type): string | `consul` + - [`Description`](#sources-description): string + - [`LegacyID`](#sources-legacyid): string | no default | _read-only_ + - [`LegacyMeta`](#sources-legacymeta): map | no default | _read-only_ + - [`LegacyCreateTime`](#sources-legacycreatetime): string | no default | _read-only_ + - [`LegacyUpdateTime`](#sources-legacyupdatetime): string | no default | _read-only_ -L7 intentions within a config entry are restricted to only destination services -that define their protocol as HTTP-based via a corresponding -[`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry -or globally via [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . + + -## Sample Config Entries +- [`apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | must be set to `ServiceIntentions` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | `default` | +- [`spec`](#spec): map | no default + - [`destination`](#spec-destination): map | no default + - [`name`](#spec-destination-name): string | required + - [`namespace`](#metadata-namespace): string | `default` | + - [`sources`](#spec-sources): list | no default + - [`name`](#spec-sources-name): string | no default + - [`peer`](#spec-sources-peer): string | no default + - [`namespace`](#spec-sources-namespace): string | no default | + - [`partition`](#spec-sources-partition): string | no default | + - [`action`](#spec-sources-action): string | no default | required for L4 intentions + - [`permissions`](#spec-sources-permissions): list | no default + - [`action`](#spec-sources-permissions-action): string | no default | required + - [`http`](#spec-sources-permissions-http): map | required + - [`pathExact`](#spec-sources-permissions-http): string | no default + - [`pathPrefix`](#spec-sources-permissions-http): string | no default + - [`pathRegex`](#spec-sources-permissions-http): string | no default + - [`methods`](#spec-sources-permissions-http): list | no default + - [`header`](#spec-sources-permissions-http-header): list of maps |no default + - [`name`](#spec-sources-permissions-http-header): string | required + - [`present`](#spec-sources-permissions-http-header): boolean | `false` + - [`exact`](#spec-sources-permissions-http-header): string | no default + - [`prefix`](#spec-sources-permissions-http-header): string | no default + - [`suffix`](#spec-sources-permissions-http-header): string | no default + - [`regex`](#spec-sources-permissions-http-header): string | no default + - [`invert`](#spec-sources-permissions-http-header): boolean | `false` + - [`type`](#spec-sources-type): string | `consul` + - [`description`](#spec-sources-description): string -The following examples demonstrate potential use-cases for the `service-intentions` configuration entry. + + -### REST Access +## Complete configuration + + + + + +```hcl +Kind = "service-intentions" +Name = "" +Namespace = "" # string +Partition = "" # string +Meta = { + "" = "" + "" = "" + } +Sources = [ + { + Name = "" # string + Peer = "" # string + Namespace = "" # string + Partition = "" # string + Action = "allow" or "deny" # string for L4 intentions + Permissions = [ + { + Action = "allow" or "deny" # string for L7 intenions + HTTP = { + PathExact = "" # string + PathPrefix = "" # string + PathRegex = "" # string + Methods = [ + "", # string + "" + ] + Header = [ + { + Name = "" # string + Present = # boolean + }, + { + Name = "" # string + Exact = "" # boolean + }, + { + Name = "" # string + Prefix = "" # string + }, + { + Name = "" # string + Suffix = "" # string + }, + { + Name = "" # string + Regex = "" # string + Invert = # boolean + } + ] + } + } + ] + Type = "consul" # string + Description = "" # string + Precedence = # number + LegacyID = # string + LegacyMeta = # string + LegacyCreateTime = # string + LegacyUpdateTime = # string + } +] +``` + + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: service-intentions +metadata: + name: + namespace: +spec: + destination: + destination: + name: + namespace: + sources: + name: + peer: + namespace: + partition: + action: allow or deny + permissions: + - action: allow or deny + http: + pathExact: + pathPrefix: + pathRegex: + methods: + - + + header: + - name: + present: true + - name: + exact: false + - name: + prefix: + - name: + suffix: + - name: + regex: + invert: false + type: consul + description: +``` + + + + +```json +{ + "Kind":"service-intentions", + "Name":"", + "Namespace":"", + "Partition":"", + "Meta":{ + "key-1":"", + "key-2":"" + }, + "Sources":[ + { + "Name":"", + "Peer":"", + "Namespace":"", + "Partition":"", + "Action":"allow or deny", + "Permissions":[ + { + "Action":"allow or deny", + "HTTP":{ + "PathExact":"", + "PathPrefix":"", + "PathRegex":"", + "Methods":[ + "", + "" + ], + "Header":[ + { + "Name":"", + "Present":true + }, + { + "Name":"", + "Exact":false + }, + { + "Name":"", + "Prefix":"" + }, + { + "Name":"", + "Suffix":"" + }, + { + "Name":"", + "Regex":"", + "Invert":false + } + ] + } + } + ], + "Type":"consul", + "Description":"", + "Precedence":"", + "LegacyID":"", + "LegacyMeta":"", + "LegacyCreateTime":"", + "LegacyUpdateTime":"" + } + ] +} +``` + + + + + +## Specification + +This section provides details about the fields you can configure in the service defaults configuration entry. + + + + + +### `Kind` + +Specifies the type of configuration entry to implement. Must be set to `service-intentions`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `service-intentions`. + +### `Name` + +Specifies a name of the destination service for all intentions defined in the configuration entry. + +#### Values + +- Default: Defaults to the name of the node after writing the entry to the Consul server. +- This field is required. +- Data type: String + +You can also specify a wildcard character (`*`) to match all services without intentions. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions). + +### `Namespace` + +Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. Services in the namespace are the traffic destinations that the intentions allow or deny traffic to. + +#### Values + +- Default: `default` +- Data type: String + +You can also specify a wildcard character (`*`) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`Permissions`](#sources-permissions). + +### `Partition` + +Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry. Services in the specified partition are the traffic destinations that the intentions allow or deny traffic to. + +#### Values + +- Default: `default` +- Data type: String + +### `Meta` + +Specifies key-value pairs to add to the KV store when the configuration entry is evaluated. + +#### Values + +- Default: None +- Data type: Map of one or more key-value pairs + - keys: String + - values: String, integer, or float + +### `Sources[]` + +List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime. Refer to [`Precedence`](#sources-precedence) for additional information. + +#### Values + +- Default: None +- List of objects that contain the following fields: + - `Name` + - `Peer` + - `Namespace` + - `Partition` + - `Action` + - `Permissions` + - `Precedence` + - `Type` + - `Description` + - `LegacyID` + - `LegacyMeta` + - `LegacyCreateTime` + - `LegacyUpdateTime` + +### `Sources[].Name` + +Specifies the name of the source that the intention allows or denies traffic from. If [`Type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog. + +#### Values + +- Default: None +- This field is required. +- Data type: String + +### `Sources[].Peer` + +Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers. + +The `Peer` and `Partition` fields are mutually exclusive. + +#### Values + +- Default: None +- Data type: String + +### `Sources[].Namespace` + +Specifies the traffic source namespace that the intention allows or denies traffic from. + +#### Values + +- Default: If [`Peer`](#sources-peer) is unspecified, defaults to the destination [`Namespace`](#namespace). +- Data type: String + +### `Sources[].Partition` + +Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions. + +The `Peer` and `Partition` fields are mutually exclusive. + +#### Values + +- Default: If [`Peer`](#sources-peer) is unspecified, defaults to the destination [`Partition`](#partition). +- Data type: string + +### `Sources[].Action` + +Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field for L7 intentions. Configure the [`Permissions`](#sources-permissions) field instead. + +#### Values + +- Default: None +- This field is required for L4 intentions. +- Data type: String value set to either `allow` or `deny` + +### `Sources[].Permissions[]` + +Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. + +Consul applies permissions in the order specified in the configuration. Beginning at the top of the list, Consul applies the first matching request and stops evaluating against the remaining configurations. + +For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. + +Do not configure this field for L4 intentions. Use the [`Sources.Action`](#sources-action) parameter instead. + +The `Permissions` only applies to services with a compatible protocol. `Permissions` are not supported when the [`Name`](#name) or [`Namespace`](#namespace) field is configured with a wildcard because service instances or services in a namespace may use different protocols. + +#### Values + +- Default: None +- List of objects that contain the following fields: + - `Action` + - `HTTP` + +### `Sources[].Permissions[].Action` + +Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value set to either `allow` or `deny`. + +### `Sources[].Permissions[].HTTP` + +Specifies a set of HTTP-specific match criteria. Consul applies the action defined in the [`Action`](#sources-permissions-action) field to source traffic that matches the criteria. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +The following table describes the parameters that the HTTP map may contain: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `PathExact` | Specifies an exact path to match on the HTTP request path. Do not specify `PathExact` if `PathPrefix` or `PathRegex` are configured in the same `HTTP` configuration. | string | none | +| `PathPrefix` | Specifies a path prefix to match on the HTTP request path. Do not specify `PathPrefix` if `PathExact` or `PathRegex` are configured in the same `HTTP` configuration. | string | none | +| `PathRegex` | Defines a regular expression to match on the HTTP request path. Do not specify `PathRegex` if `PathExact` or `PathPrefix` are configured in the same `HTTP` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | none | +| `Methods` | Specifies a list of HTTP methods. Consul applies the permission if a request matches the `PathExact`, `PathPrefix`, `PathRegex`, or `Header`, and the source sent the request using one of the specified methods. Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for a list of supported request headers. | list | All request methods | +| `Header` | Specifies a header name and matching criteria for HTTP request headers. Refer to [`Sources[].Permissions[].HTTP[].Header`](#sources-permissions-http-header) for details. | list of maps | none | + +### `Sources[].Permissions[].HTTP[].Header[]` + +Specifies a header name and matching criteria for HTTP request headers. The request header must match all specified criteria for the permission to apply. + +#### Values + +- Default: None +- Data type: list of objects + +Each member of the `Header` list is a map that contains a `Name` field and at least one match criterion. The following table describes the parameters that each member of the `Header` list may contain: + +| Parameter | Description | Data type | Required | +| --- | --- | --- | --- | +| `Name` | Specifies the name of the header to match. | string | required | +| `Present` | Enables a match if the header configured in the `Name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `Present` if `Exact`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | boolean | optional | +| `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `Exact` value, Consul applies the permission. Do not specify `Exact` if `Present`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional | +| `Prefix` | Specifies a prefix value for the header key set in the `Name` field. If the request header value starts with the `Prefix` value, Consul applies the permission. Do not specify `Prefix` if `Present`, `Exact`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional | +| `Suffix` | Specifies a suffix value for the header key set in the `Name` field. If the request header value ends with the `Suffix` value, Consul applies the permission. Do not specify `Suffix` if `Present`, `Exact`, `Prefix`, or `Regex` are configured in the same `Header` configuration. | string | optional | +| `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, or `Suffix` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional | +| `Invert` | Inverts the matching logic configured in the `Header`. Default is `false`. | boolean | optional | + + +### `Sources[].Precedence` + +The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/intentions#precedence-and-matching-order) for additional information. + +### `Sources[].Type` + +Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`. + +#### Values + +- Default: `consul` +- Data type: String + +### `Sources[].Description` + +Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network. + +#### Values + +- Default: None +- Data type: String + +### `Sources[].LegacyID` + +Read-only unique user ID (UUID) for the intention in the system. Consul generates the value and exposes it in the configuration entry so that legacy API endpoints continue to function. Refer to [Read Specific Intention by ID](/consul/api-docs/connect/intentions#read-specific-intention-by-id) for additional information. + +### `Sources[].LegacyMeta` + +Read-only set of arbitrary key-value pairs to attach to the intention. Consul generates the metadata and exposes it in the configuration entry so that legacy intention API endpoints continue to function. Refer to [Read Specific Intention by ID](/consul/api-docs/connect/intentions#read-specific-intention-by-id) for additional information. + +### `Sources[].CreateTime` + +Read-only timestamp for the intention creation. Consul exposes the timestamp in the configuration entry to allow legacy intention API endpoints to continue functioning. Refer to [Read Specific Intention by ID](/consul/api-docs/connect/intentions#read-specific-intention-by-id) for additional information. + +### `Sources[].LegacyUpdateTime` + +Read-only timestamp marking the most recent intention update. Consul exposes the timestamp in the configuration entry to allow legacy intention API endpoints to continue functioning. Refer to [Read Specific Intention by ID](/consul/api-docs/connect/intentions#read-specific-intention-by-id) for additional information. + + + + + +### `apiVersion` + +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. + +#### Values + +- Default: None +- This field is required. +- String value that must be set to `consul.hashicorp.com/v1alpha1`. + +### `kind` + +Specifies the type of configuration entry to implement. Must be set to `ServiceIntentions`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `ServiceIntentions`. + +### `metadata` + +Map that contains an arbitrary name for the configuration entry and the namespace it applies to. + +#### Values + +- Default: None +- Data type: Map + +### `metadata.name` + +Specifies an arbitrary name for the configuration entry. Note that in other configuration entries, the `metadata.name` field specifies the name of the service that the settings apply to. For service intentions, the service that accepts the configurations is the _destination_ and is specified in the [`spec.destination.name`](#spec-destination-name) field. Refer to the following topics for additional information: + +- [ServiceIntentions Special Case (OSS)](/consul/docs/k8s/crds#serviceintentions-special-case) +- [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise) + +#### Values + +- Default: None +- Data type: String + +### `metadata.namespace` + +Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. Refer to [Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the `metadata.namespace` configuration. + +#### Values + +- Default: `default` +- Data type: String + +### `spec` +Map that contains the details about the `ServiceIntentions` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.destination` + +Map that identifies the destination name and destination namespace that source services are allowed or denied access to. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.destination.name` + +Specifies the name of the destination service in the mesh that the intentions apply to. +You can also specify a wildcard character (`*`) to match all services that are missing intention settings. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`permissions`](#spec-sources-permissions). + +#### Values + +- Default: None +- This field is required. +- Data type: String + +### `spec.metadata.namespace` + +Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. You can also specify a wildcard character (`*`) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`permissions`](#spec-sources-permissions). + +Refer to [Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the `metadata.namespace` configuration. + +#### Values + +- Default: If not set, destination service namespace is inherited from the `connectInject.consulNamespaces` configuration. Refer to [ServiceIntentions Special Case (Enterprise)](/docs/k8s/crds#serviceintentions-special-case-enterprise) for details. +- Data type: String + +### `spec.sources[]` + +List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime. + +#### Values + +- Default: None +- List of objects that contain the following fields: + - `name` + - `peer` + - `namespace` + - `partition` + - `Action` + - `permissions` + - `type` + - `description` + +### `spec.sources[].name` + +Specifies the name of the source that the intention allows or denies traffic from. If [`type`](#sources-type) is set to `consul`, then the value refers to the name of a Consul service. The source is not required to be registered into the Consul catalog. + +#### Values + +- Default: None +- This field is required. +- Data type: String + +### `spec.sources[].peer` + +Specifies the name of a peered Consul cluster that the intention allows or denies traffic from. Refer to [Cluster peering overview](/consul/docs/connect/cluster-peering) for additional information about peers. The `peer` and `partition` fields are mutually exclusive. +#### Values + +- Default: None +- Data type: String + +### `spec.sources[].namespace` + +Specifies the traffic source namespace that the intention allows or denies traffic from. + +#### Values + +- Default: If [`peer`](#spec-sources-peer) is unspecified, defaults to the namespace specified in the [`spec.destination.namespace`](#spec-destination-namespace) field. +- Data type: String + +### `spec.sources[].partition` + +Specifies the name of an admin partition that the intention allows or denies traffic from. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information about partitions. The `peer` and `partition` fields are mutually exclusive. + +#### Values + +- Default: If [`peer`](#sources-peer) is unspecified, defaults to the partition specified in [`spec.destination.partition`](#spec-destination-partition). +- Data type: String + +### `spec.sources[].action` + +Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field for L7 intentions. Configure the [`spec.sources.permissions`](#spec-sources-permissions) field instead. + +#### Values + +- Default: None +- This field is required for L4 intentions. +- Data type: String value set to either `allow` or `deny` + +### `spec.sources[].permissions[]` + +Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. + +Consul applies permissions in the order specified in the configuration. Starting at the beginning of the list, Consul applies the first matching request and stops evaluating against the remaining configurations. + +For requests that do not match any of the defined permissions, Consul applies the intention behavior defined in the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. + +Do not configure this field for L4 intentions. Use the [`spec.sources.action`](#sources-action) parameter instead. + +`permissions` configurations only apply to services with a compatible protocol. As a result, they are not supported when the [`spec.destination.name`](#spec-destination-name) or [`spec.destination.namespace`](#spec-destination-namespace) field is configured with a wildcard because service instances or services in a namespace may use different protocols. + +#### Values + +- Default: None +- List of objects that contain the following fields: + - `action` + - `http` + +### `spec.sources[].permissions[].action` + +Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value set to either `allow` or `deny` + +### `spec.sources[].permissions[].http` + +Specifies a set of HTTP-specific match criteria. Consul applies the action defined in the [`spec.sources.permissions.action`](#spec-sources-permissions-action) field to source traffic that matches the criteria. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +The following table describes the parameters that the HTTP map may contain: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `pathExact` | Specifies an exact path to match on the HTTP request path. Do not specify `pathExact` if `pathPrefix` or `pathRegex` are configured in the same `http` configuration. | string | none | +| `pathPrefix` | Specifies a path prefix to match on the HTTP request path. Do not specify `pathPrefix` if `pathExact` or `pathRegex` are configured in the same `http` configuration. | string | none | +| `pathRegex` | Defines a regular expression to match on the HTTP request path. Do not specify `pathRegex` if `pathExact` or `pathPrefix` are configured in the same `http` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | none | +| `methods` | Specifies a list of HTTP methods. Consul applies the permission if a request matches the `pathExact`, `pathPrefix`, `pathRegex`, or `header`, and the source sent the request using one of the specified methods. Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for a list of supported request headers. | list | All request methods | +| `header` | Specifies a header name and matching criteria for HTTP request headers. Refer to [`spec.sources[].permissions[].http[].header`](#spec-sources-permissions-http-header) for details. | list of maps | none | + +### `spec.sources[].permissions[].http[].header` + +Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply. + +#### Values + +- Default: None +- Data type: List of maps + +Each member of the `header` list is a map that contains a `name` field and at least one match criterion. The following table describes the parameters that each member of the `header` list may contain: + +| Parameter | Description | Data type | Required | +| --- | --- | --- | --- | +| `name` | Specifies the name of the header to match. | string | required | +| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | boolean | optional | +| `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `exact` value, Consul applies the permission. Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional | +| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission. Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional | +| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission. Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `header` configuration. | string | optional | +| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional | +| `invert` | Inverts the matching logic configured in the `header`. Default is `false`. | boolean | optional | + +### `spec.sources[].type` + +Specifies the type of destination service that the configuration entry applies to. The only value supported is `consul`. + +#### Values + +- Default: `consul` +- Data type: String + +### `spec.sources[].description` + +Specifies a description of the intention. Consul presents the description in API responses to assist other tools integrated into the network. + +#### Values + +- Default: None +- Data type: String + + + + + + +## Examples + +The following examples demonstrate potential use-cases for the service intentions configuration entry. + +### REST access In the following example, the `admin-dashboard` and `report-generator` services have different levels of access when making REST calls: @@ -134,8 +874,8 @@ spec: ### gRPC -In the following use-case, access to the `IssueRefund` gRPC service method is set to `deny`. Because gRPC method calls [are -HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), an HTTP path-matching rule can be used to control traffic: +In the following example, Consul denies requests from `frontend-web` to the `IssueRefund` gRPC service. +Because gRPC method calls use the [HTTP/2 protocol](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), you can apply an HTTP path-matching rule to control traffic: @@ -174,8 +914,8 @@ Sources = [ } ] } - # NOTE: a default catch-all based on the default ACL policy will apply to - # unmatched connections and requests. Typically this will be DENY. + # A default catch-all based on the default ACL policy applies to + # unmatched connections and requests. This is typically DENY. ] ``` @@ -204,8 +944,8 @@ spec: - 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. + # A default catch-all based on the default ACL policy applies to + # unmatched connections and requests. This is typically DENY. ``` ```json @@ -249,7 +989,7 @@ spec: ### L4 and L7 -You can mix and match L4 and L7 intentions per source: +In the following example, Consul enforces application layer intentions that deny requests to `api` from `hackathon-project` but allow requests from `web`. In the same configuration entry, Consul enforces network layer intentions that allow requests from `nightly-reconciler` that send `POST` requests to the `/v1/reconcile-data` HTTP endpoint: @@ -277,8 +1017,8 @@ Sources = [ } ] }, - # NOTE: a default catch-all based on the default ACL policy will apply to - # unmatched connections and requests. Typically this will be DENY. + # A default catch-all based on the default ACL policy applies to + # unmatched connections and requests. This is typically DENY. ] ``` @@ -301,8 +1041,8 @@ spec: 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. + # A default catch-all based on the default ACL policy applies to + # unmatched connections and requests. This is typically DENY. ``` ```json @@ -384,406 +1124,4 @@ When using cluster peering connections, intentions secure your deployments with ] } ``` - - -## Available Fields - -', - yaml: false, - }, - { - name: 'Namespace', - type: `string: "default"`, - enterprise: true, - description: - "Specifies the namespaces 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. Wildcard intentions cannot be used when defining L7 [`Permissions`](/consul/docs/connect/config-entries/service-intentions#permissions).", - yaml: false, - }, - { - name: 'Partition', - type: `string: "default"`, - enterprise: true, - description: - "Specifies the admin partition on which the configuration entry will apply. Wildcard characters (`*`) are not supported. Admin partitions must specified explicitly.", - yaml: false, - }, - { - name: 'Meta', - type: 'map: nil', - description: 'Specifies arbitrary KV metadata pairs.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: - 'Unlike other config entries, the `metadata.name` field is not used to set the name of the service being configured. Instead, that is set in `spec.destination.name`. Thus this name can be set to anything. See [ServiceIntentions Special Case (OSS)](/consul/docs/k8s/crds#serviceintentions-special-case) or [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise) for more details.', - }, - { - name: 'namespace', - description: - 'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.', - }, - ], - hcl: false, - }, - { - name: 'destination', - hcl: false, - children: [ - { - name: 'name', - hcl: false, - type: 'string: ', - description: - "The name of the destination service for 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. Wildcard intentions cannot be used when defining L7 [`Permissions`](/consul/docs/connect/config-entries/service-intentions#permissions).", - }, - { - name: 'namespace', - hcl: false, - enterprise: true, - type: 'string: ', - description: - "Specifies the namespaces 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. If not set, the namespace used will depend on the `connectInject.consulNamespaces` configuration. See [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise) for more details. Wildcard intentions cannot be used when defining L7 [`Permissions`](/consul/docs/connect/config-entries/service-intentions#permissions).", - }, - ], - }, - { - name: 'Sources', - type: 'array', - description: `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` - -', - description: { - hcl: - "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.", - yaml: - "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.", - }, - }, - { - name: 'Peer', - type: 'string: ""', - description: { - hcl: - "Specifies the [peer](/consul/docs/connect/cluster-peering/index.mdx) of the source service. `Peer` is mutually exclusive with `Partition`.", - yaml: - "Specifies the [peer](/consul/docs/connect/cluster-peering/index.mdx) of the source service. `peer` is mutually exclusive with `partition`.", - }, - }, - { - name: 'Namespace', - enterprise: true, - type: 'string: ""', - description: { - hcl: - "The namespace of the source service. If `Peer` is empty, `Namespace` defaults to the namespace of the destination service (i.e. the config entry's namespace).", - yaml: - 'The namespace of the source service. If `peer` is empty, `namespace` defaults to the namespace of the destination service (i.e. `spec.destination.namespace`).', - }, - }, - { - name: 'Partition', - enterprise: true, - type: 'string: ""', - description: { - hcl: - "Specifies the admin partition of the source service. If `Peer` is empty, `Partition` defaults to the destination service's partition (i.e. the configuration entry's partition). `Partition` is mutually exclusive with `Peer`.", - yaml: - "Specifies the admin partition of the source service. If `peer` is empty, `partition` defaults to the destination service's partition (i.e. `spec.destination.partition`). `partition` is mutually exclusive with `peer`.", - }, - }, - { - name: 'Action', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Permissions', - type: 'array', - description: { - hcl: `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](/consul/docs/agent/config/config-files#acl_default_policy).

- This should be omitted for an L4 intention as it is mutually exclusive with - the \`Action\` field.

- Setting \`Permissions\` is not valid if a wildcard is used for the \`Name\` or \`Namespace\` because they can only be - applied to services with a compatible protocol.`, - yaml: `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](/consul/docs/agent/config/config-files#acl_default_policy).

- This should be omitted for an L4 intention as it is mutually exclusive with - the \`action\` field.

- Setting \`permissions\` is not valid if a wildcard is used for the \`spec.destination.name\` or \`spec.destination.namespace\` - because they can only be applied to services with a compatible protocol.`, - }, - }, - { - name: 'Precedence', - type: 'int: ', - description: - 'An [integer precedence value](/consul/docs/connect/intentions#precedence-and-match-order) computed from the source and destination naming components.', - yaml: false, - }, - { - name: 'Type', - type: 'string: "consul"', - description: { - hcl: - '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".', - yaml: - '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".', - }, - }, - { - name: 'Description', - type: 'string: ""', - description: - 'Description for the intention. This is not used by Consul, but is presented in API responses to assist tooling.', - }, - { - name: 'LegacyID', - type: 'string: ', - description: `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](/consul/api-docs/connect/intentions#update-intention-by-id) - [endpoints](/consul/api-docs/connect/intentions#read-specific-intention-by-id) to - continue to function for a period of time after [upgrading to 1.9.0](/consul/docs/upgrading/upgrade-specific#consul-1-9-0).`, - yaml: false, - }, - { - name: 'LegacyMeta', - type: 'map: ', - description: `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](/consul/api-docs/connect/intentions#update-intention-by-id) - [endpoints](/consul/api-docs/connect/intentions#read-specific-intention-by-id) to - continue to function for a period of time after [upgrading to 1.9.0](/consul/docs/upgrading/upgrade-specific#consul-1-9-0).`, - yaml: false, - }, - { - name: 'LegacyCreateTime', - type: 'time: optional', - description: `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](/consul/api-docs/connect/intentions#update-intention-by-id) - [endpoints](/consul/api-docs/connect/intentions#read-specific-intention-by-id) to - continue to function for a period of time after [upgrading to 1.9.0](/consul/docs/upgrading/upgrade-specific#consul-1-9-0).`, - yaml: false, - }, - { - name: 'LegacyUpdateTime', - type: 'time: optional', - description: `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](/consul/api-docs/connect/intentions#update-intention-by-id) - [endpoints](/consul/api-docs/connect/intentions#read-specific-intention-by-id) to - continue to function for a period of time after [upgrading to 1.9.0](/consul/docs/upgrading/upgrade-specific#consul-1-9-0).`, - yaml: false, - }, - ]} -/> - -### `IntentionPermission` - -', - description: - 'This is one of "allow" or "deny" for the action that should be taken if this permission matches a request.', - }, - { - name: 'HTTP', - type: 'IntentionHTTPPermission: ', - description: - 'A set of [HTTP-specific authorization criteria](#intentionhttppermission)', - }, - ]} -/> - -### `IntentionHTTPPermission` - -
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Exact path to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathPrefix', - type: 'string: ""', - description: { - hcl: - 'Path prefix to match on the HTTP request path.

At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Path prefix to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathRegex', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Methods', - type: 'array', - description: - '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).', - }, - { - name: 'Header', - type: 'array', - description: - '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.', - children: [ - { - name: 'Name', - type: 'string: ', - description: 'Name of the header to match', - }, - { - name: 'Present', - type: 'bool: false', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Exact', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Prefix', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Suffix', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Regex', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Invert', - type: 'bool: false', - description: 'Inverts the logic of the match', - }, - ], - }, - ]} -/> - -## ACLs - -Configuration entries may be protected by [ACLs](/consul/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](/consul/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](/consul/docs/connect/proxies/envoy) as a proxy, the syntax for -these fields is [RE2](https://github.com/google/re2/wiki/Syntax). + \ No newline at end of file From 4034c6f753a5023fdaacd28b67f86ffb52dc1206 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 13:04:17 -0700 Subject: [PATCH 02/23] set up intentions nav --- .../{ => intentions}/intentions-legacy.mdx | 0 .../connect/{ => intentions}/intentions.mdx | 0 website/data/docs-nav-data.json | 21 +++++++++++++------ 3 files changed, 15 insertions(+), 6 deletions(-) rename website/content/docs/connect/{ => intentions}/intentions-legacy.mdx (100%) rename website/content/docs/connect/{ => intentions}/intentions.mdx (100%) diff --git a/website/content/docs/connect/intentions-legacy.mdx b/website/content/docs/connect/intentions/intentions-legacy.mdx similarity index 100% rename from website/content/docs/connect/intentions-legacy.mdx rename to website/content/docs/connect/intentions/intentions-legacy.mdx diff --git a/website/content/docs/connect/intentions.mdx b/website/content/docs/connect/intentions/intentions.mdx similarity index 100% rename from website/content/docs/connect/intentions.mdx rename to website/content/docs/connect/intentions/intentions.mdx diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index f66afc94c5f..c03cdbecdc7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -539,12 +539,21 @@ ] }, { - "title": "Service-to-service permissions - Intentions", - "path": "connect/intentions" - }, - { - "title": "Service-to-service permissions - Intentions (Legacy Mode)", - "path": "connect/intentions-legacy" + "title": "Service intentions", + "routes": [ + { + "title": "Service intentions overview", + "path": "connect/intentions/intentions" + }, + { + "title": "Service intentions legacy mode", + "path": "connect/intentions/intentions-legacy" + }, + { + "title": "Configuration", + "href": "/consul/docs/connect/config-entries/service-intentions" + } + ] }, { "title": "Transparent Proxy", From 8c06a1883e2023a3e68ec10e2edd83b684acc9c0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 13:14:02 -0700 Subject: [PATCH 03/23] add page for intentions usage --- .../connect/intentions/intentions-usage.mdx | 341 ++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 website/content/docs/connect/intentions/intentions-usage.mdx diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx new file mode 100644 index 00000000000..b3b0371a93a --- /dev/null +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -0,0 +1,341 @@ +--- +layout: docs +page_title: Service Mesh Intentions +description: >- + Intentions define communication permissions in the service mesh between microservices. Learn about configuration basics, wildcard intentions, precedence and match order, and protecting intention management with ACLs. +--- + +# Service Mesh Intentions + +-> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and +later. The documentation for the legacy intentions system is +[here](/consul/docs/connect/intentions-legacy). + +Intentions define access control for services via Connect and are used to +control which services may establish connections or make requests. Intentions +can be managed via the API, CLI, or UI. + +Intentions are enforced on inbound connections or requests by the +[proxy](/consul/docs/connect/proxies) or within a [natively integrated +application](/consul/docs/connect/native). + +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 application layer 7 (e.g. HTTP): + +- **Identity-based** - All intentions may enforce access based on identities + encoded within [TLS + certificates](/consul/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](/consul/docs/connect/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](/consul/api-docs/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_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. +If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. +If is set to `deny`, then all connections or requests will be denied by default. + +## Intention Basics + +You can define a [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/consul/api-docs/connect/intentions) and [CLI](/consul/commands/intention) documentation for details. + +The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples. + + + +```hcl +Kind = "service-intentions" +Name = "db" +Sources = [ + { + Name = "web" + Action = "deny" + }, + { + Name = "api" + Action = "allow" + } +] +``` + +```json +{ + "Kind": "service-intentions", + "Name": "db", + "Sources": [ + { + "Action": "deny", + "Name": "web" + }, + { + "Action": "allow", + "Name": "api" + } + ] +} +``` + + + +This configuration entry defines two intentions with a common destination of `db`. The +first intention above is a deny intention with a source of `web`. This says +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`. +This says that connections from api to db are allowed and connections will be +accepted. + +### Wildcard Intentions + +You can use the `*` wildcard to match service names when defining an intention source or destination. The wildcard matches _any_ value, which enables you to set a wide initial scope when configuring intentions. + +The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/consul/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information). + +In the following example, the `web` service cannot connect to _any_ service: + + + +```hcl +Kind = "service-intentions" +Name = "*" +Sources = [ + { + Name = "web" + Action = "deny" + } +] +``` + +```json +{ + "Kind": "service-intentions", + "Name": "*", + "Sources": [ + { + "Action": "deny", + "Name": "web" + } + ] +} +``` + + + +The `db` service is configured to deny all connection in the following example: + + + +```hcl +Kind = "service-intentions" +Name = "db" +Sources = [ + { + Name = "*" + Action = "deny" + } +] +``` + +```json +{ + "Kind": "service-intentions", + "Name": "db", + "Sources": [ + { + "Action": "deny", + "Name": "*" + } + ] +} +``` + + + + This example grants Prometheus access to any service in +any namespace. + + + +```hcl +Kind = "service-intentions" +Name = "*" +Namespace = "*" +Sources = [ + { + Name = "prometheus" + Namespace = "monitoring" + Action = "allow" + } +] +``` + +```json +{ + "Kind": "service-intentions", + "Name": "*", + "Namespace": "*", + "Sources": [ + { + "Action": "allow", + "Name": "prometheus", + "Namespace": "monitoring" + } + ] +} +``` + + + +### 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 + +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 a +[field](/consul/docs/connect/config-entries/service-intentions#precedence) on the +`service-intentions` configuration entry after it is modified. Precedence cannot be +manually overridden today. + +The numbers in the table above are not stable. Their ordering will remain +fixed but the actual number values may change in the future. + +-> - Namespaces are an Enterprise feature. In Consul +OSS the only allowable value for either namespace field is `"default"`. Other +rows in this table are not applicable. + +## Intention Management Permissions + +Intention management can be protected by [ACLs](/consul/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" +} +``` + +```json +{ + "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. + +Supported [proxies] (such as [Envoy]) also cache this data within their own +configuration so that inbound connections or requests require no Consul agent +involvement during authorization. All actions in the data path of connections +happen within the proxy. + +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. Proxies similarly use blocking queries to update +their local configurations quickly. + +Because all the intention data is cached locally, the agents or proxies can +fail static. Even if the agents are severed completely from the Consul servers, +or the proxies are severed completely from their local Consul agent, inbound +connection authorization continues to work indefinitely. Changes to intentions +will not be picked up until the partition heals, but will then automatically +take effect when connectivity is restored. + +[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol +[proxies]: /consul/docs/connect/proxies +[envoy]: /consul/docs/connect/proxies/envoy From 35757aa1f602018379dbc5fbf1e4c5ccfbce0624 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 14:33:18 -0700 Subject: [PATCH 04/23] final intentions usage page --- .../connect/intentions/intentions-usage.mdx | 437 ++++++++---------- website/data/docs-nav-data.json | 4 + 2 files changed, 207 insertions(+), 234 deletions(-) diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx index b3b0371a93a..8ffe0465527 100644 --- a/website/content/docs/connect/intentions/intentions-usage.mdx +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -1,64 +1,185 @@ --- layout: docs -page_title: Service Mesh Intentions +page_title: Create and manage service intentions description: >- - Intentions define communication permissions in the service mesh between microservices. Learn about configuration basics, wildcard intentions, precedence and match order, and protecting intention management with ACLs. + Learn how to create and manage Consul service mesh intentions using service-intentions config entries, the `consul intentions` command, and `/connect/intentions` API endpoint. --- -# Service Mesh Intentions +# Create and manage intentions --> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and -later. The documentation for the legacy intentions system is -[here](/consul/docs/connect/intentions-legacy). +This topic describes how to create and manage service intentions, which are configurations for controlling access between services in the service mesh. -Intentions define access control for services via Connect and are used to -control which services may establish connections or make requests. Intentions -can be managed via the API, CLI, or UI. +## Overview -Intentions are enforced on inbound connections or requests by the -[proxy](/consul/docs/connect/proxies) or within a [natively integrated -application](/consul/docs/connect/native). +You can create single intentions or create them in batches using the Consul API, CLI, or UI. You can also define a service intention configuration entry that sets default intentions for all services in the mesh. Refer to [Service intentions overview](/consul/docs/connnect/intentions/intentions) for additional background information about intentions. -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 application layer 7 (e.g. HTTP): +## Requirements -- **Identity-based** - All intentions may enforce access based on identities - encoded within [TLS - certificates](/consul/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**. +- At least two services must be registered in the datacenter. +- TLS must be enabled to enforce L4 intentions. Refer to [Encryption](/consul/docs/security/encryption) for additional information. -- **Application-aware** - Some intentions may additionally enforce access based - on [L7 request - attributes](/consul/docs/connect/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**. +### ACL requirements -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. +Consul grants permissions for creating and managing intentions based on the destination, not the source. When ACLs are enabled, services and operators must present a token linked to a policy that grants read and write permissions to the destination service. -The [intention match API](/consul/api-docs/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. +Consul implicitly grants `intentions:read` permissions to destination services when they are configured with `service:read` or `service:write` permissions. This is so that the services can allow or deny inbound connections when they attempt to join the service mesh. Refer to [Service rules](/consul/docs/security/acl/acl-rules#service-rules) for additional information about configuring ALCs for intentions. -The default intention behavior is defined by the [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. -If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. -If is set to `deny`, then all connections or requests will be denied by default. +The default ACL policy configuration determines the default behavior for intentions. If the policy is set to `deny`, then all connections or requests are denied and you must enable them explicitly. Refer to [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) for details. -## Intention Basics +## Create a single intention -You can define a [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/consul/api-docs/connect/intentions) and [CLI](/consul/commands/intention) documentation for details. +You can create and manage intentions one at a time using the Consul API, CLI, or UI You can specify one destination or multiple destinations in a single intention. -The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples. +### API - +Send a `PUT` request to the `/connect/intentions/exact` HTTP API endpoint and specify the following query parameters: + +- `source`: Service sending the request +- `destination`: Service responding to the request +- `ns`: Namespace of the destination service + +For L4 intentions, you must also specify the intention action in the request payload. + +The following example creates an intention that allows `web` to send request to `db`: + +```shell-session +$ curl --request PUT \ +--data ' { "Action": "allow" } ' \ +http://localhost:8500/v1/connect/intentions/exact\?source\=web\&destination\=db +``` + +Refer to the `/connect/intentions/exact` [HTTP API endpoint documentation](/consul/api-docs/connect/intentions) for additional information request payload parameters. + +For L7 intentions, specify the `Permissions` in the request payload to configure attributes for dynamically enforcing intentions. In the following example payload, Consul allows HTTP GET requests if the request body is empty: + + + +```json +{ + "Permissions": [ + { + "Action": "allow", + "HTTP": { + "Methods": ["GET"], + "Header": [ + { + "Name": "Content-Length", + "Exact": "0" + } + ] + } + } + ] +} + +``` + + + +The `Permissions` object specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. Refer to the [`Sources[].Permissions[]` parameter](/consul/connect/config-entries/service-intentions#source-permissions) in the service intentions configuration entry reference for configuration details. + +To apply the intention, call the endpoint and pass the configuration file containing the attributes to the endpoint: + +```shell-session +$ curl --request PUT \ +--data @payload.json \ +http://localhost:8500/v1/connect/intentions/exact\?source\=svc1\&destination\=sv2 +``` +### CLI + +Use the `consul intention create` command according to the following syntax to create a new intention: + +```shell-session +$ consul intention create - +``` + +The following example creates an intention that allows `web` service instances to connect to `db` service instances: + +```shell-session +$ consul intention create -allow web db +``` + +You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/intentions#precedence-and-match-order) for additional information. + +### Consul UI + +1. Log into the Consul UI and choose **Services** from the sidebar menu. +1. Click on a service and then click the **Intentions* tab. +1. Click **Create** and choose the source service from the drop-down menu. +1. You can add an optional description. +1. Choose one of the following options: + 1. **Allow**: Allows the source service to send requests to the destination. + 1. **Deny**: Prevents the source service from sending requests to the destination. + 1. **Application Aware**: Enables you to specify L7 criteria for dynamically enforcing intentions. Refer to [Configure application aware settings](#configure-application-aware-settings) for additional information. +1. Click **Save**. + +Repeat the procedure as necessary to create additional intentions. + +#### Configure application aware settings + +You can use the Consul UI to configure L7 permissions. + +1. Click **Add permission** to open the permission editor. +1. Enable the **Allow** or **Deny** option. +1. You can specify a path, request method, and request headers to match. All criteria must be satisfied for Consul to enforce the permission. Refer to the [`Sources[].Permissions[]` parameter](/consul/docs/connect/config-entries/service-intentions#sources-permissions) in the service intentions configuration entry reference for information about the available configuration fields. +1. Click **Save**. + +Repeat the procedure as necessary to create additional permissions. + +## Create intention defaults + +You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic. + +### Define the service defaults configuration entry + +Configure the following fields: + + + + + +- [`Kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `service-intentions`. +- [`Name`](/consul/docs/connect/config-entries/service-intentions#kind): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions. +- [`Sources`](/consul/docs/connect/config-entries/service-intentions#sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence. +- [`Sources.Action`](/consul/docs/connect/config-entries/service-intentions#sources-action) or [`Sources.Permissions`](/consul/docs/connect/config-entries/service-intentions#sources-permissions): For L4 intentions, set the `Action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `Permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `Actions` and `Permissions` settings are mutually exclusive. + + + + + +- [`apiVersion`](/consul/docs/connect/config-entries/service-intentions#apiversion): Specifies the Consul API version. Must be set to `consul.hashicorp.com/v1alpha1`. +- [`kind`](/consul/docs/connect/config-entries/service-intentions#kind): Declares the type of configuration entry. Must be set to `ServiceIntentions`. +- [`spec.destination.name`](/consul/docs/connect/config-entries/service-intentions#spec-destination-name): Specifies the name of the destination service for intentions defined in the configuration entry. You can use a wildcard character (*) to set L4 intentions for all services that are not protected by specific intentions. Wildcards are not supported for L7 intentions. +- [`spec.sources`](/consul/docs/connect/config-entries/service-intentions#spec-sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence. +- [`spec.sources.action`](/consul/docs/connect/config-entries/service-intentions#spec-sources-action) or [`spec.sources.permissions`](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions): For L4 intentions, set the `action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `actions` and `permissions` settings are mutually exclusive. + +Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about the configuration options. + + + + + +#### Interaction with other configuration entries + +L7 intentions defined in a configuration entry are restricted to destination services +configured with an HTTP-based protocol as defined in a corresponding +[service defaults configuration entry](/docs/connect/config-entries/service-defaults) +or globally in a [proxy defaults configuration entry](/docs/connect/config-entries/proxy-defaults). + +### Apply the service intentions configuration entry + +You can apply the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `ServiceIntentions` custom resource definitions (CRD) to implement and manage Consul configuration entries. + +Refer to the following topics for details about applying configuration entries: + +- [How to Use Configuration Entries](/consul/docs/agent/config-entries) +- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds) + +### Example service intentions + +The following example configuration entry specifies an L4 intention that denies traffic from `web` to `db` service instances, but allows traffic from `api` to `db`. + + ```hcl Kind = "service-intentions" @@ -75,6 +196,19 @@ Sources = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: db + sources: + - name: web + action: deny + - name: api + action: allow +``` + ```json { "Kind": "service-intentions", @@ -94,22 +228,9 @@ Sources = [ -This configuration entry defines two intentions with a common destination of `db`. The -first intention above is a deny intention with a source of `web`. This says -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`. -This says that connections from api to db are allowed and connections will be -accepted. - -### Wildcard Intentions - -You can use the `*` wildcard to match service names when defining an intention source or destination. The wildcard matches _any_ value, which enables you to set a wide initial scope when configuring intentions. +In the following L4 example, the destination is configured with a `*` wildcard. As a result, traffic from `web` service instances is denied for any service in the datacenter. -The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/consul/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information). - -In the following example, the `web` service cannot connect to _any_ service: - - + ```hcl Kind = "service-intentions" @@ -122,6 +243,17 @@ Sources = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: * + sources: + - name: web + action: deny +``` + ```json { "Kind": "service-intentions", @@ -137,9 +269,9 @@ Sources = [ -The `db` service is configured to deny all connection in the following example: +In the following L4 example, the source is configured with a `*` wildcard. As a result, traffic from any service is denied to `db` service instances. - + ```hcl Kind = "service-intentions" @@ -152,6 +284,17 @@ Sources = [ ] ``` +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: db + sources: + - name: * + action: deny +``` + ```json { "Kind": "service-intentions", @@ -164,178 +307,4 @@ Sources = [ ] } ``` - - - - This example grants Prometheus access to any service in -any namespace. - - - -```hcl -Kind = "service-intentions" -Name = "*" -Namespace = "*" -Sources = [ - { - Name = "prometheus" - Namespace = "monitoring" - Action = "allow" - } -] -``` - -```json -{ - "Kind": "service-intentions", - "Name": "*", - "Namespace": "*", - "Sources": [ - { - "Action": "allow", - "Name": "prometheus", - "Namespace": "monitoring" - } - ] -} -``` - - -### 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 - -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 a -[field](/consul/docs/connect/config-entries/service-intentions#precedence) on the -`service-intentions` configuration entry after it is modified. Precedence cannot be -manually overridden today. - -The numbers in the table above are not stable. Their ordering will remain -fixed but the actual number values may change in the future. - --> - Namespaces are an Enterprise feature. In Consul -OSS the only allowable value for either namespace field is `"default"`. Other -rows in this table are not applicable. - -## Intention Management Permissions - -Intention management can be protected by [ACLs](/consul/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" -} -``` - -```json -{ - "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. - -Supported [proxies] (such as [Envoy]) also cache this data within their own -configuration so that inbound connections or requests require no Consul agent -involvement during authorization. All actions in the data path of connections -happen within the proxy. - -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. Proxies similarly use blocking queries to update -their local configurations quickly. - -Because all the intention data is cached locally, the agents or proxies can -fail static. Even if the agents are severed completely from the Consul servers, -or the proxies are severed completely from their local Consul agent, inbound -connection authorization continues to work indefinitely. Changes to intentions -will not be picked up until the partition heals, but will then automatically -take effect when connectivity is restored. - -[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol -[proxies]: /consul/docs/connect/proxies -[envoy]: /consul/docs/connect/proxies/envoy diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index c03cdbecdc7..ddcfb753c73 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -545,6 +545,10 @@ "title": "Service intentions overview", "path": "connect/intentions/intentions" }, + { + "title": "Create and manage service intentions", + "path": "connect/intentions/intentions-usage" + }, { "title": "Service intentions legacy mode", "path": "connect/intentions/intentions-legacy" From 1204b419ac7d4a46d6ac4cad976d6992c46d3121 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 16:06:41 -0700 Subject: [PATCH 05/23] final intentions overview page --- .../docs/connect/intentions/intentions.mdx | 364 +++--------------- website/data/docs-nav-data.json | 2 +- ...onsul-service-mesh-intentions-overview.svg | 1 + 3 files changed, 59 insertions(+), 308 deletions(-) create mode 100644 website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg diff --git a/website/content/docs/connect/intentions/intentions.mdx b/website/content/docs/connect/intentions/intentions.mdx index b3b0371a93a..d4d14a6def8 100644 --- a/website/content/docs/connect/intentions/intentions.mdx +++ b/website/content/docs/connect/intentions/intentions.mdx @@ -1,229 +1,44 @@ --- layout: docs -page_title: Service Mesh Intentions +page_title: Service mesh intentions overview description: >- - Intentions define communication permissions in the service mesh between microservices. Learn about configuration basics, wildcard intentions, precedence and match order, and protecting intention management with ACLs. + Intentions are access controls that allow or deny incoming requests to services in the mesh. --- -# Service Mesh Intentions +# Service intentions overview --> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and -later. The documentation for the legacy intentions system is -[here](/consul/docs/connect/intentions-legacy). +This topic provides overview information about Consul intentions, which are mechanisms that control traffic communication between services in the Consul service mesh. -Intentions define access control for services via Connect and are used to -control which services may establish connections or make requests. Intentions -can be managed via the API, CLI, or UI. +![Diagram showing how service intentions control access between services](/img/consul-connect/consul-service-mesh-intentions-overview.svg) -Intentions are enforced on inbound connections or requests by the -[proxy](/consul/docs/connect/proxies) or within a [natively integrated -application](/consul/docs/connect/native). +## Intention types -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 application layer 7 (e.g. HTTP): +Intentions control traffic communication between services at the network layer, also called _L7_ traffic, or the application layer, also called _L4 traffic_. The protocol that the destination service uses to send and receive traffic determines the type of authorization the intention can enforce. -- **Identity-based** - All intentions may enforce access based on identities - encoded within [TLS - certificates](/consul/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**. +### L4 traffic intentions -- **Application-aware** - Some intentions may additionally enforce access based - on [L7 request - attributes](/consul/docs/connect/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**. +If the destination service uses TCP or any non-HTTP-based protocol, then intentions can control traffic based on identities encoded in mTLS certificates. Refer to [Mutual transport layer security (mTLS)](/consul/docs/connect/connect-internals#mutual-transport-layer-security-mtls) for additional information. -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. +This implementation allows broad all-or-nothing access control between pairs of services. The only requirement is that the service is aware of the TLS handshake that wraps the opaque TCP connection. -The [intention match API](/consul/api-docs/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. +### L7 traffic intentions -The default intention behavior is defined by the [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. -If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. -If is set to `deny`, then all connections or requests will be denied by default. +If the destination service uses an HTTP-based protocol, then intentions can enforce access based on application-aware request attributes, in addition to identity-based enforcement, to control traffic between services. Refer to[Service intentions configuration reference](/consul/docs/connect/config-entries/service-intentions#permissions) for additional information. -## Intention Basics - -You can define a [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/consul/api-docs/connect/intentions) and [CLI](/consul/commands/intention) documentation for details. - -The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples. - - - -```hcl -Kind = "service-intentions" -Name = "db" -Sources = [ - { - Name = "web" - Action = "deny" - }, - { - Name = "api" - Action = "allow" - } -] -``` - -```json -{ - "Kind": "service-intentions", - "Name": "db", - "Sources": [ - { - "Action": "deny", - "Name": "web" - }, - { - "Action": "allow", - "Name": "api" - } - ] -} -``` - - - -This configuration entry defines two intentions with a common destination of `db`. The -first intention above is a deny intention with a source of `web`. This says -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`. -This says that connections from api to db are allowed and connections will be -accepted. - -### Wildcard Intentions - -You can use the `*` wildcard to match service names when defining an intention source or destination. The wildcard matches _any_ value, which enables you to set a wide initial scope when configuring intentions. - -The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/consul/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information). - -In the following example, the `web` service cannot connect to _any_ service: - - - -```hcl -Kind = "service-intentions" -Name = "*" -Sources = [ - { - Name = "web" - Action = "deny" - } -] -``` - -```json -{ - "Kind": "service-intentions", - "Name": "*", - "Sources": [ - { - "Action": "deny", - "Name": "web" - } - ] -} -``` - - - -The `db` service is configured to deny all connection in the following example: - - - -```hcl -Kind = "service-intentions" -Name = "db" -Sources = [ - { - Name = "*" - Action = "deny" - } -] -``` - -```json -{ - "Kind": "service-intentions", - "Name": "db", - "Sources": [ - { - "Action": "deny", - "Name": "*" - } - ] -} -``` - - - - This example grants Prometheus access to any service in -any namespace. - - - -```hcl -Kind = "service-intentions" -Name = "*" -Namespace = "*" -Sources = [ - { - Name = "prometheus" - Namespace = "monitoring" - Action = "allow" - } -] -``` - -```json -{ - "Kind": "service-intentions", - "Name": "*", - "Namespace": "*", - "Sources": [ - { - "Action": "allow", - "Name": "prometheus", - "Namespace": "monitoring" - } - ] -} -``` - - +## Workflow -### Enforcement +You can manually create intentions from the Consul UI, API, or CLI. You can also enable Consul to dynamically create them by defining traffic routes in service intention configuration entries. Refer to [Create and manage intentions](/consul/docs/connect/intentions/intentions-usage) for details. -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. +### Precedence and match order -For services that define their protocol as HTTP-based, intentions mediate the -ability to **issue new requests**. +Consul processes criteria configured in the service intention configuration entry to match on incoming requests and either allow or deny the request to the destination service. The match criteria may include specific HTTP headers, request methods, or other attributes. Additionally, you can use regular expressions to programmatically match attributes. Refer to [Service intention configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for details. -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. +Consul orders the matches implicitly based the following factors: -## Precedence and Match Order +- Specificity: Incoming requests that match attributes directly have the highest precedence. For example, intentions that are configured to deny traffic from services that send `POST` requests take precedence over intentions that allow traffic from methods configured with the wildcard value `*`. +- Authorization: Consul enforces `deny` over `allow` if match criteria are weighted equally. -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. +The following table describes the order of precedence: | Source Namespace | Source Name | Destination Namespace | Destination Name | Precedence | | ---------------- | ----------- | --------------------- | ---------------- | ---------- | @@ -237,105 +52,40 @@ top to bottom, with larger numbers being evaluated first. | Exact | `*` | `*` | `*` | 2 | | `*` | `*` | `*` | `*` | 1 | -The precedence value can be read from a -[field](/consul/docs/connect/config-entries/service-intentions#precedence) on the -`service-intentions` configuration entry after it is modified. Precedence cannot be -manually overridden today. - -The numbers in the table above are not stable. Their ordering will remain -fixed but the actual number values may change in the future. - --> - Namespaces are an Enterprise feature. In Consul -OSS the only allowable value for either namespace field is `"default"`. Other -rows in this table are not applicable. - -## Intention Management Permissions - -Intention management can be protected by [ACLs](/consul/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" -} -``` - -```json -{ - "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. - -Supported [proxies] (such as [Envoy]) also cache this data within their own -configuration so that inbound connections or requests require no Consul agent -involvement during authorization. All actions in the data path of connections -happen within the proxy. - -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. Proxies similarly use blocking queries to update -their local configurations quickly. - -Because all the intention data is cached locally, the agents or proxies can -fail static. Even if the agents are severed completely from the Consul servers, -or the proxies are severed completely from their local Consul agent, inbound -connection authorization continues to work indefinitely. Changes to intentions -will not be picked up until the partition heals, but will then automatically -take effect when connectivity is restored. - -[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol -[proxies]: /consul/docs/connect/proxies -[envoy]: /consul/docs/connect/proxies/envoy +Consul prints the precedence value to the service intentions configuration entry after it processes the matching criteria. The value is read-only. Refer to +[`Precedence`](/docs/connect/config-entries/service-intentions#precedence) for additional information. + +Namespaces are an Enterprise feature. In Consul OSS, the only allowable value for either namespace field is `"default"`. Other rows in the table are not applicable. + +The [intention match API](/consul/api-docs/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_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. +If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. +If is set to `deny`, then all connections or requests will be denied by default. + +### Enforcement + +The [proxy](/consul/docs/connect/proxies) or [natively-integrated +application](/consul/docs/connect/native) enforces intentions on inbound connections or requests. Only one intention can control authorization between a pair of services at any single point in time. + +L4 intentions mediate the ability to establish new connections. Modifying an intention does not have an effect on existing connections. As a result, changing a connection from `allow` to `deny` does not sever the connection. + +L7 intentions mediate the ability to issue new requests. When an intention is modified, requests received after the modification use the latest intention rules to enforce access. Changing a connection from `allow` to `deny` does not sever the connection, but doing so blocks new requests from being processed. + +### Caching + +The intentions for services registered with a Consul agent are cached locally on the agent. Supported proxies also cache intention data in their own configurations so that they can authorize inbound connections or requests without relying on the Consul agent. All actions in the data path of connections take place within the proxy. + +### Updates + +Consul propagates updates to intentions almost instantly as a result of the continuous blocking query the agent uses. A _blocking query_ is a Consul API feature that uses long polling to wait for potential changes. Refer to [Blocking Queries](/consul/api-docs/features/blocking) for additional information. Proxies also use blocking queries to quickly update their local configurations. + +Because all intention data is cached locally, authorizations for inbound connection persist, even if the agents are completely severed from the Consul servers or if the proxies are completely severed from their local Consul agent. If the connection is severed, Consul automatically applies changes to intentions when connectivity is restored. + +### Intention maintenance + +Services should periodically call the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) to retrieve all relevant intentions for the target destination. After verifying the TLS client certificate, the cached intentions for each incoming connection or request determine if it should be accepted or rejected. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ddcfb753c73..046aa6358ee 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -542,7 +542,7 @@ "title": "Service intentions", "routes": [ { - "title": "Service intentions overview", + "title": "Service mesh intentions overview", "path": "connect/intentions/intentions" }, { diff --git a/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg b/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg new file mode 100644 index 00000000000..a7825c2da5d --- /dev/null +++ b/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg @@ -0,0 +1 @@ + \ No newline at end of file From 7339de87c3cab18a0405bcdf3e77cb1d145931a5 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 16:17:12 -0700 Subject: [PATCH 06/23] fixed old relative links --- .../docs/connect/config-entries/service-intentions.mdx | 2 +- website/content/docs/connect/intentions/intentions-usage.mdx | 4 ++-- website/content/docs/connect/intentions/intentions.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index eb1814075e5..b4e7d58c7c8 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -611,7 +611,7 @@ Refer to [Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for inform #### Values -- Default: If not set, destination service namespace is inherited from the `connectInject.consulNamespaces` configuration. Refer to [ServiceIntentions Special Case (Enterprise)](/docs/k8s/crds#serviceintentions-special-case-enterprise) for details. +- Default: If not set, destination service namespace is inherited from the `connectInject.consulNamespaces` configuration. Refer to [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise) for details. - Data type: String ### `spec.sources[]` diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx index 8ffe0465527..06cc762c5ee 100644 --- a/website/content/docs/connect/intentions/intentions-usage.mdx +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -163,8 +163,8 @@ Refer to the [service intentions configuration entry](/consul/docs/connect/confi L7 intentions defined in a configuration entry are restricted to destination services configured with an HTTP-based protocol as defined in a corresponding -[service defaults configuration entry](/docs/connect/config-entries/service-defaults) -or globally in a [proxy defaults configuration entry](/docs/connect/config-entries/proxy-defaults). +[service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults) +or globally in a [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults). ### Apply the service intentions configuration entry diff --git a/website/content/docs/connect/intentions/intentions.mdx b/website/content/docs/connect/intentions/intentions.mdx index d4d14a6def8..ea24e11e79d 100644 --- a/website/content/docs/connect/intentions/intentions.mdx +++ b/website/content/docs/connect/intentions/intentions.mdx @@ -53,7 +53,7 @@ The following table describes the order of precedence: | `*` | `*` | `*` | `*` | 1 | Consul prints the precedence value to the service intentions configuration entry after it processes the matching criteria. The value is read-only. Refer to -[`Precedence`](/docs/connect/config-entries/service-intentions#precedence) for additional information. +[`Precedence`](/consul/docs/connect/config-entries/service-intentions#precedence) for additional information. Namespaces are an Enterprise feature. In Consul OSS, the only allowable value for either namespace field is `"default"`. Other rows in the table are not applicable. From 9b6b69ffb16816950ac536bfe94c1892a6b885b0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 16:24:08 -0700 Subject: [PATCH 07/23] updated diagram for overview --- .../consul-connect/consul-service-mesh-intentions-overview.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg b/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg index a7825c2da5d..5422f6069b2 100644 --- a/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg +++ b/website/public/img/consul-connect/consul-service-mesh-intentions-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file From 7e612a5154e00af323b877b4a2a5f1b1817f9fee Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 16:57:49 -0700 Subject: [PATCH 08/23] updated links to intentions content --- website/content/api-docs/api-structure.mdx | 2 +- .../content/api-docs/connect/intentions.mdx | 42 +++++++++---------- website/content/commands/connect/envoy.mdx | 2 +- website/content/commands/connect/index.mdx | 2 +- website/content/commands/intention/check.mdx | 4 +- website/content/commands/intention/create.mdx | 4 +- website/content/commands/intention/delete.mdx | 4 +- website/content/commands/intention/get.mdx | 4 +- website/content/commands/intention/index.mdx | 9 ++-- website/content/commands/intention/list.mdx | 4 +- website/content/commands/intention/match.mdx | 4 +- .../docs/connect/cluster-peering/index.mdx | 2 +- .../docs/connect/config-entries/index.mdx | 2 +- .../config-entries/service-defaults.mdx | 4 +- .../docs/connect/connect-internals.mdx | 4 +- website/content/docs/connect/dev.mdx | 2 +- website/content/docs/connect/index.mdx | 28 ++++++------- .../connect/intentions/intentions-legacy.mdx | 3 +- .../content/docs/connect/proxies/envoy.mdx | 2 +- website/content/docs/connect/security.mdx | 2 +- .../docs/connect/transparent-proxy.mdx | 2 +- website/content/docs/k8s/connect/index.mdx | 8 ++-- .../docs/k8s/connect/ingress-gateways.mdx | 2 +- .../docs/lambda/invoke-from-lambda.mdx | 2 +- .../content/docs/security/acl/acl-rules.mdx | 2 +- .../troubleshoot/troubleshoot-services.mdx | 2 +- .../docs/upgrading/upgrade-specific.mdx | 2 +- 27 files changed, 74 insertions(+), 76 deletions(-) diff --git a/website/content/api-docs/api-structure.mdx b/website/content/api-docs/api-structure.mdx index 7a190894129..f686362de35 100644 --- a/website/content/api-docs/api-structure.mdx +++ b/website/content/api-docs/api-structure.mdx @@ -116,7 +116,7 @@ header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which mirrors the current value of the agent's [`acl.default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) option. -This is also the default [intention](/consul/docs/connect/intentions) enforcement +This is also the default [intention](/consul/docs/connect/intentions/intentions) enforcement action if no intention matches. This is returned even if ACLs are disabled. diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index f5b38e082cf..db983f1975a 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -9,7 +9,7 @@ description: |- # Intentions - Connect HTTP API The `/connect/intentions` endpoint provide tools for managing -[intentions](/consul/docs/connect/intentions). +[intentions](/consul/docs/connect/intentions/intentions). -> **1.9.0 and later:** Reading and writing intentions has been migrated to the @@ -48,8 +48,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -154,8 +154,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -251,8 +251,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -305,8 +305,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -377,8 +377,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -440,8 +440,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -527,8 +527,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -582,8 +582,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -638,8 +638,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

@@ -698,8 +698,8 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index c35a0b4feaa..486e7bf2bb2 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -56,7 +56,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]` ACL token from `-token` or the environment and so should be handled as a secret. This token grants the identity of any service it has `service:write` permission for and so can be used to access any upstream service that that service is - allowed to access by [Connect intentions](/consul/docs/connect/intentions). + allowed to access by [service mesh intentions](/consul/docs/connect/intentions/intentions). - `-envoy-version` - The version of envoy that is being started. Default is `1.23.1`. This is required so that the correct configuration can be generated. diff --git a/website/content/commands/connect/index.mdx b/website/content/commands/connect/index.mdx index 166b8ff8352..b390f189935 100644 --- a/website/content/commands/connect/index.mdx +++ b/website/content/commands/connect/index.mdx @@ -10,7 +10,7 @@ description: >- Command: `consul connect` The `connect` command is used to interact with Consul -[Connect](/consul/docs/connect/intentions) subsystems. It exposes commands for +[service mesh](/consul/docs/connect) subsystems. It exposes commands for running the built-in mTLS proxy and viewing/updating the Certificate Authority (CA) configuration. This command is available in Consul 1.2 and later. diff --git a/website/content/commands/intention/check.mdx b/website/content/commands/intention/check.mdx index d9a4d5d328c..75e600c8663 100644 --- a/website/content/commands/intention/check.mdx +++ b/website/content/commands/intention/check.mdx @@ -36,8 +36,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/intention/create.mdx b/website/content/commands/intention/create.mdx index 31f2ae899a9..2a78896f621 100644 --- a/website/content/commands/intention/create.mdx +++ b/website/content/commands/intention/create.mdx @@ -30,8 +30,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/intention/delete.mdx b/website/content/commands/intention/delete.mdx index 87d9d65e905..1dc4d6ad504 100644 --- a/website/content/commands/intention/delete.mdx +++ b/website/content/commands/intention/delete.mdx @@ -24,8 +24,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/intention/get.mdx b/website/content/commands/intention/get.mdx index 68dd744404f..5507b81eb27 100644 --- a/website/content/commands/intention/get.mdx +++ b/website/content/commands/intention/get.mdx @@ -29,8 +29,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/intention/index.mdx b/website/content/commands/intention/index.mdx index 9246ef9e050..a4a7462ec4b 100644 --- a/website/content/commands/intention/index.mdx +++ b/website/content/commands/intention/index.mdx @@ -10,14 +10,13 @@ description: >- Command: `consul intention` The `intention` command is used to interact with Connect -[intentions](/consul/docs/connect/intentions). It exposes commands for +[intentions](/consul/docs/connect/intentions/intentions). It exposes commands for creating, updating, reading, deleting, checking, and managing intentions. This command is available in Consul 1.2 and later. -Intentions are managed primarily via -[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config -entries after Consul 1.9. Intentions may also be managed via the [HTTP -API](/consul/api-docs/connect/intentions). +Use the +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry or the [HTTP +API](/consul/api-docs/connect/intentions) to manage intentions. ~> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of using the [config entry CLI command](/consul/commands/config/write). To create an diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 928f416095d..4353349c742 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -24,8 +24,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/commands/intention/match.mdx b/website/content/commands/intention/match.mdx index e0bbfc1222e..d5280fb6c9b 100644 --- a/website/content/commands/intention/match.mdx +++ b/website/content/commands/intention/match.mdx @@ -29,8 +29,8 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - - Intention Management Permissions + + ACL requirements for intentions {' '} for more details.

diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index f8e1c18caf3..7572dd8577c 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -25,7 +25,7 @@ Cluster peering leverages several components of Consul's architecture to enforce - A _peering token_ contains an embedded secret that securely establishes communication when shared symetrically between datacenters. Sharing this token enables each datacenter's server agents to recognize requests from authorized peers, similar to how the [gossip encryption key secures agent LAN gossip](/consul/docs/security/encryption#gossip-encryption). - A _mesh gateway_ encrypts outgoing traffic, decrypts incoming traffic, and directs traffic to healthy services. Consul's service mesh features must be enabled in order to use mesh gateways. Mesh gateways support the specific admin partitions they are deployed on. Refer to [Mesh gateways](/consul/docs/connect/gateways/mesh-gateway) for more information. - An _exported service_ communicates with downstreams deployed in other admin partitions. They are explicitly defined in an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services). -- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request. +- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request. ### Compared with WAN federation diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index 6d29a27cc38..a8bf641d176 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -27,7 +27,7 @@ The following configuration entries are supported: defaults for all the instances of a given service - [Service Intentions](/consul/docs/connect/config-entries/service-intentions) - defines - the [intentions](/consul/docs/connect/intentions) for a destination service + the [intentions](/consul/docs/connect/intentions/intentions) for a destination service - [Service Resolver](/consul/docs/connect/config-entries/service-resolver) - matches service instances with a specific Connect upstream discovery requests diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index e1e15cf7acb..0717c19733f 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -459,7 +459,7 @@ Specifies the default protocol for the service. In service mesh use cases, the ` - [observability](/consul/docs/connect/observability) - [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) - [service router configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions) +- [L7 intentions](/consul/docs/connect/intentions/intentions) You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. @@ -831,7 +831,7 @@ Specifies the default protocol for the service. In service service mesh use case - [observability](/consul/docs/connect/observability) - [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) - [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions) +- [L7 intentions](/consul/docs/connect/intentions/intentions) You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index 826a2bde222..eb561ff1e79 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -39,7 +39,7 @@ The destination service verifies the client certificate against the [public CA bundle](/consul/api-docs/connect/ca#list-ca-root-certificates). After verifying the certificate, the next step depends upon the configured application protocol of the destination service. TCP (L4) services must authorize incoming _connections_ -against the configured set of Consul [intentions](/consul/docs/connect/intentions), +against the configured set of Consul [intentions](/consul/docs/connect/intentions/intentions), whereas HTTP (L7) services must authorize incoming _requests_ against those same intentions. If the intention check responds successfully, the connection/request is established. Otherwise the connection/request is @@ -98,7 +98,7 @@ A sidecar proxy's [upstream configuration](/consul/docs/connect/registration/ser may specify an alternative datacenter or a prepared query that can address services in multiple datacenters (such as the [geo failover](/consul/tutorials/developer-discovery/automate-geo-failover) pattern). -[Intentions](/consul/docs/connect/intentions) verify connections between services by +[Intentions](/consul/docs/connect/intentions/intentions) verify connections between services by source and destination name seamlessly across datacenters. Connections can be made via gateways to enable communicating across network diff --git a/website/content/docs/connect/dev.mdx b/website/content/docs/connect/dev.mdx index 6f494bc3751..86719f68121 100644 --- a/website/content/docs/connect/dev.mdx +++ b/website/content/docs/connect/dev.mdx @@ -15,7 +15,7 @@ for this task on any machine with access to a Consul agent (local or remote). Restricting access to services only via Connect ensures that the only way to connect to a service is through valid authorization of the -[intentions](/consul/docs/connect/intentions). This can extend to developers +[intentions](/consul/docs/connect/intentions/intentions). This can extend to developers and operators, too. ## Connecting to Connect-only Services diff --git a/website/content/docs/connect/index.mdx b/website/content/docs/connect/index.mdx index cbd2903a331..83d8317ccc6 100644 --- a/website/content/docs/connect/index.mdx +++ b/website/content/docs/connect/index.mdx @@ -5,7 +5,7 @@ description: >- Consul’s service mesh makes application and microservice networking secure and observable with identity-based authentication, mutual TLS (mTLS) encryption, and explicit service-to-service authorization enforced by sidecar proxies. Learn how Consul’s service mesh works and get started on VMs or Kubernetes. --- -# Consul Service Mesh +# Consul service mesh Consul Service Mesh provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Consul Connect is used interchangeably @@ -25,30 +25,30 @@ Review the video below to learn more about Consul Connect from HashiCorp's co-fo height="315" > -## Application Security +## Application security -Connect enables secure deployment best-practices with automatic +Consul service mesh enables secure deployment best-practices with automatic service-to-service encryption, and identity-based authorization. -Connect uses the registered service identity (rather than IP addresses) to -enforce access control with [intentions](/consul/docs/connect/intentions). This -makes it easier to reason about access control and enables services to be -rescheduled by orchestrators including Kubernetes and Nomad. Intention -enforcement is network agnostic, so Connect works with physical networks, cloud +Consul uses the registered service identity, rather than IP addresses, to +enforce access control with [intentions](/consul/docs/connect/intentions/intentions). This +makes it easier to control access and enables services to be +rescheduled by orchestrators, including Kubernetes and Nomad. Intention +enforcement is network agnostic, so Consul service mesh works with physical networks, cloud networks, software-defined networks, cross-cloud, and more. ## Observability -One of the key benefits of Consul Connect is the uniform and consistent view it can +One of the key benefits of Consul service mesh is the uniform and consistent view it can provide of all the services on your network, irrespective of their different -programming languages and frameworks. When you configure Consul Connect to use -sidecar proxies, those proxies "see" all service-to-service traffic and can -collect data about it. Consul Connect can configure Envoy proxies to collect +programming languages and frameworks. When you configure Consul service mesh to use +sidecar proxies, those proxies see all service-to-service traffic and can +collect data about it. Consul service mesh can configure Envoy proxies to collect layer 7 metrics and export them to tools like Prometheus. Correctly instrumented applications can also send open tracing data through Envoy. -## Getting Started With Consul Service Mesh +## Getting started with Consul service mesh -There are several ways to try Connect in different environments. +Complete the following tutorials try Consul service mesh in different environments: - The [Getting Started with Consul Service Mesh collection](/consul/tutorials/kubernetes-deploy/service-mesh?utm_source=docs) walks you through installing Consul as service mesh for Kubernetes using the Helm diff --git a/website/content/docs/connect/intentions/intentions-legacy.mdx b/website/content/docs/connect/intentions/intentions-legacy.mdx index 0e9e991d37c..b79d34a543a 100644 --- a/website/content/docs/connect/intentions/intentions-legacy.mdx +++ b/website/content/docs/connect/intentions/intentions-legacy.mdx @@ -8,8 +8,7 @@ description: >- # 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](/consul/docs/connect/intentions). +and before. If you are using version 1.9.0 or later, refer to the [current intentions documentation](/consul/docs/connect/intentions). Intentions define access control for services via Connect and are used to control which services may establish connections. Intentions can be diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 61ea0bf738c..6bc0a7d15fa 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -92,7 +92,7 @@ responsibility for correctly configuring Envoy and ensuring version support etc. ## Intention Enforcement -[Intentions](/consul/docs/connect/intentions) are enforced using Envoy's RBAC filters. Depending on the +[Intentions](/consul/docs/connect/intentions/intentions) are enforced using Envoy's RBAC filters. Depending on the configured [protocol](/consul/docs/connect/config-entries/service-defaults#protocol) of the proxied service, intentions are either enforced per-connection (L4) using a network filter, or per-request (L7) using an HTTP filter. diff --git a/website/content/docs/connect/security.mdx b/website/content/docs/connect/security.mdx index 31fa331da63..ab8f122634a 100644 --- a/website/content/docs/connect/security.mdx +++ b/website/content/docs/connect/security.mdx @@ -31,7 +31,7 @@ of Consul. Consul must be configured to use ACLs with a default deny policy. This forces all requests to have explicit anonymous access or provide an ACL token. The configuration also forces all service-to-service communication to be explicitly -allowed via an allow [intention](/consul/docs/connect/intentions). +allowed via an allow [intention](/consul/docs/connect/intentions/intentions). To learn how to enable ACLs, please see the [tutorial on ACLs](/consul/tutorials/security/access-control-setup-production). diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx index cf0b56c96e4..f8fe9761ec3 100644 --- a/website/content/docs/connect/transparent-proxy.mdx +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -40,7 +40,7 @@ Your network must meet the following environment and software requirements to us * Transparent proxy is available for Kubernetes environments. * Consul 1.10.0+ * Consul Helm chart 0.32.0+. If you want to use the Consul CNI plugin to redirect traffic, Helm chart 0.48.0+ is required. Refer to [Enable the Consul CNI plugin](#enable-the-consul-cni-plugin) for additional information. -* [Service intentions](/consul/docs/connect/intentions) must be configured to allow communication between intended services. +* [Service intentions](/consul/docs/connect/intentions/intentions) must be configured to allow communication between intended services. * The `ip_tables` kernel module must be running on all worker nodes within a Kubernetes cluster. If you are using the `modprobe` Linux utility, for example, issue the following command: `$ modprobe ip_tables` diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx index 7e30ab2be89..108093fbc20 100644 --- a/website/content/docs/k8s/connect/index.mdx +++ b/website/content/docs/k8s/connect/index.mdx @@ -165,7 +165,7 @@ spec: By default when ACLs are enabled or when ACLs default policy is `allow`, Consul will automatically configure proxies with all upstreams from the same datacenter. When ACLs are enabled with default `deny` policy, -you must supply an [intention](/consul/docs/connect/intentions) to tell Consul which upstream you need to talk to. +you must supply an [intention](/consul/docs/connect/intentions/intentions) to tell Consul which upstream you need to talk to. When upstreams are specified explicitly with the [`consul.hashicorp.com/connect-service-upstreams` annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams), @@ -184,9 +184,9 @@ $ kubectl exec deploy/static-client -- curl --silent http://static-server/ "hello world" ``` -We can control access to the server using [intentions](/consul/docs/connect/intentions). +We can control access to the server using [intentions](/consul/docs/connect/intentions/intentions). If you use the Consul UI or [CLI](/consul/commands/intention/create) to -create a deny [intention](/consul/docs/connect/intentions) between +create a deny [intention](/consul/docs/connect/intentions/intentions) between "static-client" and "static-server", connections are immediately rejected without updating either of the running pods. You can then remove this intention to allow connections again. @@ -536,7 +536,7 @@ There are three options available: When [transparent proxy](/consul/docs/connect/transparent-proxy) is enabled and ACLs are disabled, the upstreams will be configured automatically across Consul namespaces. -When ACLs are enabled, you must configure it by specifying an [intention](/consul/docs/connect/intentions), +When ACLs are enabled, you must configure it by specifying an [intention](/consul/docs/connect/intentions/intentions), allowing services across Consul namespaces to talk to each other. If you wish to specify an upstream explicitly via the `consul.hashicorp.com/connect-service-upstreams` annotation, diff --git a/website/content/docs/k8s/connect/ingress-gateways.mdx b/website/content/docs/k8s/connect/ingress-gateways.mdx index b971484ecc1..67b666e870e 100644 --- a/website/content/docs/k8s/connect/ingress-gateways.mdx +++ b/website/content/docs/k8s/connect/ingress-gateways.mdx @@ -153,7 +153,7 @@ If TLS is enabled, use [https://localhost:8501/ui/dc1/services/ingress-gateway/i ## Defining an Intention -If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/consul/docs/connect/intentions) +If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/consul/docs/connect/intentions/intentions) to allow the ingress gateway to route to the upstream services defined in the `IngressGateway` resource (in the example above the upstream service is `static-server`). To create an intention that allows the ingress gateway to route to the service `static-server`, create a [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) diff --git a/website/content/docs/lambda/invoke-from-lambda.mdx b/website/content/docs/lambda/invoke-from-lambda.mdx index a7ec2913865..6b2aa8d1c18 100644 --- a/website/content/docs/lambda/invoke-from-lambda.mdx +++ b/website/content/docs/lambda/invoke-from-lambda.mdx @@ -264,7 +264,7 @@ Define the following environment variables in your Lambda functions to configure ## Invoke the Lambda function -If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service Mesh Intentions](/consul/docs/connect/intentions) for additional information. +If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service mesh intentions](/consul/docs/connect/intentions/intentions) for additional information. There are several ways to invoke Lambda functions. In the following example, the `aws lambda invoke` CLI command invokes the function: diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 3b63e327a20..fc834d07422 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -869,7 +869,7 @@ service "app" { -Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) +Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for more information about managing intentions access with service rules. ## Session Rules diff --git a/website/content/docs/troubleshoot/troubleshoot-services.mdx b/website/content/docs/troubleshoot/troubleshoot-services.mdx index 92a66881475..a72ef64a493 100644 --- a/website/content/docs/troubleshoot/troubleshoot-services.mdx +++ b/website/content/docs/troubleshoot/troubleshoot-services.mdx @@ -42,7 +42,7 @@ For more information about using Envoy proxies with Consul, refer to [Envoy prox When troubleshooting service-to-service communication issues, be aware of the following constraints: -- The troubleshooting tool does not check service intentions. For more information about intentions, including precedence and match order, refer to [service mesh intentions](/consul/docs/connect/intentions). +- The troubleshooting tool does not check service intentions. For more information about intentions, including precedence and match order, refer to [service mesh intentions](/consul/docs/connect/intentions/intentions). - The troubleshooting tool validates one direct connection between a downstream service and an upstream service. You must run the `consul troubleshoot` command with the Envoy ID for an individual upstream service. It does support validating multiple connections simultaneously. - The troubleshooting tool only validates Envoy configurations for sidecar proxies. As a result, the troubleshooting tool does not validate Envoy configurations on upstream proxies such as mesh gateways and terminating gateways. diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 06997760e35..611eb7a0a8b 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -624,7 +624,7 @@ namespace with a query parameter of `?ns=*`. #### Migration Upgrading to Consul 1.9.0 will trigger a one-time background migration of -[intentions](/consul/docs/connect/intentions) into an equivalent set of +[intentions](/consul/docs/connect/intentions/intentions) into an equivalent set of [`service-intentions`](/consul/docs/connect/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+. From 22a90662acbd425946368be49f073125f9414412 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Mar 2023 17:05:18 -0700 Subject: [PATCH 09/23] fixed typo in updated links --- .../content/api-docs/connect/intentions.mdx | 20 +++++++++---------- website/content/commands/intention/check.mdx | 2 +- website/content/commands/intention/create.mdx | 2 +- website/content/commands/intention/delete.mdx | 2 +- website/content/commands/intention/get.mdx | 2 +- website/content/commands/intention/list.mdx | 2 +- website/content/commands/intention/match.mdx | 2 +- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index db983f1975a..68dbc513509 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -48,7 +48,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -154,7 +154,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -251,7 +251,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -305,7 +305,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -377,7 +377,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -440,7 +440,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -527,7 +527,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -582,7 +582,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -638,7 +638,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. @@ -698,7 +698,7 @@ The table below shows this endpoint's support for

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/check.mdx b/website/content/commands/intention/check.mdx index 75e600c8663..3d2780e3290 100644 --- a/website/content/commands/intention/check.mdx +++ b/website/content/commands/intention/check.mdx @@ -36,7 +36,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/create.mdx b/website/content/commands/intention/create.mdx index 2a78896f621..c98953ca9f4 100644 --- a/website/content/commands/intention/create.mdx +++ b/website/content/commands/intention/create.mdx @@ -30,7 +30,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/delete.mdx b/website/content/commands/intention/delete.mdx index 1dc4d6ad504..780fd6f9af3 100644 --- a/website/content/commands/intention/delete.mdx +++ b/website/content/commands/intention/delete.mdx @@ -24,7 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/get.mdx b/website/content/commands/intention/get.mdx index 5507b81eb27..3b688963512 100644 --- a/website/content/commands/intention/get.mdx +++ b/website/content/commands/intention/get.mdx @@ -29,7 +29,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 4353349c742..21a87504a97 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -24,7 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. diff --git a/website/content/commands/intention/match.mdx b/website/content/commands/intention/match.mdx index d5280fb6c9b..5d76218d0f5 100644 --- a/website/content/commands/intention/match.mdx +++ b/website/content/commands/intention/match.mdx @@ -29,7 +29,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint

1 Intention ACL rules are specified as part of a{' '} service rule. See{' '} - + ACL requirements for intentions {' '} for more details. From ad6e9406711a19db201aa4c6da76b9d906b277fb Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 11:43:19 -0700 Subject: [PATCH 10/23] rename intentions overview page file to index --- .../content/docs/connect/intentions/{intentions.mdx => index.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename website/content/docs/connect/intentions/{intentions.mdx => index.mdx} (100%) diff --git a/website/content/docs/connect/intentions/intentions.mdx b/website/content/docs/connect/intentions/index.mdx similarity index 100% rename from website/content/docs/connect/intentions/intentions.mdx rename to website/content/docs/connect/intentions/index.mdx From b345201dbbf70d75a304945e34341b9a551259c9 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 11:50:53 -0700 Subject: [PATCH 11/23] rollback link updates to intentions overview --- website/content/api-docs/api-structure.mdx | 2 +- website/content/api-docs/connect/intentions.mdx | 2 +- website/content/commands/connect/envoy.mdx | 2 +- website/content/commands/intention/index.mdx | 2 +- .../content/docs/connect/cluster-peering/index.mdx | 2 +- .../content/docs/connect/config-entries/index.mdx | 2 +- .../docs/connect/config-entries/service-defaults.mdx | 4 ++-- .../connect/config-entries/service-intentions.mdx | 2 +- website/content/docs/connect/connect-internals.mdx | 4 ++-- website/content/docs/connect/dev.mdx | 2 +- website/content/docs/connect/index.mdx | 2 +- website/content/docs/connect/proxies/envoy.mdx | 2 +- website/content/docs/connect/security.mdx | 2 +- website/content/docs/connect/transparent-proxy.mdx | 2 +- website/content/docs/k8s/connect/index.mdx | 12 ++++++------ .../content/docs/k8s/connect/ingress-gateways.mdx | 2 +- website/content/docs/lambda/invoke-from-lambda.mdx | 2 +- .../docs/troubleshoot/troubleshoot-services.mdx | 2 +- website/content/docs/upgrading/upgrade-specific.mdx | 2 +- 19 files changed, 26 insertions(+), 26 deletions(-) diff --git a/website/content/api-docs/api-structure.mdx b/website/content/api-docs/api-structure.mdx index f686362de35..7a190894129 100644 --- a/website/content/api-docs/api-structure.mdx +++ b/website/content/api-docs/api-structure.mdx @@ -116,7 +116,7 @@ header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which mirrors the current value of the agent's [`acl.default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) option. -This is also the default [intention](/consul/docs/connect/intentions/intentions) enforcement +This is also the default [intention](/consul/docs/connect/intentions) enforcement action if no intention matches. This is returned even if ACLs are disabled. diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index 68dbc513509..23ccebdbd81 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -9,7 +9,7 @@ description: |- # Intentions - Connect HTTP API The `/connect/intentions` endpoint provide tools for managing -[intentions](/consul/docs/connect/intentions/intentions). +[intentions](/consul/docs/connect/intentions). -> **1.9.0 and later:** Reading and writing intentions has been migrated to the diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index 486e7bf2bb2..c9e0ffb2e93 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -56,7 +56,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]` ACL token from `-token` or the environment and so should be handled as a secret. This token grants the identity of any service it has `service:write` permission for and so can be used to access any upstream service that that service is - allowed to access by [service mesh intentions](/consul/docs/connect/intentions/intentions). + allowed to access by [service mesh intentions](/consul/docs/connect/intentions). - `-envoy-version` - The version of envoy that is being started. Default is `1.23.1`. This is required so that the correct configuration can be generated. diff --git a/website/content/commands/intention/index.mdx b/website/content/commands/intention/index.mdx index a4a7462ec4b..d3e4fc56c43 100644 --- a/website/content/commands/intention/index.mdx +++ b/website/content/commands/intention/index.mdx @@ -10,7 +10,7 @@ description: >- Command: `consul intention` The `intention` command is used to interact with Connect -[intentions](/consul/docs/connect/intentions/intentions). It exposes commands for +[intentions](/consul/docs/connect/intentions). It exposes commands for creating, updating, reading, deleting, checking, and managing intentions. This command is available in Consul 1.2 and later. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 7572dd8577c..f8e1c18caf3 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -25,7 +25,7 @@ Cluster peering leverages several components of Consul's architecture to enforce - A _peering token_ contains an embedded secret that securely establishes communication when shared symetrically between datacenters. Sharing this token enables each datacenter's server agents to recognize requests from authorized peers, similar to how the [gossip encryption key secures agent LAN gossip](/consul/docs/security/encryption#gossip-encryption). - A _mesh gateway_ encrypts outgoing traffic, decrypts incoming traffic, and directs traffic to healthy services. Consul's service mesh features must be enabled in order to use mesh gateways. Mesh gateways support the specific admin partitions they are deployed on. Refer to [Mesh gateways](/consul/docs/connect/gateways/mesh-gateway) for more information. - An _exported service_ communicates with downstreams deployed in other admin partitions. They are explicitly defined in an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services). -- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request. +- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request. ### Compared with WAN federation diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index a8bf641d176..6d29a27cc38 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -27,7 +27,7 @@ The following configuration entries are supported: defaults for all the instances of a given service - [Service Intentions](/consul/docs/connect/config-entries/service-intentions) - defines - the [intentions](/consul/docs/connect/intentions/intentions) for a destination service + the [intentions](/consul/docs/connect/intentions) for a destination service - [Service Resolver](/consul/docs/connect/config-entries/service-resolver) - matches service instances with a specific Connect upstream discovery requests diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 0717c19733f..75b8497c98c 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -459,7 +459,7 @@ Specifies the default protocol for the service. In service mesh use cases, the ` - [observability](/consul/docs/connect/observability) - [service splitter configuration entry](/consul/docs/connect/config-entries/service-splitter) - [service router configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions/intentions) +- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions) You can set the global protocol for proxies in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#default-protocol) configuration entry, but the protocol specified in the `service-defaults` configuration entry overrides the `proxy-defaults` configuration. @@ -831,7 +831,7 @@ Specifies the default protocol for the service. In service service mesh use case - [observability](/consul/docs/connect/observability) - [`service-splitter` configuration entry](/consul/docs/connect/config-entries/service-splitter) - [`service-router` configuration entry](/consul/docs/connect/config-entries/service-router) -- [L7 intentions](/consul/docs/connect/intentions/intentions) +- [L7 intentions](/consul/docs/connect/intentions/index#l7-traffic-intentions) You can set the global protocol for proxies in the [`ProxyDefaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults#default-protocol), but the protocol specified in the `ServiceDefaults` configuration entry overrides the `ProxyDefaults` configuration. diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index b4e7d58c7c8..cede6093427 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -7,7 +7,7 @@ description: >- # Service intentions configuration entry reference -This topic provides reference information for the service intentions configuration entry. Intentions are configurations for controlling access between services in the service mesh. A single service intentions configuration entry specifies one destination service and one or more L4 traffic sources, L7 traffic sources, or combination of traffic sources. Refer to [Service mesh intentions overview](/consul/docs/connect/intentions/intentions) for additional information. +This topic provides reference information for the service intentions configuration entry. Intentions are configurations for controlling access between services in the service mesh. A single service intentions configuration entry specifies one destination service and one or more L4 traffic sources, L7 traffic sources, or combination of traffic sources. Refer to [Service mesh intentions overview](/consul/docs/connect/intentions) for additional information. ## Configuration model diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index eb561ff1e79..826a2bde222 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -39,7 +39,7 @@ The destination service verifies the client certificate against the [public CA bundle](/consul/api-docs/connect/ca#list-ca-root-certificates). After verifying the certificate, the next step depends upon the configured application protocol of the destination service. TCP (L4) services must authorize incoming _connections_ -against the configured set of Consul [intentions](/consul/docs/connect/intentions/intentions), +against the configured set of Consul [intentions](/consul/docs/connect/intentions), whereas HTTP (L7) services must authorize incoming _requests_ against those same intentions. If the intention check responds successfully, the connection/request is established. Otherwise the connection/request is @@ -98,7 +98,7 @@ A sidecar proxy's [upstream configuration](/consul/docs/connect/registration/ser may specify an alternative datacenter or a prepared query that can address services in multiple datacenters (such as the [geo failover](/consul/tutorials/developer-discovery/automate-geo-failover) pattern). -[Intentions](/consul/docs/connect/intentions/intentions) verify connections between services by +[Intentions](/consul/docs/connect/intentions) verify connections between services by source and destination name seamlessly across datacenters. Connections can be made via gateways to enable communicating across network diff --git a/website/content/docs/connect/dev.mdx b/website/content/docs/connect/dev.mdx index 86719f68121..6f494bc3751 100644 --- a/website/content/docs/connect/dev.mdx +++ b/website/content/docs/connect/dev.mdx @@ -15,7 +15,7 @@ for this task on any machine with access to a Consul agent (local or remote). Restricting access to services only via Connect ensures that the only way to connect to a service is through valid authorization of the -[intentions](/consul/docs/connect/intentions/intentions). This can extend to developers +[intentions](/consul/docs/connect/intentions). This can extend to developers and operators, too. ## Connecting to Connect-only Services diff --git a/website/content/docs/connect/index.mdx b/website/content/docs/connect/index.mdx index 83d8317ccc6..7c7235569d3 100644 --- a/website/content/docs/connect/index.mdx +++ b/website/content/docs/connect/index.mdx @@ -30,7 +30,7 @@ Review the video below to learn more about Consul Connect from HashiCorp's co-fo Consul service mesh enables secure deployment best-practices with automatic service-to-service encryption, and identity-based authorization. Consul uses the registered service identity, rather than IP addresses, to -enforce access control with [intentions](/consul/docs/connect/intentions/intentions). This +enforce access control with [intentions](/consul/docs/connect/intentions). This makes it easier to control access and enables services to be rescheduled by orchestrators, including Kubernetes and Nomad. Intention enforcement is network agnostic, so Consul service mesh works with physical networks, cloud diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 6bc0a7d15fa..61ea0bf738c 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -92,7 +92,7 @@ responsibility for correctly configuring Envoy and ensuring version support etc. ## Intention Enforcement -[Intentions](/consul/docs/connect/intentions/intentions) are enforced using Envoy's RBAC filters. Depending on the +[Intentions](/consul/docs/connect/intentions) are enforced using Envoy's RBAC filters. Depending on the configured [protocol](/consul/docs/connect/config-entries/service-defaults#protocol) of the proxied service, intentions are either enforced per-connection (L4) using a network filter, or per-request (L7) using an HTTP filter. diff --git a/website/content/docs/connect/security.mdx b/website/content/docs/connect/security.mdx index ab8f122634a..31fa331da63 100644 --- a/website/content/docs/connect/security.mdx +++ b/website/content/docs/connect/security.mdx @@ -31,7 +31,7 @@ of Consul. Consul must be configured to use ACLs with a default deny policy. This forces all requests to have explicit anonymous access or provide an ACL token. The configuration also forces all service-to-service communication to be explicitly -allowed via an allow [intention](/consul/docs/connect/intentions/intentions). +allowed via an allow [intention](/consul/docs/connect/intentions). To learn how to enable ACLs, please see the [tutorial on ACLs](/consul/tutorials/security/access-control-setup-production). diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx index f8fe9761ec3..cf0b56c96e4 100644 --- a/website/content/docs/connect/transparent-proxy.mdx +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -40,7 +40,7 @@ Your network must meet the following environment and software requirements to us * Transparent proxy is available for Kubernetes environments. * Consul 1.10.0+ * Consul Helm chart 0.32.0+. If you want to use the Consul CNI plugin to redirect traffic, Helm chart 0.48.0+ is required. Refer to [Enable the Consul CNI plugin](#enable-the-consul-cni-plugin) for additional information. -* [Service intentions](/consul/docs/connect/intentions/intentions) must be configured to allow communication between intended services. +* [Service intentions](/consul/docs/connect/intentions) must be configured to allow communication between intended services. * The `ip_tables` kernel module must be running on all worker nodes within a Kubernetes cluster. If you are using the `modprobe` Linux utility, for example, issue the following command: `$ modprobe ip_tables` diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx index 108093fbc20..00e5c8e9383 100644 --- a/website/content/docs/k8s/connect/index.mdx +++ b/website/content/docs/k8s/connect/index.mdx @@ -165,7 +165,7 @@ spec: By default when ACLs are enabled or when ACLs default policy is `allow`, Consul will automatically configure proxies with all upstreams from the same datacenter. When ACLs are enabled with default `deny` policy, -you must supply an [intention](/consul/docs/connect/intentions/intentions) to tell Consul which upstream you need to talk to. +you must supply an [intention](/consul/docs/connect/intentions) to tell Consul which upstream you need to talk to. When upstreams are specified explicitly with the [`consul.hashicorp.com/connect-service-upstreams` annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams), @@ -175,18 +175,18 @@ upstream. This is analogous to the standard Kubernetes service environment varia point instead to the correct local proxy port to establish connections via Connect. -We can verify access to the static text server using `kubectl exec`. +You can verify access to the static text server using `kubectl exec`. Because transparent proxy is enabled by default, -we use Kubernetes DNS to connect to our desired upstream. +use Kubernetes DNS to connect to your desired upstream. ```shell-session $ kubectl exec deploy/static-client -- curl --silent http://static-server/ "hello world" ``` -We can control access to the server using [intentions](/consul/docs/connect/intentions/intentions). +You can control access to the server using [intentions](/consul/docs/connect/intentions). If you use the Consul UI or [CLI](/consul/commands/intention/create) to -create a deny [intention](/consul/docs/connect/intentions/intentions) between +deny communication between "static-client" and "static-server", connections are immediately rejected without updating either of the running pods. You can then remove this intention to allow connections again. @@ -536,7 +536,7 @@ There are three options available: When [transparent proxy](/consul/docs/connect/transparent-proxy) is enabled and ACLs are disabled, the upstreams will be configured automatically across Consul namespaces. -When ACLs are enabled, you must configure it by specifying an [intention](/consul/docs/connect/intentions/intentions), +When ACLs are enabled, you must configure it by specifying an [intention](/consul/docs/connect/intentions), allowing services across Consul namespaces to talk to each other. If you wish to specify an upstream explicitly via the `consul.hashicorp.com/connect-service-upstreams` annotation, diff --git a/website/content/docs/k8s/connect/ingress-gateways.mdx b/website/content/docs/k8s/connect/ingress-gateways.mdx index 67b666e870e..b971484ecc1 100644 --- a/website/content/docs/k8s/connect/ingress-gateways.mdx +++ b/website/content/docs/k8s/connect/ingress-gateways.mdx @@ -153,7 +153,7 @@ If TLS is enabled, use [https://localhost:8501/ui/dc1/services/ingress-gateway/i ## Defining an Intention -If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/consul/docs/connect/intentions/intentions) +If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/consul/docs/connect/intentions) to allow the ingress gateway to route to the upstream services defined in the `IngressGateway` resource (in the example above the upstream service is `static-server`). To create an intention that allows the ingress gateway to route to the service `static-server`, create a [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) diff --git a/website/content/docs/lambda/invoke-from-lambda.mdx b/website/content/docs/lambda/invoke-from-lambda.mdx index 6b2aa8d1c18..4c29e4b8d9c 100644 --- a/website/content/docs/lambda/invoke-from-lambda.mdx +++ b/website/content/docs/lambda/invoke-from-lambda.mdx @@ -264,7 +264,7 @@ Define the following environment variables in your Lambda functions to configure ## Invoke the Lambda function -If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service mesh intentions](/consul/docs/connect/intentions/intentions) for additional information. +If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service mesh intentions](/consul/docs/connect/intentions) for additional information. There are several ways to invoke Lambda functions. In the following example, the `aws lambda invoke` CLI command invokes the function: diff --git a/website/content/docs/troubleshoot/troubleshoot-services.mdx b/website/content/docs/troubleshoot/troubleshoot-services.mdx index a72ef64a493..92a66881475 100644 --- a/website/content/docs/troubleshoot/troubleshoot-services.mdx +++ b/website/content/docs/troubleshoot/troubleshoot-services.mdx @@ -42,7 +42,7 @@ For more information about using Envoy proxies with Consul, refer to [Envoy prox When troubleshooting service-to-service communication issues, be aware of the following constraints: -- The troubleshooting tool does not check service intentions. For more information about intentions, including precedence and match order, refer to [service mesh intentions](/consul/docs/connect/intentions/intentions). +- The troubleshooting tool does not check service intentions. For more information about intentions, including precedence and match order, refer to [service mesh intentions](/consul/docs/connect/intentions). - The troubleshooting tool validates one direct connection between a downstream service and an upstream service. You must run the `consul troubleshoot` command with the Envoy ID for an individual upstream service. It does support validating multiple connections simultaneously. - The troubleshooting tool only validates Envoy configurations for sidecar proxies. As a result, the troubleshooting tool does not validate Envoy configurations on upstream proxies such as mesh gateways and terminating gateways. diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 611eb7a0a8b..06997760e35 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -624,7 +624,7 @@ namespace with a query parameter of `?ns=*`. #### Migration Upgrading to Consul 1.9.0 will trigger a one-time background migration of -[intentions](/consul/docs/connect/intentions/intentions) into an equivalent set of +[intentions](/consul/docs/connect/intentions) into an equivalent set of [`service-intentions`](/consul/docs/connect/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+. From 8cd42d6d9060f0159d2a9d38b73ca8e034d4a180 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 11:52:59 -0700 Subject: [PATCH 12/23] fixed nav --- website/data/docs-nav-data.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 046aa6358ee..cb312efe94d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -543,7 +543,7 @@ "routes": [ { "title": "Service mesh intentions overview", - "path": "connect/intentions/intentions" + "path": "connect/intentions" }, { "title": "Create and manage service intentions", From 0a45d1e2c930d7ae1a3f2696b5625bd3342e4112 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 12:18:39 -0700 Subject: [PATCH 13/23] Updated custom HTML in API and CLI pages to MD --- .../content/api-docs/connect/intentions.mdx | 110 ++---------------- website/content/commands/intention/check.mdx | 11 +- website/content/commands/intention/create.mdx | 11 +- website/content/commands/intention/delete.mdx | 11 +- website/content/commands/intention/get.mdx | 11 +- website/content/commands/intention/list.mdx | 11 +- 6 files changed, 15 insertions(+), 150 deletions(-) diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index 23ccebdbd81..b598eb40f57 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -43,16 +43,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention create -replace`](/consul/commands/intention/create#replace). @@ -149,16 +140,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention create`](/consul/commands/intention/create). @@ -246,16 +228,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint. Additional parameters unique to this endpoint include: @@ -300,16 +273,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). @@ -372,16 +336,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). @@ -435,16 +390,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention list`](/consul/commands/intention/list). @@ -522,16 +468,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). @@ -577,16 +514,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). @@ -633,16 +561,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `NO` | `none` | `none` | `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `NO` | `none` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention check`](/consul/commands/intention/check). @@ -693,16 +612,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | ----------------------------- | -| `YES` | `all` | `background refresh` | `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `YES` | `all` | `background refresh` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention match`](/consul/commands/intention/match). diff --git a/website/content/commands/intention/check.mdx b/website/content/commands/intention/check.mdx index 3d2780e3290..5d87ec32ca3 100644 --- a/website/content/commands/intention/check.mdx +++ b/website/content/commands/intention/check.mdx @@ -31,16 +31,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/create.mdx b/website/content/commands/intention/create.mdx index c98953ca9f4..f9af9b99feb 100644 --- a/website/content/commands/intention/create.mdx +++ b/website/content/commands/intention/create.mdx @@ -25,16 +25,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ------------------------------ | -| `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/delete.mdx b/website/content/commands/intention/delete.mdx index 780fd6f9af3..744e13c61b3 100644 --- a/website/content/commands/intention/delete.mdx +++ b/website/content/commands/intention/delete.mdx @@ -19,16 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ------------------------------ | -| `intentions:write`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| -> **Deprecated** - The one argument form of this command is deprecated in Consul 1.9.0. Intentions no longer need IDs when represented as diff --git a/website/content/commands/intention/get.mdx b/website/content/commands/intention/get.mdx index 3b688963512..10b1ab1863a 100644 --- a/website/content/commands/intention/get.mdx +++ b/website/content/commands/intention/get.mdx @@ -24,16 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 21a87504a97..2bde0c12902 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -19,16 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| ## Usage From 9c1a513b56e198bd81d3d4afe5e4400e5041d123 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 12:36:44 -0700 Subject: [PATCH 14/23] applied suggestions from review to index page --- .../content/docs/connect/intentions/index.mdx | 78 +++++++++---------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/website/content/docs/connect/intentions/index.mdx b/website/content/docs/connect/intentions/index.mdx index ea24e11e79d..203da8c7467 100644 --- a/website/content/docs/connect/intentions/index.mdx +++ b/website/content/docs/connect/intentions/index.mdx @@ -29,44 +29,6 @@ If the destination service uses an HTTP-based protocol, then intentions can enfo You can manually create intentions from the Consul UI, API, or CLI. You can also enable Consul to dynamically create them by defining traffic routes in service intention configuration entries. Refer to [Create and manage intentions](/consul/docs/connect/intentions/intentions-usage) for details. -### Precedence and match order - -Consul processes criteria configured in the service intention configuration entry to match on incoming requests and either allow or deny the request to the destination service. The match criteria may include specific HTTP headers, request methods, or other attributes. Additionally, you can use regular expressions to programmatically match attributes. Refer to [Service intention configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for details. - -Consul orders the matches implicitly based the following factors: - -- Specificity: Incoming requests that match attributes directly have the highest precedence. For example, intentions that are configured to deny traffic from services that send `POST` requests take precedence over intentions that allow traffic from methods configured with the wildcard value `*`. -- Authorization: Consul enforces `deny` over `allow` if match criteria are weighted equally. - -The following table describes the order of precedence: - -| 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 | - -Consul prints the precedence value to the service intentions configuration entry after it processes the matching criteria. The value is read-only. Refer to -[`Precedence`](/consul/docs/connect/config-entries/service-intentions#precedence) for additional information. - -Namespaces are an Enterprise feature. In Consul OSS, the only allowable value for either namespace field is `"default"`. Other rows in the table are not applicable. - -The [intention match API](/consul/api-docs/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_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. -If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. -If is set to `deny`, then all connections or requests will be denied by default. - ### Enforcement The [proxy](/consul/docs/connect/proxies) or [natively-integrated @@ -88,4 +50,42 @@ Because all intention data is cached locally, authorizations for inbound connect ### Intention maintenance -Services should periodically call the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) to retrieve all relevant intentions for the target destination. After verifying the TLS client certificate, the cached intentions for each incoming connection or request determine if it should be accepted or rejected. \ No newline at end of file +Services should periodically call the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) to retrieve all relevant intentions for the target destination. After verifying the TLS client certificate, the cached intentions for each incoming connection or request determine if it should be accepted or rejected. + +## Precedence and match order + +Consul processes criteria defined in the service intention configuration entry to match incoming requests. When Consul finds a match, it applies the corresponding action specified in the configuration entry. The match criteria may include specific HTTP headers, request methods, or other attributes. Additionally, you can use regular expressions to programmatically match attributes. Refer to [Service intention configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for details. + +Consul orders the matches based the following factors: + +- Specificity: Incoming requests that match attributes directly have the highest precedence. For example, intentions that are configured to deny traffic from services that send `POST` requests take precedence over intentions that allow traffic from methods configured with the wildcard value `*`. +- Authorization: Consul enforces `deny` over `allow` if match criteria are weighted equally. + +The following table shows match precedence in descending order: + +| Precedence | Source Namespace | Source Name | Destination Namespace | Destination Name | +| -----------| ---------------- | ------------| --------------------- | ---------------- | +| 9 | Exact | Exact | Exact | Exact | +| 8 | Exact | `*` | Exact | Exact | +| 7 | `*` | `*` | Exact | Exact | +| 6 | Exact | Exact | Exact | `*` | +| 5 | Exact | `*` | Exact | `*` | +| 4 | `*` | `*` | Exact | `*` | +| 3 | Exact | Exact | `*` | `*` | +| 2 | Exact | `*` | `*` | `*` | +| 1 | `*` | `*` | `*` | `*` | + +Consul prints the precedence value to the service intentions configuration entry after it processes the matching criteria. The value is read-only. Refer to +[`Precedence`](/consul/docs/connect/config-entries/service-intentions#precedence) for additional information. + +Namespaces are an Enterprise feature. In Consul OSS, the only allowable value for either namespace field is `"default"`. Other rows in the table are not applicable. + +The [intention match API](/consul/api-docs/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_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. +If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. +If is set to `deny`, then all connections or requests will be denied by default. \ No newline at end of file From 0b9bfea9f0847708bda03a31fcccf09f6e8debc0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 12:55:58 -0700 Subject: [PATCH 15/23] moved conf examples from usage to conf ref --- .../config-entries/service-intentions.mdx | 154 +++++++++++++++++- .../connect/intentions/intentions-usage.mdx | 139 +--------------- 2 files changed, 157 insertions(+), 136 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index cede6093427..0e1dcc1323f 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -402,7 +402,7 @@ The `Peer` and `Partition` fields are mutually exclusive. ### `Sources[].Action` -Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field for L7 intentions. Configure the [`Permissions`](#sources-permissions) field instead. +Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. Do not configure this field to apply L7 intentions to the same source. Configure the [`Permissions`](#sources-permissions) field instead. #### Values @@ -410,6 +410,13 @@ Specifies the action to take when the source sends traffic to the destination se - This field is required for L4 intentions. - Data type: String value set to either `allow` or `deny` +Refer to the following examples for additional guidance: + +- [L4 Intentions for specific sources and destinations](#l4-intentions-for-specific-sources-and-destinations) +- [L4 intentions for all destinations](#l4-intentions-for-all-destinations) +- [L4 intentions for all sources](#l4-intentions-for-all-sources) +- [L4 and L7](#l4-and-l7) + ### `Sources[].Permissions[]` Specifies a list of permissions for L7 traffic sources. The list contains one or more actions and a set of match criteria for each action. @@ -429,6 +436,13 @@ The `Permissions` only applies to services with a compatible protocol. `Permissi - `Action` - `HTTP` +Refer to the following examples for additional guidance: + +- [Rest access](#rest-access) +- [gRPC](#grpc) +- [Cluster peering](#cluster-peering) +- [L4 and L7](#l4-and-l7) + ### `Sources[].Permissions[].Action` Specifies the action to take when the source sends traffic to the destination service. The value is either `allow` or `deny`. @@ -774,6 +788,144 @@ Specifies a description of the intention. Consul presents the description in API The following examples demonstrate potential use-cases for the service intentions configuration entry. +### L4 Intentions for specific sources and destinations + +The following example configuration entry specifies an L4 intention that denies traffic from `web` to `db` service instances, but allows traffic from `api` to `db`. + + + +```hcl +Kind = "service-intentions" +Name = "db" +Sources = [ + { + Name = "web" + Action = "deny" + }, + { + Name = "api" + Action = "allow" + } +] +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: db + sources: + - name: web + action: deny + - name: api + action: allow +``` + +```json +{ + "Kind": "service-intentions", + "Name": "db", + "Sources": [ + { + "Action": "deny", + "Name": "web" + }, + { + "Action": "allow", + "Name": "api" + } + ] +} +``` + + + +### L4 intentions for all destinations + +In the following L4 example, the destination is configured with a `*` wildcard. As a result, traffic from `web` service instances is denied for any service in the datacenter. + + + +```hcl +Kind = "service-intentions" +Name = "*" +Sources = [ + { + Name = "web" + Action = "deny" + } +] +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: * + sources: + - name: web + action: deny +``` + +```json +{ + "Kind": "service-intentions", + "Name": "*", + "Sources": [ + { + "Action": "deny", + "Name": "web" + } + ] +} +``` + + + +### L4 intentions for all sources + +In the following L4 example, the source is configured with a `*` wildcard. As a result, traffic from any service is denied to `db` service instances. + + + +```hcl +Kind = "service-intentions" +Name = "db" +Sources = [ + { + Name = "*" + Action = "deny" + } +] +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceIntentions +spec: + destination: + name: db + sources: + - name: * + action: deny +``` + +```json +{ + "Kind": "service-intentions", + "Name": "db", + "Sources": [ + { + "Action": "deny", + "Name": "*" + } + ] +} +``` + + ### REST access In the following example, the `admin-dashboard` and `report-generator` services have different levels of access when making REST calls: diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx index 06cc762c5ee..44b54771646 100644 --- a/website/content/docs/connect/intentions/intentions-usage.mdx +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -153,12 +153,14 @@ Configure the following fields: - [`spec.sources`](/consul/docs/connect/config-entries/service-intentions#spec-sources): Specifies an unordered list of all intention sources and the authorizations granted to those sources. Consul stores and evaluates the list in reverse order sorted by intention precedence. - [`spec.sources.action`](/consul/docs/connect/config-entries/service-intentions#spec-sources-action) or [`spec.sources.permissions`](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions): For L4 intentions, set the `action` field to "allow" or "deny" so that Consul can enforce intentions that match the source service. For L7 intentions, configure the `permissions` settings, which define a set of application-aware attributes for dynamically matching incoming requests. The `actions` and `permissions` settings are mutually exclusive. -Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about the configuration options. - +Refer to the [service intentions configuration entry](/consul/docs/connect/config-entries/service-intentions) reference documentation for details about all configuration options. + +Refer to the [example service intentions configurations](/consul/docs/connect/config-entries/service-intentions#examples) for additional guidance. + #### Interaction with other configuration entries L7 intentions defined in a configuration entry are restricted to destination services @@ -175,136 +177,3 @@ Refer to the following topics for details about applying configuration entries: - [How to Use Configuration Entries](/consul/docs/agent/config-entries) - [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds) -### Example service intentions - -The following example configuration entry specifies an L4 intention that denies traffic from `web` to `db` service instances, but allows traffic from `api` to `db`. - - - -```hcl -Kind = "service-intentions" -Name = "db" -Sources = [ - { - Name = "web" - Action = "deny" - }, - { - Name = "api" - Action = "allow" - } -] -``` - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceIntentions -spec: - destination: - name: db - sources: - - name: web - action: deny - - name: api - action: allow -``` - -```json -{ - "Kind": "service-intentions", - "Name": "db", - "Sources": [ - { - "Action": "deny", - "Name": "web" - }, - { - "Action": "allow", - "Name": "api" - } - ] -} -``` - - - -In the following L4 example, the destination is configured with a `*` wildcard. As a result, traffic from `web` service instances is denied for any service in the datacenter. - - - -```hcl -Kind = "service-intentions" -Name = "*" -Sources = [ - { - Name = "web" - Action = "deny" - } -] -``` - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceIntentions -spec: - destination: - name: * - sources: - - name: web - action: deny -``` - -```json -{ - "Kind": "service-intentions", - "Name": "*", - "Sources": [ - { - "Action": "deny", - "Name": "web" - } - ] -} -``` - - - -In the following L4 example, the source is configured with a `*` wildcard. As a result, traffic from any service is denied to `db` service instances. - - - -```hcl -Kind = "service-intentions" -Name = "db" -Sources = [ - { - Name = "*" - Action = "deny" - } -] -``` - -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ServiceIntentions -spec: - destination: - name: db - sources: - - name: * - action: deny -``` - -```json -{ - "Kind": "service-intentions", - "Name": "db", - "Sources": [ - { - "Action": "deny", - "Name": "*" - } - ] -} -``` - From aaef49ef9778d811e56555d4a7eebe42ce3c06d1 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 13:02:20 -0700 Subject: [PATCH 16/23] missed custom HTML section --- website/content/commands/intention/match.mdx | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/website/content/commands/intention/match.mdx b/website/content/commands/intention/match.mdx index 5d76218d0f5..aaddff8799b 100644 --- a/website/content/commands/intention/match.mdx +++ b/website/content/commands/intention/match.mdx @@ -24,16 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`1 | - -

- 1 Intention ACL rules are specified as part of a{' '} - service rule. See{' '} - - ACL requirements for intentions - {' '} - for more details. -

+| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| ## Usage From c8e88947439dba05356a10a5407386922763c566 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 13:03:11 -0700 Subject: [PATCH 17/23] applied additional feedback --- website/content/docs/connect/intentions/intentions-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx index 44b54771646..5bc7704d6f0 100644 --- a/website/content/docs/connect/intentions/intentions-usage.mdx +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -26,7 +26,7 @@ Consul implicitly grants `intentions:read` permissions to destination services w The default ACL policy configuration determines the default behavior for intentions. If the policy is set to `deny`, then all connections or requests are denied and you must enable them explicitly. Refer to [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) for details. -## Create a single intention +## Create an intention You can create and manage intentions one at a time using the Consul API, CLI, or UI You can specify one destination or multiple destinations in a single intention. From 4c4059982860e22b0f35cd06815871938895c339 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Fri, 24 Mar 2023 14:22:36 -0700 Subject: [PATCH 18/23] Apply suggestions from code review Co-authored-by: Tu Nguyen --- website/content/docs/connect/intentions/index.mdx | 2 +- website/data/docs-nav-data.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/connect/intentions/index.mdx b/website/content/docs/connect/intentions/index.mdx index 203da8c7467..19bf6ad787d 100644 --- a/website/content/docs/connect/intentions/index.mdx +++ b/website/content/docs/connect/intentions/index.mdx @@ -13,7 +13,7 @@ This topic provides overview information about Consul intentions, which are mech ## Intention types -Intentions control traffic communication between services at the network layer, also called _L7_ traffic, or the application layer, also called _L4 traffic_. The protocol that the destination service uses to send and receive traffic determines the type of authorization the intention can enforce. +Intentions control traffic communication between services at the network layer, also called _L4_ traffic, or the application layer, also called _L7 traffic_. The protocol that the destination service uses to send and receive traffic determines the type of authorization the intention can enforce. ### L4 traffic intentions diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index cb312efe94d..a1f514bbf18 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -542,7 +542,7 @@ "title": "Service intentions", "routes": [ { - "title": "Service mesh intentions overview", + "title": "Overview", "path": "connect/intentions" }, { From a5ff062ba27132254809e58d1f6db8b468dadf1e Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 14:30:50 -0700 Subject: [PATCH 19/23] updated headings in usage page --- .../content/docs/connect/intentions/intentions-usage.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/intentions-usage.mdx index 5bc7704d6f0..cd6fe07589d 100644 --- a/website/content/docs/connect/intentions/intentions-usage.mdx +++ b/website/content/docs/connect/intentions/intentions-usage.mdx @@ -126,11 +126,11 @@ You can use the Consul UI to configure L7 permissions. Repeat the procedure as necessary to create additional permissions. -## Create intention defaults +## Create multiple service intentions You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic. -### Define the service defaults configuration entry +### Define a service intention configuration entry Configure the following fields: @@ -175,5 +175,4 @@ You can apply the configuration entry using the [`consul config` command](/consu Refer to the following topics for details about applying configuration entries: - [How to Use Configuration Entries](/consul/docs/agent/config-entries) -- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds) - +- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds) \ No newline at end of file From 0be6ddf0bad1ba2012801e0d439d86b6390f9778 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 14:33:07 -0700 Subject: [PATCH 20/23] renamed files and udpated nav --- .../{intentions-usage.mdx => create-manage-intentions.mdx} | 0 .../connect/intentions/{intentions-legacy.mdx => legacy.mdx} | 0 website/data/docs-nav-data.json | 4 ++-- 3 files changed, 2 insertions(+), 2 deletions(-) rename website/content/docs/connect/intentions/{intentions-usage.mdx => create-manage-intentions.mdx} (100%) rename website/content/docs/connect/intentions/{intentions-legacy.mdx => legacy.mdx} (100%) diff --git a/website/content/docs/connect/intentions/intentions-usage.mdx b/website/content/docs/connect/intentions/create-manage-intentions.mdx similarity index 100% rename from website/content/docs/connect/intentions/intentions-usage.mdx rename to website/content/docs/connect/intentions/create-manage-intentions.mdx diff --git a/website/content/docs/connect/intentions/intentions-legacy.mdx b/website/content/docs/connect/intentions/legacy.mdx similarity index 100% rename from website/content/docs/connect/intentions/intentions-legacy.mdx rename to website/content/docs/connect/intentions/legacy.mdx diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a1f514bbf18..67317ed5fa7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -547,11 +547,11 @@ }, { "title": "Create and manage service intentions", - "path": "connect/intentions/intentions-usage" + "path": "connect/intentions/create-manage-intentions" }, { "title": "Service intentions legacy mode", - "path": "connect/intentions/intentions-legacy" + "path": "connect/intentions/legacy" }, { "title": "Configuration", From 8b64feae14c5a32f4af08e1d52f8bf41cfa9cc23 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 14:36:27 -0700 Subject: [PATCH 21/23] updated links to new file names --- .../content/api-docs/connect/intentions.mdx | 20 +++++++++---------- website/content/commands/intention/check.mdx | 2 +- website/content/commands/intention/create.mdx | 2 +- website/content/commands/intention/delete.mdx | 2 +- website/content/commands/intention/get.mdx | 2 +- website/content/commands/intention/list.mdx | 2 +- website/content/commands/intention/match.mdx | 2 +- .../config-entries/service-intentions.mdx | 2 +- .../intentions/create-manage-intentions.mdx | 2 +- .../content/docs/connect/intentions/index.mdx | 2 +- .../content/docs/security/acl/acl-rules.mdx | 2 +- 11 files changed, 20 insertions(+), 20 deletions(-) diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index b598eb40f57..1658b16992f 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -43,7 +43,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention create -replace`](/consul/commands/intention/create#replace). @@ -140,7 +140,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention create`](/consul/commands/intention/create). @@ -228,7 +228,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| This endpoint supports the same parameters as the [create an intention](#create-intention-with-id) endpoint. Additional parameters unique to this endpoint include: @@ -273,7 +273,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). @@ -336,7 +336,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). @@ -390,7 +390,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `YES` | `all` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention list`](/consul/commands/intention/list). @@ -468,7 +468,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). @@ -514,7 +514,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | -| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). @@ -561,7 +561,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | -| `NO` | `none` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `NO` | `none` | `none` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention check`](/consul/commands/intention/check). @@ -612,7 +612,7 @@ The table below shows this endpoint's support for | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | ----------------------------- | -| `YES` | `all` | `background refresh` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `YES` | `all` | `background refresh` | `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| The corresponding CLI command is [`consul intention match`](/consul/commands/intention/match). diff --git a/website/content/commands/intention/check.mdx b/website/content/commands/intention/check.mdx index 5d87ec32ca3..fadc8d224bd 100644 --- a/website/content/commands/intention/check.mdx +++ b/website/content/commands/intention/check.mdx @@ -31,7 +31,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/create.mdx b/website/content/commands/intention/create.mdx index f9af9b99feb..71c491b06ad 100644 --- a/website/content/commands/intention/create.mdx +++ b/website/content/commands/intention/create.mdx @@ -25,7 +25,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ------------------------------ | -| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/delete.mdx b/website/content/commands/intention/delete.mdx index 744e13c61b3..ad2fca1c97e 100644 --- a/website/content/commands/intention/delete.mdx +++ b/website/content/commands/intention/delete.mdx @@ -19,7 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ------------------------------ | -| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:write`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| -> **Deprecated** - The one argument form of this command is deprecated in Consul 1.9.0. Intentions no longer need IDs when represented as diff --git a/website/content/commands/intention/get.mdx b/website/content/commands/intention/get.mdx index 10b1ab1863a..84b3a86065d 100644 --- a/website/content/commands/intention/get.mdx +++ b/website/content/commands/intention/get.mdx @@ -24,7 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 2bde0c12902..85a7d6b9d6c 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -19,7 +19,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/commands/intention/match.mdx b/website/content/commands/intention/match.mdx index aaddff8799b..4c727b1fc21 100644 --- a/website/content/commands/intention/match.mdx +++ b/website/content/commands/intention/match.mdx @@ -24,7 +24,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint | ACL Required | | ----------------------------- | -| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) for additional information.

| +| `intentions:read`

Define intention rules in the `service` policy. Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for additional information.

| ## Usage diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 0e1dcc1323f..22d83c33570 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -497,7 +497,7 @@ Each member of the `Header` list is a map that contains a `Name` field and at le ### `Sources[].Precedence` -The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/intentions#precedence-and-matching-order) for additional information. +The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-matching-order) for additional information. ### `Sources[].Type` diff --git a/website/content/docs/connect/intentions/create-manage-intentions.mdx b/website/content/docs/connect/intentions/create-manage-intentions.mdx index cd6fe07589d..2b696bf74c5 100644 --- a/website/content/docs/connect/intentions/create-manage-intentions.mdx +++ b/website/content/docs/connect/intentions/create-manage-intentions.mdx @@ -99,7 +99,7 @@ The following example creates an intention that allows `web` service instances t $ consul intention create -allow web db ``` -You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/intentions#precedence-and-match-order) for additional information. +You can use the asterisk (`*`) wildcard to specify multiple destination services. Refer to [Precedence and match order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-match-order) for additional information. ### Consul UI diff --git a/website/content/docs/connect/intentions/index.mdx b/website/content/docs/connect/intentions/index.mdx index 19bf6ad787d..6472fc79b3e 100644 --- a/website/content/docs/connect/intentions/index.mdx +++ b/website/content/docs/connect/intentions/index.mdx @@ -27,7 +27,7 @@ If the destination service uses an HTTP-based protocol, then intentions can enfo ## Workflow -You can manually create intentions from the Consul UI, API, or CLI. You can also enable Consul to dynamically create them by defining traffic routes in service intention configuration entries. Refer to [Create and manage intentions](/consul/docs/connect/intentions/intentions-usage) for details. +You can manually create intentions from the Consul UI, API, or CLI. You can also enable Consul to dynamically create them by defining traffic routes in service intention configuration entries. Refer to [Create and manage intentions](/consul/docs/connect/intentions/create-manage-intentions) for details. ### Enforcement diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index fc834d07422..a09ffd2fc25 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -869,7 +869,7 @@ service "app" { -Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/intentions-usage#acl-requirements) +Refer to [ACL requirements for intentions](/consul/docs/connect/intentions/create-manage-intentions#acl-requirements) for more information about managing intentions access with service rules. ## Session Rules From 7acd71506171ded9cd81a4d3ca9ee6c3b0dcf042 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 14:44:47 -0700 Subject: [PATCH 22/23] added redirects and final tweaks --- .../connect/intentions/create-manage-intentions.mdx | 2 +- website/redirects.js | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/intentions/create-manage-intentions.mdx b/website/content/docs/connect/intentions/create-manage-intentions.mdx index 2b696bf74c5..80e68ce890a 100644 --- a/website/content/docs/connect/intentions/create-manage-intentions.mdx +++ b/website/content/docs/connect/intentions/create-manage-intentions.mdx @@ -126,7 +126,7 @@ You can use the Consul UI to configure L7 permissions. Repeat the procedure as necessary to create additional permissions. -## Create multiple service intentions +## Create multiple intentions You can create a service intentions configuration entry to specify default intentions for your service mesh. You can specify default settings for L4 or L7 application-aware traffic. diff --git a/website/redirects.js b/website/redirects.js index 3e462501650..fb9ec442c66 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -22,4 +22,14 @@ module.exports = [ destination: '/consul/docs/k8s/connect/cluster-peering/tech-specs', permanent: true, }, + { + source: '/consul/docs/connect/intentions#intention-management-permissions', + destination: `/consul/docs/connect/intentions/create-manage-intentions#acl-requirements`, + permanent: true, + }, + { + source: '/consul/docs/connect/intentions#intention-basics', + destination: `/consul/docs/connect/intentions`, + permanent: true, + }, ] From 2bb6e9b10985915d9e38a07ae6f9c7846564f8aa Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 14:49:44 -0700 Subject: [PATCH 23/23] typo --- website/content/docs/connect/intentions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/intentions/index.mdx b/website/content/docs/connect/intentions/index.mdx index 6472fc79b3e..301344c64ec 100644 --- a/website/content/docs/connect/intentions/index.mdx +++ b/website/content/docs/connect/intentions/index.mdx @@ -23,7 +23,7 @@ This implementation allows broad all-or-nothing access control between pairs of ### L7 traffic intentions -If the destination service uses an HTTP-based protocol, then intentions can enforce access based on application-aware request attributes, in addition to identity-based enforcement, to control traffic between services. Refer to[Service intentions configuration reference](/consul/docs/connect/config-entries/service-intentions#permissions) for additional information. +If the destination service uses an HTTP-based protocol, then intentions can enforce access based on application-aware request attributes, in addition to identity-based enforcement, to control traffic between services. Refer to [Service intentions configuration reference](/consul/docs/connect/config-entries/service-intentions#permissions) for additional information. ## Workflow