June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
        • WAN Federation
      • Compatibility Matrix
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Overview
      • task
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.1.x
      • v0.2.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.5.x
      • v0.6.0-beta
    • Overview
    • ACL
  • Guides
Type '/' to Search

»Watches

Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health checks) which is monitored for updates. When an update is detected, an external handler is invoked. A handler can be any executable or HTTP endpoint. As an example, you could watch the status of health checks and notify an external system when a check is critical.

Watches are implemented using blocking queries in the HTTP API. Agents automatically make the proper API calls to watch for changes and inform a handler when the data view has updated.

Watches can be configured as part of the agent's configuration, causing them to run once the agent is initialized. Reloading the agent configuration allows for adding or removing watches dynamically.

Alternatively, the watch command enables a watch to be started outside of the agent. This can be used by an operator to inspect data in Consul or to easily pipe data into processes without being tied to the agent lifecycle.

In either case, the type of the watch must be specified. Each type of watch supports different parameters, some required and some optional. These options are specified in a JSON body when using agent configuration or as CLI flags for the watch command.

»Handlers

The watch configuration specifies the view of data to be monitored. Once that view is updated, the specified handler is invoked. Handlers can be either an executable or an HTTP endpoint. A handler receives JSON formatted data with invocation info, following a format that depends on the type of the watch. Each watch type documents the format type. Because they map directly to an HTTP API, handlers should expect the input to match the format of the API. A Consul index is also given, corresponding to the responses from the HTTP API.

»Executable

An executable handler reads the JSON invocation info from stdin. Additionally, the CONSUL_INDEX environment variable will be set to the Consul index. Anything written to stdout is logged.

Here is an example configuration, where handler_type is optionally set to script:

Consul watch with script handler defined in agent configuration
Consul watch with script handler defined in agent configuration
HCL
  • HCL
  • JSON
watches = [
  {
    type = "key"
    key = "foo/bar/baz"
    handler_type = "script"
    args = ["/usr/bin/my-service-handler.sh", "-redis"]
  }
]
agent-config.hcl
watches = [
  {
    type = "key"
    key = "foo/bar/baz"
    handler_type = "script"
    args = ["/usr/bin/my-service-handler.sh", "-redis"]
  }
]
{
  "watches": [
    {
      "type": "key",
      "key": "foo/bar/baz",
      "handler_type": "script",
      "args": ["/usr/bin/my-service-handler.sh", "-redis"]
    }
  ]
}
agent-config.json
{
  "watches": [
    {
      "type": "key",
      "key": "foo/bar/baz",
      "handler_type": "script",
      "args": ["/usr/bin/my-service-handler.sh", "-redis"]
    }
  ]
}

Prior to Consul 1.0, watches used a single handler field to define the command to run, and would always run in a shell. In Consul 1.0, the args array was added so that handlers can be run without a shell. The handler field is deprecated, and you should include the shell in the args to run under a shell, eg. "args": ["sh", "-c", "..."].

»HTTP endpoint

An HTTP handler sends an HTTP request when a watch is invoked. The JSON invocation info is sent as a payload along the request. The response also contains the Consul index as a header named X-Consul-Index.

The HTTP handler can be configured by setting handler_type to http. Additional handler options are set using http_handler_config. The only required parameter is the path field which specifies the URL to the HTTP endpoint. Consul uses POST as the default HTTP method, but this is also configurable. Other optional fields are header, timeout and tls_skip_verify. The watch invocation data is always sent as a JSON payload.

Here is an example configuration:

Consul watch with HTTP handler defined in agent configuration
Consul watch with HTTP handler defined in agent configuration
HCL
  • HCL
  • JSON
watches = [
  {
    type = "key"
    key = "foo/bar/baz"
    handler_type = "http"
    http_handler_config {
      path = "https://localhost:8000/watch"
      method = "POST"
      header = {
        x-foo = ["bar", "baz"]
      }
      timeout = "10s"
      tls_skip_verify = false
    }
  }
]
agent-config.hcl
watches = [
  {
    type = "key"
    key = "foo/bar/baz"
    handler_type = "http"
    http_handler_config {
      path = "https://localhost:8000/watch"
      method = "POST"
      header = {
        x-foo = ["bar", "baz"]
      }
      timeout = "10s"
      tls_skip_verify = false
    }
  }
]
{
  "watches": [
    {
      "type": "key",
      "key": "foo/bar/baz",
      "handler_type": "http",
      "http_handler_config": {
        "path": "https://localhost:8000/watch",
        "method": "POST",
        "header": { "x-foo": ["bar", "baz"] },
        "timeout": "10s",
        "tls_skip_verify": false
      }
    }
  ]
}
agent-config.json
{
  "watches": [
    {
      "type": "key",
      "key": "foo/bar/baz",
      "handler_type": "http",
      "http_handler_config": {
        "path": "https://localhost:8000/watch",
        "method": "POST",
        "header": { "x-foo": ["bar", "baz"] },
        "timeout": "10s",
        "tls_skip_verify": false
      }
    }
  ]
}

