Register Services with Service Definitions

One of the main goals of service discovery is to provide a catalog of available services. To that end, the agent provides a simple service definition format to declare the availability of a service and to potentially associate it with a health check. A health check associated with a service is considered to be an application-level check. Define services in a configuration file or add it at runtime using the HTTP interface.

Complete the Getting Started tutorials to get hands-on experience registering a simple service with a health check on your local machine.

Service Definition

Configure a service by providing the service definition to the agent. You can either specify the configuration file using the -config-file option, or specify the directory containing the service definition file with the -config-dir option. Consul can load service definitions saved as .json or .hcl files.

Send a SIGHUP to the running agent or use consul reload to check for new service definitions or to update existing services. Alternatively, the service can be registered dynamically using the HTTP API.

A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network. All possible parameters are included in the following example, but only the top-level service parameter and its name parameter child are required by default.

service {
  name = "redis"
  id   = "redis"
  port = 80
  tags = ["primary"]

  meta = {
    custom_meta_key = "custom_meta_value"
  }

  tagged_addresses = {
    lan = {
      address = "192.168.0.55"
      port    = 8000
    }

    wan = {
      address = "198.18.0.23"
      port    = 80
    }
  }

  port                = 8000
  socket_path         = "/tmp/redis.sock"
  enable_tag_override = false

  checks = [
    {
      args     = ["/usr/local/bin/check_redis.py"]
      interval = "10s"
    }
  ]

  kind              = "connect-proxy"
  proxy_destination = "redis"

  proxy = {
    destination_service_name  = "redis"
    destination_service_id    = "redis1"
    local_service_address     = "127.0.0.1"
    local_service_port        = 9090
    local_service_socket_path = "/tmp/redis.sock"
    mode                      = "transparent"

    transparent_proxy {
      outbound_listener_port = 22500
    }

    mesh_gateway = {
      mode = "local"
    }

    expose = {
      checks = true

      paths = [
        {
          path            = "/healthz"
          local_path_port = 8080
          listener_port   = 21500
          protocol        = "http2"
        }
      ]
    }
  }

  connect = {
    native = false
  }

  weights = {
    passing = 5
    warning = 1
  }

  token     = "233b604b-b92e-48c8-a253-5f11514e4b50"
  namespace = "foo"
}

{
  "service": {
    "id": "redis",
    "name": "redis",
    "tags": ["primary"],
    "address": "",
    "meta": {
      "meta": "for my service"
    },
    "tagged_addresses": {
      "lan": {
        "address": "192.168.0.55",
        "port": 8000,
      },
      "wan": {
        "address": "198.18.0.23",
        "port": 80
      }
    },
    "port": 8000,
    "socket_path": "/tmp/redis.sock",
    "enable_tag_override": false,
    "checks": [
      {
        "args": ["/usr/local/bin/check_redis.py"],
        "interval": "10s"
      }
    ],
    "kind": "connect-proxy",
    "proxy_destination": "redis", // Deprecated
    "proxy": {
      "destination_service_name": "redis",
      "destination_service_id": "redis1",
      "local_service_address": "127.0.0.1",
      "local_service_port": 9090,
      "local_service_socket_path": "/tmp/redis.sock",
      "mode": "transparent",
      "transparent_proxy": {
        "outbound_listener_port": 22500
      },
      "config": {},
      "upstreams": [],
      "mesh_gateway": {
        "mode": "local"
      },
      "expose": {
        "checks": true,
        "paths": [
          {
            "path": "/healthz",
            "local_path_port": 8080,
            "listener_port": 21500,
            "protocol": "http2"
          }
       ]
      }
    },
    "connect": {
      "native": false,
      "sidecar_service": {}
      "proxy": {  // Deprecated
        "command": [],
        "config": {}
      }
    },
    "weights": {
      "passing": 5,
      "warning": 1
    },
    "token": "233b604b-b92e-48c8-a253-5f11514e4b50",
    "namespace": "foo"
  }
}

The following table describes the available parameters for service definitions.

service

This is the root-level parameter that defines the service. You can specify the parameters to configure the service.

Adding Meta Data

You can add semantic meta data to the service using the meta parameter. This parameter defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service.

Security Configurations

If the ACL system is enabled, specify a value for the token parameter to provide an ACL token. This token is used for any interaction with the catalog for the service, including anti-entropy syncs and deregistration.

