Skip to content

update go sdk dir #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
furykerry merged 2 commits into from
Jun 4, 2026
Merged

update go sdk dir #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8b7f9f
update go sdk dir
ZhaoQing7892 Jun 3, 2026
4df9e57
update dir clients → k8s
ZhaoQing7892 Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
10 changes: 5 additions & 5 deletions .github/workflows/publish-maven-central.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,13 @@ jobs:

- name: Update version in pom.xml
run: |
cd clients/java
cd k8s/java
mvn versions:set -DnewVersion=${{ github.event.inputs.version }}
mvn versions:commit

- name: Build and publish to Maven Central
run: |
cd clients/java
cd k8s/java
mvn clean deploy -Psign-artifacts -Dgpg.passphrase="${{ secrets.GPG_PASSPHRASE }}" --batch-mode
env:
GPG_TTY: ''
Expand All @@ -83,7 +83,7 @@ jobs:
with:
name: maven-artifacts
path: |
clients/java/target/*.jar
clients/java/target/*.pom
clients/java/target/*.asc
k8s/java/target/*.jar
k8s/java/target/*.pom
k8s/java/target/*.asc
retention-days: 1
25 changes: 13 additions & 12 deletions docs/sdk-codegen-zh_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@

项目支持三种语言的 SDK 生成：

| 语言 | 生成工具 | 输出目录 |
|--------|-----------------------------------|-------------------|
| Go | k8s code-generator | `client/` |
| Java | Fabric8 java-generator-cli 6.14.0 | `clients/java/` |
| Python | datamodel-codegen（Pydantic v2） | `clients/python/` |
| 语言 | 生成工具 | 输出目录 |
|--------|-----------------------------------|---------------|
| Go | k8s code-generator | `client/` |
| Java | Fabric8 java-generator-cli 6.14.0 | `k8s/java/` |
| Python | datamodel-codegen（Pydantic v2） | `k8s/python/` |

## 前置依赖

Expand Down Expand Up @@ -45,7 +45,8 @@ make generate-all
make generate-all SKIP_UPDATE=true
```

> **⚠️ 注意：** 上游同步通过 GitHub API 下载 CRD 文件，未携带 Token 时可能触发限流（HTTP 403）。如果遇到限流，可以手动将最新的 CRD YAML 文件放到 `agents/crds/` 目录下，然后使用 `SKIP_UPDATE=true` 跳过自动同步。
> **⚠️ 注意：** 上游同步通过 GitHub API 下载 CRD 文件，未携带 Token 时可能触发限流（HTTP 403）。如果遇到限流，可以手动将最新的
> CRD YAML 文件放到 `agents/crds/` 目录下，然后使用 `SKIP_UPDATE=true` 跳过自动同步。

### 单独生成某个语言

Expand Down Expand Up @@ -92,14 +93,14 @@ hack/generate_client.sh
```
hack/generate_java_sdk.sh
→ Fabric8 java-generator-cli
→ 输出到 clients/java/.../models/
→ 输出到 k8s/java/.../models/
→ hack/patch_sdk_types.sh --java（类型修补）
```

**生成的 Java 模型**位于：

```
clients/java/src/main/java/io/openkruise/agents/client/v2/models/
k8s/java/src/main/java/io/openkruise/agents/client/v2/models/
```

包含 Sandbox、SandboxSet、SandboxTemplate、SandboxClaim、SandboxUpdateOps、Checkpoint 等所有 CRD 资源的 Java 类型定义。
Expand All @@ -112,14 +113,14 @@ clients/java/src/main/java/io/openkruise/agents/client/v2/models/
hack/generate_python_sdk.sh
→ datamodel-codegen（Pydantic v2）
→ ruff 格式化
→ 输出到 clients/python/.../models/
→ 输出到 k8s/python/.../models/
→ hack/patch_sdk_types.sh --python（类型修补 + ruff 格式化）
```

**生成的 Python 模型**位于：

```
clients/python/openkruise/agents/models/
k8s/python/openkruise/agents/models/
```

每个 CRD 对应一个 Python 文件（如 `sandbox.py`、`sandboxset.py`），包含 Pydantic BaseModel 类定义。
Expand All @@ -141,7 +142,7 @@ CRD 中标记了 `x-kubernetes-preserve-unknown-fields: true` 的字段，在代

### 修补规则配置

所有替换规则集中维护在 `clients/codegen/type_mapping.yaml`：
所有替换规则集中维护在 `k8s/codegen/type_mapping.yaml`：

```yaml
fields:
Expand Down Expand Up @@ -184,7 +185,7 @@ fields:
agents-api/
├── agents/crds/ # CRD YAML 定义（数据源）
├── client/ # Go clientset / lister / informer
├── clients/
├── k8s/
│ ├── codegen/ # 代码生成后处理工具
│ │ ├── type_mapping.yaml # 类型替换规则配置
│ │ ├── patch_java_types.py # Java 类型修补脚本
Expand Down
44 changes: 24 additions & 20 deletions docs/sdk-codegen.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ This document describes how to generate multi-language SDK client code for the K

The project supports SDK generation for three languages:

| Language | Generator | Output Directory |
| --- | --- | --- |
| Go | k8s code-generator | `client/` |
| Java | Fabric8 java-generator-cli 6.14.0 | `clients/java/` |
| Python | datamodel-codegen (Pydantic v2) | `clients/python/` |
| Language | Generator | Output Directory |
|----------|-----------------------------------|------------------|
| Go | k8s code-generator | `client/` |
| Java | Fabric8 java-generator-cli 6.14.0 | `k8s/java/` |
| Python | datamodel-codegen (Pydantic v2) | `k8s/python/` |

## Prerequisites

Expand Down Expand Up @@ -45,7 +45,9 @@ make generate-all
make generate-all SKIP_UPDATE=true
```

> **⚠️ Note:** Upstream sync downloads CRD files via the GitHub API. Without a token, you may hit rate limiting (HTTP 403). If this happens, manually place the latest CRD YAML files into the `agents/crds/` directory, then use `SKIP_UPDATE=true` to skip the automatic sync.
> **⚠️ Note:** Upstream sync downloads CRD files via the GitHub API. Without a token, you may hit rate limiting (HTTP
> 403). If this happens, manually place the latest CRD YAML files into the `agents/crds/` directory, then use
`SKIP_UPDATE=true` to skip the automatic sync.

### Generate a Single Language

Expand Down Expand Up @@ -92,17 +94,18 @@ Uses Fabric8 java-generator-cli to generate Java model classes from CRD YAML def
```
hack/generate_java_sdk.sh
→ Fabric8 java-generator-cli
→ Output: clients/java/.../models/
→ Output: k8s/java/.../models/
→ hack/patch_sdk_types.sh --java (type patching)
```

**Generated Java models** are located at:

```
clients/java/src/main/java/io/openkruise/agents/client/v2/models/
k8s/java/src/main/java/io/openkruise/agents/client/v2/models/
```

This includes Java type definitions for all CRD resources: Sandbox, SandboxSet, SandboxTemplate, SandboxClaim, SandboxUpdateOps, Checkpoint, etc.
This includes Java type definitions for all CRD resources: Sandbox, SandboxSet, SandboxTemplate, SandboxClaim,
SandboxUpdateOps, Checkpoint, etc.

### Python SDK

Expand All @@ -112,14 +115,14 @@ Uses datamodel-codegen to generate Pydantic v2 models from CRD JSON Schema.
hack/generate_python_sdk.sh
→ datamodel-codegen (Pydantic v2)
→ ruff formatting
→ Output: clients/python/.../models/
→ Output: k8s/python/.../models/
→ hack/patch_sdk_types.sh --python (type patching + ruff formatting)
```

**Generated Python models** are located at:

```
clients/python/openkruise/agents/models/
k8s/python/openkruise/agents/models/
```

Each CRD maps to a Python file (e.g. `sandbox.py`, `sandboxset.py`), containing Pydantic BaseModel class definitions.
Expand All @@ -128,20 +131,21 @@ Each CRD maps to a Python file (e.g. `sandbox.py`, `sandboxset.py`), containing

### Why Is Type Patching Needed?

CRD fields marked with `x-kubernetes-preserve-unknown-fields: true` lose concrete type information during code generation:
CRD fields marked with `x-kubernetes-preserve-unknown-fields: true` lose concrete type information during code
generation:

| Field | Go Type | Java Generated | Python Generated |
| --- | --- | --- | --- |
| `template` | `*corev1.PodTemplateSpec` | `AnyType` ❌ | `Any` ❌ |
| `volumeClaimTemplates` | `[]corev1.PersistentVolumeClaim` | `AnyType` ❌ | `Any` ❌ |
| `metadata` | `metav1.ObjectMeta` | ✅ Correct | `dict[str, Any]` ❌ |
| `patch` | `runtime.RawExtension` | `AnyType` ❌ | ✅ Kept as Any |
| Field | Go Type | Java Generated | Python Generated |
|------------------------|----------------------------------|----------------|--------------------|
| `template` | `*corev1.PodTemplateSpec` | `AnyType` ❌ | `Any` ❌ |
| `volumeClaimTemplates` | `[]corev1.PersistentVolumeClaim` | `AnyType` ❌ | `Any` ❌ |
| `metadata` | `metav1.ObjectMeta` | ✅ Correct | `dict[str, Any]` ❌ |
| `patch` | `runtime.RawExtension` | `AnyType` ❌ | ✅ Kept as Any |

The type patching scripts automatically replace these placeholder types with the correct Kubernetes types.

### Patching Rules Configuration

All replacement rules are centrally maintained in `clients/codegen/type_mapping.yaml`:
All replacement rules are centrally maintained in `k8s/codegen/type_mapping.yaml`:

```yaml
fields:
Expand Down Expand Up @@ -184,7 +188,7 @@ When patching runs, the script first prints all planned changes (file, line numb
agents-api/
├── agents/crds/ # CRD YAML definitions (data source)
├── client/ # Go clientset / lister / informer
├── clients/
├── k8s/
│ ├── codegen/ # Post-generation tooling
│ │ ├── type_mapping.yaml # Type replacement rules
│ │ ├── patch_java_types.py # Java type patching script
Expand Down
Loading
Loading