#S3 Storage Configuration

本文档介绍如何为 Tekton Results 配置兼容 S3 的存储（如 Ceph）以实现日志归档。

#Overview

Tekton Results 支持将归档日志存储在兼容 S3 的对象存储系统中，如 Ceph、AWS S3、MinIO 等。这为长期日志保留提供了可扩展且持久的解决方案，替代了效率较低的 PVC 存储等机制。

#Key Benefits

• Scalability：对象存储可横向扩展，不受块存储限制
• Durability：对象存储系统内置冗余和复制机制
• Cost-effectiveness：相比持久卷，存储成本更低
• Long-term retention：适合合规和历史故障排查需求

#Prerequisites

#Storage System Requirements

• 兼容 S3 的对象存储服务（Ceph、AWS S3、MinIO 等）
• 有权限创建桶并管理凭证
• Kubernetes 集群能访问 S3 端点的网络连通性

#Permissions

• 能够创建桶
• 对指定日志桶具有读/写/删除权限
• 配置了合适的 IAM 策略或访问控制

#Configuration Overview

Tekton Results 的 S3 存储配置包含两个主要部分：

1. S3 凭证和连接参数存储在 Kubernetes Secret 中
2. S3 配置在 TektonConfig 自定义资源的 spec.result 中启用

#Configuration Parameters Reference

#S3-Specific Parameters in Secret

#Parameter Details

• S3_BUCKET_NAME：Tekton 日志存储的 S3 桶名称，确保桶已存在且权限正确。
• S3_ENDPOINT：S3 服务端点 URL，AWS S3 可省略，Ceph、MinIO 等兼容服务必填。
• S3_REGION：S3 服务所在地域，AWS S3 使用对应区域标识，兼容服务使用配置的区域标识。
• S3_ACCESS_KEY_ID 和 S3_SECRET_ACCESS_KEY：用于 S3 服务认证的凭证。
• S3_HOSTNAME_IMMUTABLE：针对部分兼容服务需要主机名不可变时使用。
• S3_MULTI_PART_SIZE：定义分段上传的大小阈值，较大值有助于提升大文件上传性能。

#Basic Configuration

基础 S3 存储配置步骤如下：

#1. 准备 S3 存储

配置 Tekton Results 前，请确保：

• 已准备好兼容 S3 的存储系统（Ceph、AWS S3、MinIO 等）
• 有专用桶用于存储 Tekton 日志
• 拥有有效且权限合适的访问凭证（读、写、删）
• Kubernetes 集群能访问 S3 端点的网络连通性

#2. 创建 S3 凭证 Secret

创建包含 S3 凭证和配置的 Kubernetes Secret：

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: my-s3-secret
  namespace: tekton-pipelines
stringData:
  S3_BUCKET_NAME: tekton-logs
  S3_ENDPOINT: https://your-ceph-endpoint.example.com
  S3_HOSTNAME_IMMUTABLE: "false"
  S3_REGION: region-1
  S3_ACCESS_KEY_ID: your-access-key-id
  S3_SECRET_ACCESS_KEY: your-secret-access-key
  S3_MULTI_PART_SIZE: "5242880"

创建步骤说明：

1. 确认 S3 参数：

   • 日志存储桶名称
   • S3 端点 URL（如 Ceph 的 https://ceph.example.com）
   • 区域标识
   • 具备读写删权限的访问凭证

2. 使用 kubectl 创建 Secret：

   kubectl create secret generic my-s3-secret \
     --namespace="tekton-pipelines" \
     --from-literal=S3_BUCKET_NAME=tekton-logs \
     --from-literal=S3_ENDPOINT=https://your-ceph-endpoint.example.com \
     --from-literal=S3_HOSTNAME_IMMUTABLE=false \
     --from-literal=S3_REGION=region-1 \
     --from-literal=S3_ACCESS_KEY_ID=your-access-key-id \
     --from-literal=S3_SECRET_ACCESS_KEY=your-secret-access-key \
     --from-literal=S3_MULTI_PART_SIZE=5242880

   示例输出：

   secret/my-s3-secret created

3. 验证 Secret 创建成功：

   kubectl get secret my-s3-secret -n tekton-pipelines

   示例输出：

   NAME           TYPE     DATA   AGE
   my-s3-secret   Opaque   7      5m

#3. 配置 TektonConfig 资源

