website: docs for services CLI
This commit is contained in:
Mitchell Hashimoto
parent
1b7f836398
commit
3bbbc3fd66
|
|
@ -28,16 +28,17 @@ Usage: consul [--version] [--help] <command> [<args>]
|
|||
Available commands are:
|
||||
agent Runs a Consul agent
|
||||
catalog Interact with the catalog
|
||||
connect Interact with Consul Connect
|
||||
event Fire a new event
|
||||
exec Executes a command on Consul nodes
|
||||
force-leave Forces a member of the cluster to enter the "left" state
|
||||
info Provides debugging information for operators.
|
||||
intention Interact with Connect service intentions
|
||||
join Tell Consul agent to join cluster
|
||||
keygen Generates a new encryption key
|
||||
keyring Manages gossip layer encryption keys
|
||||
kv Interact with the key-value store
|
||||
leave Gracefully leaves the Consul cluster and shuts down
|
||||
license Get/Put the Consul Enterprise license (Enterprise-only)
|
||||
lock Execute a command holding a lock
|
||||
maint Controls node or service maintenance mode
|
||||
members Lists the members of a Consul cluster
|
||||
|
|
@ -45,6 +46,7 @@ Available commands are:
|
|||
operator Provides cluster-level tools for Consul operators
|
||||
reload Triggers the agent to reload configuration files
|
||||
rtt Estimates network round trip time between nodes
|
||||
services Interact with services
|
||||
snapshot Saves, restores and inspects snapshots of Consul server state
|
||||
validate Validate config files/directories
|
||||
version Prints the Consul version
|
||||
|
|
|
|||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Services"
|
||||
sidebar_current: "docs-commands-services"
|
||||
---
|
||||
|
||||
# Consul Agent Services
|
||||
|
||||
Command: `consul services`
|
||||
|
||||
The `services` command has subcommands for interacting with Consul services
|
||||
registered with the [local agent](/docs/agent/basics.html). These provide
|
||||
useful commands such as `register` and `deregister` for easily registering
|
||||
services in scripts, dev mode, etc.
|
||||
To view all services in the catalog, instead of only agent-local services,
|
||||
see the [`catalog services`](/docs/commands/catalog/services.html) command.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul services <subcommand>`
|
||||
|
||||
For the exact documentation for your Consul version, run `consul services -h` to
|
||||
view the complete list of subcommands.
|
||||
|
||||
```text
|
||||
Usage: consul services <subcommand> [options] [args]
|
||||
|
||||
...
|
||||
|
||||
Subcommands:
|
||||
deregister Deregister services with the local agent
|
||||
register Register services with the local agent
|
||||
```
|
||||
|
||||
For more information, examples, and usage about a subcommand, click on the name
|
||||
of the subcommand in the sidebar.
|
||||
|
||||
## Basic Examples
|
||||
|
||||
To create a simple service:
|
||||
|
||||
```text
|
||||
$ consul services register -name=web
|
||||
```
|
||||
|
||||
To create a service from a configuration file:
|
||||
|
||||
```text
|
||||
$ cat web.json
|
||||
{
|
||||
"Service": {
|
||||
"Name": "web"
|
||||
}
|
||||
}
|
||||
|
||||
$ consul services register web.json
|
||||
```
|
||||
|
||||
To deregister a service:
|
||||
|
||||
```sh
|
||||
# Either style works:
|
||||
$ consul services deregister web.json
|
||||
|
||||
$ consul services deregister -id web
|
||||
```
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Services Deregister"
|
||||
sidebar_current: "docs-commands-services-deregister"
|
||||
---
|
||||
|
||||
# Consul Agent Service Deregistration
|
||||
|
||||
Command: `consul services deregister`
|
||||
|
||||
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](/docs/commands/reload.html) Consul is the correct method to
|
||||
deregister. See [Service Definition](/docs/agent/services.html) for more
|
||||
information about registering services generally.
|
||||
|
||||
## 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
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### 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.
|
||||
|
||||
* `-id` - The ID of the service.
|
||||
|
||||
## Examples
|
||||
|
||||
To deregister by ID:
|
||||
|
||||
```text
|
||||
$ consul services deregister -id=web
|
||||
```
|
||||
|
||||
To deregister from a configuration file:
|
||||
|
||||
```text
|
||||
$ cat web.json
|
||||
{
|
||||
"Service": {
|
||||
"Name": "web"
|
||||
}
|
||||
}
|
||||
|
||||
$ consul services deregister web.json
|
||||
```
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Services Register"
|
||||
sidebar_current: "docs-commands-services-register"
|
||||
---
|
||||
|
||||
# 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
|
||||
registered by placing a [service definition](/docs/agent/services.html)
|
||||
in the Consul agent configuration directory and issuing a
|
||||
[reload](/docs/commands/reload.html). 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.html) directly.
|
||||
|
||||
## 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.html#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
|
||||
|
||||
<%= partial "docs/commands/http_api_options_client" %>
|
||||
|
||||
#### 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.html).
|
||||
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.
|
||||
|
||||
* `-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:
|
||||
|
||||
```text
|
||||
$ consul services register -name=web
|
||||
```
|
||||
|
||||
To create a service from a configuration file:
|
||||
|
||||
```text
|
||||
$ cat web.json
|
||||
{
|
||||
"Service": {
|
||||
"Name": "web"
|
||||
}
|
||||
}
|
||||
|
||||
$ consul services register web.json
|
||||
```
|
||||
|
|
@ -185,6 +185,18 @@
|
|||
<a href="/docs/commands/rtt.html">rtt</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-services") %>>
|
||||
<a href="/docs/commands/services.html">services</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-services-register") %>>
|
||||
<a href="/docs/commands/services/register.html">register</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-services-deregister") %>>
|
||||
<a href="/docs/commands/services/deregister.html">deregister</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-snapshot") %>>
|
||||
<a href="/docs/commands/snapshot.html">snapshot</a>
|
||||
<ul class="nav">
|
||||
|
|
|
|||
Loading…
Reference in New Issue