github.com/criteo-forks/consul@v1.4.5-criteonogrpc/website/source/docs/commands/services/register.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Services Register"
     4  sidebar_current: "docs-commands-services-register"
     5  ---
     6  
     7  # Consul Agent Service Registration
     8  
     9  Command: `consul services register`
    10  
    11  The `services register` command registers a service with the local agent.
    12  This command returns after registration and must be paired with explicit
    13  service deregistration. This command simplifies service registration from
    14  scripts, in dev mode, etc.
    15  
    16  This is just one method of service registration. Services can also be
    17  registered by placing a [service definition](/docs/agent/services.html)
    18  in the Consul agent configuration directory and issuing a
    19  [reload](/docs/commands/reload.html). This approach is easiest for
    20  configuration management systems that other systems that have access to
    21  the configuration directory. Clients may also use the
    22  [HTTP API](/api/agent/service.html) directly.
    23  
    24  ## Usage
    25  
    26  Usage: `consul services register [options] [FILE...]`
    27  
    28  This command can register either a single service using flags documented
    29  below, or one or more services using service definition files in HCL
    30  or JSON format. The service is registered against the specified Consul
    31  agent (defaults to the local agent). This agent will execute all registered
    32  health checks.
    33  
    34  This command returns after registration succeeds. It must be paired with
    35  a deregistration command or API call to remove the service. To ensure that
    36  services are properly deregistered, it is **highly recommended** that
    37  a check is created with the
    38  [`DeregisterCriticalServiceAfter`](/api/agent/check.html#deregistercriticalserviceafter)
    39  configuration set. This will ensure that even if deregistration failed for
    40  any reason, the agent will automatically deregister the service instance after
    41  it is unhealthy for the specified period of time.
    42  
    43  Registered services are persisted in the agent state directory. If the
    44  state directory remains unmodified, registered services will persist across
    45  restarts.
    46  
    47  ~> **Warning for Consul operators:** The Consul agent persists registered
    48  services in the local state directory. If this state directory is deleted
    49  or lost, services registered with this command will need to be reregistered.
    50  
    51  #### API Options
    52  
    53  <%= partial "docs/commands/http_api_options_client" %>
    54  
    55  #### Service Registration Flags
    56  
    57  The flags below should only be set if _no arguments_ are given. If no
    58  arguments are given, the flags below can be used to register a single
    59  service.
    60  
    61  Note that the behavior of each of the fields below is exactly the same
    62  as when constructing a standard [service definition](/docs/agent/services.html).
    63  Please refer to that documentation for full details.
    64  
    65  * `-id` - The ID of the service. This will default to `-name` if not set.
    66  
    67  * `-name` - The name of the service to register.
    68  
    69  * `-address` - The address of the service. If this isn't specified,
    70    it will default to the address registered with the local agent.
    71  
    72  * `-port` - The port of the service.
    73  
    74  * `-meta key=value` - Specify arbitrary KV metadata to associate with the
    75    service instance. This can be specified multiple times.
    76  
    77  * `-tag value` - Associate a tag with the service instance. This flag can
    78    be specified multiples times.
    79  
    80  ## Examples
    81  
    82  To create a simple service:
    83  
    84  ```text
    85  $ consul services register -name=web
    86  ```
    87  
    88  To create a service from a configuration file:
    89  
    90  ```text
    91  $ cat web.json
    92  {
    93    "Service": {
    94      "Name": "web"
    95    }
    96  }
    97  
    98  $ consul services register web.json
    99  ```