在 TektonConfig 中启用 S3 存储：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    # 启用日志 API 并指定 S3 作为存储类型
    logs_api: true
    logs_type: S3
    
    # 引用 S3 凭证 Secret
    secret_name: my-s3-secret
    
    # 使用外部数据库（生产环境推荐）
    is_external_db: true
    db_host: your-postgres-host.example.com
    db_port: 5432
    db_name: tekton_results
    db_sslmode: require
    db_secret_name: tekton-results-postgres

#4. 应用配置

1. 应用 TektonConfig 配置：

   kubectl apply -f tekton-config-s3-config.yaml

   示例输出：

   tektonconfig.operator.tekton.dev/config configured

2. 等待组件重启完成：

   kubectl rollout status -n tekton-pipelines deployment/tekton-results-api

   示例输出：

   deployment "tekton-results-api" successfully rolled out

   kubectl rollout status -n tekton-pipelines deployment/tekton-results-watcher

   示例输出：

   deployment "tekton-results-watcher" successfully rolled out

3. 验证配置生效：

   kubectl get pods -n tekton-pipelines

   示例输出：

   NAME                                          READY   STATUS    RESTARTS   AGE
   tekton-results-api-7d5b8c9c4-xl2v9            1/1     Running   0          10m
   tekton-results-watcher-6b4f7c8d5-z3n4p        1/1     Running   0          10m
   tekton-results-retention-policy-agent-5c9g2   1/1     Running   0          10m

#Advanced Configuration

#自定义分段大小

为优化上传性能，可调整分段大小：

# 在您的 S3 Secret 中
stringData:
  S3_MULTI_PART_SIZE: "10485760"  # 10MB 分段大小

#Ceph 特定配置

使用 Ceph 作为兼容 S3 存储时：

• 若 Ceph 配置要求，设置 S3_HOSTNAME_IMMUTABLE 为 "true"
• 使用 Ceph 集群提供的正确端点 URL
• 确保 Ceph RGW（RADOS Gateway）正确配置以支持 S3 兼容性

#完整生产环境配置示例

结合 S3 存储和外部数据库的完整配置示例：

---
# S3 凭证 Secret
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: tekton-results-s3-credentials
  namespace: tekton-pipelines
stringData:
  # S3 配置
  S3_BUCKET_NAME: tekton-logs-prod
  S3_ENDPOINT: https://ceph-storage.company.com
  S3_HOSTNAME_IMMUTABLE: "false"
  S3_REGION: ceph-region
  S3_ACCESS_KEY_ID: your-ceph-access-key
  S3_SECRET_ACCESS_KEY: your-ceph-secret-key
  S3_MULTI_PART_SIZE: "5242880"  # 5MB 分段阈值
---
# TektonConfig 配置
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    # 启用基于 S3 的日志存储
    logs_api: true
    logs_type: S3
    
    # 外部数据库配置
    is_external_db: true
    db_host: postgres.company.com
    db_port: 5432
    db_name: tekton_results
    db_sslmode: require
    db_secret_name: tekton-results-postgres  # 单独的数据库凭证
    secret_name: tekton-results-s3-credentials  # S3 凭证

#MinIO 特定配置示例

MinIO 对象存储配置示例：

---
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: minio-s3-credentials
  namespace: tekton-pipelines
stringData:
  S3_BUCKET_NAME: tekton-logs
  S3_ENDPOINT: https://minio.company.com
  S3_HOSTNAME_IMMUTABLE: "false"
  S3_REGION: us-east-1
  S3_ACCESS_KEY_ID: MINIO_ACCESS_KEY
  S3_SECRET_ACCESS_KEY: MINIO_SECRET_KEY
  S3_MULTI_PART_SIZE: "5242880"
---
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    logs_api: true
    logs_type: S3
    secret_name: minio-s3-credentials

#最大日志大小配置

您可以通过 TektonConfig 的 spec.result.options 字段配置 max-log-size 参数限制每个 TaskRun 存储的日志大小。重要：此功能需先启用 MaxLogSize 功能门控。该功能为增强特性（基于补丁），目前社区版 Tekton Results 尚未提供。

#功能门控配置

启用 max-log-size 前，需开启 MaxLogSize 功能门控，方法是设置 FEATURE_GATES 环境变量：

FEATURE_GATES='PartialResponse=true,MaxLogSize=true'

另一种方式是在 tekton-results-api 部署的环境变量中通过 TektonConfig options 配置：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    options:
      deployments:
        tekton-results-api:
          spec:
            template:
              spec:
                containers:
                - name: api  # 应与原部署容器名匹配
                  env:
                  - name: FEATURE_GATES
                    value: "PartialResponse=true,MaxLogSize=true"

