Merge branch 'main' into vpc-only-backends

Author: AshleyDumaine

.github/copilot-instructions.md

@@ -0,0 +1,204 @@
+# Cluster API Provider Linode (CAPL) - AI Agent Instructions
+
+## Project Overview
+CAPL is a Kubernetes Cluster API infrastructure provider for Linode/Akamai cloud services. It enables declarative management of Kubernetes clusters on Linode infrastructure using native Kubernetes APIs and follows the Cluster API v1beta1 specification.
+
+## Architecture Patterns
+
+### Controller-Scope-Service Architecture
+All infrastructure resources follow a three-layer pattern:
+1. **Controllers** (`internal/controller/`) - Handle Kubernetes reconciliation events
+2. **Scopes** (`cloud/scope/`) - Encapsulate reconciliation context with both K8s and Linode clients
+3. **Services** (`cloud/services/`) - Abstract Linode API interactions (loadbalancers, domains, object storage)
+
+### Standard Controller Structure
+```go
+func (r *LinodeResourceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+    // 1. Fetch the resource
+    // 2. Create scope with clients: scope.NewResourceScope(ctx, r.LinodeClientConfig, params)
+    // 3. Check pause conditions
+    // 4. Call reconcile helper with proper defer for status updates
+    // 5. Handle errors and events
+}
+```
+
+### Scope Pattern Usage
+Every resource controller creates a scope that manages:
+- Kubernetes client for CRD operations
+- Linode client for API calls
+- Resource references and credentials
+- Patch helpers for status updates
+
+Example: `scope.NewClusterScope()` combines `LinodeCluster` + CAPI `Cluster` resources.
+
+## Key Resource Types
+
+### Core Infrastructure
+- **LinodeCluster**: Cluster networking, load balancers (NodeBalancer/DNS), VPC references, firewalls
+- **LinodeMachine**: Compute instances with placement groups, disk configuration, networking
+- **LinodeVPC**: Virtual Private Cloud with IPv4/IPv6 subnets
+- **LinodeFirewall**: Cloud firewall rules with AddressSet references
+- **LinodePlacementGroup**: Anti-affinity constraints for high availability
+
+### API Design Conventions
+- **Dual Reference Pattern**: Support both direct IDs (`vpcID: 123`) and K8s object refs (`vpcRef: {name: "vpc-1"}`)
+- **Credential References**: All resources support `credentialsRef` for multi-tenancy
+- **Immutable Fields**: Use `+kubebuilder:validation:XValidation:rule="self == oldSelf"` for region, type, etc.
+- **Status Structure**: Always include `ready`, `failureReason`, `failureMessage`, `conditions`
+
+## Development Workflows
+
+### Build & Test Commands
+- `make generate` - Regenerate CRDs and mocks after API changes
+- `make test` - Run unit tests with mocked clients
+- `make e2e E2E_SELECTOR=quick` - Run specific E2E tests using Chainsaw
+- `make lint` - Run golangci-lint with project-specific rules
+- `make build` - Build the controller manager binary
+
+### Adding New Resources
+1. Define API types in `api/v1alpha2/` with proper validation markers
+2. Implement controller in `internal/controller/` following the standard pattern
+3. Add scope in `cloud/scope/` for client management
+4. Add validation webhook in `internal/webhook/v1alpha2/`
+5. Add cloud services in `cloud/services/` if needed
+6. Run `make generate` to update CRDs and mocks
+7. Add E2E tests in `e2e/<resource>-controller/`
+
+### Testing Patterns
+- Unit tests use GoMock with `mock.MockLinodeClient` and `mock.MockK8sClient`
+- Mock expectations pattern: `mockLinodeClient.EXPECT().Method().Return(result, error)`
+- E2E tests use Chainsaw YAML manifests in `e2e/` directories organized by controller and flavors
+- Service tests mock both success and error scenarios from Linode API
+- Test naming uses dynamic identifiers: `(join('-', ['e2e', 'feature', env('GIT_REF')]))`
+- Table-driven tests with `name`, `objects`, `expectedError`, `expectedResult`, `expectations` structure
+
+## Linode Platform Integration
+
+### Load Balancer Types
+- **NodeBalancer**: Linode's managed load balancer for cluster API endpoints
+- **DNS**: Uses Linode or Akamai DNS for API endpoint resolution
+- **External**: For existing external load balancers
+
+### Networking Features
+- **VPC**: Private networking with configurable IPv4/IPv6 subnets
+- **Firewalls**: Cloud firewalls with inbound/outbound rules and AddressSet reuse
+- **Placement Groups**: Anti-affinity for spreading instances across failure domains
+
+### Bootstrap Integration
+- Supports kubeadm, k3s, and rke2 bootstrap providers
+- Uses cloud-init with Linode's metadata service
+- Object storage integration for large bootstrap payloads via pre-signed URLs
+
+## Common Patterns
+
+### Standard Reconciliation Structure
+```go
+func (r *Controller) reconcile(ctx context.Context, scope *ScopeType) (res ctrl.Result, err error) {
+    scope.Resource.Status.Ready = false
+    scope.Resource.Status.FailureReason = nil
+    
+    defer func() {
+        if err != nil {
+            scope.Resource.Status.FailureReason = util.Pointer("ReconcileError")
+            scope.Resource.Status.FailureMessage = util.Pointer(err.Error())
+        }
+        if patchErr := scope.Close(ctx); patchErr != nil {
+            err = errors.Join(err, patchErr)
+        }
+    }()
+    
+    // Add finalizer, handle deletion, or ensure resource
+}
+```
+
+### Error Handling
+```go
+// Ignore specific HTTP errors
+if util.IgnoreLinodeAPIError(err, http.StatusNotFound) != nil {
+    return fmt.Errorf("failed to get resource: %w", err)
+}
+
+// Handle retryable vs terminal errors
+if linodego.ErrHasStatus(err, http.StatusBadRequest) {
+    // Terminal error - set failure reason, don't requeue
+    return ctrl.Result{}, fmt.Errorf("terminal error: %w", err)
+}
+// Retryable error - requeue with backoff
+return ctrl.Result{RequeueAfter: time.Minute * 5}, nil
+```
+
+### Finalizer Management
+Add finalizers early in reconciliation, remove during deletion after cleanup.
+
+### Credential Resolution
+Controllers resolve credentials from `credentialsRef` Secret or default to cluster-wide token.
+
+### Template System
+Cluster templates in `templates/flavors/` define different configurations (VPC vs vpcless, dual-stack networking, etc.).
+
+## Environment Variables
+
+### Core Authentication & API
+- `LINODE_TOKEN`: Primary Linode API authentication token (required)
+- `LINODE_DNS_TOKEN`: Separate token for DNS operations (optional, defaults to LINODE_TOKEN)
+- `LINODE_URL`: Custom Linode API endpoint (optional, for testing/dev environments)
+- `LINODE_DNS_URL`: Custom DNS API endpoint (optional)
+- `LINODE_DNS_CA`: Custom CA certificate for DNS API (optional)
+- `LINODE_CA_BASE64`: Base64-encoded CA certificate for Linode API (optional)
+
+### Akamai Integration
+- `AKAMAI_HOST`: Akamai EdgeRC API hostname
+- `AKAMAI_CLIENT_TOKEN`: Akamai EdgeRC client token  
+- `AKAMAI_CLIENT_SECRET`: Akamai EdgeRC client secret
+- `AKAMAI_ACCESS_TOKEN`: Akamai EdgeRC access token
+
+### Development & Debugging
+- `CAPL_DEBUG`: Enable debug logging and OpenTelemetry tracing (`true`/`false`)
+- `CAPL_MONITORING`: Enable Prometheus metrics and Grafana dashboards (`true`/`false`)
+- `ENABLE_WEBHOOKS`: Enable/disable admission webhooks (`true`/`false`)
+- `GZIP_COMPRESSION_ENABLED`: Enable gzip compression for metadata (`true`/`false`)
+- `SKIP_DOCKER_BUILD`: Skip Docker build in Tilt development (`true`/`false`)
+- `VERSION`: Build version override
+
+### Provider Installation (Tilt Development)
+- `INSTALL_KUBEADM_PROVIDER`: Install kubeadm bootstrap/control-plane providers (`true`/`false`, default: `true`)
+- `INSTALL_HELM_PROVIDER`: Install Cluster API Addon Provider Helm (`true`/`false`, default: `true`)
+- `INSTALL_K3S_PROVIDER`: Install K3s bootstrap/control-plane providers (`true`/`false`, default: `false`)
+- `INSTALL_RKE2_PROVIDER`: Install RKE2 bootstrap/control-plane providers (`true`/`false`, default: `false`)
+
+### Cluster Configuration (Templates)
+- `CLUSTER_NAME`: Name for generated clusters
+- `LINODE_REGION`: Default Linode region (e.g., `us-ord`, `us-sea`)
+- `LINODE_CONTROL_PLANE_MACHINE_TYPE`: Instance type for control plane nodes (e.g., `g6-standard-2`)
+- `LINODE_MACHINE_TYPE`: Instance type for worker nodes (e.g., `g6-standard-2`)
+- `LINODE_SSH_PUBKEY`: SSH public key for cluster node access
+
+### DNS LoadBalancer Configuration
+- `DNS_ROOT_DOMAIN`: Root domain for DNS-based load balancing (e.g., `example.com`)
+- `DNS_UNIQUE_ID`: Unique identifier for DNS records (e.g., `abc123`)
+
+### Backup & Storage
+- `OBJ_BUCKET_REGION`: Object storage region for etcd backups (e.g., `us-ord`)
+- `ETCDBR_IMAGE`: Custom etcd backup/restore controller image
+- `SSE_KEY`: Server-side encryption key for object storage
+
+### E2E Testing
+- `E2E_SELECTOR`: Chainsaw test selector (`quick`, `all`, `flavors`, `linodecluster`, etc.)
+- `E2E_FLAGS`: Additional flags passed to Chainsaw (e.g., `--assert-timeout 10m0s`)
+- `CLUSTER_AUTOSCALER_VERSION`: Version for cluster autoscaler tests (e.g., `v1.29.0`)
+
+### OpenTelemetry Tracing
+Standard OpenTelemetry environment variables are supported via `autoexport` package:
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP endpoint URL
+- `OTEL_EXPORTER_JAEGER_ENDPOINT`: Jaeger endpoint URL  
+- `OTEL_SERVICE_NAME`: Service name for traces
+- `OTEL_RESOURCE_ATTRIBUTES`: Additional resource attributes
+
+## Debugging Tips
+- Check controller logs for reconciliation errors and API failures
+- Verify Linode API permissions and regional capabilities  
+- Use `kubectl describe` on resources to see status conditions and events
+- E2E test failures often indicate webhook validation or API compatibility issues
+- Enable debug logging with `CAPL_DEBUG=true` for detailed tracing
+- Validate CRDs are current with `make generate` after API changes
+- Generate local-release whenever making changes to the /templates directory. Use command `make local-release` to generate the release files.

.github/workflows/e2e-test.yaml

@@ -135,6 +135,7 @@ jobs:
           LINODE_CONTROL_PLANE_MACHINE_TYPE: g6-standard-2
           LINODE_MACHINE_TYPE: g6-standard-2
           CLUSTERCTL_CONFIG: /home/runner/work/cluster-api-provider-linode/cluster-api-provider-linode/e2e/gha-clusterctl-config.yaml
+          LINODE_CLIENT_TIMEOUT: 30
         run: make e2etest
 
       - name: cleanup stale clusters

Tiltfile

@@ -196,6 +196,13 @@ for resource in manager_yaml:
         resource["spec"]["template"]["spec"].pop("securityContext")
         for container in resource["spec"]["template"]["spec"]["containers"]:
             container.pop("securityContext")
+            timeout_value = os.getenv("LINODE_CLIENT_TIMEOUT")
+            if timeout_value:
+                env = container.setdefault("env", [])
+                env.append({
+                    "name": "LINODE_CLIENT_TIMEOUT",
+                    "value": timeout_value
+                })
 
 k8s_yaml(encode_yaml_stream(manager_yaml))
 

api/v1alpha2/linodemachine_types.go

@@ -111,6 +111,45 @@ type LinodeMachineSpec struct {
 	// VPCID is the ID of an existing VPC in Linode. This allows using a VPC that is not managed by CAPL.
 	// +optional
 	VPCID *int `json:"vpcID,omitempty"`
+
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
+	// IPv6Options defines the IPv6 options for the instance.
+	// If not specified, IPv6 ranges won't be allocated to instance.
+	// +optional
+	IPv6Options *IPv6CreateOptions `json:"ipv6Options,omitempty"`
+
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
+	// +optional
+	// NetworkHelper is an option usually enabled on account level. It helps configure networking automatically for instances.
+	// You can use this to enable/disable the network helper for a specific instance.
+	// For more information, see https://techdocs.akamai.com/cloud-computing/docs/automatically-configure-networking
+	// Defaults to true.
+	NetworkHelper *bool `json:"networkHelper,omitempty"`
+}
+
+// IPv6CreateOptions defines the IPv6 options for the instance.
+type IPv6CreateOptions struct {
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
+	// EnableSLAAC is an option to enable SLAAC (Stateless Address Autoconfiguration) for the instance.
+	// This is useful for IPv6 addresses, allowing the instance to automatically configure its own IPv6 address.
+	// Defaults to false.
+	// +optional
+	EnableSLAAC *bool `json:"enableSLAAC,omitempty"`
+
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
+	// EnableRanges is an option to enable IPv6 ranges for the instance.
+	// If set to true, the instance will have a range of IPv6 addresses.
+	// This is useful for instances that require multiple IPv6 addresses.
+	// Defaults to false.
+	// +optional
+	EnableRanges *bool `json:"enableRanges,omitempty"`
+
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
+	// IsPublicIPv6 is an option to enable public IPv6 for the instance.
+	// If set to true, the instance will have a publicly routable IPv6 range.
+	// Defaults to false.
+	// +optional
+	IsPublicIPv6 *bool `json:"isPublicIPv6,omitempty"`
 }
 
 // InstanceDisk defines a list of disks to use for an instance

