Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/idvoretskyi/oci-code-server-arm

Deploy and manage code-server (VS Code in the browser) on Oracle Cloud Infrastructure ARM instances using K3d and Terraform.
https://github.com/idvoretskyi/oci-code-server-arm

Last synced: 10 months ago
JSON representation

Deploy and manage code-server (VS Code in the browser) on Oracle Cloud Infrastructure ARM instances using K3d and Terraform.

Awesome Lists containing this project

README 

          
# OCI Code Server ARM



Deploy code-server (VS Code in the browser) on Oracle Cloud Infrastructure (OCI) ARM instances with K3d High Availability cluster.



## Overview



This project provides Infrastructure as Code (IaC) to deploy:

- Single OCI ARM instance (VM.Standard.A1.Flex) using Always Free tier maximum specs

- K3d High Availability cluster (3 masters + 3 workers) running in Docker containers

- Code-server deployment with persistent storage and Helm charts

- Nginx Ingress Controller for external access

- Complete automation with dynamic OCI configuration



## Prerequisites



- OCI account with configured CLI/API access

- Terraform installed

- SSH key pair available in `~/.ssh/`

- OCI config file at `~/.oci/config`

- Docker (for local K3d testing - optional)



## Quick Start



1. **Deploy Infrastructure (Single VM with K3d HA):**

   ```bash

   ./deploy.sh

   ```



2. **SSH to VM and verify K3d HA cluster:**

   ```bash

   ssh $USER@

   # K3d HA cluster created automatically during boot

   kubectl get nodes  # Should show 3 masters + 3 workers

   ```



3. **Deploy Code-Server with Helm:**

   ```bash

   ./deploy-code-server.sh

   ```



4. **Access Code-Server:**

   ```bash

   # Port forward to access locally

   kubectl port-forward -n code-server svc/code-server-service 8080:8080

   ```

   Then visit: http://localhost:8080 (password: set in values.yaml)



## Architecture



### Infrastructure (Updated for K3d HA)

- **Network**: VCN with public subnet and internet gateway

- **Compute**: Single ARM instance (4 vCPUs, 24GB RAM - Always Free tier maximum)

- **Storage**: Block storage with Docker volumes for K3d persistence

- **Security**: Security lists with K3d and ingress ports



### K3d High Availability Cluster

- **K3d**: Lightweight Kubernetes in Docker containers

- **Masters**: 3 master nodes for HA with etcd quorum

- **Workers**: 3 worker nodes for load distribution

- **Load Balancer**: Built-in K3d load balancer

- **Ingress**: Nginx Ingress Controller

- **Storage**: Docker volumes for persistent data

- **Networking**: Container networking with host port mapping



### Code-Server

- **Container**: Official code-server image

- **Deployment**: Helm chart for easy configuration and upgrades

- **Storage**: Persistent workspace data across pod restarts

- **Access**: Password-based authentication with configurable security

- **Features**: Full VS Code experience in browser with extensions



## Configuration



### Infrastructure Configuration (Updated for K3d HA)

Edit `terraform/terraform.tfvars` (auto-generated by `deploy.sh`):

```hcl

# Instance configuration (Always Free tier maximum)

instance_shape           = "VM.Standard.A1.Flex"

instance_ocpus          = 4                    # Maximum for Always Free

instance_memory_in_gbs  = 24                   # Maximum for Always Free

boot_volume_size_in_gbs = 50



# K3d HA cluster configuration

k3d_nodes    = 6     # Total nodes (3 masters + 3 workers)

k3d_masters  = 3     # HA masters (odd number for quorum)

k3d_workers  = 3     # HA workers for load distribution

```



### Code-Server Configuration

Edit `helm-chart/code-server/values.yaml`:

```yaml

codeServer:

  password: "YOUR-SECURE-PASSWORD-HERE"  # CHANGE THIS!

  config:

    bind-addr: "0.0.0.0:8080"

    auth: "password"

    # ... other settings

```



### Security Configuration

Change default password using Helm:

```bash

# During deployment

helm install code-server ./helm-chart/code-server -n code-server --set codeServer.password=your-new-password



# Or upgrade existing deployment

helm upgrade code-server ./helm-chart/code-server -n code-server --set codeServer.password=your-new-password

```



## Management Commands



### Infrastructure Management (K3d HA)

```bash

# Deploy infrastructure (single VM with K3d HA)

./deploy.sh



# Show outputs (VM IP and connection details)

./deploy.sh output



# Destroy infrastructure

./deploy.sh destroy

```



### K3d HA Cluster Management

```bash

# SSH to VM and manage K3d cluster

ssh $USER@



# K3d HA cluster operations

k3d cluster list                               # List clusters

k3d cluster info k3s-ha-cluster               # Cluster info

k3d node list                                 # List all nodes



# Scale K3d cluster

k3d node create new-worker --cluster k3s-ha-cluster --role agent

k3d node delete worker-node --cluster k3s-ha-cluster



# HA cluster health checks

kubectl get nodes -o wide                     # Check all nodes

kubectl get pods -n kube-system               # System pods

kubectl cluster-info                          # Cluster endpoints

kubectl get endpoints kubernetes -n default   # Master endpoints

```