»Global Parameters

In addition to the parameters supported by each option type, there are a few global parameters that all watches support:

  • datacenter - Can be provided to override the agent's default datacenter.
  • token - Can be provided to override the agent's default ACL token.
  • args - The handler subprocess and arguments to invoke when the data view updates.
  • handler - The handler shell command to invoke when the data view updates.

»Watch Types

The following types are supported. Detailed documentation on each is below:

  • key - Watch a specific KV pair
  • keyprefix - Watch a prefix in the KV store
  • services - Watch the list of available services
  • nodes - Watch the list of nodes
  • service- Watch the instances of a service
  • checks - Watch the value of health checks
  • event - Watch for custom user events

»Type: key

The "key" watch type is used to watch a specific key in the KV store. It requires that the key parameter be specified.

This maps to the /v1/kv/ API internally.

Here is an example configuration:

Example key watch type
Example key watch type
HCL
  • HCL
  • JSON
{
  type = "key"
  key = "foo/bar/baz"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
}
{
  type = "key"
  key = "foo/bar/baz"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
}
{
  "type": "key",
  "key": "foo/bar/baz",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"]
}
{
  "type": "key",
  "key": "foo/bar/baz",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"]
}

Or, using the watch command:

$ consul watch -type=key -key=foo/bar/baz /usr/bin/my-key-handler.sh
$ consul watch -type=key -key=foo/bar/baz /usr/bin/my-key-handler.sh

An example of the output of this command:

{
  "Key": "foo/bar/baz",
  "CreateIndex": 1793,
  "ModifyIndex": 1793,
  "LockIndex": 0,
  "Flags": 0,
  "Value": "aGV5",
  "Session": ""
}
{
  "Key": "foo/bar/baz",
  "CreateIndex": 1793,
  "ModifyIndex": 1793,
  "LockIndex": 0,
  "Flags": 0,
  "Value": "aGV5",
  "Session": ""
}

»Type: keyprefix

The keyprefix watch type is used to watch a prefix of keys in the KV store. It requires that the prefix parameter be specified. This watch returns all keys matching the prefix whenever any key matching the prefix changes.

This maps to the /v1/kv/ API internally.

Here is an example configuration:

Example keyprefix watch type
Example keyprefix watch type
HCL
  • HCL
  • JSON
{
  type = "keyprefix"
  prefix = "foo/"
  args = ["/usr/bin/my-prefix-handler.sh", "-redis"]
}
{
  type = "keyprefix"
  prefix = "foo/"
  args = ["/usr/bin/my-prefix-handler.sh", "-redis"]
}
{
  "type": "keyprefix",
  "prefix": "foo/",
  "args": ["/usr/bin/my-prefix-handler.sh", "-redis"]
}
{
  "type": "keyprefix",
  "prefix": "foo/",
  "args": ["/usr/bin/my-prefix-handler.sh", "-redis"]
}

Or, using the watch command:

$ consul watch -type=keyprefix -prefix=foo/ /usr/bin/my-prefix-handler.sh
$ consul watch -type=keyprefix -prefix=foo/ /usr/bin/my-prefix-handler.sh

An example of the output of this command:

[
  {
    "Key": "foo/bar",
    "CreateIndex": 1796,
    "ModifyIndex": 1796,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "TU9BUg==",
    "Session": ""
  },
  {
    "Key": "foo/baz",
    "CreateIndex": 1795,
    "ModifyIndex": 1795,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "YXNkZg==",
    "Session": ""
  },
  {
    "Key": "foo/test",
    "CreateIndex": 1793,
    "ModifyIndex": 1793,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "aGV5",
    "Session": ""
  }
]
[
  {
    "Key": "foo/bar",
    "CreateIndex": 1796,
    "ModifyIndex": 1796,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "TU9BUg==",
    "Session": ""
  },
  {
    "Key": "foo/baz",
    "CreateIndex": 1795,
    "ModifyIndex": 1795,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "YXNkZg==",
    "Session": ""
  },
  {
    "Key": "foo/test",
    "CreateIndex": 1793,
    "ModifyIndex": 1793,
    "LockIndex": 0,
    "Flags": 0,
    "Value": "aGV5",
    "Session": ""
  }
]

