hashicorp/consul-esm

Consul ESM (External Service Monitor) 镜像文档

镜像概述

Consul ESM (External Service Monitor) 是一个与 Consul 协同运行的守护进程，主要用于对外部节点执行健康检查，并将这些健康检查的状态更新至 Consul 服务目录。若启用相关功能，还可管理外部节点的网络坐标更新，确保 Consul 能准确跟踪外部服务的位置信息。该镜像需配合 Consul 集群使用，扩展 Consul 对非集群内节点的监控能力。

核心功能与特性

核心功能

• 外部节点健康检查：对不在 Consul 集群内的外部节点执行用户定义的健康检查（如 HTTP、TCP、脚本检查等）。
• 健康状态同步：将外部节点的健康检查结果实时更新至 Consul 服务目录，确保目录状态与实际节点状态一致。
• 坐标管理（可选）：支持更新外部节点的网络坐标，帮助 Consul 实现基于地理位置的服务发现（需手动启用）。

关键特性

• 与 Consul API 深度集成，无需修改 Consul 核心组件即可扩展监控范围。
• 轻量化设计，资源占用低，可部署于边缘节点或专用监控实例。
• 配置灵活，支持通过配置文件或环境变量定义检查规则及节点属性。

使用场景与适用范围

典型使用场景

• 跨网络服务监控：监控位于不同网络环境（如公有云、合作伙伴网络）的外部服务节点。
• 遗留系统集成：对无法直接接入 Consul 集群的遗留应用节点执行健康检查。
• 混合架构管理：在混合云或多云架构中，统一监控分布在不同平台的外部服务。

适用范围

• 已部署 Consul 集群，需扩展对外部节点监控能力的环境。
• 需要通过 Consul 服务目录集中管理内外部服务健康状态的场景。
• 依赖网络坐标进行服务路由或故障转移的 Consul 部署环境。

使用方法与配置说明

前置条件

• 已运行的 Consul 集群（服务端或客户端节点均可，需确保网络可达）。
• 外部节点的基础信息（如节点名称、地址、健康检查规则）已预先定义。

配置方式

Consul ESM 支持通过配置文件（推荐）或环境变量进行配置，核心配置项如下：

核心配置参数

配置文件示例

创建 esm-config.hcl 配置文件，定义外部节点及健康检查规则：

hcl
consul {
  address = "consul-server:8500"
  token   = "your-acl-token"  # 若 Consul 未启用 ACL，可省略此行
}

external_node {
  name    = "external-db-node"
  address = "192.168.1.100"
}

health_checks = [
  {
    name     = "db-tcp-check"
    type     = "tcp"
    address  = "192.168.1.100"
    port     = 3306
    interval = "10s"
    timeout  = "5s"
  },
  {
    name     = "app-http-check"
    type     = "http"
    url      = "http://192.168.1.100:8080/health"
    interval = "5s"
    timeout  = "2s"
  }
]

enable_coordinates = true  # 启用坐标更新
log_level = "info"

Docker 部署示例

1. 使用 docker run 部署

bash
docker run -d \
  --name consul-esm \
  -v $(pwd)/esm-config.hcl:/etc/consul-esm/esm-config.hcl \  # 挂载配置文件
  -e CONSUL_ESM_CONFIG_FILE=/etc/consul-esm/esm-config.hcl \  # 指定配置文件路径
  hashicorp/consul-esm:latest

2. 使用 docker-compose 部署

创建 docker-compose.yml：

yaml
version: "3.8"

services:
  consul-esm:
    image: docker.xuanyuan.run/hashicorp/consul-esm:latest
    container_name: consul-esm
    volumes:
      - ./esm-config.hcl:/etc/consul-esm/esm-config.hcl
    environment:
      - CONSUL_ESM_CONFIG_FILE=/etc/consul-esm/esm-config.hcl
    restart: unless-stopped
    network_mode: "host"  # 若外部节点与容器不在同一网络，需配置端口映射或使用 host 网络

验证部署

1. 检查 Consul ESM 容器日志，确认无错误输出：

   bash
   docker logs consul-esm
   

2. 通过 Consul UI 或 API 查看外部节点状态：

   bash
   curl http://<consul-address>:8500/v1/catalog/node/<external-node-name>
   

   若返回节点信息及健康检查状态，则部署成功。

参考文档：Consul 官方 https://learn.hashicorp.com/tutorials/consul/service-registration-external-services