注意：MaxLogSize 功能标志通常通过 Tekton 特性标志中的 MaxResultSize 配置实现，用于控制可存储结果的最大大小。

#最大日志大小配置示例

启用功能门控后，可配置 max-log-size 参数：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    logs_api: true
    logs_type: S3
    secret_name: my-s3-secret
    
    # 可选：通过 options 配置最大日志大小限制
    options:
      configMaps:
        tekton-results-api-config:  # 该 ConfigMap 必须存在
          data:
            max-log-size: "5242880"  # 字节数（5 MiB）

配置说明：

• 目的：限制每个 TaskRun 日志大小，防止存储无限增长，保障查询性能稳定
• 默认值：5 MiB（5242880 字节）
• 行为：当日志超出限制时，系统保留日志开头部分，丢弃尾部。设置 max-log-size 为 "0" 可禁用此限制，上传完整日志内容。
• 备注：此为增强功能（基于补丁），社区版 Tekton Results 尚未支持
• 前提：必须启用 MaxLogSize 功能门控

#Operations

#更新 S3 配置

修改 S3 配置后，需重启 Tekton Results 组件使配置生效。

重启 API 服务器：

kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

示例输出：

pod "tekton-results-api-7d5b8c9c4-xl2v9" deleted

重启 watcher：

kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-watcher

示例输出：

pod "tekton-results-watcher-6b4f7c8d5-z3n4p" deleted

#验证命令

# 查看 TektonConfig 状态
kubectl get tektonconfig config -o yaml

示例输出：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    logs_api: true
    logs_type: S3
    secret_name: my-s3-secret
    is_external_db: true
    db_host: postgres.company.com
status:
  conditions:
  - type: Ready
    status: "True"
    reason: InstallSucceeded
    message: "Install successful"

# 查看 S3 连接相关的 pod 日志
kubectl logs -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

示例输出：

{"level":"info","ts":"2023-05-15T10:30:45.123Z","caller":"api/main.go:89","msg":"Starting Tekton Results API server"}
{"level":"info","ts":"2023-05-15T10:30:45.124Z","caller":"s3/client.go:45","msg":"Successfully connected to S3 storage"}
{"level":"info","ts":"2023-05-15T10:30:45.125Z","caller":"api/server.go:123","msg":"API server listening on :8080"}

# 验证 Secret 是否存在
kubectl get secret my-s3-secret -n tekton-pipelines

# 验证带有 S3 配置的 pods 是否运行
kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

示例输出：

NAME                                    READY   STATUS    RESTARTS   AGE
tekton-results-api-7d5b8c9c4-xl2v9       1/1     Running   0          10m

kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-watcher

示例输出：

NAME                                    READY   STATUS    RESTARTS   AGE
tekton-results-watcher-6b4f7c8d5-z3n4p    1/1     Running   0          10m

#Best Practices

#安全注意事项

1. 使用专用凭证：为 Tekton Results 创建权限最小的专用 S3 凭证（仅对指定桶具备读写删权限）
2. 凭证安全存储：将凭证存储在 Kubernetes Secret 中，避免明文配置文件
3. 定期轮换凭证：建立定期（如季度）轮换 S3 访问密钥的流程
4. 网络安全：确保集群与 S3 端点之间的网络连接安全，优先使用私有网络或 VPN
5. 最小权限原则：仅授予 S3 凭证所需的最小权限
6. 加密：确保存储的日志支持服务器端加密

#性能优化

1. 合理分段大小：根据网络状况调整 S3_MULTI_PART_SIZE（默认 5MB，高延迟网络可考虑 10-15MB）
2. 桶位置：尽量将 S3 桶部署在与集群相同地域，减少延迟
3. 监控：监控 S3 存储使用量、上传/下载性能及错误率
4. 连接池管理：Tekton Results 自动管理与 S3 的连接池
5. 带宽保障：确保集群与 S3 存储间有足够带宽

#存储管理

1. 保留策略：为 S3 桶配置生命周期策略，自动清理旧日志
2. 存储类别：根据日志保留周期使用不同的 S3 存储类别
3. 压缩：若支持，启用兼容存储的压缩功能
4. 对象标签：使用 S3 对象标签按命名空间、流水线等维度组织日志

#命名规范

• 使用包含环境信息的描述性桶名（如 tekton-logs-prod、tekton-logs-staging）
• Secret 命名保持一致（如 tekton-results-s3-credentials）
• 多实例部署时加环境前缀
• 配置资源命名清晰规范

#运营建议

