status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Co-authored-by: Ashesh Vidyut <134911583+absolutelightning@users.noreply.github.com>

* 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>
This commit is contained in:
Tauhid Anjum 2024-02-06 09:01:20 +05:30 committed by GitHub
parent 922844b8e0
commit 0c509a60a4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 712 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.changelog/20331.txt Normal file
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
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 Normal file
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 Normal file
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 Normal file
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 Normal file
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
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
View File

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