Platform API (Go)

RESTful API server for Kubernetes-based platform management. Built with Go, Gin framework, and PostgreSQL.

Status: Production Ready

Overview

Platform-go provides a RESTful API for managing Kubernetes resources, user authentication, project management, and persistent storage.

Key Features

User and group management with RBAC
Kubernetes resource orchestration (namespaces, PVCs, pods)
Project and configuration file management
Image pull job tracking and monitoring
Persistent storage lifecycle management
Comprehensive audit logging
Token-based authentication (JWT)
PostgreSQL database with view-based queries

Architecture

The platform follows a modular architecture:

API Server - HTTP REST interface (port 8080)
Business Logic - Application services and domain models
Data Layer - Repository pattern with PostgreSQL
K8s Integration - Client-go based Kubernetes operations

Quick Start

Prerequisites

Go 1.21 or later
PostgreSQL 12 or later
Kubernetes cluster (for full functionality)
Optional: MinIO or S3-compatible storage

Run Locally

# Clone repository
git clone https://github.com/linskybing/platform-go.git
cd platform-go

# Download dependencies
go mod download

# Run tests
go test ./...

# Build API
make build-api

# Run API server
./bin/api

Installation

Database Setup

Create PostgreSQL database:

createdb platform_db

Apply schema:

psql platform_db < infra/db/schema.sql

Configure environment:

cp .env.example .env
# Edit .env with database credentials

Build from Source

# Build all components
make build

# Build API only
make build-api

# Build with optimizations
make build-production

Docker Build

# Build API image
docker build -t platform-go-api:latest -f Dockerfile .

# Run container
docker run -p 8080:8080 platform-go-api:latest

Configuration

Environment Variables

Create .env file or set environment variables:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=platform_db

# Server Configuration
PORT=8080
GIN_MODE=release

# Kubernetes Configuration
KUBECONFIG=/path/to/kubeconfig
DEFAULT_STORAGE_CLASS=standard
USER_PV_SIZE=10Gi

# Security
JWT_SECRET=your_secret_key
BCRYPT_COST=12

Kubernetes Secrets

For production deployment, use Kubernetes secrets:

kubectl create secret generic platform-secrets \
  --from-literal=db-password=your_password \
  --from-literal=jwt-secret=your_secret

Project Structure

platform-go/
├── cmd/
│   └── api/              # API server entry point
├── internal/
│   ├── api/              # HTTP handlers and middleware
│   ├── application/      # Business logic services
│   │   ├── user/         # User management
│   │   ├── group/        # Group management
│   │   ├── project/      # Project management
│   │   ├── configfile/   # Config file management
│   │   ├── image/        # Image pull jobs
│   │   └── k8s/          # Kubernetes operations
│   ├── domain/           # Entity models and DTOs
│   ├── repository/       # Data access layer
│   ├── config/           # Configuration management
│   │   └── db/           # Database setup and migrations
│   ├── constants/        # Application constants
│   └── cron/             # Background jobs
├── pkg/
│   ├── k8s/              # Kubernetes client utilities
│   ├── utils/            # Helper functions
│   └── response/         # HTTP response utilities
├── k8s/                  # Kubernetes manifests
├── docs/                 # Documentation
├── Makefile              # Build automation
└── go.mod                # Go dependencies

Development

Code Quality

# Format code
make fmt

# Check formatting
make fmt-check

# Run linter
make vet

# Static analysis
go vet ./...

Run Tests

# All tests
make test

# With coverage
make test-coverage

# Race detection
make test-race

# Verbose output
make test-verbose

# Specific package
go test ./internal/application/user -v

Generate Coverage Report

# HTML report
make coverage-html

# Terminal report
go test -cover ./...

Make Targets

Use make help to see all available commands. Key targets include:

# Skills-based commands (from .github/skills)
make skills-lint              # Production standards
make skills-compile           # Compilation check
make skills-migration         # Database migration validation
make docker-integration       # Docker integration tests
make ci-extended              # Extended CI pipeline
make production-check         # Full production validation

Testing

Test Statistics

Total Tests: 100+ unit tests
Coverage: 60%+ across core packages
Status: All passing

Test Coverage by Package

Package	Tests	Coverage
`internal/application/user`	15+	70%
`internal/application/group`	12+	65%
`internal/application/configfile`	10+	60%
`internal/application/k8s`	8+	55%
`pkg/utils`	8+	75%

Run Specific Tests

# User service tests
go test ./internal/application/user -run TestRegisterUser -v

# Group service tests
go test ./internal/application/group -v

# Integration tests
make test-integration

Deployment

Kubernetes Deployment

Prerequisites

Kubernetes cluster running
kubectl configured
Database accessible from cluster

Deploy Steps

# 1. Create namespace
kubectl create namespace platform

# 2. Apply secrets
kubectl apply -f k8s/secret.yaml

# 3. Deploy PostgreSQL (if needed)
kubectl apply -f k8s/postgres.yaml

