pangea-kubernetes 0.1.0

data/lib/pangea/kubernetes/network_backend_registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Kubernetes
+    # Lazy-loading registry for network backends.
+    # Mirrors BackendRegistry pattern for compute backends.
+    module NetworkBackendRegistry
+      NETWORK_MAP = {
+        vpc_cni: 'pangea/kubernetes/network_backends/vpc_cni',
+        cilium: 'pangea/kubernetes/network_backends/cilium',
+      }.freeze
+
+      ALIASES = {
+        aws_cni: :vpc_cni,
+        eni: :vpc_cni,
+        ebpf: :cilium,
+      }.freeze
+
+      CLASS_MAP = {
+        vpc_cni: 'Pangea::Kubernetes::NetworkBackends::VpcCni',
+        cilium: 'Pangea::Kubernetes::NetworkBackends::Cilium',
+      }.freeze
+
+      # Resolve a network backend by name.
+      #
+      # @param name [Symbol] Backend name or alias
+      # @return [Module] The network backend module
+      # @raise [ArgumentError] If the backend is unknown
+      def self.resolve(name)
+        name = ALIASES.fetch(name, name)
+        path = NETWORK_MAP.fetch(name) do
+          raise ArgumentError, "Unknown network backend: #{name}. Available: #{NETWORK_MAP.keys.join(', ')}"
+        end
+        require path
+        Object.const_get(CLASS_MAP.fetch(name))
+      end
+
+      # Check if a network backend is compatible with a compute backend.
+      #
+      # @param network [Symbol] Network backend name
+      # @param compute [Symbol] Compute backend name
+      # @return [Boolean]
+      def self.compatible?(network, compute)
+        backend = resolve(network)
+        backend.compatible_backends.include?(compute)
+      end
+
+      # @return [Array<Symbol>] All registered network backend names
+      def self.available
+        NETWORK_MAP.keys
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/network_backends/base.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Kubernetes
+    module NetworkBackends
+      # Contract interface for network backends. Each backend module
+      # provides CNI-specific infrastructure (IAM, config) and metadata.
+      #
+      # Network backends are orthogonal to compute backends — you can
+      # combine any network backend with any compatible compute backend:
+      #
+      #   | Network Backend | EKS | K3s/NixOS | mTLS | L7 Obs | eBPF |
+      #   |----------------|-----|-----------|------|--------|------|
+      #   | vpc_cni        | ✅  | ❌        | ❌   | ❌     | ❌   |
+      #   | cilium_eni     | ✅  | ❌        | ✅   | ✅     | ✅   |
+      #   | cilium_overlay | ✅  | ✅        | ✅   | ✅     | ✅   |
+      #   | calico         | ✅  | ✅        | ❌   | ❌     | partial |
+      #   | flannel        | ❌  | ✅        | ❌   | ❌     | ❌   |
+      #
+      module Base
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # @return [Symbol] Backend identifier (:vpc_cni, :cilium, :calico, :flannel)
+          def backend_name
+            raise NotImplementedError, "#{self} must implement .backend_name"
+          end
+
+          # @return [Array<Symbol>] Compatible compute backends (:aws, :gcp, :azure, :hcloud, etc.)
+          def compatible_backends
+            raise NotImplementedError, "#{self} must implement .compatible_backends"
+          end
+
+          # @return [Boolean] Whether this backend provides service mesh capabilities
+          def mesh_capable?
+            false
+          end
+
+          # @return [Boolean] Whether this backend provides L7 observability (e.g., Hubble)
+          def l7_observable?
+            false
+          end
+
+          # Create cloud-level IAM resources for the CNI (e.g., IRSA for Cilium operator).
+          # Returns nil if no cloud IAM is needed.
+          #
+          # @param ctx [Object] Synthesizer context
+          # @param name [Symbol] Cluster name
+          # @param config [Hash] Network configuration
+          # @param tags [Hash] Resource tags
+          # @return [Hash, nil] IAM resources created
+          def create_network_iam(_ctx, _name, _config, _tags)
+            nil # Most network backends don't need cloud IAM
+          end
+
+          # Return the NixOS/blackmatter-kubernetes profile name for this backend.
+          # Used by NixOS backends in cloud-init to select the correct CNI config.
+          #
+          # @return [String, nil] Profile name (e.g., 'cilium-mesh', 'flannel-production')
+          def nixos_profile
+            nil # Managed backends (EKS/GKE/AKS) don't use NixOS profiles
+          end
+
+          # Return Helm values or configuration to be passed to the GitOps layer.
+          # This is what gets deployed via FluxCD HelmRelease.
+          #
+          # @param config [Hash] Network configuration
+          # @return [Hash] Configuration for the network backend's Helm chart
+          def helm_values(_config)
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/network_backends/cilium.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Kubernetes
+    module NetworkBackends
+      # Cilium — eBPF-based CNI with service mesh and L7 observability.
+      # Supports ENI mode (AWS VPC IPs) and overlay mode (VXLAN/Geneve).
+      # Hubble provides per-request latency histograms without app instrumentation.
+      module Cilium
+        include Base
+
+        class << self
+          def backend_name
+            :cilium
+          end
+
+          def compatible_backends
+            %i[aws gcp azure hcloud aws_nixos gcp_nixos azure_nixos]
+          end
+
+          def mesh_capable?
+            true
+          end
+
+          def l7_observable?
+            true # Hubble
+          end
+
+          # IRSA for Cilium operator on EKS.
+          def create_network_iam(ctx, name, config, tags)
+            return nil unless config[:compute_backend] == :aws
+
+            # Cilium operator needs permissions for ENI management
+            ctx.extend(Pangea::Resources::AWS) unless ctx.respond_to?(:aws_iam_role)
+
+            policy_doc = JSON.generate({
+              Version: '2012-10-17',
+              Statement: [{
+                Effect: 'Allow',
+                Action: [
+                  'ec2:DescribeNetworkInterfaces',
+                  'ec2:DescribeSubnets',
+                  'ec2:DescribeVpcs',
+                  'ec2:DescribeSecurityGroups',
+                  'ec2:CreateNetworkInterface',
+                  'ec2:AttachNetworkInterface',
+                  'ec2:DeleteNetworkInterface',
+                  'ec2:ModifyNetworkInterfaceAttribute',
+                  'ec2:AssignPrivateIpAddresses',
+                  'ec2:UnassignPrivateIpAddresses',
+                  'ec2:CreateTags',
+                ],
+                Resource: '*',
+              }],
+            })
+
+            policy = ctx.aws_iam_policy(:"#{name}-cilium-operator", {
+              name: "#{name}-cilium-operator",
+              policy: policy_doc,
+              tags: tags.merge(Component: 'cilium'),
+            })
+
+            { policy: policy }
+          end
+
+          def nixos_profile
+            'cilium-mesh'
+          end
+
+          def helm_values(config)
+            mode = config[:cilium_mode] || :eni
+            values = {
+              'ipam' => { 'mode' => mode.to_s },
+              'hubble' => {
+                'enabled' => true,
+                'relay' => { 'enabled' => true },
+                'ui' => { 'enabled' => false }, # No GUI, MCP-queryable via Grafana
+                'metrics' => {
+                  'enabled' => [
+                    'dns', 'drop', 'tcp', 'flow',
+                    'icmp', 'http', 'port-distribution',
+                    'httpV2:exemplars=true;labelsContext=source_ip,source_namespace,source_workload,destination_ip,destination_namespace,destination_workload',
+                  ],
+                },
+              },
+              'prometheus' => { 'enabled' => true },
+              'operator' => { 'prometheus' => { 'enabled' => true } },
+            }
+
+            # ENI mode: use AWS VPC IPs (compatible with existing /20 pod subnets)
+            if mode == :eni
+              values['eni'] = {
+                'enabled' => true,
+                'awsEnablePrefixDelegation' => true,
+              }
+              values['tunnel'] = 'disabled'
+            end
+
+            values
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/network_backends/vpc_cni.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Kubernetes
+    module NetworkBackends
+      # AWS VPC CNI — default EKS networking.
+      # Pods get VPC IP addresses via ENI attachment.
+      # No mesh, no mTLS, no L7 observability.
+      module VpcCni
+        include Base
+
+        class << self
+          def backend_name
+            :vpc_cni
+          end
+
+          def compatible_backends
+            [:aws]
+          end
+
+          def mesh_capable?
+            false
+          end
+
+          def l7_observable?
+            false
+          end
+
+          def nixos_profile
+            nil # VPC CNI is EKS-only, no NixOS support
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/argocd_config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Kubernetes
+    module Types
+      # ArgoCD GitOps bootstrap configuration.
+      #
+      # Parallel to FluxCDConfig — provides the same role but for ArgoCD.
+      # The bootstrap service writes ArgoCD manifests to the k3s auto-deploy
+      # directory at boot, then creates git auth credentials after API is ready.
+      class ArgocdConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        attribute :enabled, T::Bool.default(true)
+        attribute :repo_url, T::String
+        attribute :target_revision, T::String.default('HEAD')
+        attribute :path, T::String.default('./')
+        attribute :project, T::String.default('default')
+        attribute :sync_policy, T::String.constrained(included_in: %w[automated manual]).default('automated')
+        attribute :auto_prune, T::Bool.default(true)
+        attribute :self_heal, T::Bool.default(true)
+
+        # Auth
+        attribute :auth_type, T::String.constrained(included_in: %w[ssh token]).default('ssh')
+        attribute :ssh_key_file, T::String.optional.default(nil)
+        attribute :token_file, T::String.optional.default(nil)
+        attribute :token_username, T::String.default('git')
+
+        # SOPS
+        attribute :sops_enabled, T::Bool.default(false)
+        attribute :sops_age_key_file, T::String.optional.default(nil)
+
+        def to_h
+          hash = {
+            enabled: enabled,
+            repo_url: repo_url,
+            target_revision: target_revision,
+            path: path,
+            project: project,
+            sync_policy: sync_policy,
+            auto_prune: auto_prune,
+            self_heal: self_heal,
+            auth_type: auth_type,
+            token_username: token_username
+          }
+          hash[:ssh_key_file] = ssh_key_file if ssh_key_file
+          hash[:token_file] = token_file if token_file
+          hash[:sops_enabled] = sops_enabled if sops_enabled
+          hash[:sops_age_key_file] = sops_age_key_file if sops_age_key_file
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/control_plane_config.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'pangea/resources/types'
+
+module Pangea
+  module Kubernetes
+    module Types
+      # Control plane configuration for blackmatter-kubernetes NixOS modules.
+      # Maps to `controlPlane.*` options in the NixOS module.
+      # Only relevant for vanilla Kubernetes (k3s manages its own control plane).
+      class ControlPlaneConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        # Extra args for kube-apiserver
+        attribute :api_server_extra_args, T::Hash.default({}.freeze)
+
+        # Extra SANs for the API server certificate
+        attribute :api_server_extra_sans, T::Array.of(T::String).default([].freeze)
+
+        # Extra args for kube-controller-manager
+        attribute :controller_manager_extra_args, T::Hash.default({}.freeze)
+
+        # Extra args for kube-scheduler
+        attribute :scheduler_extra_args, T::Hash.default({}.freeze)
+
+        # Disable kube-proxy (for CNIs that replace it, like Cilium)
+        attribute :disable_kube_proxy, T::Bool.default(false)
+
+        # Extra args for kube-proxy (when not disabled)
+        attribute :kube_proxy_extra_args, T::Hash.default({}.freeze)
+
+        # Use external etcd instead of co-located
+        attribute :etcd_external, T::Bool.default(false)
+
+        # External etcd endpoints
+        attribute :etcd_endpoints, T::Array.of(T::String).default([].freeze)
+
+        # External etcd CA file
+        attribute :etcd_ca_file, T::String.optional.default(nil)
+
+        # External etcd cert file
+        attribute :etcd_cert_file, T::String.optional.default(nil)
+
+        # External etcd key file
+        attribute :etcd_key_file, T::String.optional.default(nil)
+
+        def to_h
+          hash = {}
+          hash[:api_server_extra_args] = api_server_extra_args if api_server_extra_args.any?
+          hash[:api_server_extra_sans] = api_server_extra_sans if api_server_extra_sans.any?
+          hash[:controller_manager_extra_args] = controller_manager_extra_args if controller_manager_extra_args.any?
+          hash[:scheduler_extra_args] = scheduler_extra_args if scheduler_extra_args.any?
+          hash[:disable_kube_proxy] = disable_kube_proxy if disable_kube_proxy
+          hash[:kube_proxy_extra_args] = kube_proxy_extra_args if kube_proxy_extra_args.any?
+          hash[:etcd_external] = etcd_external if etcd_external
+          hash[:etcd_endpoints] = etcd_endpoints if etcd_endpoints.any?
+          hash[:etcd_ca_file] = etcd_ca_file if etcd_ca_file
+          hash[:etcd_cert_file] = etcd_cert_file if etcd_cert_file
+          hash[:etcd_key_file] = etcd_key_file if etcd_key_file
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/etcd_config.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'pangea/resources/types'
+
+module Pangea
+  module Kubernetes
+    module Types
+      # Etcd configuration for blackmatter-kubernetes NixOS modules.
+      # Maps to `etcd.*` options in the NixOS module.
+      # Only relevant for vanilla Kubernetes (k3s embeds etcd).
+      class EtcdConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        # Initial cluster state: 'new' or 'existing'
+        attribute :initial_cluster_state, T::String.constrained(
+          included_in: %w[new existing]
+        ).default('new')
+
+        # Data directory for etcd
+        attribute :data_dir, T::String.default('/var/lib/etcd')
+
+        # External etcd endpoints (when not co-located with control plane)
+        attribute :external_endpoints, T::Array.of(T::String).default([].freeze)
+
+        # Snapshot count before compaction
+        attribute :snapshot_count, T::Coercible::Integer.optional.default(nil)
+
+        # Heartbeat interval in ms
+        attribute :heartbeat_interval, T::Coercible::Integer.optional.default(nil)
+
+        # Election timeout in ms
+        attribute :election_timeout, T::Coercible::Integer.optional.default(nil)
+
+        # CA certificate file path (for external etcd)
+        attribute :ca_file, T::String.optional.default(nil)
+
+        # Client certificate file path (for external etcd)
+        attribute :cert_file, T::String.optional.default(nil)
+
+        # Client key file path (for external etcd)
+        attribute :key_file, T::String.optional.default(nil)
+
+        def external?
+          external_endpoints.any?
+        end
+
+        def to_h
+          hash = {
+            initial_cluster_state: initial_cluster_state,
+            data_dir: data_dir
+          }
+          hash[:external_endpoints] = external_endpoints if external_endpoints.any?
+          hash[:snapshot_count] = snapshot_count if snapshot_count
+          hash[:heartbeat_interval] = heartbeat_interval if heartbeat_interval
+          hash[:election_timeout] = election_timeout if election_timeout
+          hash[:ca_file] = ca_file if ca_file
+          hash[:cert_file] = cert_file if cert_file
+          hash[:key_file] = key_file if key_file
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/firewall_config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'pangea/resources/types'
+
+module Pangea
+  module Kubernetes
+    module Types
+      # Firewall configuration for blackmatter-kubernetes NixOS modules.
+      # Maps to `firewall.*` options in the NixOS module.
+      class FirewallConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        # Enable the firewall module
+        attribute :enabled, T::Bool.default(true)
+
+        # Additional TCP ports to open (beyond K8s defaults)
+        attribute :extra_tcp_ports, T::Array.of(T::Coercible::Integer).default([].freeze)
+
+        # Additional UDP ports to open (beyond K8s defaults)
+        attribute :extra_udp_ports, T::Array.of(T::Coercible::Integer).default([].freeze)
+
+        # Trusted source CIDRs for internal traffic
+        attribute :trusted_cidrs, T::Array.of(T::String).default([].freeze)
+
+        # Allow all intra-cluster traffic
+        attribute :allow_intra_cluster, T::Bool.default(true)
+
+        def to_h
+          hash = { enabled: enabled }
+          hash[:extra_tcp_ports] = extra_tcp_ports if extra_tcp_ports.any?
+          hash[:extra_udp_ports] = extra_udp_ports if extra_udp_ports.any?
+          hash[:trusted_cidrs] = trusted_cidrs if trusted_cidrs.any?
+          hash[:allow_intra_cluster] = allow_intra_cluster
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/k3s_config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'pangea/resources/types'
+require 'pangea/kubernetes/types/firewall_config'
+require 'pangea/kubernetes/types/kernel_config'
+require 'pangea/kubernetes/types/wait_for_dns_config'
+
+module Pangea
+  module Kubernetes
+    module Types
+      # K3s distribution configuration for blackmatter-kubernetes NixOS modules.
+      # Maps to `services.blackmatter.k3s.*` options.
+      # Covers all k3s-specific settings that NixOS modules expose.
+      class K3sConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        # Cluster CIDR for pod networking
+        attribute :cluster_cidr, T::String.optional.default(nil)
+
+        # Service CIDR for service networking
+        attribute :service_cidr, T::String.optional.default(nil)
+
+        # Cluster DNS address
+        attribute :cluster_dns, T::String.optional.default(nil)
+
+        # Node name override
+        attribute :node_name, T::String.optional.default(nil)
+
+        # Node labels (key => value)
+        attribute :node_labels, T::Hash.default({}.freeze)
+
+        # Node taints (array of taint strings, e.g., "key=value:NoSchedule")
+        attribute :node_taints, T::Array.of(T::String).default([].freeze)
+
+        # Node IP address override
+        attribute :node_ip, T::String.optional.default(nil)
+
+        # Extra flags passed to k3s server/agent
+        attribute :extra_flags, T::Array.of(T::String).default([].freeze)
+
+        # Data directory for k3s
+        attribute :data_dir, T::String.optional.default(nil)
+
+        # Config file path for k3s
+        attribute :config_path, T::String.optional.default(nil)
+
+        # Environment file for k3s systemd service
+        attribute :environment_file, T::String.optional.default(nil)
+
+        # Containerd config template path
+        attribute :containerd_config_template, T::String.optional.default(nil)
+
+        # K3s components to disable (e.g., ['traefik', 'servicelb'])
+        attribute :disable, T::Array.of(T::String).default([].freeze)
+
+        # Disable the agent on server nodes
+        attribute :disable_agent, T::Bool.default(false)
+
+        # Extra kubelet args (key => value)
+        attribute :extra_kubelet_config, T::Hash.default({}.freeze)
+
+        # Extra kube-proxy args (key => value)
+        attribute :extra_kube_proxy_config, T::Hash.default({}.freeze)
+
+        # Auto-deploying manifests directory content
+        attribute :manifests, T::Hash.default({}.freeze)
+
+        # Firewall configuration
+        attribute :firewall, FirewallConfig.optional.default(nil)
+
+        # Kernel configuration
+        attribute :kernel, KernelConfig.optional.default(nil)
+
+        # DNS wait configuration
+        attribute :wait_for_dns, WaitForDNSConfig.optional.default(nil)
+
+        # Enable NVIDIA GPU support
+        attribute :nvidia_enable, T::Bool.default(false)
+
+        # Enable graceful node shutdown
+        attribute :graceful_node_shutdown, T::Bool.default(true)
+
+        def to_h
+          hash = {}
+          hash[:cluster_cidr] = cluster_cidr if cluster_cidr
+          hash[:service_cidr] = service_cidr if service_cidr
+          hash[:cluster_dns] = cluster_dns if cluster_dns
+          hash[:node_name] = node_name if node_name
+          hash[:node_labels] = node_labels if node_labels.any?
+          hash[:node_taints] = node_taints if node_taints.any?
+          hash[:node_ip] = node_ip if node_ip
+          hash[:extra_flags] = extra_flags if extra_flags.any?
+          hash[:data_dir] = data_dir if data_dir
+          hash[:config_path] = config_path if config_path
+          hash[:environment_file] = environment_file if environment_file
+          hash[:containerd_config_template] = containerd_config_template if containerd_config_template
+          hash[:disable] = disable if disable.any?
+          hash[:disable_agent] = disable_agent if disable_agent
+          hash[:extra_kubelet_config] = extra_kubelet_config if extra_kubelet_config.any?
+          hash[:extra_kube_proxy_config] = extra_kube_proxy_config if extra_kube_proxy_config.any?
+          hash[:manifests] = manifests if manifests.any?
+          hash[:firewall] = firewall.to_h if firewall
+          hash[:kernel] = kernel.to_h if kernel
+          hash[:wait_for_dns] = wait_for_dns.to_h if wait_for_dns
+          hash[:nvidia_enable] = nvidia_enable if nvidia_enable
+          hash[:graceful_node_shutdown] = graceful_node_shutdown
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pangea/kubernetes/types/kernel_config.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'pangea/resources/types'
+
+module Pangea
+  module Kubernetes
+    module Types
+      # Kernel configuration for blackmatter-kubernetes NixOS modules.
+      # Maps to `kernel.*` options in the NixOS module.
+      class KernelConfig < Pangea::Resources::BaseAttributes
+        transform_keys(&:to_sym)
+
+        # Extra kernel modules to load at boot
+        attribute :extra_modules, T::Array.of(T::String).default([].freeze)
+
+        # Kernel sysctl parameters (key => value)
+        attribute :sysctl, T::Hash.default({}.freeze)
+
+        # Enable kernel hardening (sysctl defaults for K8s)
+        attribute :hardening, T::Bool.default(true)
+
+        def to_h
+          hash = { hardening: hardening }
+          hash[:extra_modules] = extra_modules if extra_modules.any?
+          hash[:sysctl] = sysctl if sysctl.any?
+          hash
+        end
+      end
+    end
+  end
+end