github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Manual Backport of Exported services CLI and docs into release/1.18.x (#20331) (#20493) 

Exported services CLI and docs (#20331)

* Exported services CLI and docs

* Changelog added

* Added format option for pretty print

* Update command/exportedservices/exported_services.go



* Addressing PR comments, moving the command under services category

* Add consumer peer and partition filter

* Adding bexpr filter, change format of data

---------

Co-authored-by: Ashesh Vidyut <134911583+absolutelightning@users.noreply.github.com>
pull/20503/head
Tauhid Anjum 10 months ago committed by GitHub
parent
0ad0d4077b
commit
ddb2987612
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 712 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 3
      .changelog/20331.txt
  2. 2
      command/registry.go
  3. 176
      command/services/exportedservices/exported_services.go
  4. 323
      command/services/exportedservices/exported_services_test.go
  5. 143
      website/content/api-docs/exported-services.mdx
  6. 57
      website/content/commands/services/exported-services.mdx
  7. 4
      website/data/api-docs-nav-data.json
  8. 4
      website/data/commands-nav-data.json

3
.changelog/20331.txt
Unescape View File

@ -0,0 +1,3 @@
```release-note:feature
cli: Adds new command `exported-services` to list all services exported and their consumers. Refer to the [CLI docs](https://developer.hashicorp.com/consul/commands/exported-services) for more information.
```

2
command/registry.go
Unescape View File

@ -122,6 +122,7 @@ import (
"github.com/hashicorp/consul/command/services"
svcsderegister "github.com/hashicorp/consul/command/services/deregister"
svcsexport "github.com/hashicorp/consul/command/services/export"
exportedservices "github.com/hashicorp/consul/command/services/exportedservices"
svcsregister "github.com/hashicorp/consul/command/services/register"
"github.com/hashicorp/consul/command/snapshot"
snapinspect "github.com/hashicorp/consul/command/snapshot/inspect"
@ -264,6 +265,7 @@ func RegisteredCommands(ui cli.Ui) map[string]mcli.CommandFactory {
entry{"services register", func(ui cli.Ui) (cli.Command, error) { return svcsregister.New(ui), nil }},
entry{"services deregister", func(ui cli.Ui) (cli.Command, error) { return svcsderegister.New(ui), nil }},
entry{"services export", func(ui cli.Ui) (cli.Command, error) { return svcsexport.New(ui), nil }},
entry{"services exported-services", func(ui cli.Ui) (cli.Command, error) { return exportedservices.New(ui), nil }},
entry{"snapshot", func(cli.Ui) (cli.Command, error) { return snapshot.New(), nil }},
entry{"snapshot inspect", func(ui cli.Ui) (cli.Command, error) { return snapinspect.New(ui), nil }},
entry{"snapshot restore", func(ui cli.Ui) (cli.Command, error) { return snaprestore.New(ui), nil }},

176
command/services/exportedservices/exported_services.go
Unescape View File

@ -0,0 +1,176 @@
// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: BUSL-1.1
package exportedservices
import (
"encoding/json"
"flag"
"fmt"
"strings"
"github.com/mitchellh/cli"
"github.com/hashicorp/consul/api"
"github.com/hashicorp/consul/command/flags"
"github.com/hashicorp/go-bexpr"
"github.com/ryanuber/columnize"
)
const (
PrettyFormat string = "pretty"
JSONFormat string = "json"
)
func getSupportedFormats() []string {
return []string{PrettyFormat, JSONFormat}
}
func formatIsValid(f string) bool {
for _, format := range getSupportedFormats() {
if f == format {
return true
}
}
return false
}
func New(ui cli.Ui) *cmd {
c := &cmd{UI: ui}
c.init()
return c
}
type cmd struct {
UI cli.Ui
flags *flag.FlagSet
http *flags.HTTPFlags
help string
format string
filter string
}
func (c *cmd) init() {
c.flags = flag.NewFlagSet("", flag.ContinueOnError)
c.flags.StringVar(
&c.format,
"format",
PrettyFormat,
fmt.Sprintf("Output format {%s} (default: %s)", strings.Join(getSupportedFormats(), "|"), PrettyFormat),
)
c.flags.StringVar(&c.filter, "filter", "", "go-bexpr filter string to filter the response")
c.http = &flags.HTTPFlags{}
flags.Merge(c.flags, c.http.ClientFlags())
flags.Merge(c.flags, c.http.ServerFlags())
flags.Merge(c.flags, c.http.PartitionFlag())
c.help = flags.Usage(help, c.flags)
}
func (c *cmd) Run(args []string) int {
if err := c.flags.Parse(args); err != nil {
return 1
}
if !formatIsValid(c.format) {
c.UI.Error(fmt.Sprintf("Invalid format, valid formats are {%s}", strings.Join(getSupportedFormats(), "|")))
return 1
}
client, err := c.http.APIClient()
if err != nil {
c.UI.Error(fmt.Sprintf("Error connect to Consul agent: %s", err))
return 1
}
exportedServices, _, err := client.ExportedServices(nil)
if err != nil {
c.UI.Error(fmt.Sprintf("Error reading exported services: %v", err))
return 1
}
var filterType []api.ResolvedExportedService
filter, err := bexpr.CreateFilter(c.filter, nil, filterType)
if err != nil {
c.UI.Error(fmt.Sprintf("Error while creating filter: %s", err))
return 1
}
raw, err := filter.Execute(exportedServices)
if err != nil {
c.UI.Error(fmt.Sprintf("Error while filtering response: %s", err))
return 1
}
filteredServices := raw.([]api.ResolvedExportedService)
if len(filteredServices) == 0 {
c.UI.Info("No exported services found")
return 0
}
if c.format == JSONFormat {
output, err := json.MarshalIndent(filteredServices, "", " ")
if err != nil {
c.UI.Error(fmt.Sprintf("Error marshalling JSON: %s", err))
return 1
}
c.UI.Output(string(output))
return 0
}
c.UI.Output(formatExportedServices(filteredServices))
return 0
}
func formatExportedServices(services []api.ResolvedExportedService) string {
result := make([]string, 0, len(services)+1)
if services[0].Partition != "" {
result = append(result, "Service\x1fPartition\x1fNamespace\x1fConsumer Peers\x1fConsumer Partitions")
} else {
result = append(result, "Service\x1fConsumer Peers")
}
for _, expService := range services {
row := ""
peers := strings.Join(expService.Consumers.Peers, ", ")
partitions := strings.Join(expService.Consumers.Partitions, ", ")
if expService.Partition != "" {
row = fmt.Sprintf("%s\x1f%s\x1f%s\x1f%s\x1f%s", expService.Service, expService.Partition, expService.Namespace, peers, partitions)
} else {
row = fmt.Sprintf("%s\x1f%s", expService.Service, peers)
}
result = append(result, row)
}
return columnize.Format(result, &columnize.Config{Delim: string([]byte{0x1f})})
}
func (c *cmd) Synopsis() string {
return synopsis
}
func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const (
synopsis = "Lists exported services"
help = `
Usage: consul services exported-services [options]
Lists all the exported services and their consumers. Wildcards and sameness groups(Enterprise) are expanded.
Example:
$ consul services exported-services
`
)

323
command/services/exportedservices/exported_services_test.go
Unescape View File

@ -0,0 +1,323 @@
// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: BUSL-1.1
package exportedservices
import (
"encoding/json"
"testing"
"github.com/hashicorp/consul/agent"
"github.com/hashicorp/consul/api"
"github.com/mitchellh/cli"
"github.com/stretchr/testify/require"
)
func TestExportedServices_noTabs(t *testing.T) {
t.Parallel()
require.NotContains(t, New(cli.NewMockUi()).Help(), "\t")
}
func TestExportedServices_Error(t *testing.T) {
if testing.Short() {
t.Skip("too slow for testing.Short")
}
t.Parallel()
a := agent.NewTestAgent(t, ``)
defer a.Shutdown()
t.Run("No exported services", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
}
code := cmd.Run(args)
require.Equal(t, 0, code)
output := ui.OutputWriter.String()
require.Equal(t, "No exported services found\n", output)
})
t.Run("invalid format", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-format=toml",
}
code := cmd.Run(args)
require.Equal(t, 1, code, "exited successfully when it should have failed")
output := ui.ErrorWriter.String()
require.Contains(t, output, "Invalid format")
})
}
func TestExportedServices_Pretty(t *testing.T) {
if testing.Short() {
t.Skip("too slow for testing.Short")
}
t.Parallel()
a := agent.NewTestAgent(t, ``)
defer a.Shutdown()
client := a.Client()
ui := cli.NewMockUi()
c := New(ui)
set, _, err := client.ConfigEntries().Set(&api.ExportedServicesConfigEntry{
Name: "default",
Services: []api.ExportedService{
{
Name: "db",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
{
Peer: "west",
},
},
},
{
Name: "web",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
},
},
},
}, nil)
require.NoError(t, err)
require.True(t, set)
args := []string{
"-http-addr=" + a.HTTPAddr(),
}
code := c.Run(args)
require.Equal(t, 0, code)
output := ui.OutputWriter.String()
// Spot check some fields and values
require.Contains(t, output, "db")
require.Contains(t, output, "web")
}
func TestExportedServices_JSON(t *testing.T) {
if testing.Short() {
t.Skip("too slow for testing.Short")
}
t.Parallel()
a := agent.NewTestAgent(t, ``)
defer a.Shutdown()
client := a.Client()
ui := cli.NewMockUi()
c := New(ui)
set, _, err := client.ConfigEntries().Set(&api.ExportedServicesConfigEntry{
Name: "default",
Services: []api.ExportedService{
{
Name: "db",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
{
Peer: "west",
},
},
},
{
Name: "web",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
},
},
},
}, nil)
require.NoError(t, err)
require.True(t, set)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-format=json",
}
code := c.Run(args)
require.Equal(t, 0, code)
var resp []api.ResolvedExportedService
err = json.Unmarshal(ui.OutputWriter.Bytes(), &resp)
require.NoError(t, err)
require.Equal(t, 2, len(resp))
require.Equal(t, "db", resp[0].Service)
require.Equal(t, "web", resp[1].Service)
require.Equal(t, []string{"east", "west"}, resp[0].Consumers.Peers)
require.Equal(t, []string{"east"}, resp[1].Consumers.Peers)
}
func TestExportedServices_filter(t *testing.T) {
if testing.Short() {
t.Skip("too slow for testing.Short")
}
t.Parallel()
a := agent.NewTestAgent(t, ``)
defer a.Shutdown()
client := a.Client()
set, _, err := client.ConfigEntries().Set(&api.ExportedServicesConfigEntry{
Name: "default",
Services: []api.ExportedService{
{
Name: "db",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
{
Peer: "west",
},
},
},
{
Name: "web",
Consumers: []api.ServiceConsumer{
{
Peer: "east",
},
},
},
{
Name: "backend",
Consumers: []api.ServiceConsumer{
{
Peer: "west",
},
},
},
{
Name: "frontend",
Consumers: []api.ServiceConsumer{
{
Peer: "peer1",
},
{
Peer: "peer2",
},
},
},
},
}, nil)
require.NoError(t, err)
require.True(t, set)
t.Run("consumerPeer=east", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-format=json",
"-filter=" + `east in Consumers.Peers`,
}
code := cmd.Run(args)
require.Equal(t, 0, code)
var resp []api.ResolvedExportedService
err = json.Unmarshal(ui.OutputWriter.Bytes(), &resp)
require.NoError(t, err)
require.Equal(t, 2, len(resp))
require.Equal(t, "db", resp[0].Service)
require.Equal(t, "web", resp[1].Service)
require.Equal(t, []string{"east", "west"}, resp[0].Consumers.Peers)
require.Equal(t, []string{"east"}, resp[1].Consumers.Peers)
})
t.Run("consumerPeer=west", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-format=json",
"-filter=" + `west in Consumers.Peers`,
}
code := cmd.Run(args)
require.Equal(t, 0, code)
var resp []api.ResolvedExportedService
err = json.Unmarshal(ui.OutputWriter.Bytes(), &resp)
require.NoError(t, err)
require.Equal(t, 2, len(resp))
require.Equal(t, "backend", resp[0].Service)
require.Equal(t, "db", resp[1].Service)
require.Equal(t, []string{"west"}, resp[0].Consumers.Peers)
require.Equal(t, []string{"east", "west"}, resp[1].Consumers.Peers)
})
t.Run("consumerPeer=peer1", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-format=json",
"-filter=" + `peer1 in Consumers.Peers`,
}
code := cmd.Run(args)
require.Equal(t, 0, code)
var resp []api.ResolvedExportedService
err = json.Unmarshal(ui.OutputWriter.Bytes(), &resp)
require.NoError(t, err)
require.Equal(t, 1, len(resp))
require.Equal(t, "frontend", resp[0].Service)
require.Equal(t, []string{"peer1", "peer2"}, resp[0].Consumers.Peers)
})
t.Run("No exported services", func(t *testing.T) {
ui := cli.NewMockUi()
cmd := New(ui)
args := []string{
"-http-addr=" + a.HTTPAddr(),
"-filter=" + `unknown in Consumers.Peers`,
}
code := cmd.Run(args)
require.Equal(t, 0, code)
output := ui.OutputWriter.String()
require.Equal(t, "No exported services found\n", output)
})
}

