k3d-proxy 镜像文档

镜像概述和主要用途

k3d-proxy 是一个辅助容器镜像，专为 k3d（轻量级 Kubernetes 集群管理工具）设计，用于支持集群代理功能。该镜像基于 NGINX 构建，并通过 confd 实现动态配置管理，核心用途是将外部请求代理到 k3d 集群内部的服务，简化集群访问流程。

核心功能和特性

• NGINX 代理能力：基于 NGINX 实现高性能 HTTP/HTTPS 请求转发，支持标准代理特性（如负载均衡、路径路由）。
• confd 动态配置：集成 confd 工具，可根据 k3d 集群状态（如服务地址、端口变化）自动生成和更新 NGINX 配置，无需手动干预。
• k3d 集群适配：针对 k3d 集群的网络结构和服务发现机制优化，确保代理请求准确路由至集群内部服务。
• 轻量级设计：镜像体积小巧，部署快速，资源占用低，适合本地开发和测试环境。

使用场景和适用范围

使用场景

• 本地开发环境：在使用 k3d 搭建本地 Kubernetes 集群时，通过 k3d-proxy 统一入口代理，简化集群内部服务（如微服务、API 服务）的外部访问配置。
• 测试环境流量管理：集中管理对 k3d 集群的请求流量，便于日志收集、访问控制和流量监控。
• 多服务代理：当 k3d 集群中部署多个服务时，通过路径或域名路由实现请求分发，模拟生产环境的反向代理架构。

适用范围

• 目标用户：k3d 用户，需具备基础的 k3d 集群管理能力。
• 环境限制：适用于开发、测试环境，不建议用于生产环境。

使用方法和配置说明

快速启动（docker run）

通过以下命令启动 k3d-proxy 容器，将外部请求代理到指定 k3d 集群：

docker run -d \
  --name k3d-proxy \
  -p 8080:80 \  # 映射主机端口8080到容器内NGINX端口80
  -e K3D_CLUSTER_NAME=my-k3d-cluster \  # 指定k3d集群名称
  -e PROXY_TARGET_PORT=80 \  # 集群内部服务目标端口
  rancher/k3d-proxy:latest

docker-compose 配置示例

使用 docker-compose 管理容器，配置更结构化：

version: '3'
services:
  k3d-proxy:
    image: rancher/k3d-proxy:latest
    container_name: k3d-proxy
    ports:
      - "8080:80"  # 代理端口映射（主机:容器）
    environment:
      - K3D_CLUSTER_NAME=my-k3d-cluster  # k3d集群名称（必填）
      - PROXY_TARGET_PORT=80  # 集群内部服务端口
      - CONFD_INTERVAL=60  # confd配置检查间隔（秒）
    restart: unless-stopped

配置参数说明

k3d-proxy 的配置通过环境变量和 confd 配置文件实现，核心参数如下：

1. 集群连接参数

• K3D_CLUSTER_NAME：k3d 集群名称（必填），用于识别目标集群（如 my-k3d-cluster）。
• K3D_CLUSTER_API_URL：k3d 集群 API 服务器地址（可选，默认通过集群名称自动发现）。

2. 代理服务参数

• PROXY_PORT：容器内 NGINX 监听端口（默认 80）。
• PROXY_TARGET_PORT：k3d 集群内部服务的目标端口（默认 80）。
• PROXY_TIMEOUT：NGINX 代理超时时间（默认 60s，格式：60s）。

3. confd 配置参数

• CONFD_BACKEND：confd 配置后端类型（默认 etcd，k3d 集群通常使用 etcd 存储配置）。
• CONFD_INTERVAL：confd 检查配置更新的间隔时间（默认 30s，单位：秒）。
• CONFD_NODE：confd 后端节点地址（可选，默认通过 k3d 集群自动获取）。

环境变量说明

源码地址

k3d-proxy 源码托管于 GitHub：[***]