gsadmin/spinifex
1
0
Fork 0
mirror of https://github.com/mulgadc/spinifex.git synced 2026-10-22 12:16:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'dev' of github.com:mulgadc/spinifex into dev

Browse Source
This commit is contained in:
Ben Duncan
2026-03-31 13:19:48 +10:00
parent b73a630f41 c283100fcf
commit ae223cdf15
11 changed files with 52 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/creating-accounts/README.md
+1 -1
View File
@@ -32,7 +32,7 @@ Spinifex supports multi-tenant account isolation. Each account gets its own IAM
## Create Account
```bash
./bin/spx admin account create --name myteam
spx admin account create --name myteam
export AWS_PROFILE=spinifex-myteam
```
docs/creating-an-environment/README.md
-110
View File
@@ -1,110 +0,0 @@
---
title: "Creating an Environment"
description: "End-to-end guide: user accounts, SSH keys, VPCs, AMIs, and launching instances."
category: "Environments"
tags:
- environment
- vpc
- ec2
- ssh
resources:
- title: "Spinifex Repository"
url: "https://github.com/mulgadc/spinifex"
- title: "Debian Cloud Images"
url: "https://cloud.debian.org/images/cloud/bookworm/latest/"
---
# Creating an Environment
> End-to-end guide: user accounts, SSH keys, VPCs, AMIs, and launching instances.
## Table of Contents
- [Overview](#overview)
- [Instructions](#instructions)
- [Troubleshooting](#troubleshooting)
---
## Overview
This guide walks through the complete workflow for creating a production-ready Spinifex environment.
## Instructions
## 1. Import SSH Key
```bash
aws ec2 import-key-pair --key-name "spinifex-key" --public-key-material fileb://~/.ssh/id_rsa.pub
```
## 2. Create VPC
```bash
aws ec2 create-vpc --cidr-block 10.200.0.0/16
export SPINIFEX_VPC="vpc-XXX"
aws ec2 create-subnet --vpc-id $SPINIFEX_VPC --cidr-block 10.200.1.0/24
export SPINIFEX_SUBNET="subnet-XXX"
```
## 3. Import AMI
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-x86_64
export SPINIFEX_AMI="ami-XXX"
```
## 4. Launch Instance
```bash
aws ec2 run-instances \
--image-id $SPINIFEX_AMI \
--instance-type t3.small \
--key-name spinifex-key \
--subnet-id $SPINIFEX_SUBNET \
--count 1
```
## 5. Connect via SSH
```bash
ps auxw | grep $INSTANCE_ID
# Look for: hostfwd=tcp:127.0.0.1:<port>-:22
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
## Troubleshooting
## Instance Stuck in Pending
Check the Spinifex daemon and QEMU logs for boot errors:
```bash
ls ~/spinifex/logs/
cat ~/spinifex/logs/spinifex.log
```
Verify the AMI exists and architecture matches your host:
```bash
aws ec2 describe-images --image-ids $SPINIFEX_AMI
```
## SSH Connection Refused
cloud-init takes 30-60 seconds to configure networking and SSH after boot. Wait and retry.
Verify the SSH port forwarding is active:
```bash
ps auxw | grep hostfwd
```
Ensure you're using the correct key and port:
```bash
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
docs/installing-spinifex-airgapped/README.md
+1 -1
View File
@@ -85,7 +85,7 @@ cp -r /mnt/usb/spinifex-source ~/Development/mulga/spinifex
cd ~/Development/mulga/spinifex && make build
```
Then follow the [Source Install](/docs/source-install) guide from Step 3 (Setup OVN) onwards.
Then follow the [Source Installation](/docs/source-installation) guide from Step 3 (Setup OVN) onwards.
## Troubleshooting
docs/installing-spinifex/README.md
+10 -2
View File
@@ -31,14 +31,14 @@ resources:
Spinifex is an open-source infrastructure platform that brings core AWS services — EC2, VPC, EBS, and S3 — to bare-metal, edge, and on-prem environments.
This guide installs Spinifex on a single server using the binary installer. For multi-server clusters, see [Multi-Node Installation](/docs/installing-spinifex-multi-node). To build from source, see [Source Install](/docs/source-install).
This guide installs Spinifex on a single server using the binary installer. For multi-server clusters, see [Multi-Node Installation](/docs/installing-spinifex-multi-node). To build from source, see [Source Installation](/docs/source-installation).
**Supported Operating Systems:**
- Ubuntu 22.04 / 24.04 / 25.10
- Debian 12 / 13
**What gets installed:**
**What Gets Installed:**
- Spinifex daemon and CLI
- QEMU/KVM for virtual machine management
@@ -75,6 +75,14 @@ sudo /usr/local/share/spinifex/setup-ovn.sh --management --wan-bridge=br-wan --w
sudo /usr/local/share/spinifex/setup-ovn.sh --management --macvlan --wan-iface=enp0s3
```
**Separating VPC tunnel traffic from WAN:** If you want Geneve tunnel traffic (inter-VM east-west) to use a dedicated interface instead of the WAN IP, add `--encap-ip=<IP>` to specify the tunnel endpoint address:
```bash
sudo /usr/local/share/spinifex/setup-ovn.sh --management --encap-ip=10.0.0.1
```
This is recommended for production and required in multi-node deployments. See [Multi-Node Installation](/docs/installing-spinifex-multi-node) for details.
## Step 3. Initialize
```bash
docs/launching-instances/README.md
+7 -3
View File
@@ -1,7 +1,7 @@
---
title: "Launching Instances"
description: "Launch, manage, and connect to EC2-compatible virtual machines on Spinifex."
category: "Environments"
category: "Compute"
tags:
- ec2
- instances
@@ -125,11 +125,15 @@ aws ec2 describe-instance-types \
## SSH (Development)
In development mode, find the QEMU port forward and connect via localhost:
```bash
ps auxw | grep $INSTANCE_ID
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
For production SSH via public IPs, see [Setting Up Your Cluster](/docs/setting-up-your-cluster).
## Troubleshooting
### Instance Fails to Boot
@@ -144,8 +148,8 @@ aws ec2 describe-images --image-ids $SPINIFEX_AMI
If the AMI is for a different architecture (e.g. arm64 on an x86_64 host), import the correct image:
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-x86_64
spx admin images list
spx admin images import --name debian-12-x86_64
```
### Cannot SSH Into Instance
docs/placement-groups/README.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: "Placement Groups"
description: "Create and manage spread and cluster placement groups for hardware-level instance placement control."
category: "Environments"
category: "Compute"
tags:
- ec2
- placement
@@ -99,7 +99,7 @@ aws ec2 delete-placement-group --group-name my-spread-group
Not enough distinct physical hosts for a spread launch. Reduce `--count` or terminate existing instances to free host slots:
```bash
./bin/spx admin nodes list
spx admin nodes list
```
### Cannot Delete Placement Group
docs/setting-up-your-cluster/README.md
+1 -1
View File
@@ -35,7 +35,7 @@ resources:
This guide assumes Spinifex is already installed and running. If not, follow one of the installation guides first:
- [Binary Install (Single Node)](/docs/installing-spinifex)
- [Multi-Node Installation](/docs/installing-spinifex-multi-node)
- [Source Install](/docs/source-install)
- [Source Installation](/docs/source-installation)
## Instructions
docs/source-install/README.md → docs/source-installation/README.md
+11 -11
View File
@@ -1,5 +1,5 @@
---
title: "Source Install"
title: "Source Installation"
description: "Build Spinifex from source for development, custom builds, or contributing."
category: "Getting Started"
tags:
@@ -13,7 +13,7 @@ resources:
url: "https://go.dev/dl/"
---
# Source Install
# Source Installation
> Build Spinifex from source for development, custom builds, or contributing.
@@ -57,15 +57,7 @@ cd spinifex
Confirm `./bin/spx` exists.
## Step 3. Initialize
```bash
sudo ./bin/spx admin init --node node1 --nodes 1
```
Save the admin credentials printed during init.
## Step 4. Setup OVN
## Step 3. Setup OVN
If your WAN interface is already a bridge (e.g. `br-wan`), setup-ovn.sh auto-detects it:
@@ -83,6 +75,14 @@ If your WAN is a physical NIC, choose one:
./scripts/setup-ovn.sh --management --macvlan --wan-iface=enp0s3
```
## Step 4. Initialize
```bash
sudo ./bin/spx admin init --node node1 --nodes 1
```
Save the admin credentials printed during init.
## Step 5. Start Services
```bash
docs/spinifex-admin-cli/README.md
+8 -8
View File
@@ -27,7 +27,7 @@ resources:
The `spx` binary is the central administration tool for managing your Spinifex infrastructure. It provides commands for cluster initialization, account management, node operations, VM lifecycle, and service control.
**Binary location:** `~/Development/mulga/spinifex/bin/spx`
**Binary location:** `/usr/local/bin/spx` (binary install) or `~/Development/mulga/spinifex/bin/spx` (source install)
All services in the Spinifex platform are managed through this single binary.
@@ -36,14 +36,14 @@ All services in the Spinifex platform are managed through this single binary.
## Account Management
```bash
./bin/spx admin account create --name myteam
spx admin account create --name myteam
export AWS_PROFILE=spinifex-myteam
```
## Node Management
```bash
./bin/spx get nodes
spx get nodes
```
```
@@ -56,20 +56,20 @@ node3 Ready 127.0.0.3 ap-southeast-2 ap-southeast-2a 2m 0
## Monitor Resources
```bash
./bin/spx top nodes
spx top nodes
```
## Image Management
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-arm64
spx admin images list
spx admin images import --name debian-12-arm64
```
## Cluster Shutdown
```bash
./bin/spx admin cluster shutdown
spx admin cluster shutdown
```
## Troubleshooting
@@ -79,7 +79,7 @@ node3 Ready 127.0.0.3 ap-southeast-2 ap-southeast-2a 2m 0
The binary may not be executable. Fix permissions:
```bash
chmod +x ./bin/spx
chmod +x /usr/local/bin/spx
```
If you get permission errors during operations, ensure you're running with appropriate privileges. Some OVN and networking commands require `sudo`.
docs/vpc-networking/README.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: "VPC Networking"
description: "How Spinifex implements AWS-compatible VPC networking with public and private subnets, security groups, and Elastic IPs using OVN."
category: "Environments"
category: "Compute"
tags:
- vpc
- networking
scripts/setup.sh
+10 -6
View File
@@ -341,13 +341,17 @@ print_summary() {
echo " Next steps:"
echo ""
echo " 1. Setup OVN networking:"
echo " sudo /usr/local/share/spinifex/setup-ovn.sh --management"
echo " # If WAN is a physical NIC (not a bridge), add:"
echo " # --wan-bridge=br-wan --wan-iface=<WAN_NIC> (dedicated WAN NIC)"
echo " # --macvlan --wan-iface=<WAN_NIC> (single-NIC, SSH-safe)"
echo " If your WAN interface is already a bridge (e.g. br-wan):"
echo " sudo /usr/local/share/spinifex/setup-ovn.sh --management"
echo ""
echo " 2. Initialize a region:"
echo " sudo spx admin init --region <region> --az <az> --node node1 --nodes 1"
echo " If your WAN is a physical NIC:"
echo " # Dedicated WAN NIC (not your SSH connection):"
echo " sudo /usr/local/share/spinifex/setup-ovn.sh --management --wan-bridge=br-wan --wan-iface=eth1"
echo " # Single-NIC host (SSH-safe macvlan):"
echo " sudo /usr/local/share/spinifex/setup-ovn.sh --management --macvlan --wan-iface=enp0s3"
echo ""
echo " 2. Initialize:"
echo " sudo spx admin init --node node1 --nodes 1"
echo ""
echo " 3. Start services:"
echo " sudo systemctl start spinifex.target"