feat: Add multi-platform support (AWS/EKS, Generic K8s) and in-cluster deployment

[finnng]

This PR transforms k8s-node-proxy from a GCP/GKE-specific tool into a universal Kubernetes NodePort proxy that works across cloud providers and deployment models.

🎯 What's New

Multi-Platform Support

• ✅ AWS/EKS - Full support for Amazon EKS clusters with IAM authentication
• ✅ Generic Kubernetes - Works with any Kubernetes cluster via kubeconfig
• ✅ GCP/GKE - Existing GCP support maintained and improved
• ✅ In-Cluster Mode - Can now run as a pod inside the cluster using service account auth

Automatic Platform Detection
The proxy now intelligently detects the environment and configures itself automatically:

• Checks for in-cluster service account tokens
• Detects AWS credentials and EKS configuration
• Falls back to GCP if PROJECT_ID is set
• Uses kubeconfig for generic Kubernetes clusters

Production-Ready Testing

• 🧪 500+ new test cases covering all platforms
• 🎭 Mock servers for AWS, GCP, and Kubernetes APIs (no cloud credentials needed for testing)
• 🔄 Integration tests with real kind clusters
• 🤖 GitHub Actions CI/CD with automated testing on every push

📊 Impact

43 files changed, 7,193 additions(+), 166 deletions(-)

New Files:

• Platform detection system (internal/platform/)
• EKS-specific implementations (internal/nodes/eks_discovery.go, internal/services/eks_discovery.go)
• Generic K8s implementations (internal/nodes/generic_discovery.go, internal/services/generic_discovery.go)
• Comprehensive test suite (test/e2e/, test/mocks/)
• CI/CD workflows (.github/workflows/)

🏗️ Architecture Changes

Before: Single GCP-specific server
main.go → GKE discovery → Node monitoring → Proxy

After: Platform-agnostic factory pattern
main.go → Platform Detection → Factory → [GCP|EKS|Generic] Server → Node monitoring → Proxy

Key Design Patterns:

• Interface-based discovery - NodeDiscovery and ServiceDiscovery interfaces allow platform-specific implementations
• Factory pattern - Server creation abstracted by platform type
• Dependency injection - Shared Kubernetes clientsets reduce API calls
• Zero breaking changes - Existing GCP deployments work without modification

🔧 Platform-Specific Details

AWS/EKS

New environment variables:

• AWS_REGION - AWS region containing the EKS cluster
• CLUSTER_NAME - Name of the EKS cluster
• NAMESPACE - Target namespace (required)

Authentication:

• Uses AWS SDK default credential chain (IAM roles, environment variables, etc.)
• Fetches EKS cluster token via STS for Kubernetes API access
• Requires eks:DescribeCluster IAM permission

Files: cmd/server/eks_server.go, internal/platform/aws_auth.go, internal/nodes/eks_discovery.go

Generic Kubernetes

New environment variables:

• KUBECONFIG - Path to kubeconfig file
• NAMESPACE - Target namespace (required)

Authentication:

• Uses standard kubeconfig authentication
• Supports all kubeconfig auth methods (certificates, tokens, OIDC, etc.)

Files: cmd/server/generic_server.go, internal/nodes/generic_discovery.go

In-Cluster Mode

Detection:

• Automatically enabled when running inside a Kubernetes pod
• Checks for /var/run/secrets/kubernetes.io/serviceaccount/token

Requirements:

• Service account with permissions to list nodes and services
• No additional configuration needed

🧪 Testing Infrastructure

Unit Tests (make test-unit) - 30 seconds

• Tests all internal packages
• Includes race detector
• 200+ test cases

E2E Tests (make test-e2e) - 1 minute

• Platform detection logic
• Error handling scenarios
• Mock cloud provider APIs
• No cloud credentials required

Integration Tests (make test-e2e-kind) - 10-15 minutes

• Creates real kind cluster
• Deploys nginx service
• Deploys proxy as a pod
• Validates:
  • Service discovery
  • Request proxying
  • Health monitoring
  • Concurrent requests
  • Node failover

GitHub Actions
Jobs:
✓ Unit tests with race detector
✓ E2E tests with mocks
✓ Integration tests with kind
✓ Build verification

Manually trigger: gh workflow run test.yml

📝 Configuration Examples

External VM with IAM role

  export AWS_REGION=us-east-1
  export CLUSTER_NAME=my-eks-cluster
  export NAMESPACE=production
  ./k8s-node-proxy

In-cluster deployment

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: k8s-node-proxy
  spec:
    template:
      spec:
        containers:
        - name: proxy
          image: k8s-node-proxy:latest
          env:
          - name: AWS_REGION
            value: "us-east-1"
          - name: CLUSTER_NAME
            value: "my-eks-cluster"
          - name: NAMESPACE
            value: "production"

External machine with kubeconfig

  export KUBECONFIG=/path/to/kubeconfig
  export NAMESPACE=staging
  ./k8s-node-proxy

Existing deployments work without modification

  export PROJECT_ID=my-gcp-project
  export NAMESPACE=default
  ./k8s-node-proxy

⚠️ Breaking Changes

None. This PR is fully backward compatible. Existing GCP/GKE deployments will continue to work without any changes.

🚀 Migration Guide

For existing GCP users: No action required.

To switch platforms:

1. Update environment variables for your target platform
2. Ensure appropriate cloud credentials are configured
3. Restart the proxy

📚 Updated Documentation

• README.md - Complete rewrite with platform-specific setup guides, contribution guidelines, and testing instructions
• .github/workflows/README.md - CI/CD workflow documentation
• Makefile - New test targets (test-unit, test-e2e, test-e2e-kind)

✅ Checklist

• All tests pass (make test)
• Integration tests pass (make test-e2e-kind)
• Build succeeds (make build)
• Documentation updated
• CI/CD pipeline configured
• Backward compatibility maintained
• Code follows Go 1.24.1 best practices

🔍 Review Focus Areas

For reviewers, please pay special attention to:

1. Platform detection logic (internal/platform/detector.go) - Is the priority order correct?
2. Error handling - Are cloud API failures handled gracefully?
3. Test coverage - Are the mock servers realistic?
4. Documentation - Is the README clear for new contributors?

🙏 Testing Requests

If you have access to AWS/EKS or other Kubernetes platforms, please test this branch and report results!

Clone and test

  git checkout feature/eks-support
  make test-e2e-kind  # Full integration test

[Copilot]

Pull Request Overview

This PR transforms k8s-node-proxy from a GCP/GKE-specific tool into a universal Kubernetes NodePort proxy supporting multiple cloud platforms and deployment models.

• Adds AWS/EKS support with IAM authentication and automatic platform detection
• Implements Generic Kubernetes support for any cluster via kubeconfig or in-cluster deployment
• Maintains full backward compatibility with existing GCP/GKE deployments

Reviewed Changes

Copilot reviewed 41 out of 43 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cmd/server/main.go	Platform detection factory pattern routing to platform-specific servers
cmd/server/generic_server.go	Generic Kubernetes server implementation with kubeconfig support
cmd/server/eks_server.go	AWS EKS-specific server with IAM authentication
internal/platform/	Platform detection system and AWS authentication utilities
internal/services/	Service discovery interfaces for EKS and Generic platforms
internal/nodes/	Node discovery implementations across all platforms
internal/proxy/handler.go	Abstracted interface for multi-platform node discovery
test/	Comprehensive test suite with mocks and integration tests
go.mod	Updated dependencies for AWS SDK and IAM authenticator

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull request overview

Copilot reviewed 44 out of 46 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.