»Type: services

The "services" watch type is used to watch the list of available services. It has no parameters.

This maps to the /v1/catalog/services API internally.

Below is an example configuration:

Example services watch type
Example services watch type
HCL
  • HCL
  • JSON
{
  type = "services"
  args = ["/usr/bin/my-services-handler.sh"]
}
{
  type = "services"
  args = ["/usr/bin/my-services-handler.sh"]
}
{
  "type": "services",
  "args": ["/usr/bin/my-services-handler.sh"]
}
{
  "type": "services",
  "args": ["/usr/bin/my-services-handler.sh"]
}

Or, using the watch command:

$ consul watch -type=services /usr/bin/my-services-handler.sh
$ consul watch -type=services /usr/bin/my-services-handler.sh

An example of the output of this command:

{
  "consul": [],
  "redis": [],
  "web": []
}
{
  "consul": [],
  "redis": [],
  "web": []
}

»Type: nodes

The "nodes" watch type is used to watch the list of available nodes. It has no parameters.

This maps to the /v1/catalog/nodes API internally.

Below is an example configuration:

Example nodes watch type
Example nodes watch type
HCL
  • HCL
  • JSON
{
  type = "nodes"
  args = ["/usr/bin/my-nodes-handler.sh"]
}
{
  type = "nodes"
  args = ["/usr/bin/my-nodes-handler.sh"]
}
{
  "type": "nodes",
  "args": ["/usr/bin/my-nodes-handler.sh"]
}
{
  "type": "nodes",
  "args": ["/usr/bin/my-nodes-handler.sh"]
}

Or, using the watch command:

$ consul watch -type=nodes /usr/bin/my-nodes-handler.sh
$ consul watch -type=nodes /usr/bin/my-nodes-handler.sh

An example of the output of this command:

[
  {
    "ID": "8d3088b5-ce7d-0b94-f185-ae70c3445642",
    "Node": "nyc1-consul-1",
    "Address": "192.0.2.10",
    "Datacenter": "dc1",
    "TaggedAddresses": null,
    "Meta": null,
    "CreateIndex": 23792324,
    "ModifyIndex": 23792324
  },
  {
    "ID": "1edb564e-65ee-9e60-5e8a-83eae4637357",
    "Node": "nyc1-worker-1",
    "Address": "192.0.2.20",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "192.0.2.20",
      "lan_ipv4": "192.0.2.20",
      "wan": "192.0.2.20",
      "wan_ipv4": "192.0.2.20"
    },
    "Meta": {
      "consul-network-segment": "",
      "host-ip": "192.0.2.20",
      "pod-name": "hashicorp-consul-q7nth"
    },
    "CreateIndex": 23792336,
    "ModifyIndex": 23792338
  }
]
[
  {
    "ID": "8d3088b5-ce7d-0b94-f185-ae70c3445642",
    "Node": "nyc1-consul-1",
    "Address": "192.0.2.10",
    "Datacenter": "dc1",
    "TaggedAddresses": null,
    "Meta": null,
    "CreateIndex": 23792324,
    "ModifyIndex": 23792324
  },
  {
    "ID": "1edb564e-65ee-9e60-5e8a-83eae4637357",
    "Node": "nyc1-worker-1",
    "Address": "192.0.2.20",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "192.0.2.20",
      "lan_ipv4": "192.0.2.20",
      "wan": "192.0.2.20",
      "wan_ipv4": "192.0.2.20"
    },
    "Meta": {
      "consul-network-segment": "",
      "host-ip": "192.0.2.20",
      "pod-name": "hashicorp-consul-q7nth"
    },
    "CreateIndex": 23792336,
    "ModifyIndex": 23792338
  }
]

»Type: service

The "service" watch type is used to monitor the providers of a single service. It requires the service parameter and optionally takes the parameters tag and passingonly. The tag parameter will filter by one or more tags. It may be either a single string value or a slice of strings. The passingonly parameter is a boolean that will filter to only the instances passing all health checks.

This maps to the /v1/health/service API internally.

Here is an example configuration with a single tag:

Example service watch type
Example service watch type
HCL
  • HCL
  • JSON
{
  type = "service"
  service = "redis"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
  tag = "bar"
}
{
  type = "service"
  service = "redis"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
  tag = "bar"
}
{
  "type": "service",
  "service": "redis",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"],
  "tag": "bar"
}
{
  "type": "service",
  "service": "redis",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"],
  "tag": "bar"
}

