sdk_ops

README

sdk-ops

CLI: sdk-ops — Go SDK: import "github.com/natuleadan/sdk-ops"

A CLI tool for provisioning, hardening, and operating VPS servers. Automates the full lifecycle: SSH-based hardening (nftables, fail2ban, kernel tuning), Docker/k3s installation, service deployment with auto-rollback, and cluster management via kubectl.

---

Install

go install github.com/natuleadan/sdk-ops/cmd/sdk-ops@latest

Or download a pre-built binary from the releases page.

Quick Start

1. Register a node

sdk-ops config add-node 192.168.1.100 --user root --key ~/.ssh/id_ed25519

2. Provision a fresh VPS

sdk-ops infra init 192.168.1.100        # hardening + Docker + k3s (default)
# sdk-ops infra init 192.168.1.100 --docker   # Docker only
# sdk-ops infra init 192.168.1.100 --bare     # Hardening only

3. Check the cluster

sdk-ops infra status 192.168.1.100

4. Deploy a service

sdk-ops deploy push ./my-service --node 192.168.1.100

5. Operate the cluster

sdk-ops cluster nodes
sdk-ops cluster pods --all-namespaces
sdk-ops cluster top

6. View real-time metrics

sdk-ops node info 192.168.1.100
sdk-ops node top 192.168.1.100

Use as Go SDK

import "github.com/natuleadan/sdk-ops"

// Option 1: YAML-driven
server, _ := ops.New("server.yaml")
server.Provision(ctx)

// Option 2: Programmatic
server := &ops.ServerConfig{
    Host:  "192.168.1.100",
    User:  "root",
    SSHKey: "~/.ssh/id_ed25519",
    Mode:  ops.ModeK3s,
}
s := ops.New(cfg)
s.Provision(ctx)

// Check status
status, _ := s.Status()
fmt.Println(status)

// Deploy a service
s.Deploy("./my-service")

// Cluster operations
s.Cluster().Nodes()
s.Cluster().Pods("")
s.Cluster().Top()

Commands

See docs/commands.md for the full reference. Summary by category:

Category	Command	Purpose
Provision	sdk-ops infra init	Harden + install Docker/k3s
	sdk-ops infra join	Join a worker to k3s cluster
	sdk-ops infra status	Show server health
	sdk-ops infra remove	Uninstall sdk-ops from server
Operations	sdk-ops node list	List registered nodes
	sdk-ops node info	Real-time dashboard (CPU, RAM, disk)
	sdk-ops node top	Interactive htop via SSH
	sdk-ops node exec	Run a command remotely
Deploy	sdk-ops deploy push	Build + upload + deploy a service
	sdk-ops service status	Show deployed service status
	sdk-ops service logs	Tail service logs
	sdk-ops service rollback	Rollback to previous version
Cluster	sdk-ops cluster *	17 kubectl commands (nodes, pods, logs, scale, etc.)
Config	sdk-ops config init/list-nodes/add-node/remove-node	Manage ~/.sdk-ops/config.yaml

Targets

Mode	What gets installed
--k3s (default)	Hardening + Docker + k3s + Traefik
--docker	Hardening + Docker
--bare	Hardening only

Deploy Flow

Local (Mac ARM)                        VPS (x86_64)
─────                                   ─────
1. go build (linux/amd64)               docker pull
2. docker buildx + push ──registry──→  
3. tar files + SSH pipe ────────→      /opt/sdk-ops/services/<name>/v{N}/
4.                                      symlink: current → v{N}
5.                                      docker compose up -d
6.                                      Health check → OK or rollback

Documentation

File	Contents
docs/commands.md	Full command reference (all flags, subcommands)
docs/architecture.md	Architecture, hardening order, deploy engine
docs/conventional-commits.md	Commit rules, versioning, release flow
AGENTS.md	AI assistant guide

Conventional Commits

This project follows Conventional Commits for versioning and changelog generation. See docs/conventional-commits.md for the full reference.

Quick summary:

feat(cli): add --crowdsec flag to infra init   # minor bump (or patch in 0.x)
fix(ssh): handle reconnection after port change # patch bump
feat(cli)!: change output format                 # major bump

Scope is required. Pull requests will be rejected if any commit lacks a scope.

Project Structure

├── cmd/sdk-ops/              # CLI entrypoint (Cobra)
├── ssh/                  # SSH client abstraction (public SDK)
├── hardening/            # 6-step VPS hardening (public SDK)
├── docker/               # Docker install + compose (public SDK)
├── k3s/                  # k3s install + kubectl wrappers (public SDK)
├── deploy/               # Build + push + deploy engine (public SDK)
├── monitor/              # Node dashboard + metrics (public SDK)
├── server.go             # High-level ops.Server API
├── config.go             # YAML-driven config
├── docs/                 # Documentation
└── .github/              # CI/CD workflows

License

MIT

Documentation

Index

• type ClusterClient
  • func (c *ClusterClient) Logs(pod string, follow bool) (string, error)
  • func (c *ClusterClient) Nodes() (string, error)
  • func (c *ClusterClient) Pods(namespace string) (string, error)
  • func (c *ClusterClient) Top() (string, error)
• type Config
• type Mode
• type Server
  • func New(cfg ServerConfig) *Server
  • func (s *Server) Close() error
  • func (s *Server) Cluster() *ClusterClient
  • func (s *Server) CreateVPS(ctx context.Context, createCfg providers.VPSCreateConfig) (*providers.VPS, error)
  • func (s *Server) Deploy(sourceDir string) (*deploy.DeployResult, error)
  • func (s *Server) Destroy(ctx context.Context) error
  • func (s *Server) Exec(cmd string) (string, error)
  • func (s *Server) Provision(ctx context.Context) error
  • func (s *Server) Status() (string, error)
• type ServerConfig
  • func LoadConfig(path string) (*ServerConfig, error)

Types

type ClusterClient

type ClusterClient struct {
	// contains filtered or unexported fields
}

func (*ClusterClient) Logs

func (c *ClusterClient) Logs(pod string, follow bool) (string, error)

func (*ClusterClient) Nodes

func (c *ClusterClient) Nodes() (string, error)

func (*ClusterClient) Pods

func (c *ClusterClient) Pods(namespace string) (string, error)

func (*ClusterClient) Top

func (c *ClusterClient) Top() (string, error)

type Config

type Config struct {
	Host    string `yaml:"host"`
	User    string `yaml:"user"`
	SSHKey  string `yaml:"ssh_key"`
	SSHPort int    `yaml:"ssh_port"`
	Mode    string `yaml:"mode"`
}

type Mode

type Mode string

const (
	ModeK3s    Mode = "k3s"
	ModeDocker Mode = "docker"
	ModeBare   Mode = "bare"
)

type Server

type Server struct {
	// contains filtered or unexported fields
}

func New

func New(cfg ServerConfig) *Server

func (*Server) Close

func (s *Server) Close() error

func (*Server) Cluster

func (s *Server) Cluster() *ClusterClient

func (*Server) CreateVPS

func (s *Server) CreateVPS(ctx context.Context, createCfg providers.VPSCreateConfig) (*providers.VPS, error)

func (*Server) Deploy

func (s *Server) Deploy(sourceDir string) (*deploy.DeployResult, error)

func (*Server) Destroy

func (s *Server) Destroy(ctx context.Context) error

func (*Server) Exec

func (s *Server) Exec(cmd string) (string, error)

func (*Server) Provision

func (s *Server) Provision(ctx context.Context) error

func (*Server) Status

func (s *Server) Status() (string, error)

type ServerConfig

type ServerConfig struct {
	Host       string
	User       string
	SSHKey     string
	SSHPort    int
	Mode       Mode
	CrowdSec   bool
	Kubeconfig string
	Context    string
	MergeKube  bool
	Provider   providers.Provider
}

func LoadConfig

func LoadConfig(path string) (*ServerConfig, error)