diff --git a/website/pages/api-docs/connect/intentions.mdx b/website/pages/api-docs/connect/intentions.mdx index 3b3f6fd7bb..598ed5d25d 100644 --- a/website/pages/api-docs/connect/intentions.mdx +++ b/website/pages/api-docs/connect/intentions.mdx @@ -50,17 +50,23 @@ The table below shows this endpoint's support for For a `SourceType` of `consul` this is the name of a Consul service. The service doesn't need to be registered. +- `SourceNS` `(string: "")` - The namespace for the + `SourceName` parameter. + - `DestinationName` `(string: )` - The destination of the intention. The intention destination is always a Consul service, unlike the source. The service doesn't need to be registered. +- `DestinationNS` `(string: "")` - The namespace for the + `DestinationName` parameter. + - `SourceType` `(string: )` - The type for the `SourceName` value. This can be only "consul" today to represent a Consul service. - `Action` `(string: )` - This is one of "allow" or "deny" for the action that should be taken if this intention matches a request. -- `Description` `(string: nil)` - Description for the intention. This is not +- `Description` `(string: "")` - Description for the intention. This is not used for anything by Consul, but is presented in API responses to assist tooling. @@ -79,7 +85,7 @@ The table below shows this endpoint's support for ### Sample Request -```text +```shell-session $ curl \ --request POST \ --data @payload.json \ @@ -128,7 +134,7 @@ The table below shows this endpoint's support for ### Sample Request -```text +```shell-session $ curl \ http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c ``` @@ -190,7 +196,7 @@ The table below shows this endpoint's support for ### Sample Request -```text +```shell-session $ curl \ 'http://127.0.0.1:8500/v1/connect/intentions?filter=SourceName==web' ``` @@ -288,7 +294,7 @@ The table below shows this endpoint's support for ### Sample Request -```text +```shell-session $ curl \ --request PUT \ --data @payload.json \ @@ -329,7 +335,7 @@ The table below shows this endpoint's support for ### Sample Request -```text +```shell-session $ curl \ --request DELETE \ http://127.0.0.1:8500/v1/connect/intentions/e9ebc19f-d481-42b1-4871-4d298d3acd5c @@ -372,13 +378,15 @@ The table below shows this endpoint's support for - `source` `(string: )` - Specifies the source service. This is specified as part of the URL. + This can take [several forms](/docs/commands/intention#source-and-destination-naming). - `destination` `(string: )` - Specifies the destination service. This is specified as part of the URL. + This can take [several forms](/docs/commands/intention#source-and-destination-naming). ### Sample Request -```text +```shell-session $ curl \ http://127.0.0.1:8500/v1/connect/intentions/check?source=web&destination=db ``` @@ -428,10 +436,11 @@ The table below shows this endpoint's support for - `name` `(string: )` - Specifies a name to match. This parameter can be repeated for batching multiple matches. + This can take [several forms](/docs/commands/intention#source-and-destination-naming). ### Sample Request -```text +```shell-session $ curl \ http://127.0.0.1:8500/v1/connect/intentions/match?by=source&name=web ``` diff --git a/website/pages/docs/commands/intention/check.mdx b/website/pages/docs/commands/intention/check.mdx index 2ec5148992..263d782ab0 100644 --- a/website/pages/docs/commands/intention/check.mdx +++ b/website/pages/docs/commands/intention/check.mdx @@ -22,13 +22,19 @@ intention read permissions and don't evaluate the result. Usage: `consul intention check [options] SRC DST` +`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming). + #### API Options @include 'http_api_options_client.mdx' +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + ## Examples -```text +```shell-session $ consul intention check web db Denied diff --git a/website/pages/docs/commands/intention/create.mdx b/website/pages/docs/commands/intention/create.mdx index fd40ffdf9c..efb65040d9 100644 --- a/website/pages/docs/commands/intention/create.mdx +++ b/website/pages/docs/commands/intention/create.mdx @@ -15,10 +15,16 @@ The `intention create` command creates or updates an intention. Usage: `consul intention create [options] SRC DST` Usage: `consul intention create [options] -f FILE...` +`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming). + #### API Options @include 'http_api_options_client.mdx' +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + #### Intention Create Options - `-allow` - Set the action to "allow" for intentions. This is the default. @@ -39,18 +45,18 @@ Usage: `consul intention create [options] -f FILE...` Create an intention `web => db`: -```shell +```shell-session $ consul intention create web db ``` Create intentions from a set of files: -```shell +```shell-session $ consul intention create -file one.json two.json ``` Create intentions from a directory using shell expansion: -```shell +```shell-session $ consul intention create -file intentions/*.json ``` diff --git a/website/pages/docs/commands/intention/delete.mdx b/website/pages/docs/commands/intention/delete.mdx index 8a6de0db6b..9bf1f1aa03 100644 --- a/website/pages/docs/commands/intention/delete.mdx +++ b/website/pages/docs/commands/intention/delete.mdx @@ -17,20 +17,26 @@ Usage: - `consul intention delete [options] SRC DST` - `consul intention delete [options] ID` +`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming). + #### API Options @include 'http_api_options_client.mdx' +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + ## Examples Delete an intention from "web" to "db" with any action: -```text +```shell-session $ consul intention delete web db ``` Delete an intention by unique ID: -```text +```shell-session $ consul intention delete 4ffed935-439c-695d-4f51-f4fc0b12a7a7 ``` diff --git a/website/pages/docs/commands/intention/get.mdx b/website/pages/docs/commands/intention/get.mdx index 583f328f06..570eb72438 100644 --- a/website/pages/docs/commands/intention/get.mdx +++ b/website/pages/docs/commands/intention/get.mdx @@ -17,13 +17,19 @@ Usage: - `consul intention get [options] SRC DST` - `consul intention get [options] ID` +`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming). + #### API Options @include 'http_api_options_client.mdx' +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + ## Examples -```text +```shell-session $ consul intention get web db Source: web Destination: db diff --git a/website/pages/docs/commands/intention/index.mdx b/website/pages/docs/commands/intention/index.mdx index d549c3db24..fae4235bb6 100644 --- a/website/pages/docs/commands/intention/index.mdx +++ b/website/pages/docs/commands/intention/index.mdx @@ -42,25 +42,38 @@ of the subcommand in the sidebar. Create an intention to allow "web" to talk to "db": -```shell +```shell-session $ consul intention create web db ``` Create an intention to deny "db" from initiating connections to _any_ service: -```shell +```shell-session $ consul intention create -deny db '*' Created: db => * (deny) ``` Test whether a "web" is allowed to connect to "db": -```shell +```shell-session $ consul intention check web db ``` Find all intentions for communicating to the "db" service: -```shell +```shell-session $ consul intention match db ``` + +## Source and Destination Naming + +Intention commands commonly take positional arguments referred to as `SRC` and +`DST` in the command documentation. These can take several forms: + +| Format | Meaning | +| ----------------------- | -----------------------------------------------------------------------| +| `` | the named service in the current namespace | +| `*` | any service in the current namespace | +| `/` | the named service in a specific namespace | +| `/*` | any service in the specified namespace | +| `*/*` | any service in any namespace | diff --git a/website/pages/docs/commands/intention/match.mdx b/website/pages/docs/commands/intention/match.mdx index db319fe75c..12edbc0ee5 100644 --- a/website/pages/docs/commands/intention/match.mdx +++ b/website/pages/docs/commands/intention/match.mdx @@ -19,10 +19,16 @@ check whether a connection would be authorized between any two services. Usage: `consul intention match [options] SRC_OR_DST` +`SRC` and `DST` can both take [several forms](/docs/commands/intention#source-and-destination-naming). + #### API Options @include 'http_api_options_client.mdx' +#### Enterprise Options + +@include 'http_api_namespace_options.mdx' + #### Intention Match Options - `-destination` - Match by destination. @@ -31,7 +37,7 @@ Usage: `consul intention match [options] SRC_OR_DST` ## Examples -```text +```shell-session $ consul intention match -source web web => db (deny) web => * (allow)