cyberark/sidecar-injector

Kubernetes自动边车注入Webhook镜像文档

镜像概述和主要用途

该镜像是一个基于Kubernetes准入控制机制的变异Webhook控制器，核心功能是在Pod创建过程中自动注入边车（Sidecar）容器。通过与Kubernetes API服务器集成，实现无需手动修改Pod定义即可为应用添加辅助功能容器，广泛应用于服务网格、可观测性采集、安全代理等场景。

核心功能和特性

• 自动边车注入：在Pod创建生命周期中自动执行边车容器注入，减少手动配置工作量
• Kubernetes原生集成：遵循Kubernetes Admission Webhook规范，与集群控制平面无缝协作
• 灵活的注入规则：支持通过命名空间标签、Pod标签、注解等多维度选择注入目标
• 可定制注入内容：支持自定义边车容器镜像、资源限制、环境变量、挂载卷等配置
• 安全通信：基于TLS加密与Kubernetes API服务器通信，确保配置传输安全性

使用场景和适用范围

典型应用场景

• 服务网格部署：自动注入服务代理容器（如Istio Proxy），实现流量管理、服务发现和监控
• 可观测性采集：统一注入日志（Fluent Bit）、指标（Prometheus Agent）采集代理
• 安全增强：注入网络策略执行、身份验证或加密代理，强化Pod安全边界
• 应用无侵入扩展：在不修改业务镜像的前提下，为Pod添加网络、存储或配置管理功能

适用范围

• Kubernetes集群版本1.16+（支持AdmissionRegistration v1 API）
• 需要标准化Pod辅助功能配置的企业级集群
• 服务网格、微服务架构或DevOps实践的技术栈环境

使用方法和配置说明

前置条件

• 具备集群管理员权限（需创建MutatingWebhookConfiguration等集群级资源）
• 已部署TLS证书管理（推荐使用cert-manager自动管理Webhook证书）
• 集群已启用准入控制器（默认启用）

部署步骤

1. 部署Webhook服务

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sidecar-injector
  namespace: kube-system
spec:
  replicas: 2  # 建议多副本确保高可用
  selector:
    matchLabels:
      app: sidecar-injector
  template:
    metadata:
      labels:
        app: sidecar-injector
    spec:
      containers:
      - name: injector
        image: [镜像名称]:[版本标签]  # 替换为实际镜像地址
        ports:
        - containerPort: 443
        volumeMounts:
        - name: tls-cert
          mountPath: /etc/webhook/tls
          readOnly: true
        - name: injector-config
          mountPath: /etc/webhook/config
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi
      volumes:
      - name: tls-cert
        secret:
          secretName: sidecar-injector-tls  # 包含Webhook服务TLS证书
      - name: injector-config
        configMap:
          name: sidecar-injector-config  # 注入规则配置

2. 创建服务暴露

yaml
apiVersion: v1
kind: Service
metadata:
  name: sidecar-injector
  namespace: kube-system
spec:
  selector:
    app: sidecar-injector
  ports:
  - port: 443
    targetPort: 443

3. 配置MutatingWebhookConfiguration

yaml
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: sidecar-injector-webhook
webhooks:
- name: sidecar-injector.example.com
  clientConfig:
    service:
      name: sidecar-injector
      namespace: kube-system
      path: /mutate-v1-pod
    caBundle: [CA证书Base64编码]  # API服务器验证Webhook的CA证书
  rules:
  - operations: ["CREATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
  admissionReviewVersions: ["v1"]
  sideEffects: None
  timeoutSeconds: 10
  namespaceSelector:  # 仅匹配带特定标签的命名空间
    matchLabels:
      sidecar-injection: enabled
  objectSelector:  # 仅匹配带特定标签的Pod
    matchLabels:
      sidecar: required

4. 配置注入模板

通过ConfigMap定义边车容器具体配置：

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-injector-config
  namespace: kube-system
data:
  config.yaml: |
    sidecarContainers:
    - name: sidecar-proxy
      image: proxy-image:latest
      ports:
      - containerPort: 8080
      resources:
        limits:
          cpu: 200m
          memory: 256Mi
        requests:
          cpu: 100m
          memory: 128Mi
      env:
      - name: PROXY_MODE
        value: "transparent"
      volumeMounts:
      - name: proxy-config
        mountPath: /etc/proxy
    volumes:
    - name: proxy-config
      configMap:
        name: proxy-default-config

验证部署

创建测试Pod并验证边车注入：

bash
# 创建带注入标签的测试Pod
kubectl run test-pod --image=nginx --labels=sidecar=required -n [启用注入的命名空间]

# 检查Pod容器列表（应包含业务容器和sidecar容器）
kubectl describe pod test-pod | grep "Container ID"

配置参数说明

注意事项

• 生产环境建议部署2+副本确保Webhook服务高可用
• 合理配置超时时间避免影响Pod创建效率
• 通过命名空间和Pod标签精确控制注入范围，避免过度注入
• 定期更新TLS证书防止过期导致注入失败
• 首次部署建议先在测试命名空间验证注入效果