diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md index 68c55a5b14..f242ecbf55 100644 --- a/website/source/docs/commands/index.html.md +++ b/website/source/docs/commands/index.html.md @@ -28,16 +28,17 @@ Usage: consul [--version] [--help] [] 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 diff --git a/website/source/docs/commands/services.html.md b/website/source/docs/commands/services.html.md new file mode 100644 index 0000000000..f80e4b7f7b --- /dev/null +++ b/website/source/docs/commands/services.html.md @@ -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 ` + +For the exact documentation for your Consul version, run `consul services -h` to +view the complete list of subcommands. + +```text +Usage: consul services [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 +``` diff --git a/website/source/docs/commands/services/deregister.html.md b/website/source/docs/commands/services/deregister.html.md new file mode 100644 index 0000000000..87316383cf --- /dev/null +++ b/website/source/docs/commands/services/deregister.html.md @@ -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 +``` diff --git a/website/source/docs/commands/services/register.html.md b/website/source/docs/commands/services/register.html.md new file mode 100644 index 0000000000..9fd69feb14 --- /dev/null +++ b/website/source/docs/commands/services/register.html.md @@ -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 +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 372f8de59b..1731c80ca6 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -185,6 +185,18 @@ rtt + > + services + + + > snapshot