Services registered in Consul clusters where both Consul NamespacesEnterpriseEnterprise and the ACL system are enabled can be registered to specific namespaces that are associated with ACL tokens scoped to the namespace. Services registered with a service definition will not inherit the namespace associated with the ACL token specified in the token field. The namespace and the token parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.

Health Checks

You can add health checks to your service definition. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. The health check functionality is strongly integrated into the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query.

The health check name is automatically generated as service:<service-id>. If there are multiple service checks registered, the ID will be generated as service:<service-id>:<num> where <num> is an incrementing number starting from 1.

Consul includes several check types with different options. Refer to the health checks documentation for details.

Proxy

Service definitions allow for an optional proxy registration. Proxies used with Connect are registered as services in Consul's catalog. See the Proxy Service Registration reference for the available configuration options.

Connect

The kind parameter determines the service's role. Services can be configured to perform several roles, but you must omit the kind parameter for typical non-proxy instances.

The following roles are supported for service entries:

• connect-proxy: Defines the configuration for a connect proxy
• ingress-gateway: Defines the configuration for an ingress gateway
• mesh-gateway: Defines the configuration for a mesh gateway
• terminating-gateway: Defines the configuration for a terminating gateway

In the service definition example described above, the service is registered as a proxy because the kind property is set to connect-proxy. The proxy parameter is also required for Connect proxy registrations and is only valid if kind is connect-proxy. Refer to the Proxy Service Registration documentation for details about this type.

When the kind parameter is set to connect-proxy, the only required parameter for the proxy configuration is destination_service_name. Refer to the complete proxy configuration example for additional information.

The connect field can be specified to configure Connect for a service. This field is available in Consul 1.2.0 and later. The following parameters are available.

Deprecated parameters

Different Consul Connect parameters are supported for different Consul versions. The following table describes changes applicable to service discovery.

DNS SRV Weights

You can configure how the service responds to DNS SRV requests by specifying a set of states/weights in the weights field.

weights

When DNS SRV requests are made, the response will include the weights specified for the given state of the service. This allows some instances to be given higher weight if they have more capacity. It also allows load reduction on services with checks in warning status by giving passing instances a higher weight.

If a service is critical, it is excluded from DNS responses. Services with warning checks are included in responses by default, but excluded if the optional param only_passing = true is present in the agent DNS configuration or the passing query parameter is used via the API.

Enable Tag Override and Anti-Entropy

Services may also contain a token field to provide an ACL token. This token is used for any interaction with the catalog for the service, including anti-entropy syncs and deregistration.

You can optionally disable the anti-entropy feature for this service using the enable_tag_override flag. External agents can modify tags on services in the catalog, so subsequent sync operations can either maintain tag modifications or revert them. If enable_tag_override is set to TRUE, the next sync cycle may revert some service properties, but the tags would maintain the updated value. If enable_tag_override is set to FALSE, the next sync cycle will revert any updated service properties, including tags, to their original value.

It's important to note that this applies only to the locally registered service. If you have multiple nodes all registering the same service their enable_tag_override configuration and all other service configuration items are independent of one another. Updating the tags for the service registered on one node is independent of the same service (by name) registered on another node. If enable_tag_override is not specified the default value is false. See anti-entropy syncs for more info.

For Consul 0.9.3 and earlier you need to use enableTagOverride. Consul 1.0 supports both enable_tag_override and enableTagOverride but the latter is deprecated and has been removed as of Consul 1.1.

Tagged Addresses

Tagged addresses are additional addresses that may be defined for a node or service. Tagged addresses can be used by remote agents and services as alternative addresses for communicating with the given node or service. Multiple tagged addresses may be configured on a node or service.

The following example describes the syntax for defining a tagged address.

service {
  name = "redis"
  port = 80
  tagged_addresses {
    <tag> = {
      address = "<address>"
      port = port
    }
  }
}

{
  "service": {
    "name": "redis",
    "port": 80,
    "tagged_addresses": {
      "<tag>": {
        "address": "<address>",
        "port": port
      }
    }
  }
}

The following table provides an overview of the various tagged address types supported by Consul.

LAN tags