api/v1alpha2/zz_generated.deepcopy.go

@@ -174,7 +174,11 @@ func EnsureLinodeDNSEntries(ctx context.Context, cscope *scope.ClusterScope, ope
 	if err != nil {
 		return err
 	}
-	domainRecords, err := cscope.LinodeDomainsClient.ListDomainRecords(ctx, domainID, linodego.NewListOptions(0, string(filter)))
+
+	listOptions := linodego.NewListOptions(0, string(filter))
+	listOptions.PageSize = 500 // set a high page size to avoid multiple requests
+
+	domainRecords, err := cscope.LinodeDomainsClient.ListDomainRecords(ctx, domainID, listOptions)
 	if err != nil {
 		return err
 	}

cloud/services/domains.go

@@ -178,8 +178,23 @@ func validateEnvironment() (linodeConfig, dnsConfig scope.ClientConfig) {
 		linodeDNSToken = linodeToken
 	}
 
-	return scope.ClientConfig{Token: linodeToken},
-		scope.ClientConfig{Token: linodeDNSToken, BaseUrl: linodeDNSURL, RootCertificatePath: linodeDNSCA}
+	linodeClientTimeout := 0
+	if raw, ok := os.LookupEnv("LINODE_CLIENT_TIMEOUT"); ok {
+		if timeout, err := strconv.Atoi(raw); timeout > 0 && err == nil {
+			linodeClientTimeout = timeout
+			setupLog.Info("LINODE_CLIENT_TIMEOUT set", "timeout", linodeClientTimeout)
+		} else {
+			setupLog.Error(fmt.Errorf("invalid LINODE_CLIENT_TIMEOUT value: %s", raw), "using default timeout")
+		}
+	}
+
+	linodeConfig = scope.ClientConfig{Token: linodeToken}
+	dnsConfig = scope.ClientConfig{Token: linodeDNSToken, BaseUrl: linodeDNSURL, RootCertificatePath: linodeDNSCA}
+	if linodeClientTimeout > 0 {
+		linodeConfig.Timeout = time.Duration(linodeClientTimeout) * time.Second
+		dnsConfig.Timeout = time.Duration(linodeClientTimeout) * time.Second
+	}
+	return linodeConfig, dnsConfig
 }
 
 // setupManager initializes and returns a new manager instance with the provided configurations.