### Code-Server Management

```bash

# Deploy code-server

./deploy-code-server.sh



# Show deployment status

./deploy-code-server.sh status



# Show access information

./deploy-code-server.sh access



# View logs

./deploy-code-server.sh logs



# Upgrade deployment

./deploy-code-server.sh upgrade



# Show current Helm values

./deploy-code-server.sh values



# Delete deployment

./deploy-code-server.sh delete

```



### Direct Helm and K3d Commands

```bash

# Check HA cluster status

kubectl get nodes -o wide                     # Shows all 6 nodes (3 masters + 3 workers)

kubectl get pods --all-namespaces             # All system and application pods



# Helm operations

helm list -n code-server

helm status code-server -n code-server

helm get values code-server -n code-server



# Access code-server pod  

kubectl exec -it -n code-server deployment/code-server -- /bin/bash



# Check ingress and load balancer

kubectl get ingress -n code-server

kubectl get svc -n ingress-nginx              # Nginx ingress controller

```



## Troubleshooting



### Common Issues (Updated for K3d HA)



1. **K3d cluster not starting:**

   - Check Docker service: `sudo systemctl status docker`

   - Check cloud-init logs: `sudo journalctl -u cloud-final`

   - Verify K3d installation: `k3d version`

   - Check available resources: `free -h` and `df -h`



2. **K3d HA cluster health:**

   - Check all nodes: `kubectl get nodes -o wide`

   - Check master endpoints: `kubectl get endpoints kubernetes -n default`

   - Check etcd health: `kubectl get pods -n kube-system | grep etcd`

   - Check system pods: `kubectl get pods -n kube-system`



3. **Code-server not accessible:**

   - Check pod status: `kubectl get pods -n code-server`

   - Check service: `kubectl get svc -n code-server`

   - Use port-forward for direct access

   - Check ingress controller: `kubectl get pods -n ingress-nginx`



4. **Storage issues:**

   - Verify Docker volumes: `docker volume ls`

   - Check PV/PVC status: `kubectl get pv,pvc -n code-server`

   - Check mount points: `df -h`



### Log Locations (K3d HA)

- **Cloud-init**: `/var/log/cloud-init-output.log`

- **K3d cluster**: `k3d cluster info k3s-ha-cluster`

- **Docker logs**: `docker logs `

- **Code-server**: `kubectl logs -n code-server deployment/code-server`

- **Ingress controller**: `kubectl logs -n ingress-nginx deployment/ingress-nginx-controller`



## Cost Optimization (K3d HA Benefits)



- Uses OCI Always Free tier ARM instances at maximum specs (4 vCPUs, 24GB RAM)

- Single VM instead of multiple VMs reduces management overhead

- K3d containers share host kernel, reducing memory overhead

- Efficient resource utilization with containerized HA cluster

- Automatic resource tagging for cost tracking

- Better resource density with 6 nodes in containers vs 3 separate VMs



## Security Considerations (K3d HA)



- SSH key-based authentication for VM access

- Security groups with minimal required ports (22, 6443, 80, 443, 8080)

- Container isolation between K3d nodes

- Private cluster communication within Docker networks

- Regular security updates via cloud-init (Ubuntu 24.04 LTS)

- Kubernetes RBAC for application security



## Customization (K3d HA Ready)



### Adding Applications

Deploy additional applications to the K3d HA cluster:

```bash

# Example: Deploy monitoring stack

kubectl apply -f monitoring-manifests/



# Example: Deploy additional development tools

helm install   -n 



# Scale applications across HA workers

kubectl scale deployment  --replicas=3 -n 

```



### Custom Domains

Update ingress configuration in `helm-chart/code-server/values.yaml`:

```yaml

ingress:

  enabled: true

  hosts:

    - host: code.yourdomain.com

      paths:

        - path: /

          pathType: Prefix

  tls:

    - secretName: code-server-tls

      hosts:

        - code.yourdomain.com

```



## HA Cluster Benefits



### High Availability Features

- **Master HA**: 3 masters provide etcd quorum resilience (can survive 1 master failure)

- **Worker HA**: 3 workers distribute workload evenly across nodes

- **Load Balancer**: Built-in K3d load balancer for traffic distribution

- **Fault Tolerance**: Kubernetes automatically reschedules pods on node failures



### Resource Efficiency

- **Memory Optimization**: 24GB RAM shared across 6 containerized nodes

- **CPU Optimization**: 4 vCPUs efficiently shared with container scheduling

- **Storage Efficiency**: Docker volumes provide persistent storage without VM overhead

- **Network Efficiency**: Container networking eliminates VM network overhead



### Development Benefits

- **Production-Like**: Multi-master setup mimics production Kubernetes environments

- **Scaling Ready**: Easy horizontal scaling with additional K3d nodes

- **Testing**: Test HA scenarios and failover without multiple VMs

- **Learning**: Experience real Kubernetes HA patterns and best practices



## Contributing



1. Fork the repository

2. Create feature branch

3. Test changes thoroughly with K3d HA setup

4. Submit pull request



## License



This project is open source under MIT License. See LICENSE file for details.