README
¶
machine-controller-manager-provider-stackit
Out of tree (controller based) implementation for STACKIT as a provider for Gardener.
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 and bootstrapped from the sample provider template.
Project Structure
machine-controller-manager-provider-stackit/
├── cmd/
│ └── machine-controller/
│ └── main.go # Provider entrypoint
├── pkg/
│ ├── provider/
│ │ ├── core.go # Core provider implementation
│ │ ├── provider.go # Driver interface implementation
│ │ ├── stackit_client.go # STACKIT client interface
│ │ ├── sdk_client.go # STACKIT SDK wrapper implementation
│ │ ├── helpers.go # SDK type conversion utilities
│ │ ├── apis/
│ │ │ ├── provider_spec.go # ProviderSpec CRD definitions
│ │ │ └── validation/ # Field validation logic
│ │ └── *_test.go # Unit tests
│ └── spi/
│ └── spi.go # Service provider interface
├── test/
│ └── e2e/ # End-to-end integration tests
├── samples/ # Example manifests
├── kubernetes/ # Deployment manifests
└── vendor/ # Go module dependencies
Getting Started
Deployment
See the samples/ directory for example manifests including:
secret.yaml- STACKIT credentials configurationmachine-class.yaml- MachineClass definitionmachine.yaml- Individual Machine examplemachine-deployment.yaml- MachineDeployment for scaled workloadsdeployment.yaml- Provider controller deployment
Deploy using standard kubectl commands:
kubectl apply -f samples/secret.yaml
kubectl apply -f samples/machine-class.yaml
kubectl apply -f samples/machine.yaml
STACKIT SDK Integration
This provider uses the official STACKIT Go SDK for all interactions with the STACKIT IaaS API. The SDK provides type-safe API access, built-in authentication handling, and is officially maintained by STACKIT.
Each provider instance is bound to a single STACKIT project via the service account credentials provided in the Secret. The SDK client is initialized once on first use and automatically handles token refresh. In Gardener deployments, each shoot cluster gets its own control plane with a dedicated MCM and provider instance.
Authentication & Credentials
The provider requires STACKIT credentials to be provided via a Kubernetes Secret. The Secret must contain the following fields:
| Field | Required | Description |
|---|---|---|
projectId |
Yes | STACKIT project UUID |
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.
Credential Rotation: The provider captures credentials on first use and reuses the same STACKIT SDK client for all subsequent requests (the SDK automatically handles token refresh). If the Secret is updated with new credentials, the provider pod must be restarted to pick up the changes. This follows the standard Kubernetes pattern for credential rotation.
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
| Field | Type | Required | Description |
|---|---|---|---|
machineType |
string | Yes | STACKIT server type (e.g., "c2i.2", "m2i.8") |
imageId |
string | Yes | UUID of the OS image |
labels |
map[string]string | No | Labels for server identification |
networking |
NetworkingSpec | No | Network configuration (NetworkID or NICIDs) |
securityGroups |
[]string | No | Security group names |
userData |
string | No | Cloud-init user data (overrides Secret.userData) |
bootVolume |
BootVolumeSpec | No | Boot disk configuration |
volumes |
[]string | No | UUIDs of additional volumes to attach |
keypairName |
string | No | SSH keypair name |
availabilityZone |
string | No | Availability zone (e.g., "eu01-1") |
affinityGroup |
string | No | UUID of affinity group |
serviceAccountMails |
[]string | No | Service account email addresses (max 1) |
agent |
AgentSpec | No | STACKIT agent configuration |
metadata |
map[string]interface{} | No | Custom metadata key-value pairs |
Local Testing
Use the local development environment for rapid iteration:
# Set up dev environment
just dev
# Or run provider locally for debugging
just start
References
Machine Controller Manager
- Machine Controller Manager - Core MCM project
- MCM Provider Development Guide - Guidelines followed to build this provider
- MCM Sample Provider - Original template used as starting point
- MCM Driver Interface - Provider contract interface
STACKIT SDK
- STACKIT SDK Go - Official STACKIT Go SDK
- IaaS Service Package - IaaS service API documentation
- SDK Core Package - Core SDK configuration and authentication
- SDK Examples - Code examples and usage patterns
- SDK Releases - Release notes and changelog
STACKIT Platform
- STACKIT Documentation - STACKIT cloud platform documentation
- STACKIT Portal - STACKIT management console
- Service Accounts - Creating and managing service accounts
- Service Account Keys - API authentication setup
- IaaS API Documentation - STACKIT IaaS REST API reference
Directories