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

107 lines
3.5 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 Register'
2018-10-01 17:27:15 +00:00
---
# Consul Agent Service Registration
Command: `consul services register`
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
2020-04-09 23:46:54 +00:00
registered by placing a [service definition](/docs/agent/services)
2018-10-01 17:27:15 +00:00
in the Consul agent configuration directory and issuing a
[reload](/commands/reload). This approach is easiest for
2018-10-01 17:27:15 +00:00
configuration management systems that other systems that have access to
the configuration directory. Clients may also use the
2020-04-09 23:46:54 +00:00
[HTTP API](/api/agent/service) directly.
2018-10-01 17:27:15 +00:00
## 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
2020-04-09 23:46:54 +00:00
[`DeregisterCriticalServiceAfter`](/api/agent/check#deregistercriticalserviceafter)
2018-10-01 17:27:15 +00:00
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
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 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
2020-04-09 23:46:54 +00:00
as when constructing a standard [service definition](/docs/agent/services).
2018-10-01 17:27:15 +00:00
Please refer to that documentation for full details.
2020-04-07 18:55:19 +00:00
- `-id` - The ID of the service. This will default to `-name` if not set.
2018-10-01 17:27:15 +00:00
2020-04-07 18:55:19 +00:00
- `-name` - The name of the service to register.
2018-10-01 17:27:15 +00:00
2020-04-07 18:55:19 +00:00
- `-address` - The address of the service. If this isn't specified,
2018-10-01 17:27:15 +00:00
it will default to the address registered with the local agent.
2020-04-07 18:55:19 +00:00
- `-port` - The port of the service.
2018-10-01 17:27:15 +00:00
- `-socket` - The Unix Domain socket of the service. Conflicts with address and port flags.
2020-04-07 18:55:19 +00:00
- `-meta key=value` - Specify arbitrary KV metadata to associate with the
2018-10-01 17:27:15 +00:00
service instance. This can be specified multiple times.
2020-04-07 18:55:19 +00:00
- `-tag value` - Associate a tag with the service instance. This flag can
2018-10-01 17:27:15 +00:00
be specified multiples times.
## Examples
To create a simple service:
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-01 17:27:15 +00:00
$ consul services register -name=web
```
To create a service 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 register web.json
```