nycdb-k8s-loader 镜像文档

镜像概述和主要用途

本镜像用于探索通过Kubernetes任务或Amazon Fargate填充NYC-DB实例的可能性。它提供了容器化的NYC-DB数据集加载方案，适用于需要部署和维护NYC-DB实例的场景。

核心功能和特性

• 容器化便利性：对熟悉容器化技术的开发者更友好，无需学***VPS或Ansible等部署工具
• 环境一致性：确保开发环境与生产环境一致
• 并行处理能力：可在多台机器上并行处理工作负载，提升数据库填充速度
• 定时更新支持：通过Kubernetes定时任务或Amazon Fargate计划任务实现NYC-DB实例持续更新
• 管理便捷性：Kubernetes仪表板提供直观UI，便于任务状态监控和管理

使用场景和适用范围

• 熟悉容器化技术的开发者部署NYC-DB实例
• 需要定时更新NYC-DB数据集的场景
• 追求开发/生产环境一致性的团队
• 需要通过并行处理提升数据集加载速度的场景
• 希望利用Kubernetes或AWS Fargate管理NYC-DB维护任务的用户

使用方法和配置说明

环境准备

需安装Docker。

首先，复制示例环境变量文件创建.env：

bash
cp .env.example .env     # Windows系统使用: copy .env.example .env

编辑.env文件，根据需求修改环境变量配置。

开发环境设置

通过Docker Compose可便捷搭建开发环境，自动配置Postgres服务器：

bash
docker-compose run app bash

进入容器后，可开发和运行load_dataset.py脚本。/app目录挂载本地仓库根目录，文件修改会实时同步到容器环境。

部署方式

Kubernetes部署

1. 准备Kubernetes集群
   本地可通过Docker Desktop启用Kubernetes，建议部署Kubernetes仪表板UI便于任务监控。

2. 构建容器镜像

   bash
   docker-compose build
   

3. 生成Kubernetes任务文件

   bash
   docker-compose run app python k8s_build_jobs.py
   

   生成的任务文件会使用.env中定义的环境变量。

4. 启动Kubernetes任务

   bash
   kubectl create -f ./k8s-jobs
   

   通过Kubernetes仪表板的"任务"部分查看任务状态。

5. 停止或清理任务

   bash
   kubectl delete -f ./k8s-jobs
   

Amazon Fargate部署

可将容器部署为Amazon Fargate任务，支持计划任务。部署指南：

• 任务定义：容器镜像使用justfixnyc/nycdb-k8s-loader:latest，按.env.example配置环境变量。

• 网络配置：运行任务时需将"Auto-assign public IP"设为ENABLED（容器需访问外部网络，详见aws/amazon-ecs-agent#1128）。

• VPC和安全组：确保数据库实例在VPC中可访问，RDS实例安全组入站规则需允许容器IP范围访问（默认安全组可能名为rds-launch-wizard）。

• 计划任务配置：使用aws_schedule_tasks.py脚本配置定期加载数据集的计划任务。

注意：目前Fargate不支持查看任务级CPU/内存使用率（aws/amazon-ecs-agent#565），且无法使用SSM参数存储作为密钥存储（aws/amazon-ecs-agent#1209），需明文指定数据库URL。

其他系统部署

容器通过环境变量配置，详细参数见.env.example。

工作原理

数据集URL通常包含ETag和Last-Modified元数据，加载器利用这些信息判断数据集是否更新：若未变更，则不重复下载和加载。可通过dbtool.py lastmod:reset命令重置数据集的最后修改元数据。

加载流程：下载更新的数据集→创建临时Postgres schema→加载数据到临时schema→删除公共schema中旧表→将临时schema表移至公共schema。临时schema确保加载过程不影响用户查询。

其他工具

dbtool.py工具提供数据库状态查询和修改功能。

测试

运行测试套件：

bash
docker-compose run app pytest

更新NYC-DB版本

Dockerfile中通过NYCDB_REV参数指定NYC-DB Python库的GitHub提交哈希。更新步骤：修改Dockerfile中NYCDB_REV默认值→提交PR→CI验证通过后合并至master分支→Docker Hub自动发布新镜像。

更新Who Owns What数据

镜像包含wowutil.py工具，用于创建和更新Who Owns What（WoW）所需的NYCDB派生表和函数：

• WoW表和函数创建在wow Postgres schema中，需将Postgres schema搜索路径设为wow, public以确保WoW函数正常工作。

• 需手动确保运行wowutil.py时，数据库中已存在WoW数据依赖的NYCDB数据集。

• Dockerfile中WOW_REV参数指定wowutil.py使用的WoW版本。

• 替代方式：通过load_dataset.py工具加载wow数据集（相当于wowutil.py build的快捷方式）。