117 lines
3.9 KiB
Plaintext
117 lines
3.9 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: Services Register'
|
|
---
|
|
|
|
# Consul Agent Service Registration
|
|
|
|
Command: `consul services register`
|
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/register](/api-docs/agent/service#register-service)
|
|
|
|
The `services register` command registers a service with the local agent.
|
|
This command returns after registration and must be paired with explicit
|
|
service deregistration. This command simplifies service registration from
|
|
scripts, in dev mode, etc.
|
|
|
|
This is just one method of service registration. Services can also be
|
|
registered by placing a [service definition](/docs/agent/services)
|
|
in the Consul agent configuration directory and issuing a
|
|
[reload](/commands/reload). This approach is easiest for
|
|
configuration management systems that other systems that have access to
|
|
the configuration directory. Clients may also use the
|
|
[HTTP API](/api/agent/service) directly.
|
|
|
|
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` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul services register [options] [FILE...]`
|
|
|
|
This command can register either a single service using flags documented
|
|
below, or one or more services using service definition files in HCL
|
|
or JSON format. The service is registered against the specified Consul
|
|
agent (defaults to the local agent). This agent will execute all registered
|
|
health checks.
|
|
|
|
This command returns after registration succeeds. It must be paired with
|
|
a deregistration command or API call to remove the service. To ensure that
|
|
services are properly deregistered, it is **highly recommended** that
|
|
a check is created with the
|
|
[`DeregisterCriticalServiceAfter`](/api/agent/check#deregistercriticalserviceafter)
|
|
configuration set. This will ensure that even if deregistration failed for
|
|
any reason, the agent will automatically deregister the service instance after
|
|
it is unhealthy for the specified period of time.
|
|
|
|
Registered services are persisted in the agent state directory. If the
|
|
state directory remains unmodified, registered services will persist across
|
|
restarts.
|
|
|
|
~> **Warning for Consul operators:** The Consul agent persists registered
|
|
services in the local state directory. If this state directory is deleted
|
|
or lost, services registered with this command will need to be reregistered.
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_namespace_options.mdx'
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
#### Service Registration 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 register a single
|
|
service.
|
|
|
|
Note that the behavior of each of the fields below is exactly the same
|
|
as when constructing a standard [service definition](/docs/agent/services).
|
|
Please refer to that documentation for full details.
|
|
|
|
- `-id` - The ID of the service. This will default to `-name` if not set.
|
|
|
|
- `-name` - The name of the service to register.
|
|
|
|
- `-address` - The address of the service. If this isn't specified,
|
|
it will default to the address registered with the local agent.
|
|
|
|
- `-port` - The port of the service.
|
|
|
|
- `-socket` - The Unix Domain socket of the service. Conflicts with address and port flags.
|
|
|
|
- `-meta key=value` - Specify arbitrary KV metadata to associate with the
|
|
service instance. This can be specified multiple times.
|
|
|
|
- `-tag value` - Associate a tag with the service instance. This flag can
|
|
be specified multiples times.
|
|
|
|
## Examples
|
|
|
|
To create a simple service:
|
|
|
|
```shell-session
|
|
$ consul services register -name=web
|
|
```
|
|
|
|
To create a service from a configuration file:
|
|
|
|
```shell-session
|
|
$ cat web.json
|
|
{
|
|
"Service": {
|
|
"Name": "web"
|
|
}
|
|
}
|
|
|
|
$ consul services register web.json
|
|
```
|