1. 健康监控：定期监控 Tekton Results 组件及 S3 连接健康状况
2. 备份策略：尽管 S3 具备持久性，仍需制定日志访问故障时的应急方案
3. 容量规划：根据 PipelineRun/TaskRun 量预估日志存储增长
4. 测试：定期测试日志检索功能，确保 S3 连接正常
5. 文档维护：保持 S3 端点及访问流程文档更新

#兼容存储特定建议

• Ceph：确保 Ceph RGW 配置正确并经过 S3 兼容性测试
• MinIO：验证 MinIO 服务器设置以优化与 Tekton Results 的性能
• AWS S3：检查 IAM 策略，确保跨账户访问权限（如适用）
• 性能调优：不同兼容存储可能需调整分段大小或连接参数

#Security Considerations

#Credential Management

1. 安全存储：将 S3 凭证存储在 Kubernetes Secret 中，避免明文配置文件
2. 访问控制：通过 RBAC 限制对包含 S3 凭证的 Secret 的访问
3. 轮换流程：定期轮换 S3 访问凭证
4. 最小权限原则：仅授予所需的最小权限（指定桶的读写删）

#Network Security

1. 加密连接：始终使用 HTTPS/SSL 连接 S3 兼容存储
2. 私有网络：尽可能使用私有网络或 VPN 连接 S3 端点
3. 防火墙规则：配置防火墙限制对 S3 端点的访问
4. 证书验证：确保 SSL 连接配置了正确的证书验证

#Monitoring and Auditing

1. 访问日志：启用 S3 兼容存储的访问日志，跟踪操作记录
2. 异常检测：监控异常访问模式或认证失败
3. 审计轨迹：维护凭证访问和配置变更的审计日志
4. 安全告警：设置安全事件告警

#Troubleshooting

#常见问题

1. S3 连接错误：

   • 确认 S3 端点 URL 正确且可访问
   • 检查集群到 S3 端点的网络连通性
   • 使用 HTTPS 时验证 SSL 证书
   • 确认端点从集群内部可达

2. 认证失败：

   • 确认访问密钥和密钥对正确
   • 检查 IAM 策略是否授予所需权限
   • 区域配置是否匹配 S3 服务区域
   • 确保凭证未过期或未被轮换

3. 权限拒绝：

   • 确保凭证对桶有读写删权限
   • 验证桶策略允许集群访问
   • 确认桶存在且凭证可访问

4. 日志上传缓慢：

   • 调整分段大小以优化性能
   • 检查集群与 S3 端点间带宽
   • 验证 S3 服务性能
   • 监控网络拥塞或限流情况

5. 日志缺失：

   • 确认 watcher 组件正常捕获日志
   • 检查日志是否已存储在 S3 但 API 无法访问
   • 确认保留策略未过早清理日志

6. 配置问题：

   • 确认所有必填 S3 参数正确配置
   • 检查 TektonConfig 资源配置是否正确
   • 确认 Secret 格式正确且可访问

#安全相关问题

1. 凭证泄露：

   • 检查日志或错误信息中是否暴露凭证
   • 确认凭证未存储在配置文件中
   • 确保 RBAC 策略限制敏感资源访问

2. 未授权访问：

   • 监控异常访问模式
   • 确认仅授权服务可访问 S3 存储
   • 检查认证机制是否生效

#诊断命令

# 查看 TektonConfig 资源状态
kubectl get tektonconfig config -o yaml

示例输出：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    logs_api: true
    logs_type: S3
    secret_name: my-s3-secret
status:
  conditions:
  - type: Ready
    status: "True"
    reason: ReconcileSuccess
    message: "All components are reconciled successfully"

# 查看详细状态
kubectl describe tektonconfig config

示例输出：

Name:         config
Namespace:    
Labels:       operator.tekton.dev/release-version=v0.76.0-1070dfb
Annotations:  <none>
API Version:  operator.tekton.dev/v1alpha1
Kind:         TektonConfig
Metadata:
  Creation Timestamp:  2026-01-26T04:40:31Z
  Finalizers:
    tektonconfigs.operator.tekton.dev
  Generation:        16
  Resource Version:  2363257
  UID:               4ae317c9-7bb9-40b5-94fe-2c3cf708a21d
Spec:
    Result:
    auth_disable:              false
    db_enable_auto_migration:  true
    db_host:                   postgresql.example.svc.cluster.local
    db_name:                   tekton_results
    db_port:                   5432
    db_secret_name:            tekton-results-postgres
    db_sslmode:                verify-full
    db_sslrootcert:            /etc/tls/db/ca.crt
    Disabled:                  false
