diff --git a/getting-started/edera-installer/.gitignore b/getting-started/edera-installer/.gitignore new file mode 100644 index 0000000..3f62406 --- /dev/null +++ b/getting-started/edera-installer/.gitignore @@ -0,0 +1 @@ +key.json diff --git a/getting-started/edera-installer/Makefile b/getting-started/edera-installer/Makefile new file mode 100644 index 0000000..56c80b1 --- /dev/null +++ b/getting-started/edera-installer/Makefile @@ -0,0 +1,139 @@ +.PHONY: help deploy configure test test-standalone verify clean + +# Default target +help: + @echo "Edera Manual Installation" + @echo "" + @echo "Available targets:" + @echo " deploy - Install Edera on a target node (requires INSTALLER_IP)" + @echo " test-standalone - Test standalone installation (no Kubernetes)" + @echo " configure - Apply RuntimeClass and label nodes (Kubernetes)" + @echo " test - Test Kubernetes deployment with a test workload" + @echo " verify - Verify Kubernetes cluster configuration" + @echo " clean - Clean up test resources" + @echo "" + @echo "Environment variables:" + @echo " INSTALLER_IP - Required. IP address of the target node" + @echo " SSH_USER - SSH username (default: root)" + @echo " SSH_KEY - Path to SSH private key (optional)" + @echo "" + @echo "Quick start (standalone):" + @echo " 1. Save your GAR key as key.json" + @echo " 2. INSTALLER_IP= make deploy" + @echo " 3. INSTALLER_IP= make test-standalone" + @echo "" + @echo "Quick start (Kubernetes):" + @echo " 1. Save your GAR key as key.json" + @echo " 2. INSTALLER_IP= make deploy" + @echo " 3. make configure" + @echo " 4. make test" + @echo "" + @echo "Example with SSH key (e.g., for EC2):" + @echo " INSTALLER_IP= SSH_USER=ubuntu SSH_KEY=~/.ssh/my-key.pem make deploy" + +# Check that key.json exists +check-key: + @if [ ! -f key.json ]; then \ + echo "Error: key.json not found!"; \ + echo "Please save your Google Artifact Registry key as key.json"; \ + exit 1; \ + fi + +# Deploy Edera to a node +deploy: check-key + @if [ -z "$(INSTALLER_IP)" ]; then \ + echo "Error: INSTALLER_IP is not set"; \ + echo "Usage: INSTALLER_IP= make deploy"; \ + exit 1; \ + fi + @echo "Installing Edera on $(INSTALLER_IP)..." + ./scripts/install.sh + @echo "" + @echo "Installation complete!" + @echo "" + @echo "Next steps:" + @echo " make configure # Apply RuntimeClass and label nodes" + @echo " make test # Test the deployment" + +# Test standalone installation (no Kubernetes) +test-standalone: + @if [ -z "$(INSTALLER_IP)" ]; then \ + echo "Error: INSTALLER_IP is not set"; \ + echo "Usage: INSTALLER_IP= make test-standalone"; \ + exit 1; \ + fi + @echo "Testing Edera installation on $(INSTALLER_IP)..." + @SSH_OPTS=""; \ + if [ -n "$(SSH_KEY)" ]; then SSH_OPTS="-i $(SSH_KEY)"; fi; \ + SSH_USER=$${SSH_USER:-root}; \ + echo ""; \ + echo "Edera version:"; \ + ssh $$SSH_OPTS $${SSH_USER}@$(INSTALLER_IP) "sudo protect --version"; \ + echo ""; \ + echo "Edera services:"; \ + ssh $$SSH_OPTS $${SSH_USER}@$(INSTALLER_IP) "sudo systemctl status protect-daemon --no-pager | head -5"; \ + echo ""; \ + echo "Zone list:"; \ + ssh $$SSH_OPTS $${SSH_USER}@$(INSTALLER_IP) "sudo protect zone list"; \ + echo ""; \ + echo "Edera is installed and running!" + +# Configure kubectl with RuntimeClass +configure: + @echo "Applying Edera RuntimeClass..." + kubectl apply -f https://public.edera.dev/kubernetes/runtime-class.yaml + @echo "" + @echo "RuntimeClass applied. Label your nodes with:" + @echo " kubectl label nodes runtime=edera" + @echo "" + @echo "Or label all nodes:" + @echo " kubectl label nodes --all runtime=edera" + +# Test the deployment +test: + @echo "Testing Edera deployment..." + @echo "" + @echo "Node status:" + kubectl get nodes -o wide + @echo "" + @echo "Node labels (checking for runtime=edera):" + kubectl get nodes --show-labels | grep runtime=edera || echo "No nodes with runtime=edera label found" + @echo "" + @echo "RuntimeClass status:" + kubectl get runtimeclass edera -o wide || echo "RuntimeClass not found" + @echo "" + @echo "Deploying test workload..." + kubectl apply -f kubernetes/test-workload.yaml + @echo "" + @echo "Waiting for test pod to be ready..." + kubectl wait --for=condition=ready pod/edera-test-pod -n edera-test --timeout=300s + @echo "" + @echo "Test pod is running!" + @echo "" + @echo "Test results:" + kubectl get pods -n edera-test -o wide + @echo "" + @echo "Verifying pod is using Edera runtime:" + @kubectl get pod edera-test-pod -n edera-test -o jsonpath="{.spec.runtimeClassName}" + @echo "" + @echo "" + @echo "Success! Your node is running with Edera protection." + +# Verify the deployment +verify: + @echo "Verifying Edera installation..." + @echo "" + @echo "Cluster nodes:" + kubectl get nodes + @echo "" + @echo "Edera RuntimeClass:" + kubectl get runtimeclass edera + @echo "" + @echo "Test workload:" + kubectl get pods -n edera-test + +# Clean up test resources +clean: + @echo "Cleaning up test resources..." + kubectl delete -f kubernetes/test-workload.yaml --ignore-not-found=true + @echo "Test resources cleaned up" diff --git a/getting-started/edera-installer/README.md b/getting-started/edera-installer/README.md new file mode 100644 index 0000000..07706ea --- /dev/null +++ b/getting-started/edera-installer/README.md @@ -0,0 +1,250 @@ +# Edera Manual Installation - Complete Example + +This example provides scripts for installing Edera on any Linux node. It's designed for users who want direct control over the installation process or need to install Edera on existing infrastructure. + +## What This Example Provides + +- **Installation Scripts**: Automated scripts to install Edera on remote nodes +- **RuntimeClass Configuration**: Kubernetes RuntimeClass for Edera pods +- **Test Workload**: Sample nginx pod using Edera runtime +- **Makefile Automation**: Simple commands for deploy, test, and cleanup + +## Quick Start + +### Standalone (no Kubernetes) + +```bash +# 1. Save your GAR key as key.json +cp /path/to/your/key.json . + +# 2. Install Edera on your node +INSTALLER_IP= make deploy + +# 3. Verify installation (after reboot completes) +INSTALLER_IP= make test-standalone +``` + +### With Kubernetes + +```bash +# 1. Save your GAR key as key.json +cp /path/to/your/key.json . + +# 2. Install Edera on your node +INSTALLER_IP= make deploy + +# 3. Configure Kubernetes RuntimeClass +make configure + +# 4. Test with a pod +make test +``` + +### Cloud instances (EC2, GCE, etc.) + +For cloud instances that use non-root SSH users: + +```bash +INSTALLER_IP= SSH_USER=ubuntu SSH_KEY=~/.ssh/my-key.pem make deploy +INSTALLER_IP= SSH_USER=ubuntu SSH_KEY=~/.ssh/my-key.pem make test-standalone +``` + +## Prerequisites + +Before starting, ensure you have: + +1. **Edera Access**: Contact [support@edera.dev](mailto:support@edera.dev) for: + - Google Artifact Registry (GAR) key for pulling Edera images + +2. **SSH Access**: Root SSH access to your target node(s) + +3. **Container Runtime**: Docker or nerdctl installed on the target node + +4. **kubectl** (optional): For Kubernetes deployments + + ```bash + kubectl version --client + ``` + +## Configuration + +### Required: GAR Key + +Save your Google Artifact Registry key as `key.json` in this directory: + +```bash +cp /path/to/your/key.json . +``` + +### Target Node Requirements + +The target node must have: + +- Linux operating system +- Root SSH access +- Docker or nerdctl installed +- Network access to `us-central1-docker.pkg.dev` + +## Deployment + +### Step-by-Step + +```bash +# 1. Install Edera on a node +INSTALLER_IP= make deploy + +# 2. Configure Kubernetes RuntimeClass +make configure + +# 3. Label your nodes +kubectl label nodes runtime=edera + +# 4. Test the deployment +make test +``` + +### Installing Multiple Nodes + +Run the deploy command for each node: + +```bash +INSTALLER_IP=192.168.1.10 make deploy +INSTALLER_IP=192.168.1.11 make deploy +INSTALLER_IP=192.168.1.12 make deploy +``` + +### Manual Installation + +If you prefer not to use the Makefile: + +```bash +# Copy files to target node +scp key.json root@:/tmp/ +scp scripts/edera-install.sh root@:~ + +# SSH to node and run installer +ssh root@ 'chmod +x ~/edera-install.sh && ~/edera-install.sh' + +# Apply RuntimeClass (Kubernetes only) +kubectl apply -f https://public.edera.dev/kubernetes/runtime-class.yaml + +# Label nodes +kubectl label nodes runtime=edera + +# Deploy test workload +kubectl apply -f kubernetes/test-workload.yaml +``` + +## Verification + +### Automatic Verification + +```bash +make verify +``` + +This checks: + +- Cluster nodes are online +- RuntimeClass is configured +- Test workload is running + +### Manual Verification + +```bash +# Check cluster status +kubectl get nodes -o wide + +# Verify Edera RuntimeClass +kubectl get runtimeclass edera + +# Check node labels +kubectl get nodes --show-labels | grep runtime=edera + +# Verify test pod +kubectl get pods -n edera-test +kubectl get pod edera-test-pod -n edera-test -o jsonpath="{.spec.runtimeClassName}" +``` + +## Cleanup + +### Remove Test Resources Only + +```bash +make clean +``` + +## Troubleshooting + +### Common Issues + +#### SSH Permission Denied + +If you see `Permission denied (publickey)`, specify the SSH user and key: + +```bash +INSTALLER_IP= SSH_USER=ubuntu SSH_KEY=~/.ssh/my-key.pem make deploy +``` + +Common SSH users by platform: +- **EC2 Ubuntu**: `ubuntu` +- **EC2 Amazon Linux**: `ec2-user` +- **GCE**: Your Google account username +- **Azure**: The admin username you specified + +#### Make deploy shows "Error 255" + +This is expected. The installer reboots the node when complete, which closes the SSH connection. Wait 1-2 minutes for the node to come back online, then run `make test-standalone` to verify. + +#### Installation Fails + +- Verify SSH access: `ssh -i @` +- Check container runtime: `ssh -i @ 'docker --version || nerdctl --version'` +- Verify GAR key is valid and has appropriate permissions + +#### Pod Stuck in Pending (Kubernetes) + +```bash +kubectl describe pod edera-test-pod -n edera-test +``` + +Check for: + +- Missing `runtime=edera` labels on nodes +- RuntimeClass not installed +- Node capacity issues + +#### Container Login Fails + +- Verify `key.json` is a valid GAR service account key +- Check network access to `us-central1-docker.pkg.dev` + +### Getting Help + +1. **Check Logs**: + + ```bash + kubectl logs edera-test-pod -n edera-test + ``` + +2. **Describe Resources**: + + ```bash + kubectl describe pod edera-test-pod -n edera-test + kubectl describe node + ``` + +3. **Contact Support**: [support@edera.dev](mailto:support@edera.dev) + +## Next Steps + +- Deploy your own applications using `runtimeClassName: edera` +- Explore [Edera documentation](https://docs.edera.dev) +- Check out other examples in this repository + +## Files + +- `Makefile` - Automation commands +- `scripts/install.sh` - Remote installation wrapper +- `scripts/edera-install.sh` - Node installation script +- `kubernetes/test-workload.yaml` - Test pod configuration diff --git a/getting-started/edera-installer/kubernetes/test-workload.yaml b/getting-started/edera-installer/kubernetes/test-workload.yaml new file mode 100644 index 0000000..7441add --- /dev/null +++ b/getting-started/edera-installer/kubernetes/test-workload.yaml @@ -0,0 +1,26 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: edera-test +--- +apiVersion: v1 +kind: Pod +metadata: + name: edera-test-pod + namespace: edera-test + labels: + app: edera-test +spec: + runtimeClassName: edera + containers: + - name: nginx + image: nginx:1.25.3 + ports: + - containerPort: 80 + resources: + requests: + memory: "64Mi" + cpu: "250m" + limits: + memory: "128Mi" + cpu: "500m" diff --git a/getting-started/edera-installer/scripts/edera-install.sh b/getting-started/edera-installer/scripts/edera-install.sh new file mode 100755 index 0000000..3b32bb0 --- /dev/null +++ b/getting-started/edera-installer/scripts/edera-install.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# +# Edera Installer - Node Installation Script +# +# This script runs on the target node to install Edera. +# It automatically detects docker or nerdctl and uses whichever is available. +# + +set -e + +# Detect container client (docker or nerdctl) +CLIENT="" +for cmd in docker nerdctl; do + if which $cmd &>/dev/null; then + CLIENT=$(which $cmd) + break + fi +done + +if [ -z "$CLIENT" ]; then + echo "Error: No container client found (docker or nerdctl required)" + exit 1 +fi + +echo "Using container client: $CLIENT" + +# Edera version to install +TAG="v1.5.1" + +echo "Installing Edera $TAG..." + +# Login to Google Artifact Registry +$CLIENT login us-central1-docker.pkg.dev -u _json_key --password-stdin ./scripts/install.sh +# +# Environment variables: +# INSTALLER_IP - Required. IP address of the target node +# SSH_USER - SSH username (default: root) +# SSH_KEY - Path to SSH private key (optional) +# + +set -e + +# Check that INSTALLER_IP is set +if [ -z "$INSTALLER_IP" ]; then + echo "Error: INSTALLER_IP is not set" + echo "Usage: INSTALLER_IP= ./scripts/install.sh" + echo "" + echo "Environment variables:" + echo " SSH_USER - SSH username (default: root)" + echo " SSH_KEY - Path to SSH private key (optional)" + exit 1 +fi + +# Check that key.json exists +if [ ! -f "key.json" ]; then + echo "Error: key.json not found" + echo "Please save your Google Artifact Registry key as key.json" + exit 1 +fi + +# Set defaults +SSH_USER=${SSH_USER:-root} +SSH_OPTS="" +if [ -n "$SSH_KEY" ]; then + SSH_OPTS="-i $SSH_KEY" +fi + +echo "Installing Edera on $INSTALLER_IP (user: $SSH_USER)..." + +# Copy files to target node +scp $SSH_OPTS ./key.json ${SSH_USER}@${INSTALLER_IP}:/tmp/ +scp $SSH_OPTS ./scripts/edera-install.sh ${SSH_USER}@${INSTALLER_IP}:~ + +# Run the installer (use sudo if not root) +if [ "$SSH_USER" = "root" ]; then + ssh $SSH_OPTS "${SSH_USER}@${INSTALLER_IP}" 'chmod +x ~/edera-install.sh && ~/edera-install.sh' +else + ssh $SSH_OPTS "${SSH_USER}@${INSTALLER_IP}" 'chmod +x ~/edera-install.sh && sudo ~/edera-install.sh' +fi + +echo "" +echo "Installation complete on $INSTALLER_IP" diff --git a/getting-started/eks-terraform/README.md b/getting-started/eks-terraform/README.md index af12413..3c65a3a 100644 --- a/getting-started/eks-terraform/README.md +++ b/getting-started/eks-terraform/README.md @@ -78,7 +78,7 @@ cluster_version = "1.32" region = "us-west-2" # or us-gov-west-1 for GovCloud # Node group settings -instance_types = ["t3.medium"] +instance_types = ["m5n.xlarge"] desired_size = 2 min_size = 1 max_size = 3 diff --git a/getting-started/eks-terraform/terraform.tfvars.example b/getting-started/eks-terraform/terraform.tfvars.example index 12c35c7..5f60b5a 100644 --- a/getting-started/eks-terraform/terraform.tfvars.example +++ b/getting-started/eks-terraform/terraform.tfvars.example @@ -13,7 +13,7 @@ cluster_version = "1.32" region = "us-west-2" # Optional: Node group configuration -instance_types = ["t3.medium"] +instance_types = ["m5n.xlarge"] desired_size = 2 min_size = 1 max_size = 3 diff --git a/getting-started/eks-terraform/variables.tf b/getting-started/eks-terraform/variables.tf index 76251aa..b376ee8 100644 --- a/getting-started/eks-terraform/variables.tf +++ b/getting-started/eks-terraform/variables.tf @@ -25,7 +25,7 @@ variable "cluster_version" { variable "instance_types" { description = "List of instance types associated with the EKS Node Group" type = list(string) - default = ["t3.medium"] + default = ["m5n.xlarge"] } variable "min_size" {