Twingate Kubernetes Controller 镜像文档

1. 镜像概述和主要用途

Twingate Kubernetes Controller 是一个自定义控制器，旨在 Kubernetes 环境中自动化管理 Twingate 资源。该控制器提供 Kubernetes 集群与 Twingate 零信任网络（Twingate Zero Trust Network）的无缝集成，实现对 Twingate 资源的自动化配置、部署与生命周期管理。

2. 核心功能和特性

• 自动化资源管理：自动处理 Twingate 资源（如连接器、访问规则等）的创建、更新和删除，减少手动操作成本。
• Kubernetes 原生集成：遵循 Kubernetes 控制器模式，通过自定义资源定义（CRD）或原生 Kubernetes 资源（如 ConfigMap、Secret）管理 Twingate 配置，确保与 Kubernetes 生态系统兼容。
• 零信任网络集成：深度整合 Twingate 零信任平台，确保 Kubernetes 集群内服务通过 Twingate 安全访问外部资源，或允许外部用户通过 Twingate 安全访问集群内服务。
• 生命周期自动化：支持基于 Kubernetes 集群状态动态调整 Twingate 资源配置，例如根据 Pod 或 Service 变化自动更新访问规则。

3. 使用场景和适用范围

适用场景

• 企业级 Kubernetes 环境：需要在规模化 Kubernetes 集群中统一管理 Twingate 零信任网络配置的场景。
• 零信任网络架构落地：采用 Twingate 零信任网络的组织，需将 Kubernetes 集群纳入零信任访问控制体系。
• 动态资源调整需求：Kubernetes 集群内服务频繁变更（如弹性伸缩、滚动更新），需自动同步 Twingate 访问策略的场景。

适用范围

• Kubernetes 版本：支持 Kubernetes v1.21+ 集群。
• Twingate 环境：需已部署 Twingate 零信任平台（包含 Twingate 管理员账户及 API 访问权限）。

4. 使用方法和配置说明

4.1 部署前提

• 已安装 Kubernetes 集群（v1.21+），并具备集群管理员权限。
• 已获取 Twingate 平台的 API 凭证（如 API 密钥、租户 ID 等）。
• 本地环境已安装 Docker 或 Kubernetes 命令行工具（如 kubectl）。

4.2 Docker 部署示例

4.2.1 直接使用 docker run 运行

（注：该控制器通常需在 Kubernetes 集群内运行，以下为简化示例，实际部署建议通过 Kubernetes 资源配置）

bash
docker run -d \
  --name twingate-k8s-controller \
  -e TWINGATE_API_KEY=<your-twingate-api-key> \
  -e TWINGATE_TENANT=<your-twingate-tenant> \
  -e KUBECONFIG=/kube/config \
  -v /path/to/kubeconfig:/kube/config \
  twingate/kubernetes-operator:latest

4.2.2 Docker Compose 配置示例

yaml
version: '3.8'
services:
  twingate-controller:
    image: twingate/kubernetes-operator:latest
    container_name: twingate-k8s-controller
    environment:
      - TWINGATE_API_KEY=<your-twingate-api-key>  # Twingate API 密钥（必填）
      - TWINGATE_TENANT=<your-twingate-tenant>    # Twingate 租户 ID（必填）
      - KUBECONFIG=/kube/config                   # Kubernetes 配置文件路径
      - LOG_LEVEL=info                            # 日志级别（可选，默认 info）
    volumes:
      - /path/to/local/kubeconfig:/kube/config    # 挂载本地 Kubernetes 配置文件
    restart: unless-stopped

4.3 Kubernetes 部署（推荐）

由于该控制器为 Kubernetes 原生组件，推荐通过 Kubernetes 资源清单部署（如 Deployment、ServiceAccount 等）。以下为核心配置示例：

4.3.1 ServiceAccount 与权限配置

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: twingate-controller
  namespace: twingate-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: twingate-controller-role
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list", "watch"]  # 按需调整权限范围
  # 其他必要权限（如管理 Twingate CRD 等）
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: twingate-controller-binding
subjects:
  - kind: ServiceAccount
    name: twingate-controller
    namespace: twingate-system
roleRef:
  kind: ClusterRole
  name: twingate-controller-role
  apiGroup: rbac.authorization.k8s.io

4.3.2 Deployment 配置

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: twingate-controller
  namespace: twingate-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: twingate-controller
  template:
    metadata:
      labels:
        app: twingate-controller
    spec:
      serviceAccountName: twingate-controller
      containers:
        - name: controller
          image: twingate/kubernetes-operator:latest
          env:
            - name: TWINGATE_API_KEY
              valueFrom:
                secretKeyRef:
                  name: twingate-secrets
                  key: api-key
            - name: TWINGATE_TENANT
              valueFrom:
                secretKeyRef:
                  name: twingate-secrets
                  key: tenant
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

4.4 配置参数说明

环境变量

5. 参考链接

• *** GitHub 仓库
• Twingate 零信任网络文档
• Kubernetes 控制器开发指南