open-consul/website/content/commands/services/deregister.mdx

79 lines
2.1 KiB
Plaintext
Raw Normal View History

2018-10-01 17:27:15 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Services Deregister'
2018-10-01 17:27:15 +00:00
---
# Consul Agent Service Deregistration
Command: `consul services deregister`
2022-01-11 13:26:58 +00:00
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/deregister/:service_id](/api-docs/agent/service#deregister-service)
2018-10-01 17:27:15 +00:00
The `services deregister` command deregisters a service with the local agent.
Note that this command can only deregister services that were registered
with the agent specified (defaults to the local agent) and is meant to
be paired with `services register`.
This is just one method for service deregistration. If the service was
registered with a configuration file, then deleting that file and
[reloading](/commands/reload) Consul is the correct method to
2020-04-09 23:46:54 +00:00
deregister. See [Service Definition](/docs/agent/services) for more
2018-10-01 17:27:15 +00:00
information about registering services generally.
The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api/features/blocking) and [agent caching](/api/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
| ACL Required |
| --------------- |
| `service:write` |
2018-10-01 17:27:15 +00:00
## Usage
Usage: `consul services deregister [options] [FILE...]`
This command can deregister either a single service using the `-id` flag
documented below, or one or more services using service definition files
in HCL or JSON format.
This flexibility makes it easy to pair the command with the
`services register` command since the argument syntax is the same.
#### API Options
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
2018-10-01 17:27:15 +00:00
#### Enterprise Options
2020-04-07 18:55:19 +00:00
@include 'http_api_namespace_options.mdx'
@include 'http_api_partition_options.mdx'
2018-10-01 17:27:15 +00:00
#### Service Deregistration Flags
The flags below should only be set if _no arguments_ are given. If no
arguments are given, the flags below can be used to deregister a single
service.
2020-04-07 18:55:19 +00:00
- `-id` - The ID of the service.
2018-10-01 17:27:15 +00:00
## Examples
To deregister by ID:
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-01 17:27:15 +00:00
$ consul services deregister -id=web
```
To deregister from a configuration file:
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-01 17:27:15 +00:00
$ cat web.json
{
"Service": {
"Name": "web"
}
}
$ consul services deregister web.json
```