Repository Contents

Updated: 2026-03-01 Purpose: single-file map of repository structure for quick onboarding and orientation.

How to use this file

Read this file at the start of a new chat/session to understand repo structure quickly.
Re-read this file when context is unclear, requirements conflict, or there are navigation uncertainties.
For active build/deploy work, treat devops/ as the primary operational source of truth.

Для instance-ресурсов с операциями suspend/resume обязательный источник правил: docs/60_strategy/provider_philosophy.md (разделы 7-9).
Применять только каноничные флаги: adopt_existing_on_create (default false) и suspend_on_destroy (default true).
Логика apply/destroy/modify должна следовать status-matrix из стратегии (deleted, suspend, running, not created, creating).
Упоминания resume_if_exists и delete_mode считать legacy и не использовать как норматив для новой реализации.

docs/ — Единый корень документации (overview, discovery, registry, analysis, history, strategy, API).
tools/har/ — Scripts used to analyze HAR files and extract parameters/stages.
har/ — Collected HAR files captured from browser/API traffic (raw evidence files).
artifacts/ — JSON artifacts produced by live API queries and intermediate outputs.
internal/provider/ — Terraform provider implementation (resources and data-sources).
operator/, k8s/ — Operator manifests and Kubernetes overlays.
examples/ & tests/ — Usage examples and test scenarios for the provider.

Cloud Storage: The project uses Nubes Cloud S3 (s3.msk-1.ngcloud.ru) with S3_* variables.
Infrastructure: Storage is external S3; Kubernetes resources are S3-only.
Docs Location: Published static HTML is stored in the terraform-registry bucket.
Path Pattern: /docs/nubes/nubes/<version>/ (Proxy logic handles mapping to S3 keys).
Branding: Documentation uses MkDocs Material with Nubes "Strict" style (Logo-only header, Blue/Indigo palette).
CI Secrets: S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, REGISTRY_HOSTNAME.
History & Discovery: See docs/history/09_s3_migration_and_branded_docs.md, docs/discovery/s3-storage-and-docs-architecture.md and docs/discovery/documentation_build_and_deploy.md for full context on this transition and build processes.

docs/README.md — Главный индекс документации (быстрые ссылки на критические темы).
docs/00_overview/ — Обзор, архитектура, чеклисты.
docs/20_discovery/ — Discovery-материалы по сервисам.
docs/30_registry/ — Реестр и ресурсы.
docs/40_analysis/ — Анализ, форензика, инциденты.
docs/50_history/ — История изменений.
docs/60_strategy/ — Стратегия и принципы.
docs/70_api/ — API-материалы и дампы.
- docs/70_api/api_analysis/ — API reverse-engineering outputs and machine-generated API documentation.

analyze_f12_har.py — Script to parse f12vmbad.har and extract operation timelines.
analyze_faststart.py — Analysis helper for faststart.har.
extract_params.py — Extracts instanceOperationCfsParams bodies and maps them to svc IDs.
compare_har.py — Diffing tool for HAR files (stages/headers summary).
check_op.py / check_status.py — Helpers to re-query API operation status.

f12vmbad.har, f12vmbad1.har, faststart.har, edge.har, vm.har, etc. — Raw HAR files. Large and sensitive; don't commit new raw HARs to repo without consent. Use tools/har/* scripts to parse.

edge_instance.json, service_22_detail.json, instances_list.json — Live API JSON dumps captured during investigation. Use them to craft provider schemas.

*resource.go, *_data_source.go — Provider implementations for resources (VM, VDC, Edge, VApp, Postgres, S3bucket, etc.). Important files:
- vm_resource.go — VM lifecycle logic & polling
- edge_resource.go — Edge discovery/resolution
- provider.go — Provider schema and configuration

examples/* — Terraform example configs for different deployment patterns (full-stack, infra-only, quick-start).
tests/* — Automated test scenarios (lifecycle, postgres modify tests, s3 tests). Use to validate changes.

Operator code and Kubernetes manifests to run the Registry/Operator. Contains build artifacts in operator/bin/.