From 8fa9919e6a94baad7a96171d2616a942bdc7d7e6 Mon Sep 17 00:00:00 2001 From: Felix Breuer Date: Wed, 25 Feb 2026 14:54:35 +0100 Subject: [PATCH] add documentation about cloudprovider Signed-off-by: Felix Breuer --- README.md | 3 +- docs/cloudprovider.md | 66 ++++++++ hack/api-reference/api.md | 156 ++++++++++-------- pkg/apis/config/types.go | 2 + .../stackit/v1alpha1/types_cloudprofile.go | 65 +++++--- .../stackit/v1alpha1/zz_generated.deepcopy.go | 60 +++---- 6 files changed, 228 insertions(+), 124 deletions(-) create mode 100644 docs/cloudprovider.md diff --git a/README.md b/README.md index 6b3ea010..dd3746cb 100644 --- a/README.md +++ b/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). diff --git a/docs/cloudprovider.md b/docs/cloudprovider.md new file mode 100644 index 00000000..2941d9f3 --- /dev/null +++ b/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---- +type: Opaque +stringData: + project-id: + serviceaccount.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: + 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 +``` diff --git a/hack/api-reference/api.md b/hack/api-reference/api.md index cd050e0e..5229029f 100644 --- a/hack/api-reference/api.md +++ b/hack/api-reference/api.md @@ -51,246 +51,258 @@ string -constraints
+machineImages
- -Constraints + +[]MachineImages -

Constraints is an object containing constraints for certain values in the control plane config.

+

MachineImages is the list of machine images that are understood by the controller. It maps +logical names and versions to provider-specific identifiers.

-dnsServers
+storageClasses
-[]string + +[]StorageClassDefinition + (Optional) -

DNSServers is a list of IPs of DNS servers used while creating subnets.

+

StorageClasses defines storageclasses for the shoot

-dhcpDomain
+rescanBlockStorageOnResize
-string +bool (Optional) -

DHCPDomain is the dhcp domain of the OpenStack system configured in nova.conf. Only meaningful for -Kubernetes 1.10.1+. See https://github.com/kubernetes/kubernetes/pull/61890 for details.

+

RescanBlockStorageOnResize specifies whether the storage plugin scans and checks new block device size before it resizes +the filesystem.

-keystoneURL
+dnsServers
-string +[]string (Optional) -

KeyStoneURL is the URL for auth{n,z} in OpenStack (pointing to KeyStone).

+

DNSServers is a list of IPs of DNS servers used while creating subnets.

-keystoneCACert
+apiEndpoints
-string + +APIEndpoints + (Optional) -

KeystoneCACert is the CA Bundle for the KeyStoneURL.

+

APIEndpoints contains API endpoints for various services (e.g., “LoadBalancer”, “IaaS”).

-keystoneForceInsecure
+caBundle
-bool +string (Optional) -

KeyStoneForceInsecure is a flag to control whether the OpenStack client should perform no certificate validation.

+

CABundle is the CA certificate bundle for API endpoints. +This field is currently ignored and reserved for future use.

-keystoneURLs
+constraints
- -[]KeyStoneURL + +Constraints -(Optional) -

KeyStoneURLs is a region-URL mapping for auth{n,z} in OpenStack (pointing to KeyStone).

+

Constraints is an object containing constraints for certain values in the control plane config.

+

Deprecated: OpenStack-only; not used for STACKIT.

-machineImages
+dhcpDomain
- -[]MachineImages - +string -

MachineImages is the list of machine images that are understood by the controller. It maps -logical names and versions to provider-specific identifiers.

+(Optional) +

DHCPDomain is the dhcp domain of the OpenStack system configured in nova.conf. Only meaningful for +Kubernetes 1.10.1+. See https://github.com/kubernetes/kubernetes/pull/61890 for details.

+

Deprecated: OpenStack-only; not used for STACKIT.

-requestTimeout
+keystoneURL
- -Kubernetes meta/v1.Duration - +string (Optional) -

RequestTimeout specifies the HTTP timeout against the OpenStack API.

+

KeyStoneURL is the URL for auth{n,z} in OpenStack (pointing to KeyStone).

+

Deprecated: OpenStack-only; not used for STACKIT.

-rescanBlockStorageOnResize
+keystoneCACert
-bool +string (Optional) -

RescanBlockStorageOnResize specifies whether the storage plugin scans and checks new block device size before it resizes -the filesystem.

+

KeystoneCACert is the CA Bundle for the KeyStoneURL.

+

Deprecated: OpenStack-only; not used for STACKIT.

-ignoreVolumeAZ
+keystoneForceInsecure
bool (Optional) -

IgnoreVolumeAZ specifies whether the volumes AZ should be ignored when scheduling to nodes, -to allow for differences between volume and compute zone naming.

+

KeyStoneForceInsecure is a flag to control whether the OpenStack client should perform no certificate validation.

+

Deprecated: OpenStack-only; not used for STACKIT.

-nodeVolumeAttachLimit
+keystoneURLs
-int32 + +[]KeyStoneURL + (Optional) -

NodeVolumeAttachLimit specifies how many volumes can be attached to a node.

+

KeyStoneURLs is a region-URL mapping for auth{n,z} in OpenStack (pointing to KeyStone).

+

Deprecated: OpenStack-only; not used for STACKIT.

-useOctavia
+requestTimeout
-bool + +Kubernetes meta/v1.Duration + (Optional) -

UseOctavia specifies whether the OpenStack Octavia network load balancing is used.

-

Deprecated: This field will be removed in future release.

+

RequestTimeout specifies the HTTP timeout against the OpenStack API.

+

Deprecated: OpenStack-only; not used for STACKIT.

-useSNAT
+ignoreVolumeAZ
bool (Optional) -

UseSNAT specifies whether S-NAT is supposed to be used for the Gardener managed OpenStack router.

+

IgnoreVolumeAZ specifies whether the volumes AZ should be ignored when scheduling to nodes,

+

Deprecated: OpenStack-only; not used for STACKIT. +to allow for differences between volume and compute zone naming.

-serverGroupPolicies
+nodeVolumeAttachLimit
-[]string +int32 (Optional) -

ServerGroupPolicies specify the allowed server group policies for worker groups.

+

NodeVolumeAttachLimit specifies how many volumes can be attached to a node.

+

Deprecated: OpenStack-only; not used for STACKIT.

-resolvConfOptions
+useOctavia
-[]string +bool (Optional) -

ResolvConfOptions specifies options to be added to /etc/resolv.conf on workers

+

UseOctavia specifies whether the OpenStack Octavia network load balancing is used.

+

Deprecated: OpenStack-only; not used for STACKIT.

-storageClasses
+useSNAT
- -[]StorageClassDefinition - +bool (Optional) -

StorageClasses defines storageclasses for the shoot

+

UseSNAT specifies whether S-NAT is supposed to be used for the Gardener managed OpenStack router.

+

Deprecated: OpenStack-only; not used for STACKIT.

-apiEndpoints
+serverGroupPolicies
- -APIEndpoints - +[]string (Optional) -

APIEndpoints contains API endpoints for various services (e.g., “LoadBalancer”, “IaaS”).

+

ServerGroupPolicies specify the allowed server group policies for worker groups.

+

Deprecated: OpenStack-only; not used for STACKIT.

-caBundle
+resolvConfOptions
-string +[]string (Optional) -

CABundle is the CA certificate bundle for API endpoints. -This field is currently ignored and reserved for future use.

+

ResolvConfOptions specifies options to be added to /etc/resolv.conf on workers

+

Deprecated: OpenStack-only; not used for STACKIT.

diff --git a/pkg/apis/config/types.go b/pkg/apis/config/types.go index d5191f6b..4eed9a47 100644 --- a/pkg/apis/config/types.go +++ b/pkg/apis/config/types.go @@ -27,6 +27,8 @@ type ControllerConfiguration struct { // RegistryCaches optionally configures a container registry cache(s) that will be // configured on every shoot machine at boot time (and reconciled while its running). + // + // Deprecated: will be removed in a future version RegistryCaches []RegistryCacheConfiguration // DeployALBIngressController diff --git a/pkg/apis/stackit/v1alpha1/types_cloudprofile.go b/pkg/apis/stackit/v1alpha1/types_cloudprofile.go index 5d53d155..e77c2c87 100644 --- a/pkg/apis/stackit/v1alpha1/types_cloudprofile.go +++ b/pkg/apis/stackit/v1alpha1/types_cloudprofile.go @@ -15,69 +15,92 @@ import ( // resource. type CloudProfileConfig struct { metav1.TypeMeta `json:",inline"` - // Constraints is an object containing constraints for certain values in the control plane config. - Constraints Constraints `json:"constraints"` + // MachineImages is the list of machine images that are understood by the controller. It maps + // logical names and versions to provider-specific identifiers. + MachineImages []MachineImages `json:"machineImages"` + // StorageClasses defines storageclasses for the shoot + // +optional + StorageClasses []StorageClassDefinition `json:"storageClasses,omitempty"` + // RescanBlockStorageOnResize specifies whether the storage plugin scans and checks new block device size before it resizes + // the filesystem. + // +optional + RescanBlockStorageOnResize *bool `json:"rescanBlockStorageOnResize,omitempty"` // DNSServers is a list of IPs of DNS servers used while creating subnets. // +optional DNSServers []string `json:"dnsServers,omitempty"` + // APIEndpoints contains API endpoints for various services (e.g., "LoadBalancer", "IaaS"). + // +optional + APIEndpoints *APIEndpoints `json:"apiEndpoints,omitempty"` + // CABundle is the CA certificate bundle for API endpoints. + // This field is currently ignored and reserved for future use. + // +optional + CABundle *string `json:"caBundle,omitempty"` + // Constraints is an object containing constraints for certain values in the control plane config. + // + // Deprecated: OpenStack-only; not used for STACKIT. + Constraints Constraints `json:"constraints"` // DHCPDomain is the dhcp domain of the OpenStack system configured in nova.conf. Only meaningful for // Kubernetes 1.10.1+. See https://github.com/kubernetes/kubernetes/pull/61890 for details. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional DHCPDomain *string `json:"dhcpDomain,omitempty"` // KeyStoneURL is the URL for auth{n,z} in OpenStack (pointing to KeyStone). + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional KeyStoneURL string `json:"keystoneURL,omitempty"` // KeystoneCACert is the CA Bundle for the KeyStoneURL. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional KeyStoneCACert *string `json:"keystoneCACert,omitempty"` // KeyStoneForceInsecure is a flag to control whether the OpenStack client should perform no certificate validation. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional KeyStoneForceInsecure bool `json:"keystoneForceInsecure,omitempty"` // KeyStoneURLs is a region-URL mapping for auth{n,z} in OpenStack (pointing to KeyStone). + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional KeyStoneURLs []KeyStoneURL `json:"keystoneURLs,omitempty"` - // MachineImages is the list of machine images that are understood by the controller. It maps - // logical names and versions to provider-specific identifiers. - MachineImages []MachineImages `json:"machineImages"` // RequestTimeout specifies the HTTP timeout against the OpenStack API. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional RequestTimeout *metav1.Duration `json:"requestTimeout,omitempty"` - // RescanBlockStorageOnResize specifies whether the storage plugin scans and checks new block device size before it resizes - // the filesystem. - // +optional - RescanBlockStorageOnResize *bool `json:"rescanBlockStorageOnResize,omitempty"` // IgnoreVolumeAZ specifies whether the volumes AZ should be ignored when scheduling to nodes, + // + // Deprecated: OpenStack-only; not used for STACKIT. // to allow for differences between volume and compute zone naming. // +optional IgnoreVolumeAZ *bool `json:"ignoreVolumeAZ,omitempty"` // NodeVolumeAttachLimit specifies how many volumes can be attached to a node. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional NodeVolumeAttachLimit *int32 `json:"nodeVolumeAttachLimit,omitempty"` // UseOctavia specifies whether the OpenStack Octavia network load balancing is used. // - // Deprecated: This field will be removed in future release. - // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional UseOctavia *bool `json:"useOctavia,omitempty"` // UseSNAT specifies whether S-NAT is supposed to be used for the Gardener managed OpenStack router. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional UseSNAT *bool `json:"useSNAT,omitempty"` // ServerGroupPolicies specify the allowed server group policies for worker groups. + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional ServerGroupPolicies []string `json:"serverGroupPolicies,omitempty"` // ResolvConfOptions specifies options to be added to /etc/resolv.conf on workers + // + // Deprecated: OpenStack-only; not used for STACKIT. // +optional ResolvConfOptions []string `json:"resolvConfOptions,omitempty"` - // StorageClasses defines storageclasses for the shoot - // +optional - StorageClasses []StorageClassDefinition `json:"storageClasses,omitempty"` - // APIEndpoints contains API endpoints for various services (e.g., "LoadBalancer", "IaaS"). - // +optional - APIEndpoints *APIEndpoints `json:"apiEndpoints,omitempty"` - // CABundle is the CA certificate bundle for API endpoints. - // This field is currently ignored and reserved for future use. - // +optional - CABundle *string `json:"caBundle,omitempty"` } // Constraints is an object containing constraints for the shoots. diff --git a/pkg/apis/stackit/v1alpha1/zz_generated.deepcopy.go b/pkg/apis/stackit/v1alpha1/zz_generated.deepcopy.go index 26c9f300..501a3d1c 100644 --- a/pkg/apis/stackit/v1alpha1/zz_generated.deepcopy.go +++ b/pkg/apis/stackit/v1alpha1/zz_generated.deepcopy.go @@ -134,12 +134,41 @@ func (in *CloudControllerManagerConfig) DeepCopy() *CloudControllerManagerConfig func (in *CloudProfileConfig) DeepCopyInto(out *CloudProfileConfig) { *out = *in out.TypeMeta = in.TypeMeta - in.Constraints.DeepCopyInto(&out.Constraints) + if in.MachineImages != nil { + in, out := &in.MachineImages, &out.MachineImages + *out = make([]MachineImages, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } + if in.StorageClasses != nil { + in, out := &in.StorageClasses, &out.StorageClasses + *out = make([]StorageClassDefinition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } + if in.RescanBlockStorageOnResize != nil { + in, out := &in.RescanBlockStorageOnResize, &out.RescanBlockStorageOnResize + *out = new(bool) + **out = **in + } if in.DNSServers != nil { in, out := &in.DNSServers, &out.DNSServers *out = make([]string, len(*in)) copy(*out, *in) } + if in.APIEndpoints != nil { + in, out := &in.APIEndpoints, &out.APIEndpoints + *out = new(APIEndpoints) + (*in).DeepCopyInto(*out) + } + if in.CABundle != nil { + in, out := &in.CABundle, &out.CABundle + *out = new(string) + **out = **in + } + in.Constraints.DeepCopyInto(&out.Constraints) if in.DHCPDomain != nil { in, out := &in.DHCPDomain, &out.DHCPDomain *out = new(string) @@ -157,23 +186,11 @@ func (in *CloudProfileConfig) DeepCopyInto(out *CloudProfileConfig) { (*in)[i].DeepCopyInto(&(*out)[i]) } } - if in.MachineImages != nil { - in, out := &in.MachineImages, &out.MachineImages - *out = make([]MachineImages, len(*in)) - for i := range *in { - (*in)[i].DeepCopyInto(&(*out)[i]) - } - } if in.RequestTimeout != nil { in, out := &in.RequestTimeout, &out.RequestTimeout *out = new(v1.Duration) **out = **in } - if in.RescanBlockStorageOnResize != nil { - in, out := &in.RescanBlockStorageOnResize, &out.RescanBlockStorageOnResize - *out = new(bool) - **out = **in - } if in.IgnoreVolumeAZ != nil { in, out := &in.IgnoreVolumeAZ, &out.IgnoreVolumeAZ *out = new(bool) @@ -204,23 +221,6 @@ func (in *CloudProfileConfig) DeepCopyInto(out *CloudProfileConfig) { *out = make([]string, len(*in)) copy(*out, *in) } - if in.StorageClasses != nil { - in, out := &in.StorageClasses, &out.StorageClasses - *out = make([]StorageClassDefinition, len(*in)) - for i := range *in { - (*in)[i].DeepCopyInto(&(*out)[i]) - } - } - if in.APIEndpoints != nil { - in, out := &in.APIEndpoints, &out.APIEndpoints - *out = new(APIEndpoints) - (*in).DeepCopyInto(*out) - } - if in.CABundle != nil { - in, out := &in.CABundle, &out.CABundle - *out = new(string) - **out = **in - } return }