# Installing Edera with AWS EKS

This guide walks you through a fast setup of Edera on AWS EKS. For users who want to get up and running quickly, we provide a **complete, tested Terraform example** that creates everything from scratch.

🚀 **Ready to deploy?** Jump to our [complete EKS example](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform) for a production-ready deployment.

## Quick start with complete example

The fastest way to get started is with our complete, tested example. Before running, make sure you’re logged into AWS:

```bash
aws sso login  # or: aws configure
aws sts get-caller-identity  # verify credentials are working
```

Then:

```bash
git clone https://github.com/edera-dev/learn.git
cd learn/getting-started/eks-terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with the Edera account ID and instance type (see below)
make deploy
make test
```

**That’s it.** Your EKS cluster with Edera protection will be ready in ~15 minutes.

### Available make commands

The example includes a comprehensive set of make commands:

- `make deploy` - Deploy the complete EKS cluster with Edera
- `make test` - Test and verify the deployment with automated checks
- `make verify` - Quick verification of cluster status
- `make clean` - Remove only test resources (keeps cluster running)
- `make delete` - Destroy the entire infrastructure (with confirmation)
- `make destroy` - Alias for delete (same functionality)

**Quick cleanup:** When you’re done testing, simply run `make delete` to tear everything down safely.

## Prerequisites

Before you begin, ensure you have:

- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed and authenticated (`aws sts get-caller-identity` should return your account info)
- [Terraform](https://terraform.io/) or [OpenTofu](https://opentofu.org/) (version 1.3 or later)
- [kubectl](https://kubernetes.io/docs/tasks/tools/) for testing and verification
- **Edera account access** - Contact [support@edera.dev](mailto:support@edera.dev) to get the Edera AWS account ID

The example automatically detects and uses either Terraform or OpenTofu—just install your preferred tool.

Edera AMIs are only available in **us-west-2** and **AWS GovCloud (US-West)**. Contact [support@edera.dev](mailto:support@edera.dev) to get access. You will need to provide your AWS account ID.

## Configuration options

The complete example supports several configuration options in `terraform.tfvars`:

### Required configuration

```hcl
# The Edera AWS account ID (provided by Edera team)
edera_account_id = "123456789012"
```

### Instance type

The instance type you choose determines which hypervisor backend Edera uses.

The backend is determined by the AMI. There are separate Xen and KVM AMIs. Select the one that matches your target backend.

ℹ️

Separate Xen and KVM AMIs are available starting in **Edera v1.10.0**. Prior releases only shipped Xen AMIs using the older naming format: `edera-protect-{version}-{os}-amazon-eks-node-{k8s version}-{build date}`.

XenKVM (Early Access)

Use the Xen AMI filter in `terraform.tfvars`. Any supported EKS instance type works:

```hcl
ami_filter      = "edera-protect-*-al2023-amazon-eks-xen-node-*"
instance_types  = ["m5n.xlarge"]
```

ℹ️

KVM support is currently in **Early Access**. It is not intended for production use and has not completed Edera’s security review. For production and Edera’s hypervisor-enforced isolation guarantees, use the Xen backend.

Use the KVM AMI filter and a KVM-capable instance type:

```hcl
ami_filter      = "edera-protect-*-al2023-amazon-eks-kvm-node-*"
instance_types  = ["m7i.xlarge"]
```

KVM requires either a **bare metal instance** or an instance type that exposes hardware virtualization (nested KVM) to the guest. Supported instance families:

**Eighth-generation Intel:** C8i, M8i, R8i, C8id, M8id, R8id, C8i-flex, M8i-flex, R8i-flex, X8i

**Seventh-generation Intel:** C7i, M7i, R7i, C7i-flex, M7i-flex, I7i

Or any `*.metal` instance type. Bare metal is preferred. Nested virtualization carries a performance penalty.

### Other optional configuration

```hcl
# Cluster settings
cluster_name    = "my-edera-cluster"
cluster_version = "1.35"
region          = "us-west-2"  # or us-gov-west-1 for GovCloud

# Node group settings
desired_size   = 2
min_size       = 1
max_size       = 3

# SSH access (disabled by default for security)
enable_ssh_access = true
ssh_key_name     = "my-ec2-keypair"
```

### SSH access to worker nodes

SSH access is **disabled by default** for security. To enable it:

1. **Create or use existing EC2 key pair:**

```bash
aws ec2 create-key-pair --key-name edera-eks-key \
     --query 'KeyMaterial' --output text > edera-eks-key.pem
chmod 400 edera-eks-key.pem
```

2. **Enable SSH in terraform.tfvars:**

```hcl
enable_ssh_access = true
ssh_key_name     = "edera-eks-key"
```

3. **Deploy/redeploy the cluster:**

```bash
make deploy  # SSH access requires node group recreation
```

4. **Connect via SSH:**

```bash
# Get node IPs
kubectl get nodes -o wide

# SSH to node
ssh -i edera-eks-key.pem ec2-user@<node-ip>
```

⚠️

**Note:** Enabling SSH access requires recreating the node group, which will cause brief downtime for workloads.

## Manual configuration (alternative approach)

If you prefer to understand the components or integrate with existing infrastructure, the sections below explain the individual pieces. However, **we strongly recommend starting with the [complete example](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform)** first.

### Verifying AMI access

Once your AWS account has been granted access by the Edera team, you can verify available AMIs. The complete example includes automation for this, but if you want to check manually:

```bash
# Set your region (us-west-2 or us-gov-west-1)
export REGION=us-west-2
export EDERA_ACCOUNT_ID=your-edera-account-id

aws ec2 describe-images --owners $EDERA_ACCOUNT_ID \
  --region $REGION \
  --query 'reverse(sort_by(Images[*].[CreationDate, ImageId, Name, State], &[0]))' \
  --output table
```

Edera AMI names follow the pattern: `edera-protect-{version}-{os}-amazon-eks-{xen|kvm}-node-{k8s version}-{build date}`

### Terraform configuration reference

For reference, here are the key components needed for EKS with Edera. **The [complete example](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform) includes all of this plus VPC, security groups, and proper configuration.**

**AMI Data Source:**

```hcl
data "aws_ami" "edera_protect" {
  owners      = [var.edera_account_id]  # The Edera account ID
  most_recent = true

filter {
    name   = "name"
    values = ["edera-protect-*-al2023-amazon-eks-xen-node-${local.cluster_version}-*"]
  }
}
```

**EKS Node Group Configuration:**

```hcl
 eks_managed_node_groups = {
  edera_protect = {
    ami_id   = data.aws_ami.edera_protect.id
    ami_type = "AL2023_x86_64_STANDARD"

# Critical: Label nodes for Edera RuntimeClass
    labels = {
      "runtime" = "edera"  # Required for pod scheduling
    }

enable_bootstrap_user_data = true
  }
}
```

🔗 **See complete configuration:** [View the full Terraform files](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform) with VPC, networking, and all required components.

## Testing and verification

The [complete example](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform) includes comprehensive automated testing and verification:

```bash
make test    # Full deployment test with automated verification
make verify  # Quick status check of existing deployment
```

### What `make test` does

The automated test performs these verification steps:

1. **Configures kubectl** for the cluster
2. **Applies Edera RuntimeClass** (Kubernetes 1.32 compatible)
3. **Verifies cluster status** and node readiness
4. **Checks node labels** for `runtime=edera`
5. **Validates RuntimeClass** configuration
6. **Deploys test workload** using Edera runtime
7. **Confirms pod scheduling** and runtime assignment
8. **Displays comprehensive results** including AMI verification

**Expected output:** ✅ Test pod running with Edera runtime protection

### Manual testing steps

If you’re configuring manually, here are the key verification steps:

**1\. Configure kubectl:**

```bash
aws eks --region $REGION update-kubeconfig --name edera-cluster
```

**2\. Apply RuntimeClass:**

```bash
kubectl apply -f https://public.edera.dev/kubernetes/runtime-class.yaml
kubectl get runtimeclass edera
```

**3\. Verify node labels:**

```bash
kubectl get nodes --show-labels | grep runtime=edera
```

**4\. Test with a pod:**

```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: edera-test
spec:
  runtimeClassName: edera
  containers:
  - name: nginx
    image: nginx:1.25.3
EOF
```

🔗 **Complete verification:** The [verification script](https://github.com/edera-dev/learn/blob/main/getting-started/eks-terraform/scripts/verify-ami.sh) in the examples repository performs comprehensive checks of your deployment.

## Troubleshooting

**Pods stuck in Pending state:**

- Check node labels: `kubectl get nodes --show-labels | grep runtime=edera`
- Verify RuntimeClass: `kubectl get runtimeclass edera`
- Check pod events: `kubectl describe pod <pod-name>`

**AMI access issues:**

- Verify the Edera account ID is correct in `terraform.tfvars`
- Ensure you’re in a supported region (us-west-2 or us-gov-west-1)
- Contact [support@edera.dev](mailto:support@edera.dev) for AMI access. You will need to provide your AWS account ID.

**KVM not available on node:**

- Verify the instance type supports nested virtualization (see [instance type](https://docs.edera.dev/guides/install/eks/#instance-type) above)
- Check `/dev/kvm` exists on the node: `ssh ec2-user@<node-ip> ls -la /dev/kvm`
- Bare metal instance types are the most reliable option for KVM

**Terraform/OpenTofu issues:**

- The example auto-detects your preferred tool (no configuration needed)
- Check version: `terraform --version` or `tofu --version` (requires 1.3+)
- Run `make plan` to preview changes before deploying

**SSH access not working:**

- Ensure `enable_ssh_access = true` and `ssh_key_name` are set in `terraform.tfvars`
- SSH access requires node group recreation: `make delete && make deploy`
- Verify EC2 key pair exists in the same region

**Need to clean up?**

- `make clean` - Removes test resources only (keeps cluster)
- `make delete` - Destroys entire infrastructure (with confirmation)

🔧 **Complete troubleshooting guide:** The [EKS example README](https://github.com/edera-dev/learn/tree/main/getting-started/eks-terraform#troubleshooting) includes comprehensive troubleshooting steps, common solutions, and verification scripts.

## Next steps

1. **Deploy your applications** using `runtimeClassName: edera` in your pod specs
2. **Explore examples** in the [learn repository](https://github.com/edera-dev/learn) for other platforms
3. **Read the docs** at [docs.edera.dev](https://docs.edera.dev/) for advanced configuration
4. **Get support** at [support@edera.dev](mailto:support@edera.dev) - we like solving problems.