emissaryingress/emissary

Emissary-ingress 镜像文档

概述

Emissary-ingress 是一个基于 Envoy 代理的开源 Kubernetes 入口控制器和 API 网关，旨在简化 Kubernetes 集群的入站流量管理。它通过 Kubernetes 原生资源（如 Ingress、CustomResourceDefinition）提供声明式配置，支持动态流量路由、服务发现和高级流量管理策略，适用于微服务架构下的复杂通信场景。

核心功能与特性

1. Kubernetes 入口控制

• 完全兼容 Kubernetes Ingress API，支持标准 Ingress 资源配置
• 扩展 Kubernetes 入口功能，提供更细粒度的流量控制能力

2. 高级 API 网关能力

• 支持基于路径、主机名、请求头、查询参数的复杂路由规则
• 实现 API 版本控制（如 URI 路径、请求头版本区分）
• 提供流量镜像、分流和重试机制

3. Envoy 深度集成

• 内置 Envoy 代理，利用其高性能和丰富的流量管理特性
• 自动生成和管理 Envoy 配置，无需手动编写复杂的 Envoy 配置文件

4. 动态配置与热更新

• 通过 Kubernetes CRD（如 Mapping、Host、TLSContext）实现动态配置
• 配置变更实时生效，无需重启代理实例

5. 多团队与多租户支持

• 支持 RBAC 权限控制，实现资源隔离
• 允许不同团队独立管理各自的路由规则和 API

6. 安全与合规

• 集成 OAuth2、JWT、API Key 等认证机制
• 支持 TLS 终止、mTLS（服务间加密通信）
• 提供请求速率限制和访问控制策略

7. 可观测性

• 内置 Prometheus 指标暴露，支持流量监控
• 集成分布式追踪（Jaeger、Zipkin）
• 详细的访问日志和错误日志

使用场景与适用范围

1. 微服务架构流量管理

• 管理跨多个微服务的入站请求路由
• 实现服务间通信的负载均衡和故障转移

2. 多租户 Kubernetes 集群

• 为不同团队或项目提供隔离的入口流量控制
• 确保租户间资源和权限的安全隔离

3. API 生命周期管理

• 支持 API 版本平滑迁移（如蓝绿部署、金丝雀发布）
• 实现 API 弃用和新功能灰度发布

4. 安全策略实施

• 集中管理 API 访问认证和授权规则
• 强制实施 TLS 加密和数据传输安全标准

5. 混合云与多云环境

• 统一管理跨集群、跨云环境的流量入口
• 简化混合架构下的服务通信

使用方法与配置说明

部署步骤（Kubernetes 环境）

Emissary-ingress 主要在 Kubernetes 集群中部署，推荐使用 Helm 进行安装：

1. 添加 Helm 仓库

bash
helm repo add datawire https://www.getambassador.io
helm repo update

2. 安装 Emissary-ingress

bash
helm install emissary-ingress datawire/emissary-ingress \
  --namespace emissary-system \
  --create-namespace \
  --set service.type=LoadBalancer  # 或 NodePort/ClusterIP，根据环境选择

3. 验证部署

bash
kubectl get pods -n emissary-system

基本配置示例

1. 配置基础入口路由（Ingress 资源）

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: basic-ingress
  annotations:
    kubernetes.io/ingress.class: emissary  # 指定使用 Emissary 控制器
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /service1
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80

2. 高级路由配置（Mapping CRD）

使用 Mapping 自定义资源实现更复杂的路由规则：

yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: service2-mapping
spec:
  prefix: /v2/service2/
  service: service2:8080
  host: api.example.com
  headers:
    x-api-version: v2  # 仅匹配包含此请求头的流量
  rewrite: /  # 将前缀 /v2/service2/ 重写为 /
  timeout_ms: 5000  # 设置请求超时为 5 秒

环境变量与配置参数

Emissary-ingress 容器支持以下关键环境变量进行配置：

自定义 Envoy 配置

通过 EnvoyFilter 自定义资源可扩展 Envoy 配置（需熟悉 Envoy 配置结构）：

yaml
apiVersion: getambassador.io/v3alpha1
kind: EnvoyFilter
metadata:
  name: custom-envoy-config
spec:
  workloadSelector:
    labels:
      service: emissary-ingress
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
      listener:
        portNumber: 8080
        filterChain:
          filter:
            name: "envoy.filters.network.http_connection_manager"
            subFilter:
              name: "envoy.filters.http.router"
    patch:
      operation: INSERT_BEFORE
      value:
        name: "envoy.filters.http.lua"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua"
          inlineCode: |
            function envoy_on_request(request_handle)
              -- 自定义 Lua 脚本逻辑
            end

注意事项

• Emissary-ingress 需 Kubernetes 1.19+ 版本支持
• 生产环境建议配置资源限制（CPU/内存）和自动扩缩容
• 定期更新镜像版本以获取安全补丁和功能更新
• 复杂路由规则建议通过 Mapping CRD 而非标准 Ingress 资源配置，以利用高级特性

参考链接

• 官方文档
• https://github.com/emissary-ingress/emissary
• Helm Chart 文档