sdk_ops

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2026 License: MIT Imports: 14 Imported by: 0

README

Natuleadan SDK OPS


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


A CLI tool and Go SDK 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, cluster management via kubectl, and cloud resource management across providers.

1. Install

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

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

2. Quick Start

2.1 Register a node
sdk-ops config add-node 192.168.1.100 --user root --key ~/.ssh/id_ed25519
2.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
sdk-ops infra init --provider cubepath --plan gp.nano --location us-mia-1  # Create + provision
2.3 Check the cluster
sdk-ops infra status 192.168.1.100
2.4 Deploy a service
sdk-ops deploy push ./my-service --node 192.168.1.100
sdk-ops deploy push ./my-service --all              # deploy to all nodes
2.5 Operate the cluster
sdk-ops cluster nodes
sdk-ops cluster pods
sdk-ops cluster scale deploy/my-app --replicas 5
2.6 Manage firewall
sdk-ops infra firewall open 8080 --node 192.168.1.100
sdk-ops infra firewall list --node 192.168.1.100
2.7 Backup and restore
sdk-ops infra backup 192.168.1.100
sdk-ops infra restore 192.168.1.100 ./backup.tar.gz

3. Features

Category Feature Description
Provision infra init Harden + install Docker/k3s from zero
infra join Join a worker to k3s cluster
infra status Show server health and installed components
infra remove Uninstall sdk-ops from a server
infra backup Backup all services from a node
infra restore Restore services from a backup file
infra firewall Open/close/list nftables rules
infra cert Install TLS certs via Caddy (Let's Encrypt)
infra logs Install Promtail to ship logs to Loki
infra alerts Install Alertmanager (Slack, Email, Telegram)
Operations node list List registered nodes
node info Real-time dashboard (CPU, RAM, disk, k3s)
node top Interactive htop via SSH
node exec Run a command remotely (single or --all)
Deploy deploy push Build + upload + deploy a service with auto-rollback
deploy push --all Deploy to all registered nodes in parallel
deploy push --sops-key Auto-decrypt service.yaml with sops
deploy encrypt Encrypt a service.yaml with sops
deploy decrypt Decrypt a sops-encrypted file
service status/logs/restart Manage deployed services
service rollback Rollback to previous version
service versions List deployed versions
Cluster cluster nodes/pods/services kubectl wrappers (16 commands)
cluster top kubectl top nodes + pods
cluster logs <pod> kubectl logs -f
cluster scale deploy --replicas N kubectl scale
Config config init/add-node/list-nodes/remove-node Manage ~/.sdk-ops/config.yaml
config set-credentials Save provider credentials to file
Provider API CubePath, Hetzner, DO, Vultr, AWS Create/destroy/list VPS, K8s, LB, DNS, SSH keys via API
provider ssh-key Upload/list/delete SSH keys on providers
provider vps export Export VPS as Terraform HCL

4. Use as Go SDK

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

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

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

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

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

// Backup / Restore
s.BackupServices(".")
s.RestoreServices("./backup.tar.gz")

// Cluster operations
s.Cluster().Nodes()
s.Cluster().Pods("")
s.Cluster().Services("")
s.Cluster().Deployments("")
s.Cluster().Top()
s.Cluster().Scale("deploy/my-app", 5)

5. Init Flags

Flag Default Description
--mode k3s k3s, docker, or bare
--ssh-port 0 Migrate SSH to custom port (0 = keep port 22)
--monitor false Install Prometheus node_exporter
--crowdsec false Install CrowdSec WAF/IPS
--lock-root false Lock root password after creating sdkops user
--logs "" Install Promtail, ship logs to Loki URL
--alerts "" Install Alertmanager with Slack webhook
--cloud-init false Use cloud-init instead of SSH-based provisioning
--provider "" Create VPS via provider API first
--plan gp.nano VPS plan (provider)
--location us-mia-1 VPS location (provider)

6. Deploy Flow

Local (Mac ARM)                        VPS (x86_64)
─────                                   ─────
1. go build (linux/amd64)               docker login (auto)
2. docker buildx + push ──registry──→   docker pull
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

7. 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
docs/provider-credentials.md Provider credential setup
docs/known-issues.md Known limitations and workarounds
AGENTS.md AI assistant guide
cluster nodes/pods/services/top/logs/scale (16 kubectl commands)

8. Examples

8.1 Provision a VPS via provider + CLI
# Create VPS via CubePath, then harden + install k3s automatically
sdk-ops infra init --provider cubepath \
  --plan gp.nano \
  --location us-mia-1 \
  --template ubuntu-24 \
  --ssh-key-ids 421 \
  --api-key "${CUBEPATH_API_KEY}"
8.2 Provision via YAML + Go SDK

Create server.yaml:

provider: cubepath
api_key: "${CUBEPATH_API_KEY}"
project_id: 4601
plan: gp.nano
location: us-mia-1
template: ubuntu-24
ssh_key_ids: [421]

Then run with Go:

cfg, _ := ops.LoadConfig("server.yaml")
s := ops.New(*cfg)
s.Provision(ctx)
8.3 Firewall management
sdk-ops infra firewall open 9090 --node 192.168.1.100
sdk-ops infra firewall close 9090 --node 192.168.1.100
sdk-ops infra firewall list --node 192.168.1.100
8.4 TLS certificate via Caddy
sdk-ops infra cert install \
  --domain example.com \
  --email admin@example.com \
  --node 192.168.1.100

# Use Let's Encrypt staging for testing
sdk-ops infra cert install \
  --domain example.com \
  --email admin@example.com \
  --staging \
  --node 192.168.1.100
8.5 Log shipping with Promtail
sdk-ops infra logs install \
  --node 192.168.1.100 \
  --loki http://loki.example.com:3100
8.6 Alerting with Alertmanager
# Slack
sdk-ops infra alerts install \
  --node 192.168.1.100 \
  --slack https://hooks.slack.com/...

# Telegram
sdk-ops infra alerts install \
  --node 192.168.1.100 \
  --bot-token 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 \
  --chat-id -1001234567890

# Custom alert rules
sdk-ops infra alerts rule add ./rules.yml --node 192.168.1.100
8.7 Deploy with secrets
# Encrypt service.yaml with age key
sdk-ops deploy encrypt service.yaml --age-key age1...

# Deploy with auto-decrypt
sdk-ops deploy push ./my-service --node 192.168.1.100 --sops-key age1...
8.8 Multi-node deploy
# Deploy to all registered nodes in parallel
sdk-ops deploy push ./my-service --all
8.9 SSH key management on providers
# Upload your public key
sdk-ops provider ssh-key upload my-key --pub-key ~/.ssh/id_ed25519.pub

# List keys
sdk-ops provider ssh-key list

# Delete a key
sdk-ops provider ssh-key delete 123
8.10 Export to Terraform
sdk-ops provider vps export <vps-id> --provider cubepath
8.11 Save credentials to file
export CUBEPATH_API_KEY="your-key"
sdk-ops config set-credentials
# → Credentials saved to ~/.sdk-ops/credentials.yaml
8.12 Managed Kubernetes
# Create a 2-node managed K8s cluster
sdk-ops provider k8s create --provider cubepath \
  --name prod-cluster \
  --location us-mia-1 \
  --node-plan gp.micro \
  --nodes 2

# Get kubeconfig and use it
sdk-ops provider k8s kubeconfig <cluster-uuid> > kubeconfig.yaml
kubectl --kubeconfig kubeconfig.yaml get nodes

# Delete the cluster
sdk-ops provider k8s delete <cluster-uuid>

9. Project Structure

├── cmd/sdk-ops/              # CLI entrypoint (Cobra)
│   ├── main.go           # Root command, version, newSSHClient helper
│   ├── infra.go          # infra init/join/status/remove/backup/restore/firewall/cert/logs/alerts
│   ├── node.go           # node list/info/top/exec (--all)
│   ├── deploy.go         # deploy push/encrypt/decrypt + service status/logs/restart/rollback/versions
│   ├── cluster.go        # cluster (16 kubectl wrappers)
│   ├── config.go         # config init/add-node/list-nodes/remove-node/set-credentials
│   ├── provider.go       # provider vps/k8s/lb/dns/ssh-key
│   └── backup.go         # backup create/restore (top-level)
├── ssh/                  # SSH client abstraction (public SDK)
├── hardening/            # VPS hardening (public SDK)
│   ├── apply.go          # Orchestrator (calls steps in order)
│   ├── steps.go          # Individual hardening steps + node_exporter
│   ├── firewall.go       # FirewallOpen/Close/List via nftables
│   └── hconfig.go        # YAML config export/import
├── cloudinit/            # Cloud-init user-data generation
├── docker/               # Docker install + compose (public SDK)
├── k3s/                  # k3s install + join (public SDK)
├── deploy/               # Build + push + deploy engine (public SDK)
│   ├── upload.go         # Tar/SSH upload, version management, rollback
│   ├── run.go            # Service lifecycle (status, logs, restart, health check)
│   ├── backup.go         # Backup/restore services
│   ├── tls.go            # Caddy TLS cert install
│   ├── logging.go        # Promtail log shipper install
│   └── alerting.go       # Alertmanager install
├── monitor/              # Node dashboard + metrics (public SDK)
├── terraform/            # Terraform HCL generation (export)
├── secrets/              # sops encryption/decryption helpers
├── providers/            # Multi-provider interface + implementations
│   ├── provider.go       # Provider interface (21 methods)
│   ├── types.go          # VPS, K8s, LB, DNS, BareMetal, SSHKey structs
│   ├── credentials.go    # Credential file loader
│   ├── cubepath/         # CubePath (raw HTTP)
│   ├── hetzner/          # Hetzner (hcloud-go + raw HTTP)
│   ├── digitalocean/     # DigitalOcean (godo)
│   ├── vultr/            # Vultr (govultr)
│   └── aws/              # AWS (aws-sdk-go-v2)
├── server.go             # High-level ops.Server API
├── config.go             # YAML-driven config
├── docs/                 # Documentation
└── .github/              # CI/CD workflows

10. License

This project is open source under the MIT License. See LICENSE for the full text.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClusterClient 

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

func (*ClusterClient) Apply 

func (c *ClusterClient) Apply(file string) (string, error)

func (*ClusterClient) ConfigMaps 

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

func (*ClusterClient) Delete 

func (c *ClusterClient) Delete(resource, name string) (string, error)

func (*ClusterClient) Deployments 

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

func (*ClusterClient) Describe 

func (c *ClusterClient) Describe(resource, name string) (string, error)

func (*ClusterClient) Exec 

func (c *ClusterClient) Exec(pod string, cmdArgs []string) (string, error)

func (*ClusterClient) Info 

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

func (*ClusterClient) Ingresses 

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

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) Scale 

func (c *ClusterClient) Scale(resource string, replicas int32) (string, error)

func (*ClusterClient) Secrets 

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

func (*ClusterClient) Services 

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

func (*ClusterClient) Top 

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

func (*ClusterClient) Version 

func (c *ClusterClient) Version() (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) BackupServices 

func (s *Server) BackupServices(destDir string) (string, error)

func (*Server) Close 

func (s *Server) Close() error

func (*Server) Cluster 

func (s *Server) Cluster() *ClusterClient

func (*Server) CreateDNSRecord 

func (s *Server) CreateDNSRecord(ctx context.Context, zoneID string, r providers.DNSRecord) error

func (*Server) CreateK8s 

func (s *Server) CreateK8s(ctx context.Context, cfg providers.K8sCreateConfig) (*providers.K8sCluster, error)

func (*Server) CreateLB 

func (s *Server) CreateLB(ctx context.Context, cfg providers.LBCreateConfig) (*providers.LoadBalancer, error)

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) DeployPush 

func (s *Server) DeployPush(sourceDir, name 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) RestoreServices 

func (s *Server) RestoreServices(backupPath string) 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
	Monitor     bool
	LockRoot    bool
	HardSSHPort int
	Kubeconfig  string
	Context     string
	MergeKube   bool
	InsecureSSH bool
	CloudInit   bool
	Provider    providers.Provider
}

func LoadConfig 

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
sdk-ops command
aws
cubepath
digitalocean
hetzner
vultr

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.