Bug: Undesirable UX in consul CLI when retrieving service intentions

webdog commented 2 years ago

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:

bash-4.2# consul intention
Usage: consul intention <subcommand> [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.

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:

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:

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.

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! 😺

blake commented 1 year ago

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)

This is expected behavior. The Intention.ID field was deprecated with the introduction to service intentions. Once an intention is migrated from a legacy intention to service intention, the ID field is cleared.

Intention.ID after migration is stored in the LegacyID field. After transitioning this field is cleared.

The Kubernetes CRD creates service intentions, not legacy intentions, so it is correct that the ID field is empty.

webdog commented 1 year ago

@blake Appreciate you following up. The point remains that this is still poor UX for the Consul practitioner. Whether or not behavior is intended or correct by some measure is not relevant to the user that is attempting to get information from consul, but can't because of some limitation that they may or may not be aware of. The next steps are clear in that this could be an opportunity for improving the UX. Limitations of Consul schema/attrs don't have to limit the experience a user has with the Consul CLI.

As a heads-up, I left HashiCorp awhile back, so I don't have any ownership of this issue anymore, so feel free to manage it as you will. Thanks! 😃

hashicorp / consul