hashicorp / hashicorp/consul

Bug: Undesirable UX in consul CLI when retrieving service intentions

Open
#13,608 2 comments 0 reactions 0 assignees View on GitHub
type/bug
Dominant language
Go
Stars
30.1k
Forks
4.6k
Avg merge
1d 18h
Merged PRs (30d)
39

Description

#### Overview of the Issue

I have a service intention, and want to retrieve configuration data from the CLI, to troubleshoot. The practitioner's process of retrieving an intention's configuration isn't clear and provides insufficient information/breadcrumbs.

Starting off, I use `consul intention` to understand this CLI subcommand:

```shell
bash-4.2# consul intention
Usage: consul intention [options] [args]

This command has subcommands for interacting with intentions. Intentions
are permissions describing which services are allowed to communicate via
Connect. Here are some simple examples, and more detailed examples are
available in the subcommands or the documentation.

Create an intention to allow "web" to talk to "db":

$ consul intention create web db

Test whether a "web" is allowed to connect to "db":

$ consul intention check web db

List all intentions:

$ consul intention list

Find all intentions for communicating to the "db" service:

$ consul intention match db

For more examples, ask for subcommand help or view the documentation.

Subcommands:
check Check whether a connection between two services is allowed.
create Create intentions for service connections.
delete Delete an intention.
get Show information about an intention.
list List intentions.
match Show intentions that match a source or destination.

```
The docs returned from `consul intention` do not contain an example for `consul intention get`, and advise the following:

>For more examples, ask for subcommand help or view the documentation.

A practitioner will assume this could mean `consul intention get help`, a reasonable assumption as other CLIs (`aws` as an example) provide the string `help` as a reserved keyword to generate the help docs for a given subcommand. We do not do this, and assume this string is the name of a service.

```shell
bash-4.2# consul intention get help
Error reading the intention: Unexpected response 400: Bad request: failed config entry lookup: index error: UUID must be 36 characters
```

There's no breadcrumb for the practitioner to understand what they are doing incorrectly here. Using a guess, we can ascertain that `-h` is the correct usage:

```shell
bash-4.2# consul intention get -h
Usage: consul intention get [options] SRC DST
Usage: consul intention get [options] ID

Read and show the details about an intention. The intention can be looked
up via an exact source/destination match or via the unique intention ID.

$ consul intention get web db

. . .
```

* The CLI's `consul intention list` output doesn't provide a value for ID (Note: These Service Intentions were created by Kubernetes planfiles with the service intentions CRD, I'm not sure if this would prevent creation of a UUID). So the second usage example is not usable.

List intentions, no ID/UUID is displayed:

```shell
bash-4.2# consul intention list
ID Source Action Destination Precedence
api-gateway allow nginx 9
frontend allow public-api 9
nginx allow public-api 9
product-api allow postgres 9
public-api allow payments 9
public-api allow product-api 9
```

Get an intention, returning an error, because I didn't provide the destination. The error is confusing to the practitioner as it remarks that I am missing the UUID. But the previous returned data from `consul intention list` shows that the UUID column is empty. How would I pass a UUID if I can't lookup a UUID? The issue in reality is that I didn't pass the destination, but this could be easily overlooked if the help docs aren't easily accessible.

```shell
bash-4.2# consul intention get product-api
Error reading the intention: Unexpected response 400: Bad request: failed config entry lookup: index error: UUID must be 36 characters
bash-4.2# consul intention
```

### Operating system and Environment details
Consul v1.12.2
Revision 19041f20
Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)

Consul installation deployed to Kubernetes with consul-k8s, using latest chart, version 1.12.2, with an upstream HCP Consul Server cluster.

### Next steps:

* Improve the help docs to provide clear and explicit instructions in the CLI on how to retrieve consul service intentions.
* Improve the command help to understand how to access help docs of subcommands. (i.e. `consul intention get -h`
* Provide a mechanism to user from this CLI command to retrieve the UUID of a specific intention. (This could be accessible from the HTTP API, but I think this could be accessible via the CLI?)

Thank you! 😺

Contributor guide

Open the contributing guide

Research direction

Start with the `consul intention` and `consul intention get` CLI entry points, then reproduce the documented commands and errors from the issue. Trace how subcommand help, intention listing, UUID lookup, and missing arguments are handled. Done means the CLI provides clear retrieval guidance, exposes or explains the required identifier, and gives actionable errors for incomplete commands.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
cli, developer-experience
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.