Feat: serviceaccount auth

Replace token-based auth with serviceAccountKey (JSON) across provider, SDK client, validation, docs, samples, and tests; add env flags for endpoint/no-auth.

Author: craigvanaman

README.md

@@ -8,7 +8,7 @@ Out of tree (controller based) implementation for `STACKIT` as a provider for Ga
 
 A Machine Controller Manager (MCM) external provider implementation for STACKIT cloud infrastructure. This provider enables Gardener to manage virtual machines on STACKIT using the declarative Kubernetes API.
 
-The provider was built following the [MCM provider development guidelines](https://github.com/gardener/machine-controller-manager/blob/master/docs/development/cp_support_new.md) and bootstrapped from the [sample provider template](https://github.com/gardener/machine-controller-manager-provider-sampleprovider).Following are the basic principles kept in mind while developing the external plugin.
+The provider was built following the [MCM provider development guidelines](https://github.com/gardener/machine-controller-manager/blob/master/docs/development/cp_support_new.md) and bootstrapped from the [sample provider template](https://github.com/gardener/machine-controller-manager-provider-sampleprovider).
 
 ## Project Structure
 
@@ -59,19 +59,9 @@ This project uses **Hermit** for reproducible development environments and **jus
 hermit shell-hooks
 ```
 
-**just** is the task runner (defined in `justfile`). It provides a cleaner syntax than Make and better task organization:
+**[just](https://github.com/casey/just)** is the task runner (defined in `justfile`):
 
-```sh
-# List all available commands
-just --list
-
-# Or just run 'just' with no arguments
-just
 ```
-
-### Quick Start
-
-```sh
 just build              # Build the provider binary
 just test               # Run unit tests
 just test-e2e           # Run end-to-end tests
@@ -80,16 +70,22 @@ just start              # Run provider locally for debugging
 just docker-build       # Build container image
 ```
 
-**NOTE:** Run `just --list` for more information on all available commands.
+```sh
+# List all available commands
+just --list
+
+# Or just run 'just' with no arguments
+just
+```
 
 ### Deployment
 
 See the [samples/](./samples/) directory for example manifests including:
-- `secret.yaml` - STACKIT credentials configuration
-- `machine-class.yaml` - MachineClass definition
-- `machine.yaml` - Individual Machine example
-- `machine-deployment.yaml` - MachineDeployment for scaled workloads
-- `deployment.yaml` - Provider controller deployment
+- [`secret.yaml`](./samples/secret.yaml) - STACKIT credentials configuration
+- [`machine-class.yaml`](./samples/machine-class.yaml) - MachineClass definition
+- [`machine.yaml`](./samples/machine.yaml) - Individual Machine example
+- [`machine-deployment.yaml`](./samples/machine-deployment.yaml) - MachineDeployment for scaled workloads
+- [`deployment.yaml`](./kubernetes/deployment.yaml) - Provider controller deployment
 
 Deploy using standard kubectl commands:
 
@@ -112,11 +108,24 @@ The provider requires STACKIT credentials to be provided via a Kubernetes Secret
 | Field | Required | Description |
 |-------|----------|-------------|
 | `projectId` | Yes | STACKIT project UUID |
-| `stackitToken` | Yes | STACKIT API authentication token |
+| `serviceAccountKey` | Yes | STACKIT service account credentials (JSON format) |
 | `region` | Yes | STACKIT region (e.g., `eu01-1`, `eu01-2`) |
 | `userData` | No | Default cloud-init user data (can be overridden in ProviderSpec) |
 | `networkId` | No | Default network UUID (can be overridden in ProviderSpec) |
 
+The service account key should be obtained from the STACKIT Portal (Project Settings → Service Accounts → Create Key) and contains JWT credentials and a private key for secure authentication.
+
+### Environment Variables
+
+The provider supports the following environment variables for configuration:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STACKIT_API_ENDPOINT` | (SDK default) | Override STACKIT API endpoint URL (useful for testing) |
+| `STACKIT_NO_AUTH` | `false` | Skip authentication (for testing with mock servers, set to `true`) |
+
+**Note:** `STACKIT_NO_AUTH=true` is only intended for testing environments with mock servers. It skips the authenticaiton step and communicates with the STACKIT API without authenticating itself. Do not use in production.
+
 ## Configuration Reference
 
 ### ProviderSpec Fields
@@ -138,19 +147,6 @@ The provider requires STACKIT credentials to be provided via a Kubernetes Secret
 | `agent` | AgentSpec | No | STACKIT agent configuration |
 | `metadata` | map[string]interface{} | No | Custom metadata key-value pairs |
 
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-### Development Workflow
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/my-feature`
-3. Make changes and add tests
-4. Run verification: `just test && just golang::lint`
-5. Commit with meaningful messages
-6. Push and create a Pull Request
-
 ### Local Testing
 
 Use the local development environment for rapid iteration:

pkg/provider/apis/validation/validation.go

@@ -6,6 +6,7 @@
 package validation
 
 import (
+	"encoding/json"
 	"fmt"
 	"regexp"
 
@@ -52,29 +53,32 @@ func ValidateProviderSpecNSecret(spec *api.ProviderSpec, secrets *corev1.Secret)
 
 	projectID, ok := secrets.Data["projectId"]
 	if !ok {
-		errors = append(errors, fmt.Errorf("secret must contain 'projectId' field"))
+		errors = append(errors, fmt.Errorf("secret field 'projectId' is required"))
 	} else if len(projectID) == 0 {
-		errors = append(errors, fmt.Errorf("secret 'projectId' cannot be empty"))
+		errors = append(errors, fmt.Errorf("secret field 'projectId' cannot be empty"))
 	} else if !isValidUUID(string(projectID)) {
-		errors = append(errors, fmt.Errorf("secret 'projectId' must be a valid UUID"))
+		errors = append(errors, fmt.Errorf("secret field 'projectId' must be a valid UUID"))
 	}
 
-	// Validate stackitToken (required for authentication)
-	stackitToken, ok := secrets.Data["stackitToken"]
+	// Validate serviceAccountKey (required for authentication)
+	// ServiceAccount Key Flow: JSON string containing service account credentials and private key
+	serviceAccountKey, ok := secrets.Data["serviceAccountKey"]
 	if !ok {
-		errors = append(errors, fmt.Errorf("secret must contain 'stackitToken' field"))
-	} else if len(stackitToken) == 0 {
-		errors = append(errors, fmt.Errorf("secret 'stackitToken' cannot be empty"))
+		errors = append(errors, fmt.Errorf("secret field 'serviceAccountKey' is required"))
+	} else if len(serviceAccountKey) == 0 {
+		errors = append(errors, fmt.Errorf("secret field 'serviceAccountKey' cannot be empty"))
+	} else if !isValidJSON(string(serviceAccountKey)) {
+		errors = append(errors, fmt.Errorf("secret field 'serviceAccountKey' must be valid JSON (service account credentials)"))
 	}
 
 	// Validate region (required for SDK)
 	region, ok := secrets.Data["region"]
 	if !ok {
-		errors = append(errors, fmt.Errorf("secret must contain 'region' field"))
+		errors = append(errors, fmt.Errorf("secret field 'region' is required"))
 	} else if len(region) == 0 {
-		errors = append(errors, fmt.Errorf("secret 'region' cannot be empty"))
+		errors = append(errors, fmt.Errorf("secret field 'region' cannot be empty"))
 	} else if !isValidRegion(string(region)) {
-		errors = append(errors, fmt.Errorf("secret 'region' has invalid format (expected format: eu01-1, eu01-2, etc.)"))
+		errors = append(errors, fmt.Errorf("secret field 'region' has invalid format (expected format: eu01-1, eu01-2, etc.)"))
 	}
 
 	// Validate ProviderSpec
@@ -280,3 +284,9 @@ func isValidMachineType(s string) bool {
 func isValidRegion(s string) bool {
 	return regionRegex.MatchString(s)
 }
+
+// isValidJSON checks if a string is valid JSON
+func isValidJSON(s string) bool {
+	var js json.RawMessage
+	return json.Unmarshal([]byte(s), &js) == nil
+}

pkg/provider/apis/validation/validation_core_labels_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})

pkg/provider/apis/validation/validation_fields_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})

pkg/provider/apis/validation/validation_networking_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})

pkg/provider/apis/validation/validation_secgroup_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})

pkg/provider/apis/validation/validation_secret_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})
@@ -60,5 +60,73 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 			Expect(errors).NotTo(BeEmpty())
 			Expect(errors[0].Error()).To(ContainSubstring("projectId' must be a valid UUID"))
 		})
+
+		It("should fail when serviceAccountKey is missing from secret", func() {
+			delete(secret.Data, "serviceAccountKey")
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).NotTo(BeEmpty())
+			Expect(errors[0].Error()).To(ContainSubstring("serviceAccountKey"))
+		})
+
+		It("should fail when serviceAccountKey is empty in secret", func() {
+			secret.Data["serviceAccountKey"] = []byte("")
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).NotTo(BeEmpty())
+			Expect(errors[0].Error()).To(ContainSubstring("serviceAccountKey"))
+		})
+
+		It("should fail when serviceAccountKey is not valid JSON", func() {
+			secret.Data["serviceAccountKey"] = []byte("not-valid-json")
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).NotTo(BeEmpty())
+			Expect(errors[0].Error()).To(ContainSubstring("must be valid JSON"))
+		})
+
+		It("should fail when serviceAccountKey is malformed JSON (missing closing brace)", func() {
+			secret.Data["serviceAccountKey"] = []byte(`{"credentials":{"iss":"test"`)
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).NotTo(BeEmpty())
+			Expect(errors[0].Error()).To(ContainSubstring("must be valid JSON"))
+		})
+
+		It("should pass when serviceAccountKey is valid JSON with minimal structure", func() {
+			secret.Data["serviceAccountKey"] = []byte(`{"credentials":{"iss":"test@sa.stackit.cloud"}}`)
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).To(BeEmpty())
+		})
+
+		It("should pass when serviceAccountKey is valid JSON with full structure", func() {
+			secret.Data["serviceAccountKey"] = []byte(`{
+				"credentials": {
+					"iss": "test@sa.stackit.cloud",
+					"sub": "12345678-1234-1234-1234-123456789012",
+					"aud": "stackit"
+				},
+				"privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQE\n-----END PRIVATE KEY-----"
+			}`)
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			Expect(errors).To(BeEmpty())
+		})
+
+		It("should pass when serviceAccountKey is valid JSON array (edge case)", func() {
+			// JSON validation should accept any valid JSON, even if not the expected structure
+			// The SDK will validate the actual content
+			secret.Data["serviceAccountKey"] = []byte(`[]`)
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			// Should not have JSON validation error (though SDK would fail with this content)
+			for _, err := range errors {
+				Expect(err.Error()).NotTo(ContainSubstring("must be valid JSON"))
+			}
+		})
+
+		It("should pass when serviceAccountKey is valid JSON string (edge case)", func() {
+			// JSON validation should accept any valid JSON, even if not the expected structure
+			secret.Data["serviceAccountKey"] = []byte(`"some-string"`)
+			errors := ValidateProviderSpecNSecret(providerSpec, secret)
+			// Should not have JSON validation error (though SDK would fail with this content)
+			for _, err := range errors {
+				Expect(err.Error()).NotTo(ContainSubstring("must be valid JSON"))
+			}
+		})
 	})
 })

pkg/provider/apis/validation/validation_volumes_test.go

@@ -26,9 +26,9 @@ var _ = Describe("ValidateProviderSpecNSecret", func() {
 		}
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
-				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token"),
-				"region":       []byte("eu01-1"),
+				"projectId":         []byte("11111111-2222-3333-4444-555555555555"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
+				"region":            []byte("eu01-1"),
 			},
 		}
 	})

pkg/provider/core.go

@@ -50,7 +50,7 @@ func (p *Provider) CreateMachine(ctx context.Context, req *driver.CreateMachineR
 
 	// Extract credentials from Secret
 	projectID := string(req.Secret.Data["projectId"])
-	token := string(req.Secret.Data["stackitToken"])
+	serviceAccountKey := string(req.Secret.Data["serviceAccountKey"])
 	region := string(req.Secret.Data["region"])
 
 	// Build labels: merge ProviderSpec labels with MCM-specific labels
@@ -164,7 +164,7 @@ func (p *Provider) CreateMachine(ctx context.Context, req *driver.CreateMachineR
 	}
 
 	// Call STACKIT API to create server
-	server, err := p.client.CreateServer(ctx, token, projectID, region, createReq)
+	server, err := p.client.CreateServer(ctx, serviceAccountKey, projectID, region, createReq)
 	if err != nil {
 		klog.Errorf("Failed to create server for machine %q: %v", req.Machine.Name, err)
 		return nil, status.Error(codes.Internal, fmt.Sprintf("failed to create server: %v", err))
@@ -203,7 +203,7 @@ func (p *Provider) DeleteMachine(ctx context.Context, req *driver.DeleteMachineR
 	}
 
 	// Extract token from Secret for authentication
-	token := string(req.Secret.Data["stackitToken"])
+	serviceAccountKey := string(req.Secret.Data["serviceAccountKey"])
 
 	// Extract region from Secret
 	region := string(req.Secret.Data["region"])
@@ -215,7 +215,7 @@ func (p *Provider) DeleteMachine(ctx context.Context, req *driver.DeleteMachineR
 	}
 
 	// Call STACKIT API to delete server
-	err = p.client.DeleteServer(ctx, token, projectID, region, serverID)
+	err = p.client.DeleteServer(ctx, serviceAccountKey, projectID, region, serverID)
 	if err != nil {
 		// Check if server was not found (404) - this is OK for idempotency
 		if errors.Is(err, ErrServerNotFound) {
@@ -259,7 +259,7 @@ func (p *Provider) GetMachineStatus(ctx context.Context, req *driver.GetMachineS
 	}
 
 	// Extract token from Secret for authentication
-	token := string(req.Secret.Data["stackitToken"])
+	serviceAccountKey := string(req.Secret.Data["serviceAccountKey"])
 
 	// Extract region from Secret
 	region := string(req.Secret.Data["region"])
@@ -272,7 +272,7 @@ func (p *Provider) GetMachineStatus(ctx context.Context, req *driver.GetMachineS
 	}
 
 	// Call STACKIT API to get server status
-	server, err := p.client.GetServer(ctx, token, projectID, region, serverID)
+	server, err := p.client.GetServer(ctx, serviceAccountKey, projectID, region, serverID)
 	if err != nil {
 		// Check if server was not found (404)
 		if errors.Is(err, ErrServerNotFound) {
@@ -310,11 +310,11 @@ func (p *Provider) ListMachines(ctx context.Context, req *driver.ListMachinesReq
 
 	// Extract credentials from Secret
 	projectID := string(req.Secret.Data["projectId"])
-	token := string(req.Secret.Data["stackitToken"])
+	serviceAccountKey := string(req.Secret.Data["serviceAccountKey"])
 	region := string(req.Secret.Data["region"])
 
 	// Call STACKIT API to list all servers
-	servers, err := p.client.ListServers(ctx, token, projectID, region)
+	servers, err := p.client.ListServers(ctx, serviceAccountKey, projectID, region)
 	if err != nil {
 		klog.Errorf("Failed to list servers for MachineClass %q: %v", req.MachineClass.Name, err)
 		return nil, status.Error(codes.Internal, fmt.Sprintf("failed to list servers: %v", err))

pkg/provider/core_create_machine_basic_test.go

@@ -42,7 +42,7 @@ var _ = Describe("CreateMachine", func() {
 		secret = &corev1.Secret{
 			Data: map[string][]byte{
 				"projectId":    []byte("11111111-2222-3333-4444-555555555555"),
-				"stackitToken": []byte("test-token-123"),
+				"serviceAccountKey": []byte(`{"credentials":{"iss":"test"}}`),
 				"region":       []byte("eu01-1"),
 				"networkId":    []byte("770e8400-e29b-41d4-a716-446655440000"),
 			},