# 4. Deploy API
kubectl apply -f k8s/go-api.yaml

# 5. Verify deployment
kubectl get pods -n platform
kubectl logs -f deployment/platform-api -n platform

Using Makefile

# Deploy all resources
make k8s-deploy

# Check status
make k8s-status

# View logs
make k8s-logs-api

# Delete resources
make k8s-delete

Production Considerations

Security

Use Kubernetes secrets for sensitive data
Enable RBAC and network policies
Use TLS for database connections
Rotate JWT secrets regularly
Implement rate limiting

Scaling

Horizontal pod autoscaling based on CPU/memory
Database connection pooling
Read replicas for PostgreSQL
Redis cache for frequently accessed data

Monitoring

Prometheus metrics endpoint
Structured logging with log levels
Request tracing and correlation IDs
Health check endpoints (/health, /ready)

API Documentation

Base URL

http://localhost:8080/api

Authentication

Include JWT token in request header:

Authorization: Bearer <your_token>

Endpoints Overview

Method	Endpoint	Description
POST	`/api/auth/login`	User login
POST	`/api/auth/register`	User registration
GET	`/api/users`	List users
POST	`/api/users`	Create user
GET	`/api/projects`	List projects
POST	`/api/projects`	Create project
GET	`/api/groups`	List groups
POST	`/api/storage/initialize`	Initialize user storage

For complete API documentation, see API Standards.

Documentation

Core Documentation

API Standards - API design, response formats, error handling
K8s Architecture Analysis - Kubernetes integration and resource management

Additional Resources

Makefile - Build targets and automation
k8s/ - Kubernetes deployment manifests
.github/workflows/ - CI/CD pipeline configuration

Contributing

Workflow

Fork the repository
Create feature branch (git checkout -b feature/new-feature)
Make changes and add tests
Run tests and formatting (make test && make fmt)
Commit changes (git commit -m 'Add new feature')
Push to branch (git push origin feature/new-feature)
Create Pull Request

Code Standards

Follow Go best practices and idioms
Write unit tests for new features
Maintain test coverage above 60%
Use meaningful variable and function names
Add comments for complex logic
Keep functions focused and small

Pull Request Guidelines

Describe changes clearly in PR description
Reference related issues
Ensure all tests pass
Update documentation if needed
Keep commits atomic and well-described

Last Updated: 2026-02-02
Version: 1.0.0
Status: Production Ready

Quick Start

Prerequisites

Go 1.21+
PostgreSQL 12+
(Optional) MinIO for object storage

Local Development

# Download dependencies
go mod download

# Run all tests
go test ./...

# Build binaries
make build

# Build API only
make build-api

# Build Scheduler only
make build-scheduler

Notes

Read each helper script before running; some modify system state
Ensure PostgreSQL is running before deployment
MinIO is not deployed by default. The backend can connect to an external S3/MinIO-compatible object storage; configure endpoint and credentials via Kubernetes Secret or environment variables.

Deployment & development cautions (important)

Initial database and .env: The project depends on backend/infra/db/schema.sql for database schema and seed data (for example, creating the initial admin user). Before starting or deploying the backend, provide a .env file (or Kubernetes Secret) with the correct database connection string, credentials, and required settings. Without proper DB credentials or permissions, initialization will fail.
backend/scripts/build_image.sh (update registry): This script helps build and push the backend image to a registry. Before deploying to your cluster, update the script's HARBOR/REGISTRY/IMAGE/TAG values or modify the script to accept environment variables so the image is pushed to a registry accessible by your cluster.
Development manifests using hostPath: Development manifests may mount local host files (for example certificates or configs) into Pods using hostPath. This is convenient for single-node testing but is insecure and non-portable for multi-node or production clusters. Replace hostPath with Secret, ConfigMap, or PVC before deploying to shared clusters.
Suggested deploy order: Build and push images, update manifest image strings, then apply manifests. Suggested order:
1. kubectl apply -f ca.yaml (if TLS/CA manifests are required)
2. kubectl apply -f k8s/go-api.yaml (or go-api.yaml)
3. kubectl apply -f k8s/postgres.yaml
The goal is to ensure Deployments reference images that exist in the registry and that any DB PV/PVC is ready.

Kubernetes Deployment

# Deploy all resources
make k8s-deploy

# View status
make k8s-status

# View logs
make k8s-logs-api
make k8s-logs-scheduler

# Cleanup
make k8s-delete

Project Structure

platform-go/
 cmd/ # Application entry points
 api/ # REST API server
 scheduler/ # Background job scheduler
 internal/
 api/ # HTTP layer
 application/ # Business logic
 domain/ # Entity models
 repository/ # Data access
 scheduler/ # Scheduling infrastructure
 priority/ # Resource priority management
 pkg/ # Reusable packages
 k8s/ # Kubernetes manifests
 infra/ # Infrastructure setup
 docs/ # Documentation

Common Commands

Testing

make test # Run all tests
make test-coverage # Generate coverage report
make test-race # Check for race conditions

