hashicorp / hashicorp/consul

Provide clearer warning when Name is used when ID is needed instead

Open
#10,861 3 comments 2 reactions 0 assignees View on GitHub
theme/operator-usability type/enhancement type/umbrella-☂️
Dominant language
Go
Stars
30.1k
Forks
4.6k
Avg merge
1d 18h
Merged PRs (30d)
39

Description

#### Feature Description

Some entities within Consul have an ID and a Name (e.g., services). When the CLI or an API endpoint for such an entity specifically requires an ID, and will not work with a Name, Consul should provide an error message that makes this mistake clear to the user.

Example taken from #3122: let's say a user has a service with ID `web-service-id` and Name `web-service-name`. If the user executes `/v1/agent/service/deregister/web-service-name`, the following is output to the log:
```
2017/06/07 16:59:47 [WARN] agent: Failed to deregister service "web-service-name": Service does not exist
```

That error message is very misleading, as a service with that _name_ does exist... just not a service with that _id_. The user might reasonably conclude something is wrong with the Consul catalog / state, when the actual problem is that the wrong field was used in the API call. Perhaps if Consul fails to lookup a service with that _id_, it could lookup whether any services exist with that name and, if some do, output a clearer warning message... such as:

```
2017/06/07 16:59:47 [WARN] agent: Failed to deregister service "web-service-name": a service ID must be used to deregister a service, not a service name.
```

This description will be updated to include relevant cases in the list below.

API:
- [x] GET `/agent/service/:service_id`: requires service ID, not name
- [x] PUT `/agent/service/deregister/:service_id`: requires service ID, not name (potentially related issues: #9861, #3122, #9415). See PR https://github.com/hashicorp/consul/pull/10894.
- [ ] PUT `/catalog/deregister`: requires node ID, not name (user has tried to deregister using the node name in this issue and in the past #10848)... **EDIT:** the docs are wrong, node name is required, not ID. Need to update the docs.

#### Use Case(s)

Ease troubleshooting of any CLI or API endpoints that accept an ID but not a name.

Contributor guide

Open the contributing guide

Research direction

Start with the listed /agent/service/:service_id, /agent/service/deregister/:service_id, and /catalog/deregister API handlers, then review related issues #3122, #9861, #9415, and PR #10894. Done means ID-versus-name mistakes produce clear warnings for the applicable endpoints and the catalog documentation reflects that node name is required.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api
Issue type
Feature
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.