How-to Deregister Services in Consul

The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

Expected Outcome

A service is deregistered in Consul and the catalog is updated.

Use Case

The appropriate procedure depends on the following two scenarios:

1. The registered service is still running on the agent (Deregistering a Service)
   • Deregistration is done on the Host of the Consul agent
     
     Note: There are scenarios when a deregistered service will reappear after deregistration.  For example, if you deregister a service managed by Nomad the Nomad agent may have the Consul agent re-register the service. In these scenarios, stop the service before deregistering it in Consul.
2. The service has been discontinued, but its entry remains in the catalog (Update the Catalog)
   

   This happens when the service's host is terminated without running the deregister command

   • The Consul Catalog needs to have the service deregistered from a Consul server

Procedure

Deregistering a Service

1. Identify the agent(s) that have the registered service
   • Pull the details using Catalog HTTP API List Services call
2. Log into the host of the service
3. Deregister the service by running the consul services deregister CLI command 
   • There is no need to manually update the catalog since the client agent will automatically notify the Consul servers to perform the necessary actions

Update the Catalog

1. From a Consul server, identify the service(s) in the Consul catalog
   • Pull the details using Catalog HTTP API List Services call
2. Use the Consul Catalog API Deregister Entity to deregister the service(s)

Usage Example

In the below example, the service is named hello-app.

1. Create a JSON file with the service(s) Datacenter, Node name, and ServiceID

   $ curl -sk $CONSUL_HTTP_ADDR/v1/catalog/service/hello-app\?pretty\&passing=false | jq -r '.[] | {Datacenter:.Datacenter, Node: .Node, ServiceID: .ServiceID}' | tee /tmp/service.json
   {
   "Datacenter": "apigw",
   "Node": "lima-apigw-cli-02",
   "ServiceID": "_nomad-task-a459c1bc-c966-ffee-836a-964458742323-group-apps-hello-app-9090"
   }

2. Deregister the service(s)

   $ curl -sk -H "x-consul-token: <token with node:write,service:write>" $CONSUL_HTTP_ADDR/v1/catalog/deregister -X PUT --data @/tmp/service.json
   true

To ensure the complete removal of a Connect-Enabled service from your service mesh, you must also deregister the associated <service-name>-sidecar-proxy service. This eliminates any lingering service instances and prevents potential conflicts.

Additional Information

• Catalog HTTP API

  • List Services
  • Deregister Entity
• CLI Command: Consul Agent Service Deregistration