• lan - The IPv4 LAN address at which the node or service is accessible.
• lan_ipv4 - The IPv4 LAN address at which the node or service is accessible.
• lan_ipv6 - The IPv6 LAN address at which the node or service is accessible.

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    lan = {
      address = "192.0.2.10"
      port = 80
    }
    lan_ipv4 = {
      address = "192.0.2.10"
      port = 80
    }
    lan_ipv6 = {
      address = "2001:db8:1:2:cafe::1337"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "lan": {
        "address": "192.0.2.10",
        "port": 80
      },
      "lan_ipv4": {
        "address": "192.0.2.10",
        "port": 80
      },
      "lan_ipv6": {
        "address": "2001:db8:1:2:cafe::1337",
        "port": 80
      }
    }
  }
}

Virtual tags

Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:

1. Transparent proxy is enabled for the downstream and upstream services.
2. The upstream service is not configured for individual instances to be dialed directly.

Virtual addresses are not required to be routable IPs within the network. They are strictly a control plane construct used to provide a fixed address for the instances of a given logical service. Egress connections from the proxy to an upstream service will be destined to the IP address of an individual service instance, not the virtual address of the logical service.

Use the following address tag to specify the logical address at which the service can be reached by other services in the mesh.

• virtual - The virtual IP address at which a logical service is reachable.

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    virtual = {
      address = "203.0.113.50"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "virtual": {
        "address": "203.0.113.50",
        "port": 80
      }
    }
  }
}

WAN tags

One or more of the following address tags can be configured for a node or service to advertise how it should be accessed over the WAN.

• wan - The IPv4 WAN address at which the node or service is accessible when being dialed from a remote data center.
• wan_ipv4 - The IPv4 WAN address at which the node or service is accessible when being dialed from a remote data center.
• wan_ipv6 - The IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center.

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    wan = {
      address = "198.51.100.200"
      port = 80
    }
    wan_ipv4 = {
      address = "198.51.100.200"
      port = 80
    }
    wan_ipv6 = {
      address = "2001:db8:5:6:1337::1eaf"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "wan": {
        "address": "198.51.100.200",
        "port": 80
      },
      "wan_ipv4": {
        "address": "198.51.100.200",
        "port": 80
      },
      "wan_ipv6": {
        "address": "2001:db8:5:6:1337::1eaf",
        "port": 80
      }
    }
  }
}

Multiple Service Definitions

Multiple services definitions can be provided at once when registering services via the agent configuration by using the plural services key (registering multiple services in this manner is not supported using the HTTP API).

services {
  id = "red0"
  name = "redis"
  tags = [
    "primary"
  ]
  address = ""
  port = 6000
  checks = [
    {
      args = ["/bin/check_redis", "-p", "6000"]
      interval = "5s"
      timeout = "20s"
    }
  ]
}
services {
  id = "red1"
  name = "redis"
  tags = [
    "delayed",
    "secondary"
  ]
  address = ""
  port = 7000
  checks = [
    {
      args = ["/bin/check_redis", "-p", "7000"]
      interval = "30s"
      timeout = "60s"
    }
  ]
}

{
  "services": [
    {
      "id": "red0",
      "name": "redis",
      "tags": [
        "primary"
      ],
      "address": "",
      "port": 6000,
      "checks": [
        {
          "args": ["/bin/check_redis", "-p", "6000"],
          "interval": "5s",
          "timeout": "20s"
        }
      ]
    },
    {
      "id": "red1",
      "name": "redis",
      "tags": [
        "delayed",
        "secondary"
      ],
      "address": "",
      "port": 7000,
      "checks": [
        {
          "args": ["/bin/check_redis", "-p", "7000"],
          "interval": "30s",
          "timeout": "60s"
        }
      ]
    },
    ...
  ]
}

Service and Tag Names with DNS

Consul exposes service definitions and tags over the DNS interface. DNS queries have a strict set of allowed characters and a well-defined format that Consul cannot override. While it is possible to register services or tags with names that don't match the conventions, those services and tags will not be discoverable via the DNS interface. It is recommended to always use DNS-compliant service and tag names.

DNS-compliant service and tag names may contain any alpha-numeric characters, as well as dashes. Dots are not supported because Consul internally uses them to delimit service tags.

Service Definition Parameter Case

For historical reasons Consul's API uses CamelCased parameter names in responses, however its configuration file uses snake_case for both HCL and JSON representations. For this reason the registration HTTP APIs accept both name styles for service definition parameters although APIs will return the listings using CamelCase.

Note though that all config file formats require snake_case fields. We always document service definition examples using snake_case and JSON since this format works in both config files and API calls.