add README for Akamai provider in CNCF self-hosted runners

ci/cluster/akamai/README.md

@@ -0,0 +1,62 @@
+# Akamai Provider for CNCF Self-Hosted Runners (PoC)
+
+This directory contains automation tools and configurations for deploying and managing CNCF GitHub self-hosted runners on Akamai infrastructure.
+
+> **Note:** This implementation is currently in Proof of Concept (PoC) stage.
+
+## Overview
+
+The Akamai provider enables CNCF projects to leverage Akamai's cloud infrastructure for running CI/CD workflows with GitHub Actions. These self-hosted runners offer enhanced performance, customized environments, and dedicated resources tailored to CNCF project needs.
+
+This automation specifically provisions and manages **Linode managed Kubernetes clusters** and deploys **Actions Runner Controller (ARC)** to handle GitHub Actions workloads efficiently.
+
+## Features
+
+- Automated provisioning of managed Kubernetes clusters on Linode
+- Deployment and configuration of Actions Runner Controller (ARC)
+- Runner configuration and registration with GitHub
+- Auto-scaling capabilities based on workflow demand
+- Monitoring and maintenance utilities
+- Support for multiple GitHub organizations and repositories
+
+## Prerequisites
+
+- Akamai cloud account with appropriate permissions
+- Linode API credentials for Kubernetes cluster management
+- Service account credentials configured for automation
+- GitHub Personal Access Token (PAT) with appropriate permissions
+
+## Configuration
+
+Configuration is managed through environment variables and config files:
+
+- `AKAMAI_API_KEY`: API key for accessing Akamai services
+- `AKAMAI_API_SECRET`: API secret for authentication
+- `LINODE_API_TOKEN`: API token for Linode Kubernetes service
+- `GITHUB_PAT`: GitHub Personal Access Token for runner registration
+
+See the sample configuration file in `config-example.yaml` for detailed settings.
+
+## Usage
+
+Detailed usage instructions for provisioning and managing runners are coming soon.
+
+### Proof of Concept Deployment
+
+This PoC uses an intentionally cost-effective setup with spot instances to demonstrate the functionality at minimal expense. The configuration is not intended for production use without appropriate adjustments.
+
+## Kubernetes Deployment
+
+This provider automatically:
+1. Creates a Kubernetes cluster in Linode
+2. Installs and configures Actions Runner Controller using Helm
+3. Sets up runner scale sets for GitHub repositories/organizations
+4. Configures auto-scaling based on workflow demand
+
+## Troubleshooting
+
+Common issues and their solutions will be documented as they are encountered.
+
+## Contributing
+
+Contributions to improve the Akamai provider are welcome! Please follow the contributing guidelines in the root of this repository.

ci/cluster/akamai/SETUP.md