Here is an example configuration with multiple tags:

Example service watch type with multiple tags
Example service watch type with multiple tags
HCL
  • HCL
  • JSON
{
  type = "service"
  service = "redis"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
  tag = ["bar", "foo"]
}
{
  type = "service"
  service = "redis"
  args = ["/usr/bin/my-service-handler.sh", "-redis"]
  tag = ["bar", "foo"]
}
{
  "type": "service",
  "service": "redis",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"],
  "tag": ["bar", "foo"]
}
{
  "type": "service",
  "service": "redis",
  "args": ["/usr/bin/my-service-handler.sh", "-redis"],
  "tag": ["bar", "foo"]
}

Or, using the watch command:

Single tag:

$ consul watch -type=service -service=redis -tag=bar /usr/bin/my-service-handler.sh
$ consul watch -type=service -service=redis -tag=bar /usr/bin/my-service-handler.sh

Multiple tags:

$ consul watch -type=service -service=redis -tag=bar -tag=foo /usr/bin/my-service-handler.sh
$ consul watch -type=service -service=redis -tag=bar -tag=foo /usr/bin/my-service-handler.sh

An example of the output of this command:

[
  {
    "Node": {
      "ID": "f013522f-aaa2-8fc6-c8ac-c84cb8a56405",
      "Node": "hashicorp-consul-server-1",
      "Address": "192.0.2.50",
      "Datacenter": "dc1",
      "TaggedAddresses": null,
      "Meta": null,
      "CreateIndex": 23785783,
      "ModifyIndex": 23785783
    },
    "Service": {
      "ID": "redis",
      "Service": "redis",
      "Tags": [],
      "Meta": null,
      "Port": 6379,
      "Address": "",
      "Weights": {
        "Passing": 1,
        "Warning": 1
      },
      "EnableTagOverride": false,
      "CreateIndex": 23785794,
      "ModifyIndex": 23785794,
      "Proxy": {
        "MeshGateway": {},
        "Expose": {}
      },
      "Connect": {}
    },
    "Checks": [
      {
        "Node": "hashicorp-consul-server-1",
        "CheckID": "serfHealth",
        "Name": "Serf Health Status",
        "Status": "passing",
        "Notes": "",
        "Output": "Agent alive and reachable",
        "ServiceID": "",
        "ServiceName": "",
        "ServiceTags": [],
        "Type": "",
        "Definition": {
          "Interval": "0s",
          "Timeout": "0s",
          "DeregisterCriticalServiceAfter": "0s",
          "HTTP": "",
          "Header": null,
          "Method": "",
          "Body": "",
          "TLSServerName": "",
          "TLSSkipVerify": false,
          "TCP": "",
          "GRPC": "",
          "GRPCUseTLS": false
        },
        "CreateIndex": 23785783,
        "ModifyIndex": 23791503
      }
    ]
  }
]
[
  {
    "Node": {
      "ID": "f013522f-aaa2-8fc6-c8ac-c84cb8a56405",
      "Node": "hashicorp-consul-server-1",
      "Address": "192.0.2.50",
      "Datacenter": "dc1",
      "TaggedAddresses": null,
      "Meta": null,
      "CreateIndex": 23785783,
      "ModifyIndex": 23785783
    },
    "Service": {
      "ID": "redis",
      "Service": "redis",
      "Tags": [],
      "Meta": null,
      "Port": 6379,
      "Address": "",
      "Weights": {
        "Passing": 1,
        "Warning": 1
      },
      "EnableTagOverride": false,
      "CreateIndex": 23785794,
      "ModifyIndex": 23785794,
      "Proxy": {
        "MeshGateway": {},
        "Expose": {}
      },
      "Connect": {}
    },
    "Checks": [
      {
        "Node": "hashicorp-consul-server-1",
        "CheckID": "serfHealth",
        "Name": "Serf Health Status",
        "Status": "passing",
        "Notes": "",
        "Output": "Agent alive and reachable",
        "ServiceID": "",
        "ServiceName": "",
        "ServiceTags": [],
        "Type": "",
        "Definition": {
          "Interval": "0s",
          "Timeout": "0s",
          "DeregisterCriticalServiceAfter": "0s",
          "HTTP": "",
          "Header": null,
          "Method": "",
          "Body": "",
          "TLSServerName": "",
          "TLSSkipVerify": false,
          "TCP": "",
          "GRPC": "",
          "GRPCUseTLS": false
        },
        "CreateIndex": 23785783,
        "ModifyIndex": 23791503
      }
    ]
  }
]

