hashicorp/consul-k8s

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

1. 镜像概述和主要用途

consul-k8s 是 HashiCorp 提供的官方镜像，用于实现 Consul 与 Kubernetes（K8s）的原生集成。该镜像包含控制平面组件，负责协调 Consul 与 K8s 集群的交互，提供服务注册、配置管理、服务网格等核心功能。新镜像已迁移至 Docker Hub 仓库：https://hub.docker.com/repository/docker/hashicorp/consul-k8s-control-plane%E3%80%82

主要用途：作为 Consul 与 K8s 集群的集成桥梁，简化在 K8s 环境中部署、管理和使用 Consul 的流程，实现微服务架构下的服务发现、配置同步和流量管理。

2. 核心功能和特性

2.1 服务注册与发现

• 自动注册：监听 K8s 资源（如 Deployment、StatefulSet）事件，自动将 Pod 服务注册至 Consul 集群。
• 服务健康检查：集成 K8s liveness/readiness probe，同步服务健康状态至 Consul。
• DNS 解析：通过 Consul DNS 或 K8s CoreDNS 插件，实现跨服务域名解析。

2.2 配置管理

• 配置同步：将 Consul KV 或 Config Entries（如服务默认配置、意图策略）同步至 K8s ConfigMap/Secret。
• 动态更新：支持配置变更的热更新，无需重启 K8s 服务。

2.3 服务网格集成（Consul Connect）

• Sidecar 自动注入：通过 K8s MutatingWebhook，为 Pod 自动注入 Consul Connect Sidecar 代理。
• 流量管理：支持基于 Consul Intentions 的服务间访问控制，以及 TCP/HTTP 流量路由。
• TLS 加密：自动生成和轮换服务间通信的 TLS 证书，确保传输安全。

2.4 安全特性

• RBAC 集成：基于 K8s ServiceAccount 实现细粒度权限控制。
• 审计日志：记录控制平面操作日志，支持与 K8s 审计系统集成。

2.5 K8s 原生集成

• 资源适配：支持 K8s 原生资源（如 Namespace、Label）与 Consul 服务元数据的映射。
• Helm 一键部署：提供官方 Helm Chart，简化集群级部署和配置。

3. 使用场景和适用范围

3.1 适用场景

• K8s 微服务部署：需实现服务发现、配置管理的微服务架构。
• 服务网格需求：需通过 Consul Connect 实现服务间流量加密、访问控制的场景。
• 跨集群服务注册：多 K8s 集群或混合云环境下的跨集群服务发现。
• 配置中心：需集中管理多环境（开发、测试、生产）服务配置的场景。

3.2 适用范围

• 用户：K8s 集群管理员、微服务开发团队、DevOps 工程师。
• 环境：单节点 K8s（测试）、生产级 K8s 集群（如 EKS、GKE、AKS 或自建集群）。
• 版本兼容性：支持 K8s 1.21+ 及 Consul 1.11+ 版本。

4. 详细使用方法和配置说明

4.1 镜像拉取

从 Docker Hub 拉取最新版本镜像：

bash
docker pull hashicorp/consul-k8s-control-plane:latest

指定版本（推荐生产环境使用固定版本）：

bash
docker pull hashicorp/consul-k8s-control-plane:1.2.3  # 替换为实际版本号

4.2 Helm Chart 安装（推荐）

通过官方 Helm Chart 部署 consul-k8s 控制平面及 Consul 集群：

4.2.1 添加 Helm 仓库

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

4.2.2 安装 Consul 集群及控制平面

bash
helm install consul hashicorp/consul \
  --namespace consul --create-namespace \
  --set global.name=consul \
  --set server.replicas=3 \  # 生产环境推荐 3+ 副本
  --set client.enabled=true \
  --set connectInject.enabled=true  # 启用 Connect Sidecar 注入

4.3 环境变量配置

控制平面容器支持通过环境变量调整行为，常用变量如下：

4.4 常用配置参数（Helm Values）

通过 values.yaml 自定义部署配置，核心参数示例：

yaml
# 控制平面配置
controller:
  enabled: true  # 启用控制平面控制器
  replicas: 2    # 控制平面副本数（生产环境推荐 2+）

# Consul 服务器配置
server:
  enabled: true
  replicas: 3
  storageClass: "standard"  # 持久化存储类
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"

# Connect 注入配置
connectInject:
  enabled: true
  default: true  # 对所有 Pod 自动注入 Sidecar（可通过注解禁用）
  transparentProxy:
    enabled: true  # 启用透明代理

# 服务网格配置
meshGateway:
  enabled: true  # 启用网格网关（跨数据中心通信）

5. 部署示例

5.1 Helm 自定义配置部署

bash
# 创建自定义 values.yaml
cat > values.yaml << EOF
global:
  name: consul
  datacenter: dc1
controller:
  enabled: true
  logLevel: debug
connectInject:
  enabled: true
  default: false  # 需手动注解 Pod 才注入 Sidecar
server:
  replicas: 3
EOF

# 安装或升级 Helm Release
helm install consul hashicorp/consul \
  --namespace consul --create-namespace \
  -f values.yaml

5.2 服务注册示例（K8s Deployment）

通过注解手动启用服务注册和 Sidecar 注入：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-service
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: example-service
  template:
    metadata:
      labels:
        app: example-service
      annotations:
        consul.hashicorp.com/connect-inject: "true"  # 启用 Sidecar 注入
        consul.hashicorp.com/service-name: "example-service"  # 注册到 Consul 的服务名
        consul.hashicorp.com/health-check-path: "/health"  # 健康检查路径
    spec:
      containers:
      - name: service
        image: nginx:alpine
        ports:
        - containerPort: 80

6. 注意事项

• 版本兼容性：确保 consul-k8s-control-plane 版本与 Consul 服务器版本匹配（参考 官方兼容性矩阵）。
• 资源需求：控制平面建议分配至少 200m CPU 和 256Mi 内存，避免因资源不足导致同步延迟。
• 安全配置：生产环境需启用 TLS 加密（通过 global.tls.enabled: true）和 RBAC 权限控制。
• 升级策略：通过 Helm 滚动升级，避免控制平面中断导致服务注册异常。