From 0b9bfea9f0847708bda03a31fcccf09f6e8debc0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 Mar 2023 12:55:58 -0700 Subject: [PATCH] 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 cede6093427e..0e1dcc1323f6 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 06cc762c5ee4..44b547716464 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": "*" - } - ] -} -``` -