dubey/kat
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
kat/docs/plan/filestructure.md
Tanishq Dubey e03e27270b
Init Docs
2025-05-09 19:15:50 -04:00

7.8 KiB
Raw Blame History

Directory/File Structure

This structure assumes a Go-based project, as hinted by the Go interface definitions in the RFC.

kat-system/
├── README.md               # Project overview, build instructions, contribution guide
├── LICENSE                 # Project license (e.g., Apache 2.0, MIT)
├── go.mod                  # Go modules definition
├── go.sum                  # Go modules checksums
├── Makefile                # Build, test, lint, generate code, etc.
│
├── api/
│   └── v1alpha1/
│       ├── kat.proto       # Protocol Buffer definitions for all KAT resources (Workload, Node, etc.)
│       └── generated/      # Generated Go code from .proto files (e.g., using protoc-gen-go)
│                           # Potentially OpenAPI/Swagger specs generated from protos too.
│
├── cmd/
│   ├── kat-agent/
│   │   └── main.go         # Entrypoint for the kat-agent binary
│   └── katcall/
│       └── main.go         # Entrypoint for the katcall CLI binary
│
├── internal/
│   ├── agent/
│   │   ├── agent.go        # Core agent logic, heartbeating, command processing
│   │   ├── runtime.go      # Interface with ContainerRuntime (Podman)
│   │   ├── build.go        # Git-native build process logic
│   │   └── dns_resolver.go # Embedded DNS server logic
│   │
│   ├── leader/
│   │   ├── leader.go       # Core leader logic, reconciliation loops
│   │   ├── schedule.go     # Scheduling algorithm implementation
│   │   ├── ipam.go         # IP Address Management logic
│   │   ├── state_backup.go # etcd backup logic
│   │   └── api_handler.go  # HTTP API request handlers (connects to api/v1alpha1)
│   │
│   ├── api/                # Server-side API implementation details
│   │   ├── server.go       # HTTP server setup, middleware (auth, logging)
│   │   ├── router.go       # API route definitions
│   │   └── auth.go         # Authentication (mTLS, Bearer token) logic
│   │
│   ├── cli/
│   │   ├── commands/       # Subdirectories for each katcall command (apply, get, logs, etc.)
│   │   │   ├── apply.go
│   │   │   └── ...
│   │   ├── client.go       # HTTP client for interacting with KAT API
│   │   └── utils.go        # CLI helper functions
│   │
│   ├── config/
│   │   ├── types.go        # Go structs for Quadlet file kinds if not directly from proto
│   │   ├── parse.go        # Logic for parsing and validating *.kat files (Quadlets, cluster.kat)
│   │   └── defaults.go     # Default values for configurations
│   │
│   ├── store/
│   │   ├── interface.go    # Definition of StateStore interface (as in RFC 5.1)
│   │   └── etcd.go         # etcd implementation of StateStore, embedded etcd setup
│   │
│   ├── runtime/
│   │   ├── interface.go    # Definition of ContainerRuntime interface (as in RFC 6.1)
│   │   └── podman.go       # Podman implementation of ContainerRuntime
│   │
│   ├── network/
│   │   ├── wireguard.go    # WireGuard setup and peer management logic
│   │   └── types.go        # Network related internal types
│   │
│   ├── pki/
│   │   ├── ca.go           # Certificate Authority management (generation, signing)
│   │   └── certs.go        # Certificate generation and handling utilities
│   │
│   ├── observability/
│   │   ├── logging.go      # Logging setup for components
│   │   ├── metrics.go      # Metrics collection and exposure logic
│   │   └── events.go       # Event recording and retrieval logic
│   │
│   ├── types/              # Core internal data structures if not covered by API protos
│   │   ├── node.go
│   │   ├── workload.go
│   │   └── ...
│   │
│   ├── constants/
│   │   └── constants.go    # Global constants (etcd key prefixes, default ports, etc.)
│   │
│   └── utils/
│       ├── utils.go        # Common utility functions (error handling, string manipulation)
│       └── tar.go          # Utilities for handling tar.gz Quadlet archives
│
├── docs/
│   ├── rfc/
│   │   └── RFC001-KAT.md   # The source RFC document
│   ├── user-guide/         # User documentation (installation, getting started, tutorials)
│   │   ├── installation.md
│   │   └── basic_usage.md
│   └── api-guide/          # API usage documentation (perhaps generated)
│
├── examples/
│   ├── simple-service/     # Example Quadlet for a simple service
│   │   ├── workload.kat
│   │   └── VirtualLoadBalancer.kat
│   ├── git-build-service/  # Example Quadlet for a service built from Git
│   │   ├── workload.kat
│   │   └── build.kat
│   ├── job/                # Example Quadlet for a Job
│   │   ├── workload.kat
│   │   └── job.kat
│   └── cluster.kat         # Example cluster configuration file
│
├── scripts/
│   ├── setup-dev-env.sh    # Script to set up development environment
│   ├── lint.sh             # Code linting script
│   ├── test.sh             # Script to run all tests
│   └── gen-proto.sh        # Script to generate Go code from .proto files
│
└── test/
    ├── unit/               # Unit tests (mirroring internal/ structure)
    ├── integration/        # Integration tests (e.g., agent-leader interaction)
    └── e2e/                # End-to-end tests (testing full cluster operations via katcall)
        ├── fixtures/       # Test Quadlet files
        └── e2e_test.go

Description of Key Files/Directories and Relationships:

  • api/v1alpha1/kat.proto: The source of truth for all resource definitions. make generate (or scripts/gen-proto.sh) would convert this into Go structs in api/v1alpha1/generated/. These structs will be used across the internal/ packages.
  • cmd/kat-agent/main.go: Initializes and runs the kat-agent. It will instantiate components from internal/store (for etcd), internal/agent, internal/leader, internal/pki, internal/network, and internal/api (for the API server if elected leader).
  • cmd/katcall/main.go: Entry point for the CLI. It uses internal/cli components to parse commands and interact with the KAT API via internal/cli/client.go.
  • internal/config/parse.go: Used by the Leader to parse submitted Quadlet tar.gz archives and by kat-agent init to parse cluster.kat.
  • internal/store/etcd.go: Implements StateStore and manages the embedded etcd instance. Used by both Agent (for watching) and Leader (for all state modifications, leader election).
  • internal/runtime/podman.go: Implements ContainerRuntime. Used by internal/agent/runtime.go to manage containers based on Podman.
  • internal/agent/agent.go and internal/leader/leader.go: Contain the core state machines and logic for the respective roles. The kat-agent binary decides which role's logic to activate based on leader election status.
  • internal/pki/ca.go: Used by kat-agent init to create the CA, and by the Leader to sign CSRs from joining agents.
  • internal/network/wireguard.go: Used by agents to configure their local WireGuard interface based on data synced from etcd (managed by the Leader).
  • internal/leader/api_handler.go: Implements the HTTP handlers for the API, using other leader components (scheduler, IPAM, store) to fulfill requests.