add documentation about cloudprovider

README.md

@@ -23,6 +23,7 @@ You can find all available make targets by running `make help`.
 
 For information on our workflows, see:
 
+* [Cloudprovider configuration guide](docs/cloudprovider.md)
 * [Development guide](docs/development.md)
 * [Testing guide](docs/testing.md)
 * [Release procedure](docs/releases.md)
@@ -32,4 +33,4 @@ For information on our workflows, see:
 Feedback and contributions are always welcome. Please report bugs or
 suggestions as GitHub issues.
 
-Please report bugs or suggestions as GitHub issues or reach out on [Slack](https://gardener-cloud.slack.com/) in the `stackit` channel (join the workspace [here](https://gardener.cloud/community/)).
+Please report bugs or suggestions as GitHub issues or reach out on [Slack](https://gardener-cloud.slack.com/) in the `stackit` channel ([join](https://gardener.cloud/community/) the workspace).

docs/cloudprovider.md

@@ -0,0 +1,66 @@
+# CloudProvider Configuration
+
+This document describes the CloudProvider configuration for the STACKIT Gardener Extension, including the cloudprovider secret and the `CloudProfileConfig`.
+
+## CloudProvider Secret
+
+The cloudprovider secret requires the following fields:
+
+| Field                | Key                   | Description                                | Required |
+| -------------------- | --------------------- | ------------------------------------------ | -------- |
+| Project ID           | `project-id`          | project identifier                         | Yes      |
+| Service Account JSON | `serviceaccount.json` | service account credentials in JSON format | Yes      |
+
+**Example Secret:**
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: cloudprovider
+  namespace: shoot--<project>--<cluster>
+type: Opaque
+stringData:
+  project-id: <project-id>
+  serviceaccount.json: <sa-json>
+```
+
+The service account needs the following permissions:
+
+| Permission                     | Purpose                               |
+| ------------------------------ | ------------------------------------- |
+| `nlb.admin`                    | create network load balancer          |
+| `blockstorage.admin`           | CSI driver                            |
+| `compute.admin`                | CCM node-controller                   |
+| `iaas.network.admin`           | bastion and infrastructure controller |
+| `iaas.isoplated-network.admin` | infrastructure controller             |
+
+## CloudProfileConfig Fields
+
+Example with comments:
+
+```yaml
+providerConfig:
+  # image mappings used for bastion and workers
+  machineImages:
+    - name: ubuntu
+      versions:
+        - version: "22.04"
+          regions:
+            - name: eu01
+              # provider-specific image ID
+              id: <image-id>
+              architecture: amd64
+  # rescan block devices after resize
+  rescanBlockStorageOnResize: true
+  # list of IPs of DNS servers used while creating subnets
+  dnsServers:
+    - 1.1.1.1
+  # shoot storage classes
+  storageClasses:
+    - name: default
+      default: true
+      parameters:
+        type: "storage_premium_perf4"
+      provisioner: block-storage.csi.stackit.cloud
+```