From 2e775e73a413f8ee3f618d6f11ee69eb381a6f4e Mon Sep 17 00:00:00 2001 From: Naeel Date: Tue, 14 Apr 2026 21:53:34 +0300 Subject: [PATCH] doc: switch provider MVP plan from REST v2 to Kubernetes CRD API --- doc/CODEX_PLAN.md | 111 ++++++++++++++++++++++++++-------------------- 1 file changed, 64 insertions(+), 47 deletions(-) diff --git a/doc/CODEX_PLAN.md b/doc/CODEX_PLAN.md index 00687a9..d8c45b6 100644 --- a/doc/CODEX_PLAN.md +++ b/doc/CODEX_PLAN.md @@ -3,6 +3,20 @@ # Агент: GPT 5.3 Codex # Домен: fission.kube5s.ru +## ОБНОВЛЕНИЕ ПО ФАКТУ ПРОВЕРКИ В КЛАСТЕРЕ (2026-04-14) + +Проверено на кластере `iot-naeel`: +- Fission `v1.22.1` поднят и работает (env/function/route через `fission` CLI успешны) +- путь `GET /v2/environments` через ingress (`185.247.187.151`) возвращает `404 page not found` +- отдельного `controller` service/deployment в текущем `fission-all` релизе нет + +**Критичное решение:** +MVP провайдера делать через Kubernetes API (CRD Fission) с использованием `client-go`/dynamic client, +а не через REST `/v2/*`. + +Provider продолжает управлять теми же сущностями (`Environment`, `Package`, `Function`, `HTTPTrigger`), +но операции Create/Read/Update/Delete выполняются через Kubernetes CRD ресурсы. + --- ## КОНТЕКСТ ПРОЕКТА @@ -17,20 +31,20 @@ Fission используется как managed FaaS-сервис в нашем ### Архитектура ``` -Terraform Provider (Go) → HTTP → Fission Controller API (порт 443 через Ingress) - ↓ - Fission делает всё сам: - - StorageSvc (PV, позже S3) - - Builder Manager → Builder Pods - - Executor → Function Pods - - Router → HTTP routing +Terraform Provider (Go) → Kubernetes API (client-go/dynamic) → Fission CRD + ↓ + Fission делает всё сам: + - StorageSvc (PV, позже S3) + - Builder Manager → Builder Pods + - Executor → Function Pods + - Router → HTTP routing ``` -**Provider НЕ управляет S3, PV, Kubernetes напрямую.** Только HTTP-вызовы к Fission Controller REST API. +**Provider НЕ управляет S3/PV напрямую.** Он управляет только Fission CRD через Kubernetes API. Fission сам хранит код (StorageSvc), собирает (Builder), запускает (Executor), маршрутизирует (Router). ### Ключевые решения -- Без proxy/operator — provider напрямую к Fission Controller API +- Без proxy/operator — provider напрямую к Kubernetes API (Fission CRD) - StorageSvc на PV (local storage) — позже мигрируем на S3 - terraform-plugin-framework (НЕ старый SDKv2) - Паттерны из существующего sless-провайдера (структура, client, build script) @@ -75,6 +89,9 @@ Fission сам хранит код (StorageSvc), собирает (Builder), з ## FISSION API REFERENCE +> ⚠️ Для текущей установки Fission v1.22.1 в этом кластере REST `/v2/*` недоступен (`404`). +> Раздел ниже оставлен как историческая справка; для реализации MVP использовать Kubernetes CRD API. + ### Fission Controller REST API Fission Controller слушает на порте 8888 (внутри кластера) или через Ingress. @@ -323,7 +340,7 @@ helm install fission fission-charts/fission-all \ --set authentication.enabled=true ``` -**0.2** Настроить Ingress на fission.kube5s.ru → Fission Router + Controller +**0.2** Настроить Ingress на fission.kube5s.ru → Fission Router **0.3** Установить fission CLI и проверить: ```bash @@ -332,9 +349,10 @@ fission fn create --name hello --env python --code hello.py fission fn test --name hello ``` -**0.4** Проверить REST API: +**0.4** Проверить CRD API через Kubernetes: ```bash -curl -H "Authorization: Bearer $TOKEN" https://fission.kube5s.ru/v2/environments +kubectl get crd environments.fission.io functions.fission.io packages.fission.io httptriggers.fission.io +kubectl get environments -n default ``` --- @@ -350,20 +368,19 @@ curl -H "Authorization: Bearer $TOKEN" https://fission.kube5s.ru/v2/environments - `.gitignore` — бинарники, .terraform, *.tfstate #### 1.2 Client (internal/client/client.go) -HTTP-клиент к Fission Controller API. +Клиент к Kubernetes API для работы с Fission CRD. **Структура:** ```go package client type Client struct { - httpClient *http.Client - endpoint string // https://fission.kube5s.ru - token string // Bearer JWT - namespace string // namespace для функций (дефолт "fission-function") + dynClient dynamic.Interface + k8sClient kubernetes.Interface + namespace string // namespace для функций (дефолт "default") } -func New(endpoint, token, namespace string) *Client +func New(kubeconfigPath, kubeContext, namespace string) (*Client, error) // Environments func (c *Client) CreateEnvironment(ctx, env) error @@ -390,30 +407,30 @@ func (c *Client) UpdateHTTPTrigger(ctx, trigger) error func (c *Client) DeleteHTTPTrigger(ctx, name) error ``` -**Формат запросов:** -- Content-Type: application/json (для CRUD) -- Content-Type: multipart/form-data (для upload в Package) -- Authorization: Bearer -- Namespace в metadata объекта +**Формат работы:** +- dynamic client для CRD `*.fission.io` +- операции CRUD через Kubernetes API +- Namespace через metadata и provider config +- код package загружается в `spec.source.literal` (base64 zip) для MVP -**ВАЖНО:** Размер client.go — целевой ~500-800 строк. Никакого S3, kaniko, polling. +**ВАЖНО:** Размер client.go — целевой ~500-900 строк. Никакого S3, kaniko, polling. #### 1.3 Provider (internal/provider/provider.go) **Атрибуты провайдера:** ```hcl provider "fission" { - endpoint = "https://fission.kube5s.ru" # URL Fission Controller (env: FISSION_ENDPOINT) - token = "xxx" # Bearer JWT (env: FISSION_TOKEN) - namespace = "fission-function" # Namespace (env: FISSION_NAMESPACE, default: "fission-function") + kubeconfig_path = "~/.kube/config" # env: KUBECONFIG + kube_context = "" # env: KUBE_CONTEXT (optional) + namespace = "default" # env: FISSION_NAMESPACE } ``` **Configure():** -1. Прочитать endpoint (config → env FISSION_ENDPOINT → default "http://localhost:8888") -2. Прочитать token (config → env FISSION_TOKEN → пусто = без auth) -3. Прочитать namespace (config → env FISSION_NAMESPACE → default "fission-function") -4. Создать Client +1. Прочитать kubeconfig_path (config → env KUBECONFIG) +2. Прочитать kube_context (config → env KUBE_CONTEXT) +3. Прочитать namespace (config → env FISSION_NAMESPACE → default "default") +4. Создать Kubernetes dynamic client 5. Положить в resp.ResourceData и resp.DataSourceData **Resources():** @@ -450,10 +467,10 @@ resource "fission_environment" "python" { ``` **CRUD:** -- Create: POST /v2/environments → JSON body -- Read: GET /v2/environments/{name}?namespace={ns} -- Update: PUT /v2/environments/{name} → JSON body -- Delete: DELETE /v2/environments/{name}?namespace={ns} +- Create: Kubernetes `create` CRD `environments.fission.io` +- Read: Kubernetes `get` CRD `environments.fission.io` +- Update: Kubernetes `update` CRD `environments.fission.io` +- Delete: Kubernetes `delete` CRD `environments.fission.io` #### 1.5 Resource: fission_package @@ -477,10 +494,10 @@ resource "fission_package" "hello_pkg" { source_dir и code_path — взаимоисключающие. **CRUD:** -- Create: zip source_dir или читаем code_path → POST /v2/packages (multipart) → poll build_status -- Read: GET /v2/packages/{name} -- Update: PUT /v2/packages/{name} (перезаливаем zip) -- Delete: DELETE /v2/packages/{name} +- Create: zip source_dir или читаем code_path → base64 → Kubernetes `create` CRD `packages.fission.io` +- Read: Kubernetes `get` CRD `packages.fission.io` +- Update: Kubernetes `update` CRD `packages.fission.io` +- Delete: Kubernetes `delete` CRD `packages.fission.io` #### 1.6 Resource: fission_function @@ -521,10 +538,10 @@ resource "fission_function" "hello" { ``` **CRUD:** -- Create: POST /v2/functions → JSON body -- Read: GET /v2/functions/{name} -- Update: PUT /v2/functions/{name} -- Delete: DELETE /v2/functions/{name} +- Create: Kubernetes `create` CRD `functions.fission.io` +- Read: Kubernetes `get` CRD `functions.fission.io` +- Update: Kubernetes `update` CRD `functions.fission.io` +- Delete: Kubernetes `delete` CRD `functions.fission.io` #### 1.7 Resource: fission_http_trigger @@ -546,10 +563,10 @@ resource "fission_http_trigger" "hello_route" { ``` **CRUD:** -- Create: POST /v2/triggers/http → JSON body -- Read: GET /v2/triggers/http/{name} -- Update: PUT /v2/triggers/http/{name} -- Delete: DELETE /v2/triggers/http/{name} +- Create: Kubernetes `create` CRD `httptriggers.fission.io` +- Read: Kubernetes `get` CRD `httptriggers.fission.io` +- Update: Kubernetes `update` CRD `httptriggers.fission.io` +- Delete: Kubernetes `delete` CRD `httptriggers.fission.io` #### 1.8 Build & Publish (hack/build-and-publish.sh) Адаптировать из sless: