hashicorp/consul-k8s-control-plane

Consul + Kubernetes (consul-k8s) 镜像文档

1. 镜像概述和主要用途

consul-k8s 是一个提供 Consul 与 Kubernetes 原生集成的工具，其二进制文件封装了多种核心用例，如服务同步、注入 Connect 边车等。该项目旨在简化 Consul 在 Kubernetes 环境中的部署与使用，支持快速迭代 Kubernetes 集成功能，且版本独立于 Consul 主版本，无需强制升级 Consul 即可获取新的集成特性。

Consul 与 Kubernetes 的集成详细文档可参考 Consul 官方网站，本文档仅提供基础概述。

2. 核心功能和特性

2.1 服务目录同步（Catalog Sync）

• 功能描述：实现 Consul 服务与 Kubernetes 服务的双向同步。此功能允许 Kubernetes 集群轻松访问外部服务，同时使非 Kubernetes 节点能够发现并访问 Kubernetes 服务。
• 版本要求：需 Consul 1.1+
• 详细文档：Consul 服务同步文档

2.2 Consul 服务网格（Connect）

• 功能描述：在 Kubernetes 上运行 Consul 服务网格（即 Consul Connect）。该功能会注入 Envoy 边车代理，并将 Pod 注册到 Consul。
• 版本要求：需 Consul 1.3+
• 详细文档：Consul Connect on Kubernetes

3. 使用场景和适用范围

3.1 服务目录同步场景

• 跨环境服务发现：当 Kubernetes 集群需要访问外部非 Kubernetes 环境的服务（如物理机、虚拟机部署的服务），或外部环境需发现 Kubernetes 集群内服务时，通过服务目录同步实现双向可见性。
• 混合云/多云架构：在混合云或多云环境中，统一服务发现机制，简化跨平台服务通信。

3.2 Consul 服务网格场景

• Kubernetes 服务网格部署：需在 Kubernetes 集群内实现服务间安全通信、流量控制（如熔断、重试）、可观测性（如流量监控）时，通过 Consul Connect 注入 Envoy 边车，构建服务网格。
• 微服务治理：对 Kubernetes 上的微服务进行统一治理，包括服务注册、健康检查、身份验证等。

3.3 适用范围

• 已部署 Consul 且需与 Kubernetes 集成的环境。
• 需实现跨 Kubernetes 与外部环境服务发现的场景。
• 需在 Kubernetes 上构建服务网格的微服务架构。

4. 使用方法和配置说明

4.1 Helm Chart 安装（推荐）

官方推荐通过 https://github.com/hashicorp/consul-helm 安装，可自动配置 Consul 与 Kubernetes 的集成，适用于现有 Kubernetes 集群。

基本步骤：

1. 添加 Helm 仓库：

   bash
   helm repo add hashicorp https://helm.releases.hashicorp.com
   

2. 更新仓库索引：

   bash
   helm repo update
   

3. 安装 Consul Helm Chart（可通过 --set 参数自定义配置）：

   bash
   helm install consul hashicorp/consul --namespace consul --create-namespace
   

4.2 Docker 镜像使用

consul-k8s 提供 Docker 镜像 hashicorp/consul-k8s，可用于在调度环境中手动运行。

4.2.1 拉取镜像

bash
docker pull hashicorp/consul-k8s:latest  # 或指定版本，如 hashicorp/consul-k8s:1.2.3

4.2.2 运行容器示例

手动运行 consul-k8s 容器（需根据具体用例指定命令和配置）：

bash
docker run -d \
  --name consul-k8s \
  -v /path/to/config:/config \  # 挂载配置目录（如需要）
  hashicorp/consul-k8s:latest \
  <command>  # 指定具体命令，如 catalog-sync、connect-inject 等

4.2.3 Docker Compose 配置示例

yaml
version: '3'
services:
  consul-k8s:
    image: hashicorp/consul-k8s:latest
    volumes:
      - ./config:/config  # 挂载本地配置目录
    command: <command>  # 如 "catalog-sync --config /config/sync.hcl"
    restart: unless-stopped

4.3 原始二进制文件安装

可从 HashiCorp 发布目录 下载原始二进制文件，直接运行或构建自定义包。

基本步骤：

1. 下载对应版本的二进制文件（如 Linux amd64）：

   bash
   wget https://releases.hashicorp.com/consul-k8s/<version>/consul-k8s_<version>_linux_amd64.zip
   

2. 解压并安装：

   bash
   unzip consul-k8s_<version>_linux_amd64.zip
   sudo mv consul-k8s /usr/local/bin/
   

3. 直接运行命令（如服务同步）：

   bash
   consul-k8s catalog-sync --help  # 查看命令帮助
   

4.4 配置说明

• Helm Chart 配置：主要通过 Helm Chart 的 values.yaml 文件或 --set 命令行参数自定义，具体配置项参考 https://github.com/hashicorp/consul-helm#configuration%E3%80%82
• 命令行参数：二进制文件和 Docker 镜像运行时，可通过命令行参数配置（如 --config 指定配置文件路径），具体参数可通过 consul-k8s <command> --help 查看。
• 详细配置：完整配置说明请参考 Consul 官网 Kubernetes 集成文档。