Code Quality

make fmt # Format code
make fmt-check # Check format
make vet # Static analysis

Build & Deploy

make build # Build API + Scheduler
make clean # Clean artifacts
make ci # Full CI pipeline
make all # Build + Deploy

See Quick Reference for more commands.

Test Results

Unit Tests: 100+ tests, all passing
Code Format: All files properly formatted
Static Analysis: No issues found
Build: Both API and Scheduler binaries successful

Test coverage:

internal/application - 50+ tests
internal/scheduler - 10+ tests
internal/priority - 3 tests
pkg/mps - 4 tests
pkg/utils - 8 tests

See Testing Report for details.

Docker & Kubernetes

Build Docker Images

Build the API image. The Scheduler image target is present in the repo but the Scheduler component is not implemented yet.

docker build -t platform-go-api:latest -f deploy/api.Dockerfile .
# docker build -t platform-go-scheduler:latest -f deploy/scheduler.Dockerfile .  # scheduler not implemented

Kubernetes Deployment

Apply API manifests and related resources. Scheduler manifests are provided as placeholders and should not be applied until the Scheduler is implemented.

# Apply all manifests (API + resources)
kubectl apply -f k8s/

# Or apply individually
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/postgres.yaml
kubectl apply -f k8s/go-api.yaml
# kubectl apply -f k8s/go-scheduler.yaml  # scheduler not implemented

Configuration

Environment variables (via K8s secrets):

DB_HOST=postgres
DB_PORT=5432
DB_USER=<from-secret>
DB_PASSWORD=<from-secret>

See k8s/secret.yaml for sensitive data management.

Helper Scripts

scripts/dev.sh - Local development setup
scripts/build_images.sh - Docker build automation
scripts/setup_fakek8s.sh - Local K8s cluster setup
scripts/create_gpu_pod.py - GPU pod creation helper

API Documentation

Swagger documentation available at /swagger.html when server is running.

See internal/api/handlers/ for endpoint implementations.

Development Tips

Run specific test

go test ./internal/application -run TestCreateUserGroup -v

Generate coverage HTML

make coverage-html # Opens in browser

Check code format issues

make fmt-check

View detailed test output

make test-verbose

Architecture

API Server (cmd/api/) - HTTP REST interface

Port 8080
Request/response handling
Business logic orchestration

Scheduler - planned background job processor (not implemented)

Shared code areas:

Domain models (internal/domain/)
Business logic (internal/application/)
Data access layer (internal/repository/)

Key Files

File	Purpose
`Makefile`	Build and development tasks
`.github/workflows/integration-test.yml`	CI/CD pipeline
`go.mod` / `go.sum`	Go dependencies
`k8s/go-api.yaml`	API deployment config
`k8s/go-scheduler.yaml`	Scheduler deployment config

Features

Modular architecture with clear separation of concerns
Comprehensive unit tests (100+ tests)
Kubernetes-ready with full YAML configs
Independent API and Scheduler services
Priority-based job scheduling
GPU resource management
Full audit logging
Project and configuration file management

Contributing

Make changes to code
Run tests: make test
Format code: make fmt
Build: make build
Test in Kubernetes: make k8s-deploy

Last Updated: 2026-01-15 Status: Production Ready

Name		Name	Last commit message	Last commit date
Latest commit History 156 Commits
.github		.github
cmd		cmd
docs		docs
infra		infra
internal		internal
k8s		k8s
pkg		pkg
test/integration		test/integration
tools		tools
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
Dockerfile.integration		Dockerfile.integration
Makefile		Makefile
README.md		README.md
coverage.html		coverage.html
go.mod		go.mod
go.sum		go.sum
main		main
platform		platform

Folders and files

Latest commit

History

Repository files navigation

Platform API (Go)

Table of Contents

Overview

Key Features

Architecture

Quick Start

Prerequisites

Run Locally

Installation

Database Setup

Build from Source

Docker Build

Configuration

Environment Variables

Kubernetes Secrets

Project Structure

Development

Code Quality

Run Tests

Generate Coverage Report

Make Targets

Testing

Test Statistics

Test Coverage by Package

Run Specific Tests

Deployment

Kubernetes Deployment

Prerequisites

Deploy Steps

Using Makefile

Production Considerations

Security

Scaling

Monitoring

API Documentation

Base URL

Authentication

Endpoints Overview

Documentation

Core Documentation

Additional Resources

Contributing

Workflow

Code Standards

Pull Request Guidelines

Quick Start

Prerequisites

Local Development

Notes

Deployment & development cautions (important)

Kubernetes Deployment

Project Structure

Common Commands

Testing

Code Quality

Build & Deploy

Test Results

Docker & Kubernetes

Build Docker Images

Kubernetes Deployment

Configuration

Helper Scripts

API Documentation

Development Tips

Run specific test

Generate coverage HTML

Check code format issues

View detailed test output

Architecture

Key Files

Features

Contributing

About

Resources

Uh oh!

Stars

Packages