website: docs for services CLI

website/source/docs/commands/index.html.md

@@ -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

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 <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
+```

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
+```

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
+```

website/source/layouts/docs.erb

@@ -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">