Barrie20/secure-eks-platform

# secure-eks-platform [](https://github.com/Barrie20/secure-eks-platform/actions/workflows/ci.yml) [](https://github.com/Barrie20/secure-eks-platform/actions/workflows/security.yml) [](https://www.terraform.io/) [](https://kubernetes.io/) [](LICENSE) ## 目录 - [项目初衷](#why-this-project-exists) - [架构](#architecture) - [安全模型](#security-model) - [项目内容](#whats-inside) - [本地零成本开始](#getting-started-locally-zero-cost) - [部署到 AWS](#deploying-to-aws-on-demand) - [CI/CD](#cicd) - [使用 Argo CD 实现 GitOps](#gitops-with-argo-cd) - [可观测性](#observability) - [成本模型](#cost-model) - [运行手册与运维](#runbooks-and-operations) - [完全拆除](#tearing-it-all-down) - [路线图](#roadmap) - [延伸阅读](#further-reading) ## 项目初衷 大多数 "DevOps 作品集" 项目不过是 `terraform apply` + `helm install nginx`，配上一个漂亮的 README。真正的平台工程是一个系统之系统：应用、流水线、基础设施、策略、可观测性、成本控制和运维手册，所有这些都通过 GitOps 进行版本管理和治理。 本仓库是第二类事物，处于最小可信规模： - 一个示例 Python (FastAPI) 工作负载，打包为加固的 OCI 镜像。 - 基础设施即代码 (Terraform)，用于配置最小权限的 AWS 账户资源：VPC、私有 EKS 集群、IAM Roles for Service Accounts (IRSA)、ECR、KMS、S3 状态后端。 - 用于工作负载的 Helm chart，通过 Argo CD 从此仓库部署。 - 分层安全流水线：秘密扫描、SAST、IaC 扫描、容器扫描、SBOM 生成、使用 cosign 的镜像签名，以及通过 Kyverno 实现的准入时策略执行。 - 通过 kube-prometheus-stack (Prometheus, Alertmanager, Grafana) 和 Loki 实现的可观测性。 - 使用 Falco 进行运行时威胁检测。 - 运行手册、ADR、事后复盘模板以及文档化的故障注入演练。 ## 架构 ### 高层次 ``` flowchart LR Dev[Developer] -->|git push| GH[GitHub] GH -->|PR checks| CI[GitHub Actions CI] CI -->|SAST, IaC scan, SBOM, Trivy, cosign sign| Reg[(Amazon ECR)] CI -->|bump image tag| GH ArgoCD((Argo CD)) -->|pull| GH ArgoCD -->|sync| EKS[(Amazon EKS)] EKS -->|metrics| Prom[Prometheus] EKS -->|logs| Loki[Loki] EKS -->|events| Falco[Falco] Prom --> Grafana Loki --> Grafana Falco --> Alertmanager Prom --> Alertmanager Alertmanager -->|notify| OnCall[On-call channel] ``` ### AWS 网络拓扑 ``` flowchart TB subgraph AWS["AWS Account (workloads)"] subgraph VPC["VPC 10.0.0.0/16"] subgraph AZA["AZ us-east-1a"] PubA[Public subnet] PrivA[Private subnet\nEKS nodes] end subgraph AZB["AZ us-east-1b"] PubB[Public subnet] PrivB[Private subnet\nEKS nodes] end IGW[Internet Gateway] NAT[NAT Gateway] EKSCP[EKS control plane\nprivate API endpoint] end ECR[(ECR)] S3[(S3 tfstate + logs)] KMS[(KMS CMKs)] CW[CloudWatch Logs] end Users((Users)) --> ALB[Ingress ALB] ALB --> PubA ALB --> PubB PubA --> NAT PubB --> NAT NAT --> IGW PrivA <--> EKSCP PrivB <--> EKSCP PrivA --> ECR PrivA --> S3 EKSCP --> CW ``` ### CI/CD 与 GitOps 流程 ``` sequenceDiagram participant Dev as Developer participant GH as GitHub participant CI as GitHub Actions participant ECR as Amazon ECR participant Argo as Argo CD participant EKS as EKS cluster Dev->>GH: Open pull request GH->>CI: Trigger ci.yml CI->>CI: Lint, unit tests, SAST (Bandit) CI->>CI: Terraform fmt, validate, tfsec, Checkov CI->>CI: Build image, Trivy FS + image scan CI->>CI: Generate SBOM (Syft), sign (cosign keyless OIDC) CI->>ECR: Push image + attestations CI->>GH: Open PR to bump image tag in gitops/ Dev->>GH: Merge PR Argo->>GH: Poll / webhook Argo->>EKS: Apply manifests via server-side apply EKS->>EKS: Kyverno admission checks EKS->>Argo: Health + sync status ``` ## 安全模型 安全是分层的。任何单一控制都可能失效；只有多项失效才会导致事件发生。 | 层级 | 控制 | 工具 | |---|---|---| | 源码 | 每次 PR 进行秘密扫描 | Gitleaks | | 源码 | 依赖项漏洞 | `pip-audit`, Dependabot | | 代码 | 静态分析 (SAST) | Bandit, Semgrep | | IaC | Terraform 策略扫描 | tfsec, Checkov | | 构建 | 基础镜像通过摘要固定、非 root 用户、无发行版运行时 | Dockerfile | | 构建 | 容器扫描 (操作系统 + 库) | Trivy | | 构建 | 软件物料清单 | Syft | | 构建 | 镜像签名 (无密钥，OIDC) | Cosign + Sigstore | | 注册表 | 私有注册表、推送时扫描、不可变标签 | ECR | | 集群认证 | IAM 联合至 Kubernetes RBAC，无静态 kubeconfig | EKS + `aws eks get-token` | | 集群身份 | Pod 通过 IRSA 获取 AWS 凭证，无节点级凭证 | IRSA + OIDC 提供商 | | 准入 | 阻止高风险清单 (特权、hostPath、latest 标签、未签名镜像) | Kyverno | | 网络 | 默认拒绝 NetworkPolicy，出口受控 | Cilium/Calico | | 运行时 | 系统调用级异常检测 | Falco | | 秘密 | 绝不存放在 Git 中。运行时从 Secrets Manager 拉取 | External Secrets Operator | | 数据 | S3 + EBS 使用客户管理的 KMS 密钥加密 | KMS | | 审计 | API 服务器、CloudTrail、VPC 流日志发送到中央账户 | CloudWatch + S3 | 详细的威胁模型请参见 [`docs/security/threat-model.md`](docs/security/threat-model.md)。 ## 项目内容 ``` secure-eks-platform/ ├── app/ # Sample FastAPI workload │ ├── src/ │ ├── tests/ │ ├── Dockerfile # Multi-stage, distroless, non-root, pinned by digest │ └── pyproject.toml ├── terraform/ │ ├── modules/ │ │ ├── network/ # VPC, subnets, NAT, flow logs │ │ ├── eks/ # Cluster, node groups, IRSA, addons │ │ ├── ecr/ # Private registry with scan-on-push │ │ └── observability/ # CloudWatch log groups, KMS keys │ └── environments/ │ ├── dev/ │ └── prod/ ├── helm/ │ └── sample-api/ # Workload Helm chart ├── gitops/ │ ├── bootstrap/ # Argo CD install + App-of-Apps root │ ├── platform/ # Cluster-level addons (Kyverno, ESO, kps, Loki, Falco) │ └── apps/ # Workload Applications per environment ├── policies/ │ └── kyverno/ # ClusterPolicy manifests ├── observability/ │ ├── alerts/ # PrometheusRule definitions + SLOs │ └── dashboards/ # Grafana JSON ├── .github/ │ ├── workflows/ │ │ ├── ci.yml # Lint, test, SAST, IaC scan, image scan, sign, push │ │ ├── cd.yml # Bump image tag in gitops/ via PR │ │ └── security.yml # Scheduled re-scans of main │ ├── ISSUE_TEMPLATE/ │ └── PULL_REQUEST_TEMPLATE.md ├── scripts/ # Bootstrap, teardown, chaos experiments ├── docs/ │ ├── adr/ # Architecture Decision Records │ ├── runbooks/ # On-call procedures │ ├── security/ # Threat model, SBOM notes │ └── postmortems/ # Real and simulated incident writeups ├── Makefile ├── .pre-commit-config.yaml └── README.md ``` ## 本地零成本开始 要求：Docker, `kind`, `kubectl`, `helm`, `terraform`, `python` 3.11+, `make`. ``` # 创建本地 3 节点 Kubernetes 集群 make local-up # 安装平台组件（Kyverno、kps、Loki、Falco、Argo CD） make platform-install # 构建示例应用镜像并加载至 kind make app-build app-load # 通过 Helm 部署工作负载 make app-deploy # 为 Grafana 和应用进行端口转发 make port-forward ``` 打开 http://localhost:3000 访问 Grafana (admin / admin) 以及 http://localhost:8080 访问 API。 ## 部署到 AWS (按需) ``` # 1. 一次性操作：引导状态后端（S3 + DynamoDB 锁表） make tf-bootstrap # 2. 启动开发环境 make aws-up ENV=dev # 3. 配置 kubectl make kubeconfig ENV=dev # 4. 应用 GitOps 引导（安装 Argo CD + App-of-Apps） make gitops-bootstrap # 5. 拆除所有环境 make aws-down ENV=dev ``` ## CI/CD 每个拉取请求都会并行运行以下检查。任何一项失败都会阻止合并。 1. `lint` - ruff, black --check, yamllint, hadolint, shellcheck 2. `test` - 带有 80% 覆盖率阈值的 pytest 3. `sast` - Bandit, Semgrep 4. `iac` - `terraform fmt`, `terraform validate`, tfsec, Checkov 5. `secrets` - Gitleaks 6. `container` - 构建镜像，Trivy 文件系统 + 镜像扫描 (高危/严重漏洞时失败)，使用 Syft 生成 SBOM，推送到 ECR，使用 cosign 无密钥签名 (GitHub OIDC) 7. `policy` - Kyverno CLI 对 chart 输出进行测试 当合并到 `main` 分支时，`cd.yml` 会自动向 `gitops/apps/dev/values.yaml` 创建一个 PR，更新镜像标签。Argo CD 会拾取这个变更并进行滚动发布。 GitHub 中不存在长期有效的 AWS 凭证。CI 通过 [GitHub OIDC 联合到 IAM 角色](docs/adr/0003-github-oidc-to-aws.md) 进行认证。 ## 使用 Argo CD 实现 GitOps Argo CD 运行 App-of-Apps 模式： - `gitops/bootstrap/root-app.yaml` 将 Argo CD 指向 `gitops/platform/` 和 `gitops/apps/`。 - `gitops/platform/` 安装集群插件：Kyverno, External Secrets Operator, kube-prometheus-stack, Loki, Falco。 - `gitops/apps//` 包含工作负载 Application，每个环境一个。 与 Git 的偏差会自动修复。手动 `kubectl edit` 是策略违规行为。 ## 可观测性 - **指标：** kube-prometheus-stack。应用以 Prometheus 格式暴露 `/metrics`。默认抓取节点、kubelet、cAdvisor、kube-state-metrics 和 API 服务器指标。 - **日志：** Loki，以 Grafana Agent 作为收集器。应用输出结构化 JSON 日志。 - **链路追踪：** OpenTelemetry SDK 集成到 FastAPI 应用中，导出器可配置。 - **SLO：** 定义在 `observability/alerts/slo.yaml` 中。根据 [Google SRE 多窗口方法](https://sre.google/workbook/alerting-on-slos/)，在错误预算消耗率达到 2% 和 5% 时触发告警。 启动时默认的 Grafana 仪表板： - 平台概览 - 工作负载 SLO + 延迟直方图 - 成本 (通过 kubecost exporter - 可选) ## 成本模型 | 项目 | 开发环境 (按需) | 持续运行月成本 | |---|---|---| | EKS 控制平面 | $0.10/小时 | $73 | | 2 个 t3.small 节点 | $0.042/小时 | $30 | | NAT 网关 (开发环境单可用区) | $0.045/小时 | $32 | | ECR 存储 | ~ | $1 | | CloudWatch 日志 | ~ | $2 | | **持续运行总成本** | | **~$138/月** | | **3 小时演示总成本** | **~$0.60** | | 内置的成本节约选择： - 开发环境使用单个 NAT 网关，生产环境才使用多可用区。 - 开发环境托管节点组使用 SPOT 容量。 - CloudWatch 日志保留期有上限 (开发环境 14 天 / 生产环境 90 天)。 - 状态后端 S3 生命周期规则。 - `make aws-down` 可移除所有计费资源。 参见 [`docs/adr/0005-cost-vs-availability-tradeoffs.md`](docs/adr/0005-cost-vs-availability-tradeoffs.md)。 ## 运行手册与运维 - [事件响应](docs/runbooks/incident-response.md) - [事后复盘模板](docs/postmortems/_template.md) - 事后复盘示例： - [2026-02 模拟 etcd 丢失](docs/postmortems/2026-02-etcd-loss.md) - [2026-03 模拟 IAM 配置错误](docs/postmortems/2026-03-irsa-misconfig.md) - [混沌实验](scripts/chaos/README.md) ## 完全拆除 ``` make aws-down ENV=dev make local-down ``` 所有资源都标记了 `project=secure-eks-platform`；可以使用以下命令审计遗留资源： `aws resourcegroupstaggingapi get-resources --tag-filters Key=project,Values=secure-eks-platform` ## 路线图 - [ ] 多账户 AWS Organizations 布局 (安全、日志、工作负载) - [ ] 使用 S3 Object Lock 的集中日志归档 - [ ] 工作负载跨区域灾备 - [ ] 服务网格 (Istio ambient) 和默认 mTLS - [ ] 使用 Argo Rollouts 进行渐进式发布 - [ ] FinOps：kubecost + 预算告警 ## 延伸阅读 - Google SRE 手册与工作手册 - 《设计数据密集型应用》，Martin Kleppmann - 《Kubernetes 模式》，Ibryam 和 Huß - AWS 良好架构：安全支柱 - Sigstore 和 SLSA 供应链框架 ## 许可证 Apache 2.0。参见 [LICENSE](LICENSE)。

标签：API集成, Argo CD, AV绕过, AWS, DPI, ECR, ECS, EKS, FastAPI, GitOps, Helm, IAM, KMS, Lerna, Python, S3, Terraform, 可观测性, 子域名突变, 安全, 安全扫描, 容器编排, 容器镜像, 平台工程, 成本控制, 无后门, 时序注入, 最少特权, 灾难恢复, 知识图谱, 策略执行, 自定义请求头, 资源管理, 超时处理, 运维手册, 逆向工具