@@ -0,0 +1,134 @@
+# Setting Up Linode Kubernetes Engine with OpenTofu
+
+This guide walks you through deploying a Linode Kubernetes Engine (LKE) cluster using OpenTofu.
+
+## Prerequisites
+
+- [OpenTofu](https://opentofu.org/docs/intro/install/) installed
+- Linode account with API token
+- GitHub Personal Access Token with appropriate permissions
+
+## Installation Steps
+
+### 1. Install OpenTofu
+
+If you haven't already installed OpenTofu, follow these instructions:
+
+```bash
+# For Linux/macOS
+brew install opentofu/tap/opentofu
+
+# Alternatively, you can download directly from the releases
+# https://github.com/opentofu/opentofu/releases
+```
+
+### 2. Configure Environment Variables
+
+Create a `.env` file (which is ignored by git) to store your sensitive credentials:
+
+```bash
+# Create and edit .env file
+touch .env
+```
+
+Add the following content to the `.env` file:
+
+```
+export TF_VAR_linode_api_token="your-linode-api-token"
+export TF_VAR_github_token="your-github-pat"
+```
+
+Source the environment variables:
+
+```bash
+source .env
+```
+
+### 3. Initialize OpenTofu
+
+```bash
+cd ci/cluster/akamai
+tofu init
+```
+
+This will download the necessary providers defined in the configuration.
+
+### 4. Review the Execution Plan
+
+```bash
+tofu plan
+```
+
+This will show you what resources will be created without actually creating them.
+
+### 5. Apply the Configuration
+
+When you're ready to create the cluster:
+
+```bash
+tofu apply
+```
+
+Review the planned changes and type `yes` to confirm.
+
+### 6. Access Your Kubernetes Cluster
+
+After successful deployment, OpenTofu will generate a `kubeconfig.yaml` file in the current directory:
+
+```bash
+export KUBECONFIG=$(pwd)/kubeconfig.yaml
+kubectl get nodes
+```
+
+### 7. Verify Actions Runner Controller Installation
+
+Check that ARC is running in the cluster:
+
+```bash
+kubectl -n arc-system get pods
+```
+
+### 8. Create Runner Scale Sets
+
+After ARC is installed, you can create runner scale sets for your GitHub organizations or repositories:
+
+```bash
+kubectl apply -f - <<EOF
+apiVersion: actions.summerwind.dev/v1alpha1
+kind: RunnerDeployment
+metadata:
+  name: cncf-runner-deployment
+  namespace: arc-system
+spec:
+  replicas: 1
+  template:
+    spec:
+      organization: your-github-org
+      labels:
+        - cncf-runner
+EOF
+```
+
+## Cleaning Up
+
+When you're done with the resources, you can destroy them:
+
+```bash
+tofu destroy
+```
+
+This will remove all resources created by OpenTofu.
+
+## Troubleshooting
+
+- **Authentication Issues**: Make sure your Linode API token has read/write permissions
+- **Connection Issues**: Ensure network connectivity to Linode's API
+- **Helm Failures**: Check if Helm is installed and properly configured
+
+For detailed error logs, run commands with increased verbosity:
+
+```bash
+tofu apply -v=1
+```
+
+For additional support, refer to the [OpenTofu documentation](https://opentofu.org/docs/) or [Linode API documentation](https://www.linode.com/docs/api/).

ci/cluster/akamai/config-example.yaml

@@ -0,0 +1,29 @@
+# Example configuration for CNCF Runners on Linode Kubernetes Engine
+# Copy this file to config.yaml and fill in your values
+
+# Linode Configuration
+linode:
+  api_token: "your-linode-api-token"
+  region: "us-east"
+
+# Kubernetes Configuration
+kubernetes:
+  version: "1.32" # Updated to the most recent version
+  cluster_name: "cncf-poc-runners"
+  node_count: 1
+  node_type: "g6-standard-1"
+
+# GitHub Configuration
+github:
+  token: "your-github-pat"
+  organization: "cncf"
+  repositories:
+    - "repo1"
+    - "repo2"
+
+# Actions Runner Controller Configuration
+arc:
+  namespace: "arc-system"
+  runner_scale_set_name: "cncf-runners"
+  min_runners: 1
+  max_runners: 3

ci/cluster/akamai/main.tf

@@ -0,0 +1,125 @@
+terraform {
+  required_providers {
+    linode = {
+      source  = "linode/linode"
+      version = "~> 2.0"
+    }
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.9"
+    }
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "~> 2.21"
+    }
+  }
+}
+
+resource "linode_lke_cluster" "cncf_poc_cluster" {
+  label       = var.cluster_name
+  k8s_version = var.kubernetes_version
+  region      = var.region
+  tags        = ["cncf", "poc", "runners"]
+
+  pool {
+    type  = "g6-standard-1" # Cheapest shared CPU instance type
+    count = var.node_count
+
+    # Use autoscaler for spot instances if available
+    autoscaler {
+      min = 1
+      max = 3
+    }
+  }
+}
+
+resource "local_file" "kubeconfig" {
+  content  = base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)
+  filename = "${path.module}/kubeconfig.yaml"
+}
+
+# Configure Kubernetes provider with the cluster's kubeconfig
+provider "kubernetes" {
+  host                   = yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).clusters[0].cluster.server
+  cluster_ca_certificate = base64decode(yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).clusters[0].cluster.certificate-authority-data)
+  token                  = yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).users[0].user.token
+}
+
+# Configure Helm provider with the cluster's kubeconfig
+provider "helm" {
+  kubernetes {
+    host                   = yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).clusters[0].cluster.server
+    cluster_ca_certificate = base64decode(yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).clusters[0].cluster.certificate-authority-data)
+    token                  = yamldecode(base64decode(linode_lke_cluster.cncf_poc_cluster.kubeconfig)).users[0].user.token
+  }
+}
+
+# Create namespace for ARC
+resource "kubernetes_namespace" "arc_system" {
+  metadata {
+    name = "arc-system"
+  }
+
+  depends_on = [linode_lke_cluster.cncf_poc_cluster]
+}
+
+# Create secret for GitHub token
+resource "kubernetes_secret" "github_token" {
+  metadata {
+    name      = "github-token"
+    namespace = kubernetes_namespace.arc_system.metadata[0].name
+  }
+
+  data = {
+    github_token = var.github_token
+  }
+
+  depends_on = [kubernetes_namespace.arc_system]
+}
+
+# Install Actions Runner Controller using Helm
+resource "helm_release" "arc" {
+  name       = "arc"
+  repository = "https://actions-runner-controller.github.io/actions-runner-controller"
+  chart      = "actions-runner-controller"
+  namespace  = kubernetes_namespace.arc_system.metadata[0].name
+  version    = "0.23.0"  # Specify the version you want to use
+
+  set {
+    name  = "authSecret.create"
+    value = "false"  # We create the secret separately
+  }
+
+  set {
+    name  = "authSecret.name"
+    value = kubernetes_secret.github_token.metadata[0].name
+  }
+
+  depends_on = [
+    kubernetes_secret.github_token,
+    linode_lke_cluster.cncf_poc_cluster
+  ]
+}
+
+# Optional: Deploy a runner scale set
+resource "kubernetes_manifest" "runner_scale_set" {
+  manifest = {
+    apiVersion = "actions.summerwind.dev/v1alpha1"
+    kind       = "RunnerDeployment"
+    metadata = {
+      name      = "cncf-runner-deployment"
+      namespace = kubernetes_namespace.arc_system.metadata[0].name
+    }
+    spec = {
+      replicas = 1
+      template = {
+        spec = {
+          organization = var.github_organization
+          labels       = ["cncf-runner"]
+        }
+      }
+    }
+  }
+
+  depends_on = [helm_release.arc]
+}

ci/cluster/akamai/outputs.tf

@@ -0,0 +1,19 @@
+output "api_endpoints" {
+  description = "The API endpoints for the cluster"
+  value       = linode_lke_cluster.cncf_poc_cluster.api_endpoints
+}
+
+output "status" {
+  description = "The status of the cluster"
+  value       = linode_lke_cluster.cncf_poc_cluster.status
+}
+
+output "kubeconfig_path" {
+  description = "Path to the kubeconfig file"
+  value       = "${path.module}/kubeconfig.yaml"
+}
+
+output "dashboard_url" {
+  description = "URL to access the Kubernetes Dashboard"
+  value       = "https://${linode_lke_cluster.cncf_poc_cluster.api_endpoints[0]}/kubernetes-dashboard"
+}

ci/cluster/akamai/providers.tf

@@ -0,0 +1,3 @@
+provider "linode" {
+  token = var.linode_api_token
+}