Metadata-Version: 2.4
Name: alikafka-management-tool
Version: 0.1.1
Summary: Aliyun Kafka Management Tool - Manage Kafka resources using YAML
Author-email: Trask Li <trask.li@decathlon.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/alikafka-cli
Project-URL: Documentation, https://github.com/your-org/alikafka-cli#readme
Project-URL: Repository, https://github.com/your-org/alikafka-cli.git
Project-URL: Issues, https://github.com/your-org/alikafka-cli/issues
Keywords: aliyun,kafka,management,yaml,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alibabacloud-alikafka20190916>=1.0.0
Requires-Dist: alibabacloud-tea-openapi>=0.3.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: GitPython>=3.1.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# AliKafka CLI Tool

基于 [alibabacloud-alikafka20190916](https://api.aliyun.com/api/alikafka/2019-09-16/) API 版本构建的阿里云 Kafka 管理工具，通过 YAML 配置文件管理 Kafka 资源。

## 功能特性

- ✅ **Topic 管理**：创建、更新、删除 Topic
- ✅ **Consumer Group 管理**：管理消费者组
- ✅ **SASL 用户管理**：管理 SASL 用户及 ACL 权限
- ✅ **白名单管理**：管理实例 IP 白名单
- ✅ **配置即代码**：所有配置存储在 YAML 文件中，支持 Git 版本控制
- ✅ **Dry-run 模式**：预览变更而不实际执行
- ✅ **Git 集成**：自动生成 commit 建议

## 安装

### 从 PyPI 安装（推荐）

```bash
pip install alikafka-management-tool
```

### 从源码安装（开发模式）

```bash
git clone https://github.com/your-org/alikafka-cli.git
cd alikafka-cli
pip install -e .
```

## 快速开始

### 1. 设置配置目录

默认情况下，工具会在当前目录的 `config/` 子目录中查找配置文件。您也可以通过环境变量指定自定义配置路径：

```bash
# 使用默认配置路径（当前目录/config）
cd /path/to/your/config/repo

# 或使用自定义配置路径
export ALIKAFKA_CONFIG_DIR=/path/to/config
```

### 2. 配置访问凭证

创建 `.env` 文件：

```bash
# Aliyun 访问密钥
ALIKAFKA_ACCESS_KEY_ID=your_access_key_id
ALIKAFKA_ACCESS_KEY_SECRET=your_access_key_secret
ALIKAFKA_REGION_ID=cn-shanghai

# 可选：指定配置目录（默认为 ./config）
# ALIKAFKA_CONFIG_DIR=./config
```

### 3. 基本使用

```bash
# 列出所有实例
alikafka list-instances

# 初始化配置（从现有实例导出）
alikafka init --instance alikafka_xxx --region cn-shanghai

# 应用配置（dry-run）
alikafka apply --instance-name xxx --dry-run

# 应用配置
alikafka apply --instance-name xxx

# 导出配置
alikafka export --instance-name xxx

# 查看差异
alikafka diff --instance-name xxx
```

## 命令参考

### init

从现有 Kafka 实例初始化配置文件：

```bash
alikafka init --instance INSTANCE_ID --region REGION_ID
```

### apply

应用 YAML 配置到 Kafka：

```bash
# 应用所有配置
alikafka apply --instance INSTANCE_ID

# 使用实例名称
alikafka apply --instance-name INSTANCE_NAME

# 只应用特定类型
alikafka apply --instance-name xxx --topics-only
alikafka apply --instance-name xxx --groups-only
alikafka apply --instance-name xxx --users-only

# Dry-run 模式
alikafka apply --instance-name xxx --dry-run
```

### export

导出 Kafka 当前状态到 YAML：

```bash
alikafka export --instance INSTANCE_ID
alikafka export --instance-name INSTANCE_NAME
```

### diff

显示 YAML 配置与 Kafka 实际状态的差异：

```bash
alikafka diff --instance INSTANCE_ID
alikafka diff --instance-name INSTANCE_NAME
```

### list-instances

列出账户中的所有 Kafka 实例：

```bash
alikafka list-instances
```

## 配置仓库

本工具需要配合配置仓库使用。配置仓库包含 Kafka 资源的 YAML 配置文件：

- [alikafka-configs-preprod](https://github.com/your-org/alikafka-configs-preprod) - 预生产环境配置
- [alikafka-configs-prod](https://github.com/your-org/alikafka-configs-prod) - 生产环境配置

### 配置仓库结构

```
alikafka-configs-xxx/
├── config/
│   ├── global.yaml.template
│   ├── index.yaml
│   └── instances/
│       └── INSTANCE_NAME/
│           ├── metadata.yaml
│           ├── topics.yaml
│           ├── consumer_groups.yaml
│           ├── sasl_users.yaml
│           └── allowlist.yaml
└── .env
```

## 开发

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/your-org/alikafka-cli.git
cd alikafka-cli

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 以开发模式安装
pip install -e .

# 运行命令
alikafka --help
```

### 代码格式化

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 格式化代码
black src/

# 检查代码风格
flake8 src/
```

## 路线图

- [ ] 支持更多资源类型
- [ ] 配置验证模式
- [ ] 配置文件加密
- [ ] Web UI（可选）

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 相关链接

- [阿里云 Kafka 文档](https://www.alibabacloud.com/help/product/29536)
- [配置仓库示例](https://github.com/your-org/alikafka-configs-preprod)