»Type: checks

The "checks" watch type is used to monitor the checks of a given service or those in a specific state. It optionally takes the service parameter to filter to a specific service or the state parameter to filter to a specific state. By default, it will watch all checks.

This maps to the /v1/health/state/ API if monitoring by state or /v1/health/checks/ if monitoring by service.

Here is an example configuration for monitoring by state:

Example checks watch type for all services in the passing state
Example checks watch type for all services in the passing state
HCL
  • HCL
  • JSON
{
  type = "checks"
  state = "passing"
  args = ["/usr/bin/my-check-handler.sh", "-passing"]
}
{
  type = "checks"
  state = "passing"
  args = ["/usr/bin/my-check-handler.sh", "-passing"]
}
{
  "type": "checks",
  "state": "passing",
  "args": ["/usr/bin/my-check-handler.sh", "-passing"]
}
{
  "type": "checks",
  "state": "passing",
  "args": ["/usr/bin/my-check-handler.sh", "-passing"]
}

Here is an example configuration for monitoring by service:

Example checks watch type for a specific service
Example checks watch type for a specific service
HCL
  • HCL
  • JSON
{
  type = "checks"
  service = "redis"
  args = ["/usr/bin/my-check-handler.sh", "-redis"]
}
{
  type = "checks"
  service = "redis"
  args = ["/usr/bin/my-check-handler.sh", "-redis"]
}
{
  "type": "checks",
  "service": "redis",
  "args": ["/usr/bin/my-check-handler.sh", "-redis"]
}
{
  "type": "checks",
  "service": "redis",
  "args": ["/usr/bin/my-check-handler.sh", "-redis"]
}

Or, using the watch command:

State:

$ consul watch -type=checks -state=passing /usr/bin/my-check-handler.sh -passing
$ consul watch -type=checks -state=passing /usr/bin/my-check-handler.sh -passing

Service:

$ consul watch -type=checks -service=redis /usr/bin/my-check-handler.sh -redis
$ consul watch -type=checks -service=redis /usr/bin/my-check-handler.sh -redis

An example of the output of this command:

[
  {
    "Node": "foobar",
    "CheckID": "service:redis",
    "Name": "Service 'redis' check",
    "Status": "passing",
    "Notes": "",
    "Output": "",
    "ServiceID": "redis",
    "ServiceName": "redis"
  }
]
[
  {
    "Node": "foobar",
    "CheckID": "service:redis",
    "Name": "Service 'redis' check",
    "Status": "passing",
    "Notes": "",
    "Output": "",
    "ServiceID": "redis",
    "ServiceName": "redis"
  }
]

»Type: event

The "event" watch type is used to monitor for custom user events. These are fired using the consul event command. It takes only a single optional name parameter which restricts the watch to only events with the given name.

This maps to the /v1/event/list API internally.

Here is an example configuration:

Example event watch type
Example event watch type
HCL
  • HCL
  • JSON
{
  type = "event"
  name = "web-deploy"
  args = ["/usr/bin/my-event-handler.sh", "-web-deploy"]
}
{
  type = "event"
  name = "web-deploy"
  args = ["/usr/bin/my-event-handler.sh", "-web-deploy"]
}
{
  "type": "event",
  "name": "web-deploy",
  "args": ["/usr/bin/my-event-handler.sh", "-web-deploy"]
}
{
  "type": "event",
  "name": "web-deploy",
  "args": ["/usr/bin/my-event-handler.sh", "-web-deploy"]
}

Or, using the watch command:

$ consul watch -type=event -name=web-deploy /usr/bin/my-event-handler.sh -web-deploy
$ consul watch -type=event -name=web-deploy /usr/bin/my-event-handler.sh -web-deploy

An example of the output of this command:

[
  {
    "ID": "f07f3fcc-4b7d-3a7c-6d1e-cf414039fcee",
    "Name": "web-deploy",
    "Payload": "MTYwOTAzMA==",
    "NodeFilter": "",
    "ServiceFilter": "",
    "TagFilter": "",
    "Version": 1,
    "LTime": 18
  },
  ...
]
[
  {
    "ID": "f07f3fcc-4b7d-3a7c-6d1e-cf414039fcee",
    "Name": "web-deploy",
    "Payload": "MTYwOTAzMA==",
    "NodeFilter": "",
    "ServiceFilter": "",
    "TagFilter": "",
    "Version": 1,
    "LTime": 18
  },
  ...
]

To fire a new web-deploy event the following could be used:

$ consul event -name=web-deploy 1609030
$ consul event -name=web-deploy 1609030
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager