README
¶
qStack
Собственный облачный провайдер: IaaS (вычисления, сети, диски, объектное хранилище, балансировщики), IAM и биллинг.
Control plane написан на Go. Под капотом: Debian 13, KVM/QEMU + libvirt, OVN/OVS, Ceph (RBD + RGW) или локальные диски (LVM).
Как в Proxmox: compute-узлы подключаются одной командой (qs-node join), веб-консоль доступна на любом узле. Control plane никогда не работает на compute-узлах: он разворачивается Helm-чартом в отдельном Kubernetes-кластере (минимально — одна машина с k3s).
Разработка
Код можно писать на любой ОС (в том числе Windows); сборка и тесты идут на Linux в поде k3s через DevSpace.
Нужно: Go ≥ 1.26, DevSpace и kubeconfig с доступом к dev-namespace (qstack-dev).
devspace dev # развернуть dev-под, включить синхронизацию, открыть shell
devspace run verify # make verify внутри пода
Внутри пода (или на Linux/CI напрямую):
| Команда | Что делает |
|---|---|
make gen |
генерация кода (buf, sqlc) |
make lint |
golangci-lint |
make test |
unit-тесты (-race) |
make test-integration |
интеграционные тесты (тег integration) |
make licenses |
проверка лицензий зависимостей (совместимость с Apache-2.0) |
make verify |
всё, что проверяет CI |
make build |
статические бинарники в bin/linux-<arch>/ |
make deb |
.deb (Debian 13) для qs-node и агентов в dist/ |
make image BIN=<binary> |
OCI-образ (distroless, Debian 13) |
Версии инструментов закреплены в tools/go.mod и tools/protoc/go.mod и запускаются через go tool, глобально ничего ставить не нужно.
Статус
Фаза 0 — фундамент монорепо.
Лицензия
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
qs-admin
command
Command qs-admin is the operator CLI.
|
Command qs-admin is the operator CLI. |
|
qs-node
command
Command qs-node runs on every compute node (spec 15 §2): later it serves the console and API proxy on :8443, joins the node and starts the agents (T-1.68).
|
Command qs-node runs on every compute node (spec 15 §2): later it serves the console and API proxy on :8443, joins the node and starts the agents (T-1.68). |
|
qs-resource-manager-api
command
Command qs-resource-manager-api serves the public Resource Manager API (spec 03 §6): organizations, projects and their access bindings.
|
Command qs-resource-manager-api serves the public Resource Manager API (spec 03 §6): organizations, projects and their access bindings. |
|
qs-resource-manager-controller
command
Command qs-resource-manager-controller runs the background work of Resource Manager: it publishes outbox events to NATS JetStream, reconciles quota usage with usage snapshots and purges finished operations and reservations (spec 02 §5.3, §8; 03 §5).
|
Command qs-resource-manager-controller runs the background work of Resource Manager: it publishes outbox events to NATS JetStream, reconciles quota usage with usage snapshots and purges finished operations and reservations (spec 02 §5.3, §8; 03 §5). |
|
gen
|
|
|
internal
|
|
|
iam/api
Package api serves the IAM gRPC API (spec 03 §6).
|
Package api serves the IAM gRPC API (spec 03 §6). |
|
iam/catalog
Package catalog is the declarative catalog of permissions and predefined roles (spec 03 §2), embedded from roles.yaml and loaded at start.
|
Package catalog is the declarative catalog of permissions and predefined roles (spec 03 §2), embedded from roles.yaml and loaded at start. |
|
resourcemanager/api
Package api serves the Resource Manager gRPC API: request validation, authorization and proto mapping; the use cases live in app (REQ-PLT-071).
|
Package api serves the Resource Manager gRPC API: request validation, authorization and proto mapping; the use cases live in app (REQ-PLT-071). |
|
resourcemanager/app
Package app holds the Resource Manager use cases.
|
Package app holds the Resource Manager use cases. |
|
resourcemanager/config
Package config is the configuration of the Resource Manager binaries (spec 02 §14).
|
Package config is the configuration of the Resource Manager binaries (spec 02 §14). |
|
resourcemanager/controller
Package controller runs the background work of Resource Manager: the outbox relay (REQ-PLT-090), the reconciliation of quota usage with the services' usage snapshots (REQ-RM-002) and the purge of finished operations, reservations and processed event IDs.
|
Package controller runs the background work of Resource Manager: the outbox relay (REQ-PLT-090), the reconciliation of quota usage with the services' usage snapshots (REQ-RM-002) and the purge of finished operations, reservations and processed event IDs. |
|
resourcemanager/domain
Package domain holds the Resource Manager entities and their invariants (spec 03 §2): organizations, projects and access bindings.
|
Package domain holds the Resource Manager entities and their invariants (spec 03 §2): organizations, projects and access bindings. |
|
resourcemanager/store
Package store persists Resource Manager entities in the `rm` database (REQ-PLT-080): fixed queries are generated by sqlc (sqlcdb), List queries with filters and keyset paging are built here.
|
Package store persists Resource Manager entities in the `rm` database (REQ-PLT-080): fixed queries are generated by sqlc (sqlcdb), List queries with filters and keyset paging are built here. |
|
testgen/authz
Package authzgen generates authorization tests for every public gRPC method of a service (spec 14 §1, REQ-SEC-004).
|
Package authzgen generates authorization tests for every public gRPC method of a service (spec 14 §1, REQ-SEC-004). |
|
pkg
|
|
|
agentproto
Package agentproto implements the protocol between service controllers and host agents (spec 02 §10, ADR-0005): the controller keeps every host's desired state in a Hub and serves it with HostAgentService; the agent's Client watches it (snapshot, then deltas with revisions), caches it on disk, applies it level-triggered and reports status.
|
Package agentproto implements the protocol between service controllers and host agents (spec 02 §10, ADR-0005): the controller keeps every host's desired state in a Hub and serves it with HostAgentService; the agent's Client watches it (snapshot, then deltas with revisions), caches it on disk, applies it level-triggered and reports status. |
|
apierr
Package apierr builds API errors in the qStack format (spec 02 §5.5): a gRPC status code plus google.rpc.ErrorInfo{reason: QS_*, domain: "qstack.cloud"} and, where relevant, BadRequest / QuotaFailure / RetryInfo details.
|
Package apierr builds API errors in the qStack format (spec 02 §5.5): a gRPC status code plus google.rpc.ErrorInfo{reason: QS_*, domain: "qstack.cloud"} and, where relevant, BadRequest / QuotaFailure / RetryInfo details. |
|
audit
Package audit records audit trail events (spec 11 §3, REQ-OBS-010) and removes sensitive fields from requests in audit events and logs (REQ-SEC-005).
|
Package audit records audit trail events (spec 11 §3, REQ-OBS-010) and removes sensitive fields from requests in audit events and logs (REQ-SEC-005). |
|
authz
Package authz enforces IAM permissions in every public API (spec 03 §4, REQ-IAM-011, REQ-IAM-012).
|
Package authz enforces IAM permissions in every public API (spec 03 §4, REQ-IAM-011, REQ-IAM-012). |
|
authz/authzfake
Package authzfake is an in-memory AccessService for tests: grants are (subject, permission, resource) triples and, as in IAM, a grant on a resource covers everything below it in the path (spec 03 §4.1).
|
Package authzfake is an in-memory AccessService for tests: grants are (subject, permission, resource) triples and, as in IAM, a grant on a resource covers everything below it in the path (spec 03 §4.1). |
|
clock
Package clock is the only place allowed to read wall-clock time (enforced by the forbidigo linter).
|
Package clock is the only place allowed to read wall-clock time (enforced by the forbidigo linter). |
|
config
Package config loads service configuration (spec 02 §14): a YAML file whose unknown keys are rejected, then QS_* environment overrides declared with `env` struct tags, then validation.
|
Package config loads service configuration (spec 02 §14): a YAML file whose unknown keys are rejected, then QS_* environment overrides declared with `env` struct tags, then validation. |
|
db
Package db is the PostgreSQL access layer shared by all services (spec 02 §7, ADR-0004): a pgx connection pool, transactions, optimistic locking, forward-only migrations and pool metrics.
|
Package db is the PostgreSQL access layer shared by all services (spec 02 §7, ADR-0004): a pgx connection pool, transactions, optimistic locking, forward-only migrations and pool metrics. |
|
events
Package events defines qStack events (spec 02 §8): the CloudEvents 1.0 envelope, NATS subjects and streams, a JetStream publisher and a consumer that processes every event exactly once against the consumer's database.
|
Package events defines qStack events (spec 02 §8): the CloudEvents 1.0 envelope, NATS subjects and streams, a JetStream publisher and a consumer that processes every event exactly once against the consumer's database. |
|
filter
Package filter parses List filters (spec 02 §5.2, REQ-PLT-032):
|
Package filter parses List filters (spec 02 §5.2, REQ-PLT-032): |
|
grpcclient
Package grpcclient dials internal gRPC services (spec 01 §7, 02 §11): discovery by DNS (headless Service), client-side round_robin over healthy backends (gRPC health checking), a 5 s default timeout, retries only for UNAVAILABLE (at most 3, with gRPC's jittered backoff), and propagation of the caller context: x-request-id, x-qs-subject and traceparent.
|
Package grpcclient dials internal gRPC services (spec 01 §7, 02 §11): discovery by DNS (headless Service), client-side round_robin over healthy backends (gRPC health checking), a 5 s default timeout, retries only for UNAVAILABLE (at most 3, with gRPC's jittered backoff), and propagation of the caller context: x-request-id, x-qs-subject and traceparent. |
|
idempotency
Package idempotency makes mutating API calls safe to retry (spec 02 §5.4, REQ-PLT-050).
|
Package idempotency makes mutating API calls safe to retry (spec 02 §5.4, REQ-PLT-050). |
|
ids
Package ids generates and parses resource IDs of the form `<prefix>-<ulid>` (spec 02 §3, REQ-PLT-020), e.g.
|
Package ids generates and parses resource IDs of the form `<prefix>-<ulid>` (spec 02 §3, REQ-PLT-020), e.g. |
|
operation
Package operation stores long-running operations (LRO, spec 02 §5.3) in the owner service's database (REQ-PLT-042).
|
Package operation stores long-running operations (LRO, spec 02 §5.3) in the owner service's database (REQ-PLT-042). |
|
outbox
Package outbox implements the transactional outbox (spec 02 §8, REQ-PLT-090): a change and its event are written in one transaction, and a relay running in the service's controller publishes the events to NATS JetStream and deletes them once acknowledged.
|
Package outbox implements the transactional outbox (spec 02 §8, REQ-PLT-090): a change and its event are written in one transaction, and a relay running in the service's controller publishes the events to NATS JetStream and deletes them once acknowledged. |
|
pagination
Package pagination implements List paging (spec 02 §5.2, REQ-PLT-031): page_size defaults to 100 and is capped at 1000; page_token is an opaque, HMAC-signed keyset cursor bound to the request parameters and valid for one hour.
|
Package pagination implements List paging (spec 02 §5.2, REQ-PLT-031): page_size defaults to 100 and is capped at 1000; page_token is an opaque, HMAC-signed keyset cursor bound to the request parameters and valid for one hour. |
|
protoopts
Package protoopts reads qStack proto options declared in api/proto/qstack/api/annotations.proto: the IAM permission of an RPC and the sensitive marker of a field.
|
Package protoopts reads qStack proto options declared in api/proto/qstack/api/annotations.proto: the IAM permission of an RPC and the sensitive marker of a field. |
|
quota
Package quota is the client of project quotas (spec 02 §12, 03 §5): a mutating method reserves the resources it is about to create for its operation, and the controller commits the reservation when the resource exists or releases it when the operation fails.
|
Package quota is the client of project quotas (spec 02 §12, 03 §5): a mutating method reserves the resources it is about to create for its operation, and the controller commits the reservation when the resource exists or releases it when the operation fails. |
|
quota/quotafake
Package quotafake is an in-memory QuotaService with the semantics of qs-resource-manager (spec 03 §5, REQ-RM-001): reservations are checked atomically against limits, so concurrent callers never exceed them.
|
Package quotafake is an in-memory QuotaService with the semantics of qs-resource-manager (spec 03 §5, REQ-RM-001): reservations are checked atomically against limits, so concurrent callers never exceed them. |
|
reconcile
Package reconcile runs controllers (spec 02 §9): a Reconciler drives one resource at a time towards its desired state, fed by a deduplicating work queue with exponential backoff, by events and by periodic resync.
|
Package reconcile runs controllers (spec 02 §9): a Reconciler drives one resource at a time towards its desired state, fed by a deduplicating work queue with exponential backoff, by events and by periodic resync. |
|
telemetry
Package telemetry wires logging, metrics, tracing and health endpoints the same way in every qStack binary (spec 02 §13).
|
Package telemetry wires logging, metrics, tracing and health endpoints the same way in every qStack binary (spec 02 §13). |
|
testenv
Package testenv provides real infrastructure for integration tests (build tag `integration`, spec 14 §1).
|
Package testenv provides real infrastructure for integration tests (build tag `integration`, spec 14 §1). |
|
validate
Package validate checks requests against their protovalidate rules (spec 02 §1) before the handler runs: a violation is INVALID_ARGUMENT / QS_INVALID_FIELD with one google.rpc.BadRequest field violation per rule.
|
Package validate checks requests against their protovalidate rules (spec 02 §1) before the handler runs: a violation is INVALID_ARGUMENT / QS_INVALID_FIELD with one google.rpc.BadRequest field violation per rule. |
|
version
Package version reports build metadata of qStack binaries.
|
Package version reports build metadata of qStack binaries. |
Click to show internal directories.
Click to hide internal directories.