cyscaledev/kubernetes-agent

Cyscale Kubernetes Agent 镜像文档

1. 镜像概述

Cyscale Kubernetes Agent 是一款与 Cyscale Platform 集成的 Kubernetes 代理组件，旨在通过收集 Kubernetes 集群的资源配置、运行时数据及安全相关信息，为 Cyscale Platform 提供数据输入，从而实现对集群安全状态的持续监控、风险识别与合规性评估。

2. 核心功能与特性

2.1 核心功能

• 集群资源全面扫描：自动发现并收集 Kubernetes 集群中的节点、Pod、Deployment、Service、ConfigMap、Secret 等核心资源的配置信息与运行状态。
• 安全配置基线检查：基于内置安全规则（如 CIS Benchmark for Kubernetes），检测集群资源配置中的安全隐患（如未授权访问、敏感信息暴露、权限过度分配等）。
• 合规性评估：支持主流合规标准（如 GDPR、HIPAA、PCI-DSS）的自动化合规检查，生成合规性报告与差距分析。
• 漏洞与风险检测：集成镜像扫描能力，识别容器镜像中的已知漏洞（CVE），并关联资源配置风险形成综合安全评估。
• 实时监控与告警：持续监控集群安全状态变化，通过 Cyscale Platform 触发实时告警（如新增高危漏洞、合规性违规等）。

2.2 特性

• 轻量化部署：容器化设计，资源占用低，支持在小型集群中高效运行。
• 配置灵活：支持通过环境变量、ConfigMap 等方式自定义扫描范围、规则策略与数据上报频率。
• 多集群支持：单个 Cyscale Platform 可管理多个 Kubernetes 集群的代理，实现统一安全管控。
• 加密传输：与 Cyscale Platform 之间的通信采用 TLS 加密，确保数据传输安全。

3. 使用场景与适用范围

3.1 使用场景

• Kubernetes 集群安全监控：实时跟踪集群资源配置变化，及时发现并修复安全漏洞。
• 合规性审计：满足行业合规要求（如***、***领域），定期生成合规性报告。
• 安全漏洞管理：集中管理容器镜像漏洞，优先处理高危风险，降低被***风险。
• 多集群统一安全管理：对企业内部多个 Kubernetes 集群（如开发、测试、生产环境）进行统一安全状态可视化与管控。

3.2 适用范围

• 集群类型：支持自托管 Kubernetes 集群（如 kubeadm 部署）及云托管集群（如 EKS、GKE、AKS、ACK 等）。
• 集群规模：适用于中小型（节点数 < 50）及大型（节点数 50+）Kubernetes 集群。
• Kubernetes 版本：兼容 Kubernetes v1.21 及以上版本。

4. 使用方法与配置说明

4.1 前置条件

• 已部署 Kubernetes 集群（v1.21+），且集群节点可访问公网（用于连接 Cyscale Platform）。
• 已注册 Cyscale Platform 账号，并获取 API 密钥（登录后在「Settings > API Keys」中创建）。
• 集群内已安装 kubectl 命令行工具，且具备集群管理员权限（用于部署代理）。

4.2 安装步骤

4.2.1 准备配置文件

创建代理配置文件（如 cyscale-agent-deployment.yaml），示例如下（根据实际环境调整参数）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cyscale-agent
  namespace: cyscale-agent
  labels:
    app: cyscale-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cyscale-agent
  template:
    metadata:
      labels:
        app: cyscale-agent
    spec:
      containers:
      - name: cyscale-agent
        image: cyscale/k8s-agent:latest  # 替换为实际镜像标签
        imagePullPolicy: Always
        env:
        - name: CYSCALE_API_KEY
          value: "your-cyscale-api-key"  # 替换为 Cyscale API 密钥
        - name: CLUSTER_NAME
          value: "your-cluster-name"     # 自定义集群名称（用于平台识别）
        - name: LOG_LEVEL
          value: "info"                  # 日志级别：debug/info/warn/error
        resources:
          limits:
            cpu: "500m"
            memory: "512Mi"
          requests:
            cpu: "200m"
            memory: "256Mi"

4.2.2 部署代理

1. 创建命名空间（如 cyscale-agent）：

   bash
   kubectl create namespace cyscale-agent
   

2. 应用部署配置：

   bash
   kubectl apply -f cyscale-agent-deployment.yaml -n cyscale-agent
   

4.2.3 验证部署

• 检查 Pod 运行状态：

  bash
  kubectl get pods -n cyscale-agent
  

  预期输出：cyscale-agent-xxxxxxxxx-xxxxx 状态为 Running。

• 查看代理日志（确认数据上报正常）：

  bash
  kubectl logs -f <pod-name> -n cyscale-agent
  

5. 部署示例

5.1 Kubernetes Deployment 完整配置

以下为生产环境推荐的 Deployment 配置（包含资源限制、健康检查及自动重启策略）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cyscale-agent
  namespace: cyscale-agent
  labels:
    app: cyscale-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cyscale-agent
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: cyscale-agent
    spec:
      containers:
      - name: cyscale-agent
        image: cyscale/k8s-agent:v1.2.0  # 指定具体版本，避免自动升级风险
        imagePullPolicy: IfNotPresent
        env:
        - name: CYSCALE_API_KEY
          valueFrom:
            secretKeyRef:
              name: cyscale-secrets
              key: api-key  # 推荐通过 Secret 管理敏感信息
        - name: CLUSTER_NAME
          value: "production-cluster-01"
        - name: LOG_LEVEL
          value: "info"
        - name: SCAN_INTERVAL
          value: "300"  # 扫描间隔（秒），默认 300
        resources:
          limits:
            cpu: "1000m"
            memory: "1Gi"
          requests:
            cpu: "500m"
            memory: "512Mi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        securityContext:
          readOnlyRootFilesystem: true  # 增强容器安全性
          runAsNonRoot: true
          runAsUser: 1000
      restartPolicy: Always

5.2 容器独立运行示例（非 Kubernetes 环境）

若需在非 K8s 环境中运行代理（仅用于测试），可通过 docker run 命令启动容器：

bash
docker run -d \
  --name cyscale-agent \
  -e CYSCALE_API_KEY="your-api-key" \
  -e CLUSTER_NAME="test-cluster" \
  -e KUBECONFIG=/kubeconfig \
  -v /path/to/local/kubeconfig:/kubeconfig \  # 挂载本地 kubeconfig 以访问集群
  cyscale/k8s-agent:latest

6. 配置参数说明

6.1 环境变量

6.2 资源配置建议

根据集群规模调整资源请求与限制：

• 小型集群（< 50 节点）：CPU 200m-500m，内存 256Mi-512Mi
• 中型集群（50-200 节点）：CPU 500m-1000m，内存 512Mi-1Gi
• 大型集群（> 200 节点）：CPU 1000m-2000m，内存 1Gi-2Gi

7. 升级与卸载

7.1 升级代理

1. 更新部署文件中的镜像标签（如 v1.2.0 升级至 v1.3.0）：

   yaml
   image: cyscale/k8s-agent:v1.3.0
   

2. 应用更新：

   bash
   kubectl apply -f cyscale-agent-deployment.yaml -n cyscale-agent
   

7.2 卸载代理

bash
kubectl delete deployment cyscale-agent -n cyscale-agent
kubectl delete namespace cyscale-agent