143
website/content/api-docs/exported-services.mdx
Unescape View File

@ -0,0 +1,143 @@
---
layout: api
page_title: Exported Services - HTTP API
description: The /exported-services endpoint lists exported services and their consumers.
---
# Exported Services HTTP Endpoint
<Note>
The exported services HTTP API endpoint requires Consul v1.17.3 or newer.
</Note>
The `/exported-services` endpoint returns a list of exported services, as well as the admin partitions and cluster peers that consume the services.
This list consists of the services that were exported using an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services). Sameness groups and wildcards in the configuration entry are expanded in the response.
## List Exported Services
This endpoint returns a list of exported services.
| Method | Path | Produces |
| ------------------ | -------------------- | ------------------ |
| `GET` | `/exported-services` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | --------------- | ------------------------------ |
| `YES` | `none` | `none` | `mesh:read` or `operator:read` |
### Query Parameters
- `partition` `(string: "")` <EnterpriseAlert inline /> - Specifies the admin partition the services are exported from. When not specified, assumes the default value `default`.
### Sample Request
```shell-session
$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
http://127.0.0.1:8500/v1/exported-services
```
### Sample Response
<Tabs>
<Tab heading="CE">
```json
[
{
"Service": "frontend",
"Consumers": {
"Peers": [
"east",
"west",
]
}
},
{
"Service": "db",
"Consumers": {
"Peers": [
"east",
]
}
},
{
"Service": "web",
"Consumers": {
"Peers": [
"east",
"west"
]
}
}
]
```
</Tab>
<Tab heading="Enterprise">
```json
[
{
"Service": "frontend",
"Partition": "default",
"Namespace": "default",
"Consumers": {
"Peers": [
"east",
"west"
],
"Partitions": [
"part1"
]
}
},
{
"Service": "frontend",
"Partition": "default",
"Namespace": "ns",
"Consumers": {
"Peers": [
"east",
]
}
},
{
"Service": "web",
"Partition": "default",
"Namespace": "default",
"Consumers": {
"Peers": [
"west"
],
"Partitions": [
"part1"
]
}
},
{
"Service": "db",
"Partition": "default",
"Namespace": "default",
"Consumers": {
"Partitions": [
"part1"
]
}
}
]
```
</Tab>
</Tabs>

