fabianpiper.com

Portfolio deployment using K3s, Terraform, Atmos, Cloudflare DNS, and ArgoCD on Oracle Cloud Free Tier

Overview · Prerequisites · Installation · Architecture · CI/CD Pipeline · Documentation · License

---

Overview

This repository demonstrates infrastructure automation and GitOps principles by deploying a portfolio website on Oracle Cloud Infrastructure Free Tier. The stack uses Terraform with Atmos for infrastructure orchestration, K3s for container orchestration, and ArgoCD for continuous deployment.

Key capabilities:

• Declarative infrastructure provisioning with Terraform (networking, IAM, OCI Vault, K3s cluster, Cloudflare DNS)
• GitOps workflow via ArgoCD ApplicationSets
• Automated image updates and zero-downtime deployments
• Secure secret management using SOPS and OCI Vault
• CI/CD pipeline with SOPS-encrypted OCI credentials and GITHUB_TOKEN for GHCR
• Observability with kube-prometheus-stack (Prometheus + Grafana), Loki log aggregation, and Gatus status page

Prerequisites

Install the following tools before beginning:

• Make v4.3+
• Terraform v1.5+
• Atmos v0.23+
• SOPS v3.11+
• age v1.3+
• Bun v1.3+

Installation

Account Setup

1. Create Oracle Cloud Infrastructure account and upgrade Free Tier to paid account for priority resource allocation (remains within Free Tier limits) (link)
2. Create Cloudflare account and generate API token with DNS management permissions (link)
3. Generate GitHub Personal Access Token with repo and packages scopes (link)

Repository Configuration

git clone https://github.com/fapiper/fabianpiper.com.git
cd fabianpiper.com

Initialize encryption and configure secrets:

make setup

Note

This generates secrets/.sops.key and configures SOPS for all secret files.

Copy the example secrets files and add your credentials:

cp secrets/prod/secrets.example.yaml secrets/prod/secrets.decrypted.yaml
cp secrets/prod/www.example.yaml secrets/prod/www.decrypted.yaml

Edit secrets/prod/*.decrypted.yaml with your actual values, then encrypt:

make sops-encrypt-prod

Infrastructure Deployment

Deploy the complete stack with a single command:

make deploy-prod

This provisions networking, IAM policies, OCI Vault, and a K3s cluster with ArgoCD automatically installed. DNS records are synced to Cloudflare after cluster bootstrap.

Verify deployment health:

make validate-prod

Accessing ArgoCD

Retrieve the admin password:

ssh -i ~/.ssh/id_rsa ubuntu@<INGRESS_IP> \
  'ssh ubuntu@10.0.2.10 sudo kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d'

Create a port forward to access the UI:

ssh -i ~/.ssh/id_rsa -L 8080:10.0.2.10:80 ubuntu@<INGRESS_IP>

Open your browser to http://localhost:8080 and log in with username admin and the retrieved password.

Architecture

The infrastructure consists of:

• VCN with public (10.0.1.0/24) and private (10.0.2.0/24) subnets
• Three ARM Ampere A1 instances running K3s
• OCI Vault for runtime secret storage via Instance Principal
• Cloudflare DNS with static A records provisioned by Terraform, dynamic records synced by external-dns from HTTPRoutes
• ArgoCD managing GitOps deployments
• kube-prometheus-stack (Prometheus + Grafana) + Loki for observability

Directory Structure

fabianpiper.com/

fabianpiper.com/
├── components/terraform/       # Atmos component wrappers
│   ├── networking/             # VCN, subnets, security lists
│   ├── iam/                    # Dynamic groups and policies
│   ├── vault/                  # OCI Vault and stored secrets
│   ├── dns/                    # Cloudflare DNS records
│   └── cluster/                # K3s instances and cloud-init
├── modules/                    # Terraform module implementations
├── stacks/                     # Atmos stack configurations
│   ├── orgs/glg/prod/fra.yaml  # Production deployment config
│   ├── mixins/                 # Reusable configuration snippets
│   └── workflows/              # Multi-component workflows
├── kubernetes/                 # GitOps manifests
│   ├── bootstrap/              # ArgoCD root app and ApplicationSets
│   ├── infrastructure/         # Platform services (cert-manager, gateway, monitoring…)
│   └── apps/                   # Application deployments
├── apps/www/                   # Website source code (Astro 5.7)
├── secrets/prod/               # SOPS-encrypted secrets
└── .github/workflows/          # CI/CD automation

CI/CD Pipeline

The automated deployment flow:

1. Code changes pushed to main branch
2. GitHub Actions workflow triggered
3. Docker image built and pushed to GHCR
4. ArgoCD Image Updater detects new image digest
5. ArgoCD automatically syncs and deploys updated application

Important

Only one GitHub secret is required: SOPS_AGE_KEY for infrastructure modifications.

Documentation

For detailed operational procedures and agent-friendly instructions, refer to AGENTS.md.

License

This project is licensed under the MIT License. See the LICENSE file for details.