# .....

# 查看所有相关 pods
kubectl get pods -n tekton-pipelines | grep tekton-results

示例输出：

NAME                                          READY   STATUS    RESTARTS   AGE
tekton-results-api-7d5b8c9c4-xl2v9            1/1     Running   0          10m
tekton-results-watcher-6b4f7c8d5-z3n4p        1/1     Running   0          10m
tekton-results-retention-policy-agent-5c9g2   1/1     Running   0          10m

# 查看 API 服务器日志中与 S3 相关的信息
kubectl logs -n tekton-pipelines deployment/tekton-results-api | grep -i s3

示例输出：

{"level":"info","ts":"2023-05-15T10:30:45.123Z","caller":"s3/client.go:45","msg":"Successfully connected to S3 storage"}
{"level":"info","ts":"2023-05-15T10:30:45.124Z","caller":"api/server.go:123","msg":"S3 storage configured with bucket: tekton-logs"}

# 查看 watcher 日志中上传操作相关信息
kubectl logs -n tekton-pipelines deployment/tekton-results-watcher | grep -i upload

示例输出：

{"level":"info","ts":"2023-05-15T10:30:46.234Z","caller":"watcher/upload.go:67","msg":"Successfully uploaded log to S3: namespace/pipeline-run-name"}
{"level":"info","ts":"2023-05-15T10:30:47.345Z","caller":"watcher/upload.go:67","msg":"Log upload completed for task-run: namespace/task-run-name"}

# 小心查看 Secret 内容
kubectl get secret my-s3-secret -n tekton-pipelines -o yaml

示例输出：

apiVersion: v1
kind: Secret
metadata:
  name: my-s3-secret
  namespace: tekton-pipelines
data:
  s3-secret-key: <s3 secret data>
  ......
type: Opaque

# 在集群内测试 S3 连接
kubectl run s3-test --image=minio/mc --restart=Never -n tekton-pipelines --rm -it -- \
  mc alias set my-s3 https://your-endpoint your-access-key your-secret-key || echo "Connection failed"

示例输出：

s3-test
If you don't see a command prompt, try pressing enter.
Connection established. Waiting for command completion.
Pod s3-test terminated

#验证步骤

1. 确认组件运行正常：

   kubectl get pods -n tekton-pipelines
   # 查看 tekton-results-api、tekton-results-watcher 及可选的 retention-policy-agent

   示例输出：

   NAME                                          READY   STATUS    RESTARTS   AGE
   tekton-results-api-7d5b8c9c4-xl2v9            1/1     Running   0          10m
   tekton-results-watcher-6b4f7c8d5-z3n4p        1/1     Running   0          10m
   tekton-results-retention-policy-agent-5c9g2   1/1     Running   0          10m

2. 创建 PipelineRun 以触发日志上传：

   # 创建一个简单测试的 pipelinerun
   kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-watcher

   示例输出：

   NAME                                     READY   STATUS    RESTARTS   AGE
   tekton-results-watcher-6b4f7c8d5-z3n4p   1/1     Running   0          10m

3. 验证 S3 连接：

   • 检查日志是否出现在 S3 桶中
   • 验证日志结构是否符合预期
   • 确认保留策略正常工作

#Log Analysis

排查 S3 配置问题时，关注以下关键日志：

• Tekton Results API 日志中的 S3 上传/下载操作
• Tekton Results Watcher 日志中的日志捕获和转发
• S3 服务日志（如可用）确认对象创建/删除
• Kubernetes 事件日志中与资源相关的问题

重点关注错误模式：

• 认证失败
• 连接超时
• 权限错误
• 网络连通性问题
• SSL/TLS 握手失败

#Performance Issues

遇到性能问题时：

1. 检查资源使用情况：

   # kubectl top 命令需集群安装 metrics-server
   kubectl top pods -n tekton-pipelines

   示例输出：

   NAME                                          CPU(cores)   MEMORY(bytes)
   tekton-results-api-7d5b8c9c4-xl2v9            15m          55Mi
   tekton-results-watcher-6b4f7c8d5-z3n4p        8m           32Mi
   tekton-results-retention-policy-agent-5c9g2   5m           28Mi

2. 监控网络性能：

   • 检查集群与 S3 端点间带宽
   • 监控丢包率和高延迟

3. 调整分段上传设置：

   • 对高延迟网络增加 S3_MULTI_PART_SIZE
   • 根据日志量调整工作池大小