57
website/content/commands/services/exported-services.mdx
Unescape View File

@ -0,0 +1,57 @@
---
layout: commands
page_title: 'Commands: Exported Services'
description: >-
The `consul services exported-services` command lists exported services and their consumers.
---
# Consul Exported Services
Command: `consul services exported-services`
Corresponding HTTP API Endpoint: [\[GET\] /v1/exported-services](/consul/api-docs/exported-services)
The `exported-services` command displays the services that were exported using an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services). Sameness groups and wildcards in the configuration entry are expanded in the response.
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
| ACL Required |
| ------------------------------ |
| `mesh:read` or `operator:read` |
## Usage
Usage: `consul services exported-services [options]`
#### Command Options
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
- `-filter` - Specifies an expression to use for filtering the results. `Consumers.Peers` and `Consumers.Partitions' selectors are supported.
#### Enterprise Options
@include 'http_api_partition_options.mdx'
#### API Options
@include 'http_api_options_client.mdx'
## Examples
To list all exported services and consumers:
$ consul services exported-services
Service Consumer Peers
backend east, west
db west
frontend east, east-eu
web east
The following lists exported services with a filter expression:
$ consul services exported-services -filter='"west" in Consumers.Peers'
Service Consumer Peers
backend east, west
db west

4
website/data/api-docs-nav-data.json
Unescape View File

@ -131,6 +131,10 @@
"title": "Events",
"path": "event"
},
{
"title": "Exported Services",
"path": "exported-services"
},
{
"title": "HCP Consul Central Link",
"path": "hcp-link"

4
website/data/commands-nav-data.json
Unescape View File

@ -516,6 +516,10 @@
{
"title": "export",
"path": "services/export"
},
{
"title": "exported-services",
"path": "services/exported-services"
}
]
},

Write Preview
Loading…
Cancel
Save