fission-console/.github/copilot-instructions.md

Правила работы агента в проекте fission

ГЛАВНОЕ ПРАВИЛО

НЕ "СОВЕРШЕНСТВОВАТЬ" РАБОЧИЙ КОД БЕЗ ЯВНОГО УКАЗАНИЯ.

---

Файловая система и выполнение команд

Маппинг путей

Локальная папка ~/remote_dev/ примонтирована через sshfs к ~/terra/ на ВМ 5.172.178.213. Это одна и та же файловая система:

Локально (VS Code)	На ВМ
/home/naeel/remote_dev/fission	/home/naeel/terra/fission
/home/naeel/remote_dev/sless	/home/naeel/terra/sless
/home/naeel/remote_dev/IoT	/home/naeel/terra/IoT

Любой файл, сохранённый локально через VS Code, мгновенно виден на ВМ. SCP не нужен.

Что можно делать локально

• Редактировать файлы — через VS Code, replace_string_in_file, create_file и т.д. Изменения сразу на ВМ.
• Читать файлы — read_file, grep_search, file_search, semantic_search — всё разрешено.

Что ЗАПРЕЩЕНО локально

Все команды выполнять ИСКЛЮЧИТЕЛЬНО через SSH на ВМ:

ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 'КОМАНДА'

Причина: локально может быть активен VPN, что вызывает сбои при выполнении сетевых команд, обращениях к кластеру, Docker и пр.

Запрещено запускать локально (без ssh):

• go build, go test, go mod tidy
• docker build, docker push
• kubectl, helm
• terraform
• curl, wget к кластерным сервисам
• git push, git pull (git операции — через ssh на ВМ)
• Любые bash-скрипты проекта

Формат работы

1. Отредактировать файлы локально (VS Code / инструменты агента)
2. Запустить команды через SSH на ВМ
3. Ждать результата

---

Документация

Всё важное фиксировать в doc/:

• doc/thinking/ — лог рассуждений агента (обязательно)
• doc/progress.md — трекер задач
• Обновлять после каждого значимого изменения.

Git

Коммитить и пушить после каждого завершённого этапа.

Версионирование тегами

После каждого коммита с изменениями — поднимать версию тега:

# Посмотреть текущий тег
git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"

# Поднять patch-версию (v0.1.0 → v0.1.1, v0.1.1 → v0.1.2 и т.д.)
git tag vX.Y.Z && git push origin vX.Y.Z

Правила:

• Patch (Z) — любое изменение: правка кода, новая функция, фикс
• Minor (Y) — новая фича/компонент (новый ресурс провайдера, новый модуль консоли)
• Major (X) — breaking change
• Тег ставить ПОСЛЕ успешного коммита и пуша
• Формат: vMAJOR.MINOR.PATCH (например v0.2.3)

---

Как создать и задеплоить новую Fission-функцию через Terraform

Пошаговая инструкция (ОБЯЗАТЕЛЬНО следовать)

Шаг 1: Создать папку с функцией

Создать папку в examples/ по шаблону. Пример: examples/my-test/

Структура:

examples/my-test/
├── code/
│   └── main.py       # Код функции
└── main.tf            # Terraform манифест

Шаг 2: Написать код функции

Файл code/main.py — обязательно функция main():

def main():
    return "hello from my-test"

Можно сложнее — с аргументами, JSON, вычислениями:

import json

def main():
    result = {"status": "ok", "data": [1, 2, 3]}
    return json.dumps(result)

Шаг 3: Написать Terraform манифест

Файл main.tf — КОПИРОВАТЬ этот шаблон и менять только имена и URL:

terraform {
  required_providers {
    fission = {
      source  = "nail/fission"
      version = "~> 0.1.0"
    }
  }
}

provider "fission" {
  kubeconfig_path = "/home/naeel/.kube/config"
  namespace       = "default"
}

resource "fission_environment" "python" {
  name    = "УНИКАЛЬНОЕ-ИМЯ-env"
  image   = "ghcr.io/fission/python-env"
  version = 3
}

resource "fission_package" "pkg" {
  name        = "УНИКАЛЬНОЕ-ИМЯ-pkg"
  environment = fission_environment.python.name
  source_dir  = "${path.module}/code"
}

resource "fission_function" "fn" {
  name         = "УНИКАЛЬНОЕ-ИМЯ-fn"
  environment  = fission_environment.python.name
  package_name = fission_package.pkg.name
  entrypoint   = "main.main"
}

resource "fission_http_trigger" "route" {
  name     = "УНИКАЛЬНОЕ-ИМЯ-route"
  function = fission_function.fn.name
  url      = "/УНИКАЛЬНЫЙ-URL"
  methods  = ["GET"]
}

ВАЖНО: Все имена ресурсов (name) должны быть уникальными по всему кластеру. Используй префикс, например tf-mytest-env, tf-mytest-pkg, tf-mytest-fn, tf-mytest-route.

Шаг 4: Задеплоить через SSH

ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd ~/terra/fission/examples/my-test && TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission terraform apply -auto-approve'

ОБЯЗАТЕЛЬНО:

• Переменная TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission — ВСЕГДА нужна (dev override провайдера)
• terraform init НЕ нужен (dev_overrides пропускает init)
• Выполнять ТОЛЬКО через SSH

Шаг 5: Проверить функцию через curl

Роутер требует JWT. Паттерн:

ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 '
PASSWORD=$(kubectl -n fission get secret router -o jsonpath={.data.password} | base64 -d)
TOKEN=$(curl -sk -X POST https://fission.kube5s.ru/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"$PASSWORD\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)[\"accesstoken\"])")
curl -sk -H "Authorization: Bearer $TOKEN" https://fission.kube5s.ru/УНИКАЛЬНЫЙ-URL
'

Шаг 6: Удалить (если нужно)

ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd ~/terra/fission/examples/my-test && TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission terraform destroy -auto-approve'

Уже задеплоенные функции (НЕ ТРОГАТЬ без явного указания)

Папка	Endpoint	Ответ
examples/hello-python/	GET /tf-hello	hello from fission via terraform
examples/stress-suite/	GET /stress/fast	fast-ok
examples/stress-suite/	GET /stress/cpu	cpu-ok:NUMBER
examples/stress-suite/	GET /stress/json	{"status":"ok","service":"json"}

Частые ошибки

Ошибка	Причина	Решение
unauthorized: malformed token	curl без JWT	Добавить JWT (см. шаг 5)
terraform init required	Забыт TF_CLI_CONFIG_FILE	Добавить TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission
resource already exists	Имя не уникальное	Сменить имена на уникальные с префиксом
Error: connection refused	Команда запущена локально	Выполнять ТОЛЬКО через SSH
package not found	Опечатка в source_dir	Проверить path.module/code и файл main.py