From d6d0450665659f172360d4daebc3103777e6c8a9 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 12 Jul 2023 15:35:37 -0500 Subject: [PATCH 1/9] Init file for services export command docs --- website/content/commands/services/export.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 website/content/commands/services/export.mdx diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx new file mode 100644 index 000000000000..d9da54240d17 --- /dev/null +++ b/website/content/commands/services/export.mdx @@ -0,0 +1,8 @@ +--- +layout: commands +page_title: 'Commands: Services Export' +description: | + The `consul services export` command exports a service from one peer or admin partition to another. +--- + +# Consul Agent Service Export From 39feb999f1dd5327ff2d3c9f425a58f4d6ec51bb Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 12 Jul 2023 16:02:20 -0500 Subject: [PATCH 2/9] Add link for export command to nav --- website/data/commands-nav-data.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/data/commands-nav-data.json b/website/data/commands-nav-data.json index ee491e9dfa7b..dd38459a9012 100644 --- a/website/data/commands-nav-data.json +++ b/website/data/commands-nav-data.json @@ -487,6 +487,10 @@ { "title": "deregister", "path": "services/deregister" + }, + { + "title": "export", + "path": "services/export" } ] }, From 8b1398a9b1b80bc2491f55f4fcc4ed028c2f6590 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 12 Jul 2023 16:02:51 -0500 Subject: [PATCH 3/9] Add export to list of subcommands for services --- website/content/commands/services/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/content/commands/services/index.mdx b/website/content/commands/services/index.mdx index ec26946c580a..f511ffe2efce 100644 --- a/website/content/commands/services/index.mdx +++ b/website/content/commands/services/index.mdx @@ -31,6 +31,7 @@ Usage: consul services [options] [args] Subcommands: deregister Deregister services with the local agent register Register services with the local agent + export Export services from one cluster peer or admin partition to another ``` For more information, examples, and usage about a subcommand, click on the name From 47b9c12a044f37649c906a9b6acf85d6e3055f56 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 9 Aug 2023 16:52:26 -0400 Subject: [PATCH 4/9] Add usage and basic command options --- website/content/commands/services/export.mdx | 31 +++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index d9da54240d17..6515d266a064 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -5,4 +5,33 @@ description: | The `consul services export` command exports a service from one peer or admin partition to another. --- -# Consul Agent Service Export +# Consul Services Export + +Command: `consul services export` + +The services export subcommand is used to export a service from one admin partition +or cluster peer to another. + +```text +Usage: consul services export [options] -name -consumer-peers + + Export a service to a peered cluster. + + $ consul services export -name=web -consumer-peers=other-cluster + + Use the -consumer-partitions flag instead of -consumer-peers to export to a different partition in the same cluster. + + $ consul services export -name=web -consumer-partitions=other-partition + + Additional flags and more advanced use cases are detailed below. +``` + +#### Command Options + +- `-name` - (Required) The name of the service to export. + +- `-consumer-peers` - (Required) A comma-separated list of cluster peers to export the service to. + In Consul Enterprise, this flag is optional if -consumer-partitions is specified. + +- `-consumer-partitions` - (Enterprise only) A comma-separated list of admin partitions within the + same datacenter to export the service to. This flag is optional if -consumer-peers is specified. From db8d974cf156e4374307ac4a990373ec2bfd0d8d Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Thu, 10 Aug 2023 15:28:05 -0400 Subject: [PATCH 5/9] Add API options using includes --- website/content/commands/services/export.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index 6515d266a064..dd004b2e7fa0 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -35,3 +35,9 @@ Usage: consul services export [options] -name -consumer-peers Date: Thu, 10 Aug 2023 15:32:20 -0400 Subject: [PATCH 6/9] Add section for enterprise options --- website/content/commands/services/export.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index dd004b2e7fa0..d02e6f21f899 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -33,11 +33,15 @@ Usage: consul services export [options] -name -consumer-peers Date: Thu, 10 Aug 2023 15:47:50 -0400 Subject: [PATCH 7/9] Include argument value in flag format --- website/content/commands/services/export.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index d02e6f21f899..2d61b5ffc522 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -28,14 +28,14 @@ Usage: consul services export [options] -name -consumer-peers ` - (Required) The name of the service to export. -- `-consumer-peers` - (Required) A comma-separated list of cluster peers to export the service to. +- `-consumer-peers=` - (Required) A comma-separated list of cluster peers to export the service to. In Consul Enterprise, this flag is optional if -consumer-partitions is specified. #### Enterprise Options -- `-consumer-partitions` - (Enterprise only) A comma-separated list of admin partitions within the +- `-consumer-partitions=` - A comma-separated list of admin partitions within the same datacenter to export the service to. This flag is optional if -consumer-peers is specified. @include 'http_api_partition_options.mdx' From 2e34721547ddc39162456e182fac7b611197a4f5 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Thu, 10 Aug 2023 16:19:12 -0400 Subject: [PATCH 8/9] Add examples --- website/content/commands/services/export.mdx | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index 2d61b5ffc522..db05a9c92f13 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -10,7 +10,9 @@ description: | Command: `consul services export` The services export subcommand is used to export a service from one admin partition -or cluster peer to another. +or cluster peer to another. This is accomplished by creating or updating the corresponding +`exported-services` configuration entry. Running the command multiple times with the same +arguments will result in a no-op. ```text Usage: consul services export [options] -name -consumer-peers @@ -45,3 +47,19 @@ Usage: consul services export [options] -name -consumer-peers Date: Fri, 11 Aug 2023 12:43:45 -0400 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- website/content/commands/services/export.mdx | 25 ++++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/website/content/commands/services/export.mdx b/website/content/commands/services/export.mdx index db05a9c92f13..281d5f23e7d7 100644 --- a/website/content/commands/services/export.mdx +++ b/website/content/commands/services/export.mdx @@ -9,10 +9,10 @@ description: | Command: `consul services export` -The services export subcommand is used to export a service from one admin partition -or cluster peer to another. This is accomplished by creating or updating the corresponding +The `services export` command exports a service from one admin partition +or cluster peer to another. This command can be used in lieu of creating or updating the corresponding `exported-services` configuration entry. Running the command multiple times with the same -arguments will result in a no-op. +arguments results in a no-op. ```text Usage: consul services export [options] -name -consumer-peers @@ -28,38 +28,37 @@ Usage: consul services export [options] -name -consumer-peers ` - (Required) The name of the service to export. - `-consumer-peers=` - (Required) A comma-separated list of cluster peers to export the service to. - In Consul Enterprise, this flag is optional if -consumer-partitions is specified. + In Consul Enterprise, this flag is optional when `-consumer-partitions` is specified. -#### Enterprise Options +#### Enterprise options - `-consumer-partitions=` - A comma-separated list of admin partitions within the - same datacenter to export the service to. This flag is optional if -consumer-peers is specified. + same datacenter to export the service to. This flag is optional when `-consumer-peers` is specified. @include 'http_api_partition_options.mdx' @include 'http_api_namespace_options.mdx' -#### API Options +#### API options @include 'http_api_options_client.mdx' ## Examples -The example below shows using the `export` command to export the `web` service to a cluster -peer named `dc2`. +In the following example, the `consul services export` command makes the `web` service available to services running in a cluster named `dc2` that has a previously-established cluster peering connection. ```shell-session hideClipboard $ consul services export -name=web -consumer-peers=dc2 ``` -The example below shows using the `export` command to export the `web` service located in the -namespace `ns1` and the admin partition `part1` to other admin partitions named `part2` and `part3`. +In the following example, the `consul services export` command makes the `web` service located in the +namespace `ns1` and the admin partition `alpha` to other admin partitions named `beta` and `delta`. ```shell-session hideClipboard -$ consul services export -name=web -namespace=ns1 -partition=part1 -consumer-partitions=part2,part3 +$ consul services export -name=web -namespace=ns1 -partition=alpha -consumer-partitions=beta,delta ```