Add usage documentations

docs/operations/operations.md

@@ -0,0 +1,69 @@
+# Using the STACKIT provider extension with Gardener as operator
+
+The [`core.gardener.cloud/v1beta1.CloudProfile` resource](https://github.com/gardener/gardener/blob/master/example/30-cloudprofile.yaml) declares a `providerConfig` field that is meant to contain provider-specific configuration.
+
+In this document we are describing how this configuration looks like for STACKIT and provide an example `CloudProfile` manifest with minimal configuration that you can use to allow creating STACKIT shoot clusters.
+
+
+## `CloudProfileConfig`
+
+The cloud profile configuration contains information about the real machine image IDs in the STACKIT environment (image names).
+You have to map every version that you specify in `.spec.machineImages[].versions` here such that the STACKIT extension knows the image ID for every version you want to offer.
+
+TODO: ask about storageclass, where can i find what type of storage class exist and what imp thing to mention.
+
+It also contains optional default values for DNS servers that shall be used for shoots.
+In the `dnsServers[]` list you can specify IP addresses that are used as DNS configuration for created shoot subnets.
+
+Some hypervisors (especially those which are VMware-based) don't automatically send a new volume size to a Linux kernel when a volume is resized and in-use.
+For those hypervisors you can enable the storage plugin interacting with Cinder to telling the SCSI block device to refresh its information to provide information about it's updated size to the kernel. You might need to enable this behavior depending on the underlying hypervisor of your STACKIT installation. The `rescanBlockStorageOnResize` field controls this. Please note that it only applies for Kubernetes versions where CSI is used.
+
+You can specify API endpoints for various STACKIT services(IaaS, LoadBalancer), via `APIEndpoints`.
+
+## Example `CloudProfile` manifest
+
+The following example shows a minimal `CloudProfile` configuration for STACKIT:
+
+```yaml
+apiVersion: core.gardener.cloud/v1beta1
+kind: CloudProfile
+metadata:
+  name: stackit
+spec:
+  type: stackit
+  kubernetes:
+    versions:
+    - version: 1.35.6
+  machineImages:
+  - name: coreos
+    versions:
+    - version: 4593.2.2
+      architectures:
+      - amd64
+  machineTypes:
+  - name: g1.2
+    cpu: "2"
+    gpu: "0"
+    memory: 8Gi
+    architecture: amd64
+    storage:
+      class: storage_premium_perf1
+      type: storage_premium_perf1
+      size: 50Gi
+  regions:
+  - name: RegionOne
+    zones:
+    - name: eu01-1
+  providerConfig:
+    apiVersion: stackit.provider.extensions.gardener.cloud/v1alpha1
+    kind: CloudProfileConfig
+    machineImages:
+    - name: coreos
+      versions:
+      - version: 4593.2.2
+        regions:
+        - name: RegionOne
+          architecture: amd64
+          id: <STACKIT_IMAGE_ID>
+	storageClasses: TODO: add it after clarification.
+

docs/usage/usage.md

@@ -0,0 +1,99 @@
+# Using the STACKIT provider extension with Gardener as end-user
+
+## STACKIT Workload Identity with Gardener
+
+This extension automatically deploys and configures the `stackit-pod-identity-webhook` in your SKE cluster's control plane, enabling workloads to use STACKIT Workload Identity.
+
+### What this extension provides
+
+- Automatic deployment of the `stackit-pod-identity-webhook` in the Shoot control plane
+- Webhook configuration to inject STACKIT authentication into Pods
+- TLS setup for webhook communication with the Kubernetes API server
+
+No manual webhook installation is required — the extension handles this for you.
+
+### Quick start
+
+**Prerequisites:**
+
+- An SKE cluster with Workload Identity support enabled
+- A STACKIT Service Account with appropriate permissions
+- A federated identity configured in the STACKIT IdP
+
+#### Create a federated identity in STACKIT
+
+Retrieve your cluster's OIDC issuer:
+
+```bash
+stackit ske cluster describe -p <PROJECT_ID> <CLUSTER_NAME> -o json \
+  | jq -r '.status.serviceAccountIssuer'
+```
+
+Create a Federated Identity Provider in the STACKIT Portal using this issuer URL. Restrict the federation with the Kubernetes `sub` claim: `system:serviceaccount:<namespace>:<service-account-name>`
+
+#### Annotate your Kubernetes `ServiceAccount`
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: app
+  namespace: default
+  annotations:
+    workload-identity.stackit.cloud/service-account-email: "my-service-account@sa.stackit.cloud"
+```
+
+Pods using this `ServiceAccount` will automatically have STACKIT authentication injected.
+
+### Supported annotations
+
+| Annotation | Default | Description |
+| --- | --- | --- |
+| `workload-identity.stackit.cloud/service-account-email` | None | STACKIT Service Account email to assume. **Required.** |
+| `workload-identity.stackit.cloud/audience` | `sts.accounts.stackit.cloud` | Audience for the token. |
+| `workload-identity.stackit.cloud/service-account-token-expiration-seconds` | `600` | Token lifetime in seconds. |
+| `workload-identity.stackit.cloud/idp-token-endpoint` | `https://accounts.stackit.cloud/oauth/v2/token` | Token exchange endpoint. |
+
+Opt out of mutation with: `workload-identity.stackit.cloud/skip-pod-identity-webhook: "true"` label on Pod or Namespace.
+
+### Learn more
+
+For detailed information about STACKIT Workload Identity, see the [STACKIT documentation](https://docs.stackit.cloud/products/runtime/kubernetes-engine/how-tos/workload-identity/).
+
+### References
+
+- [STACKIT Service Account Federation](https://docs.stackit.cloud/platform/access-and-identity/service-accounts/how-tos/manage-service-account-federations/)
+- [`stackit-pod-identity-webhook`](https://github.com/stackitcloud/stackit-pod-identity-webhook)
+- [Gardener Managed Service Account Issuer](https://gardener.cloud/docs/gardener/security/shoot_serviceaccounts/#managed-service-account-issuer)
+- [Kubernetes ServiceAccount token projection](https://kubernetes.io/docs/concepts/storage/projected-volumes/#serviceaccounttoken)
+
+
+## STACKIT Application Load Balancer
+
+This extension automatically deploys and configures the STACKIT Application Load Balancer (ALB) Controller in your SKE cluster's control plane, enabling workloads to create Application Load Balancers using Kubernetes `Ingress` resources.
+
+### Quick start
+
+Refer to [usage doc](https://github.com/stackitcloud/application-load-balancer-controller/blob/main/docs/user.md) of Application Load Balancer for setup. 
+
+### Enable the extension
+
+The Application Load Balancer extension can be enables by ControlPlaneConfig of the shoot:
+
+```yaml
+extensions:
+  applicationLoadBalancer:
+    enabled: true
+  	ingress:
+	  enabled: true
+```
+
+NOTE: Ingress support needs to be enabled in order to use Application Load Balancer extension.
+
+### Learn more
+
+For more information about the STACKIT Application Load Balancer Controller, see the [`application-load-balancer-controller`](https://github.com/stackitcloud/application-load-balancer-controller) repository.
+
+# Migrate from Openstack to STACKIT provider
+
+We still have openstack code runnnig in the repository, and in future it will be fully migrated and use stackit provider.