This is the multi-page printable view of this section. Click here to print.
Docs
1 - Gardener
Documentation Index
Overview
- General Architecture
- Gardener landing page
gardener.cloud
- “Gardener, the Kubernetes Botanist” blog on kubernetes.io
- “Gardener Project Update” blog on kubernetes.io
Concepts
Usage
- Audit a Kubernetes cluster
- Auto-Scaling for shoot clusters
- Cleanup of Shoot clusters in deletion
containerd
Registry Configuration- Custom
containerd
configuration - Custom
CoreDNS
configuration - (Custom) CSI components
- Default Seccomp Profile
- DNS Autoscaling
- DNS Search Path Optimization
- Endpoints and Ports of a Shoot Control-Plane
- ExposureClasses
- Hibernate a Cluster
- IPv6 in Gardener Clusters
- Logging
NodeLocalDNS
feature- OpenIDConnect presets
- Projects
- Service Account Manager
- Readiness of Shoot Worker Nodes
- Reversed Cluster VPN
- Shoot Cluster Purposes
- Shoot Scheduling Profiles
- Shoot Credentials Rotation
- Shoot Kubernetes and Operating System Versioning
- Shoot
KUBERNETES_SERVICE_HOST
Environment Variable Injection - Shoot Networking
- Shoot Maintenance
- Shoot
ServiceAccount
Configurations - Shoot Status
- Shoot Info
ConfigMap
- Shoot Updates and Upgrades
- Shoot HA Control Plane
- Shoot HA Best Practices
- Shoot Workers Settings
- Accessing Shoot Clusters
- Supported Kubernetes versions
- Tolerations
- Trigger shoot operations
- Trusted TLS certificate for shoot control planes
- Trusted TLS certificate for garden runtime cluster
- Controlling the Kubernetes versions for specific worker pools
- Migrating from
PodSecurityPolicy
s to PodSecurity admission controller - Supported CPU Architectures for Shoot Worker Nodes
- Workerless
Shoot
s
API Reference
authentication.gardener.cloud
API Groupcore.gardener.cloud
API Groupextensions.gardener.cloud
API Groupoperations.gardener.cloud
API Groupresources.gardener.cloud
API Groupseedmanagement.gardener.cloud
API Groupsettings.gardener.cloud
API Group
Proposals
- GEP: Gardener Enhancement Proposal Description
- GEP: Template
- GEP-1: Gardener extensibility and extraction of cloud-specific/OS-specific knowledge
- GEP-2:
BackupInfrastructure
CRD and Controller Redesign - GEP-3: Network extensibility
- GEP-4: New
core.gardener.cloud/v1beta1
APIs required to extract cloud-specific/OS-specific knowledge out of Gardener core - GEP-5: Gardener Versioning Policy
- GEP-6: Integrating etcd-druid with Gardener
- GEP-7: Shoot Control Plane Migration
- GEP-8: SNI Passthrough proxy for kube-apiservers
- GEP-9: Gardener integration test framework
- GEP-10: Support additional container runtimes
- GEP-11: Utilize API Server Network Proxy to Invert Seed-to-Shoot Connectivity
- GEP-12: OIDC Webhook Authenticator
- GEP-13: Automated Seed Management
- GEP-14: Reversed Cluster VPN
- GEP-15: Manage Bastions and SSH Key Pair Rotation
- GEP-16: Dynamic kubeconfig generation for Shoot clusters
- GEP-17: Shoot Control Plane Migration “Bad Case” Scenario
- GEP-18: Automated Shoot CA Rotation
- GEP-19: Observability Stack - Migrating to the prometheus-operator and fluent-bit operator
- GEP-20: Highly Available Shoot Control Planes
- GEP-21: IPv6 Single-Stack Support in Local Gardener
- GEP-22: Improved Usage of the
ShootState
API - GEP-23: Autoscaling Shoot kube-apiserver via Independently Driven HPA and VPA
Development
- Getting started locally (using the local provider)
- Setting up a development environment (using a cloud provider)
- Testing (Unit, Integration, E2E Tests)
- Test Machinery Tests
- Dependency Management
- Kubernetes Clients in Gardener
- Logging in Gardener Components
- Changing the API
- Secrets Management for Seed and Shoot Clusters
- Releases, Features, Hotfixes
- Adding New Cloud Providers
- Adding Support For A New Kubernetes Version
- Extending the Monitoring Stack
- How to create log parser for container into fluent-bit
PriorityClasses
in Gardener Clusters- High Availability Of Deployed Components
- Checklist For Adding New Components
Extensions
- Extensibility overview
- Extension controller registration
Cluster
resource- Extension points
- General conventions
- Trigger for reconcile operations
- Deploy resources into the shoot cluster
- Shoot resource customization webhooks
- Logging and monitoring for extensions
- Contributing to shoot health status conditions
- CA Rotation in Extensions
- Blob storage providers
- DNS providers
- IaaS/Cloud providers
- Network plugin providers
- Operating systems
- Container runtimes
- Generic (non-essential) extensions
- Extension Admission
- Heartbeat controller
- Provider Local
- Access to the Garden Cluster
- Control plane migration
- Force Deletion
- Extending project roles
- Referenced resources
Deployment
- Getting started locally
- Getting started locally with extensions
- Setup Gardener on a Kubernetes cluster
- Version Skew Policy
- Deploying Gardenlets
- Overwrite image vector
- Migration from Gardener
v0
tov1
- Feature Gates in Gardener
- Configuring the Logging stack
- SecretBinding Provider Controller
Operations
- Gardener configuration and usage
- Control Plane Migration
- Istio
- Register Shoot as Seed
NetworkPolicy
s In Garden, Seed, Shoot Clusters- Seed Bootstrapping
- Seed Settings
- Topology-Aware Traffic Routing
Monitoring
1.1 - API Reference
1.1.1 - Api Reference
Gardener API Reference
1.1.2 - Authentication
Packages:
authentication.gardener.cloud/v1alpha1
Package v1alpha1 is a version of the API.
Resource Types:AdminKubeconfigRequest
AdminKubeconfigRequest can be used to request a kubeconfig with admin credentials for a Shoot cluster.
Field | Description | ||
---|---|---|---|
apiVersion string | authentication.gardener.cloud/v1alpha1 | ||
kind string | AdminKubeconfigRequest | ||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||
spec AdminKubeconfigRequestSpec | Spec is the specification of the AdminKubeconfigRequest.
| ||
status AdminKubeconfigRequestStatus | Status is the status of the AdminKubeconfigRequest. |
ViewerKubeconfigRequest
ViewerKubeconfigRequest can be used to request a kubeconfig with viewer credentials (excluding Secrets) for a Shoot cluster.
Field | Description | ||
---|---|---|---|
apiVersion string | authentication.gardener.cloud/v1alpha1 | ||
kind string | ViewerKubeconfigRequest | ||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||
spec ViewerKubeconfigRequestSpec | Spec is the specification of the ViewerKubeconfigRequest.
| ||
status ViewerKubeconfigRequestStatus | Status is the status of the ViewerKubeconfigRequest. |
AdminKubeconfigRequestSpec
(Appears on: AdminKubeconfigRequest)
AdminKubeconfigRequestSpec contains the expiration time of the kubeconfig.
Field | Description |
---|---|
expirationSeconds int64 | (Optional) ExpirationSeconds is the requested validity duration of the credential. The credential issuer may return a credential with a different validity duration so a client needs to check the ‘expirationTimestamp’ field in a response. Defaults to 1 hour. |
AdminKubeconfigRequestStatus
(Appears on: AdminKubeconfigRequest)
AdminKubeconfigRequestStatus is the status of the AdminKubeconfigRequest containing the kubeconfig and expiration of the credential.
Field | Description |
---|---|
kubeconfig []byte | Kubeconfig contains the kubeconfig with cluster-admin privileges for the shoot cluster. |
expirationTimestamp Kubernetes meta/v1.Time | ExpirationTimestamp is the expiration timestamp of the returned credential. |
ViewerKubeconfigRequestSpec
(Appears on: ViewerKubeconfigRequest)
ViewerKubeconfigRequestSpec contains the expiration time of the kubeconfig.
Field | Description |
---|---|
expirationSeconds int64 | (Optional) ExpirationSeconds is the requested validity duration of the credential. The credential issuer may return a credential with a different validity duration so a client needs to check the ‘expirationTimestamp’ field in a response. Defaults to 1 hour. |
ViewerKubeconfigRequestStatus
(Appears on: ViewerKubeconfigRequest)
ViewerKubeconfigRequestStatus is the status of the ViewerKubeconfigRequest containing the kubeconfig and expiration of the credential.
Field | Description |
---|---|
kubeconfig []byte | Kubeconfig contains the kubeconfig with viewer privileges (excluding Secrets) for the shoot cluster. |
expirationTimestamp Kubernetes meta/v1.Time | ExpirationTimestamp is the expiration timestamp of the returned credential. |
Generated with gen-crd-api-reference-docs
1.1.3 - Core
Packages:
core.gardener.cloud/v1beta1
Package v1beta1 is a version of the API.
Resource Types:- BackupBucket
- BackupEntry
- CloudProfile
- ControllerDeployment
- ControllerInstallation
- ControllerRegistration
- ExposureClass
- InternalSecret
- Project
- Quota
- SecretBinding
- Seed
- Shoot
- ShootState
BackupBucket
BackupBucket holds details about backup bucket
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||||
kind string | BackupBucket | ||||||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||
spec BackupBucketSpec | Specification of the Backup Bucket.
| ||||||||
status BackupBucketStatus | Most recently observed status of the Backup Bucket. |
BackupEntry
BackupEntry holds details about shoot backup.
Field | Description | ||||
---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||
kind string | BackupEntry | ||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec BackupEntrySpec | (Optional) Spec contains the specification of the Backup Entry.
| ||||
status BackupEntryStatus | (Optional) Status contains the most recently observed status of the Backup Entry. |
CloudProfile
CloudProfile represents certain properties about a provider environment.
Field | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||||||||||||||
kind string | CloudProfile | ||||||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||
spec CloudProfileSpec | (Optional) Spec defines the provider environment properties.
|
ControllerDeployment
ControllerDeployment contains information about how this controller is deployed.
Field | Description |
---|---|
apiVersion string | core.gardener.cloud/v1beta1 |
kind string | ControllerDeployment |
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. |
type string | Type is the deployment type. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | ProviderConfig contains type-specific configuration. It contains assets that deploy the controller. |
ControllerInstallation
ControllerInstallation represents an installation request for an external controller.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||
kind string | ControllerInstallation | ||||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||
spec ControllerInstallationSpec | Spec contains the specification of this installation. If the object’s deletion timestamp is set, this field is immutable.
| ||||||
status ControllerInstallationStatus | Status contains the status of this installation. |
ControllerRegistration
ControllerRegistration represents a registration of an external controller.
Field | Description | ||||
---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||
kind string | ControllerRegistration | ||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec ControllerRegistrationSpec | Spec contains the specification of this registration. If the object’s deletion timestamp is set, this field is immutable.
|
ExposureClass
ExposureClass represents a control plane endpoint exposure strategy.
Field | Description |
---|---|
apiVersion string | core.gardener.cloud/v1beta1 |
kind string | ExposureClass |
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. |
handler string | Handler is the name of the handler which applies the control plane endpoint exposure strategy. This field is immutable. |
scheduling ExposureClassScheduling | (Optional) Scheduling holds information how to select applicable Seed’s for ExposureClass usage. This field is immutable. |
InternalSecret
InternalSecret holds secret data of a certain type. The total bytes of the values in the Data field must be less than MaxSecretSize bytes.
Field | Description |
---|---|
apiVersion string | core.gardener.cloud/v1beta1 |
kind string | InternalSecret |
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata Refer to the Kubernetes API documentation for the fields of themetadata field. |
immutable bool | (Optional) Immutable, if set to true, ensures that data stored in the Secret cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. |
data map[string][]byte | (Optional) Data contains the secret data. Each key must consist of alphanumeric characters, ‘-’, ‘_’ or ‘.’. The serialized form of the secret data is a base64 encoded string, representing the arbitrary (possibly non-string) data value here. Described in https://tools.ietf.org/html/rfc4648#section-4 |
stringData map[string]string | (Optional) stringData allows specifying non-binary secret data in string form. It is provided as a write-only input field for convenience. All keys and values are merged into the data field on write, overwriting any existing values. The stringData field is never output when reading from the API. |
type Kubernetes core/v1.SecretType | (Optional) Used to facilitate programmatic handling of secret data. More info: https://kubernetes.io/docs/concepts/configuration/secret/#secret-types |
Project
Project holds certain properties about a Gardener project.
Field | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||||||||||
kind string | Project | ||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||
spec ProjectSpec | (Optional) Spec defines the project properties.
| ||||||||||||||
status ProjectStatus | (Optional) Most recently observed status of the Project. |
Quota
Quota represents a quota on resources consumed by shoot clusters either per project or per provider secret.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||
kind string | Quota | ||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||
spec QuotaSpec | (Optional) Spec defines the Quota constraints.
|
SecretBinding
SecretBinding represents a binding to a secret in the same or another namespace.
Field | Description |
---|---|
apiVersion string | core.gardener.cloud/v1beta1 |
kind string | SecretBinding |
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret object in the same or another namespace. This field is immutable. |
quotas []Kubernetes core/v1.ObjectReference | (Optional) Quotas is a list of references to Quota objects in the same or another namespace. This field is immutable. |
provider SecretBindingProvider | (Optional) Provider defines the provider type of the SecretBinding. This field is immutable. |
Seed
Seed represents an installation request for an external controller.
Field | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||||||||||||||
kind string | Seed | ||||||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||
spec SeedSpec | Spec contains the specification of this installation.
| ||||||||||||||||||
status SeedStatus | Status contains the status of this installation. |
Shoot
Shoot represents a Shoot cluster created and managed by Gardener.
Field | Description | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||||||||||||||||||||||||||||||||||||||
kind string | Shoot | ||||||||||||||||||||||||||||||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||||||||||||||||||||||||||
spec ShootSpec | (Optional) Specification of the Shoot cluster. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||||||||||||||||||||||||||||||||||
status ShootStatus | (Optional) Most recently observed status of the Shoot cluster. |
ShootState
ShootState contains a snapshot of the Shoot’s state required to migrate the Shoot’s control plane to a new Seed.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | core.gardener.cloud/v1beta1 | ||||||
kind string | ShootState | ||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||
spec ShootStateSpec | (Optional) Specification of the ShootState.
|
APIServerLogging
(Appears on: KubeAPIServerConfig)
APIServerLogging contains configuration for the logs level and http access logs
Field | Description |
---|---|
verbosity int32 | (Optional) Verbosity is the kube-apiserver log verbosity level Defaults to 2. |
httpAccessVerbosity int32 | (Optional) HTTPAccessVerbosity is the kube-apiserver access logs level |
APIServerRequests
(Appears on: KubeAPIServerConfig)
APIServerRequests contains configuration for request-specific settings for the kube-apiserver.
Field | Description |
---|---|
maxNonMutatingInflight int32 | (Optional) MaxNonMutatingInflight is the maximum number of non-mutating requests in flight at a given time. When the server exceeds this, it rejects requests. |
maxMutatingInflight int32 | (Optional) MaxMutatingInflight is the maximum number of mutating requests in flight at a given time. When the server exceeds this, it rejects requests. |
Addon
(Appears on: KubernetesDashboard, NginxIngress)
Addon allows enabling or disabling a specific addon and is used to derive from.
Field | Description |
---|---|
enabled bool | Enabled indicates whether the addon is enabled or not. |
Addons
(Appears on: ShootSpec)
Addons is a collection of configuration for specific addons which are managed by the Gardener.
Field | Description |
---|---|
kubernetesDashboard KubernetesDashboard | (Optional) KubernetesDashboard holds configuration settings for the kubernetes dashboard addon. |
nginxIngress NginxIngress | (Optional) NginxIngress holds configuration settings for the nginx-ingress addon. |
AdmissionPlugin
(Appears on: KubeAPIServerConfig)
AdmissionPlugin contains information about a specific admission plugin and its corresponding configuration.
Field | Description |
---|---|
name string | Name is the name of the plugin. |
config k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) Config is the configuration of the plugin. |
disabled bool | (Optional) Disabled specifies whether this plugin should be disabled. |
kubeconfigSecretName string | (Optional) KubeconfigSecretName specifies the name of a secret containing the kubeconfig for this admission plugin. |
Alerting
(Appears on: Monitoring)
Alerting contains information about how alerting will be done (i.e. who will receive alerts and how).
Field | Description |
---|---|
emailReceivers []string | (Optional) MonitoringEmailReceivers is a list of recipients for alerts |
AuditConfig
(Appears on: KubeAPIServerConfig)
AuditConfig contains settings for audit of the api server
Field | Description |
---|---|
auditPolicy AuditPolicy | (Optional) AuditPolicy contains configuration settings for audit policy of the kube-apiserver. |
AuditPolicy
(Appears on: AuditConfig)
AuditPolicy contains audit policy for kube-apiserver
Field | Description |
---|---|
configMapRef Kubernetes core/v1.ObjectReference | (Optional) ConfigMapRef is a reference to a ConfigMap object in the same namespace, which contains the audit policy for the kube-apiserver. |
AvailabilityZone
(Appears on: Region)
AvailabilityZone is an availability zone.
Field | Description |
---|---|
name string | Name is an availability zone name. |
unavailableMachineTypes []string | (Optional) UnavailableMachineTypes is a list of machine type names that are not availability in this zone. |
unavailableVolumeTypes []string | (Optional) UnavailableVolumeTypes is a list of volume type names that are not availability in this zone. |
BackupBucketProvider
(Appears on: BackupBucketSpec)
BackupBucketProvider holds the details of cloud provider of the object store.
Field | Description |
---|---|
type string | Type is the type of provider. |
region string | Region is the region of the bucket. |
BackupBucketSpec
(Appears on: BackupBucket)
BackupBucketSpec is the specification of a Backup Bucket.
Field | Description |
---|---|
provider BackupBucketProvider | Provider holds the details of cloud provider of the object store. This field is immutable. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to BackupBucket resource. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the credentials to access object store. |
seedName string | (Optional) SeedName holds the name of the seed allocated to BackupBucket for running controller. This field is immutable. |
BackupBucketStatus
(Appears on: BackupBucket)
BackupBucketStatus holds the most recently observed status of the Backup Bucket.
Field | Description |
---|---|
providerStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderStatus is the configuration passed to BackupBucket resource. |
lastOperation LastOperation | (Optional) LastOperation holds information about the last operation on the BackupBucket. |
lastError LastError | (Optional) LastError holds information about the last occurred error during an operation. |
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this BackupBucket. It corresponds to the BackupBucket’s generation, which is updated on mutation by the API Server. |
generatedSecretRef Kubernetes core/v1.SecretReference | (Optional) GeneratedSecretRef is reference to the secret generated by backup bucket, which will have object store specific credentials. |
BackupEntrySpec
(Appears on: BackupEntry)
BackupEntrySpec is the specification of a Backup Entry.
Field | Description |
---|---|
bucketName string | BucketName is the name of backup bucket for this Backup Entry. |
seedName string | (Optional) SeedName holds the name of the seed to which this BackupEntry is scheduled |
BackupEntryStatus
(Appears on: BackupEntry)
BackupEntryStatus holds the most recently observed status of the Backup Entry.
Field | Description |
---|---|
lastOperation LastOperation | (Optional) LastOperation holds information about the last operation on the BackupEntry. |
lastError LastError | (Optional) LastError holds information about the last occurred error during an operation. |
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this BackupEntry. It corresponds to the BackupEntry’s generation, which is updated on mutation by the API Server. |
seedName string | (Optional) SeedName is the name of the seed to which this BackupEntry is currently scheduled. This field is populated at the beginning of a create/reconcile operation. It is used when moving the BackupEntry between seeds. |
migrationStartTime Kubernetes meta/v1.Time | (Optional) MigrationStartTime is the time when a migration to a different seed was initiated. |
CARotation
(Appears on: ShootCredentialsRotation)
CARotation contains information about the certificate authority credential rotation.
Field | Description |
---|---|
phase CredentialsRotationPhase | Phase describes the phase of the certificate authority credential rotation. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the certificate authority credential rotation was successfully completed. |
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the certificate authority credential rotation was initiated. |
lastInitiationFinishedTime Kubernetes meta/v1.Time | (Optional) LastInitiationFinishedTime is the recent time when the certificate authority credential rotation initiation was completed. |
lastCompletionTriggeredTime Kubernetes meta/v1.Time | (Optional) LastCompletionTriggeredTime is the recent time when the certificate authority credential rotation completion was triggered. |
CRI
(Appears on: MachineImageVersion, Worker)
CRI contains information about the Container Runtimes.
Field | Description |
---|---|
name CRIName | The name of the CRI library. Supported values are |
containerRuntimes []ContainerRuntime | (Optional) ContainerRuntimes is the list of the required container runtimes supported for a worker pool. |
CRIName
(string
alias)
(Appears on: CRI)
CRIName is a type alias for the CRI name string.
CloudProfileSpec
(Appears on: CloudProfile)
CloudProfileSpec is the specification of a CloudProfile. It must contain exactly one of its defined keys.
Field | Description |
---|---|
caBundle string | (Optional) CABundle is a certificate bundle which will be installed onto every host machine of shoot cluster targeting this profile. |
kubernetes KubernetesSettings | Kubernetes contains constraints regarding allowed values of the ‘kubernetes’ block in the Shoot specification. |
machineImages []MachineImage | MachineImages contains constraints regarding allowed values for machine images in the Shoot specification. |
machineTypes []MachineType | MachineTypes contains constraints regarding allowed values for machine types in the ‘workers’ block in the Shoot specification. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig contains provider-specific configuration for the profile. |
regions []Region | Regions contains constraints regarding allowed values for regions and zones. |
seedSelector SeedSelector | (Optional) SeedSelector contains an optional list of labels on |
type string | Type is the name of the provider. |
volumeTypes []VolumeType | (Optional) VolumeTypes contains constraints regarding allowed values for volume types in the ‘workers’ block in the Shoot specification. |
ClusterAutoscaler
(Appears on: Kubernetes)
ClusterAutoscaler contains the configuration flags for the Kubernetes cluster autoscaler.
Field | Description |
---|---|
scaleDownDelayAfterAdd Kubernetes meta/v1.Duration | (Optional) ScaleDownDelayAfterAdd defines how long after scale up that scale down evaluation resumes (default: 1 hour). |
scaleDownDelayAfterDelete Kubernetes meta/v1.Duration | (Optional) ScaleDownDelayAfterDelete how long after node deletion that scale down evaluation resumes, defaults to scanInterval (default: 0 secs). |
scaleDownDelayAfterFailure Kubernetes meta/v1.Duration | (Optional) ScaleDownDelayAfterFailure how long after scale down failure that scale down evaluation resumes (default: 3 mins). |
scaleDownUnneededTime Kubernetes meta/v1.Duration | (Optional) ScaleDownUnneededTime defines how long a node should be unneeded before it is eligible for scale down (default: 30 mins). |
scaleDownUtilizationThreshold float64 | (Optional) ScaleDownUtilizationThreshold defines the threshold in fraction (0.0 - 1.0) under which a node is being removed (default: 0.5). |
scanInterval Kubernetes meta/v1.Duration | (Optional) ScanInterval how often cluster is reevaluated for scale up or down (default: 10 secs). |
expander ExpanderMode | (Optional) Expander defines the algorithm to use during scale up (default: least-waste). See: https://github.com/gardener/autoscaler/blob/machine-controller-manager-provider/cluster-autoscaler/FAQ.md#what-are-expanders. |
maxNodeProvisionTime Kubernetes meta/v1.Duration | (Optional) MaxNodeProvisionTime defines how long CA waits for node to be provisioned (default: 20 mins). |
maxGracefulTerminationSeconds int32 | (Optional) MaxGracefulTerminationSeconds is the number of seconds CA waits for pod termination when trying to scale down a node (default: 600). |
ignoreTaints []string | (Optional) IgnoreTaints specifies a list of taint keys to ignore in node templates when considering to scale a node group. |
newPodScaleUpDelay Kubernetes meta/v1.Duration | (Optional) NewPodScaleUpDelay specifies how long CA should ignore newly created pods before they have to be considered for scale-up. |
maxEmptyBulkDelete int32 | (Optional) MaxEmptyBulkDelete specifies the maximum number of empty nodes that can be deleted at the same time (default: 10). |
Condition
(Appears on: ControllerInstallationStatus, SeedStatus, ShootStatus)
Condition holds the information about the state of a resource.
Field | Description |
---|---|
type ConditionType | Type of the condition. |
status ConditionStatus | Status of the condition, one of True, False, Unknown. |
lastTransitionTime Kubernetes meta/v1.Time | Last time the condition transitioned from one status to another. |
lastUpdateTime Kubernetes meta/v1.Time | Last time the condition was updated. |
reason string | The reason for the condition’s last transition. |
message string | A human readable message indicating details about the transition. |
codes []ErrorCode | (Optional) Well-defined error codes in case the condition reports a problem. |
ConditionStatus
(string
alias)
(Appears on: Condition)
ConditionStatus is the status of a condition.
ConditionType
(string
alias)
(Appears on: Condition)
ConditionType is a string alias.
ContainerRuntime
(Appears on: CRI)
ContainerRuntime contains information about worker’s available container runtime
Field | Description |
---|---|
type string | Type is the type of the Container Runtime. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to container runtime resource. |
ControlPlane
(Appears on: ShootSpec)
ControlPlane holds information about the general settings for the control plane of a shoot.
Field | Description |
---|---|
highAvailability HighAvailability | (Optional) HighAvailability holds the configuration settings for high availability of the control plane of a shoot. |
ControllerDeploymentPolicy
(string
alias)
(Appears on: ControllerRegistrationDeployment)
ControllerDeploymentPolicy is a string alias.
ControllerInstallationSpec
(Appears on: ControllerInstallation)
ControllerInstallationSpec is the specification of a ControllerInstallation.
Field | Description |
---|---|
registrationRef Kubernetes core/v1.ObjectReference | RegistrationRef is used to reference a ControllerRegistration resource. The name field of the RegistrationRef is immutable. |
seedRef Kubernetes core/v1.ObjectReference | SeedRef is used to reference a Seed resource. The name field of the SeedRef is immutable. |
deploymentRef Kubernetes core/v1.ObjectReference | (Optional) DeploymentRef is used to reference a ControllerDeployment resource. |
ControllerInstallationStatus
(Appears on: ControllerInstallation)
ControllerInstallationStatus is the status of a ControllerInstallation.
Field | Description |
---|---|
conditions []Condition | (Optional) Conditions represents the latest available observations of a ControllerInstallations’s current state. |
providerStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderStatus contains type-specific status. |
ControllerRegistrationDeployment
(Appears on: ControllerRegistrationSpec)
ControllerRegistrationDeployment contains information for how this controller is deployed.
Field | Description |
---|---|
policy ControllerDeploymentPolicy | (Optional) Policy controls how the controller is deployed. It defaults to ‘OnDemand’. |
seedSelector Kubernetes meta/v1.LabelSelector | (Optional) SeedSelector contains an optional label selector for seeds. Only if the labels match then this controller will be considered for a deployment. An empty list means that all seeds are selected. |
deploymentRefs []DeploymentRef | (Optional) DeploymentRefs holds references to |
ControllerRegistrationSpec
(Appears on: ControllerRegistration)
ControllerRegistrationSpec is the specification of a ControllerRegistration.
Field | Description |
---|---|
resources []ControllerResource | (Optional) Resources is a list of combinations of kinds (DNSProvider, Infrastructure, Generic, …) and their actual types (aws-route53, gcp, auditlog, …). |
deployment ControllerRegistrationDeployment | (Optional) Deployment contains information for how this controller is deployed. |
ControllerResource
(Appears on: ControllerRegistrationSpec)
ControllerResource is a combination of a kind (DNSProvider, Infrastructure, Generic, …) and the actual type for this kind (aws-route53, gcp, auditlog, …).
Field | Description |
---|---|
kind string | Kind is the resource kind, for example “OperatingSystemConfig”. |
type string | Type is the resource type, for example “coreos” or “ubuntu”. |
globallyEnabled bool | (Optional) GloballyEnabled determines if this ControllerResource is required by all Shoot clusters. This field is defaulted to false when kind is “Extension”. |
reconcileTimeout Kubernetes meta/v1.Duration | (Optional) ReconcileTimeout defines how long Gardener should wait for the resource reconciliation. This field is defaulted to 3m0s when kind is “Extension”. |
primary bool | (Optional) Primary determines if the controller backed by this ControllerRegistration is responsible for the extension resource’s lifecycle. This field defaults to true. There must be exactly one primary controller for this kind/type combination. This field is immutable. |
lifecycle ControllerResourceLifecycle | (Optional) Lifecycle defines a strategy that determines when different operations on a ControllerResource should be performed. This field is defaulted in the following way when kind is “Extension”. Reconcile: “AfterKubeAPIServer” Delete: “BeforeKubeAPIServer” Migrate: “BeforeKubeAPIServer” |
workerlessSupported bool | (Optional) WorkerlessSupported specifies whether this ControllerResource supports Workerless Shoot clusters. This field is only relevant when kind is “Extension”. |
ControllerResourceLifecycle
(Appears on: ControllerResource)
ControllerResourceLifecycle defines the lifecycle of a controller resource.
Field | Description |
---|---|
reconcile ControllerResourceLifecycleStrategy | (Optional) Reconcile defines the strategy during reconciliation. |
delete ControllerResourceLifecycleStrategy | (Optional) Delete defines the strategy during deletion. |
migrate ControllerResourceLifecycleStrategy | (Optional) Migrate defines the strategy during migration. |
ControllerResourceLifecycleStrategy
(string
alias)
(Appears on: ControllerResourceLifecycle)
ControllerResourceLifecycleStrategy is a string alias.
CoreDNS
(Appears on: SystemComponents)
CoreDNS contains the settings of the Core DNS components running in the data plane of the Shoot cluster.
Field | Description |
---|---|
autoscaling CoreDNSAutoscaling | (Optional) Autoscaling contains the settings related to autoscaling of the Core DNS components running in the data plane of the Shoot cluster. |
rewriting CoreDNSRewriting | (Optional) Rewriting contains the setting related to rewriting of requests, which are obviously incorrect due to the unnecessary application of the search path. |
CoreDNSAutoscaling
(Appears on: CoreDNS)
CoreDNSAutoscaling contains the settings related to autoscaling of the Core DNS components running in the data plane of the Shoot cluster.
Field | Description |
---|---|
mode CoreDNSAutoscalingMode | The mode of the autoscaling to be used for the Core DNS components running in the data plane of the Shoot cluster.
Supported values are |
CoreDNSAutoscalingMode
(string
alias)
(Appears on: CoreDNSAutoscaling)
CoreDNSAutoscalingMode is a type alias for the Core DNS autoscaling mode string.
CoreDNSRewriting
(Appears on: CoreDNS)
CoreDNSRewriting contains the setting related to rewriting requests, which are obviously incorrect due to the unnecessary application of the search path.
Field | Description |
---|---|
commonSuffixes []string | (Optional) CommonSuffixes are expected to be the suffix of a fully qualified domain name. Each suffix should contain at least one or two dots (‘.’) to prevent accidental clashes. |
CredentialsRotationPhase
(string
alias)
(Appears on: CARotation, ETCDEncryptionKeyRotation, ServiceAccountKeyRotation)
CredentialsRotationPhase is a string alias.
DNS
(Appears on: ShootSpec)
DNS holds information about the provider, the hosted zone id and the domain.
Field | Description |
---|---|
domain string | (Optional) Domain is the external available domain of the Shoot cluster. This domain will be written into the kubeconfig that is handed out to end-users. This field is immutable. |
providers []DNSProvider | (Optional) Providers is a list of DNS providers that shall be enabled for this shoot cluster. Only relevant if not a default domain is used. |
DNSIncludeExclude
(Appears on: DNSProvider)
DNSIncludeExclude contains information about which domains shall be included/excluded.
Field | Description |
---|---|
include []string | (Optional) Include is a list of domains that shall be included. |
exclude []string | (Optional) Exclude is a list of domains that shall be excluded. |
DNSProvider
(Appears on: DNS)
DNSProvider contains information about a DNS provider.
Field | Description |
---|---|
domains DNSIncludeExclude | (Optional) Domains contains information about which domains shall be included/excluded for this provider. Deprecated: This field is deprecated and will be removed in Gardener release v1.87. |
primary bool | (Optional) Primary indicates that this DNSProvider is used for shoot related domains. |
secretName string | (Optional) SecretName is a name of a secret containing credentials for the stated domain and the provider. When not specified, the Gardener will use the cloud provider credentials referenced by the Shoot and try to find respective credentials there (primary provider only). Specifying this field may override this behavior, i.e. forcing the Gardener to only look into the given secret. |
type string | (Optional) Type is the DNS provider type. |
zones DNSIncludeExclude | (Optional) Zones contains information about which hosted zones shall be included/excluded for this provider. Deprecated: This field is deprecated and will be removed in Gardener release v1.87. |
DataVolume
(Appears on: Worker)
DataVolume contains information about a data volume.
Field | Description |
---|---|
name string | Name of the volume to make it referencable. |
type string | (Optional) Type is the type of the volume. |
size string | VolumeSize is the size of the volume. |
encrypted bool | (Optional) Encrypted determines if the volume should be encrypted. |
DeploymentRef
(Appears on: ControllerRegistrationDeployment)
DeploymentRef contains information about ControllerDeployment
references.
Field | Description |
---|---|
name string | Name is the name of the |
ETCDEncryptionKeyRotation
(Appears on: ShootCredentialsRotation)
ETCDEncryptionKeyRotation contains information about the ETCD encryption key credential rotation.
Field | Description |
---|---|
phase CredentialsRotationPhase | Phase describes the phase of the ETCD encryption key credential rotation. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the ETCD encryption key credential rotation was successfully completed. |
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the ETCD encryption key credential rotation was initiated. |
lastInitiationFinishedTime Kubernetes meta/v1.Time | (Optional) LastInitiationFinishedTime is the recent time when the certificate authority credential rotation initiation was completed. |
lastCompletionTriggeredTime Kubernetes meta/v1.Time | (Optional) LastCompletionTriggeredTime is the recent time when the certificate authority credential rotation completion was triggered. |
ErrorCode
(string
alias)
(Appears on: Condition, LastError)
ErrorCode is a string alias.
ExpanderMode
(string
alias)
(Appears on: ClusterAutoscaler)
ExpanderMode is type used for Expander values
ExpirableVersion
(Appears on: KubernetesSettings, MachineImageVersion)
ExpirableVersion contains a version and an expiration date.
Field | Description |
---|---|
version string | Version is the version identifier. |
expirationDate Kubernetes meta/v1.Time | (Optional) ExpirationDate defines the time at which this version expires. |
classification VersionClassification | (Optional) Classification defines the state of a version (preview, supported, deprecated) |
ExposureClassScheduling
(Appears on: ExposureClass)
ExposureClassScheduling holds information to select applicable Seed’s for ExposureClass usage.
Field | Description |
---|---|
seedSelector SeedSelector | (Optional) SeedSelector is an optional label selector for Seed’s which are suitable to use the ExposureClass. |
tolerations []Toleration | (Optional) Tolerations contains the tolerations for taints on Seed clusters. |
Extension
(Appears on: ShootSpec)
Extension contains type and provider information for Shoot extensions.
Field | Description |
---|---|
type string | Type is the type of the extension resource. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to extension resource. |
disabled bool | (Optional) Disabled allows to disable extensions that were marked as ‘globally enabled’ by Gardener administrators. |
ExtensionResourceState
(Appears on: ShootStateSpec)
ExtensionResourceState contains the kind of the extension custom resource and its last observed state in the Shoot’s namespace on the Seed cluster.
Field | Description |
---|---|
kind string | Kind (type) of the extension custom resource |
name string | (Optional) Name of the extension custom resource |
purpose string | (Optional) Purpose of the extension custom resource |
state k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) State of the extension resource |
resources []NamedResourceReference | (Optional) Resources holds a list of named resource references that can be referred to in the state by their names. |
FailureTolerance
(Appears on: HighAvailability)
FailureTolerance describes information about failure tolerance level of a highly available resource.
Field | Description |
---|---|
type FailureToleranceType | Type specifies the type of failure that the highly available resource can tolerate |
FailureToleranceType
(string
alias)
(Appears on: FailureTolerance)
FailureToleranceType specifies the type of failure that a highly available shoot control plane that can tolerate.
Gardener
(Appears on: SeedStatus, ShootStatus)
Gardener holds the information about the Gardener version that operated a resource.
Field | Description |
---|---|
id string | ID is the Docker container id of the Gardener which last acted on a resource. |
name string | Name is the hostname (pod name) of the Gardener which last acted on a resource. |
version string | Version is the version of the Gardener which last acted on a resource. |
GardenerResourceData
(Appears on: ShootStateSpec)
GardenerResourceData holds the data which is used to generate resources, deployed in the Shoot’s control plane.
Field | Description |
---|---|
name string | Name of the object required to generate resources |
type string | Type of the object |
data k8s.io/apimachinery/pkg/runtime.RawExtension | Data contains the payload required to generate resources |
labels map[string]string | (Optional) Labels are labels of the object |
Hibernation
(Appears on: ShootSpec)
Hibernation contains information whether the Shoot is suspended or not.
Field | Description |
---|---|
enabled bool | (Optional) Enabled specifies whether the Shoot needs to be hibernated or not. If it is true, the Shoot’s desired state is to be hibernated. If it is false or nil, the Shoot’s desired state is to be awakened. |
schedules []HibernationSchedule | (Optional) Schedules determine the hibernation schedules. |
HibernationSchedule
(Appears on: Hibernation)
HibernationSchedule determines the hibernation schedule of a Shoot. A Shoot will be regularly hibernated at each start time and will be woken up at each end time. Start or End can be omitted, though at least one of each has to be specified.
Field | Description |
---|---|
start string | (Optional) Start is a Cron spec at which time a Shoot will be hibernated. |
end string | (Optional) End is a Cron spec at which time a Shoot will be woken up. |
location string | (Optional) Location is the time location in which both start and shall be evaluated. |
HighAvailability
(Appears on: ControlPlane)
HighAvailability specifies the configuration settings for high availability for a resource. Typical usages could be to configure HA for shoot control plane or for seed system components.
Field | Description |
---|---|
failureTolerance FailureTolerance | FailureTolerance holds information about failure tolerance level of a highly available resource. |
HorizontalPodAutoscalerConfig
(Appears on: KubeControllerManagerConfig)
HorizontalPodAutoscalerConfig contains horizontal pod autoscaler configuration settings for the kube-controller-manager. Note: Descriptions were taken from the Kubernetes documentation.
Field | Description |
---|---|
cpuInitializationPeriod Kubernetes meta/v1.Duration | (Optional) The period after which a ready pod transition is considered to be the first. |
downscaleStabilization Kubernetes meta/v1.Duration | (Optional) The configurable window at which the controller will choose the highest recommendation for autoscaling. |
initialReadinessDelay Kubernetes meta/v1.Duration | (Optional) The configurable period at which the horizontal pod autoscaler considers a Pod “not yet ready” given that it’s unready and it has transitioned to unready during that time. |
syncPeriod Kubernetes meta/v1.Duration | (Optional) The period for syncing the number of pods in horizontal pod autoscaler. |
tolerance float64 | (Optional) The minimum change (from 1.0) in the desired-to-actual metrics ratio for the horizontal pod autoscaler to consider scaling. |
IPFamily
(string
alias)
(Appears on: Networking, SeedNetworks)
IPFamily is a type for specifying an IP protocol version to use in Gardener clusters.
Ingress
(Appears on: SeedSpec)
Ingress configures the Ingress specific settings of the cluster
Field | Description |
---|---|
domain string | Domain specifies the IngressDomain of the cluster pointing to the ingress controller endpoint. It will be used to construct ingress URLs for system applications running in Shoot/Garden clusters. Once set this field is immutable. |
controller IngressController | Controller configures a Gardener managed Ingress Controller listening on the ingressDomain |
IngressController
(Appears on: Ingress)
IngressController enables a Gardener managed Ingress Controller listening on the ingressDomain
Field | Description |
---|---|
kind string | Kind defines which kind of IngressController to use. At the moment only |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig specifies infrastructure specific configuration for the ingressController |
KubeAPIServerConfig
(Appears on: Kubernetes)
KubeAPIServerConfig contains configuration settings for the kube-apiserver.
Field | Description |
---|---|
KubernetesConfig KubernetesConfig | (Members of |
admissionPlugins []AdmissionPlugin | (Optional) AdmissionPlugins contains the list of user-defined admission plugins (additional to those managed by Gardener), and, if desired, the corresponding configuration. |
apiAudiences []string | (Optional) APIAudiences are the identifiers of the API. The service account token authenticator will validate that tokens used against the API are bound to at least one of these audiences. Defaults to [“kubernetes”]. |
auditConfig AuditConfig | (Optional) AuditConfig contains configuration settings for the audit of the kube-apiserver. |
oidcConfig OIDCConfig | (Optional) OIDCConfig contains configuration settings for the OIDC provider. |
runtimeConfig map[string]bool | (Optional) RuntimeConfig contains information about enabled or disabled APIs. |
serviceAccountConfig ServiceAccountConfig | (Optional) ServiceAccountConfig contains configuration settings for the service account handling of the kube-apiserver. |
watchCacheSizes WatchCacheSizes | (Optional) WatchCacheSizes contains configuration of the API server’s watch cache sizes.
Configuring these flags might be useful for large-scale Shoot clusters with a lot of parallel update requests
and a lot of watching controllers (e.g. large ManagedSeed clusters). When the API server’s watch cache’s
capacity is too small to cope with the amount of update requests and watchers for a particular resource, it
might happen that controller watches are permanently stopped with |
requests APIServerRequests | (Optional) Requests contains configuration for request-specific settings for the kube-apiserver. |
enableAnonymousAuthentication bool | (Optional) EnableAnonymousAuthentication defines whether anonymous requests to the secure port
of the API server should be allowed (flag |
eventTTL Kubernetes meta/v1.Duration | (Optional) EventTTL controls the amount of time to retain events. Defaults to 1h. |
logging APIServerLogging | (Optional) Logging contains configuration for the log level and HTTP access logs. |
defaultNotReadyTolerationSeconds int64 | (Optional) DefaultNotReadyTolerationSeconds indicates the tolerationSeconds of the toleration for notReady:NoExecute
that is added by default to every pod that does not already have such a toleration (flag |
defaultUnreachableTolerationSeconds int64 | (Optional) DefaultUnreachableTolerationSeconds indicates the tolerationSeconds of the toleration for unreachable:NoExecute
that is added by default to every pod that does not already have such a toleration (flag |
KubeControllerManagerConfig
(Appears on: Kubernetes)
KubeControllerManagerConfig contains configuration settings for the kube-controller-manager.
Field | Description |
---|---|
KubernetesConfig KubernetesConfig | (Members of |
horizontalPodAutoscaler HorizontalPodAutoscalerConfig | (Optional) HorizontalPodAutoscalerConfig contains horizontal pod autoscaler configuration settings for the kube-controller-manager. |
nodeCIDRMaskSize int32 | (Optional) NodeCIDRMaskSize defines the mask size for node cidr in cluster (default is 24). This field is immutable. |
podEvictionTimeout Kubernetes meta/v1.Duration | (Optional) PodEvictionTimeout defines the grace period for deleting pods on failed nodes. Defaults to 2m. Deprecated: The corresponding kube-controller-manager flag |
nodeMonitorGracePeriod Kubernetes meta/v1.Duration | (Optional) NodeMonitorGracePeriod defines the grace period before an unresponsive node is marked unhealthy. |
KubeProxyConfig
(Appears on: Kubernetes)
KubeProxyConfig contains configuration settings for the kube-proxy.
Field | Description |
---|---|
KubernetesConfig KubernetesConfig | (Members of |
mode ProxyMode | (Optional) Mode specifies which proxy mode to use. defaults to IPTables. |
enabled bool | (Optional) Enabled indicates whether kube-proxy should be deployed or not. Depending on the networking extensions switching kube-proxy off might be rejected. Consulting the respective documentation of the used networking extension is recommended before using this field. defaults to true if not specified. |
KubeSchedulerConfig
(Appears on: Kubernetes)
KubeSchedulerConfig contains configuration settings for the kube-scheduler.
Field | Description |
---|---|
KubernetesConfig KubernetesConfig | (Members of |
kubeMaxPDVols string | (Optional) KubeMaxPDVols allows to configure the |
profile SchedulingProfile | (Optional) Profile configures the scheduling profile for the cluster. If not specified, the used profile is “balanced” (provides the default kube-scheduler behavior). |
KubeletConfig
(Appears on: Kubernetes, WorkerKubernetes)
KubeletConfig contains configuration settings for the kubelet.
Field | Description |
---|---|
KubernetesConfig KubernetesConfig | (Members of |
cpuCFSQuota bool | (Optional) CPUCFSQuota allows you to disable/enable CPU throttling for Pods. |
cpuManagerPolicy string | (Optional) CPUManagerPolicy allows to set alternative CPU management policies (default: none). |
evictionHard KubeletConfigEviction | (Optional) EvictionHard describes a set of eviction thresholds (e.g. memory.available<1Gi) that if met would trigger a Pod eviction. Default: memory.available: “100Mi/1Gi/5%” nodefs.available: “5%” nodefs.inodesFree: “5%” imagefs.available: “5%” imagefs.inodesFree: “5%” |
evictionMaxPodGracePeriod int32 | (Optional) EvictionMaxPodGracePeriod describes the maximum allowed grace period (in seconds) to use when terminating pods in response to a soft eviction threshold being met. Default: 90 |
evictionMinimumReclaim KubeletConfigEvictionMinimumReclaim | (Optional) EvictionMinimumReclaim configures the amount of resources below the configured eviction threshold that the kubelet attempts to reclaim whenever the kubelet observes resource pressure. Default: 0 for each resource |
evictionPressureTransitionPeriod Kubernetes meta/v1.Duration | (Optional) EvictionPressureTransitionPeriod is the duration for which the kubelet has to wait before transitioning out of an eviction pressure condition. Default: 4m0s |
evictionSoft KubeletConfigEviction | (Optional) EvictionSoft describes a set of eviction thresholds (e.g. memory.available<1.5Gi) that if met over a corresponding grace period would trigger a Pod eviction. Default: memory.available: “200Mi/1.5Gi/10%” nodefs.available: “10%” nodefs.inodesFree: “10%” imagefs.available: “10%” imagefs.inodesFree: “10%” |
evictionSoftGracePeriod KubeletConfigEvictionSoftGracePeriod | (Optional) EvictionSoftGracePeriod describes a set of eviction grace periods (e.g. memory.available=1m30s) that correspond to how long a soft eviction threshold must hold before triggering a Pod eviction. Default: memory.available: 1m30s nodefs.available: 1m30s nodefs.inodesFree: 1m30s imagefs.available: 1m30s imagefs.inodesFree: 1m30s |
maxPods int32 | (Optional) MaxPods is the maximum number of Pods that are allowed by the Kubelet. Default: 110 |
podPidsLimit int64 | (Optional) PodPIDsLimit is the maximum number of process IDs per pod allowed by the kubelet. |
imagePullProgressDeadline Kubernetes meta/v1.Duration | (Optional) ImagePullProgressDeadline describes the time limit under which if no pulling progress is made, the image pulling will be cancelled. Default: 1m |
failSwapOn bool | (Optional) FailSwapOn makes the Kubelet fail to start if swap is enabled on the node. (default true). |
kubeReserved KubeletConfigReserved | (Optional) KubeReserved is the configuration for resources reserved for kubernetes node components (mainly kubelet and container runtime). When updating these values, be aware that cgroup resizes may not succeed on active worker nodes. Look for the NodeAllocatableEnforced event to determine if the configuration was applied. Default: cpu=80m,memory=1Gi,pid=20k |
systemReserved KubeletConfigReserved | (Optional) SystemReserved is the configuration for resources reserved for system processes not managed by kubernetes (e.g. journald). When updating these values, be aware that cgroup resizes may not succeed on active worker nodes. Look for the NodeAllocatableEnforced event to determine if the configuration was applied. |
imageGCHighThresholdPercent int32 | (Optional) ImageGCHighThresholdPercent describes the percent of the disk usage which triggers image garbage collection. Default: 50 |
imageGCLowThresholdPercent int32 | (Optional) ImageGCLowThresholdPercent describes the percent of the disk to which garbage collection attempts to free. Default: 40 |
serializeImagePulls bool | (Optional) SerializeImagePulls describes whether the images are pulled one at a time. Default: true |
registryPullQPS int32 | (Optional) RegistryPullQPS is the limit of registry pulls per second. The value must not be a negative number. Setting it to 0 means no limit. Default: 5 |
registryBurst int32 | (Optional) RegistryBurst is the maximum size of bursty pulls, temporarily allows pulls to burst to this number, while still not exceeding registryPullQPS. The value must not be a negative number. Only used if registryPullQPS is greater than 0. Default: 10 |
seccompDefault bool | (Optional) SeccompDefault enables the use of |
containerLogMaxSize k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) A quantity defines the maximum size of the container log file before it is rotated. For example: “5Mi” or “256Ki”. Default: 100Mi |
containerLogMaxFiles int32 | (Optional) Maximum number of container log files that can be present for a container. |
protectKernelDefaults bool | (Optional) ProtectKernelDefaults ensures that the kernel tunables are equal to the kubelet defaults. Defaults to true for Kubernetes v1.26 or later. |
streamingConnectionIdleTimeout Kubernetes meta/v1.Duration | (Optional) StreamingConnectionIdleTimeout is the maximum time a streaming connection can be idle before the connection is automatically closed. This field cannot be set lower than “30s” or greater than “4h”. Default: “4h” for Kubernetes < v1.26. “5m” for Kubernetes >= v1.26. |
memorySwap MemorySwapConfiguration | (Optional) MemorySwap configures swap memory available to container workloads. |
KubeletConfigEviction
(Appears on: KubeletConfig)
KubeletConfigEviction contains kubelet eviction thresholds supporting either a resource.Quantity or a percentage based value.
Field | Description |
---|---|
memoryAvailable string | (Optional) MemoryAvailable is the threshold for the free memory on the host server. |
imageFSAvailable string | (Optional) ImageFSAvailable is the threshold for the free disk space in the imagefs filesystem (docker images and container writable layers). |
imageFSInodesFree string | (Optional) ImageFSInodesFree is the threshold for the available inodes in the imagefs filesystem. |
nodeFSAvailable string | (Optional) NodeFSAvailable is the threshold for the free disk space in the nodefs filesystem (docker volumes, logs, etc). |
nodeFSInodesFree string | (Optional) NodeFSInodesFree is the threshold for the available inodes in the nodefs filesystem. |
KubeletConfigEvictionMinimumReclaim
(Appears on: KubeletConfig)
KubeletConfigEvictionMinimumReclaim contains configuration for the kubelet eviction minimum reclaim.
Field | Description |
---|---|
memoryAvailable k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) MemoryAvailable is the threshold for the memory reclaim on the host server. |
imageFSAvailable k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) ImageFSAvailable is the threshold for the disk space reclaim in the imagefs filesystem (docker images and container writable layers). |
imageFSInodesFree k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) ImageFSInodesFree is the threshold for the inodes reclaim in the imagefs filesystem. |
nodeFSAvailable k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) NodeFSAvailable is the threshold for the disk space reclaim in the nodefs filesystem (docker volumes, logs, etc). |
nodeFSInodesFree k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) NodeFSInodesFree is the threshold for the inodes reclaim in the nodefs filesystem. |
KubeletConfigEvictionSoftGracePeriod
(Appears on: KubeletConfig)
KubeletConfigEvictionSoftGracePeriod contains grace periods for kubelet eviction thresholds.
Field | Description |
---|---|
memoryAvailable Kubernetes meta/v1.Duration | (Optional) MemoryAvailable is the grace period for the MemoryAvailable eviction threshold. |
imageFSAvailable Kubernetes meta/v1.Duration | (Optional) ImageFSAvailable is the grace period for the ImageFSAvailable eviction threshold. |
imageFSInodesFree Kubernetes meta/v1.Duration | (Optional) ImageFSInodesFree is the grace period for the ImageFSInodesFree eviction threshold. |
nodeFSAvailable Kubernetes meta/v1.Duration | (Optional) NodeFSAvailable is the grace period for the NodeFSAvailable eviction threshold. |
nodeFSInodesFree Kubernetes meta/v1.Duration | (Optional) NodeFSInodesFree is the grace period for the NodeFSInodesFree eviction threshold. |
KubeletConfigReserved
(Appears on: KubeletConfig)
KubeletConfigReserved contains reserved resources for daemons
Field | Description |
---|---|
cpu k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) CPU is the reserved cpu. |
memory k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) Memory is the reserved memory. |
ephemeralStorage k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) EphemeralStorage is the reserved ephemeral-storage. |
pid k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) PID is the reserved process-ids. |
Kubernetes
(Appears on: ShootSpec)
Kubernetes contains the version and configuration variables for the Shoot control plane.
Field | Description |
---|---|
allowPrivilegedContainers bool | (Optional) AllowPrivilegedContainers indicates whether privileged containers are allowed in the Shoot. Defaults to true for Kubernetes versions below v1.25. Unusable for Kubernetes versions v1.25 and higher. |
clusterAutoscaler ClusterAutoscaler | (Optional) ClusterAutoscaler contains the configuration flags for the Kubernetes cluster autoscaler. |
kubeAPIServer KubeAPIServerConfig | (Optional) KubeAPIServer contains configuration settings for the kube-apiserver. |
kubeControllerManager KubeControllerManagerConfig | (Optional) KubeControllerManager contains configuration settings for the kube-controller-manager. |
kubeScheduler KubeSchedulerConfig | (Optional) KubeScheduler contains configuration settings for the kube-scheduler. |
kubeProxy KubeProxyConfig | (Optional) KubeProxy contains configuration settings for the kube-proxy. |
kubelet KubeletConfig | (Optional) Kubelet contains configuration settings for the kubelet. |
version string | (Optional) Version is the semantic Kubernetes version to use for the Shoot cluster.
Defaults to the highest supported minor and patch version given in the referenced cloud profile.
The version can be omitted completely or partially specified, e.g. |
verticalPodAutoscaler VerticalPodAutoscaler | (Optional) VerticalPodAutoscaler contains the configuration flags for the Kubernetes vertical pod autoscaler. |
enableStaticTokenKubeconfig bool | (Optional) EnableStaticTokenKubeconfig indicates whether static token kubeconfig secret will be created for the Shoot cluster. Defaults to true for Shoots with Kubernetes versions < 1.26. Defaults to false for Shoots with Kubernetes versions >= 1.26. Starting Kubernetes 1.27 the field will be locked to false. |
KubernetesConfig
(Appears on: KubeAPIServerConfig, KubeControllerManagerConfig, KubeProxyConfig, KubeSchedulerConfig, KubeletConfig)
KubernetesConfig contains common configuration fields for the control plane components.
Field | Description |
---|---|
featureGates map[string]bool | (Optional) FeatureGates contains information about enabled feature gates. |
KubernetesDashboard
(Appears on: Addons)
KubernetesDashboard describes configuration values for the kubernetes-dashboard addon.
Field | Description |
---|---|
Addon Addon | (Members of |
authenticationMode string | (Optional) AuthenticationMode defines the authentication mode for the kubernetes-dashboard. |
KubernetesSettings
(Appears on: CloudProfileSpec)
KubernetesSettings contains constraints regarding allowed values of the ‘kubernetes’ block in the Shoot specification.
Field | Description |
---|---|
versions []ExpirableVersion | (Optional) Versions is the list of allowed Kubernetes versions with optional expiration dates for Shoot clusters. |
LastError
(Appears on: BackupBucketStatus, BackupEntryStatus, ShootStatus)
LastError indicates the last occurred error for an operation on a resource.
Field | Description |
---|---|
description string | A human readable message indicating details about the last error. |
taskID string | (Optional) ID of the task which caused this last error |
codes []ErrorCode | (Optional) Well-defined error codes of the last error(s). |
lastUpdateTime Kubernetes meta/v1.Time | (Optional) Last time the error was reported |
LastMaintenance
(Appears on: ShootStatus)
LastMaintenance holds information about a maintenance operation on the Shoot.
Field | Description |
---|---|
description string | A human-readable message containing details about the operations performed in the last maintenance. |
triggeredTime Kubernetes meta/v1.Time | TriggeredTime is the time when maintenance was triggered. |
state LastOperationState | Status of the last maintenance operation, one of Processing, Succeeded, Error. |
failureReason string | (Optional) FailureReason holds the information about the last maintenance operation failure reason. |
LastOperation
(Appears on: BackupBucketStatus, BackupEntryStatus, SeedStatus, ShootStatus)
LastOperation indicates the type and the state of the last operation, along with a description message and a progress indicator.
Field | Description |
---|---|
description string | A human readable message indicating details about the last operation. |
lastUpdateTime Kubernetes meta/v1.Time | Last time the operation state transitioned from one to another. |
progress int32 | The progress in percentage (0-100) of the last operation. |
state LastOperationState | Status of the last operation, one of Aborted, Processing, Succeeded, Error, Failed. |
type LastOperationType | Type of the last operation, one of Create, Reconcile, Delete, Migrate, Restore. |
LastOperationState
(string
alias)
(Appears on: LastMaintenance, LastOperation)
LastOperationState is a string alias.
LastOperationType
(string
alias)
(Appears on: LastOperation)
LastOperationType is a string alias.
Machine
(Appears on: Worker)
Machine contains information about the machine type and image.
Field | Description |
---|---|
type string | Type is the machine type of the worker group. |
image ShootMachineImage | (Optional) Image holds information about the machine image to use for all nodes of this pool. It will default to the latest version of the first image stated in the referenced CloudProfile if no value has been provided. |
architecture string | (Optional) Architecture is CPU architecture of machines in this worker pool. |
MachineControllerManagerSettings
(Appears on: Worker)
MachineControllerManagerSettings contains configurations for different worker-pools. Eg. MachineDrainTimeout, MachineHealthTimeout.
Field | Description |
---|---|
machineDrainTimeout Kubernetes meta/v1.Duration | (Optional) MachineDrainTimeout is the period after which machine is forcefully deleted. |
machineHealthTimeout Kubernetes meta/v1.Duration | (Optional) MachineHealthTimeout is the period after which machine is declared failed. |
machineCreationTimeout Kubernetes meta/v1.Duration | (Optional) MachineCreationTimeout is the period after which creation of the machine is declared failed. |
maxEvictRetries int32 | (Optional) MaxEvictRetries are the number of eviction retries on a pod after which drain is declared failed, and forceful deletion is triggered. |
nodeConditions []string | (Optional) NodeConditions are the set of conditions if set to true for the period of MachineHealthTimeout, machine will be declared failed. |
MachineImage
(Appears on: CloudProfileSpec)
MachineImage defines the name and multiple versions of the machine image in any environment.
Field | Description |
---|---|
name string | Name is the name of the image. |
versions []MachineImageVersion | Versions contains versions, expiration dates and container runtimes of the machine image |
updateStrategy MachineImageUpdateStrategy | (Optional) UpdateStrategy is the update strategy to use for the machine image. Possible values are: - patch: update to the latest patch version of the current minor version. - minor: update to the latest minor and patch version. - major: always update to the overall latest version (default). |
MachineImageUpdateStrategy
(string
alias)
(Appears on: MachineImage)
MachineImageUpdateStrategy is the update strategy to use for a machine image
MachineImageVersion
(Appears on: MachineImage)
MachineImageVersion is an expirable version with list of supported container runtimes and interfaces
Field | Description |
---|---|
ExpirableVersion ExpirableVersion | (Members of |
cri []CRI | (Optional) CRI list of supported container runtime and interfaces supported by this version |
architectures []string | (Optional) Architectures is the list of CPU architectures of the machine image in this version. |
kubeletVersionConstraint string | (Optional) KubeletVersionConstraint is a constraint describing the supported kubelet versions by the machine image in this version. If the field is not specified, it is assumed that the machine image in this version supports all kubelet versions. Examples: - ‘>= 1.26’ - supports only kubelet versions greater than or equal to 1.26 - ‘< 1.26’ - supports only kubelet versions less than 1.26 |
MachineType
(Appears on: CloudProfileSpec)
MachineType contains certain properties of a machine type.
Field | Description |
---|---|
cpu k8s.io/apimachinery/pkg/api/resource.Quantity | CPU is the number of CPUs for this machine type. |
gpu k8s.io/apimachinery/pkg/api/resource.Quantity | GPU is the number of GPUs for this machine type. |
memory k8s.io/apimachinery/pkg/api/resource.Quantity | Memory is the amount of memory for this machine type. |
name string | Name is the name of the machine type. |
storage MachineTypeStorage | (Optional) Storage is the amount of storage associated with the root volume of this machine type. |
usable bool | (Optional) Usable defines if the machine type can be used for shoot clusters. |
architecture string | (Optional) Architecture is the CPU architecture of this machine type. |
MachineTypeStorage
(Appears on: MachineType)
MachineTypeStorage is the amount of storage associated with the root volume of this machine type.
Field | Description |
---|---|
class string | Class is the class of the storage type. |
size k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) StorageSize is the storage size. |
type string | Type is the type of the storage. |
minSize k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) MinSize is the minimal supported storage size.
This overrides any other common minimum size configuration from |
Maintenance
(Appears on: ShootSpec)
Maintenance contains information about the time window for maintenance operations and which operations should be performed.
Field | Description |
---|---|
autoUpdate MaintenanceAutoUpdate | (Optional) AutoUpdate contains information about which constraints should be automatically updated. |
timeWindow MaintenanceTimeWindow | (Optional) TimeWindow contains information about the time window for maintenance operations. |
confineSpecUpdateRollout bool | (Optional) ConfineSpecUpdateRollout prevents that changes/updates to the shoot specification will be rolled out immediately. Instead, they are rolled out during the shoot’s maintenance time window. There is one exception that will trigger an immediate roll out which is changes to the Spec.Hibernation.Enabled field. |
MaintenanceAutoUpdate
(Appears on: Maintenance)
MaintenanceAutoUpdate contains information about which constraints should be automatically updated.
Field | Description |
---|---|
kubernetesVersion bool | KubernetesVersion indicates whether the patch Kubernetes version may be automatically updated (default: true). |
machineImageVersion bool | (Optional) MachineImageVersion indicates whether the machine image version may be automatically updated (default: true). |
MaintenanceTimeWindow
(Appears on: Maintenance)
MaintenanceTimeWindow contains information about the time window for maintenance operations.
Field | Description |
---|---|
begin string | Begin is the beginning of the time window in the format HHMMSS+ZONE, e.g. “220000+0100”. If not present, a random value will be computed. |
end string | End is the end of the time window in the format HHMMSS+ZONE, e.g. “220000+0100”. If not present, the value will be computed based on the “Begin” value. |
MemorySwapConfiguration
(Appears on: KubeletConfig)
MemorySwapConfiguration contains kubelet swap configuration For more information, please see KEP: 2400-node-swap
Field | Description |
---|---|
swapBehavior SwapBehavior | (Optional) SwapBehavior configures swap memory available to container workloads. May be one of {“LimitedSwap”, “UnlimitedSwap”} defaults to: LimitedSwap |
Monitoring
(Appears on: ShootSpec)
Monitoring contains information about the monitoring configuration for the shoot.
Field | Description |
---|---|
alerting Alerting | (Optional) Alerting contains information about the alerting configuration for the shoot cluster. |
NamedResourceReference
(Appears on: ExtensionResourceState, ShootSpec)
NamedResourceReference is a named reference to a resource.
Field | Description |
---|---|
name string | Name of the resource reference. |
resourceRef Kubernetes autoscaling/v1.CrossVersionObjectReference | ResourceRef is a reference to a resource. |
Networking
(Appears on: ShootSpec)
Networking defines networking parameters for the shoot cluster.
Field | Description |
---|---|
type string | (Optional) Type identifies the type of the networking plugin. This field is immutable. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to network resource. |
pods string | (Optional) Pods is the CIDR of the pod network. This field is immutable. |
nodes string | (Optional) Nodes is the CIDR of the entire node network. This field is immutable if the feature gate MutableShootSpecNetworkingNodes is disabled. |
services string | (Optional) Services is the CIDR of the service network. This field is immutable. |
ipFamilies []IPFamily | (Optional) IPFamilies specifies the IP protocol versions to use for shoot networking. This field is immutable. See https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md. Defaults to [“IPv4”]. |
NginxIngress
(Appears on: Addons)
NginxIngress describes configuration values for the nginx-ingress addon.
Field | Description |
---|---|
Addon Addon | (Members of |
loadBalancerSourceRanges []string | (Optional) LoadBalancerSourceRanges is list of allowed IP sources for NginxIngress |
config map[string]string | (Optional) Config contains custom configuration for the nginx-ingress-controller configuration. See https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#configuration-options |
externalTrafficPolicy Kubernetes core/v1.ServiceExternalTrafficPolicy | (Optional) ExternalTrafficPolicy controls the |
NodeLocalDNS
(Appears on: SystemComponents)
NodeLocalDNS contains the settings of the node local DNS components running in the data plane of the Shoot cluster.
Field | Description |
---|---|
enabled bool | Enabled indicates whether node local DNS is enabled or not. |
forceTCPToClusterDNS bool | (Optional) ForceTCPToClusterDNS indicates whether the connection from the node local DNS to the cluster DNS (Core DNS) will be forced to TCP or not. Default, if unspecified, is to enforce TCP. |
forceTCPToUpstreamDNS bool | (Optional) ForceTCPToUpstreamDNS indicates whether the connection from the node local DNS to the upstream DNS (infrastructure DNS) will be forced to TCP or not. Default, if unspecified, is to enforce TCP. |
disableForwardToUpstreamDNS bool | (Optional) DisableForwardToUpstreamDNS indicates whether requests from node local DNS to upstream DNS should be disabled. Default, if unspecified, is to forward requests for external domains to upstream DNS |
OIDCConfig
(Appears on: KubeAPIServerConfig)
OIDCConfig contains configuration settings for the OIDC provider. Note: Descriptions were taken from the Kubernetes documentation.
Field | Description |
---|---|
caBundle string | (Optional) If set, the OpenID server’s certificate will be verified by one of the authorities in the oidc-ca-file, otherwise the host’s root CA set will be used. |
clientAuthentication OpenIDConnectClientAuthentication | (Optional) ClientAuthentication can optionally contain client configuration used for kubeconfig generation. |
clientID string | (Optional) The client ID for the OpenID Connect client, must be set if oidc-issuer-url is set. |
groupsClaim string | (Optional) If provided, the name of a custom OpenID Connect claim for specifying user groups. The claim value is expected to be a string or array of strings. This flag is experimental, please see the authentication documentation for further details. |
groupsPrefix string | (Optional) If provided, all groups will be prefixed with this value to prevent conflicts with other authentication strategies. |
issuerURL string | (Optional) The URL of the OpenID issuer, only HTTPS scheme will be accepted. If set, it will be used to verify the OIDC JSON Web Token (JWT). |
requiredClaims map[string]string | (Optional) key=value pairs that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. |
signingAlgs []string | (Optional) List of allowed JOSE asymmetric signing algorithms. JWTs with a ‘alg’ header value not in this list will be rejected. Values are defined by RFC 7518 https://tools.ietf.org/html/rfc7518#section-3.1 |
usernameClaim string | (Optional) The OpenID claim to use as the user name. Note that claims other than the default (‘sub’) is not guaranteed to be unique and immutable. This flag is experimental, please see the authentication documentation for further details. (default “sub”) |
usernamePrefix string | (Optional) If provided, all usernames will be prefixed with this value. If not provided, username claims other than ‘email’ are prefixed by the issuer URL to avoid clashes. To skip any prefixing, provide the value ‘-’. |
ObservabilityRotation
(Appears on: ShootCredentialsRotation)
ObservabilityRotation contains information about the observability credential rotation.
Field | Description |
---|---|
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the observability credential rotation was initiated. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the observability credential rotation was successfully completed. |
OpenIDConnectClientAuthentication
(Appears on: OIDCConfig)
OpenIDConnectClientAuthentication contains configuration for OIDC clients.
Field | Description |
---|---|
extraConfig map[string]string | (Optional) Extra configuration added to kubeconfig’s auth-provider. Must not be any of idp-issuer-url, client-id, client-secret, idp-certificate-authority, idp-certificate-authority-data, id-token or refresh-token |
secret string | (Optional) The client Secret for the OpenID Connect client. |
ProjectMember
(Appears on: ProjectSpec)
ProjectMember is a member of a project.
Field | Description |
---|---|
Subject Kubernetes rbac/v1.Subject | (Members of Subject is representing a user name, an email address, or any other identifier of a user, group, or service account that has a certain role. |
role string | Role represents the role of this member.
IMPORTANT: Be aware that this field will be removed in the |
roles []string | (Optional) Roles represents the list of roles of this member. |
ProjectPhase
(string
alias)
(Appears on: ProjectStatus)
ProjectPhase is a label for the condition of a project at the current time.
ProjectSpec
(Appears on: Project)
ProjectSpec is the specification of a Project.
Field | Description |
---|---|
createdBy Kubernetes rbac/v1.Subject | (Optional) CreatedBy is a subject representing a user name, an email address, or any other identifier of a user who created the project. This field is immutable. |
description string | (Optional) Description is a human-readable description of what the project is used for. |
owner Kubernetes rbac/v1.Subject | (Optional) Owner is a subject representing a user name, an email address, or any other identifier of a user owning
the project.
IMPORTANT: Be aware that this field will be removed in the |
purpose string | (Optional) Purpose is a human-readable explanation of the project’s purpose. |
members []ProjectMember | (Optional) Members is a list of subjects representing a user name, an email address, or any other identifier of a user, group, or service account that has a certain role. |
namespace string | (Optional) Namespace is the name of the namespace that has been created for the Project object. A nil value means that Gardener will determine the name of the namespace. This field is immutable. |
tolerations ProjectTolerations | (Optional) Tolerations contains the tolerations for taints on seed clusters. |
ProjectStatus
(Appears on: Project)
ProjectStatus holds the most recently observed status of the project.
Field | Description |
---|---|
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this project. |
phase ProjectPhase | Phase is the current phase of the project. |
staleSinceTimestamp Kubernetes meta/v1.Time | (Optional) StaleSinceTimestamp contains the timestamp when the project was first discovered to be stale/unused. |
staleAutoDeleteTimestamp Kubernetes meta/v1.Time | (Optional) StaleAutoDeleteTimestamp contains the timestamp when the project will be garbage-collected/automatically deleted because it’s stale/unused. |
lastActivityTimestamp Kubernetes meta/v1.Time | (Optional) LastActivityTimestamp contains the timestamp from the last activity performed in this project. |
ProjectTolerations
(Appears on: ProjectSpec)
ProjectTolerations contains the tolerations for taints on seed clusters.
Field | Description |
---|---|
defaults []Toleration | (Optional) Defaults contains a list of tolerations that are added to the shoots in this project by default. |
whitelist []Toleration | (Optional) Whitelist contains a list of tolerations that are allowed to be added to the shoots in this project. Please note
that this list may only be added by users having the |
Provider
(Appears on: ShootSpec)
Provider contains provider-specific information that are handed-over to the provider-specific extension controller.
Field | Description |
---|---|
type string | Type is the type of the provider. This field is immutable. |
controlPlaneConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ControlPlaneConfig contains the provider-specific control plane config blob. Please look up the concrete definition in the documentation of your provider extension. |
infrastructureConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) InfrastructureConfig contains the provider-specific infrastructure config blob. Please look up the concrete definition in the documentation of your provider extension. |
workers []Worker | (Optional) Workers is a list of worker groups. |
workersSettings WorkersSettings | (Optional) WorkersSettings contains settings for all workers. |
ProxyMode
(string
alias)
(Appears on: KubeProxyConfig)
ProxyMode available in Linux platform: ‘userspace’ (older, going to be EOL), ‘iptables’ (newer, faster), ‘ipvs’ (newest, better in performance and scalability). As of now only ‘iptables’ and ‘ipvs’ is supported by Gardener. In Linux platform, if the iptables proxy is selected, regardless of how, but the system’s kernel or iptables versions are insufficient, this always falls back to the userspace proxy. IPVS mode will be enabled when proxy mode is set to ‘ipvs’, and the fall back path is firstly iptables and then userspace.
QuotaSpec
(Appears on: Quota)
QuotaSpec is the specification of a Quota.
Field | Description |
---|---|
clusterLifetimeDays int32 | (Optional) ClusterLifetimeDays is the lifetime of a Shoot cluster in days before it will be terminated automatically. |
metrics Kubernetes core/v1.ResourceList | Metrics is a list of resources which will be put under constraints. |
scope Kubernetes core/v1.ObjectReference | Scope is the scope of the Quota object, either ‘project’ or ‘secret’. This field is immutable. |
Region
(Appears on: CloudProfileSpec)
Region contains certain properties of a region.
Field | Description |
---|---|
name string | Name is a region name. |
zones []AvailabilityZone | (Optional) Zones is a list of availability zones in this region. |
labels map[string]string | (Optional) Labels is an optional set of key-value pairs that contain certain administrator-controlled labels for this region. It can be used by Gardener administrators/operators to provide additional information about a region, e.g. wrt quality, reliability, access restrictions, etc. |
ResourceData
(Appears on: ShootStateSpec)
ResourceData holds the data of a resource referred to by an extension controller state.
Field | Description |
---|---|
CrossVersionObjectReference Kubernetes autoscaling/v1.CrossVersionObjectReference | (Members of |
data k8s.io/apimachinery/pkg/runtime.RawExtension | Data of the resource |
ResourceWatchCacheSize
(Appears on: WatchCacheSizes)
ResourceWatchCacheSize contains configuration of the API server’s watch cache size for one specific resource.
Field | Description |
---|---|
apiGroup string | (Optional) APIGroup is the API group of the resource for which the watch cache size should be configured.
An unset value is used to specify the legacy core API (e.g. for |
resource string | Resource is the name of the resource for which the watch cache size should be configured
(in lowercase plural form, e.g. |
size int32 | CacheSize specifies the watch cache size that should be configured for the specified resource. |
SSHAccess
(Appears on: WorkersSettings)
SSHAccess contains settings regarding ssh access to the worker nodes.
Field | Description |
---|---|
enabled bool | Enabled indicates whether the SSH access to the worker nodes is ensured to be enabled or disabled in systemd. Defaults to true. |
SchedulingProfile
(string
alias)
(Appears on: KubeSchedulerConfig)
SchedulingProfile is a string alias used for scheduling profile values.
SecretBindingProvider
(Appears on: SecretBinding)
SecretBindingProvider defines the provider type of the SecretBinding.
Field | Description |
---|---|
type string | Type is the type of the provider. For backwards compatibility, the field can contain multiple providers separated by a comma. However the usage of single SecretBinding (hence Secret) for different cloud providers is strongly discouraged. |
SeedBackup
(Appears on: SeedSpec)
SeedBackup contains the object store configuration for backups for shoot (currently only etcd).
Field | Description |
---|---|
provider string | Provider is a provider name. This field is immutable. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to BackupBucket resource. |
region string | (Optional) Region is a region name. This field is immutable. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a Secret object containing the cloud provider credentials for the object store where backups should be stored. It should have enough privileges to manipulate the objects as well as buckets. |
SeedDNS
(Appears on: SeedSpec)
SeedDNS contains DNS-relevant information about this seed cluster.
Field | Description |
---|---|
provider SeedDNSProvider | (Optional) Provider configures a DNSProvider |
SeedDNSProvider
(Appears on: SeedDNS)
SeedDNSProvider configures a DNSProvider for Seeds
Field | Description |
---|---|
type string | Type describes the type of the dns-provider, for example |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a Secret object containing cloud provider credentials used for registering external domains. |
SeedNetworks
(Appears on: SeedSpec)
SeedNetworks contains CIDRs for the pod, service and node networks of a Kubernetes cluster.
Field | Description |
---|---|
nodes string | (Optional) Nodes is the CIDR of the node network. This field is immutable. |
pods string | Pods is the CIDR of the pod network. This field is immutable. |
services string | Services is the CIDR of the service network. This field is immutable. |
shootDefaults ShootNetworks | (Optional) ShootDefaults contains the default networks CIDRs for shoots. |
blockCIDRs []string | (Optional) BlockCIDRs is a list of network addresses that should be blocked for shoot control plane components running in the seed cluster. |
ipFamilies []IPFamily | (Optional) IPFamilies specifies the IP protocol versions to use for seed networking. This field is immutable. See https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md. Defaults to [“IPv4”]. |
SeedProvider
(Appears on: SeedSpec)
SeedProvider defines the provider-specific information of this Seed cluster.
Field | Description |
---|---|
type string | Type is the name of the provider. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the configuration passed to Seed resource. |
region string | Region is a name of a region. |
zones []string | (Optional) Zones is the list of availability zones the seed cluster is deployed to. |
SeedSelector
(Appears on: CloudProfileSpec, ExposureClassScheduling, ShootSpec)
SeedSelector contains constraints for selecting seed to be usable for shoots using a profile
Field | Description |
---|---|
LabelSelector Kubernetes meta/v1.LabelSelector | (Members of LabelSelector is optional and can be used to select seeds by their label settings |
providerTypes []string | (Optional) Providers is optional and can be used by restricting seeds by their provider type. ‘*’ can be used to enable seeds regardless of their provider type. |
SeedSettingDependencyWatchdog
(Appears on: SeedSettings)
SeedSettingDependencyWatchdog controls the dependency-watchdog settings for the seed.
Field | Description |
---|---|
weeder SeedSettingDependencyWatchdogWeeder | (Optional) Weeder controls the weeder settings for the dependency-watchdog for the seed. |
prober SeedSettingDependencyWatchdogProber | (Optional) Prober controls the prober settings for the dependency-watchdog for the seed. |
SeedSettingDependencyWatchdogProber
(Appears on: SeedSettingDependencyWatchdog)
SeedSettingDependencyWatchdogProber controls the prober settings for the dependency-watchdog for the seed.
Field | Description |
---|---|
enabled bool | Enabled controls whether the probe controller(prober) of the dependency-watchdog should be enabled. This controller scales down the kube-controller-manager, machine-controller-manager and cluster-autoscaler of shoot clusters in case their respective kube-apiserver is not reachable via its external ingress in order to avoid melt-down situations. |
SeedSettingDependencyWatchdogWeeder
(Appears on: SeedSettingDependencyWatchdog)
SeedSettingDependencyWatchdogWeeder controls the weeder settings for the dependency-watchdog for the seed.
Field | Description |
---|---|
enabled bool | Enabled controls whether the endpoint controller(weeder) of the dependency-watchdog should be enabled. This controller helps to alleviate the delay where control plane components remain unavailable by finding the respective pods in CrashLoopBackoff status and restarting them once their dependants become ready and available again. |
SeedSettingExcessCapacityReservation
(Appears on: SeedSettings)
SeedSettingExcessCapacityReservation controls the excess capacity reservation for shoot control planes in the seed.
Field | Description |
---|---|
enabled bool | (Optional) Enabled controls whether the default excess capacity reservation should be enabled. When not specified, the functionality is enabled. |
configs []SeedSettingExcessCapacityReservationConfig | (Optional) Configs configures excess capacity reservation deployments for shoot control planes in the seed. |
SeedSettingExcessCapacityReservationConfig
(Appears on: SeedSettingExcessCapacityReservation)
SeedSettingExcessCapacityReservationConfig configures excess capacity reservation deployments for shoot control planes in the seed.
Field | Description |
---|---|
resources Kubernetes core/v1.ResourceList | Resources specify the resource requests and limits of the excess-capacity-reservation pod. |
nodeSelector map[string]string | (Optional) NodeSelector specifies the node where the excess-capacity-reservation pod should run. |
tolerations []Kubernetes core/v1.Toleration | (Optional) Tolerations specify the tolerations for the the excess-capacity-reservation pod. |
SeedSettingLoadBalancerServices
(Appears on: SeedSettings)
SeedSettingLoadBalancerServices controls certain settings for services of type load balancer that are created in the seed.
Field | Description |
---|---|
annotations map[string]string | (Optional) Annotations is a map of annotations that will be injected/merged into every load balancer service object. |
externalTrafficPolicy Kubernetes core/v1.ServiceExternalTrafficPolicy | (Optional) ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the service’s “externally-facing” addresses. Defaults to “Cluster”. |
zones []SeedSettingLoadBalancerServicesZones | (Optional) Zones controls settings, which are specific to the single-zone load balancers in a multi-zonal setup. Can be empty for single-zone seeds. Each specified zone has to relate to one of the zones in seed.spec.provider.zones. |
SeedSettingLoadBalancerServicesZones
(Appears on: SeedSettingLoadBalancerServices)
SeedSettingLoadBalancerServicesZones controls settings, which are specific to the single-zone load balancers in a multi-zonal setup.
Field | Description |
---|---|
name string | Name is the name of the zone as specified in seed.spec.provider.zones. |
annotations map[string]string | (Optional) Annotations is a map of annotations that will be injected/merged into the zone-specific load balancer service object. |
externalTrafficPolicy Kubernetes core/v1.ServiceExternalTrafficPolicy | (Optional) ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the service’s “externally-facing” addresses. Defaults to “Cluster”. |
SeedSettingScheduling
(Appears on: SeedSettings)
SeedSettingScheduling controls settings for scheduling decisions for the seed.
Field | Description |
---|---|
visible bool | Visible controls whether the gardener-scheduler shall consider this seed when scheduling shoots. Invisible seeds are not considered by the scheduler. |
SeedSettingTopologyAwareRouting
(Appears on: SeedSettings)
SeedSettingTopologyAwareRouting controls certain settings for topology-aware traffic routing in the seed. See https://github.com/gardener/gardener/blob/master/docs/operations/topology_aware_routing.md.
Field | Description |
---|---|
enabled bool | Enabled controls whether certain Services deployed in the seed cluster should be topology-aware. These Services are etcd-main-client, etcd-events-client, kube-apiserver, gardener-resource-manager and vpa-webhook. |
SeedSettingVerticalPodAutoscaler
(Appears on: SeedSettings)
SeedSettingVerticalPodAutoscaler controls certain settings for the vertical pod autoscaler components deployed in the seed.
Field | Description |
---|---|
enabled bool | Enabled controls whether the VPA components shall be deployed into the garden namespace in the seed cluster. It is enabled by default because Gardener heavily relies on a VPA being deployed. You should only disable this if your seed cluster already has another, manually/custom managed VPA deployment. |
SeedSettings
(Appears on: SeedSpec)
SeedSettings contains certain settings for this seed cluster.
Field | Description |
---|---|
excessCapacityReservation SeedSettingExcessCapacityReservation | (Optional) ExcessCapacityReservation controls the excess capacity reservation for shoot control planes in the seed. |
scheduling SeedSettingScheduling | (Optional) Scheduling controls settings for scheduling decisions for the seed. |
loadBalancerServices SeedSettingLoadBalancerServices | (Optional) LoadBalancerServices controls certain settings for services of type load balancer that are created in the seed. |
verticalPodAutoscaler SeedSettingVerticalPodAutoscaler | (Optional) VerticalPodAutoscaler controls certain settings for the vertical pod autoscaler components deployed in the seed. |
dependencyWatchdog SeedSettingDependencyWatchdog | (Optional) DependencyWatchdog controls certain settings for the dependency-watchdog components deployed in the seed. |
topologyAwareRouting SeedSettingTopologyAwareRouting | (Optional) TopologyAwareRouting controls certain settings for topology-aware traffic routing in the seed. See https://github.com/gardener/gardener/blob/master/docs/operations/topology_aware_routing.md. |
SeedSpec
(Appears on: Seed, SeedTemplate)
SeedSpec is the specification of a Seed.
Field | Description |
---|---|
backup SeedBackup | (Optional) Backup holds the object store configuration for the backups of shoot (currently only etcd). If it is not specified, then there won’t be any backups taken for shoots associated with this seed. If backup field is present in seed, then backups of the etcd from shoot control plane will be stored under the configured object store. |
dns SeedDNS | DNS contains DNS-relevant information about this seed cluster. |
networks SeedNetworks | Networks defines the pod, service and worker network of the Seed cluster. |
provider SeedProvider | Provider defines the provider type and region for this Seed cluster. |
secretRef Kubernetes core/v1.SecretReference | (Optional) SecretRef is a reference to a Secret object containing the Kubeconfig of the Kubernetes cluster to be registered as Seed. Deprecated: This field is deprecated, gardenlet must run in the Seed cluster, hence it should use the in-cluster rest config via ServiceAccount to communicate with the Seed cluster. |
taints []SeedTaint | (Optional) Taints describes taints on the seed. |
volume SeedVolume | (Optional) Volume contains settings for persistentvolumes created in the seed cluster. |
settings SeedSettings | (Optional) Settings contains certain settings for this seed cluster. |
ingress Ingress | (Optional) Ingress configures Ingress specific settings of the Seed cluster. This field is immutable. |
SeedStatus
(Appears on: Seed)
SeedStatus is the status of a Seed.
Field | Description |
---|---|
gardener Gardener | (Optional) Gardener holds information about the Gardener which last acted on the Shoot. |
kubernetesVersion string | (Optional) KubernetesVersion is the Kubernetes version of the seed cluster. |
conditions []Condition | (Optional) Conditions represents the latest available observations of a Seed’s current state. |
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this Seed. It corresponds to the Seed’s generation, which is updated on mutation by the API Server. |
clusterIdentity string | (Optional) ClusterIdentity is the identity of the Seed cluster. This field is immutable. |
capacity Kubernetes core/v1.ResourceList | (Optional) Capacity represents the total resources of a seed. |
allocatable Kubernetes core/v1.ResourceList | (Optional) Allocatable represents the resources of a seed that are available for scheduling. Defaults to Capacity. |
clientCertificateExpirationTimestamp Kubernetes meta/v1.Time | (Optional) ClientCertificateExpirationTimestamp is the timestamp at which gardenlet’s client certificate expires. |
lastOperation LastOperation | (Optional) LastOperation holds information about the last operation on the Seed. |
SeedTaint
(Appears on: SeedSpec)
SeedTaint describes a taint on a seed.
Field | Description |
---|---|
key string | Key is the taint key to be applied to a seed. |
value string | (Optional) Value is the taint value corresponding to the taint key. |
SeedTemplate
SeedTemplate is a template for creating a Seed object.
Field | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||
spec SeedSpec | (Optional) Specification of the desired behavior of the Seed.
|
SeedVolume
(Appears on: SeedSpec)
SeedVolume contains settings for persistentvolumes created in the seed cluster.
Field | Description |
---|---|
minimumSize k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) MinimumSize defines the minimum size that should be used for PVCs in the seed. |
providers []SeedVolumeProvider | (Optional) Providers is a list of storage class provisioner types for the seed. |
SeedVolumeProvider
(Appears on: SeedVolume)
SeedVolumeProvider is a storage class provisioner type.
Field | Description |
---|---|
purpose string | Purpose is the purpose of this provider. |
name string | Name is the name of the storage class provisioner type. |
ServiceAccountConfig
(Appears on: KubeAPIServerConfig)
ServiceAccountConfig is the kube-apiserver configuration for service accounts.
Field | Description |
---|---|
issuer string | (Optional) Issuer is the identifier of the service account token issuer. The issuer will assert this identifier in “iss” claim of issued tokens. This value is used to generate new service account tokens. This value is a string or URI. Defaults to URI of the API server. |
extendTokenExpiration bool | (Optional) ExtendTokenExpiration turns on projected service account expiration extension during token generation, which helps safe transition from legacy token to bound service account token feature. If this flag is enabled, admission injected tokens would be extended up to 1 year to prevent unexpected failure during transition, ignoring value of service-account-max-token-expiration. |
maxTokenExpiration Kubernetes meta/v1.Duration | (Optional) MaxTokenExpiration is the maximum validity duration of a token created by the service account token issuer. If an otherwise valid TokenRequest with a validity duration larger than this value is requested, a token will be issued with a validity duration of this value. This field must be within [30d,90d]. |
acceptedIssuers []string | (Optional) AcceptedIssuers is an additional set of issuers that are used to determine which service account tokens are accepted. These values are not used to generate new service account tokens. Only useful when service account tokens are also issued by another external system or a change of the current issuer that is used for generating tokens is being performed. |
ServiceAccountKeyRotation
(Appears on: ShootCredentialsRotation)
ServiceAccountKeyRotation contains information about the service account key credential rotation.
Field | Description |
---|---|
phase CredentialsRotationPhase | Phase describes the phase of the service account key credential rotation. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the service account key credential rotation was successfully completed. |
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the service account key credential rotation was initiated. |
lastInitiationFinishedTime Kubernetes meta/v1.Time | (Optional) LastInitiationFinishedTime is the recent time when the certificate authority credential rotation initiation was completed. |
lastCompletionTriggeredTime Kubernetes meta/v1.Time | (Optional) LastCompletionTriggeredTime is the recent time when the certificate authority credential rotation completion was triggered. |
ShootAdvertisedAddress
(Appears on: ShootStatus)
ShootAdvertisedAddress contains information for the shoot’s Kube API server.
Field | Description |
---|---|
name string | Name of the advertised address. e.g. external |
url string | The URL of the API Server. e.g. https://api.foo.bar or https://1.2.3.4 |
ShootCredentials
(Appears on: ShootStatus)
ShootCredentials contains information about the shoot credentials.
Field | Description |
---|---|
rotation ShootCredentialsRotation | (Optional) Rotation contains information about the credential rotations. |
ShootCredentialsRotation
(Appears on: ShootCredentials)
ShootCredentialsRotation contains information about the rotation of credentials.
Field | Description |
---|---|
certificateAuthorities CARotation | (Optional) CertificateAuthorities contains information about the certificate authority credential rotation. |
kubeconfig ShootKubeconfigRotation | (Optional) Kubeconfig contains information about the kubeconfig credential rotation. |
sshKeypair ShootSSHKeypairRotation | (Optional) SSHKeypair contains information about the ssh-keypair credential rotation. |
observability ObservabilityRotation | (Optional) Observability contains information about the observability credential rotation. |
serviceAccountKey ServiceAccountKeyRotation | (Optional) ServiceAccountKey contains information about the service account key credential rotation. |
etcdEncryptionKey ETCDEncryptionKeyRotation | (Optional) ETCDEncryptionKey contains information about the ETCD encryption key credential rotation. |
ShootKubeconfigRotation
(Appears on: ShootCredentialsRotation)
ShootKubeconfigRotation contains information about the kubeconfig credential rotation.
Field | Description |
---|---|
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the kubeconfig credential rotation was initiated. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the kubeconfig credential rotation was successfully completed. |
ShootMachineImage
(Appears on: Machine)
ShootMachineImage defines the name and the version of the shoot’s machine image in any environment. Has to be defined in the respective CloudProfile.
Field | Description |
---|---|
name string | Name is the name of the image. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the shoot’s individual configuration passed to an extension resource. |
version string | (Optional) Version is the version of the shoot’s image. If version is not provided, it will be defaulted to the latest version from the CloudProfile. |
ShootNetworks
(Appears on: SeedNetworks)
ShootNetworks contains the default networks CIDRs for shoots.
Field | Description |
---|---|
pods string | (Optional) Pods is the CIDR of the pod network. |
services string | (Optional) Services is the CIDR of the service network. |
ShootPurpose
(string
alias)
(Appears on: ShootSpec)
ShootPurpose is a type alias for string.
ShootSSHKeypairRotation
(Appears on: ShootCredentialsRotation)
ShootSSHKeypairRotation contains information about the ssh-keypair credential rotation.
Field | Description |
---|---|
lastInitiationTime Kubernetes meta/v1.Time | (Optional) LastInitiationTime is the most recent time when the ssh-keypair credential rotation was initiated. |
lastCompletionTime Kubernetes meta/v1.Time | (Optional) LastCompletionTime is the most recent time when the ssh-keypair credential rotation was successfully completed. |
ShootSpec
(Appears on: Shoot, ShootTemplate)
ShootSpec is the specification of a Shoot.
Field | Description |
---|---|
addons Addons | (Optional) Addons contains information about enabled/disabled addons and their configuration. |
cloudProfileName string | CloudProfileName is a name of a CloudProfile object. This field is immutable. |
dns DNS | (Optional) DNS contains information about the DNS settings of the Shoot. |
extensions []Extension | (Optional) Extensions contain type and provider information for Shoot extensions. |
hibernation Hibernation | (Optional) Hibernation contains information whether the Shoot is suspended or not. |
kubernetes Kubernetes | Kubernetes contains the version and configuration settings of the control plane components. |
networking Networking | (Optional) Networking contains information about cluster networking such as CNI Plugin type, CIDRs, …etc. |
maintenance Maintenance | (Optional) Maintenance contains information about the time window for maintenance operations and which operations should be performed. |
monitoring Monitoring | (Optional) Monitoring contains information about custom monitoring configurations for the shoot. |
provider Provider | Provider contains all provider-specific and provider-relevant information. |
purpose ShootPurpose | (Optional) Purpose is the purpose class for this cluster. |
region string | Region is a name of a region. This field is immutable. |
secretBindingName string | (Optional) SecretBindingName is the name of the a SecretBinding that has a reference to the provider secret. The credentials inside the provider secret will be used to create the shoot in the respective account. This field is immutable. |
seedName string | (Optional) SeedName is the name of the seed cluster that runs the control plane of the Shoot. |
seedSelector SeedSelector | (Optional) SeedSelector is an optional selector which must match a seed’s labels for the shoot to be scheduled on that seed. |
resources []NamedResourceReference | (Optional) Resources holds a list of named resource references that can be referred to in extension configs by their names. |
tolerations []Toleration | (Optional) Tolerations contains the tolerations for taints on seed clusters. |
exposureClassName string | (Optional) ExposureClassName is the optional name of an exposure class to apply a control plane endpoint exposure strategy. This field is immutable. |
systemComponents SystemComponents | (Optional) SystemComponents contains the settings of system components in the control or data plane of the Shoot cluster. |
controlPlane ControlPlane | (Optional) ControlPlane contains general settings for the control plane of the shoot. |
schedulerName string | (Optional) SchedulerName is the name of the responsible scheduler which schedules the shoot. If not specified, the default scheduler takes over. This field is immutable. |
ShootStateSpec
(Appears on: ShootState)
ShootStateSpec is the specification of the ShootState.
Field | Description |
---|---|
gardener []GardenerResourceData | (Optional) Gardener holds the data required to generate resources deployed by the gardenlet |
extensions []ExtensionResourceState | (Optional) Extensions holds the state of custom resources reconciled by extension controllers in the seed |
resources []ResourceData | (Optional) Resources holds the data of resources referred to by extension controller states |
ShootStatus
(Appears on: Shoot)
ShootStatus holds the most recently observed status of the Shoot cluster.
Field | Description |
---|---|
conditions []Condition | (Optional) Conditions represents the latest available observations of a Shoots’s current state. |
constraints []Condition | (Optional) Constraints represents conditions of a Shoot’s current state that constraint some operations on it. |
gardener Gardener | Gardener holds information about the Gardener which last acted on the Shoot. |
hibernated bool | IsHibernated indicates whether the Shoot is currently hibernated. |
lastOperation LastOperation | (Optional) LastOperation holds information about the last operation on the Shoot. |
lastErrors []LastError | (Optional) LastErrors holds information about the last occurred error(s) during an operation. |
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this Shoot. It corresponds to the Shoot’s generation, which is updated on mutation by the API Server. |
retryCycleStartTime Kubernetes meta/v1.Time | (Optional) RetryCycleStartTime is the start time of the last retry cycle (used to determine how often an operation must be retried until we give up). |
seedName string | (Optional) SeedName is the name of the seed cluster that runs the control plane of the Shoot. This value is only written after a successful create/reconcile operation. It will be used when control planes are moved between Seeds. |
technicalID string | TechnicalID is the name that is used for creating the Seed namespace, the infrastructure resources, and basically everything that is related to this particular Shoot. This field is immutable. |
uid k8s.io/apimachinery/pkg/types.UID | UID is a unique identifier for the Shoot cluster to avoid portability between Kubernetes clusters. It is used to compute unique hashes. This field is immutable. |
clusterIdentity string | (Optional) ClusterIdentity is the identity of the Shoot cluster. This field is immutable. |
advertisedAddresses []ShootAdvertisedAddress | (Optional) List of addresses on which the Kube API server can be reached. |
migrationStartTime Kubernetes meta/v1.Time | (Optional) MigrationStartTime is the time when a migration to a different seed was initiated. |
credentials ShootCredentials | (Optional) Credentials contains information about the shoot credentials. |
lastHibernationTriggerTime Kubernetes meta/v1.Time | (Optional) LastHibernationTriggerTime indicates the last time when the hibernation controller managed to change the hibernation settings of the cluster |
lastMaintenance LastMaintenance | (Optional) LastMaintenance holds information about the last maintenance operations on the Shoot. |
ShootTemplate
ShootTemplate is a template for creating a Shoot object.
Field | Description | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||||||||||||||||||||||||||
spec ShootSpec | (Optional) Specification of the desired behavior of the Shoot.
|
SwapBehavior
(string
alias)
(Appears on: MemorySwapConfiguration)
SwapBehavior configures swap memory available to container workloads
SystemComponents
(Appears on: ShootSpec)
SystemComponents contains the settings of system components in the control or data plane of the Shoot cluster.
Field | Description |
---|---|
coreDNS CoreDNS | (Optional) CoreDNS contains the settings of the Core DNS components running in the data plane of the Shoot cluster. |
nodeLocalDNS NodeLocalDNS | (Optional) NodeLocalDNS contains the settings of the node local DNS components running in the data plane of the Shoot cluster. |
Toleration
(Appears on: ExposureClassScheduling, ProjectTolerations, ShootSpec)
Toleration is a toleration for a seed taint.
Field | Description |
---|---|
key string | Key is the toleration key to be applied to a project or shoot. |
value string | (Optional) Value is the toleration value corresponding to the toleration key. |
VersionClassification
(string
alias)
(Appears on: ExpirableVersion)
VersionClassification is the logical state of a version.
VerticalPodAutoscaler
(Appears on: Kubernetes)
VerticalPodAutoscaler contains the configuration flags for the Kubernetes vertical pod autoscaler.
Field | Description |
---|---|
enabled bool | Enabled specifies whether the Kubernetes VPA shall be enabled for the shoot cluster. |
evictAfterOOMThreshold Kubernetes meta/v1.Duration | (Optional) EvictAfterOOMThreshold defines the threshold that will lead to pod eviction in case it OOMed in less than the given threshold since its start and if it has only one container (default: 10m0s). |
evictionRateBurst int32 | (Optional) EvictionRateBurst defines the burst of pods that can be evicted (default: 1) |
evictionRateLimit float64 | (Optional) EvictionRateLimit defines the number of pods that can be evicted per second. A rate limit set to 0 or -1 will disable the rate limiter (default: -1). |
evictionTolerance float64 | (Optional) EvictionTolerance defines the fraction of replica count that can be evicted for update in case more than one pod can be evicted (default: 0.5). |
recommendationMarginFraction float64 | (Optional) RecommendationMarginFraction is the fraction of usage added as the safety margin to the recommended request (default: 0.15). |
updaterInterval Kubernetes meta/v1.Duration | (Optional) UpdaterInterval is the interval how often the updater should run (default: 1m0s). |
recommenderInterval Kubernetes meta/v1.Duration | (Optional) RecommenderInterval is the interval how often metrics should be fetched (default: 1m0s). |
Volume
(Appears on: Worker)
Volume contains information about the volume type, size, and encryption.
Field | Description |
---|---|
name string | (Optional) Name of the volume to make it referencable. |
type string | (Optional) Type is the type of the volume. |
size string | VolumeSize is the size of the volume. |
encrypted bool | (Optional) Encrypted determines if the volume should be encrypted. |
VolumeType
(Appears on: CloudProfileSpec)
VolumeType contains certain properties of a volume type.
Field | Description |
---|---|
class string | Class is the class of the volume type. |
name string | Name is the name of the volume type. |
usable bool | (Optional) Usable defines if the volume type can be used for shoot clusters. |
minSize k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) MinSize is the minimal supported storage size. |
WatchCacheSizes
(Appears on: KubeAPIServerConfig)
WatchCacheSizes contains configuration of the API server’s watch cache sizes.
Field | Description |
---|---|
default int32 | (Optional) Default configures the default watch cache size of the kube-apiserver
(flag |
resources []ResourceWatchCacheSize | (Optional) Resources configures the watch cache size of the kube-apiserver per resource
(flag |
Worker
(Appears on: Provider)
Worker is the base definition of a worker group.
Field | Description |
---|---|
annotations map[string]string | (Optional) Annotations is a map of key/value pairs for annotations for all the |
caBundle string | (Optional) CABundle is a certificate bundle which will be installed onto every machine of this worker pool. |
cri CRI | (Optional) CRI contains configurations of CRI support of every machine in the worker pool.
Defaults to a CRI with name |
kubernetes WorkerKubernetes | (Optional) Kubernetes contains configuration for Kubernetes components related to this worker pool. |
labels map[string]string | (Optional) Labels is a map of key/value pairs for labels for all the |
name string | Name is the name of the worker group. |
machine Machine | Machine contains information about the machine type and image. |
maximum int32 | Maximum is the maximum number of machines to create. This value is divided by the number of configured zones for a fair distribution. |
minimum int32 | Minimum is the minimum number of machines to create. This value is divided by the number of configured zones for a fair distribution. |
maxSurge k8s.io/apimachinery/pkg/util/intstr.IntOrString | (Optional) MaxSurge is maximum number of machines that are created during an update. This value is divided by the number of configured zones for a fair distribution. |
maxUnavailable k8s.io/apimachinery/pkg/util/intstr.IntOrString | (Optional) MaxUnavailable is the maximum number of machines that can be unavailable during an update. This value is divided by the number of configured zones for a fair distribution. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the provider-specific configuration for this worker pool. |
taints []Kubernetes core/v1.Taint | (Optional) Taints is a list of taints for all the |
volume Volume | (Optional) Volume contains information about the volume type and size. |
dataVolumes []DataVolume | (Optional) DataVolumes contains a list of additional worker volumes. |
kubeletDataVolumeName string | (Optional) KubeletDataVolumeName contains the name of a dataVolume that should be used for storing kubelet state. |
zones []string | (Optional) Zones is a list of availability zones that are used to evenly distribute this worker pool. Optional as not every provider may support availability zones. |
systemComponents WorkerSystemComponents | (Optional) SystemComponents contains configuration for system components related to this worker pool |
machineControllerManager MachineControllerManagerSettings | (Optional) MachineControllerManagerSettings contains configurations for different worker-pools. Eg. MachineDrainTimeout, MachineHealthTimeout. |
sysctls map[string]string | (Optional) Sysctls is a map of kernel settings to apply on all machines in this worker pool. |
WorkerKubernetes
(Appears on: Worker)
WorkerKubernetes contains configuration for Kubernetes components related to this worker pool.
Field | Description |
---|---|
kubelet KubeletConfig | (Optional) Kubelet contains configuration settings for all kubelets of this worker pool.
If set, all |
version string | (Optional) Version is the semantic Kubernetes version to use for the Kubelet in this Worker Group. If not specified the kubelet version is derived from the global shoot cluster kubernetes version. version must be equal or lower than the version of the shoot kubernetes version. Only one minor version difference to other worker groups and global kubernetes version is allowed. |
WorkerSystemComponents
(Appears on: Worker)
WorkerSystemComponents contains configuration for system components related to this worker pool
Field | Description |
---|---|
allow bool | Allow determines whether the pool should be allowed to host system components or not (defaults to true) |
WorkersSettings
(Appears on: Provider)
WorkersSettings contains settings for all workers.
Field | Description |
---|---|
sshAccess SSHAccess | (Optional) SSHAccess contains settings regarding ssh access to the worker nodes. |
Generated with gen-crd-api-reference-docs
1.1.4 - Extensions
Packages:
extensions.gardener.cloud/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
Resource Types:- BackupBucket
- BackupEntry
- Bastion
- Cluster
- ContainerRuntime
- ControlPlane
- DNSRecord
- Extension
- Infrastructure
- Network
- OperatingSystemConfig
- Worker
BackupBucket
BackupBucket is a specification for backup bucket.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||
kind string | BackupBucket | ||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||
spec BackupBucketSpec | Specification of the BackupBucket. If the object’s deletion timestamp is set, this field is immutable.
| ||||||
status BackupBucketStatus | (Optional) |
BackupEntry
BackupEntry is a specification for backup Entry.
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||||
kind string | BackupEntry | ||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||||
spec BackupEntrySpec | Specification of the BackupEntry. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||
status BackupEntryStatus | (Optional) |
Bastion
Bastion is a bastion or jump host that is dynamically created to provide SSH access to shoot nodes.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||
kind string | Bastion | ||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||
spec BastionSpec | Spec is the specification of this Bastion. If the object’s deletion timestamp is set, this field is immutable.
| ||||||
status BastionStatus | (Optional) Status is the bastion’s status. |
Cluster
Cluster is a specification for a Cluster resource.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||
kind string | Cluster | ||||||
metadata Kubernetes meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||
spec ClusterSpec |
|
ContainerRuntime
ContainerRuntime is a specification for a container runtime resource.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||
kind string | ContainerRuntime | ||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||
spec ContainerRuntimeSpec | Specification of the ContainerRuntime. If the object’s deletion timestamp is set, this field is immutable.
| ||||||
status ContainerRuntimeStatus | (Optional) |
ControlPlane
ControlPlane is a specification for a ControlPlane resource.
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||||
kind string | ControlPlane | ||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||||
spec ControlPlaneSpec | Specification of the ControlPlane. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||
status ControlPlaneStatus | (Optional) |
DNSRecord
DNSRecord is a specification for a DNSRecord resource.
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||||||||||
kind string | DNSRecord | ||||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||||||||||
spec DNSRecordSpec | Specification of the DNSRecord. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||||||||
status DNSRecordStatus | (Optional) |
Extension
Extension is a specification for a Extension resource.
Field | Description | ||
---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||
kind string | Extension | ||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||
spec ExtensionSpec | Specification of the Extension. If the object’s deletion timestamp is set, this field is immutable.
| ||
status ExtensionStatus | (Optional) |
Infrastructure
Infrastructure is a specification for cloud provider infrastructure.
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||
kind string | Infrastructure | ||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||
spec InfrastructureSpec | Specification of the Infrastructure. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||
status InfrastructureStatus | (Optional) |
Network
Network is the specification for cluster networking.
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||
kind string | Network | ||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||
spec NetworkSpec | Specification of the Network. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||
status NetworkStatus | (Optional) |
OperatingSystemConfig
OperatingSystemConfig is a specification for a OperatingSystemConfig resource
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||||||
kind string | OperatingSystemConfig | ||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||||||
spec OperatingSystemConfigSpec | Specification of the OperatingSystemConfig. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||||
status OperatingSystemConfigStatus | (Optional) |
Worker
Worker is a specification for a Worker resource.
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | extensions.gardener.cloud/v1alpha1 | ||||||||||||
kind string | Worker | ||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional)
Refer to the Kubernetes API documentation for the fields of the
metadata field. | ||||||||||||
spec WorkerSpec | Specification of the Worker. If the object’s deletion timestamp is set, this field is immutable.
| ||||||||||||
status WorkerStatus | (Optional) |
BackupBucketSpec
(Appears on: BackupBucket)
BackupBucketSpec is the spec for an BackupBucket resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
region string | Region is the region of this bucket. This field is immutable. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the credentials to access object store. |
BackupBucketStatus
(Appears on: BackupBucket)
BackupBucketStatus is the status for an BackupBucket resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
generatedSecretRef Kubernetes core/v1.SecretReference | (Optional) GeneratedSecretRef is reference to the secret generated by backup bucket, which will have object store specific credentials. |
BackupEntrySpec
(Appears on: BackupEntry)
BackupEntrySpec is the spec for an BackupEntry resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
backupBucketProviderStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) BackupBucketProviderStatus contains the provider status that has
been generated by the controller responsible for the |
region string | Region is the region of this Entry. This field is immutable. |
bucketName string | BucketName is the name of backup bucket for this Backup Entry. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the credentials to access object store. |
BackupEntryStatus
(Appears on: BackupEntry)
BackupEntryStatus is the status for an BackupEntry resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
BastionIngressPolicy
(Appears on: BastionSpec)
BastionIngressPolicy represents an ingress policy for SSH bastion hosts.
Field | Description |
---|---|
ipBlock Kubernetes networking/v1.IPBlock | IPBlock defines an IP block that is allowed to access the bastion. |
BastionSpec
(Appears on: Bastion)
BastionSpec contains the specification for an SSH bastion host.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
userData []byte | UserData is the base64-encoded user data for the bastion instance. This should contain code to provision the SSH key on the bastion instance. This field is immutable. |
ingress []BastionIngressPolicy | Ingress controls from where the created bastion host should be reachable. |
BastionStatus
(Appears on: Bastion)
BastionStatus holds the most recently observed status of the Bastion.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
ingress Kubernetes core/v1.LoadBalancerIngress | (Optional) Ingress is the external IP and/or hostname of the bastion host. |
CRIConfig
(Appears on: OperatingSystemConfigSpec)
CRIConfig contains configurations of the CRI library.
Field | Description |
---|---|
name CRIName | Name is a mandatory string containing the name of the CRI library. Supported values are |
CRIName
(string
alias)
(Appears on: CRIConfig)
CRIName is a type alias for the CRI name string.
CloudConfig
(Appears on: OperatingSystemConfigStatus)
CloudConfig contains the generated output for the given operating system config spec. It contains a reference to a secret as the result may contain confidential data.
Field | Description |
---|---|
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the actual result of the generated cloud config. |
ClusterSpec
(Appears on: Cluster)
ClusterSpec is the spec for a Cluster resource.
Field | Description |
---|---|
cloudProfile k8s.io/apimachinery/pkg/runtime.RawExtension | CloudProfile is a raw extension field that contains the cloudprofile resource referenced by the shoot that has to be reconciled. |
seed k8s.io/apimachinery/pkg/runtime.RawExtension | Seed is a raw extension field that contains the seed resource referenced by the shoot that has to be reconciled. |
shoot k8s.io/apimachinery/pkg/runtime.RawExtension | Shoot is a raw extension field that contains the shoot resource that has to be reconciled. |
ContainerRuntimeSpec
(Appears on: ContainerRuntime)
ContainerRuntimeSpec is the spec for a ContainerRuntime resource.
Field | Description |
---|---|
binaryPath string | BinaryPath is the Worker’s machine path where container runtime extensions should copy the binaries to. |
workerPool ContainerRuntimeWorkerPool | WorkerPool identifies the worker pool of the Shoot. For each worker pool and type, Gardener deploys a ContainerRuntime CRD. |
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
ContainerRuntimeStatus
(Appears on: ContainerRuntime)
ContainerRuntimeStatus is the status for a ContainerRuntime resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
ContainerRuntimeWorkerPool
(Appears on: ContainerRuntimeSpec)
ContainerRuntimeWorkerPool identifies a Shoot worker pool by its name and selector.
Field | Description |
---|---|
name string | Name specifies the name of the worker pool the container runtime should be available for. This field is immutable. |
selector Kubernetes meta/v1.LabelSelector | Selector is the label selector used by the extension to match the nodes belonging to the worker pool. |
ControlPlaneSpec
(Appears on: ControlPlane)
ControlPlaneSpec is the spec of a ControlPlane resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
purpose Purpose | (Optional) Purpose contains the data if a cloud provider needs additional components in order to expose the control plane. This field is immutable. |
infrastructureProviderStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) InfrastructureProviderStatus contains the provider status that has
been generated by the controller responsible for the |
region string | Region is the region of this control plane. This field is immutable. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the cloud provider specific credentials. |
ControlPlaneStatus
(Appears on: ControlPlane)
ControlPlaneStatus is the status of a ControlPlane resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
DNSRecordSpec
(Appears on: DNSRecord)
DNSRecordSpec is the spec of a DNSRecord resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the cloud provider specific credentials. |
region string | (Optional) Region is the region of this DNS record. If not specified, the region specified in SecretRef will be used. If that is also not specified, the extension controller will use its default region. |
zone string | (Optional) Zone is the DNS hosted zone of this DNS record. If not specified, it will be determined automatically by getting all hosted zones of the account and searching for the longest zone name that is a suffix of Name. |
name string | Name is the fully qualified domain name, e.g. “api. |
recordType DNSRecordType | RecordType is the DNS record type. Only A, CNAME, and TXT records are currently supported. This field is immutable. |
values []string | Values is a list of IP addresses for A records, a single hostname for CNAME records, or a list of texts for TXT records. |
ttl int64 | (Optional) TTL is the time to live in seconds. Defaults to 120. |
DNSRecordStatus
(Appears on: DNSRecord)
DNSRecordStatus is the status of a DNSRecord resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
zone string | (Optional) Zone is the DNS hosted zone of this DNS record. |
DNSRecordType
(string
alias)
(Appears on: DNSRecordSpec)
DNSRecordType is a string alias.
DataVolume
(Appears on: WorkerPool)
DataVolume contains information about a data volume.
Field | Description |
---|---|
name string | Name of the volume to make it referencable. |
type string | (Optional) Type is the type of the volume. |
size string | Size is the of the root volume. |
encrypted bool | (Optional) Encrypted determines if the volume should be encrypted. |
DefaultSpec
(Appears on: BackupBucketSpec, BackupEntrySpec, BastionSpec, ContainerRuntimeSpec, ControlPlaneSpec, DNSRecordSpec, ExtensionSpec, InfrastructureSpec, NetworkSpec, OperatingSystemConfigSpec, WorkerSpec)
DefaultSpec contains common status fields for every extension resource.
Field | Description |
---|---|
type string | Type contains the instance of the resource’s kind. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is the provider specific configuration. |
DefaultStatus
(Appears on: BackupBucketStatus, BackupEntryStatus, BastionStatus, ContainerRuntimeStatus, ControlPlaneStatus, DNSRecordStatus, ExtensionStatus, InfrastructureStatus, NetworkStatus, OperatingSystemConfigStatus, WorkerStatus)
DefaultStatus contains common status fields for every extension resource.
Field | Description |
---|---|
providerStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderStatus contains provider-specific status. |
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | (Optional) Conditions represents the latest available observations of a Seed’s current state. |
lastError github.com/gardener/gardener/pkg/apis/core/v1beta1.LastError | (Optional) LastError holds information about the last occurred error during an operation. |
lastOperation github.com/gardener/gardener/pkg/apis/core/v1beta1.LastOperation | (Optional) LastOperation holds information about the last operation on the resource. |
observedGeneration int64 | ObservedGeneration is the most recent generation observed for this resource. |
state k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) State can be filled by the operating controller with what ever data it needs. |
resources []github.com/gardener/gardener/pkg/apis/core/v1beta1.NamedResourceReference | (Optional) Resources holds a list of named resource references that can be referred to in the state by their names. |
DropIn
(Appears on: Unit)
DropIn is a drop-in configuration for a systemd unit.
Field | Description |
---|---|
name string | Name is the name of the drop-in. |
content string | Content is the content of the drop-in. |
ExtensionSpec
(Appears on: Extension)
ExtensionSpec is the spec for a Extension resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
ExtensionStatus
(Appears on: Extension)
ExtensionStatus is the status for a Extension resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
File
(Appears on: OperatingSystemConfigSpec, OperatingSystemConfigStatus)
File is a file that should get written to the host’s file system. The content can either be inlined or referenced from a secret in the same namespace.
Field | Description |
---|---|
path string | Path is the path of the file system where the file should get written to. |
permissions int32 | (Optional) Permissions describes with which permissions the file should get written to the file system. Should be defaulted to octal 0644. |
content FileContent | Content describe the file’s content. |
FileCodecID
(string
alias)
FileCodecID is the id of a FileCodec for cloud-init scripts.
FileContent
(Appears on: File)
FileContent can either reference a secret or contain inline configuration.
Field | Description |
---|---|
secretRef FileContentSecretRef | (Optional) SecretRef is a struct that contains information about the referenced secret. |
inline FileContentInline | (Optional) Inline is a struct that contains information about the inlined data. |
transmitUnencoded bool | (Optional) TransmitUnencoded set to true will ensure that the os-extension does not encode the file content when sent to the node. This for example can be used to manipulate the clear-text content before it reaches the node. |
imageRef FileContentImageRef | (Optional) ImageRef describes a container image which contains a file. |
FileContentImageRef
(Appears on: FileContent)
FileContentImageRef describes a container image which contains a file
Field | Description |
---|---|
image string | Image contains the container image repository with tag. |
filePathInImage string | FilePathInImage contains the path in the image to the file that should be extracted. |
FileContentInline
(Appears on: FileContent)
FileContentInline contains keys for inlining a file content’s data and encoding.
Field | Description |
---|---|
encoding string | Encoding is the file’s encoding (e.g. base64). |
data string | Data is the file’s data. |
FileContentSecretRef
(Appears on: FileContent)
FileContentSecretRef contains keys for referencing a file content’s data from a secret in the same namespace.
Field | Description |
---|---|
name string | Name is the name of the secret. |
dataKey string | DataKey is the key in the secret’s |
IPFamily
(string
alias)
(Appears on: NetworkSpec)
IPFamily is a type for specifying an IP protocol version to use in Gardener clusters.
InfrastructureSpec
(Appears on: Infrastructure)
InfrastructureSpec is the spec for an Infrastructure resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
region string | Region is the region of this infrastructure. This field is immutable. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the cloud provider credentials. |
sshPublicKey []byte | (Optional) SSHPublicKey is the public SSH key that should be used with this infrastructure. |
InfrastructureStatus
(Appears on: Infrastructure)
InfrastructureStatus is the status for an Infrastructure resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
nodesCIDR string | (Optional) NodesCIDR is the CIDR of the node network that was optionally created by the acting extension controller. This might be needed in environments in which the CIDR for the network for the shoot worker node cannot be statically defined in the Shoot resource but must be computed dynamically. |
MachineDeployment
(Appears on: WorkerStatus)
MachineDeployment is a created machine deployment.
Field | Description |
---|---|
name string | Name is the name of the |
minimum int32 | Minimum is the minimum number for this machine deployment. |
maximum int32 | Maximum is the maximum number for this machine deployment. |
MachineImage
(Appears on: WorkerPool)
MachineImage contains logical information about the name and the version of the machie image that should be used. The logical information must be mapped to the provider-specific information (e.g., AMIs, …) by the provider itself.
Field | Description |
---|---|
name string | Name is the logical name of the machine image. |
version string | Version is the version of the machine image. |
NetworkSpec
(Appears on: Network)
NetworkSpec is the spec for an Network resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
podCIDR string | PodCIDR defines the CIDR that will be used for pods. This field is immutable. |
serviceCIDR string | ServiceCIDR defines the CIDR that will be used for services. This field is immutable. |
ipFamilies []IPFamily | (Optional) IPFamilies specifies the IP protocol versions to use for shoot networking. This field is immutable. See https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md |
NetworkStatus
(Appears on: Network)
NetworkStatus is the status for an Network resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
NodeTemplate
(Appears on: WorkerPool)
NodeTemplate contains information about the expected node properties.
Field | Description |
---|---|
capacity Kubernetes core/v1.ResourceList | Capacity represents the expected Node capacity. |
Object
Object is an extension object resource.
OperatingSystemConfigPurpose
(string
alias)
(Appears on: OperatingSystemConfigSpec)
OperatingSystemConfigPurpose is a string alias.
OperatingSystemConfigSpec
(Appears on: OperatingSystemConfig)
OperatingSystemConfigSpec is the spec for a OperatingSystemConfig resource.
Field | Description |
---|---|
criConfig CRIConfig | (Optional) CRI config is a structure contains configurations of the CRI library |
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
purpose OperatingSystemConfigPurpose | Purpose describes how the result of this OperatingSystemConfig is used by Gardener. Either it
gets sent to the |
reloadConfigFilePath string | (Optional) ReloadConfigFilePath is the path to the generated operating system configuration. If set, controllers are asked to use it when determining the .status.command of this resource. For example, if for CoreOS the reload-path might be “/var/lib/config”; then the controller shall set .status.command to “/usr/bin/coreos-cloudinit –from-file=/var/lib/config”. TODO(rfranzke): Deprecate this field once UseGardenerNodeAgent feature gate is promoted to GA. |
units []Unit | (Optional) Units is a list of unit for the operating system configuration (usually, a systemd unit). |
files []File | (Optional) Files is a list of files that should get written to the host’s file system. |
OperatingSystemConfigStatus
(Appears on: OperatingSystemConfig)
OperatingSystemConfigStatus is the status for a OperatingSystemConfig resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
extensionUnits []Unit | (Optional) ExtensionUnits is a list of additional systemd units provided by the extension. |
extensionFiles []File | (Optional) ExtensionFiles is a list of additional files provided by the extension. |
cloudConfig CloudConfig | (Optional) CloudConfig is a structure for containing the generated output for the given operating system config spec. It contains a reference to a secret as the result may contain confidential data. |
command string | (Optional) Command is the command whose execution renews/reloads the cloud config on an existing VM, e.g.
“/usr/bin/reload-cloud-config -from-file= |
units []string | (Optional) Units is a list of systemd unit names that are part of the generated Cloud Config and shall be restarted when a new version has been downloaded. TODO(rfranzke): Deprecate this field once UseGardenerNodeAgent feature gate is promoted to GA. |
files []string | (Optional) Files is a list of file paths that are part of the generated Cloud Config and shall be written to the host’s file system. TODO(rfranzke): Deprecate this field once UseGardenerNodeAgent feature gate is promoted to GA. |
Purpose
(string
alias)
(Appears on: ControlPlaneSpec)
Purpose is a string alias.
Spec
Spec is the spec section of an Object.
Status
Status is the status of an Object.
Unit
(Appears on: OperatingSystemConfigSpec, OperatingSystemConfigStatus)
Unit is a unit for the operating system configuration (usually, a systemd unit).
Field | Description |
---|---|
name string | Name is the name of a unit. |
command UnitCommand | (Optional) Command is the unit’s command. |
enable bool | (Optional) Enable describes whether the unit is enabled or not. |
content string | (Optional) Content is the unit’s content. |
dropIns []DropIn | (Optional) DropIns is a list of drop-ins for this unit. |
filePaths []string | FilePaths is a list of files the unit depends on. If any file changes a restart of the dependent unit will be triggered. For each FilePath there must exist a File with matching Path in OperatingSystemConfig.Spec.Files. |
UnitCommand
(string
alias)
(Appears on: Unit)
UnitCommand is a string alias.
Volume
(Appears on: WorkerPool)
Volume contains information about the root disks that should be used for worker pools.
Field | Description |
---|---|
name string | (Optional) Name of the volume to make it referencable. |
type string | (Optional) Type is the type of the volume. |
size string | Size is the of the root volume. |
encrypted bool | (Optional) Encrypted determines if the volume should be encrypted. |
WorkerPool
(Appears on: WorkerSpec)
WorkerPool is the definition of a specific worker pool.
Field | Description |
---|---|
machineType string | MachineType contains information about the machine type that should be used for this worker pool. |
maximum int32 | Maximum is the maximum size of the worker pool. |
maxSurge k8s.io/apimachinery/pkg/util/intstr.IntOrString | MaxSurge is maximum number of VMs that are created during an update. |
maxUnavailable k8s.io/apimachinery/pkg/util/intstr.IntOrString | MaxUnavailable is the maximum number of VMs that can be unavailable during an update. |
annotations map[string]string | (Optional) Annotations is a map of key/value pairs for annotations for all the |
labels map[string]string | (Optional) Labels is a map of key/value pairs for labels for all the |
taints []Kubernetes core/v1.Taint | (Optional) Taints is a list of taints for all the |
machineImage MachineImage | MachineImage contains logical information about the name and the version of the machie image that should be used. The logical information must be mapped to the provider-specific information (e.g., AMIs, …) by the provider itself. |
minimum int32 | Minimum is the minimum size of the worker pool. |
name string | Name is the name of this worker pool. |
providerConfig k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) ProviderConfig is a provider specific configuration for the worker pool. |
userData []byte | UserData is a base64-encoded string that contains the data that is sent to the provider’s APIs when a new machine/VM that is part of this worker pool shall be spawned. |
volume Volume | (Optional) Volume contains information about the root disks that should be used for this worker pool. |
dataVolumes []DataVolume | (Optional) DataVolumes contains a list of additional worker volumes. |
kubeletDataVolumeName string | (Optional) KubeletDataVolumeName contains the name of a dataVolume that should be used for storing kubelet state. |
zones []string | (Optional) Zones contains information about availability zones for this worker pool. |
machineControllerManager github.com/gardener/gardener/pkg/apis/core/v1beta1.MachineControllerManagerSettings | (Optional) MachineControllerManagerSettings contains configurations for different worker-pools. Eg. MachineDrainTimeout, MachineHealthTimeout. |
kubernetesVersion string | (Optional) KubernetesVersion is the kubernetes version in this worker pool |
nodeTemplate NodeTemplate | (Optional) NodeTemplate contains resource information of the machine which is used by Cluster Autoscaler to generate nodeTemplate during scaling a nodeGroup from zero |
architecture string | (Optional) Architecture is the CPU architecture of the worker pool machines and machine image. |
WorkerSpec
(Appears on: Worker)
WorkerSpec is the spec for a Worker resource.
Field | Description |
---|---|
DefaultSpec DefaultSpec | (Members of DefaultSpec is a structure containing common fields used by all extension resources. |
infrastructureProviderStatus k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) InfrastructureProviderStatus is a raw extension field that contains the provider status that has
been generated by the controller responsible for the |
region string | Region is the name of the region where the worker pool should be deployed to. This field is immutable. |
secretRef Kubernetes core/v1.SecretReference | SecretRef is a reference to a secret that contains the cloud provider specific credentials. |
sshPublicKey []byte | (Optional) SSHPublicKey is the public SSH key that should be used with these workers. |
pools []WorkerPool | Pools is a list of worker pools. |
WorkerStatus
(Appears on: Worker)
WorkerStatus is the status for a Worker resource.
Field | Description |
---|---|
DefaultStatus DefaultStatus | (Members of DefaultStatus is a structure containing common fields used by all extension resources. |
machineDeployments []MachineDeployment | MachineDeployments is a list of created machine deployments. It will be used to e.g. configure the cluster-autoscaler properly. |
machineDeploymentsLastUpdateTime Kubernetes meta/v1.Time | (Optional) MachineDeploymentsLastUpdateTime is the timestamp when the status.MachineDeployments slice was last updated. |
Generated with gen-crd-api-reference-docs
1.1.5 - Operations
Packages:
operations.gardener.cloud/v1alpha1
Package v1alpha1 is a version of the API.
Resource Types:Bastion
Bastion holds details about an SSH bastion for a shoot cluster.
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | operations.gardener.cloud/v1alpha1 | ||||||||||
kind string | Bastion | ||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||
spec BastionSpec | Specification of the Bastion.
| ||||||||||
status BastionStatus | (Optional) Most recently observed status of the Bastion. |
BastionIngressPolicy
(Appears on: BastionSpec)
BastionIngressPolicy represents an ingress policy for SSH bastion hosts.
Field | Description |
---|---|
ipBlock Kubernetes networking/v1.IPBlock | IPBlock defines an IP block that is allowed to access the bastion. |
BastionSpec
(Appears on: Bastion)
BastionSpec is the specification of a Bastion.
Field | Description |
---|---|
shootRef Kubernetes core/v1.LocalObjectReference | ShootRef defines the target shoot for a Bastion. The name field of the ShootRef is immutable. |
seedName string | (Optional) SeedName is the name of the seed to which this Bastion is currently scheduled. This field is populated at the beginning of a create/reconcile operation. |
providerType string | (Optional) ProviderType is cloud provider used by the referenced Shoot. |
sshPublicKey string | SSHPublicKey is the user’s public key. This field is immutable. |
ingress []BastionIngressPolicy | Ingress controls from where the created bastion host should be reachable. |
BastionStatus
(Appears on: Bastion)
BastionStatus holds the most recently observed status of the Bastion.
Field | Description |
---|---|
ingress Kubernetes core/v1.LoadBalancerIngress | (Optional) Ingress holds the public IP and/or hostname of the bastion instance. |
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | (Optional) Conditions represents the latest available observations of a Bastion’s current state. |
lastHeartbeatTimestamp Kubernetes meta/v1.Time | (Optional) LastHeartbeatTimestamp is the time when the bastion was last marked as not to be deleted. When this is set, the ExpirationTimestamp is advanced as well. |
expirationTimestamp Kubernetes meta/v1.Time | (Optional) ExpirationTimestamp is the time after which a Bastion is supposed to be garbage collected. |
observedGeneration int64 | (Optional) ObservedGeneration is the most recent generation observed for this Bastion. It corresponds to the Bastion’s generation, which is updated on mutation by the API Server. |
Generated with gen-crd-api-reference-docs
1.1.6 - Operator
Packages:
operator.gardener.cloud/v1alpha1
Package v1alpha1 contains the configuration of the Gardener Operator.
Resource Types:AuditWebhook
(Appears on: GardenerAPIServerConfig, KubeAPIServerConfig)
AuditWebhook contains settings related to an audit webhook configuration.
Field | Description |
---|---|
batchMaxSize int32 | (Optional) BatchMaxSize is the maximum size of a batch. |
kubeconfigSecretName string | KubeconfigSecretName specifies the name of a secret containing the kubeconfig for this webhook. |
version string | (Optional) Version is the API version to send and expect from the webhook. |
Authentication
(Appears on: KubeAPIServerConfig)
Authentication contains settings related to authentication.
Field | Description |
---|---|
webhook AuthenticationWebhook | (Optional) Webhook contains settings related to an authentication webhook configuration. |
AuthenticationWebhook
(Appears on: Authentication)
AuthenticationWebhook contains settings related to an authentication webhook configuration.
Field | Description |
---|---|
cacheTTL Kubernetes meta/v1.Duration | (Optional) CacheTTL is the duration to cache responses from the webhook authenticator. |
kubeconfigSecretName string | KubeconfigSecretName specifies the name of a secret containing the kubeconfig for this webhook. |
version string | (Optional) Version is the API version to send and expect from the webhook. |
Backup
(Appears on: ETCDMain)
Backup contains the object store configuration for backups for the virtual garden etcd.
Field | Description |
---|---|
provider string | Provider is a provider name. This field is immutable. |
bucketName string | BucketName is the name of the backup bucket. |
secretRef Kubernetes core/v1.LocalObjectReference | SecretRef is a reference to a Secret object containing the cloud provider credentials for the object store where backups should be stored. It should have enough privileges to manipulate the objects as well as buckets. |
ControlPlane
(Appears on: VirtualCluster)
ControlPlane holds information about the general settings for the control plane of the virtual garden cluster.
Field | Description |
---|---|
highAvailability HighAvailability | (Optional) HighAvailability holds the configuration settings for high availability settings. |
Credentials
(Appears on: GardenStatus)
Credentials contains information about the virtual garden cluster credentials.
Field | Description |
---|---|
rotation CredentialsRotation | (Optional) Rotation contains information about the credential rotations. |
CredentialsRotation
(Appears on: Credentials)
CredentialsRotation contains information about the rotation of credentials.
Field | Description |
---|---|
certificateAuthorities github.com/gardener/gardener/pkg/apis/core/v1beta1.CARotation | (Optional) CertificateAuthorities contains information about the certificate authority credential rotation. |
serviceAccountKey github.com/gardener/gardener/pkg/apis/core/v1beta1.ServiceAccountKeyRotation | (Optional) ServiceAccountKey contains information about the service account key credential rotation. |
etcdEncryptionKey github.com/gardener/gardener/pkg/apis/core/v1beta1.ETCDEncryptionKeyRotation | (Optional) ETCDEncryptionKey contains information about the ETCD encryption key credential rotation. |
observability github.com/gardener/gardener/pkg/apis/core/v1beta1.ObservabilityRotation | (Optional) Observability contains information about the observability credential rotation. |
DNS
(Appears on: VirtualCluster)
DNS holds information about DNS settings.
Field | Description |
---|---|
domains []string | (Optional) Domains are the external domains of the virtual garden cluster. The first given domain in this list is immutable. |
ETCD
(Appears on: VirtualCluster)
ETCD contains configuration for the etcds of the virtual garden cluster.
Field | Description |
---|---|
main ETCDMain | (Optional) Main contains configuration for the main etcd. |
events ETCDEvents | (Optional) Events contains configuration for the events etcd. |
ETCDEvents
(Appears on: ETCD)
ETCDEvents contains configuration for the events etcd.
Field | Description |
---|---|
storage Storage | (Optional) Storage contains storage configuration. |
ETCDMain
(Appears on: ETCD)
ETCDMain contains configuration for the main etcd.
Field | Description |
---|---|
backup Backup | (Optional) Backup contains the object store configuration for backups for the virtual garden etcd. |
storage Storage | (Optional) Storage contains storage configuration. |
Garden
Garden describes a list of gardens.
Field | Description | ||||
---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec GardenSpec | Spec contains the specification of this garden.
| ||||
status GardenStatus | Status contains the status of this garden. |
GardenSpec
(Appears on: Garden)
GardenSpec contains the specification of a garden environment.
Field | Description |
---|---|
runtimeCluster RuntimeCluster | RuntimeCluster contains configuration for the runtime cluster. |
virtualCluster VirtualCluster | VirtualCluster contains configuration for the virtual cluster. |
GardenStatus
(Appears on: Garden)
GardenStatus is the status of a garden environment.
Field | Description |
---|---|
gardener github.com/gardener/gardener/pkg/apis/core/v1beta1.Gardener | (Optional) Gardener holds information about the Gardener which last acted on the Garden. |
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | Conditions is a list of conditions. |
lastOperation github.com/gardener/gardener/pkg/apis/core/v1beta1.LastOperation | (Optional) LastOperation holds information about the last operation on the Garden. |
observedGeneration int64 | ObservedGeneration is the most recent generation observed for this resource. |
credentials Credentials | (Optional) Credentials contains information about the virtual garden cluster credentials. |
Gardener
(Appears on: VirtualCluster)
Gardener contains the configuration settings for the Gardener components.
Field | Description |
---|---|
clusterIdentity string | ClusterIdentity is the identity of the garden cluster. This field is immutable. |
gardenerAPIServer GardenerAPIServerConfig | (Optional) APIServer contains configuration settings for the gardener-apiserver. |
gardenerAdmissionController GardenerAdmissionControllerConfig | (Optional) AdmissionController contains configuration settings for the gardener-admission-controller. |
gardenerControllerManager GardenerControllerManagerConfig | (Optional) ControllerManager contains configuration settings for the gardener-controller-manager. |
gardenerScheduler GardenerSchedulerConfig | (Optional) Scheduler contains configuration settings for the gardener-scheduler. |
GardenerAPIServerConfig
(Appears on: Gardener)
GardenerAPIServerConfig contains configuration settings for the gardener-apiserver.
Field | Description |
---|---|
KubernetesConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.KubernetesConfig | (Members of |
admissionPlugins []github.com/gardener/gardener/pkg/apis/core/v1beta1.AdmissionPlugin | (Optional) AdmissionPlugins contains the list of user-defined admission plugins (additional to those managed by Gardener), and, if desired, the corresponding configuration. |
auditConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.AuditConfig | (Optional) AuditConfig contains configuration settings for the audit of the kube-apiserver. |
auditWebhook AuditWebhook | (Optional) AuditWebhook contains settings related to an audit webhook configuration. |
logging github.com/gardener/gardener/pkg/apis/core/v1beta1.APIServerLogging | (Optional) Logging contains configuration for the log level and HTTP access logs. |
requests github.com/gardener/gardener/pkg/apis/core/v1beta1.APIServerRequests | (Optional) Requests contains configuration for request-specific settings for the kube-apiserver. |
watchCacheSizes github.com/gardener/gardener/pkg/apis/core/v1beta1.WatchCacheSizes | (Optional) WatchCacheSizes contains configuration of the API server’s watch cache sizes.
Configuring these flags might be useful for large-scale Garden clusters with a lot of parallel update requests
and a lot of watching controllers (e.g. large ManagedSeed clusters). When the API server’s watch cache’s
capacity is too small to cope with the amount of update requests and watchers for a particular resource, it
might happen that controller watches are permanently stopped with |
GardenerAdmissionControllerConfig
(Appears on: Gardener)
GardenerAdmissionControllerConfig contains configuration settings for the gardener-admission-controller.
Field | Description |
---|---|
logLevel string | (Optional) LogLevel is the configured log level for the gardener-admission-controller. Must be one of [info,debug,error]. Defaults to info. |
resourceAdmissionConfiguration ResourceAdmissionConfiguration | (Optional) ResourceAdmissionConfiguration is the configuration for resource size restrictions for arbitrary Group-Version-Kinds. |
GardenerControllerManagerConfig
(Appears on: Gardener)
GardenerControllerManagerConfig contains configuration settings for the gardener-controller-manager.
Field | Description |
---|---|
KubernetesConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.KubernetesConfig | (Members of |
defaultProjectQuotas []ProjectQuotaConfiguration | (Optional) DefaultProjectQuotas is the default configuration matching projects are set up with if a quota is not already specified. |
logLevel string | (Optional) LogLevel is the configured log level for the gardener-controller-manager. Must be one of [info,debug,error]. Defaults to info. |
GardenerSchedulerConfig
(Appears on: Gardener)
GardenerSchedulerConfig contains configuration settings for the gardener-scheduler.
Field | Description |
---|---|
KubernetesConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.KubernetesConfig | (Members of |
logLevel string | (Optional) LogLevel is the configured log level for the gardener-scheduler. Must be one of [info,debug,error]. Defaults to info. |
GroupResource
(Appears on: KubeAPIServerConfig)
GroupResource contains a list of resources which should be stored in etcd-events instead of etcd-main.
Field | Description |
---|---|
group string | Group is the API group name. |
resource string | Resource is the resource name. |
HighAvailability
(Appears on: ControlPlane)
HighAvailability specifies the configuration settings for high availability for a resource.
KubeAPIServerConfig
(Appears on: Kubernetes)
KubeAPIServerConfig contains configuration settings for the kube-apiserver.
Field | Description |
---|---|
KubeAPIServerConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.KubeAPIServerConfig | (Members of KubeAPIServerConfig contains all configuration values not specific to the virtual garden cluster. |
auditWebhook AuditWebhook | (Optional) AuditWebhook contains settings related to an audit webhook configuration. |
authentication Authentication | (Optional) Authentication contains settings related to authentication. |
resourcesToStoreInETCDEvents []GroupResource | (Optional) ResourcesToStoreInETCDEvents contains a list of resources which should be stored in etcd-events instead of etcd-main. The ‘events’ resource is always stored in etcd-events. Note that adding or removing resources from this list will not migrate them automatically from the etcd-main to etcd-events or vice versa. |
sni SNI | (Optional) SNI contains configuration options for the TLS SNI settings. |
KubeControllerManagerConfig
(Appears on: Kubernetes)
KubeControllerManagerConfig contains configuration settings for the kube-controller-manager.
Field | Description |
---|---|
KubeControllerManagerConfig github.com/gardener/gardener/pkg/apis/core/v1beta1.KubeControllerManagerConfig | (Members of KubeControllerManagerConfig contains all configuration values not specific to the virtual garden cluster. |
certificateSigningDuration Kubernetes meta/v1.Duration | (Optional) CertificateSigningDuration is the maximum length of duration signed certificates will be given. Individual CSRs
may request shorter certs by setting |
Kubernetes
(Appears on: VirtualCluster)
Kubernetes contains the version and configuration options for the Kubernetes components of the virtual garden cluster.
Field | Description |
---|---|
kubeAPIServer KubeAPIServerConfig | (Optional) KubeAPIServer contains configuration settings for the kube-apiserver. |
kubeControllerManager KubeControllerManagerConfig | (Optional) KubeControllerManager contains configuration settings for the kube-controller-manager. |
version string | Version is the semantic Kubernetes version to use for the virtual garden cluster. |
Maintenance
(Appears on: VirtualCluster)
Maintenance contains information about the time window for maintenance operations.
Field | Description |
---|---|
timeWindow github.com/gardener/gardener/pkg/apis/core/v1beta1.MaintenanceTimeWindow | TimeWindow contains information about the time window for maintenance operations. |
Networking
(Appears on: VirtualCluster)
Networking defines networking parameters for the virtual garden cluster.
Field | Description |
---|---|
services string | Services is the CIDR of the service network. This field is immutable. |
ProjectQuotaConfiguration
(Appears on: GardenerControllerManagerConfig)
ProjectQuotaConfiguration defines quota configurations.
Field | Description |
---|---|
config k8s.io/apimachinery/pkg/runtime.RawExtension | Config is the quota specification used for the project set-up. Only v1.ResourceQuota resources are supported. |
projectSelector Kubernetes meta/v1.LabelSelector | (Optional) ProjectSelector is an optional setting to select the projects considered for quotas. Defaults to empty LabelSelector, which matches all projects. |
Provider
(Appears on: RuntimeCluster)
Provider defines the provider-specific information for this cluster.
Field | Description |
---|---|
zones []string | (Optional) Zones is the list of availability zones the cluster is deployed to. |
ResourceAdmissionConfiguration
(Appears on: GardenerAdmissionControllerConfig)
ResourceAdmissionConfiguration contains settings about arbitrary kinds and the size each resource should have at most.
Field | Description |
---|---|
limits []ResourceLimit | Limits contains configuration for resources which are subjected to size limitations. |
unrestrictedSubjects []Kubernetes rbac/v1.Subject | (Optional) UnrestrictedSubjects contains references to users, groups, or service accounts which aren’t subjected to any resource size limit. |
operationMode ResourceAdmissionWebhookMode | (Optional) OperationMode specifies the mode the webhooks operates in. Allowed values are “block” and “log”. Defaults to “block”. |
ResourceAdmissionWebhookMode
(string
alias)
(Appears on: ResourceAdmissionConfiguration)
ResourceAdmissionWebhookMode is an alias type for the resource admission webhook mode.
ResourceLimit
(Appears on: ResourceAdmissionConfiguration)
ResourceLimit contains settings about a kind and the size each resource should have at most.
Field | Description |
---|---|
apiGroups []string | (Optional) APIGroups is the name of the APIGroup that contains the limited resource. WildcardAll represents all groups. |
apiVersions []string | (Optional) APIVersions is the version of the resource. WildcardAll represents all versions. |
resources []string | Resources is the name of the resource this rule applies to. WildcardAll represents all resources. |
size k8s.io/apimachinery/pkg/api/resource.Quantity | Size specifies the imposed limit. |
RuntimeCluster
(Appears on: GardenSpec)
RuntimeCluster contains configuration for the runtime cluster.
Field | Description |
---|---|
ingress github.com/gardener/gardener/pkg/apis/core/v1beta1.Ingress | Ingress configures Ingress specific settings for the Garden cluster. This field is immutable. |
networking RuntimeNetworking | Networking defines the networking configuration of the runtime cluster. |
provider Provider | Provider defines the provider-specific information for this cluster. |
settings Settings | (Optional) Settings contains certain settings for this cluster. |
RuntimeNetworking
(Appears on: RuntimeCluster)
RuntimeNetworking defines the networking configuration of the runtime cluster.
Field | Description |
---|---|
nodes string | (Optional) Nodes is the CIDR of the node network. This field is immutable. |
pods string | Pods is the CIDR of the pod network. This field is immutable. |
services string | Services is the CIDR of the service network. This field is immutable. |
blockCIDRs []string | (Optional) BlockCIDRs is a list of network addresses that should be blocked. |
SNI
(Appears on: KubeAPIServerConfig)
SNI contains configuration options for the TLS SNI settings.
Field | Description |
---|---|
secretName string | SecretName is the name of a secret containing the TLS certificate and private key. |
domainPatterns []string | (Optional) DomainPatterns is a list of fully qualified domain names, possibly with prefixed wildcard segments. The domain patterns also allow IP addresses, but IPs should only be used if the apiserver has visibility to the IP address requested by a client. If no domain patterns are provided, the names of the certificate are extracted. Non-wildcard matches trump over wildcard matches, explicit domain patterns trump over extracted names. |
SettingLoadBalancerServices
(Appears on: Settings)
SettingLoadBalancerServices controls certain settings for services of type load balancer that are created in the runtime cluster.
Field | Description |
---|---|
annotations map[string]string | (Optional) Annotations is a map of annotations that will be injected/merged into every load balancer service object. |
SettingTopologyAwareRouting
(Appears on: Settings)
SettingTopologyAwareRouting controls certain settings for topology-aware traffic routing in the cluster. See https://github.com/gardener/gardener/blob/master/docs/operations/topology_aware_routing.md.
Field | Description |
---|---|
enabled bool | Enabled controls whether certain Services deployed in the cluster should be topology-aware. These Services are virtual-garden-etcd-main-client, virtual-garden-etcd-events-client and virtual-garden-kube-apiserver. Additionally, other components that are deployed to the runtime cluster via other means can read this field and according to its value enable/disable topology-aware routing for their Services. |
SettingVerticalPodAutoscaler
(Appears on: Settings)
SettingVerticalPodAutoscaler controls certain settings for the vertical pod autoscaler components deployed in the seed.
Field | Description |
---|---|
enabled bool | (Optional) Enabled controls whether the VPA components shall be deployed into this cluster. It is true by default because the operator (and Gardener) heavily rely on a VPA being deployed. You should only disable this if your runtime cluster already has another, manually/custom managed VPA deployment. If this is not the case, but you still disable it, then reconciliation will fail. |
Settings
(Appears on: RuntimeCluster)
Settings contains certain settings for this cluster.
Field | Description |
---|---|
loadBalancerServices SettingLoadBalancerServices | (Optional) LoadBalancerServices controls certain settings for services of type load balancer that are created in the runtime cluster. |
verticalPodAutoscaler SettingVerticalPodAutoscaler | (Optional) VerticalPodAutoscaler controls certain settings for the vertical pod autoscaler components deployed in the cluster. |
topologyAwareRouting SettingTopologyAwareRouting | (Optional) TopologyAwareRouting controls certain settings for topology-aware traffic routing in the cluster. See https://github.com/gardener/gardener/blob/master/docs/operations/topology_aware_routing.md. |
Storage
(Appears on: ETCDEvents, ETCDMain)
Storage contains storage configuration.
Field | Description |
---|---|
capacity k8s.io/apimachinery/pkg/api/resource.Quantity | (Optional) Capacity is the storage capacity for the volumes. |
className string | (Optional) ClassName is the name of a storage class. |
VirtualCluster
(Appears on: GardenSpec)
VirtualCluster contains configuration for the virtual cluster.
Field | Description |
---|---|
controlPlane ControlPlane | (Optional) ControlPlane holds information about the general settings for the control plane of the virtual cluster. |
dns DNS | DNS holds information about DNS settings. |
etcd ETCD | (Optional) ETCD contains configuration for the etcds of the virtual garden cluster. |
gardener Gardener | Gardener contains the configuration options for the Gardener control plane components. |
kubernetes Kubernetes | Kubernetes contains the version and configuration options for the Kubernetes components of the virtual garden cluster. |
maintenance Maintenance | Maintenance contains information about the time window for maintenance operations. |
networking Networking | Networking contains information about cluster networking such as CIDRs, etc. |
Generated with gen-crd-api-reference-docs
1.1.7 - Provider Local
Packages:
local.provider.extensions.gardener.cloud/v1alpha1
Package v1alpha1 contains the local provider API resources.
Resource Types:CloudProfileConfig
CloudProfileConfig contains provider-specific configuration that is embedded into Gardener’s CloudProfile
resource.
Field | Description |
---|---|
apiVersion string | local.provider.extensions.gardener.cloud/v1alpha1 |
kind string | CloudProfileConfig |
machineImages []MachineImages | MachineImages is the list of machine images that are understood by the controller. It maps logical names and versions to provider-specific identifiers. |
WorkerStatus
WorkerStatus contains information about created worker resources.
Field | Description |
---|---|
apiVersion string | local.provider.extensions.gardener.cloud/v1alpha1 |
kind string | WorkerStatus |
machineImages []MachineImage | (Optional) MachineImages is a list of machine images that have been used in this worker. Usually, the extension controller
gets the mapping from name/version to the provider-specific machine image data from the CloudProfile. However, if
a version that is still in use gets removed from this componentconfig it cannot reconcile anymore existing |
MachineImage
(Appears on: WorkerStatus)
MachineImage is a mapping from logical names and versions to provider-specific machine image data.
Field | Description |
---|---|
name string | Name is the logical name of the machine image. |
version string | Version is the logical version of the machine image. |
image string | Image is the image for the machine image. |
MachineImageVersion
(Appears on: MachineImages)
MachineImageVersion contains a version and a provider-specific identifier.
Field | Description |
---|---|
version string | Version is the version of the image. |
image string | Image is the image for the machine image. |
MachineImages
(Appears on: CloudProfileConfig)
MachineImages is a mapping from logical names and versions to provider-specific identifiers.
Field | Description |
---|---|
name string | Name is the logical name of the machine image. |
versions []MachineImageVersion | Versions contains versions and a provider-specific identifier. |
Generated with gen-crd-api-reference-docs
1.1.8 - Resources
Packages:
resources.gardener.cloud/v1alpha1
Package v1alpha1 contains the configuration of the Gardener Resource Manager.
Resource Types:ManagedResource
ManagedResource describes a list of managed resources.
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||
spec ManagedResourceSpec | Spec contains the specification of this managed resource.
| ||||||||||||||||
status ManagedResourceStatus | Status contains the status of this managed resource. |
ManagedResourceSpec
(Appears on: ManagedResource)
ManagedResourceSpec contains the specification of this managed resource.
Field | Description |
---|---|
class string | (Optional) Class holds the resource class used to control the responsibility for multiple resource manager instances |
secretRefs []Kubernetes core/v1.LocalObjectReference | SecretRefs is a list of secret references. |
injectLabels map[string]string | (Optional) InjectLabels injects the provided labels into every resource that is part of the referenced secrets. |
forceOverwriteLabels bool | (Optional) ForceOverwriteLabels specifies that all existing labels should be overwritten. Defaults to false. |
forceOverwriteAnnotations bool | (Optional) ForceOverwriteAnnotations specifies that all existing annotations should be overwritten. Defaults to false. |
keepObjects bool | (Optional) KeepObjects specifies whether the objects should be kept although the managed resource has already been deleted. Defaults to false. |
equivalences [][]k8s.io/apimachinery/pkg/apis/meta/v1.GroupKind | (Optional) Equivalences specifies possible group/kind equivalences for objects. |
deletePersistentVolumeClaims bool | (Optional) DeletePersistentVolumeClaims specifies if PersistentVolumeClaims created by StatefulSets, which are managed by this resource, should also be deleted when the corresponding StatefulSet is deleted (defaults to false). |
ManagedResourceStatus
(Appears on: ManagedResource)
ManagedResourceStatus is the status of a managed resource.
Field | Description |
---|---|
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | |
observedGeneration int64 | ObservedGeneration is the most recent generation observed for this resource. |
resources []ObjectReference | (Optional) Resources is a list of objects that have been created. |
secretsDataChecksum string | (Optional) SecretsDataChecksum is the checksum of referenced secrets data. |
ObjectReference
(Appears on: ManagedResourceStatus)
ObjectReference is a reference to another object.
Field | Description |
---|---|
ObjectReference Kubernetes core/v1.ObjectReference | (Members of |
labels map[string]string | Labels is a map of labels that were used during last update of the resource. |
annotations map[string]string | Annotations is a map of annotations that were used during last update of the resource. |
Generated with gen-crd-api-reference-docs
1.1.9 - Seedmanagement
Packages:
seedmanagement.gardener.cloud/v1alpha1
Package v1alpha1 is a version of the API.
Resource Types:ManagedSeed
ManagedSeed represents a Shoot that is registered as Seed.
Field | Description | ||||
---|---|---|---|---|---|
apiVersion string | seedmanagement.gardener.cloud/v1alpha1 | ||||
kind string | ManagedSeed | ||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec ManagedSeedSpec | (Optional) Specification of the ManagedSeed.
| ||||
status ManagedSeedStatus | (Optional) Most recently observed status of the ManagedSeed. |
ManagedSeedSet
ManagedSeedSet represents a set of identical ManagedSeeds.
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | seedmanagement.gardener.cloud/v1alpha1 | ||||||||||||
kind string | ManagedSeedSet | ||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||
spec ManagedSeedSetSpec | (Optional) Spec defines the desired identities of ManagedSeeds and Shoots in this set.
| ||||||||||||
status ManagedSeedSetStatus | (Optional) Status is the current status of ManagedSeeds and Shoots in this ManagedSeedSet. |
Bootstrap
(string
alias)
(Appears on: Gardenlet)
Bootstrap describes a mechanism for bootstrapping gardenlet connection to the Garden cluster.
Gardenlet
(Appears on: ManagedSeedSpec)
Gardenlet specifies gardenlet deployment parameters and the GardenletConfiguration used to configure gardenlet.
Field | Description |
---|---|
deployment GardenletDeployment | (Optional) Deployment specifies certain gardenlet deployment parameters, such as the number of replicas, the image, etc. |
config k8s.io/apimachinery/pkg/runtime.RawExtension | (Optional) Config is the GardenletConfiguration used to configure gardenlet. |
bootstrap Bootstrap | (Optional) Bootstrap is the mechanism that should be used for bootstrapping gardenlet connection to the Garden cluster. One of ServiceAccount, BootstrapToken, None. If set to ServiceAccount or BootstrapToken, a service account or a bootstrap token will be created in the garden cluster and used to compute the bootstrap kubeconfig. If set to None, the gardenClientConnection.kubeconfig field will be used to connect to the Garden cluster. Defaults to BootstrapToken. This field is immutable. |
mergeWithParent bool | (Optional) MergeWithParent specifies whether the GardenletConfiguration of the parent gardenlet should be merged with the specified GardenletConfiguration. Defaults to true. This field is immutable. |
GardenletDeployment
(Appears on: Gardenlet)
GardenletDeployment specifies certain gardenlet deployment parameters, such as the number of replicas, the image, etc.
Field | Description |
---|---|
replicaCount int32 | (Optional) ReplicaCount is the number of gardenlet replicas. Defaults to 2. |
revisionHistoryLimit int32 | (Optional) RevisionHistoryLimit is the number of old gardenlet ReplicaSets to retain to allow rollback. Defaults to 2. |
serviceAccountName string | (Optional) ServiceAccountName is the name of the ServiceAccount to use to run gardenlet pods. |
image Image | (Optional) Image is the gardenlet container image. |
resources Kubernetes core/v1.ResourceRequirements | (Optional) Resources are the compute resources required by the gardenlet container. |
podLabels map[string]string | (Optional) PodLabels are the labels on gardenlet pods. |
podAnnotations map[string]string | (Optional) PodAnnotations are the annotations on gardenlet pods. |
additionalVolumes []Kubernetes core/v1.Volume | (Optional) AdditionalVolumes is the list of additional volumes that should be mounted by gardenlet containers. |
additionalVolumeMounts []Kubernetes core/v1.VolumeMount | (Optional) AdditionalVolumeMounts is the list of additional pod volumes to mount into the gardenlet container’s filesystem. |
env []Kubernetes core/v1.EnvVar | (Optional) Env is the list of environment variables to set in the gardenlet container. |
vpa bool | (Optional) VPA specifies whether to enable VPA for gardenlet. Defaults to true. |
Image
(Appears on: GardenletDeployment)
Image specifies container image parameters.
Field | Description |
---|---|
repository string | (Optional) Repository is the image repository. |
tag string | (Optional) Tag is the image tag. |
pullPolicy Kubernetes core/v1.PullPolicy | (Optional) PullPolicy is the image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if latest tag is specified, or IfNotPresent otherwise. |
ManagedSeedSetSpec
(Appears on: ManagedSeedSet)
ManagedSeedSetSpec is the specification of a ManagedSeedSet.
Field | Description |
---|---|
replicas int32 | (Optional) Replicas is the desired number of replicas of the given Template. Defaults to 1. |
selector Kubernetes meta/v1.LabelSelector | Selector is a label query over ManagedSeeds and Shoots that should match the replica count. It must match the ManagedSeeds and Shoots template’s labels. This field is immutable. |
template ManagedSeedTemplate | Template describes the ManagedSeed that will be created if insufficient replicas are detected. Each ManagedSeed created / updated by the ManagedSeedSet will fulfill this template. |
shootTemplate github.com/gardener/gardener/pkg/apis/core/v1beta1.ShootTemplate | ShootTemplate describes the Shoot that will be created if insufficient replicas are detected for hosting the corresponding ManagedSeed. Each Shoot created / updated by the ManagedSeedSet will fulfill this template. |
updateStrategy UpdateStrategy | (Optional) UpdateStrategy specifies the UpdateStrategy that will be employed to update ManagedSeeds / Shoots in the ManagedSeedSet when a revision is made to Template / ShootTemplate. |
revisionHistoryLimit int32 | (Optional) RevisionHistoryLimit is the maximum number of revisions that will be maintained in the ManagedSeedSet’s revision history. Defaults to 10. This field is immutable. |
ManagedSeedSetStatus
(Appears on: ManagedSeedSet)
ManagedSeedSetStatus represents the current state of a ManagedSeedSet.
Field | Description |
---|---|
observedGeneration int64 | ObservedGeneration is the most recent generation observed for this ManagedSeedSet. It corresponds to the ManagedSeedSet’s generation, which is updated on mutation by the API Server. |
replicas int32 | Replicas is the number of replicas (ManagedSeeds and their corresponding Shoots) created by the ManagedSeedSet controller. |
readyReplicas int32 | ReadyReplicas is the number of ManagedSeeds created by the ManagedSeedSet controller that have a Ready Condition. |
nextReplicaNumber int32 | NextReplicaNumber is the ordinal number that will be assigned to the next replica of the ManagedSeedSet. |
currentReplicas int32 | CurrentReplicas is the number of ManagedSeeds created by the ManagedSeedSet controller from the ManagedSeedSet version indicated by CurrentRevision. |
updatedReplicas int32 | UpdatedReplicas is the number of ManagedSeeds created by the ManagedSeedSet controller from the ManagedSeedSet version indicated by UpdateRevision. |
currentRevision string | CurrentRevision, if not empty, indicates the version of the ManagedSeedSet used to generate ManagedSeeds with smaller ordinal numbers during updates. |
updateRevision string | UpdateRevision, if not empty, indicates the version of the ManagedSeedSet used to generate ManagedSeeds with larger ordinal numbers during updates |
collisionCount int32 | (Optional) CollisionCount is the count of hash collisions for the ManagedSeedSet. The ManagedSeedSet controller uses this field as a collision avoidance mechanism when it needs to create the name for the newest ControllerRevision. |
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | (Optional) Conditions represents the latest available observations of a ManagedSeedSet’s current state. |
pendingReplica PendingReplica | (Optional) PendingReplica, if not empty, indicates the replica that is currently pending creation, update, or deletion. This replica is in a state that requires the controller to wait for it to change before advancing to the next replica. |
ManagedSeedSpec
(Appears on: ManagedSeed, ManagedSeedTemplate)
ManagedSeedSpec is the specification of a ManagedSeed.
Field | Description |
---|---|
shoot Shoot | (Optional) Shoot references a Shoot that should be registered as Seed. This field is immutable. |
gardenlet Gardenlet | (Optional) Gardenlet specifies that the ManagedSeed controller should deploy a gardenlet into the cluster with the given deployment parameters and GardenletConfiguration. |
ManagedSeedStatus
(Appears on: ManagedSeed)
ManagedSeedStatus is the status of a ManagedSeed.
Field | Description |
---|---|
conditions []github.com/gardener/gardener/pkg/apis/core/v1beta1.Condition | (Optional) Conditions represents the latest available observations of a ManagedSeed’s current state. |
observedGeneration int64 | ObservedGeneration is the most recent generation observed for this ManagedSeed. It corresponds to the ManagedSeed’s generation, which is updated on mutation by the API Server. |
ManagedSeedTemplate
(Appears on: ManagedSeedSetSpec)
ManagedSeedTemplate is a template for creating a ManagedSeed object.
Field | Description | ||||
---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | (Optional) Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec ManagedSeedSpec | (Optional) Specification of the desired behavior of the ManagedSeed.
|
PendingReplica
(Appears on: ManagedSeedSetStatus)
PendingReplica contains information about a replica that is currently pending creation, update, or deletion.
Field | Description |
---|---|
name string | Name is the replica name. |
reason PendingReplicaReason | Reason is the reason for the replica to be pending. |
since Kubernetes meta/v1.Time | Since is the moment in time since the replica is pending with the specified reason. |
retries int32 | (Optional) Retries is the number of times the shoot operation (reconcile or delete) has been retried after having failed. Only applicable if Reason is ShootReconciling or ShootDeleting. |
PendingReplicaReason
(string
alias)
(Appears on: PendingReplica)
PendingReplicaReason is a string enumeration type that enumerates all possible reasons for a replica to be pending.
RollingUpdateStrategy
(Appears on: UpdateStrategy)
RollingUpdateStrategy is used to communicate parameters for RollingUpdateStrategyType.
Field | Description |
---|---|
partition int32 | (Optional) Partition indicates the ordinal at which the ManagedSeedSet should be partitioned. Defaults to 0. |
Shoot
(Appears on: ManagedSeedSpec)
Shoot identifies the Shoot that should be registered as Seed.
Field | Description |
---|---|
name string | Name is the name of the Shoot that will be registered as Seed. |
UpdateStrategy
(Appears on: ManagedSeedSetSpec)
UpdateStrategy specifies the strategy that the ManagedSeedSet controller will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy.
Field | Description |
---|---|
type UpdateStrategyType | (Optional) Type indicates the type of the UpdateStrategy. Defaults to RollingUpdate. |
rollingUpdate RollingUpdateStrategy | (Optional) RollingUpdate is used to communicate parameters when Type is RollingUpdateStrategyType. |
UpdateStrategyType
(string
alias)
(Appears on: UpdateStrategy)
UpdateStrategyType is a string enumeration type that enumerates all possible update strategies for the ManagedSeedSet controller.
Generated with gen-crd-api-reference-docs
1.1.10 - Settings
Packages:
settings.gardener.cloud/v1alpha1
Package v1alpha1 is a version of the API.
Resource Types:ClusterOpenIDConnectPreset
ClusterOpenIDConnectPreset is a OpenID Connect configuration that is applied to a Shoot objects cluster-wide.
Field | Description | ||||
---|---|---|---|---|---|
apiVersion string | settings.gardener.cloud/v1alpha1 | ||||
kind string | ClusterOpenIDConnectPreset | ||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec ClusterOpenIDConnectPresetSpec | Spec is the specification of this OpenIDConnect preset.
|
OpenIDConnectPreset
OpenIDConnectPreset is a OpenID Connect configuration that is applied to a Shoot in a namespace.
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
apiVersion string | settings.gardener.cloud/v1alpha1 | ||||||||
kind string | OpenIDConnectPreset | ||||||||
metadata Kubernetes meta/v1.ObjectMeta | Standard object metadata. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||
spec OpenIDConnectPresetSpec | Spec is the specification of this OpenIDConnect preset.
|
ClusterOpenIDConnectPresetSpec
(Appears on: ClusterOpenIDConnectPreset)
ClusterOpenIDConnectPresetSpec contains the OpenIDConnect specification and project selector matching Shoots in Projects.
Field | Description |
---|---|
OpenIDConnectPresetSpec OpenIDConnectPresetSpec | (Members of |
projectSelector Kubernetes meta/v1.LabelSelector | (Optional) Project decides whether to apply the configuration if the Shoot is in a specific Project matching the label selector. Use the selector only if the OIDC Preset is opt-in, because end users may skip the admission by setting the labels. Defaults to the empty LabelSelector, which matches everything. |
KubeAPIServerOpenIDConnect
(Appears on: OpenIDConnectPresetSpec)
KubeAPIServerOpenIDConnect contains configuration settings for the OIDC provider. Note: Descriptions were taken from the Kubernetes documentation.
Field | Description |
---|---|
caBundle string | (Optional) If set, the OpenID server’s certificate will be verified by one of the authorities in the oidc-ca-file, otherwise the host’s root CA set will be used. |
clientID string | The client ID for the OpenID Connect client. Required. |
groupsClaim string | (Optional) If provided, the name of a custom OpenID Connect claim for specifying user groups. The claim value is expected to be a string or array of strings. This field is experimental, please see the authentication documentation for further details. |
groupsPrefix string | (Optional) If provided, all groups will be prefixed with this value to prevent conflicts with other authentication strategies. |
issuerURL string | The URL of the OpenID issuer, only HTTPS scheme will be accepted. If set, it will be used to verify the OIDC JSON Web Token (JWT). Required. |
requiredClaims map[string]string | (Optional) key=value pairs that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. |
signingAlgs []string | (Optional) List of allowed JOSE asymmetric signing algorithms. JWTs with a ‘alg’ header value not in this list will be rejected. Values are defined by RFC 7518 https://tools.ietf.org/html/rfc7518#section-3.1 Defaults to [RS256] |
usernameClaim string | (Optional) The OpenID claim to use as the user name. Note that claims other than the default (‘sub’) is not guaranteed to be unique and immutable. This field is experimental, please see the authentication documentation for further details. Defaults to “sub”. |
usernamePrefix string | (Optional) If provided, all usernames will be prefixed with this value. If not provided, username claims other than ‘email’ are prefixed by the issuer URL to avoid clashes. To skip any prefixing, provide the value ‘-’. |
OpenIDConnectClientAuthentication
(Appears on: OpenIDConnectPresetSpec)
OpenIDConnectClientAuthentication contains configuration for OIDC clients.
Field | Description |
---|---|
secret string | (Optional) The client Secret for the OpenID Connect client. |
extraConfig map[string]string | (Optional) Extra configuration added to kubeconfig’s auth-provider. Must not be any of idp-issuer-url, client-id, client-secret, idp-certificate-authority, idp-certificate-authority-data, id-token or refresh-token |
OpenIDConnectPresetSpec
(Appears on: OpenIDConnectPreset, ClusterOpenIDConnectPresetSpec)
OpenIDConnectPresetSpec contains the Shoot selector for which a specific OpenID Connect configuration is applied.
Field | Description |
---|---|
server KubeAPIServerOpenIDConnect | Server contains the kube-apiserver’s OpenID Connect configuration. This configuration is not overwriting any existing OpenID Connect configuration already set on the Shoot object. |
client OpenIDConnectClientAuthentication | (Optional) Client contains the configuration used for client OIDC authentication of Shoot clusters. This configuration is not overwriting any existing OpenID Connect client authentication already set on the Shoot object. |
shootSelector Kubernetes meta/v1.LabelSelector | (Optional) ShootSelector decides whether to apply the configuration if the Shoot has matching labels. Use the selector only if the OIDC Preset is opt-in, because end users may skip the admission by setting the labels. Default to the empty LabelSelector, which matches everything. |
weight int32 | Weight associated with matching the corresponding preset, in the range 1-100. Required. |
Generated with gen-crd-api-reference-docs
1.2 - Concepts
1.2.1 - Admission Controller
Gardener Admission Controller
While the Gardener API server works with admission plugins to validate and mutate resources belonging to Gardener related API groups, e.g. core.gardener.cloud
, the same is needed for resources belonging to non-Gardener API groups as well, e.g. secrets in the core
API group.
Therefore, the Gardener Admission Controller runs a http(s) server with the following handlers which serve as validating/mutating endpoints for admission webhooks.
It is also used to serve http(s) handlers for authorization webhooks.
Admission Webhook Handlers
This section describes the admission webhook handlers that are currently served.
Admission Plugin Secret Validator
In Shoot
, AdmissionPlugin
can have reference to other files. This validation handler validates the referred admission plugin secret and ensures that the secret always contains the required data kubeconfig
.
Kubeconfig Secret Validator
Malicious Kubeconfigs applied by end users may cause a leakage of sensitive data.
This handler checks if the incoming request contains a Kubernetes secret with a .data.kubeconfig
field and denies the request if the Kubeconfig structure violates Gardener’s security standards.
Namespace Validator
Namespaces are the backing entities of Gardener projects in which shoot cluster objects reside.
This validation handler protects active namespaces against premature deletion requests.
Therefore, it denies deletion requests if a namespace still contains shoot clusters or if it belongs to a non-deleting Gardener project (without .metadata.deletionTimestamp
).
Resource Size Validator
Since users directly apply Kubernetes native objects to the Garden cluster, it also involves the risk of being vulnerable to DoS attacks because these resources are continuously watched and read by controllers. One example is the creation of shoot resources with large annotation values (up to 256 kB per value), which can cause severe out-of-memory issues for the gardenlet component. Vertical autoscaling can help to mitigate such situations, but we cannot expect to scale infinitely, and thus need means to block the attack itself.
The Resource Size Validator checks arbitrary incoming admission requests against a configured maximum size for the resource’s group-version-kind combination. It denies the request if the object exceeds the quota.
Example for Gardener Admission Controller configuration:
server:
resourceAdmissionConfiguration:
limits:
- apiGroups: ["core.gardener.cloud"]
apiVersions: ["*"]
resources: ["shoots"]
size: 100k
- apiGroups: [""]
apiVersions: ["v1"]
resources: ["secrets"]
size: 100k
unrestrictedSubjects:
- kind: Group
name: gardener.cloud:system:seeds
apiGroup: rbac.authorization.k8s.io
# - kind: User
# name: admin
# apiGroup: rbac.authorization.k8s.io
# - kind: ServiceAccount
# name: "*"
# namespace: garden
# apiGroup: ""
operationMode: block #log
With the configuration above, the Resource Size Validator denies requests for shoots with Gardener’s core API group which exceed a size of 100 kB. The same is done for Kubernetes secrets.
As this feature is meant to protect the system from malicious requests sent by users, it is recommended to exclude trusted groups, users or service accounts from the size restriction via resourceAdmissionConfiguration.unrestrictedSubjects
.
For example, the backing user for the gardenlet should always be capable of changing the shoot resource instead of being blocked due to size restrictions.
This is because the gardenlet itself occasionally changes the shoot specification, labels or annotations, and might violate the quota if the existing resource is already close to the quota boundary.
Also, operators are supposed to be trusted users and subjecting them to a size limitation can inhibit important operational tasks.
Wildcard ("*") in subject name
is supported.
Size limitations depend on the individual Gardener setup and choosing the wrong values can affect the availability of your Gardener service.
resourceAdmissionConfiguration.operationMode
allows to control if a violating request is actually denied (default) or only logged.
It’s recommended to start with log
, check the logs for exceeding requests, adjust the limits if necessary and finally switch to block
.
SeedRestriction
Please refer to Scoped API Access for Gardenlets for more information.
Authorization Webhook Handlers
This section describes the authorization webhook handlers that are currently served.
SeedAuthorization
Please refer to Scoped API Access for Gardenlets for more information.
1.2.2 - API Server
Gardener API Server
The Gardener API server is a Kubernetes-native extension based on its aggregation layer.
It is registered via an APIService
object and designed to run inside a Kubernetes cluster whose API it wants to extend.
After registration, it exposes the following resources:
CloudProfile
s
CloudProfile
s are resources that describe a specific environment of an underlying infrastructure provider, e.g. AWS, Azure, etc.
Each shoot has to reference a CloudProfile
to declare the environment it should be created in.
In a CloudProfile
, the gardener operator specifies certain constraints like available machine types, regions, which Kubernetes versions they want to offer, etc.
End-users can read CloudProfile
s to see these values, but only operators can change the content or create/delete them.
When a shoot is created or updated, then an admission plugin checks that only allowed values are used via the referenced CloudProfile
.
Additionally, a CloudProfile
may contain a providerConfig
, which is a special configuration dedicated for the infrastructure provider.
Gardener does not evaluate or understand this config, but extension controllers might need it for declaration of provider-specific constraints, or global settings.
Please see this example manifest and consult the documentation of your provider extension controller to get information about its providerConfig
.
InternalSecret
s
End-users can read and/or write Secret
s in their project namespaces in the garden cluster. This prevents Gardener components from storing such “Gardener-internal” secrets in the respective project namespace.
InternalSecret
s are resources that contain shoot or project-related secrets that are “Gardener-internal”, i.e., secrets used and managed by the system that end-users don’t have access to.
InternalSecret
s are defined like plain Kubernetes Secret
s, behave exactly like them, and can be used in the same manners. The only difference is, that the InternalSecret
resource is a dedicated API resource (exposed by gardener-apiserver).
This allows separating access to “normal” secrets and internal secrets by the usual RBAC means.
Gardener uses an InternalSecret
per Shoot for syncing the client CA to the project namespace in the garden cluster (named <shoot-name>.ca-client
). The shoots/adminkubeconfig
subresource signs short-lived client certificates by retrieving the CA from the InternalSecret
.
Operators should configure gardener-apiserver
to encrypt the internalsecrets.core.gardener.cloud
resource in etcd.
Please see this example manifest.
Seed
s
Seed
s are resources that represent seed clusters.
Gardener does not care about how a seed cluster got created - the only requirement is that it is of at least Kubernetes v1.24 and passes the Kubernetes conformance tests.
The Gardener operator has to either deploy the gardenlet into the cluster they want to use as seed (recommended, then the gardenlet will create the Seed
object itself after bootstrapping) or provide the kubeconfig to the cluster inside a secret (that is referenced by the Seed
resource) and create the Seed
resource themselves.
Please see this, this, and optionally this example manifests.
Shoot Quota
s
To allow end-users not having their dedicated infrastructure account to try out Gardener, the operator can register an account owned by them that they allow to be used for trial clusters. Trial clusters can be put under quota so that they don’t consume too many resources (resulting in costs) and that one user cannot consume all resources on their own. These clusters are automatically terminated after a specified time, but end-users may extend the lifetime manually if needed.
Please see this example manifest.
Project
s
The first thing before creating a shoot cluster is to create a Project
.
A project is used to group multiple shoot clusters together.
End-users can invite colleagues to the project to enable collaboration, and they can either make them admin
or viewer
.
After an end-user has created a project, they will get a dedicated namespace in the garden cluster for all their shoots.
Please see this example manifest.
SecretBinding
s
Now that the end-user has a namespace the next step is registering their infrastructure provider account.
Please see this example manifest and consult the documentation of the extension controller for the respective infrastructure provider to get information about which keys are required in this secret.
After the secret has been created, the end-user has to create a special SecretBinding
resource that binds this secret.
Later, when creating shoot clusters, they will reference such binding.
Please see this example manifest.
Shoot
s
Shoot cluster contain various settings that influence how end-user Kubernetes clusters will look like in the end. As Gardener heavily relies on extension controllers for operating system configuration, networking, and infrastructure specifics, the end-user has the possibility (and responsibility) to provide these provider-specific configurations as well. Such configurations are not evaluated by Gardener (because it doesn’t know/understand them), but they are only transported to the respective extension controller.
⚠️ This means that any configuration issues/mistake on the end-user side that relates to a provider-specific flag or setting cannot be caught during the update request itself but only later during the reconciliation (unless a validator webhook has been registered in the garden cluster by an operator).
Please see this example manifest and consult the documentation of the provider extension controller to get information about its spec.provider.controlPlaneConfig
, .spec.provider.infrastructureConfig
, and .spec.provider.workers[].providerConfig
.
(Cluster)OpenIDConnectPreset
s
Please see this separate documentation file.
Overview Data Model
1.2.3 - APIServer Admission Plugins
Admission Plugins
Similar to the kube-apiserver, the gardener-apiserver comes with a few in-tree managed admission plugins. If you want to get an overview of the what and why of admission plugins then this document might be a good start.
This document lists all existing admission plugins with a short explanation of what it is responsible for.
ClusterOpenIDConnectPreset
, OpenIDConnectPreset
(both enabled by default)
These admission controllers react on CREATE
operations for Shoot
s.
If the Shoot
does not specify any OIDC configuration (.spec.kubernetes.kubeAPIServer.oidcConfig=nil
), then it tries to find a matching ClusterOpenIDConnectPreset
or OpenIDConnectPreset
, respectively.
If there are multiple matches, then the one with the highest weight “wins”.
In this case, the admission controller will default the OIDC configuration in the Shoot
.
ControllerRegistrationResources
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for ControllerRegistration
s.
It validates that there exists only one ControllerRegistration
in the system that is primarily responsible for a given kind/type resource combination.
This prevents misconfiguration by the Gardener administrator/operator.
CustomVerbAuthorizer
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for Project
s.
It validates whether the user is bound to a RBAC role with the modify-spec-tolerations-whitelist
verb in case the user tries to change the .spec.tolerations.whitelist
field of the respective Project
resource.
Usually, regular project members are not bound to this custom verb, allowing the Gardener administrator to manage certain toleration whitelists on Project
basis.
DeletionConfirmation
(enabled by default)
This admission controller reacts on DELETE
operations for Project
s and Shoot
s and ShootState
s.
It validates that the respective resource is annotated with a deletion confirmation annotation, namely confirmation.gardener.cloud/deletion=true
.
Only if this annotation is present it allows the DELETE
operation to pass.
This prevents users from accidental/undesired deletions.
ExposureClass
(enabled by default)
This admission controller reacts on Create
operations for Shoot
s.
It mutates Shoot
resources which have an ExposureClass
referenced by merging both their shootSelectors
and/or tolerations
into the Shoot
resource.
ExtensionValidator
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for BackupEntry
s, BackupBucket
s, Seed
s, and Shoot
s.
For all the various extension types in the specifications of these objects, it validates whether there exists a ControllerRegistration
in the system that is primarily responsible for the stated extension type(s).
This prevents misconfigurations that would otherwise allow users to create such resources with extension types that don’t exist in the cluster, effectively leading to failing reconciliation loops.
ExtensionLabels
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for BackupBucket
s, BackupEntry
s, CloudProfile
s, Seed
s, SecretBinding
s and Shoot
s. For all the various extension types in the specifications of these objects, it adds a corresponding label in the resource. This would allow extension admission webhooks to filter out the resources they are responsible for and ignore all others. This label is of the form <extension-type>.extensions.gardener.cloud/<extension-name> : "true"
. For example, an extension label for provider extension type aws
, looks like provider.extensions.gardener.cloud/aws : "true"
.
ProjectValidator
(enabled by default)
This admission controller reacts on CREATE
operations for Project
s.
It prevents creating Project
s with a non-empty .spec.namespace
if the value in .spec.namespace
does not start with garden-
.
⚠️ This admission plugin will be removed in a future release and its business logic will be incorporated into the static validation of the gardener-apiserver
.
ResourceQuota
(enabled by default)
This admission controller enables object count ResourceQuotas for Gardener resources, e.g. Shoots
, SecretBindings
, Projects
, etc.
⚠️ In addition to this admission plugin, the ResourceQuota controller must be enabled for the Kube-Controller-Manager of your Garden cluster.
ResourceReferenceManager
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for CloudProfile
s, Project
s, SecretBinding
s, Seed
s, and Shoot
s.
Generally, it checks whether referred resources stated in the specifications of these objects exist in the system (e.g., if a referenced Secret
exists).
However, it also has some special behaviours for certain resources:
CloudProfile
s: It rejects removing Kubernetes or machine image versions if there is at least oneShoot
that refers to them.Project
s: It sets the.spec.createdBy
field for newly createdProject
resources, and defaults the.spec.owner
field in case it is empty (to the same value of.spec.createdBy
).Shoot
s: It sets thegardener.cloud/created-by=<username>
annotation for newly createdShoot
resources.
SeedValidator
(enabled by default)
This admission controller reacts on DELETE
operations for Seed
s.
Rejects the deletion if Shoot
(s) reference the seed cluster.
ShootDNS
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for Shoot
s.
It tries to assign a default domain to the Shoot
.
It also validates the DNS configuration (.spec.dns
) for shoots.
ShootNodeLocalDNSEnabledByDefault
(disabled by default)
This admission controller reacts on CREATE
operations for Shoot
s.
If enabled, it will enable node local dns within the shoot cluster (for more information, see NodeLocalDNS Configuration) by setting spec.systemComponents.nodeLocalDNS.enabled=true
for newly created Shoots.
Already existing Shoots and new Shoots that explicitly disable node local dns (spec.systemComponents.nodeLocalDNS.enabled=false
)
will not be affected by this admission plugin.
ShootQuotaValidator
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for Shoot
s.
It validates the resource consumption declared in the specification against applicable Quota
resources.
Only if the applicable Quota
resources admit the configured resources in the Shoot
then it allows the request.
Applicable Quota
s are referred in the SecretBinding
that is used by the Shoot
.
ShootVPAEnabledByDefault
(disabled by default)
This admission controller reacts on CREATE
operations for Shoot
s.
If enabled, it will enable the managed VerticalPodAutoscaler
components (for more information, see Vertical Pod Auto-Scaling)
by setting spec.kubernetes.verticalPodAutoscaler.enabled=true
for newly created Shoots.
Already existing Shoots and new Shoots that explicitly disable VPA (spec.kubernetes.verticalPodAutoscaler.enabled=false
)
will not be affected by this admission plugin.
ShootTolerationRestriction
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for Shoot
s.
It validates the .spec.tolerations
used in Shoot
s against the whitelist of its Project
, or against the whitelist configured in the admission controller’s configuration, respectively.
Additionally, it defaults the .spec.tolerations
in Shoot
s with those configured in its Project
, and those configured in the admission controller’s configuration, respectively.
ShootValidator
(enabled by default)
This admission controller reacts on CREATE
, UPDATE
and DELETE
operations for Shoot
s.
It validates certain configurations in the specification against the referred CloudProfile
(e.g., machine images, machine types, used Kubernetes version, …).
Generally, it performs validations that cannot be handled by the static API validation due to their dynamic nature (e.g., when something needs to be checked against referred resources).
Additionally, it takes over certain defaulting tasks (e.g., default machine image for worker pools, default Kubernetes version).
ShootManagedSeed
(enabled by default)
This admission controller reacts on UPDATE
and DELETE
operations for Shoot
s.
It validates certain configuration values in the specification that are specific to ManagedSeed
s (e.g. the nginx-addon of the Shoot has to be disabled, the Shoot VPA has to be enabled).
It rejects the deletion if the Shoot
is referred to by a ManagedSeed
.
ManagedSeedValidator
(enabled by default)
This admission controller reacts on CREATE
and UPDATE
operations for ManagedSeeds
s.
It validates certain configuration values in the specification against the referred Shoot
, for example Seed provider, network ranges, DNS domain, etc.
Similar to ShootValidator
, it performs validations that cannot be handled by the static API validation due to their dynamic nature.
Additionally, it performs certain defaulting tasks, making sure that configuration values that are not specified are defaulted to the values of the referred Shoot
, for example Seed provider, network ranges, DNS domain, etc.
ManagedSeedShoot
(enabled by default)
This admission controller reacts on DELETE
operations for ManagedSeed
s.
It rejects the deletion if there are Shoot
s that are scheduled onto the Seed
that is registered by the ManagedSeed
.
ShootDNSRewriting
(disabled by default)
This admission controller reacts on CREATE
operations for Shoot
s.
If enabled, it adds a set of common suffixes configured in its admission plugin configuration to the Shoot
(spec.systemComponents.coreDNS.rewriting.commonSuffixes
) (for more information, see DNS Search Path Optimization).
Already existing Shoot
s will not be affected by this admission plugin.
1.2.4 - Architecture
Official Definition - What is Kubernetes?
“Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications.”
Introduction - Basic Principle
The foundation of the Gardener (providing Kubernetes Clusters as a Service) is Kubernetes itself, because Kubernetes is the go-to solution to manage software in the Cloud, even when it’s Kubernetes itself (see also OpenStack which is provisioned more and more on top of Kubernetes as well).
While self-hosting, meaning to run Kubernetes components inside Kubernetes, is a popular topic in the community, we apply a special pattern catering to the needs of our cloud platform to provision hundreds or even thousands of clusters. We take a so-called “seed” cluster and seed the control plane (such as the API server, scheduler, controllers, etcd persistence and others) of an end-user cluster, which we call “shoot” cluster, as pods into the “seed” cluster. That means that one “seed” cluster, of which we will have one per IaaS and region, hosts the control planes of multiple “shoot” clusters. That allows us to avoid dedicated hardware/virtual machines for the “shoot” cluster control planes. We simply put the control plane into pods/containers and since the “seed” cluster watches them, they can be deployed with a replica count of 1 and only need to be scaled out when the control plane gets under pressure, but no longer for HA reasons. At the same time, the deployments get simpler (standard Kubernetes deployment) and easier to update (standard Kubernetes rolling update). The actual “shoot” cluster consists only of the worker nodes (no control plane) and therefore the users may get full administrative access to their clusters.
Setting The Scene - Components and Procedure
We provide a central operator UI, which we call the “Gardener Dashboard”. It talks to a dedicated cluster, which we call the “Garden” cluster, and uses custom resources managed by an aggregated API server (one of the general extension concepts of Kubernetes) to represent “shoot” clusters. In this “Garden” cluster runs the “Gardener”, which is basically a Kubernetes controller that watches the custom resources and acts upon them, i.e. creates, updates/modifies, or deletes “shoot” clusters. The creation follows basically these steps:
- Create a namespace in the “seed” cluster for the “shoot” cluster, which will host the “shoot” cluster control plane.
- Generate secrets and credentials, which the worker nodes will need to talk to the control plane.
- Create the infrastructure (using Terraform), which basically consists out of the network setup.
- Deploy the “shoot” cluster control plane into the “shoot” namespace in the “seed” cluster, containing the “machine-controller-manager” pod.
- Create machine CRDs in the “seed” cluster, describing the configuration and the number of worker machines for the “shoot” (the machine-controller-manager watches the CRDs and creates virtual machines out of it).
- Wait for the “shoot” cluster API server to become responsive (pods will be scheduled, persistent volumes and load balancers are created by Kubernetes via the respective cloud provider).
- Finally, we deploy
kube-system
daemons likekube-proxy
and further add-ons like thedashboard
into the “shoot” cluster and the cluster becomes active.
Overview Architecture Diagram
Detailed Architecture Diagram
Note: The kubelet
, as well as the pods inside the “shoot” cluster, talks through the front-door (load balancer IP; public Internet) to its “shoot” cluster API server running in the “seed” cluster. The reverse communication from the API server to the pod, service, and node networks happens through a VPN connection that we deploy into the “seed” and “shoot” clusters.
1.2.5 - Backup and Restore
Backup and Restore
Kubernetes uses etcd as the key-value store for its resource definitions. Gardener supports the backup and restore of etcd. It is the responsibility of the shoot owners to backup the workload data.
Gardener uses an etcd-backup-restore component to backup the etcd backing the Shoot cluster regularly and restore it in case of disaster. It is deployed as sidecar via etcd-druid. This doc mainly focuses on the backup and restore configuration used by Gardener when deploying these components. For more details on the design and internal implementation details, please refer to GEP-06 and the documentation on individual repositories.
Bucket Provisioning
Refer to the backup bucket extension document to find out details about configuring the backup bucket.
Backup Policy
etcd-backup-restore supports full snapshot and delta snapshots over full snapshot. In Gardener, this configuration is currently hard-coded to the following parameters:
- Full Snapshot schedule:
- Daily,
24hr
interval. - For each Shoot, the schedule time in a day is randomized based on the configured Shoot maintenance window.
- Daily,
- Delta Snapshot schedule:
- At
5min
interval. - If aggregated events size since last snapshot goes beyond
100Mib
.
- At
- Backup History / Garbage backup deletion policy:
- Gardener configures backup restore to have
Exponential
garbage collection policy. - As per policy, the following backups are retained:
- All full backups and delta backups for the previous hour.
- Latest full snapshot of each previous hour for the day.
- Latest full snapshot of each previous day for 7 days.
- Latest full snapshot of the previous 4 weeks.
- Garbage Collection is configured at
12hr
interval.
- Gardener configures backup restore to have
- Listing:
- Gardener doesn’t have any API to list out the backups.
- To find the backups list, an admin can checkout the
BackupEntry
resource associated with the Shoot which holds the bucket and prefix details on the object store.
Restoration
The restoration process of etcd is automated through the etcd-backup-restore component from the latest snapshot. Gardener doesn’t support Point-In-Time-Recovery (PITR) of etcd. In case of an etcd disaster, the etcd is recovered from the latest backup automatically. For further details, please refer the Restoration topic. Post restoration of etcd, the Shoot reconciliation loop brings the cluster back to its previous state.
Again, the Shoot owner is responsible for maintaining the backup/restore of his workload. Gardener only takes care of the cluster’s etcd.
1.2.6 - Cluster API
Relation Between Gardener API and Cluster API (SIG Cluster Lifecycle)
In essence, the Cluster API harmonizes how to get to clusters, while Gardener goes one step further and also harmonizes the clusters themselves. The Cluster API delegates the specifics to so-called providers for infrastructures or control planes via specific CR(D)s, while Gardener only has one cluster CR(D). Different Cluster API providers, e.g. for AWS, Azure, GCP, etc., give you vastly different Kubernetes clusters. In contrast, Gardener gives you the exact same clusters with the exact same K8s version, operating system, control plane configuration like for API server or kubelet, add-ons like overlay network, HPA/VPA, DNS and certificate controllers, ingress and network policy controllers, control plane monitoring and logging stacks, down to the behavior of update procedures, auto-scaling, self-healing, etc., on all supported infrastructures. These homogeneous clusters are an essential goal for Gardener, as its main purpose is to simplify operations for teams that need to develop and ship software on Kubernetes clusters on a plethora of infrastructures (a.k.a. multi-cloud).
Incidentally, Gardener influenced the Machine API in the Cluster API with its Machine Controller Manager and was the first to adopt it. You can find more information on that in the joint SIG Cluster Lifecycle KubeCon talk where @hardikdr from our Gardener team in India spoke.
That means that we follow the Cluster API with great interest and are active members. It was completely overhauled from v1alpha1
to v1alpha2
. But because v1alpha2
made too many assumptions about the bring-up of masters and was enforcing master machine operations (for more information, see The Cluster API Book: “As of v1alpha2
, Machine-Based is the only control plane type that Cluster API supports”), services that managed their control planes differently like GKE or Gardener couldn’t adopt it (e.g. Google only supports v1alpha1
). In 2020 v1alpha3
was introduced and made it possible (again) to integrate managed services like GKE or Gardener. The mapping from the Gardener API to the Cluster API is mostly syntactic.
To wrap it up, while the Cluster API knows about clusters, it doesn’t know about their make-up. With Gardener, we wanted to go beyond that and harmonize the make-up of the clusters themselves and make them homogeneous across all supported infrastructures. Gardener can therefore deliver homogeneous clusters with exactly the same configuration and behavior on all infrastructures (see also Gardener’s coverage in the official conformance test grid).
With Cluster API v1alpha3
and the support for declarative control plane management, it has became possible (again) to enable Kubernetes managed services like GKE or Gardener. We would be more than happy if the community would be interested to contribute a Gardener control plane provider.
1.2.7 - Controller Manager
Gardener Controller Manager
The gardener-controller-manager
(often refered to as “GCM”) is a component that runs next to the Gardener API server, similar to the Kubernetes Controller Manager.
It runs several controllers that do not require talking to any seed or shoot cluster.
Also, as of today, it exposes an HTTP server that is serving several health check endpoints and metrics.
This document explains the various functionalities of the gardener-controller-manager
and their purpose.
Controllers
Bastion
Controller
Bastion
resources have a limited lifetime which can be extended up to a certain amount by performing a heartbeat on them.
The Bastion
controller is responsible for deleting expired or rotten Bastion
s.
- “expired” means a
Bastion
has exceeded itsstatus.expirationTimestamp
. - “rotten” means a
Bastion
is older than the configuredmaxLifetime
.
The maxLifetime
defaults to 24 hours and is an option in the BastionControllerConfiguration
which is part of gardener-controller-manager
s ControllerManagerControllerConfiguration
, see the example config file for details.
The controller also deletes Bastion
s in case the referenced Shoot
:
- no longer exists
- is marked for deletion (i.e., have a non-
nil
.metadata.deletionTimestamp
) - was migrated to another seed (i.e.,
Shoot.spec.seedName
is different thanBastion.spec.seedName
).
The deletion of Bastion
s triggers the gardenlet
to perform the necessary cleanups in the Seed cluster, so some time can pass between deletion and the Bastion
actually disappearing.
Clients like gardenctl
are advised to not re-use Bastion
s whose deletion timestamp has been set already.
Refer to GEP-15 for more information on the lifecycle of
Bastion
resources.
CertificateSigningRequest
Controller
After the gardenlet gets deployed on the Seed cluster, it needs to establish itself as a trusted party to communicate with the Gardener API server. It runs through a bootstrap flow similar to the kubelet bootstrap process.
On startup, the gardenlet uses a kubeconfig
with a bootstrap token which authenticates it as being part of the system:bootstrappers
group. This kubeconfig is used to create a CertificateSigningRequest
(CSR) against the Gardener API server.
The controller in gardener-controller-manager
checks whether the CertificateSigningRequest
has the expected organisation, common name and usages which the gardenlet would request.
It only auto-approves the CSR if the client making the request is allowed to “create” the
certificatesigningrequests/seedclient
subresource. Clients with the system:bootstrappers
group are bound to the gardener.cloud:system:seed-bootstrapper
ClusterRole
, hence, they have such privileges. As the bootstrap kubeconfig for the gardenlet contains a bootstrap token which is authenticated as being part of the systems:bootstrappers
group, its created CSR gets auto-approved.
CloudProfile
Controller
CloudProfile
s are essential when it comes to reconciling Shoot
s since they contain constraints (like valid machine types, Kubernetes versions, or machine images) and sometimes also some global configuration for the respective environment (typically via provider-specific configuration in .spec.providerConfig
).
Consequently, to ensure that CloudProfile
s in-use are always present in the system until the last referring Shoot
gets deleted, the controller adds a finalizer which is only released when there is no Shoot
referencing the CloudProfile
anymore.
ControllerDeployment
Controller
Extensions are registered in the garden cluster via ControllerRegistration
and deployment of respective extensions are specified via ControllerDeployment
. For more info refer to Registering Extension Controllers.
This controller ensures that ControllerDeployment
in-use always exists until the last ControllerRegistration
referencing them gets deleted. The controller adds a finalizer which is only released when there is no ControllerRegistration
referencing the ControllerDeployment
anymore.
ControllerRegistration
Controller
The ControllerRegistration
controller makes sure that the required Gardener Extensions specified by the ControllerRegistration
resources are present in the seed clusters.
It also takes care of the creation and deletion of ControllerInstallation
objects for a given seed cluster.
The controller has three reconciliation loops.
“Main” Reconciler
This reconciliation loop watches the Seed
objects and determines which ControllerRegistration
s are required for them and reconciles the corresponding ControllerInstallation
resources to reach the determined state.
To begin with, it computes the kind/type combinations of extensions required for the seed.
For this, the controller examines a live list of ControllerRegistration
s, ControllerInstallation
s, BackupBucket
s, BackupEntry
s, Shoot
s, and Secret
s from the garden cluster.
For example, it examines the shoots running on the seed and deducts the kind/type, like Infrastructure/gcp
.
The seed (seed.spec.provider.type
) and DNS (seed.spec.dns.provider.type
) provider types are considered when calculating the list of required ControllerRegistration
s, as well.
It also decides whether they should always be deployed based on the .spec.deployment.policy
.
For the configuration options, please see this section.
Based on these required combinations, each of them are mapped to ControllerRegistration
objects and then to their corresponding ControllerInstallation
objects (if existing).
The controller then creates or updates the required ControllerInstallation
objects for the given seed.
It also deletes every existing ControllerInstallation
whose referenced ControllerRegistration
is not part of the required list.
For example, if the shoots in the seed are no longer using the DNS provider aws-route53
, then the controller proceeds to delete the respective ControllerInstallation
object.
“ControllerRegistration Finalizer” Reconciler
This reconciliation loop watches the ControllerRegistration
resource and adds finalizers to it when they are created.
In case a deletion request comes in for the resource, i.e., if a .metadata.deletionTimestamp
is set, it actively scans for a ControllerInstallation
resource using this ControllerRegistration
, and decides whether the deletion can be allowed.
In case no related ControllerInstallation
is present, it removes the finalizer and marks it for deletion.
“Seed Finalizer” Reconciler
This loop also watches the Seed
object and adds finalizers to it at creation.
If a .metadata.deletionTimestamp
is set for the seed, then the controller checks for existing ControllerInstallation
objects which reference this seed.
If no such objects exist, then it removes the finalizer and allows the deletion.
Event
Controller
With the Gardener Event Controller, you can prolong the lifespan of events related to Shoot clusters. This is an optional controller which will become active once you provide the below mentioned configuration.
All events in K8s are deleted after a configurable time-to-live (controlled via a kube-apiserver argument called --event-ttl
(defaulting to 1 hour)).
The need to prolong the time-to-live for Shoot cluster events frequently arises when debugging customer issues on live systems.
This controller leaves events involving Shoots untouched, while deleting all other events after a configured time.
In order to activate it, provide the following configuration:
concurrentSyncs
: The amount of goroutines scheduled for reconciling events.ttlNonShootEvents
: When an event reaches this time-to-live it gets deleted unless it is a Shoot-related event (defaults to1h
, equivalent to theevent-ttl
default).
⚠️ In addition, you should also configure the
--event-ttl
for the kube-apiserver to define an upper-limit of how long Shoot-related events should be stored. The--event-ttl
should be larger than thettlNonShootEvents
or this controller will have no effect.
ExposureClass
Controller
ExposureClass
abstracts the ability to expose a Shoot clusters control plane in certain network environments (e.g. corporate networks, DMZ, internet) on all Seeds or a subset of the Seeds. For more information, see ExposureClasses.
Consequently, to ensure that ExposureClass
es in-use are always present in the system until the last referring Shoot
gets deleted, the controller adds a finalizer which is only released when there is no Shoot
referencing the ExposureClass
anymore.
ManagedSeedSet
Controller
ManagedSeedSet
objects maintain a stable set of replicas of ManagedSeed
s, i.e. they guarantee the availability of a specified number of identical ManagedSeed
s on an equal number of identical Shoot
s.
The ManagedSeedSet
controller creates and deletes ManagedSeed
s and Shoot
s in response to changes to the replicas and selector fields. For more information, refer to the ManagedSeedSet
proposal document.
- The reconciler first gets all the replicas of the given
ManagedSeedSet
in theManagedSeedSet
’s namespace and with the matching selector. Each replica is a struct that contains aManagedSeed
, its correspondingSeed
andShoot
objects. - Then the pending replica is retrieved, if it exists.
- Next it determines the ready, postponed, and deletable replicas.
- A replica is considered
ready
when aSeed
owned by aManagedSeed
has been registered either directly or by deployinggardenlet
into aShoot
, theSeed
isReady
and theShoot
’s status isHealthy
. - If a replica is not ready and it is not pending, i.e. it is not specified in the
ManagedSeed
’sstatus.pendingReplica
field, then it is added to thepostponed
replicas. - A replica is deletable if it has no scheduled
Shoot
s and the replica’sShoot
andManagedSeed
do not have theseedmanagement.gardener.cloud/protect-from-deletion
annotation.
- A replica is considered
- Finally, it checks the actual and target replica counts. If the actual count is less than the target count, the controller scales up the replicas by creating new replicas to match the desired target count. If the actual count is more than the target, the controller deletes replicas to match the desired count. Before scale-out or scale-in, the controller first reconciles the pending replica (there can always only be one) and makes sure the replica is ready before moving on to the next one.
Scale-out
(actual count < target count)- During the scale-out phase, the controller first creates the
Shoot
object from theManagedSeedSet
’sspec.shootTemplate
field and adds the replica to thestatus.pendingReplica
of theManagedSeedSet
. - For the subsequent reconciliation steps, the controller makes sure that the pending replica is ready before proceeding to the next replica. Once the
Shoot
is created successfully, theManagedSeed
object is created from theManagedSeedSet
’sspec.template
. TheManagedSeed
object is reconciled by theManagedSeed
controller and aSeed
object is created for the replica. Once the replica’sSeed
becomes ready and theShoot
becomes healthy, the replica also becomes ready.
- During the scale-out phase, the controller first creates the
Scale-in
(actual count > target count)- During the scale-in phase, the controller first determines the replica that can be deleted. From the deletable replicas, it chooses the one with the lowest priority and deletes it. Priority is determined in the following order:
- First, compare replica statuses. Replicas with “less advanced” status are considered lower priority. For example, a replica with
StatusShootReconciling
status has a lower value than a replica withStatusShootReconciled
status. Hence, in this case, a replica with aStatusShootReconciling
status will have lower priority and will be considered for deletion. - Then, the replicas are compared with the readiness of their
Seed
s. Replicas with non-readySeed
s are considered lower priority. - Then, the replicas are compared with the health statuses of their
Shoot
s. Replicas with “worse” statuses are considered lower priority. - Finally, the replica ordinals are compared. Replicas with lower ordinals are considered lower priority.
- First, compare replica statuses. Replicas with “less advanced” status are considered lower priority. For example, a replica with
- During the scale-in phase, the controller first determines the replica that can be deleted. From the deletable replicas, it chooses the one with the lowest priority and deletes it. Priority is determined in the following order:
Quota
Controller
Quota
object limits the resources consumed by shoot clusters either per provider secret or per project/namespace.
Consequently, to ensure that Quota
s in-use are always present in the system until the last SecretBinding
that references them gets deleted, the controller adds a finalizer which is only released when there is no SecretBinding
referencing the Quota
anymore.
Project
Controller
There are multiple controllers responsible for different aspects of Project
objects.
Please also refer to the Project
documentation.
“Main” Reconciler
This reconciler manages a dedicated Namespace
for each Project
.
The namespace name can either be specified explicitly in .spec.namespace
(must be prefixed with garden-
) or it will be determined by the controller.
If .spec.namespace
is set, it tries to create it. If it already exists, it tries to adopt it.
This will only succeed if the Namespace
was previously labeled with gardener.cloud/role=project
and project.gardener.cloud/name=<project-name>
.
This is to prevent end-users from being able to adopt arbitrary namespaces and escalate their privileges, e.g. the kube-system
namespace.
After the namespace was created/adopted, the controller creates several ClusterRole
s and ClusterRoleBinding
s that allow the project members to access related resources based on their roles.
These RBAC resources are prefixed with gardener.cloud:system:project{-member,-viewer}:<project-name>
.
Gardener administrators and extension developers can define their own roles. For more information, see Extending Project Roles for more information.
In addition, operators can configure the Project controller to maintain a default ResourceQuota for project namespaces.
Quotas can especially limit the creation of user facing resources, e.g. Shoots
, SecretBindings
, Secrets
and thus protect the garden cluster from massive resource exhaustion but also enable operators to align quotas with respective enterprise policies.
⚠️ Gardener itself is not exempted from configured quotas. For example, Gardener creates
Secrets
for every shoot cluster in the project namespace and at the same time increases the available quota count. Please mind this additional resource consumption.
The controller configuration provides a template section controllers.project.quotas
where such a ResourceQuota (see the example below) can be deposited.
controllers:
project:
quotas:
- config:
apiVersion: v1
kind: ResourceQuota
spec:
hard:
count/shoots.core.gardener.cloud: "100"
count/secretbindings.core.gardener.cloud: "10"
count/secrets: "800"
projectSelector: {}
The Project controller takes the specified config
and creates a ResourceQuota
with the name gardener
in the project namespace.
If a ResourceQuota
resource with the name gardener
already exists, the controller will only update fields in spec.hard
which are unavailable at that time.
This is done to configure a default Quota
in all projects but to allow manual quota increases as the projects’ demands increase.
spec.hard
fields in the ResourceQuota
object that are not present in the configuration are removed from the object.
Labels and annotations on the ResourceQuota
config
get merged with the respective fields on existing ResourceQuota
s.
An optional projectSelector
narrows down the amount of projects that are equipped with the given config
.
If multiple configs match for a project, then only the first match in the list is applied to the project namespace.
The .status.phase
of the Project
resources is set to Ready
or Failed
by the reconciler to indicate whether the reconciliation loop was performed successfully.
Also, it generates Event
s to provide further information about its operations.
When a Project
is marked for deletion, the controller ensures that there are no Shoots
left in the project namespace.
Once all Shoots
are gone, the Namespace
and Project
are released.
“Stale Projects” Reconciler
As Gardener is a large-scale Kubernetes as a Service, it is designed for being used by a large amount of end-users.
Over time, it is likely to happen that some of the hundreds or thousands of Project
resources are no longer actively used.
Gardener offers the “stale projects” reconciler which will take care of identifying such stale projects, marking them with a “warning”, and eventually deleting them after a certain time period. This reconciler is enabled by default and works as follows:
- Projects are considered as “stale”/not actively used when all of the following conditions apply: The namespace associated with the
Project
does not have any…Shoot
resources.BackupEntry
resources.Secret
resources that are referenced by aSecretBinding
that is in use by aShoot
(not necessarily in the same namespace).Quota
resources that are referenced by aSecretBinding
that is in use by aShoot
(not necessarily in the same namespace).- The time period when the project was used for the last time (
status.lastActivityTimestamp
) is longer than the configuredminimumLifetimeDays
If a project is considered “stale”, then its .status.staleSinceTimestamp
will be set to the time when it was first detected to be stale.
If it gets actively used again, this timestamp will be removed.
After some time, the .status.staleAutoDeleteTimestamp
will be set to a timestamp after which Gardener will auto-delete the Project
resource if it still is not actively used.
The component configuration of the gardener-controller-manager
offers to configure the following options:
minimumLifetimeDays
: Don’t consider newly createdProject
s as “stale” too early to give people/end-users some time to onboard and get familiar with the system. The “stale project” reconciler won’t set any timestamp forProject
s younger thanminimumLifetimeDays
. When you change this value, then projects marked as “stale” may be no longer marked as “stale” in case they are young enough, or vice versa.staleGracePeriodDays
: Don’t compute auto-delete timestamps for staleProject
s that are unused for less thanstaleGracePeriodDays
. This is to not unnecessarily make people/end-users nervous “just because” they haven’t actively used theirProject
for a given amount of time. When you change this value, then already assigned auto-delete timestamps may be removed if the new grace period is not yet exceeded.staleExpirationTimeDays
: Expiration time after which staleProject
s are finally auto-deleted (after.status.staleSinceTimestamp
). If this value is changed and an auto-delete timestamp got already assigned to the projects, then the new value will only take effect if it’s increased. Hence, decreasing thestaleExpirationTimeDays
will not decrease already assigned auto-delete timestamps.
Gardener administrators/operators can exclude specific
Project
s from the stale check by annotating the relatedNamespace
resource withproject.gardener.cloud/skip-stale-check=true
.
“Activity” Reconciler
Since the other two reconcilers are unable to actively monitor the relevant objects that are used in a Project
(Shoot
, Secret
, etc.), there could be a situation where the user creates and deletes objects in a short period of time. In that case, the Stale Project Reconciler
could not see that there was any activity on that project and it will still mark it as a Stale
, even though it is actively used.
The Project Activity Reconciler
is implemented to take care of such cases. An event handler will notify the reconciler for any acitivity and then it will update the status.lastActivityTimestamp
. This update will also trigger the Stale Project Reconciler
.
SecretBinding
Controller
SecretBinding
s reference Secret
s and Quota
s and are themselves referenced by Shoot
s.
The controller adds finalizers to the referenced objects to ensure they don’t get deleted while still being referenced.
Similarly, to ensure that SecretBinding
s in-use are always present in the system until the last referring Shoot
gets deleted, the controller adds a finalizer which is only released when there is no Shoot
referencing the SecretBinding
anymore.
Referenced Secret
s will also be labeled with provider.shoot.gardener.cloud/<type>=true
, where <type>
is the value of the .provider.type
of the SecretBinding
.
Also, all referenced Secret
s, as well as Quota
s, will be labeled with reference.gardener.cloud/secretbinding=true
to allow for easily filtering for objects referenced by SecretBinding
s.
Seed
Controller
The Seed controller in the gardener-controller-manager
reconciles Seed
objects with the help of the following reconcilers.
“Main” Reconciler
This reconciliation loop takes care of seed related operations in the garden cluster. When a new Seed
object is created,
the reconciler creates a new Namespace
in the garden cluster seed-<seed-name>
. Namespaces
dedicated to single
seed clusters allow us to segregate access permissions i.e., a gardenlet
must not have permissions to access objects in
all Namespaces
in the garden cluster.
There are objects in a Garden environment which are created once by the operator e.g., default domain secret,
alerting credentials, and are required for operations happening in the gardenlet
. Therefore, we not only need a seed specific
Namespace
but also a copy of these “shared” objects.
The “main” reconciler takes care about this replication:
Kind | Namespace | Label Selector |
---|---|---|
Secret | garden | gardener.cloud/role |
“Backup Buckets Check” Reconciler
Every time a BackupBucket
object is created or updated, the referenced Seed
object is enqueued for reconciliation.
It’s the reconciler’s task to check the status
subresource of all existing BackupBucket
s that reference this Seed
.
If at least one BackupBucket
has .status.lastError != nil
, the BackupBucketsReady
condition on the Seed
will be set to False
, and consequently the Seed
is considered as NotReady
.
If the SeedBackupBucketsCheckControllerConfiguration
(which is part of gardener-controller-manager
s component configuration) contains a conditionThreshold
for the BackupBucketsReady
, the condition will instead first be set to Progressing
and eventually to False
once the conditionThreshold
expires. See the example config file for details.
Once the BackupBucket
is healthy again, the seed will be re-queued and the condition will turn true
.
“Extensions Check” Reconciler
This reconciler reconciles Seed
objects and checks whether all ControllerInstallation
s referencing them are in a healthy state.
Concretely, all three conditions Valid
, Installed
, and Healthy
must have status True
and the Progressing
condition must have status False
.
Based on this check, it maintains the ExtensionsReady
condition in the respective Seed
’s .status.conditions
list.
“Lifecycle” Reconciler
The “Lifecycle” reconciler processes Seed
objects which are enqueued every 10 seconds in order to check if the responsible
gardenlet
is still responding and operable. Therefore, it checks renewals via Lease
objects of the seed in the garden cluster
which are renewed regularly by the gardenlet
.
In case a Lease
is not renewed for the configured amount in config.controllers.seed.monitorPeriod.duration
:
- The reconciler assumes that the
gardenlet
stopped operating and updates theGardenletReady
condition toUnknown
. - Additionally, the conditions and constraints of all
Shoot
resources scheduled on the affected seed are set toUnknown
as well, because a strikinggardenlet
won’t be able to maintain these conditions any more. - If the gardenlet’s client certificate has expired (identified based on the
.status.clientCertificateExpirationTimestamp
field in theSeed
resource) and if it is managed by aManagedSeed
, then this will be triggered for a reconciliation. This will trigger the bootstrapping process again and allows gardenlets to obtain a fresh client certificate.
Shoot
Controller
“Conditions” Reconciler
In case the reconciled Shoot
is registered via a ManagedSeed
as a seed cluster, this reconciler merges the conditions in the respective Seed
’s .status.conditions
into the .status.conditions
of the Shoot
.
This is to provide a holistic view on the status of the registered seed cluster by just looking at the Shoot
resource.
“Hibernation” Reconciler
This reconciler is responsible for hibernating or awakening shoot clusters based on the schedules defined in their .spec.hibernation.schedules
.
It ignores failed Shoot
s and those marked for deletion.
“Maintenance” Reconciler
This reconciler is responsible for maintaining shoot clusters based on the time window defined in their .spec.maintenance.timeWindow
.
It might auto-update the Kubernetes version or the operating system versions specified in the worker pools (.spec.provider.workers
).
It could also add some operation or task annotations. For more information, see Shoot Maintenance.
“Quota” Reconciler
This reconciler might auto-delete shoot clusters in case their referenced SecretBinding
is itself referencing a Quota
with .spec.clusterLifetimeDays != nil
.
If the shoot cluster is older than the configured lifetime, then it gets deleted.
It maintains the expiration time of the Shoot
in the value of the shoot.gardener.cloud/expiration-timestamp
annotation.
This annotation might be overridden, however only by at most twice the value of the .spec.clusterLifetimeDays
.
“Reference” Reconciler
Shoot objects may specify references to other objects in the garden cluster which are required for certain features.
For example, users can configure various DNS providers via .spec.dns.providers
and usually need to refer to a corresponding Secret
with valid DNS provider credentials inside.
Such objects need a special protection against deletion requests as long as they are still being referenced by one or multiple shoots.
Therefore, this reconciler checks Shoot
s for referenced objects and adds the finalizer gardener.cloud/reference-protection
to their .metadata.finalizers
list.
The reconciled Shoot
also gets this finalizer to enable a proper garbage collection in case the gardener-controller-manager
is offline at the moment of an incoming deletion request.
When an object is not actively referenced anymore because the Shoot
specification has changed or all related shoots were deleted (are in deletion), the controller will remove the added finalizer again so that the object can safely be deleted or garbage collected.
This reconciler inspects the following references:
- DNS provider secrets (
.spec.dns.provider
) - Audit policy configmaps (
.spec.kubernetes.kubeAPIServer.auditConfig.auditPolicy.configMapRef
)
Further checks might be added in the future.
“Retry” Reconciler
This reconciler is responsible for retrying certain failed Shoot
s.
Currently, the reconciler retries only failed Shoot
s with an error code ERR_INFRA_RATE_LIMITS_EXCEEDED
. See Shoot Status for more details.
“Status Label” Reconciler
This reconciler is responsible for maintaining the shoot.gardener.cloud/status
label on Shoot
s. See Shoot Status for more details.
1.2.8 - etcd
etcd - Key-Value Store for Kubernetes
etcd is a strongly consistent key-value store and the most prevalent choice for the Kubernetes
persistence layer. All API cluster objects like Pod
s, Deployment
s, Secret
s, etc., are stored in etcd
, which
makes it an essential part of a Kubernetes control plane.
Garden or Shoot Cluster Persistence
Each garden or shoot cluster gets its very own persistence for the control plane.
It runs in the shoot namespace on the respective seed cluster (or in the garden
namespace in the garden cluster, respectively).
Concretely, there are two etcd instances per shoot cluster, which the kube-apiserver
is configured to use in the following way:
etcd-main
A store that contains all “cluster critical” or “long-term” objects. These object kinds are typically considered for a backup to prevent any data loss.
etcd-events
A store that contains all Event
objects (events.k8s.io
) of a cluster.
Events
usually have a short retention period and occur frequently, but are not essential for a disaster recovery.
The setup above prevents both, the critical etcd-main
is not flooded by Kubernetes Events
, as well as backup space is not occupied by non-critical data.
This separation saves time and resources.
etcd Operator
Configuring, maintaining, and health-checking etcd is outsourced to a dedicated operator called etcd Druid.
When a gardenlet
reconciles a Shoot
resource or a gardener-operator
reconciles a Garden
resource, they manage an Etcd
resource in the seed or garden cluster, containing necessary information (backup information, defragmentation schedule, resources, etc.).
etcd-druid
needs to manage the lifecycle of the desired etcd instance (today main
or events
).
Likewise, when the Shoot
or Garden
is deleted, gardenlet
or gardener-operator
deletes the Etcd
resources and etcd Druid takes care of cleaning up all related objects, e.g. the backing StatefulSet
s.
Autoscaling
Gardenlet maintains HVPA
objects for etcd StatefulSet
s if the corresponding feature gate is enabled.
This enables a vertical scaling for etcd.
Downscaling is handled more pessimistically to prevent many subsequent etcd restarts.
Thus, for production
and infrastructure
shoot clusters (or all garden clusters), downscaling is deactivated for the main etcd.
For all other shoot clusters, lower advertised requests/limits are only applied during a shoot’s maintenance time window.
Backup
If Seed
s specify backups for etcd (example), then Gardener and the respective provider extensions are responsible for creating a bucket on the cloud provider’s side (modelled through a BackupBucket resource).
The bucket stores backups of Shoot
s scheduled on that Seed
.
Furthermore, Gardener creates a BackupEntry, which subdivides the bucket and thus makes it possible to store backups of multiple shoot clusters.
How long backups are stored in the bucket after a shoot has been deleted depends on the configured retention period in the Seed
resource.
Please see this example configuration for more information.
For Garden
s specifying backups for etcd (example), the bucket must be pre-created externally and provided via the Garden
specification.
Both etcd instances are configured to run with a special backup-restore sidecar. It takes care about regularly backing up etcd data and restoring it in case of data loss (in the main etcd only). The sidecar also performs defragmentation and other house-keeping tasks. More information can be found in the component’s GitHub repository.
Housekeeping
etcd maintenance tasks must be performed from time to time in order to re-gain database storage and to ensure the system’s reliability. The backup-restore sidecar takes care about this job as well.
For both Shoot
s and Garden
s, a random time within the shoot’s maintenance time is chosen for scheduling these tasks.
1.2.9 - gardenlet
gardenlet
Gardener is implemented using the operator pattern: It uses custom controllers that act on our own custom resources, and apply Kubernetes principles to manage clusters instead of containers. Following this analogy, you can recognize components of the Gardener architecture as well-known Kubernetes components, for example, shoot clusters can be compared with pods, and seed clusters can be seen as worker nodes.
The following Gardener components play a similar role as the corresponding components in the Kubernetes architecture:
Gardener Component | Kubernetes Component |
---|---|
gardener-apiserver | kube-apiserver |
gardener-controller-manager | kube-controller-manager |
gardener-scheduler | kube-scheduler |
gardenlet | kubelet |
Similar to how the kube-scheduler
of Kubernetes finds an appropriate node
for newly created pods, the gardener-scheduler
of Gardener finds an appropriate seed cluster
to host the control plane for newly ordered clusters.
By providing multiple seed clusters for a region or provider, and distributing the workload,
Gardener also reduces the blast radius of potential issues.
Kubernetes runs a primary “agent” on every node, the kubelet, which is responsible for managing pods and containers on its particular node. Decentralizing the responsibility to the kubelet has the advantage that the overall system is scalable. Gardener achieves the same for cluster management by using a gardenlet as а primary “agent” on every seed cluster, and is only responsible for shoot clusters located in its particular seed cluster:
The gardener-controller-manager
has controllers to manage resources of the Gardener API. However, instead of letting the gardener-controller-manager
talk directly to seed clusters or shoot clusters, the responsibility isn’t only delegated to the gardenlet, but also managed using a reversed control flow: It’s up to the gardenlet to contact the Gardener API server, for example, to share a status for its managed seed clusters.
Reversing the control flow allows placing seed clusters or shoot clusters behind firewalls without the necessity of direct access via VPN tunnels anymore.
TLS Bootstrapping
Kubernetes doesn’t manage worker nodes itself, and it’s also not responsible for the lifecycle of the kubelet running on the workers. Similarly, Gardener doesn’t manage seed clusters itself, so it is also not responsible for the lifecycle of the gardenlet running on the seeds. As a consequence, both the gardenlet and the kubelet need to prepare a trusted connection to the Gardener API server and the Kubernetes API server correspondingly.
To prepare a trusted connection between the gardenlet and the Gardener API server, the gardenlet initializes a bootstrapping process after you deployed it into your seed clusters:
The gardenlet starts up with a bootstrap
kubeconfig
having a bootstrap token that allows to createCertificateSigningRequest
(CSR) resources.After the CSR is signed, the gardenlet downloads the created client certificate, creates a new
kubeconfig
with it, and stores it inside aSecret
in the seed cluster.The gardenlet deletes the bootstrap
kubeconfig
secret, and starts up with its newkubeconfig
.The gardenlet starts normal operation.
The gardener-controller-manager
runs a control loop
that automatically signs CSRs created by gardenlets.
The gardenlet bootstrapping process is based on the kubelet bootstrapping process. More information: Kubelet’s TLS bootstrapping.
If you don’t want to run this bootstrap process, you can create
a kubeconfig
pointing to the garden cluster for the gardenlet yourself,
and use the field gardenClientConnection.kubeconfig
in the
gardenlet configuration to share it with the gardenlet.
gardenlet Certificate Rotation
The certificate used to authenticate the gardenlet against the API server
has a certain validity based on the configuration of the garden cluster
(--cluster-signing-duration
flag of the kube-controller-manager
(default 1y
)).
You can also configure the validity for the client certificate by specifying
.gardenClientConnection.kubeconfigValidity.validity
in the gardenlet’s component configuration. Note that changing this value will only take effect when the kubeconfig is rotated again (it is not picked up immediately). The minimum validity is10m
(that’s what is enforced by theCertificateSigningRequest
API in Kubernetes which is used by the gardenlet).
By default, after about 70-90% of the validity has expired, the gardenlet tries to automatically replace the current certificate with a new one (certificate rotation).
You can change these boundaries by specifying
.gardenClientConnection.kubeconfigValidity.autoRotationJitterPercentage{Min,Max}
in the gardenlet’s component configuration.
To use a certificate rotation, you need to specify the secret to store
the kubeconfig
with the rotated certificate in the field
.gardenClientConnection.kubeconfigSecret
of the
gardenlet component configuration.
Rotate Certificates Using Bootstrap kubeconfig
If the gardenlet created the certificate during the initial TLS Bootstrapping
using the Bootstrap kubeconfig
, certificates can be rotated automatically.
The same control loop in the gardener-controller-manager
that signs
the CSRs during the initial TLS Bootstrapping also automatically signs
the CSR during a certificate rotation.
ℹ️ You can trigger an immediate renewal by annotating the Secret
in the seed
cluster stated in the .gardenClientConnection.kubeconfigSecret
field with
gardener.cloud/operation=renew
. Within 10s
, gardenlet detects this and terminates
itself to request new credentials. After it has booted up again, gardenlet will issue a
new certificate independent of the remaining validity of the existing one.
ℹ️ Alternatively, annotate the respective Seed
with gardener.cloud/operation=renew-kubeconfig
.
This will make gardenlet annotate its own kubeconfig secret with gardener.cloud/operation=renew
and triggers the process described in the previous paragraph.
Rotate Certificates Using Custom kubeconfig
When trying to rotate a custom certificate that wasn’t created by gardenlet
as part of the TLS Bootstrap, the x509 certificate’s Subject
field
needs to conform to the following:
- the Common Name (CN) is prefixed with
gardener.cloud:system:seed:
- the Organization (O) equals
gardener.cloud:system:seeds
Otherwise, the gardener-controller-manager
doesn’t automatically
sign the CSR.
In this case, an external component or user needs to approve the CSR manually,
for example, using the command kubectl certificate approve seed-csr-<...>
).
If that doesn’t happen within 15 minutes,
the gardenlet repeats the process and creates another CSR.
Configuring the Seed to Work with gardenlet
The gardenlet works with a single seed, which must be configured in the
GardenletConfiguration
under .seedConfig
. This must be a copy of the
Seed
resource, for example:
apiVersion: gardenlet.config.gardener.cloud/v1alpha1
kind: GardenletConfiguration
seedConfig:
metadata:
name: my-seed
spec:
provider:
type: aws
# ...
settings:
scheduling:
visible: true
(see this yaml file for a more complete example)
On startup, gardenlet registers a Seed
resource using the given template
in the seedConfig
if it’s not present already.
Component Configuration
In the component configuration for the gardenlet, it’s possible to define:
- settings for the Kubernetes clients interacting with the various clusters
- settings for the controllers inside the gardenlet
- settings for leader election and log levels, feature gates, and seed selection or seed configuration.
More information: Example gardenlet Component Configuration.
Heartbeats
Similar to how Kubernetes uses Lease
objects for node heart beats
(see KEP),
the gardenlet is using Lease
objects for heart beats of the seed cluster.
Every two seconds, the gardenlet checks that the seed cluster’s /healthz
endpoint returns HTTP status code 200.
If that is the case, the gardenlet renews the lease in the Garden cluster in the gardener-system-seed-lease
namespace and updates
the GardenletReady
condition in the status.conditions
field of the Seed
resource. For more information, see this section.
Similar to the node-lifecycle-controller
inside the kube-controller-manager
,
the gardener-controller-manager
features a seed-lifecycle-controller
that sets
the GardenletReady
condition to Unknown
in case the gardenlet fails to renew the lease.
As a consequence, the gardener-scheduler
doesn’t consider this seed cluster for newly created shoot clusters anymore.
/healthz
Endpoint
The gardenlet includes an HTTP server that serves a /healthz
endpoint.
It’s used as a liveness probe in the Deployment
of the gardenlet.
If the gardenlet fails to renew its lease,
then the endpoint returns 500 Internal Server Error
, otherwise it returns 200 OK
.
Please note that the /healthz
only indicates whether the gardenlet
could successfully probe the Seed’s API server and renew the lease with
the Garden cluster.
It does not show that the Gardener extension API server (with the Gardener resource groups)
is available.
However, the gardenlet is designed to withstand such connection outages and
retries until the connection is reestablished.
Controllers
The gardenlet consists out of several controllers which are now described in more detail.
BackupBucket
Controller
The BackupBucket
controller reconciles those core.gardener.cloud/v1beta1.BackupBucket
resources whose .spec.seedName
value is equal to the name of the Seed
the respective gardenlet
is responsible for.
A core.gardener.cloud/v1beta1.BackupBucket
resource is created by the Seed
controller if .spec.backup
is defined in the Seed
.
The controller adds finalizers to the BackupBucket
and the secret mentioned in the .spec.secretRef
of the BackupBucket
. The controller also copies this secret to the seed cluster. Additionally, it creates an extensions.gardener.cloud/v1alpha1.BackupBucket
resource (non-namespaced) in the seed cluster and waits until the responsible extension controller reconciles it (see Contract: BackupBucket Resource for more details).
The status from the reconciliation is reported in the .status.lastOperation
field. Once the extension resource is ready and the .status.generatedSecretRef
is set by the extension controller, the gardenlet
copies the referenced secret to the garden
namespace in the garden cluster. An owner reference to the core.gardener.cloud/v1beta1.BackupBucket
is added to this secret.
If the core.gardener.cloud/v1beta1.BackupBucket
is deleted, the controller deletes the generated secret in the garden cluster and the extensions.gardener.cloud/v1alpha1.BackupBucket
resource in the seed cluster and it waits for the respective extension controller to remove its finalizers from the extensions.gardener.cloud/v1alpha1.BackupBucket
. Then it deletes the secret in the seed cluster and finally removes the finalizers from the core.gardener.cloud/v1beta1.BackupBucket
and the referred secret.
BackupEntry
Controller
The BackupEntry
controller reconciles those core.gardener.cloud/v1beta1.BackupEntry
resources whose .spec.seedName
value is equal to the name of a Seed
the respective gardenlet is responsible for.
Those resources are created by the Shoot
controller (only if backup is enabled for the respective Seed
) and there is exactly one BackupEntry
per Shoot
.
The controller creates an extensions.gardener.cloud/v1alpha1.BackupEntry
resource (non-namespaced) in the seed cluster and waits until the responsible extension controller reconciled it (see Contract: BackupEntry Resource for more details).
The status is populated in the .status.lastOperation
field.
The core.gardener.cloud/v1beta1.BackupEntry
resource has an owner reference pointing to the corresponding Shoot
.
Hence, if the Shoot
is deleted, the BackupEntry
resource also gets deleted.
In this case, the controller deletes the extensions.gardener.cloud/v1alpha1.BackupEntry
resource in the seed cluster and waits until the responsible extension controller has deleted it.
Afterwards, the finalizer of the core.gardener.cloud/v1beta1.BackupEntry
resource is released so that it finally disappears from the system.
If the spec.seedName
and .status.seedName
of the core.gardener.cloud/v1beta1.BackupEntry
are different, the controller will migrate it by annotating the extensions.gardener.cloud/v1alpha1.BackupEntry
in the Source Seed
with gardener.cloud/operation: migrate
, waiting for it to be migrated successfully and eventually deleting it from the Source Seed
cluster. Afterwards, the controller will recreate the extensions.gardener.cloud/v1alpha1.BackupEntry
in the Destination Seed
, annotate it with gardener.cloud/operation: restore
and wait for the restore operation to finish. For more details about control plane migration, please read Shoot Control Plane Migration.
Keep Backup for Deleted Shoots
In some scenarios it might be beneficial to not immediately delete the BackupEntry
s (and with them, the etcd backup) for deleted Shoot
s.
In this case you can configure the .controllers.backupEntry.deletionGracePeriodHours
field in the component configuration of the gardenlet.
For example, if you set it to 48
, then the BackupEntry
s for deleted Shoot
s will only be deleted 48
hours after the Shoot
was deleted.
Additionally, you can limit the shoot purposes for which this applies by setting .controllers.backupEntry.deletionGracePeriodShootPurposes[]
.
For example, if you set it to [production]
then only the BackupEntry
s for Shoot
s with .spec.purpose=production
will be deleted after the configured grace period. All others will be deleted immediately after the Shoot
deletion.
In case a BackupEntry
is scheduled for future deletion but you want to delete it immediately, add the annotation backupentry.core.gardener.cloud/force-deletion=true
.
Bastion
Controller
The Bastion
controller reconciles those operations.gardener.cloud/v1alpha1.Bastion
resources whose .spec.seedName
value is equal to the name of a Seed
the respective gardenlet is responsible for.
The controller creates an extensions.gardener.cloud/v1alpha1.Bastion
resource in the seed cluster in the shoot namespace with the same name as operations.gardener.cloud/v1alpha1.Bastion
. Then it waits until the responsible extension controller has reconciled it (see Contract: Bastion Resource for more details). The status is populated in the .status.conditions
and .status.ingress
fields.
During the deletion of operations.gardener.cloud/v1alpha1.Bastion
resources, the controller first sets the Ready
condition to False
and then deletes the extensions.gardener.cloud/v1alpha1.Bastion
resource in the seed cluster.
Once this resource is gone, the finalizer of the operations.gardener.cloud/v1alpha1.Bastion
resource is released, so it finally disappears from the system.
ControllerInstallation
Controller
The ControllerInstallation
controller in the gardenlet
reconciles ControllerInstallation
objects with the help of the following reconcilers.
“Main” Reconciler
This reconciler is responsible for ControllerInstallation
s referencing a ControllerDeployment
whose type=helm
.
For each ControllerInstallation
, it creates a namespace on the seed cluster named extension-<controller-installation-name>
.
Then, it creates a generic garden kubeconfig and garden access secret for the extension for accessing the garden cluster.
After that, it unpacks the Helm chart tarball in the ControllerDeployment
s .providerConfig.chart
field and deploys the rendered resources to the seed cluster.
The Helm chart values in .providerConfig.values
will be used and extended with some information about the Gardener environment and the seed cluster:
gardener:
version: <gardenlet-version>
garden:
clusterIdentity: <identity-of-garden-cluster>
genericKubeconfigSecretName: <secret-name>
gardenlet:
featureGates:
Foo: true
Bar: false
# ...
seed:
name: <seed-name>
clusterIdentity: <identity-of-seed-cluster>
annotations: <seed-annotations>
labels: <seed-labels>
spec: <seed-specification>
As of today, there are a few more fields in .gardener.seed
, but it is recommended to use the .gardener.seed.spec
if the Helm chart needs more information about the seed configuration.
The rendered chart will be deployed via a ManagedResource
created in the garden
namespace of the seed cluster.
It is labeled with controllerinstallation-name=<name>
so that one can easily find the owning ControllerInstallation
for an existing ManagedResource
.
The reconciler maintains the Installed
condition of the ControllerInstallation
and sets it to False
if the rendering or deployment fails.
“Care” Reconciler
This reconciler reconciles ControllerInstallation
objects and checks whether they are in a healthy state.
It checks the .status.conditions
of the backing ManagedResource
created in the garden
namespace of the seed cluster.
- If the
ResourcesApplied
condition of theManagedResource
isTrue
, then theInstalled
condition of theControllerInstallation
will be set toTrue
. - If the
ResourcesHealthy
condition of theManagedResource
isTrue
, then theHealthy
condition of theControllerInstallation
will be set toTrue
. - If the
ResourcesProgressing
condition of theManagedResource
isTrue
, then theProgressing
condition of theControllerInstallation
will be set toTrue
.
A ControllerInstallation
is considered “healthy” if Applied=Healthy=True
and Progressing=False
.
“Required” Reconciler
This reconciler watches all resources in the extensions.gardener.cloud
API group in the seed cluster.
It is responsible for maintaining the Required
condition on ControllerInstallation
s.
Concretely, when there is at least one extension resource in the seed cluster a ControllerInstallation
is responsible for, then the status of the Required
condition will be True
.
If there are no extension resources anymore, its status will be False
.
This condition is taken into account by the ControllerRegistration
controller part of gardener-controller-manager
when it computes which extensions have to be deployed to which seed cluster. See Gardener Controller Manager for more details.
ManagedSeed
Controller
The ManagedSeed
controller in the gardenlet
reconciles ManagedSeed
that refers to Shoot
scheduled on Seed
the gardenlet is responsible for. Additionally, the controller monitors Seed
s, which are owned by ManagedSeed
s for which the gardenlet is responsible.
On ManagedSeed
reconciliation, the controller first waits for the referenced Shoot to undergo a reconciliation process. Once the Shoot is successfully reconciled, the controller sets the ShootReconciled
status of the ManagedSeed to true
. Then, it creates garden
namespace within the target Shoot cluster. The controller also manages secrets related to Seeds, such as the backup
and kubeconfig
secrets. It ensures that these secrets are created and updated according to the ManagedSeed spec. Finally, it deploys the gardenlet
within the specified Shoot cluster which registers the Seed
cluster.
On ManagedSeed
deletion, the controller first deletes the corresponding Seed
that was originally created by the controller. Subsequently, it deletes the gardenlet
instance within the Shoot cluster. The controller also ensures the deletion of related Seed secrets. Finally, the dedicated garden
namespace within the Shoot cluster is deleted.
NetworkPolicy
Controller
The NetworkPolicy
controller reconciles NetworkPolicy
s in all relevant namespaces in the seed cluster and provides so-called “general” policies for access to the runtime cluster’s API server, DNS, public networks, etc.
The controller resolves the IP address of the Kubernetes service in the default
namespace and creates an egress NetworkPolicy
s for it.
For more details about NetworkPolicy
s in Gardener, please see NetworkPolicy
s In Garden, Seed, Shoot Clusters.
Seed
Controller
The Seed
controller in the gardenlet
reconciles Seed
objects with the help of the following reconcilers.
“Main Reconciler”
This reconciler is responsible for managing the seed’s system components.
Those comprise CA certificates, the various CustomResourceDefinition
s, the logging and monitoring stacks, and few central components like gardener-resource-manager
, etcd-druid
, istio
, etc.
The reconciler also deploys a BackupBucket
resource in the garden cluster in case the Seed'
s .spec.backup
is set.
It also checks whether the seed cluster’s Kubernetes version is at least the minimum supported version and errors in case this constraint is not met.
This reconciler maintains the .status.lastOperation
field, i.e. it sets it:
- to
state=Progressing
before it executes its reconciliation flow. - to
state=Error
in case an error occurs. - to
state=Succeeded
in case the reconciliation succeeded.
“Care” Reconciler
This reconciler checks whether the seed system components (deployed by the “main” reconciler) are healthy.
It checks the .status.conditions
of the backing ManagedResource
created in the garden
namespace of the seed cluster.
A ManagedResource
is considered “healthy” if the conditions ResourcesApplied=ResourcesHealthy=True
and ResourcesProgressing=False
.
If all ManagedResource
s are healthy, then the SeedSystemComponentsHealthy
condition of the Seed
will be set to True
.
Otherwise, it will be set to False
.
If at least one ManagedResource
is unhealthy and there is threshold configuration for the conditions (in .controllers.seedCare.conditionThresholds
), then the status of the SeedSystemComponentsHealthy
condition will be set:
- to
Progressing
if it wasTrue
before. - to
Progressing
if it wasProgressing
before and thelastUpdateTime
of the condition does not exceed the configured threshold duration yet. - to
False
if it wasProgressing
before and thelastUpdateTime
of the condition exceeds the configured threshold duration.
The condition thresholds can be used to prevent reporting issues too early just because there is a rollout or a short disruption.
Only if the unhealthiness persists for at least the configured threshold duration, then the issues will be reported (by setting the status to False
).
“Lease” Reconciler
This reconciler checks whether the connection to the seed cluster’s /healthz
endpoint works.
If this succeeds, then it renews a Lease
resource in the garden cluster’s gardener-system-seed-lease
namespace.
This indicates a heartbeat to the external world, and internally the gardenlet
sets its health status to true
.
In addition, the GardenletReady
condition in the status
of the Seed
is set to True
.
The whole process is similar to what the kubelet
does to report heartbeats for its Node
resource and its KubeletReady
condition. For more information, see this section.
If the connection to the /healthz
endpoint or the update of the Lease
fails, then the internal health status of gardenlet
is set to false
.
Also, this internal health status is set to false
automatically after some time, in case the controller gets stuck for whatever reason.
This internal health status is available via the gardenlet
’s /healthz
endpoint and is used for the livenessProbe
in the gardenlet
pod.
Shoot
Controller
The Shoot
controller in the gardenlet
reconciles Shoot
objects with the help of the following reconcilers.
“Main” Reconciler
This reconciler is responsible for managing all shoot cluster components and implements the core logic for creating, updating, hibernating, deleting, and migrating shoot clusters.
It is also responsible for syncing the Cluster
cluster to the seed cluster before and after each successful shoot reconciliation.
The main reconciliation logic is performed in 3 different task flows dedicated to specific operation types:
reconcile
(operations: create, reconcile, restore): this is the main flow responsible for creation and regular reconciliation of shoots. Hibernating a shoot also triggers this flow. It is also used for restoration of the shoot control plane on the new seed (second half of a Control Plane Migration)migrate
: this flow is triggered whenspec.seedName
specifies a different seed thanstatus.seedName
. It performs the first half of the Control Plane Migration, i.e., a backup (migrate
operation) of all control plane components followed by a “shallow delete”.delete
: this flow is triggered when the shoot’sdeletionTimestamp
is set, i.e., when it is deleted.
The gardenlet takes special care to prevent unnecessary shoot reconciliations. This is important for several reasons, e.g., to not overload the seed API servers and to not exhaust infrastructure rate limits too fast. The gardenlet performs shoot reconciliations according to the following rules:
- If
status.observedGeneration
is less thanmetadata.generation
: this is the case, e.g., when the spec was changed, a manual reconciliation operation was triggered, or the shoot was deleted. - If the last operation was not successful.
- If the shoot is in a failed state, the gardenlet does not perform any reconciliation on the shoot (unless the retry operation was triggered). However, it syncs the
Cluster
resource to the seed in order to inform the extension controllers about the failed state. - Regular reconciliations are performed with every
GardenletConfiguration.controllers.shoot.syncPeriod
(defaults to1h
). - Shoot reconciliations are not performed if the assigned seed cluster is not healthy or has not been reconciled by the current gardenlet version yet (determined by the
Seed.status.gardener
section). This is done to make sure that shoots are reconciled with fully rolled out seed system components after a Gardener upgrade. Otherwise, the gardenlet might perform operations of the new version that doesn’t match the old version of the deployed seed system components, which might lead to unspecified behavior.
There are a few special cases that overwrite or confine how often and under which circumstances periodic shoot reconciliations are performed:
- In case the gardenlet config allows it (
controllers.shoot.respectSyncPeriodOverwrite
, disabled by default), the sync period for a shoot can be increased individually by setting theshoot.gardener.cloud/sync-period
annotation. This is always allowed for shoots in thegarden
namespace. Shoots are not reconciled with a higher frequency than specified inGardenletConfiguration.controllers.shoot.syncPeriod
. - In case the gardenlet config allows it (
controllers.shoot.respectSyncPeriodOverwrite
, disabled by default), shoots can be marked as “ignored” by setting theshoot.gardener.cloud/ignore
annotation. In this case, the gardenlet does not perform any reconciliation for the shoot. - In case
GardenletConfiguration.controllers.shoot.reconcileInMaintenanceOnly
is enabled (disabled by default), the gardenlet performs regular shoot reconciliations only once in the respective maintenance time window (GardenletConfiguration.controllers.shoot.syncPeriod
is ignored). The gardenlet randomly distributes shoot reconciliations over the maintenance time window to avoid high bursts of reconciliations (see Shoot Maintenance). - In case
Shoot.spec.maintenance.confineSpecUpdateRollout
is enabled (disabled by default), changes to the shoot specification are not rolled out immediately but only during the respective maintenance time window (see Shoot Maintenance).
“Care” Reconciler
This reconciler performs three “care” actions related to Shoot
s.
Conditions
It maintains the following conditions:
APIServerAvailable
: The/healthz
endpoint of the shoot’skube-apiserver
is called and considered healthy when it responds with200 OK
.ControlPlaneHealthy
: The control plane is considered healthy when the respectiveDeployment
s (for examplekube-apiserver
,kube-controller-manager
), andEtcd
s (for exampleetcd-main
) exist and are healthy.ObservabilityComponentsHealthy
: This condition is considered healthy when the respectiveDeployment
s (for exampleplutono
) andStatefulSet
s (for exampleprometheus
,vali
) exist and are healthy.EveryNodyReady
: The conditions of the worker nodes are checked (e.g.,Ready
,MemoryPressure
). Also, it’s checked whether the Kubernetes version of the installedkubelet
matches the desired version specified in theShoot
resource.SystemComponentsHealthy
: The conditions of theManagedResource
s are checked (e.g.,ResourcesApplied
). Also, it is verified whether the VPN tunnel connection is established (which is required for thekube-apiserver
to communicate with the worker nodes).
Sometimes, ManagedResource
s can have both Healthy
and Progressing
conditions set to True
(e.g., when a DaemonSet
rolls out one-by-one on a large cluster with many nodes) while this is not reflected in the Shoot
status. In order to catch issues where the rollout gets stuck, one can set .controllers.shootCare.managedResourceProgressingThreshold
in the gardenlet
’s component configuration. If the Progressing
condition is still True
for more than the configured duration, the SystemComponentsHealthy
condition in the Shoot
is set to False
, eventually.
Each condition can optionally also have error codes
in order to indicate which type of issue was detected (see Shoot Status for more details).
Apart from the above, extension controllers can also contribute to the status
or error codes
of these conditions (see Contributing to Shoot Health Status Conditions for more details).
If all checks for a certain conditions are succeeded, then its status
will be set to True
.
Otherwise, it will be set to False
.
If at least one check fails and there is threshold configuration for the conditions (in .controllers.seedCare.conditionThresholds
), then the status will be set:
- to
Progressing
if it wasTrue
before. - to
Progressing
if it wasProgressing
before and thelastUpdateTime
of the condition does not exceed the configured threshold duration yet. - to
False
if it wasProgressing
before and thelastUpdateTime
of the condition exceeds the configured threshold duration.
The condition thresholds can be used to prevent reporting issues too early just because there is a rollout or a short disruption.
Only if the unhealthiness persists for at least the configured threshold duration, then the issues will be reported (by setting the status to False
).
Constraints And Automatic Webhook Remediation
Please see Shoot Status for more details.
Garbage Collection
Stale pods in the shoot namespace in the seed cluster and in the kube-system
namespace in the shoot cluster are deleted.
A pod is considered stale when:
- it was terminated with reason
Evicted
. - it was terminated with reason starting with
OutOf
(e.g.,OutOfCpu
). - it is stuck in termination (i.e., if its
deletionTimestamp
is more than5m
ago).
“State” Reconciler
This reconciler periodically (default: every 6h
) performs backups of the state of Shoot
clusters and persists them into ShootState
resources into the same namespace as the Shoot
s in the garden cluster.
It is only started in case the gardenlet
is responsible for an unmanaged Seed
, i.e. a Seed
which is not backed by a seedmanagement.gardener.cloud/v1alpha1.ManagedSeed
object.
Alternatively, it can be disabled by setting the concurrentSyncs=0
for the controller in the gardenlet
’s component configuration.
Please refer to GEP-22: Improved Usage of the ShootState
API for all information.
TokenRequestor
Controller
The gardenlet
uses an instance of the TokenRequestor
controller which initially was developed in the context of the gardener-resource-manager
, please read this document for further information.
gardenlet
uses it for requesting tokens for components running in the seed cluster that need to communicate with the garden cluster.
The mechanism works the same way as for shoot control plane components running in the seed which need to communicate with the shoot cluster.
However, gardenlet
’s instance of the TokenRequestor
controller is restricted to Secret
s labeled with resources.gardener.cloud/class=garden
.
Furthermore, it doesn’t respect the serviceaccount.resources.gardener.cloud/namespace
annotation. Instead, it always uses the seed’s namespace in the garden cluster for managing ServiceAccounts
and their tokens.
Managed Seeds
Gardener users can use shoot clusters as seed clusters, so-called “managed seeds” (aka “shooted seeds”),
by creating ManagedSeed
resources.
By default, the gardenlet that manages this shoot cluster then automatically
creates a clone of itself with the same version and the same configuration
that it currently has.
Then it deploys the gardenlet clone into the managed seed cluster.
For more information, see Register Shoot as Seed.
Migrating from Previous Gardener Versions
If your Gardener version doesn’t support gardenlets yet, no special migration is required, but the following prerequisites must be met:
- Your Gardener version is at least 0.31 before upgrading to v1.
- You have to make sure that your garden cluster is exposed in a way that it’s reachable from all your seed clusters.
With previous Gardener versions, you had deployed the Gardener Helm chart
(incorporating the API server, controller-manager
, and scheduler).
With v1, this stays the same, but you now have to deploy the gardenlet Helm chart as well
into all of your seeds (if they aren’t managed, as mentioned earlier).
See Deploy a gardenlet for all instructions.
Related Links
1.2.10 - Node Agent
Gardener Node Agent
The goal of the gardener-node-agent
is to bootstrap a machine into a worker node and maintain node-specific components, which run on the node and are unmanaged by Kubernetes (e.g. the kubelet
service, systemd units, …).
It effectively is a Kubernetes controller deployed onto the worker node.
Architecture and Basic Design
This figure visualizes the overall architecture of the gardener-node-agent
. On the left side, it starts with an OperatingSystemConfig
resource (OSC
) with a corresponding worker pool specific cloud-config-<worker-pool>
secret being passed by reference through the userdata to a machine by the machine-controller-manager
(MCM).
On the right side, the cloud-config
secret will be extracted and used by the gardener-node-agent
after being installed. Details on this can be found in the next section.
Finally, the gardener-node-agent
runs a systemd service watching on secret resources located in the kube-system
namespace like our cloud-config
secret that contains the OperatingSystemConfig
. When gardener-node-agent
applies the OSC, it installs the kubelet
+ configuration on the worker node.
Installation and Bootstrapping
This section describes how the gardener-node-agent
is initially installed onto the worker node.
In the beginning, there is a very small bash script called gardener-node-init.sh
, which will be copied to /var/lib/gardener-node-agent/init.sh
on the node with cloud-init data.
This script’s sole purpose is downloading and starting the gardener-node-agent
.
The binary artifact is extracted from an OCI artifact and lives at /opt/bin/gardener-node-agent
.
Along with the init script, a configuration for the gardener-node-agent
is carried over to the worker node at /var/lib/gardener-node-agent/config.yaml
.
This configuration contains things like the shoot’s kube-apiserver
endpoint, the according certificates to communicate with it, and controller configuration.
In a bootstrapping phase, the gardener-node-agent
sets itself up as a systemd service.
It also executes tasks that need to be executed before any other components are installed, e.g. formatting the data device for the kubelet
.
Controllers
This section describes the controllers in more details.
Lease
Controller
This controller creates a Lease
for gardener-node-agent
in kube-system
namespace of the shoot cluster.
Each instance of gardener-node-agent
creates its own Lease
when its corresponding Node
was created.
It renews the Lease
resource every 10 seconds. This indicates a heartbeat to the external world.
Node
Controller
This controller watches the Node
object for the machine it runs on.
The correct Node
is identified based on the hostname of the machine (Node
s have the kubernetes.io/hostname
label).
Whenever the worker.gardener.cloud/restart-systemd-services
annotation changes, the controller performs the desired changes by restarting the specified systemd unit files.
See also this document for more information.
After restarting all units, the annotation is removed.
ℹ️ When the
gardener-node-agent
systemd service itself is requested to be restarted, the annotation is removed first to ensure it does not restart itself indefinitely.
Operating System Config Controller
This controller contains the main logic of gardener-node-agent
.
It watches Secret
s whose data
map contains the OperatingSystemConfig
which consists of all systemd units and files that are relevant for the node configuration.
Amongst others, a prominent example is the configuration file for kubelet
and its unit file for the kubelet.service
.
The controller decodes the configuration and computes the files and units that have changed since its last reconciliation. It writes or update the files and units to the file system, removes no longer needed files and units, reloads the systemd daemon, and starts or stops the units accordingly.
After successful reconciliation, it persists the just applied OperatingSystemConfig
into a file on the host.
This file will be used for future reconciliations to compute file/unit changes.
The controller also maintains two annotations on the Node
:
worker.gardener.cloud/kubernetes-version
, describing the version of the installedkubelet
.checksum/cloud-config-data
, describing the checksum of the appliedOperatingSystemConfig
(used in future reconciliations to determine whether it needs to reconcile, and to report that this node is up-to-date).
Token Controller
This controller watches the access token Secret
s in the kube-system
namespace configured via the gardener-node-agent
’s component configuration (.controllers.token.syncConfigs[]
field).
Whenever the .data.token
field changes, it writes the new content to a file on the configured path on the host file system.
This mechanism is used to download its own access token for the shoot cluster, but also the access tokens of other systemd
components (e.g., valitail
).
Since the underlying client is based on k8s.io/client-go
and the kubeconfig points to this token file, it is dynamically reloaded without the necessity of explicit configuration or code changes.
This procedure ensures that the most up-to-date tokens are always present on the host and used by the gardener-node-agent
and the other systemd
components.
Reasoning
The gardener-node-agent
is a replacement for what was called the cloud-config-downloader
and the cloud-config-executor
, both written in bash
. The gardener-node-agent
implements this functionality as a regular controller and feels more uniform in terms of maintenance.
With the new architecture we gain a lot, let’s describe the most important gains here.
Developer Productivity
Since the Gardener community develops in Go day by day, writing business logic in bash
is difficult, hard to maintain, almost impossible to test. Getting rid of almost all bash
scripts which are currently in use for this very important part of the cluster creation process will enhance the speed of adding new features and removing bugs.
Speed
Until now, the cloud-config-downloader
runs in a loop every 60s
to check if something changed on the shoot which requires modifications on the worker node. This produces a lot of unneeded traffic on the API server and wastes time, it will sometimes take up to 60s
until a desired modification is started on the worker node.
By writing a “real” Kubernetes controller, we can watch for the Node
, the OSC
in the Secret
, and the shoot-access token in the secret
. If any of these object changed, and only then, the required action will take effect immediately.
This will speed up operations and will reduce the load on the API server of the shoot especially for large clusters.
Scalability
The cloud-config-downloader
adds a random wait time before restarting the kubelet
in case the kubelet
was updated or a configuration change was made to it. This is required to reduce the load on the API server and the traffic on the internet uplink. It also reduces the overall downtime of the services in the cluster because every kubelet
restart transforms a node for several seconds into NotReady
state which potentionally interrupts service availability.
Decision was made to keep the existing jitter mechanism which calculates the kubelet-download-and-restart-delay-seconds
on the controller itself.
Correctness
The configuration of the cloud-config-downloader
is actually done by placing a file for every configuration item on the disk on the worker node. This was done because parsing the content of a single file and using this as a value in bash
reduces to something like VALUE=$(cat /the/path/to/the/file)
. Simple, but it lacks validation, type safety and whatnot.
With the gardener-node-agent
we introduce a new API which is then stored in the gardener-node-agent
secret
and stored on disk in a single YAML file for comparison with the previous known state. This brings all benefits of type safe configuration.
Because actual and previous configuration are compared, removed files and units are also removed and stopped on the worker if removed from the OSC
.
Availability
Previously, the cloud-config-downloader
simply restarted the systemd units on every change to the OSC
, regardless which of the services changed. The gardener-node-agent
first checks which systemd unit was changed, and will only restart these. This will prevent unneeded kubelet
restarts.
Future Development
The gardener-node-agent
opens up the possibilty for further improvements.
Necessary restarts of the kubelet
could be deterministic instead of the aforementioned random jittering. In that case, the gardenlet
could add annotations across all nodes. As the gardener-node-agent
watches the Node
object, it could wait with kubelet
restarts, OSC changes or react immediately. Critical changes could be performed in chunks of nodes in serial order, but an equal time spread is possible, too.
1.2.11 - Operator
Gardener Operator
The gardener-operator
is responsible for the garden cluster environment.
Without this component, users must deploy ETCD, the Gardener control plane, etc., manually and with separate mechanisms (not maintained in this repository).
This is quite unfortunate since this requires separate tooling, processes, etc.
A lot of production- and enterprise-grade features were built into Gardener for managing the seed and shoot clusters, so it makes sense to re-use them as much as possible also for the garden cluster.
Deployment
There is a Helm chart which can be used to deploy the gardener-operator
.
Once deployed and ready, you can create a Garden
resource.
Note that there can only be one Garden
resource per system at a time.
ℹ️ Similar to seed clusters, garden runtime clusters require a VPA, see this section. By default,
gardener-operator
deploys the VPA components. However, when there already is a VPA available, then set.spec.runtimeCluster.settings.verticalPodAutoscaler.enabled=false
in theGarden
resource.
Garden
Resources
Please find an exemplary Garden
resource here.
Settings For Runtime Cluster
The Garden
resource offers a few settings that are used to control the behaviour of gardener-operator
in the runtime cluster.
This section provides an overview over the available settings in .spec.runtimeCluster.settings
:
Load Balancer Services
gardener-operator
deploys Istio and relevant resources to the runtime cluster in order to expose the virtual-garden-kube-apiserver
service (similar to how the kube-apiservers
of shoot clusters are exposed).
In most cases, the cloud-controller-manager
(responsible for managing these load balancers on the respective underlying infrastructure) supports certain customization and settings via annotations.
This document provides a good overview and many examples.
By setting the .spec.settings.loadBalancerServices.annotations
field the Gardener administrator can specify a list of annotations which will be injected into the Service
s of type LoadBalancer
.
Vertical Pod Autoscaler
gardener-operator
heavily relies on the Kubernetes vertical-pod-autoscaler
component.
By default, the Garden
controller deploys the VPA components into the garden
namespace of the respective runtime cluster.
In case you want to manage the VPA deployment on your own or have a custom one, then you might want to disable the automatic deployment of gardener-operator
.
Otherwise, you might end up with two VPAs which will cause erratic behaviour.
By setting the .spec.settings.verticalPodAutoscaler.enabled=false
you can disable the automatic deployment.
⚠️ In any case, there must be a VPA available for your runtime cluster. Using a runtime cluster without VPA is not supported.
Topology-Aware Traffic Routing
Refer to the Topology-Aware Traffic Routing documentation as this document contains the documentation for the topology-aware routing setting for the garden runtime cluster.
Controllers
As of today, the gardener-operator
only has two controllers which are now described in more detail.
Garden
Controller
The Garden controller in the operator reconciles Garden objects with the help of the following reconcilers.
Main
Reconciler
The reconciler first generates a general CA certificate which is valid for ~30d
and auto-rotated when 80% of its lifetime is reached.
Afterwards, it brings up the so-called “garden system components”.
The gardener-resource-manager
is deployed first since its ManagedResource
controller will be used to bring up the remainders.
Other system components are:
- runtime garden system resources (
PriorityClass
es for the workload resources) - virtual garden system resources (RBAC rules)
- Vertical Pod Autoscaler (if enabled via
.spec.runtimeCluster.settings.verticalPodAutoscaler.enabled=true
in theGarden
) - HVPA Controller (when
HVPA
feature gate is enabled) - ETCD Druid
- Istio
As soon as all system components are up, the reconciler deploys the virtual garden cluster.
It comprises out of two ETCDs (one “main” etcd, one “events” etcd) which are managed by ETCD Druid via druid.gardener.cloud/v1alpha1.Etcd
custom resources.
The whole management works similar to how it works for Shoot
s, so you can take a look at this document for more information in general.
The virtual garden control plane components are:
virtual-garden-etcd-main
virtual-garden-etcd-events
virtual-garden-kube-apiserver
virtual-garden-kube-controller-manager
virtual-garden-gardener-resource-manager
If the .spec.virtualCluster.controlPlane.highAvailability={}
is set then these components will be deployed in a “highly available” mode.
For ETCD, this means that there will be 3 replicas each.
This works similar like for Shoot
s (see this document) except for the fact that there is no failure tolerance type configurability.
The gardener-resource-manager
’s HighAvailabilityConfig webhook makes sure that all pods with multiple replicas are spread on nodes, and if there are at least two zones in .spec.runtimeCluster.provider.zones
then they also get spread across availability zones.
If once set, removing
.spec.virtualCluster.controlPlane.highAvailability
again is not supported.
The virtual-garden-kube-apiserver
Deployment
is exposed via a Service
of type LoadBalancer
with the same name.
In the future, we will switch to exposing it via Istio, similar to how the kube-apiservers
of shoot clusters are exposed.
Similar to the Shoot
API, the version of the virtual garden cluster is controlled via .spec.virtualCluster.kubernetes.version
.
Likewise, specific configuration for the control plane components can be provided in the same section, e.g. via .spec.virtualCluster.kubernetes.kubeAPIServer
for the kube-apiserver
or .spec.virtualCluster.kubernetes.kubeControllerManager
for the kube-controller-manager
.
The kube-controller-manager
only runs a very few controllers that are necessary in the scenario of the virtual garden.
Most prominently, the serviceaccount-token
controller is unconditionally disabled.
Hence, the usage of static ServiceAccount
secrets is not supported generally.
Instead, the TokenRequest
API should be used.
Third-party components that need to communicate with the virtual cluster can leverage the gardener-resource-manager
’s TokenRequestor
controller and the generic kubeconfig, just like it works for Shoot
s.
Please note, that this functionality is restricted to the garden
namespace. The current Secret
name of the generic kubeconfig can be found in the annotations (key: generic-token-kubeconfig.secret.gardener.cloud/name
) of the Garden
resource.
For the virtual cluster, it is essential to provide a DNS domain via .spec.virtualCluster.dns.domain
.
The respective DNS record is not managed by gardener-operator
and should be manually created and pointed to the load balancer IP of the virtual-garden-kube-apiserver
Service
.
The DNS domain is used for the server
in the kubeconfig, and for configuring the --external-hostname
flag of the API server.
Apart from the control plane components of the virtual cluster, the reconcile also deploys the control plane components of Gardener.
gardener-apiserver
reuses the same ETCDs like the virtual-garden-kube-apiserver
, so all data related to the “the garden cluster” is stored together and “isolated” from ETCD data related to the runtime cluster.
This drastically simplifies backup and restore capabilities (e.g., moving the virtual garden cluster from one runtime cluster to another).
The Gardener control plane components are:
gardener-apiserver
gardener-admission-controller
gardener-controller-manager
gardener-scheduler
The reconciler also manages a few observability-related components (more planned as part of GEP-19):
fluent-operator
fluent-bit
gardener-metrics-exporter
kube-state-metrics
plutono
vali
It is also mandatory to provide an IPv4 CIDR for the service network of the virtual cluster via .spec.virtualCluster.networking.services
.
This range is used by the API server to compute the cluster IPs of Service
s.
The controller maintains the .status.lastOperation
which indicates the status of an operation.
Care
Reconciler
This reconciler performs four “care” actions related to Garden
s.
It maintains the following conditions:
RuntimeComponentsHealthy
: The conditions of theManagedResource
s applied to the runtime cluster are checked (e.g.,ResourcesApplied
).VirtualComponentsHealthy
: The virtual components are considered healthy when the respectiveDeployment
s (for examplevirtual-garden-kube-apiserver
,virtual-garden-kube-controller-manager
), andEtcd
s (for examplevirtual-garden-etcd-main
) exist and are healthy. Additionally, the conditions of theManagedResource
s applied to the virtual cluster are checked (e.g.,ResourcesApplied
).VirtualGardenAPIServerAvailable
: The/healthz
endpoint of the garden’svirtual-garden-kube-apiserver
is called and considered healthy when it responds with200 OK
.ObservabilityComponentsHealthy
: This condition is considered healthy when the respectiveDeployment
s (for exampleplutono
) andStatefulSet
s (for exampleprometheus
,vali
) exist and are healthy.
If all checks for a certain condition are succeeded, then its status
will be set to True
.
Otherwise, it will be set to False
or Progressing
.
If at least one check fails and there is threshold configuration for the conditions (in .controllers.gardenCare.conditionThresholds
), then the status will be set:
- to
Progressing
if it wasTrue
before. - to
Progressing
if it wasProgressing
before and thelastUpdateTime
of the condition does not exceed the configured threshold duration yet. - to
False
if it wasProgressing
before and thelastUpdateTime
of the condition exceeds the configured threshold duration.
The condition thresholds can be used to prevent reporting issues too early just because there is a rollout or a short disruption.
Only if the unhealthiness persists for at least the configured threshold duration, then the issues will be reported (by setting the status to False
).
Reference
Reconciler
Garden
objects may specify references to other objects in the Garden cluster which are required for certain features.
For example, operators can configure a secret for ETCD backup via .spec.virtualCluster.etcd.main.backup.secretRef.name
or an audit policy ConfigMap
via .spec.virtualCluster.kubernetes.kubeAPIServer.auditConfig.auditPolicy.configMapRef.name
.
Such objects need a special protection against deletion requests as long as they are still being referenced by the Garden
.
Therefore, this reconciler checks Garden
s for referenced objects and adds the finalizer gardener.cloud/reference-protection
to their .metadata.finalizers
list.
The reconciled Garden
also gets this finalizer to enable a proper garbage collection in case the gardener-operator
is offline at the moment of an incoming deletion request.
When an object is not actively referenced anymore because the Garden
specification has changed is in deletion, the controller will remove the added finalizer again so that the object can safely be deleted or garbage collected.
This reconciler inspects the following references:
- ETCD backup
Secret
s (.spec.virtualCluster.etcd.main.backup.secretRef
) - Admission plugin kubeconfig
Secret
s (.spec.virtualCluster.kubernetes.kubeAPIServer.admissionPlugins[].kubeconfigSecretName
and.spec.virtualCluster.gardener.gardenerAPIServer.admissionPlugins[].kubeconfigSecretName
) - Authentication webhook kubeconfig
Secret
s (.spec.virtualCluster.kubernetes.kubeAPIServer.authentication.webhook.kubeconfigSecretName
) - Audit webhook kubeconfig
Secret
s (.spec.virtualCluster.kubernetes.kubeAPIServer.auditWebhook.kubeconfigSecretName
and.spec.virtualCluster.gardener.gardenerAPIServer.auditWebhook.kubeconfigSecretName
) - SNI
Secret
s (.spec.virtualCluster.kubernetes.kubeAPIServer.sni.secretName
) - Audit policy
ConfigMap
s (.spec.virtualCluster.kubernetes.kubeAPIServer.auditConfig.auditPolicy.configMapRef.name
and.spec.virtualCluster.gardener.gardenerAPIServer.auditConfig.auditPolicy.configMapRef.name
)
Further checks might be added in the future.
NetworkPolicy
Controller Registrar
This controller registers the same NetworkPolicy
controller which is also used in gardenlet
, please read it up here for more details.
The registration happens as soon as the Garden
resource is created.
It contains the networking information of the garden runtime cluster which is required configuration for the NetworkPolicy
controller.
Webhooks
As of today, the gardener-operator
only has one webhook handler which is now described in more detail.
Validation
This webhook handler validates CREATE
/UPDATE
/DELETE
operations on Garden
resources.
Simple validation is performed via standard CRD validation.
However, more advanced validation is hard to express via these means and is performed by this webhook handler.
Furthermore, for deletion requests, it is validated that the Garden
is annotated with a deletion confirmation annotation, namely confirmation.gardener.cloud/deletion=true
.
Only if this annotation is present it allows the DELETE
operation to pass.
This prevents users from accidental/undesired deletions.
Another validation is to check that there is only one Garden
resource at a time.
It prevents creating a second Garden
when there is already one in the system.
Defaulting
This webhook handler mutates the Garden
resource on CREATE
/UPDATE
/DELETE
operations.
Simple defaulting is performed via standard CRD defaulting.
However, more advanced defaulting is hard to express via these means and is performed by this webhook handler.
Using Garden Runtime Cluster As Seed Cluster
In production scenarios, you probably wouldn’t use the Kubernetes cluster running gardener-operator
and the Gardener control plane (called “runtime cluster”) as seed cluster at the same time.
However, such setup is technically possible and might simplify certain situations (e.g., development, evaluation, …).
If the runtime cluster is a seed cluster at the same time, gardenlet
’s Seed
controller will not manage the components which were already deployed (and reconciled) by gardener-operator
.
As of today, this applies to:
gardener-resource-manager
vpa-{admission-controller,recommender,updater}
hvpa-controller
(whenHVPA
feature gate is enabled)etcd-druid
istio
control-planenginx-ingress-controller
Those components are so-called “seed system components”. In addition, there are a few observability components:
fluent-operator
fluent-bit
vali
plutono
kube-state-metrics
As all of these components are managed by gardener-operator
in this scenario, the gardenlet
just skips them.
ℹ️ There is no need to configure anything - the
gardenlet
will automatically detect when its seed cluster is the garden runtime cluster at the same time.
⚠️ Note that such setup requires that you upgrade the versions of gardener-operator
and gardenlet
in lock-step.
Otherwise, you might experience unexpected behaviour or issues with your seed or shoot clusters.
Credentials Rotation
The credentials rotation works in the same way as it does for Shoot
resources, i.e. there are gardener.cloud/operation
annotation values for starting or completing the rotation procedures.
For certificate authorities, gardener-operator
generates one which is automatically rotated roughly each month (ca-garden-runtime
) and several CAs which are NOT automatically rotated but only on demand.
🚨 Hence, it is the responsibility of the (human) operator to regularly perform the credentials rotation.
Please refer to this document for more details. As of today, gardener-operator
only creates the following types of credentials (i.e., some sections of the document don’t apply for Garden
s and can be ignored):
- certificate authorities (and related server and client certificates)
- ETCD encryption key
- observability password For Plutono
ServiceAccount
token signing key
⚠️ Rotation of static ServiceAccount
secrets is not supported since the kube-controller-manager
does not enable the serviceaccount-token
controller.
When the ServiceAccount
token signing key rotation is in Preparing
phase, then gardener-operator
annotates all Seed
s with gardener.cloud/operation=renew-garden-access-secrets
.
This causes gardenlet
to populate new ServiceAccount
tokens for the garden cluster to all extensions, which are now signed with the new signing key.
Read more about it here.
Similarly, when the CA certificate rotation is in Preparing
phase, then gardener-operator
annotates all Seed
s with gardener.cloud/operation=renew-kubeconfig
.
This causes gardenlet
to request a new client certificate for its garden cluster kubeconfig, which is now signed with the new client CA, and which also contains the new CA bundle for the server certificate verification.
Read more about it here.
Migrating an Existing Gardener Landscape to gardener-operator
Since gardener-operator
was only developed in 2023, six years after the Gardener project initiation, most users probably already have an existing Gardener landscape.
The most prominent installation procedure is garden-setup, however experience shows that most community members have developed their own tooling for managing the garden cluster and the Gardener control plane components.
Consequently, providing a general migration guide is not possible since the detailed steps vary heavily based on how the components were set up previously. As a result, this section can only highlight the most important caveats and things to know, while the concrete migration steps must be figured out individually based on the existing installation.
Please test your migration procedure thoroughly. Note that in some cases it can be easier to set up a fresh landscape with
gardener-operator
, restore the ETCD data, switch the DNS records, and issue new credentials for all clients.
Please make sure that you configure all your desired fields in the Garden
resource.
ETCD
gardener-operator
leverages etcd-druid
for managing the virtual-garden-etcd-main
and virtual-garden-etcd-events
, similar to how shoot cluster control planes are handled.
The PersistentVolumeClaim
names differ slightly - for virtual-garden-etcd-events
it’s virtual-garden-etcd-events-virtual-garden-etcd-events-0
, while for virtual-garden-etcd-main
it’s main-virtual-garden-etcd-virtual-garden-etcd-main-0
.
The easiest approach for the migration is to make your existing ETCD volumes follow the same naming scheme.
Alternatively, backup your data, let gardener-operator
take over ETCD, and then restore your data to the new volume.
The backup bucket must be created separately, and its name as well as the respective credentials must be provided via the Garden
resource in .spec.virtualCluster.etcd.main.backup
.
virtual-garden-kube-apiserver
Deployment
gardener-operator
deploys a virtual-garden-kube-apiserver
into the runtime cluster.
This virtual-garden-kube-apiserver
spans a new cluster, called the virtual cluster.
There are a few certificates and other credentials that should not change during the migration.
You have to prepare the environment accordingly by leveraging the secret’s manager capabilities.
- The existing Cluster CA
Secret
should be labeled withsecrets-manager-use-data-for-name=ca
. - The existing Client CA
Secret
should be labeled withsecrets-manager-use-data-for-name=ca-client
. - The existing Front Proxy CA
Secret
should be labeled withsecrets-manager-use-data-for-name=ca-front-proxy
. - The existing Service Account Signing Key
Secret
should be labeled withsecrets-manager-use-data-for-name=service-account-key
. - The existing ETCD Encryption Key
Secret
should be labeled withsecrets-manager-use-data-for-name=kube-apiserver-etcd-encryption-key
.
virtual-garden-kube-apiserver
Exposure
The virtual-garden-kube-apiserver
is exposed via a dedicated istio-ingressgateway
deployed to namespace virtual-garden-istio-ingress
.
The virtual-garden-kube-apiserver
Service
in the garden
namespace is only of type ClusterIP
.
Consequently, DNS records for this API server must target the load balancer IP of the istio-ingressgateway
.
Virtual Garden Kubeconfig
gardener-operator
does not generate any static token or likewise for access to the virtual cluster.
Ideally, human users access it via OIDC only.
Alternatively, you can create an auto-rotated token that you can use for automation like CI/CD pipelines:
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: shoot-access-virtual-garden
namespace: garden
labels:
resources.gardener.cloud/purpose: token-requestor
annotations:
serviceaccount.resources.gardener.cloud/name: virtual-garden-user
serviceaccount.resources.gardener.cloud/namespace: kube-system
serviceaccount.resources.gardener.cloud/token-expiration-duration: 3h
---
apiVersion: v1
kind: Secret
metadata:
name: managedresource-virtual-garden-access
namespace: garden
type: Opaque
stringData:
clusterrolebinding____gardener.cloud.virtual-garden-access.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gardener.cloud.sap:virtual-garden
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: virtual-garden-user
namespace: kube-system
---
apiVersion: resources.gardener.cloud/v1alpha1
kind: ManagedResource
metadata:
name: virtual-garden-access
namespace: garden
spec:
secretRefs:
- name: managedresource-virtual-garden-access
The shoot-access-virtual-garden
Secret
will get a .data.token
field which can be used to authenticate against the virtual garden cluster.
See also this document for more information about the TokenRequestor
.
gardener-apiserver
Similar to the virtual-garden-kube-apiserver
, the gardener-apiserver
also uses a few certificates and other credentials that should not change during the migration.
Again, you have to prepare the environment accordingly by leveraging the secret’s manager capabilities.
- The existing ETCD Encryption Key
Secret
should be labeled withsecrets-manager-use-data-for-name=gardener-apiserver-etcd-encryption-key
.
Also note that gardener-operator
manages the Service
and Endpoints
resources for the gardener-apiserver
in the virtual cluster within the kube-system
namespace (garden-setup
uses the garden
namespace).
Local Development
The easiest setup is using a local KinD cluster and the Skaffold based approach to deploy and develop the gardener-operator
.
Setting Up the KinD Cluster (runtime cluster)
make kind-operator-up
This command sets up a new KinD cluster named gardener-local
and stores the kubeconfig in the ./example/gardener-local/kind/operator/kubeconfig
file.
It might be helpful to copy this file to
$HOME/.kube/config
, since you will need to target this KinD cluster multiple times. Alternatively, make sure to set yourKUBECONFIG
environment variable to./example/gardener-local/kind/operator/kubeconfig
for all future steps viaexport KUBECONFIG=$PWD/example/gardener-local/kind/operator/kubeconfig
.
All the following steps assume that you are using this kubeconfig.
Setting Up Gardener Operator
make operator-up
This will first build the base images (which might take a bit if you do it for the first time). Afterwards, the Gardener Operator resources will be deployed into the cluster.
Developing Gardener Operator (Optional)
make operator-dev
This is similar to make operator-up
but additionally starts a skaffold dev loop.
After the initial deployment, skaffold starts watching source files.
Once it has detected changes, press any key to trigger a new build and deployment of the changed components.
Debugging Gardener Operator (Optional)
make operator-debug
This is similar to make gardener-debug
but for Gardener Operator component. Please check Debugging Gardener for details.
Creating a Garden
In order to create a garden, just run:
kubectl apply -f example/operator/20-garden.yaml
You can wait for the Garden
to be ready by running:
./hack/usage/wait-for.sh garden local Reconciled
Alternatively, you can run kubectl get garden
and wait for the RECONCILED
status to reach True
:
NAME RECONCILED AGE
garden Progressing 1s
(Optional): Instead of creating above Garden
resource manually, you could execute the e2e tests by running:
make test-e2e-local-operator
Accessing the Virtual Garden Cluster
⚠️ Please note that in this setup, the virtual garden cluster is not accessible by default when you download the kubeconfig and try to communicate with it.
The reason is that your host most probably cannot resolve the DNS name of the cluster.
Hence, if you want to access the virtual garden cluster, you have to run the following command which will extend your /etc/hosts
file with the required information to make the DNS names resolvable:
cat <<EOF | sudo tee -a /etc/hosts
# Manually created to access local Gardener virtual garden cluster.
# TODO: Remove this again when the virtual garden cluster access is no longer required.
127.0.0.1 api.virtual-garden.local.gardener.cloud
EOF
To access the virtual garden, you can acquire a kubeconfig
by
kubectl -n garden get secret gardener -o jsonpath={.data.kubeconfig} | base64 -d > /tmp/virtual-garden-kubeconfig
kubectl --kubeconfig /tmp/virtual-garden-kubeconfig get namespaces
Note that this kubeconfig uses a token that has validity of 12h
only, hence it might expire and causing you to re-download the kubeconfig.
Deleting the Garden
./hack/usage/delete garden local
Tear Down the Gardener Operator Environment
make operator-down
make kind-operator-down
1.2.12 - Resource Manager
Gardener Resource Manager
Initially, the gardener-resource-manager
was a project similar to the kube-addon-manager.
It manages Kubernetes resources in a target cluster which means that it creates, updates, and deletes them.
Also, it makes sure that manual modifications to these resources are reconciled back to the desired state.
In the Gardener project we were using the kube-addon-manager since more than two years.
While we have progressed with our extensibility story (moving cloud providers out-of-tree), we had decided that the kube-addon-manager is no longer suitable for this use-case.
The problem with it is that it needs to have its managed resources on its file system.
This requires storing the resources in ConfigMap
s or Secret
s and mounting them to the kube-addon-manager pod during deployment time.
The gardener-resource-manager
uses CustomResourceDefinition
s which allows to dynamically add, change, and remove resources with immediate action and without the need to reconfigure the volume mounts/restarting the pod.
Meanwhile, the gardener-resource-manager
has evolved to a more generic component comprising several controllers and webhook handlers.
It is deployed by gardenlet once per seed (in the garden
namespace) and once per shoot (in the respective shoot namespaces in the seed).
Component Configuration
Similar to other Gardener components, the gardener-resource-manager
uses a so-called component configuration file.
It allows specifying certain central settings like log level and formatting, client connection configuration, server ports and bind addresses, etc.
In addition, controllers and webhooks can be configured and sometimes even disabled.
Note that the very basic ManagedResource
, secret, and health controllers cannot be disabled.
You can find an example configuration file here.
Controllers
ManagedResource
Controller
This controller watches custom objects called ManagedResource
s in the resources.gardener.cloud/v1alpha1
API group.
These objects contain references to secrets, which itself contain the resources to be managed.
The reason why a Secret
is used to store the resources is that they could contain confidential information like credentials.
---
apiVersion: v1
kind: Secret
metadata:
name: managedresource-example1
namespace: default
type: Opaque
data:
objects.yaml: YXBpVmVyc2lvbjogdjEKa2luZDogQ29uZmlnTWFwCm1ldGFkYXRhOgogIG5hbWU6IHRlc3QtMTIzNAogIG5hbWVzcGFjZTogZGVmYXVsdAotLS0KYXBpVmVyc2lvbjogdjEKa2luZDogQ29uZmlnTWFwCm1ldGFkYXRhOgogIG5hbWU6IHRlc3QtNTY3OAogIG5hbWVzcGFjZTogZGVmYXVsdAo=
# apiVersion: v1
# kind: ConfigMap
# metadata:
# name: test-1234
# namespace: default
# ---
# apiVersion: v1
# kind: ConfigMap
# metadata:
# name: test-5678
# namespace: default
---
apiVersion: resources.gardener.cloud/v1alpha1
kind: ManagedResource
metadata:
name: example
namespace: default
spec:
secretRefs:
- name: managedresource-example1
In the above example, the controller creates two ConfigMap
s in the default
namespace.
When a user is manually modifying them, they will be reconciled back to the desired state stored in the managedresource-example
secret.
It is also possible to inject labels into all the resources:
---
apiVersion: v1
kind: Secret
metadata:
name: managedresource-example2
namespace: default
type: Opaque
data:
other-objects.yaml: YXBpVmVyc2lvbjogYXBwcy92MSAjIGZvciB2ZXJzaW9ucyBiZWZvcmUgMS45LjAgdXNlIGFwcHMvdjFiZXRhMgpraW5kOiBEZXBsb3ltZW50Cm1ldGFkYXRhOgogIG5hbWU6IG5naW54LWRlcGxveW1lbnQKc3BlYzoKICBzZWxlY3RvcjoKICAgIG1hdGNoTGFiZWxzOgogICAgICBhcHA6IG5naW54CiAgcmVwbGljYXM6IDIgIyB0ZWxscyBkZXBsb3ltZW50IHRvIHJ1biAyIHBvZHMgbWF0Y2hpbmcgdGhlIHRlbXBsYXRlCiAgdGVtcGxhdGU6CiAgICBtZXRhZGF0YToKICAgICAgbGFiZWxzOgogICAgICAgIGFwcDogbmdpbngKICAgIHNwZWM6CiAgICAgIGNvbnRhaW5lcnM6CiAgICAgIC0gbmFtZTogbmdpbngKICAgICAgICBpbWFnZTogbmdpbng6MS43LjkKICAgICAgICBwb3J0czoKICAgICAgICAtIGNvbnRhaW5lclBvcnQ6IDgwCg==
# apiVersion: apps/v1
# kind: Deployment
# metadata:
# name: nginx-deployment
# spec:
# selector:
# matchLabels:
# app: nginx
# replicas: 2 # tells deployment to run 2 pods matching the template
# template:
# metadata:
# labels:
# app: nginx
# spec:
# containers:
# - name: nginx
# image: nginx:1.7.9
# ports:
# - containerPort: 80
---
apiVersion: resources.gardener.cloud/v1alpha1
kind: ManagedResource
metadata:
name: example
namespace: default
spec:
secretRefs:
- name: managedresource-example2
injectLabels:
foo: bar
In this example, the label foo=bar
will be injected into the Deployment
, as well as into all created ReplicaSet
s and Pod
s.
Preventing Reconciliations
If a ManagedResource
is annotated with resources.gardener.cloud/ignore=true
, then it will be skipped entirely by the controller (no reconciliations or deletions of managed resources at all).
However, when the ManagedResource
itself is deleted (for example when a shoot is deleted), then the annotation is not respected and all resources will be deleted as usual.
This feature can be helpful to temporarily patch/change resources managed as part of such ManagedResource
.
Condition checks will be skipped for such ManagedResource
s.
Modes
The gardener-resource-manager
can manage a resource in the following supported modes:
Ignore
- The corresponding resource is removed from the
ManagedResource
status (.status.resources
). No action is performed on the cluster. - The resource is no longer “managed” (updated or deleted).
- The primary use case is a migration of a resource from one
ManagedResource
to another one.
- The corresponding resource is removed from the
The mode for a resource can be specified with the resources.gardener.cloud/mode
annotation. The annotation should be specified in the encoded resource manifest in the Secret that is referenced by the ManagedResource
.
Skipping Health Check
If a resource in the ManagedResource
is annotated with resources.gardener.cloud/skip-health-check=true
, then the resource will be skipped during health checks by the health controller. The ManagedResource
conditions will not reflect the health condition of this resource anymore. The ResourcesProgressing
condition will also be set to False
.
Resource Class
By default, the gardener-resource-manager
controller watches for ManagedResource
s in all namespaces.
The .sourceClientConnection.namespace
field in the component configuration restricts the watch to ManagedResource
s in a single namespace only.
Note that this setting also affects all other controllers and webhooks since it’s a central configuration.
A ManagedResource
has an optional .spec.class
field that allows it to indicate that it belongs to a given class of resources.
The .controllers.resourceClass
field in the component configuration restricts the watch to ManagedResource
s with the given .spec.class
.
A default class is assumed if no class is specified.
Conditions
A ManagedResource
has a ManagedResourceStatus
, which has an array of Conditions. Conditions currently include:
Condition | Description |
---|---|
ResourcesApplied | True if all resources are applied to the target cluster |
ResourcesHealthy | True if all resources are present and healthy |
ResourcesProgressing | False if all resources have been fully rolled out |
ResourcesApplied
may be False
when:
- the resource
apiVersion
is not known to the target cluster - the resource spec is invalid (for example the label value does not match the required regex for it)
- …
ResourcesHealthy
may be False
when:
- the resource is not found
- the resource is a Deployment and the Deployment does not have the minimum availability.
- …
ResourcesProgressing
may be True
when:
- a
Deployment
,StatefulSet
orDaemonSet
has not been fully rolled out yet, i.e. not all replicas have been updated with the latest changes tospec.template
. - there are still old
Pod
s belonging to an olderReplicaSet
of aDeployment
which are not terminated yet.
Each Kubernetes resources has different notion for being healthy. For example, a Deployment is considered healthy if the controller observed its current revision and if the number of updated replicas is equal to the number of replicas.
The following status.conditions
section describes a healthy ManagedResource
:
conditions:
- lastTransitionTime: "2022-05-03T10:55:39Z"
lastUpdateTime: "2022-05-03T10:55:39Z"
message: All resources are healthy.
reason: ResourcesHealthy
status: "True"
type: ResourcesHealthy
- lastTransitionTime: "2022-05-03T10:55:36Z"
lastUpdateTime: "2022-05-03T10:55:36Z"
message: All resources have been fully rolled out.
reason: ResourcesRolledOut
status: "False"
type: ResourcesProgressing
- lastTransitionTime: "2022-05-03T10:55:18Z"
lastUpdateTime: "2022-05-03T10:55:18Z"
message: All resources are applied.
reason: ApplySucceeded
status: "True"
type: ResourcesApplied
Ignoring Updates
In some cases, it is not desirable to update or re-apply some of the cluster components (for example, if customization is required or needs to be applied by the end-user). For these resources, the annotation “resources.gardener.cloud/ignore” needs to be set to “true” or a truthy value (Truthy values are “1”, “t”, “T”, “true”, “TRUE”, “True”) in the corresponding managed resource secrets. This can be done from the components that create the managed resource secrets, for example Gardener extensions or Gardener. Once this is done, the resource will be initially created and later ignored during reconciliation.
Finalizing Deletion of Resources After Grace Period
When a ManagedResource
is deleted, the controller deletes all managed resources from the target cluster.
In case the resources still have entries in their .metadata.finalizers[]
list, they will remain stuck in the system until another entity removes the finalizers.
If you want the controller to forcefully finalize the deletion after some grace period (i.e., setting .metadata.finalizers=null
), you can annotate the managed resources with resources.gardener.cloud/finalize-deletion-after=<duration>
, e.g., resources.gardener.cloud/finalize-deletion-after=1h
.
Preserving replicas
or resources
in Workload Resources
The objects which are part of the ManagedResource
can be annotated with:
resources.gardener.cloud/preserve-replicas=true
in case the.spec.replicas
field of workload resources likeDeployment
s,StatefulSet
s, etc., shall be preserved during updates.resources.gardener.cloud/preserve-resources=true
in case the.spec.containers[*].resources
fields of all containers of workload resources likeDeployment
s,StatefulSet
s, etc., shall be preserved during updates.
This can be useful if there are non-standard horizontal/vertical auto-scaling mechanisms in place. Standard mechanisms like
HorizontalPodAutoscaler
orVerticalPodAutoscaler
will be auto-recognized bygardener-resource-manager
, i.e., in such cases the annotations are not needed.
Origin
All the objects managed by the resource manager get a dedicated annotation
resources.gardener.cloud/origin
describing the ManagedResource
object that describes
this object. The default format is <namespace>/<objectname>
.
In multi-cluster scenarios (the ManagedResource
objects are maintained in a
cluster different from the one the described objects are managed), it might
be useful to include the cluster identity, as well.
This can be enforced by setting the .controllers.clusterID
field in the component configuration.
Here, several possibilities are supported:
- given a direct value: use this as id for the source cluster.
<cluster>
: read the cluster identity from acluster-identity
config map in thekube-system
namespace (attributecluster-identity
). This is automatically maintained in all clusters managed or involved in a gardener landscape.<default>
: try to read the cluster identity from the config map. If not found, no identity is used.- empty string: no cluster identity is used (completely cluster local scenarios).
By default, cluster id is not used. If cluster id is specified, the format is <cluster id>:<namespace>/<objectname>
.
In addition to the origin annotation, all objects managed by the resource manager get a dedicated label resources.gardener.cloud/managed-by
. This label can be used to describe these objects with a selector. By default it is set to “gardener”, but this can be overwritten by setting the .conrollers.managedResources.managedByLabelValue
field in the component configuration.
Garbage Collector For Immutable ConfigMap
s/Secret
s
In Kubernetes, workload resources (e.g., Pod
s) can mount ConfigMap
s or Secret
s or reference them via environment variables in containers.
Typically, when the content of such a ConfigMap
/Secret
gets changed, then the respective workload is usually not dynamically reloading the configuration, i.e., a restart is required.
The most commonly used approach is probably having the so-called checksum annotations in the pod template, which makes Kubernetes recreate the pod if the checksum changes.
However, it has the downside that old, still running versions of the workload might not be able to properly work with the already updated content in the ConfigMap
/Secret
, potentially causing application outages.
In order to protect users from such outages (and also to improve the performance of the cluster), the Kubernetes community provides the “immutable ConfigMap
s/Secret
s feature”.
Enabling immutability requires ConfigMap
s/Secret
s to have unique names.
Having unique names requires the client to delete ConfigMap
s/Secret
s no longer in use.
In order to provide a similarly lightweight experience for clients (compared to the well-established checksum annotation approach), the gardener-resource-manager
features an optional garbage collector controller (disabled by default).
The purpose of this controller is cleaning up such immutable ConfigMap
s/Secret
s if they are no longer in use.
How Does the Garbage Collector Work?
The following algorithm is implemented in the GC controller:
- List all
ConfigMap
s andSecret
s labeled withresources.gardener.cloud/garbage-collectable-reference=true
. - List all
Deployment
s,StatefulSet
s,DaemonSet
s,Job
s,CronJob
s,Pod
s,ManagedResource
s and for each of them:- iterate over the
.metadata.annotations
and for each of them:- If the annotation key follows the
reference.resources.gardener.cloud/{configmap,secret}-<hash>
scheme and the value equals<name>
, then consider it as “in-use”.
- If the annotation key follows the
- iterate over the
- Delete all
ConfigMap
s andSecret
s not considered as “in-use”.
Consequently, clients need to:
Create immutable
ConfigMap
s/Secret
s with unique names (e.g., a checksum suffix based on the.data
).Label such
ConfigMap
s/Secret
s withresources.gardener.cloud/garbage-collectable-reference=true
.Annotate their workload resources with
reference.resources.gardener.cloud/{configmap,secret}-<hash>=<name>
for allConfigMap
s/Secret
s used by the containers of the respectivePod
s.⚠️ Add such annotations to
.metadata.annotations
, as well as to all templates of other resources (e.g.,.spec.template.metadata.annotations
inDeployment
s or.spec.jobTemplate.metadata.annotations
and.spec.jobTemplate.spec.template.metadata.annotations
forCronJob
s. This ensures that the GC controller does not unintentionally considerConfigMap
s/Secret
s as “not in use” just because there isn’t aPod
referencing them anymore (e.g., they could still be used by aDeployment
scaled down to0
).
ℹ️ For the last step, there is a helper function InjectAnnotations
in the pkg/controller/garbagecollector/references
, which you can use for your convenience.
Example:
---
apiVersion: v1
kind: ConfigMap
metadata:
name: test-1234
namespace: default
labels:
resources.gardener.cloud/garbage-collectable-reference: "true"
---
apiVersion: v1
kind: ConfigMap
metadata:
name: test-5678
namespace: default
labels:
resources.gardener.cloud/garbage-collectable-reference: "true"
---
apiVersion: v1
kind: Pod
metadata:
name: example
namespace: default
annotations:
reference.resources.gardener.cloud/configmap-82a3537f: test-5678
spec:
containers:
- name: nginx
image: nginx:1.14.2
terminationGracePeriodSeconds: 2
The GC controller would delete the ConfigMap/test-1234
because it is considered as not “in-use”.
ℹ️ If the GC controller is activated then the ManagedResource
controller will no longer delete ConfigMap
s/Secret
s having the above label.
How to Activate the Garbage Collector?
The GC controller can be activated by setting the .controllers.garbageCollector.enabled
field to true
in the component configuration.
TokenInvalidator Controller
The Kubernetes community is slowly transitioning from static ServiceAccount
token Secret
s to ServiceAccount
Token Volume Projection.
Typically, when you create a ServiceAccount
apiVersion: v1
kind: ServiceAccount
metadata:
name: default
then the serviceaccount-token
controller (part of kube-controller-manager
) auto-generates a Secret
with a static token:
apiVersion: v1
kind: Secret
metadata:
annotations:
kubernetes.io/service-account.name: default
kubernetes.io/service-account.uid: 86e98645-2e05-11e9-863a-b2d4d086dd5a)
name: default-token-ntxs9
type: kubernetes.io/service-account-token
data:
ca.crt: base64(cluster-ca-cert)
namespace: base64(namespace)
token: base64(static-jwt-token)
Unfortunately, when using ServiceAccount
Token Volume Projection in a Pod
, this static token is actually not used at all:
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
serviceAccountName: default
containers:
- image: nginx
name: nginx
volumeMounts:
- mountPath: /var/run/secrets/tokens
name: token
volumes:
- name: token
projected:
sources:
- serviceAccountToken:
path: token
expirationSeconds: 7200
While the Pod
is now using an expiring and auto-rotated token, the static token is still generated and valid.
There is neither a way of preventing kube-controller-manager
to generate such static tokens, nor a way to proactively remove or invalidate them:
- https://github.com/kubernetes/kubernetes/issues/77599
- https://github.com/kubernetes/kubernetes/issues/77600
Disabling the serviceaccount-token
controller is an option, however, especially in the Gardener context it may either break end-users or it may not even be possible to control such settings.
Also, even if a future Kubernetes version supports native configuration of the above behaviour, Gardener still supports older versions which won’t get such features but need a solution as well.
This is where the TokenInvalidator comes into play:
Since it is not possible to prevent kube-controller-manager
from generating static ServiceAccount
Secret
s, the TokenInvalidator is, as its name suggests, just invalidating these tokens.
It considers all such Secret
s belonging to ServiceAccount
s with .automountServiceAccountToken=false
.
By default, all namespaces in the target cluster are watched, however, this can be configured by specifying the .targetClientConnection.namespace
field in the component configuration.
Note that this setting also affects all other controllers and webhooks since it’s a central configuration.
apiVersion: v1
kind: ServiceAccount
metadata:
name: my-serviceaccount
automountServiceAccountToken: false
This will result in a static ServiceAccount
token secret whose token
value is invalid:
apiVersion: v1
kind: Secret
metadata:
annotations:
kubernetes.io/service-account.name: my-serviceaccount
kubernetes.io/service-account.uid: 86e98645-2e05-11e9-863a-b2d4d086dd5a
name: my-serviceaccount-token-ntxs9
type: kubernetes.io/service-account-token
data:
ca.crt: base64(cluster-ca-cert)
namespace: base64(namespace)
token: AAAA
Any attempt to regenerate the token or creating a new such secret will again make the component invalidating it.
You can opt-out of this behaviour for
ServiceAccount
s setting.automountServiceAccountToken=false
by labeling them withtoken-invalidator.resources.gardener.cloud/skip=true
.
In order to enable the TokenInvalidator you have to set both .controllers.tokenValidator.enabled=true
and .webhooks.tokenValidator.enabled=true
in the component configuration.
The below graphic shows an overview of the Token Invalidator for Service account secrets in the Shoot cluster.
TokenRequestor Controller
This controller provides the service to create and auto-renew tokens via the TokenRequest
API.
It provides a functionality similar to the kubelet’s Service Account Token Volume Projection. It was created to handle the special case of issuing tokens to pods that run in a different cluster than the API server they communicate with (hence, using the native token volume projection feature is not possible).
The controller differentiates between source cluster
and target cluster
.
The source cluster
hosts the gardener-resource-manager
pod. Secrets in this cluster are watched and modified by the controller.
The target cluster
can be configured to point to another cluster. The existence of ServiceAccounts are ensured and token requests are issued against the target.
When the gardener-resource-manager
is deployed next to the Shoot’s controlplane in the Seed, the source cluster
is the Seed while the target cluster
points to the Shoot.
Reconciliation Loop
This controller reconciles Secret
s in all namespaces in the source cluster with the label: resources.gardener.cloud/purpose=token-requestor
.
See this YAML file for an example of the secret.
The controller ensures a ServiceAccount
exists in the target cluster as specified in the annotations of the Secret
in the source cluster:
serviceaccount.resources.gardener.cloud/name: <sa-name>
serviceaccount.resources.gardener.cloud/namespace: <sa-namespace>
The requested tokens will act with the privileges which are assigned to this ServiceAccount
.
The controller will then request a token via the TokenRequest
API and populate it into the .data.token
field to the Secret
in the source cluster.
Alternatively, the client can provide a raw kubeconfig (in YAML or JSON format) via the Secret
’s .data.kubeconfig
field.
The controller will then populate the requested token in the kubeconfig for the user used in the .current-context
.
For example, if .data.kubeconfig
is
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: AAAA
server: some-server-url
name: shoot--foo--bar
contexts:
- context:
cluster: shoot--foo--bar
user: shoot--foo--bar-token
name: shoot--foo--bar
current-context: shoot--foo--bar
kind: Config
preferences: {}
users:
- name: shoot--foo--bar-token
user:
token: ""
then the .users[0].user.token
field of the kubeconfig will be updated accordingly.
The controller also adds an annotation to the Secret
to keep track when to renew the token before it expires.
By default, the tokens are issued to expire after 12 hours. The expiration time can be set with the following annotation:
serviceaccount.resources.gardener.cloud/token-expiration-duration: 6h
It automatically renews once 80% of the lifetime is reached, or after 24h
.
Optionally, the controller can also populate the token into a Secret
in the target cluster. This can be requested by annotating the Secret
in the source cluster with:
token-requestor.resources.gardener.cloud/target-secret-name: "foo"
token-requestor.resources.gardener.cloud/target-secret-namespace: "bar"
Overall, the TokenRequestor controller provides credentials with limited lifetime (JWT tokens) used by Shoot control plane components running in the Seed to talk to the Shoot API Server. Please see the graphic below:
ℹ️ Generally, the controller can run with multiple instances in different components. For example,
gardener-resource-manager
might run theTokenRequestor
controller, butgardenlet
might run it, too. In order to differentiate which instance of the controller is responsible for aSecret
, it can be labeled withresources.gardener.cloud/class=<class>
. The<class>
must be configured in the respective controller, otherwise it will be responsible for allSecret
s no matter whether they have the label or not.
Kubelet Server CertificateSigningRequest
Approver
Gardener configures the kubelets such that they request two certificates via the CertificateSigningRequest
API:
- client certificate for communicating with the
kube-apiserver
- server certificate for serving its HTTPS server
For client certificates, the kubernetes.io/kube-apiserver-client-kubelet
signer is used (see Certificate Signing Requests for more details).
The kube-controller-manager
’s csrapprover
controller is responsible for auto-approving such CertificateSigningRequest
s so that the respective certificates can be issued.
For server certificates, the kubernetes.io/kubelet-serving
signer is used.
Unfortunately, the kube-controller-manager
is not able to auto-approve such CertificateSigningRequest
s (see kubernetes/kubernetes#73356 for details).
That’s the motivation for having this controller as part of gardener-resource-manager
.
It watches CertificateSigningRequest
s with the kubernetes.io/kubelet-serving
signer and auto-approves them when all the following conditions are met:
- The
.spec.username
is prefixed withsystem:node:
. - There must be at least one DNS name or IP address as part of the certificate SANs.
- The common name in the CSR must match the
.spec.username
. - The organization in the CSR must only contain
system:nodes
. - There must be a
Node
object with the same name in the shoot cluster. - There must be exactly one
Machine
for the node in the seed cluster. - The DNS names part of the SANs must be equal to all
.status.addresses[]
of typeHostname
in theNode
. - The IP addresses part of the SANs must be equal to all
.status.addresses[]
of typeInternalIP
in theNode
.
If any one of these requirements is violated, the CertificateSigningRequest
will be denied.
Otherwise, once approved, the kube-controller-manager
’s csrsigner
controller will issue the requested certificate.
NetworkPolicy
Controller
This controller reconciles Service
s with a non-empty .spec.podSelector
.
It creates two NetworkPolicy
s for each port in the .spec.ports[]
list.
For example:
apiVersion: v1
kind: Service
metadata:
name: gardener-resource-manager
namespace: a
spec:
selector:
app: gardener-resource-manager
ports:
- name: server
port: 443
protocol: TCP
targetPort: 10250
leads to
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows ingress TCP traffic to port 10250 for pods
selected by the a/gardener-resource-manager service selector from pods running
in namespace a labeled with map[networking.resources.gardener.cloud/to-gardener-resource-manager-tcp-10250:allowed].
name: ingress-to-gardener-resource-manager-tcp-10250
namespace: a
spec:
ingress:
- from:
- podSelector:
matchLabels:
networking.resources.gardener.cloud/to-gardener-resource-manager-tcp-10250: allowed
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
app: gardener-resource-manager
policyTypes:
- Ingress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows egress TCP traffic to port 10250 from pods
running in namespace a labeled with map[networking.resources.gardener.cloud/to-gardener-resource-manager-tcp-10250:allowed]
to pods selected by the a/gardener-resource-manager service selector.
name: egress-to-gardener-resource-manager-tcp-10250
namespace: a
spec:
egress:
- to:
- podSelector:
matchLabels:
app: gardener-resource-manager
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
networking.resources.gardener.cloud/to-gardener-resource-manager-tcp-10250: allowed
policyTypes:
- Egress
A component that initiates the connection to gardener-resource-manager
’s tcp/10250
port can now be labeled with networking.resources.gardener.cloud/to-gardener-resource-manager-tcp-10250=allowed
.
That’s all this component needs to do - it does not need to create any NetworkPolicy
s itself.
Cross-Namespace Communication
Apart from this “simple” case where both communicating components run in the same namespace a
, there is also the cross-namespace communication case.
With above example, let’s say there are components running in another namespace b
, and they would like to initiate the communication with gardener-resource-manager
in a
.
To cover this scenario, the Service
can be annotated with networking.resources.gardener.cloud/namespace-selectors='[{"matchLabels":{"kubernetes.io/metadata.name":"b"}}]'
.
Note that you can specify multiple namespace selectors in this annotation which are OR-ed.
This will make the controller create additional NetworkPolicy
s as follows:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows ingress TCP traffic to port 10250 for pods selected
by the a/gardener-resource-manager service selector from pods running in namespace b
labeled with map[networking.resources.gardener.cloud/to-a-gardener-resource-manager-tcp-10250:allowed].
name: ingress-to-gardener-resource-manager-tcp-10250-from-b
namespace: a
spec:
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: b
podSelector:
matchLabels:
networking.resources.gardener.cloud/to-a-gardener-resource-manager-tcp-10250: allowed
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
app: gardener-resource-manager
policyTypes:
- Ingress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows egress TCP traffic to port 10250 from pods running in
namespace b labeled with map[networking.resources.gardener.cloud/to-a-gardener-resource-manager-tcp-10250:allowed]
to pods selected by the a/gardener-resource-manager service selector.
name: egress-to-a-gardener-resource-manager-tcp-10250
namespace: b
spec:
egress:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: a
podSelector:
matchLabels:
app: gardener-resource-manager
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
networking.resources.gardener.cloud/to-a-gardener-resource-manager-tcp-10250: allowed
policyTypes:
- Egress
The components in namespace b
now need to be labeled with networking.resources.gardener.cloud/to-a-gardener-resource-manager-tcp-10250=allowed
, but that’s already it.
Obviously, this approach also works for namespace selectors different from
kubernetes.io/metadata.name
to cover scenarios where the namespace name is not known upfront or where multiple namespaces with a similar label are relevant. The controller creates two dedicated policies for each namespace matching the selectors.
Service
Targets In Multiple Namespaces
Finally, let’s say there is a Service
called example
which exists in different namespaces whose names are not static (e.g., foo-1
, foo-2
), and a component in namespace bar
wants to initiate connections with all of them.
The example
Service
s in these namespaces can now be annotated with networking.resources.gardener.cloud/namespace-selectors='[{"matchLabels":{"kubernetes.io/metadata.name":"bar"}}]'
.
As a consequence, the component in namespace bar
now needs to be labeled with networking.resources.gardener.cloud/to-foo-1-example-tcp-8080=allowed
, networking.resources.gardener.cloud/to-foo-2-example-tcp-8080=allowed
, etc.
This approach does not work in practice, however, since the namespace names are neither static nor known upfront.
To overcome this, it is possible to specify an alias for the concrete namespace in the pod label selector via the networking.resources.gardener.cloud/pod-label-selector-namespace-alias
annotation.
In above case, the example
Service
in the foo-*
namespaces could be annotated with networking.resources.gardener.cloud/pod-label-selector-namespace-alias=all-foos
.
This would modify the label selector in all NetworkPolicy
s related to cross-namespace communication, i.e. instead of networking.resources.gardener.cloud/to-foo-{1,2,...}-example-tcp-8080=allowed
, networking.resources.gardener.cloud/to-all-foos-example-tcp-8080=allowed
would be used.
Now the component in namespace bar
only needs this single label and is able to talk to all such Service
s in the different namespaces.
Real-world examples for this scenario are the
kube-apiserver
Service
(which exists in all shoot namespaces), or theistio-ingressgateway
Service
(which exists in allistio-ingress*
namespaces). In both cases, the names of the namespaces are not statically known and depend on user input.
Overwriting The Pod Selector Label
For a component which initiates the connection to many other components, it’s sometimes impractical to specify all the respective labels in its pod template.
For example, let’s say a component foo
talks to bar{0..9}
on ports tcp/808{0..9}
.
foo
would need to have the ten networking.resources.gardener.cloud/to-bar{0..9}-tcp-808{0..9}=allowed
labels.
As an alternative and to simplify this, it is also possible to annotate the targeted Service
s with networking.resources.gardener.cloud/from-<some-alias>-allowed-ports
.
For our example, <some-alias>
could be all-bars
.
As a result, component foo
just needs to have the label networking.resources.gardener.cloud/to-all-bars=allowed
instead of all the other ten explicit labels.
⚠️ Note that this also requires to specify the list of allowed container ports as annotation value since the pod selector label will no longer be specific for a dedicated service/port.
For our example, the Service
for barX
with X
in {0..9}
needs to be annotated with networking.resources.gardener.cloud/from-all-bars-allowed-ports=[{"port":808X,"protocol":"TCP"}]
in addition.
Real-world examples for this scenario are the
Prometheis
in seed clusters which initiate the communication to a lot of components in order to scrape their metrics. Another example is thekube-apiserver
which initiates the communication to webhook servers (potentially of extension components that are not known by Gardener itself).
Ingress From Everywhere
All above scenarios are about components initiating connections to some targets. However, some components also receive incoming traffic from sources outside the cluster. This traffic requires adequate ingress policies so that it can be allowed.
To cover this scenario, the Service
can be annotated with networking.resources.gardener.cloud/from-world-to-ports=[{"port":"10250","protocol":"TCP"}]
.
As a result, the controller creates the following NetworkPolicy
:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: ingress-to-gardener-resource-manager-from-world
namespace: a
spec:
ingress:
- from:
- namespaceSelector: {}
podSelector: {}
- ipBlock:
cidr: 0.0.0.0/0
- ipBlock:
cidr: ::/0
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
app: gardener-resource-manager
policyTypes:
- Ingress
The respective pods don’t need any additional labels.
If the annotation’s value is empty ([]
) then all ports are allowed.
Services Exposed via Ingress
Resources
The controller can optionally be configured to watch Ingress
resources by specifying the pod and namespace selectors for the Ingress
controller.
If this information is provided, it automatically creates NetworkPolicy
resources allowing the respective ingress/egress traffic for the backends exposed by the Ingress
es.
This way, neither custom NetworkPolicy
s nor custom labels must be provided.
The needed configuration is part of the component configuration:
controllers:
networkPolicy:
enabled: true
concurrentSyncs: 5
# namespaceSelectors:
# - matchLabels:
# kubernetes.io/metadata.name: default
ingressControllerSelector:
namespace: default
podSelector:
matchLabels:
foo: bar
As an example, let’s assume that above gardener-resource-manager
Service
was exposed via the following Ingress
resource:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: gardener-resource-manager
namespace: a
spec:
rules:
- host: grm.foo.example.com
http:
paths:
- backend:
service:
name: gardener-resource-manager
port:
number: 443
path: /
pathType: Prefix
As a result, the controller would automatically create the following NetworkPolicy
s:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows ingress TCP traffic to port 10250 for pods
selected by the a/gardener-resource-manager service selector from ingress controller
pods running in the default namespace labeled with map[foo:bar].
name: ingress-to-gardener-resource-manager-tcp-10250-from-ingress-controller
namespace: a
spec:
ingress:
- from:
- podSelector:
matchLabels:
foo: bar
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: default
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
app: gardener-resource-manager
policyTypes:
- Ingress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
annotations:
gardener.cloud/description: Allows egress TCP traffic to port 10250 from pods
running in the default namespace labeled with map[foo:bar] to pods selected by
the a/gardener-resource-manager service selector.
name: egress-to-a-gardener-resource-manager-tcp-10250-from-ingress-controller
namespace: default
spec:
egress:
- to:
- podSelector:
matchLabels:
app: gardener-resource-manager
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: a
ports:
- port: 10250
protocol: TCP
podSelector:
matchLabels:
foo: bar
policyTypes:
- Egress
ℹ️ Note that
Ingress
resources reference the service port whileNetworkPolicy
s reference the target port/container port. The controller automatically translates this when reconciling theNetworkPolicy
resources.
Node
Controller
Gardenlet configures kubelet of shoot worker nodes to register the Node
object with the node.gardener.cloud/critical-components-not-ready
taint (effect NoSchedule
).
This controller watches newly created Node
objects in the shoot cluster and removes the taint once all node-critical components are scheduled and ready.
If the controller finds node-critical components that are not scheduled or not ready yet, it checks the Node
again after the duration configured in ResourceManagerConfiguration.controllers.node.backoff
Please refer to the feature documentation or proposal issue for more details.
Webhooks
Mutating Webhooks
High Availability Config
This webhook is used to conveniently apply the configuration to make components deployed to seed or shoot clusters highly available. The details and scenarios are described in High Availability Of Deployed Components.
The webhook reacts on creation/update of Deployment
s, StatefulSet
s, HorizontalPodAutoscaler
s and HVPA
s in namespaces labeled with high-availability-config.resources.gardener.cloud/consider=true
.
The webhook performs the following actions:
The
.spec.replicas
(orspec.minReplicas
respectively) field is mutated based on thehigh-availability-config.resources.gardener.cloud/type
label of the resource and thehigh-availability-config.resources.gardener.cloud/failure-tolerance-type
annotation of the namespace:Failure Tolerance Type ➡️
/
⬇️ Component Type️ ️unset empty non-empty controller
2
1
2
server
2
2
2
- The replica count values can be overwritten by the
high-availability-config.resources.gardener.cloud/replicas
annotation. - It does NOT mutate the replicas when:
- the replicas are already set to
0
(hibernation case), or - when the resource is scaled horizontally by
HorizontalPodAutoscaler
orHvpa
, and the current replica count is higher than what was computed above.
- the replicas are already set to
- The replica count values can be overwritten by the
When the
high-availability-config.resources.gardener.cloud/zones
annotation is NOT empty and either thehigh-availability-config.resources.gardener.cloud/failure-tolerance-type
annotation is set or thehigh-availability-config.resources.gardener.cloud/zone-pinning
annotation is set totrue
, then it adds a node affinity to the pod template spec:spec: affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: topology.kubernetes.io/zone operator: In values: - <zone1> # - ...
This ensures that all pods are pinned to only nodes in exactly those concrete zones.
Topology Spread Constraints are added to the pod template spec when the
.spec.replicas
are greater than1
. When thehigh-availability-config.resources.gardener.cloud/zones
annotation …… contains only one zone, then the following is added:
spec: topologySpreadConstraints: - topologyKey: kubernetes.io/hostname maxSkew: 1 whenUnsatisfiable: ScheduleAnyway labelSelector: ...
This ensures that the (multiple) pods are scheduled across nodes on best-effort basis.
… contains at least two zones, then the following is added:
spec: topologySpreadConstraints: - topologyKey: kubernetes.io/hostname maxSkew: 1 whenUnsatisfiable: ScheduleAnyway labelSelector: ... - topologyKey: topology.kubernetes.io/zone minDomains: 2 # lower value of max replicas or number of zones maxSkew: 1 whenUnsatisfiable: DoNotSchedule labelSelector: ...
This enforces that the (multiple) pods are scheduled across zones. It circumvents a known limitation in Kubernetes for clusters < 1.26 (ref kubernetes/kubernetes#109364. In case the number of replicas is larger than twice the number of zones, then the
maxSkew=2
for the second spread constraints. TheminDomains
calculation is based on whatever value is lower - (maximum) replicas or number of zones. This is the number of minimum domains required to schedule pods in a highly available manner.
Independent on the number of zones, when the
high-availability-config.resources.gardener.cloud/failure-tolerance-type
annotation is set and NOT empty, then thewhenUnsatisfiable
is set toDoNotSchedule
for the constraint withtopologyKey=kubernetes.io/hostname
(which enforces the node-spread).Adds default tolerations for taint-based evictions:
Tolerations for taints
node.kubernetes.io/not-ready
andnode.kubernetes.io/unreachable
are added to the handledDeployment
andStatefulSet
if theirpodTemplate
s do not already specify them. TheTolerationSeconds
are taken from the respective configuration section of the webhook’s configuration (see example)).We consider fine-tuned values for those tolerations a matter of high-availability because they often help to reduce recovery times in case of node or zone outages, also see High-Availability Best Practices. In addition, this webhook handling helps to set defaults for many but not all workload components in a cluster. For instance, Gardener can use this webhook to set defaults for nearly every component in seed clusters but only for the system components in shoot clusters. Any customer workload remains unchanged.
Kubernetes Service Host Injection
By default, when Pod
s are created, Kubernetes implicitly injects the KUBERNETES_SERVICE_HOST
environment variable into all containers.
The value of this variable points it to the default Kubernetes service (i.e., kubernetes.default.svc.cluster.local
).
This allows pods to conveniently talk to the API server of their cluster.
In shoot clusters, this network path involves the apiserver-proxy
DaemonSet
which eventually forwards the traffic to the API server.
Hence, it results in additional network hop.
The purpose of this webhook is to explicitly inject the KUBERNETES_SERVICE_HOST
environment variable into all containers and setting its value to the FQDN of the API server.
This way, the additional network hop is avoided.
Auto-Mounting Projected ServiceAccount
Tokens
When this webhook is activated, then it automatically injects projected ServiceAccount
token volumes into Pod
s and all its containers if all of the following preconditions are fulfilled:
- The
Pod
is NOT labeled withprojected-token-mount.resources.gardener.cloud/skip=true
. - The
Pod
’s.spec.serviceAccountName
field is NOT empty and NOT set todefault
. - The
ServiceAccount
specified in thePod
’s.spec.serviceAccountName
sets.automountServiceAccountToken=false
. - The
Pod
’s.spec.volumes[]
DO NOT already contain a volume with a name prefixed withkube-api-access-
.
The projected volume will look as follows:
spec:
volumes:
- name: kube-api-access-gardener
projected:
defaultMode: 420
sources:
- serviceAccountToken:
expirationSeconds: 43200
path: token
- configMap:
items:
- key: ca.crt
path: ca.crt
name: kube-root-ca.crt
- downwardAPI:
items:
- fieldRef:
apiVersion: v1
fieldPath: metadata.namespace
path: namespace
The
expirationSeconds
are defaulted to12h
and can be overwritten with the.webhooks.projectedTokenMount.expirationSeconds
field in the component configuration, or with theprojected-token-mount.resources.gardener.cloud/expiration-seconds
annotation on aPod
resource.
The volume will be mounted into all containers specified in the Pod
to the path /var/run/secrets/kubernetes.io/serviceaccount
.
This is the default location where client libraries expect to find the tokens and mimics the upstream ServiceAccount
admission plugin. See Managing Service Accounts for more information.
Overall, this webhook is used to inject projected service account tokens into pods running in the Shoot and the Seed cluster. Hence, it is served from the Seed GRM and each Shoot GRM. Please find an overview below for pods deployed in the Shoot cluster:
Pod Topology Spread Constraints
When this webhook is enabled, then it mimics the topologyKey feature for Topology Spread Constraints (TSC) on the label pod-template-hash
.
Concretely, when a pod is labelled with pod-template-hash
, the handler of this webhook extends any topology spread constraint in the pod:
metadata:
labels:
pod-template-hash: 123abc
spec:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
pod-template-hash: 123abc # added by webhook
The procedure circumvents a known limitation with TSCs which leads to imbalanced deployments after rolling updates. Gardener enables this webhook to schedule pods of deployments across nodes and zones.
Please note that the gardener-resource-manager
itself as well as pods labelled with topology-spread-constraints.resources.gardener.cloud/skip
are excluded from any mutations.
System Components Webhook
If enabled, this webhook handles scheduling concerns for system components Pod
s (except those managed by DaemonSet
s).
The following tasks are performed by this webhook:
- Add
pod.spec.nodeSelector
as given in the webhook configuration. - Add
pod.spec.tolerations
as given in the webhook configuration. - Add
pod.spec.tolerations
for any existing nodes matching the node selector given in the webhook configuration. Known taints and tolerations used for taint based evictions are disregarded.
Gardener enables this webhook for kube-system
and kubernetes-dashboard
namespaces in shoot clusters, selecting Pod
s being labelled with resources.gardener.cloud/managed-by: gardener
.
It adds a configuration, so that Pod
s will get the worker.gardener.cloud/system-components: true
node selector (step 1) as well as tolerate any custom taint (step 2) that is added to system component worker nodes (shoot.spec.provider.workers[].systemComponents.allow: true
).
In addition, the webhook merges these tolerations with the ones required for at that time available system component Node
s in the cluster (step 3).
Both is required to ensure system component Pod
s can be scheduled or executed during an active shoot reconciliation that is happening due to any modifications to shoot.spec.provider.workers[].taints
, e.g. Pod
s must be scheduled while there are still Node
s not having the updated taint configuration.
You can opt-out of this behaviour for
Pod
s by labeling them withsystem-components-config.resources.gardener.cloud/skip=true
.
EndpointSlice Hints
This webhook mutates EndpointSlice
s. For each endpoint in the EndpointSlice, it sets the endpoint’s hints to the endpoint’s zone.
apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
name: example-hints
endpoints:
- addresses:
- "10.1.2.3"
conditions:
ready: true
hostname: pod-1
zone: zone-a
hints:
forZones:
- name: "zone-a" # added by webhook
- addresses:
- "10.1.2.4"
conditions:
ready: true
hostname: pod-2
zone: zone-b
hints:
forZones:
- name: "zone-b" # added by webhook
The webhook aims to circumvent issues with the Kubernetes TopologyAwareHints
feature that currently does not allow to achieve a deterministic topology-aware traffic routing. For more details, see the following issue kubernetes/kubernetes#113731 that describes drawbacks of the TopologyAwareHints
feature for our use case.
If the above-mentioned issue gets resolved and there is a native support for deterministic topology-aware traffic routing in Kubernetes, then this webhook can be dropped in favor of the native Kubernetes feature.
Validating Webhooks
Unconfirmed Deletion Prevention For Custom Resources And Definitions
As part of Gardener’s extensibility concepts, a lot of CustomResourceDefinition
s are deployed to the seed clusters that serve as extension points for provider-specific controllers.
For example, the Infrastructure
CRD triggers the provider extension to prepare the IaaS infrastructure of the underlying cloud provider for a to-be-created shoot cluster.
Consequently, these extension CRDs have a lot of power and control large portions of the end-user’s shoot cluster.
Accidental or undesired deletions of those resource can cause tremendous and hard-to-recover-from outages and should be prevented.
When this webhook is activated, it reacts for CustomResourceDefinition
s and most of the custom resources in the extensions.gardener.cloud/v1alpha1
API group.
It also reacts for the druid.gardener.cloud/v1alpha1.Etcd
resources.
The webhook prevents DELETE
requests for those CustomResourceDefinition
s labeled with gardener.cloud/deletion-protected=true
, and for all mentioned custom resources if they were not previously annotated with the confirmation.gardener.cloud/deletion=true
.
This prevents that undesired kubectl delete <...>
requests are accepted.
Extension Resource Validation
When this webhook is activated, it reacts for most of the custom resources in the extensions.gardener.cloud/v1alpha1
API group.
It also reacts for the druid.gardener.cloud/v1alpha1.Etcd
resources.
The webhook validates the resources specifications for CREATE
and UPDATE
requests.
1.2.13 - Scheduler
Gardener Scheduler
The Gardener Scheduler is in essence a controller that watches newly created shoots and assigns a seed cluster to them. Conceptually, the task of the Gardener Scheduler is very similar to the task of the Kubernetes Scheduler: finding a seed for a shoot instead of a node for a pod.
Either the scheduling strategy or the shoot cluster purpose hereby determines how the scheduler is operating. The following sections explain the configuration and flow in greater detail.
Why Is the Gardener Scheduler Needed?
1. Decoupling
Previously, an admission plugin in the Gardener API server conducted the scheduling decisions. This implies changes to the API server whenever adjustments of the scheduling are needed. Decoupling the API server and the scheduler comes with greater flexibility to develop these components independently.
2. Extensibility
It should be possible to easily extend and tweak the scheduler in the future. Possibly, similar to the Kubernetes scheduler, hooks could be provided which influence the scheduling decisions. It should be also possible to completely replace the standard Gardener Scheduler with a custom implementation.
Algorithm Overview
The following sequence describes the steps involved to determine a seed candidate:
- Determine usable seeds with “usable” defined as follows:
- no
.metadata.deletionTimestamp
.spec.settings.scheduling.visible
istrue
.status.lastOperation
is notnil
- conditions
GardenletReady
,BackupBucketsReady
(if available) aretrue
- no
- Filter seeds:
- matching
.spec.seedSelector
inCloudProfile
used by theShoot
- matching
.spec.seedSelector
inShoot
- having no network intersection with the
Shoot
’s networks (due to the VPN connectivity between seeds and shoots their networks must be disjoint) - whose taints (
.spec.taints
) are tolerated by theShoot
(.spec.tolerations
) - whose capacity for shoots would not be exceeded if the shoot is scheduled onto the seed, see Ensuring seeds capacity for shoots is not exceeded
- which have at least three zones in
.spec.provider.zones
if shoot requests a high available control plane with failure tolerance typezone
.
- matching
- Apply active strategy e.g., Minimal Distance strategy
- Choose least utilized seed, i.e., the one with the least number of shoot control planes, will be the winner and written to the
.spec.seedName
field of theShoot
.
In order to put the scheduling decision into effect, the scheduler sends an update request for the Shoot
resource to
the API server. After validation, the gardener-apiserver
updates the Shoot
to have the spec.seedName
field set.
Subsequently, the gardenlet
picks up and starts to create the cluster on the specified seed.
Configuration
The Gardener Scheduler configuration has to be supplied on startup. It is a mandatory and also the only available flag. This yaml file holds an example scheduler configuration.
Most of the configuration options are the same as in the Gardener Controller Manager (leader election, client connection, …). However, the Gardener Scheduler on the other hand does not need a TLS configuration, because there are currently no webhooks configurable.
Strategies
The scheduling strategy is defined in the candidateDeterminationStrategy of the scheduler’s configuration and can have the possible values SameRegion
and MinimalDistance
.
The SameRegion
strategy is the default strategy.
Same Region strategy
The Gardener Scheduler reads the spec.provider.type
and .spec.region
fields from the Shoot
resource.
It tries to find a seed that has the identical .spec.provider.type
and .spec.provider.region
fields set.
If it cannot find a suitable seed, it adds an event to the shoot stating that it is unschedulable.
Minimal Distance strategy
The Gardener Scheduler tries to find a valid seed with minimal distance to the shoot’s intended region.
Distances are configured via ConfigMap
(s), usually per cloud provider in a Gardener landscape.
The configuration is structured like this:
- It refers to one or multiple
CloudProfile
s via annotationscheduling.gardener.cloud/cloudprofiles
. - It contains the declaration as
region-config
via labelscheduling.gardener.cloud/purpose
. - If a
CloudProfile
is referred by multipleConfigMap
s, only the first one is considered. - The
data
fields configure actual distances, where key relates to theShoot
region and value contains distances toSeed
regions.
apiVersion: v1
kind: ConfigMap
metadata:
name: <name>
namespace: garden
annotations:
scheduling.gardener.cloud/cloudprofiles: cloudprofile-name-1{,optional-cloudprofile-name-2,...}
labels:
scheduling.gardener.cloud/purpose: region-config
data:
region-1: |
region-2: 10
region-3: 20
...
region-2: |
region-1: 10
region-3: 10
...
Gardener provider extensions for public cloud providers usually have an example weight
ConfigMap
in their repositories. We suggest to check them out before defining your own data.
If a valid seed candidate cannot be found after consulting the distance configuration, the scheduler will fall back to
the Levenshtein distance to find the closest region. Therefore, the region name
is split into a base name and an orientation. Possible orientations are north
, south
, east
, west
and central
.
The distance then is twice the Levenshtein distance of the region’s base name plus a correction value based on the
orientation and the provider.
If the orientations of shoot and seed candidate match, the correction value is 0, if they differ it is 2 and if either the seed’s or the shoot’s region does not have an orientation it is 1. If the provider differs, the correction value is additionally incremented by 2.
Because of this, a matching region with a matching provider is always prefered.
Special handling based on shoot cluster purpose
Every shoot cluster can have a purpose that describes what the cluster is used for, and also influences how the cluster is setup (see Shoot Cluster Purpose for more information).
In case the shoot has the testing
purpose, then the scheduler only reads the .spec.provider.type
from the Shoot
resource and tries to find a Seed
that has the identical .spec.provider.type
.
The region does not matter, i.e., testing
shoots may also be scheduled on a seed in a complete different region if it is better for balancing the whole Gardener system.
shoots/binding
Subresource
The shoots/binding
subresource is used to bind a Shoot
to a Seed
. On creation of a shoot cluster/s, the scheduler updates the binding automatically if an appropriate seed cluster is available.
Only an operator with the necessary RBAC can update this binding manually. This can be done by changing the .spec.seedName
of the shoot. However, if a different seed is already assigned to the shoot, this will trigger a control-plane migration. For required steps, please see Triggering the Migration.
spec.schedulerName
Field in the Shoot
Specification
Similar to the spec.schedulerName
field in Pod
s, the Shoot
specification has an optional .spec.schedulerName
field. If this field is set on creation, only the scheduler which relates to the configured name is responsible for scheduling the shoot.
The default-scheduler
name is reserved for the default scheduler of Gardener.
Affected Shoots will remain in Pending
state if the mentioned scheduler is not present in the landscape.
spec.seedName
Field in the Shoot
Specification
Similar to the .spec.nodeName
field in Pod
s, the Shoot
specification has an optional .spec.seedName
field. If this field is set on creation, the shoot will be scheduled to this seed. However, this field can only be set by users having RBAC for the shoots/binding
subresource. If this field is not set, the scheduler
will assign a suitable seed automatically and populate this field with the seed name.
seedSelector
Field in the Shoot
Specification
Similar to the .spec.nodeSelector
field in Pod
s, the Shoot
specification has an optional .spec.seedSelector
field.
It allows the user to provide a label selector that must match the labels of the Seed
s in order to be scheduled to one of them.
The labels on the Seed
s are usually controlled by Gardener administrators/operators - end users cannot add arbitrary labels themselves.
If provided, the Gardener Scheduler will only consider as “suitable” those seeds whose labels match those provided in the .spec.seedSelector
of the Shoot
.
By default, only seeds with the same provider as the shoot are selected. By adding a providerTypes
field to the seedSelector
,
a dedicated set of possible providers (*
means all provider types) can be selected.
Ensuring a Seed’s Capacity for Shoots Is Not Exceeded
Seeds have a practical limit of how many shoots they can accommodate. Exceeding this limit is undesirable, as the system performance will be noticeably impacted. Therefore, the scheduler ensures that a seed’s capacity for shoots is not exceeded by taking into account a maximum number of shoots that can be scheduled onto a seed.
This mechanism works as follows:
- The
gardenlet
is configured with certain resources and their total capacity (and, for certain resources, the amount reserved for Gardener), see /example/20-componentconfig-gardenlet.yaml. Currently, the only such resource is the maximum number of shoots that can be scheduled onto a seed. - The
gardenlet
seed controller updates thecapacity
andallocatable
fields in the Seed status with the capacity of each resource and how much of it is actually available to be consumed by shoots. Theallocatable
value of a resource is equal tocapacity
minusreserved
. - When scheduling shoots, the scheduler filters out all candidate seeds whose allocatable capacity for shoots would be exceeded if the shoot is scheduled onto the seed.
Failure to Determine a Suitable Seed
In case the scheduler fails to find a suitable seed, the operation is being retried with exponential backoff.
The reason for the failure will be reported in the Shoot
’s .status.lastOperation
field as well as a Kubernetes event (which can be retrieved via kubectl -n <namespace> describe shoot <shoot-name>
).
Current Limitation / Future Plans
- Azure unfortunately has a geographically non-hierarchical naming pattern and does not start with the continent. This is the reason why we will exchange the implementation of the
MinimalDistance
strategy with a more suitable one in the future.
1.3 - Deployment
1.3.1 - Authentication Gardener Control Plane
Authentication of Gardener Control Plane Components Against the Garden Cluster
Note: This document refers to Gardener’s API server, admission controller, controller manager and scheduler components. Any reference to the term Gardener control plane component can be replaced with any of the mentioned above.
There are several authentication possibilities depending on whether or not the concept of Virtual Garden is used.
Virtual Garden is not used, i.e., the runtime
Garden cluster is also the target
Garden cluster.
Automounted Service Account Token
The easiest way to deploy a Gardener control plane component is to not provide a kubeconfig
at all. This way in-cluster configuration and an automounted service account token will be used. The drawback of this approach is that the automounted token will not be automatically rotated.
Service Account Token Volume Projection
Another solution is to use Service Account Token Volume Projection combined with a kubeconfig
referencing a token file (see the example below).
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: <CA-DATA>
server: https://default.kubernetes.svc.cluster.local
name: garden
contexts:
- context:
cluster: garden
user: garden
name: garden
current-context: garden
users:
- name: garden
user:
tokenFile: /var/run/secrets/projected/serviceaccount/token
This will allow for automatic rotation of the service account token by the kubelet
. The configuration can be achieved by setting both .Values.global.<GardenerControlPlaneComponent>.serviceAccountTokenVolumeProjection.enabled: true
and .Values.global.<GardenerControlPlaneComponent>.kubeconfig
in the respective chart’s values.yaml
file.
Virtual Garden is used, i.e., the runtime
Garden cluster is different from the target
Garden cluster.
Service Account
The easiest way to setup the authentication is to create a service account and the respective roles will be bound to this service account in the target
cluster. Then use the generated service account token and craft a kubeconfig
, which will be used by the workload in the runtime
cluster. This approach does not provide a solution for the rotation of the service account token. However, this setup can be achieved by setting .Values.global.deployment.virtualGarden.enabled: true
and following these steps:
- Deploy the
application
part of the charts in thetarget
cluster. - Get the service account token and craft the
kubeconfig
. - Set the crafted
kubeconfig
and deploy theruntime
part of the charts in theruntime
cluster.
Client Certificate
Another solution is to bind the roles in the target
cluster to a User
subject instead of a service account and use a client certificate for authentication. This approach does not provide a solution for the client certificate rotation. However, this setup can be achieved by setting both .Values.global.deployment.virtualGarden.enabled: true
and .Values.global.deployment.virtualGarden.<GardenerControlPlaneComponent>.user.name
, then following these steps:
- Generate a client certificate for the
target
cluster for the respective user. - Deploy the
application
part of the charts in thetarget
cluster. - Craft a
kubeconfig
using the already generated client certificate. - Set the crafted
kubeconfig
and deploy theruntime
part of the charts in theruntime
cluster.
Projected Service Account Token
This approach requires an already deployed and configured oidc-webhook-authenticator for the target
cluster. Also, the runtime
cluster should be registered as a trusted identity provider in the target
cluster. Then, projected service accounts tokens from the runtime
cluster can be used to authenticate against the target
cluster. The needed steps are as follows:
- Deploy OWA and establish the needed trust.
- Set
.Values.global.deployment.virtualGarden.enabled: true
and.Values.global.deployment.virtualGarden.<GardenerControlPlaneComponent>.user.name
.Note: username value will depend on the trust configuration, e.g.,
<prefix>:system:serviceaccount:<namespace>:<serviceaccount>
- Set
.Values.global.<GardenerControlPlaneComponent>.serviceAccountTokenVolumeProjection.enabled: true
and.Values.global.<GardenerControlPlaneComponent>.serviceAccountTokenVolumeProjection.audience
.Note: audience value will depend on the trust configuration, e.g.,
<cliend-id-from-trust-config>
. - Craft a kubeconfig (see the example below).
- Deploy the
application
part of the charts in thetarget
cluster. - Deploy the
runtime
part of the charts in theruntime
cluster.
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: <CA-DATA>
server: https://virtual-garden.api
name: virtual-garden
contexts:
- context:
cluster: virtual-garden
user: virtual-garden
name: virtual-garden
current-context: virtual-garden
users:
- name: virtual-garden
user:
tokenFile: /var/run/secrets/projected/serviceaccount/token
1.3.2 - Configuring Logging
Configuring the Logging Stack via gardenlet Configurations
Enable the Logging
In order to install the Gardener logging stack, the logging.enabled
configuration option has to be enabled in the Gardenlet configuration:
logging:
enabled: true
From now on, each Seed is going to have a logging stack which will collect logs from all pods and some systemd services. Logs related to Shoots with testing
purpose are dropped in the fluent-bit
output plugin. Shoots with a purpose different than testing
have the same type of log aggregator (but different instance) as the Seed. The logs can be viewed in the Plutono in the garden
namespace for the Seed components and in the respective shoot control plane namespaces.
Enable Logs from the Shoot’s Node systemd Services
The logs from the systemd services on each node can be retrieved by enabling the logging.shootNodeLogging
option in the gardenlet configuration:
logging:
enabled: true
shootNodeLogging:
shootPurposes:
- "evaluation"
- "deployment"
Under the shootPurpose
section, just list all the shoot purposes for which the Shoot node logging feature will be enabled. Specifying the testing
purpose has no effect because this purpose prevents the logging stack installation.
Logs can be viewed in the operator Plutono!
The dedicated labels are unit
, syslog_identifier
, and nodename
in the Explore
menu.
Configuring Central Vali Storage Capacity
By default, the central Vali has 100Gi
of storage capacity.
To overwrite the current central Vali storage capacity, the logging.vali.garden.storage
setting in the gardenlet’s component configuration should be altered.
If you need to increase it, you can do so without losing the current data by specifying a higher capacity. By doing so, the Vali’s PersistentVolume
capacity will be increased instead of deleting the current PV.
However, if you specify less capacity, then the PersistentVolume
will be deleted and with it the logs, too.
logging:
enabled: true
vali:
garden:
storage: "200Gi"
1.3.3 - Deploy Gardenlet
Deploying Gardenlets
Gardenlets act as decentral “agents” to manage the shoot clusters of a seed cluster.
To support scaleability in an automated way, gardenlets are deployed automatically. However, you can still deploy gardenlets manually to be more flexible, for example, when the shoot clusters that need to be managed by Gardener are behind a firewall. The gardenlet only requires network connectivity from the gardenlet to the Garden cluster (not the other way round), so it can be used to register Kubernetes clusters with no public endpoint.
Procedure
First, an initial gardenlet needs to be deployed:
- Deploy it manually if you have special requirements. For more information, see Deploy a Gardenlet Manually.
- Let the Gardener installer deploy it automatically otherwise. For more information, see Automatic Deployment of Gardenlets.
To add additional seed clusters, it is recommended to use regular shoot clusters. You can do this by creating a
ManagedSeed
resource with agardenlet
section as described in Register Shoot as Seed.
1.3.4 - Deploy Gardenlet Automatically
Automatic Deployment of gardenlets
The gardenlet can automatically deploy itself into shoot clusters, and register a cluster as a seed cluster. These clusters are called “managed seeds” (aka “shooted seeds”). This procedure is the preferred way to add additional seed clusters, because shoot clusters already come with production-grade qualities that are also demanded for seed clusters.
Prerequisites
The only prerequisite is to register an initial cluster as a seed cluster that already has a gardenlet deployed in one of the following ways:
- The gardenlet was deployed as part of a Gardener installation using a setup tool (for example,
gardener/garden-setup
). - The gardenlet was deployed manually (for a step-by-step manual installation guide, see Deploy a Gardenlet Manually).
The initial cluster can be the garden cluster itself.
Self-Deployment of gardenlets in Additional Managed Seed Clusters
For a better scalability, you usually need more seed clusters that you can create, as follows:
- Use the initial cluster as the seed cluster for other managed seed clusters. It hosts the control planes of the other seed clusters.
- The gardenlet deployed in the initial cluster deploys itself automatically into the managed seed clusters.
The advantage of this approach is that there’s only one initial gardenlet installation required. Every other managed seed cluster has a gardenlet deployed automatically.
Related Links
1.3.5 - Deploy Gardenlet Manually
Deploy a gardenlet Manually
Manually deploying a gardenlet is required in the following cases:
The Kubernetes cluster to be registered as a seed cluster has no public endpoint, because it is behind a firewall. The gardenlet must then be deployed into the cluster itself.
The Kubernetes cluster to be registered as a seed cluster is managed externally (the Kubernetes cluster is not a shoot cluster, so Automatic Deployment of Gardenlets cannot be used).
The gardenlet runs outside of the Kubernetes cluster that should be registered as a seed cluster. (The gardenlet is not restricted to run in the seed cluster or to be deployed into a Kubernetes cluster at all).
Once you’ve deployed a gardenlet manually, for example, behind a firewall, you can deploy new gardenlets automatically. The manually deployed gardenlet is then used as a template for the new gardenlets. For more information, see Automatic Deployment of Gardenlets.
Prerequisites
Kubernetes Cluster that Should Be Registered as a Seed Cluster
Verify that the cluster has a supported Kubernetes version.
Determine the nodes, pods, and services CIDR of the cluster. You need to configure this information in the
Seed
configuration. Gardener uses this information to check that the shoot cluster isn’t created with overlapping CIDR ranges.Every seed cluster needs an Ingress controller which distributes external requests to internal components like Plutono and Prometheus. For this, configure the following lines in your Seed resource:
spec:
dns:
provider:
type: aws-route53
secretRef:
name: ingress-secret
namespace: garden
ingress:
domain: ingress.my-seed.example.com
controller:
kind: nginx
providerConfig:
<some-optional-provider-specific-config-for-the-ingressController>
kubeconfig
for the Seed Cluster
The kubeconfig
is required to deploy the gardenlet Helm chart to the seed cluster.
The gardenlet requires certain privileges to be able to operate.
These privileges are described in RBAC resources in the gardenlet Helm chart (see charts/gardener/gardenlet/templates).
The Helm chart contains a service account gardenlet
that the gardenlet deployment uses by default to talk to the Seed API server.
If the gardenlet isn’t deployed in the seed cluster, the gardenlet can be configured to use a
kubeconfig
, which also requires the above-mentioned privileges, from a mounted directory. Thekubeconfig
is specified in theseedClientConnection.kubeconfig
section of the Gardenlet configuration. This configuration option isn’t used in the following, as this procedure only describes the recommended setup option where the gardenlet is running in the seed cluster itself.
Procedure Overview
Prepare the garden cluster:
Create a Bootstrap Token Secret in the kube-system
Namespace of the Garden Cluster
The gardenlet needs to talk to the Gardener API server residing in the garden cluster.
The gardenlet can be configured with an already existing garden cluster kubeconfig
in one of the following ways:
- By specifying
gardenClientConnection.kubeconfig
in the Gardenlet configuration. - By supplying the environment variable
GARDEN_KUBECONFIG
pointing to a mountedkubeconfig
file).
The preferred way, however, is to use the gardenlet’s ability to request a signed certificate for the garden cluster by leveraging Kubernetes Certificate Signing Requests. The gardenlet performs a TLS bootstrapping process that is similar to the Kubelet TLS Bootstrapping. Make sure that the API server of the garden cluster has bootstrap token authentication enabled.
The client credentials required for the gardenlet’s TLS bootstrapping process
need to be either token
or certificate
(OIDC isn’t supported) and have permissions
to create a Certificate Signing Request (CSR).
It’s recommended to use bootstrap tokens
due to their desirable security properties (such as a limited token lifetime).
Therefore, first create a bootstrap token secret for the garden cluster:
apiVersion: v1
kind: Secret
metadata:
# Name MUST be of form "bootstrap-token-<token id>"
name: bootstrap-token-07401b
namespace: kube-system
# Type MUST be 'bootstrap.kubernetes.io/token'
type: bootstrap.kubernetes.io/token
stringData:
# Human readable description. Optional.
description: "Token to be used by the gardenlet for Seed `sweet-seed`."
# Token ID and secret. Required.
token-id: 07401b # 6 characters
token-secret: f395accd246ae52d # 16 characters
# Expiration. Optional.
# expiration: 2017-03-10T03:22:11Z
# Allowed usages.
usage-bootstrap-authentication: "true"
usage-bootstrap-signing: "true"
When you later prepare the gardenlet Helm chart,
a kubeconfig
based on this token is shared with the gardenlet upon deployment.
Create RBAC Roles for the gardenlet to Allow Bootstrapping in the Garden Cluster
This step is only required if the gardenlet you deploy is the first gardenlet in the Gardener installation. Additionally, when using the control plane chart, the following resources are already contained in the Helm chart, that is, if you use it you can skip these steps as the needed RBAC roles already exist.
The gardenlet uses the configured bootstrap kubeconfig
in gardenClientConnection.bootstrapKubeconfig
to request a signed certificate for the user gardener.cloud:system:seed:<seed-name>
in the group gardener.cloud:system:seeds
.
Create a ClusterRole
and ClusterRoleBinding
that grant full admin permissions to authenticated gardenlets.
Create the following resources in the garden cluster:
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: gardener.cloud:system:seeds
rules:
- apiGroups:
- '*'
resources:
- '*'
verbs:
- '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gardener.cloud:system:seeds
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: gardener.cloud:system:seeds
subjects:
- kind: Group
name: gardener.cloud:system:seeds
apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: gardener.cloud:system:seed-bootstrapper
rules:
- apiGroups:
- certificates.k8s.io
resources:
- certificatesigningrequests
verbs:
- create
- get
- apiGroups:
- certificates.k8s.io
resources:
- certificatesigningrequests/seedclient
verbs:
- create
---
# A kubelet/gardenlet authenticating using bootstrap tokens is authenticated as a user in the group system:bootstrappers
# Allows the Gardenlet to create a CSR
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gardener.cloud:system:seed-bootstrapper
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: gardener.cloud:system:seed-bootstrapper
subjects:
- kind: Group
name: system:bootstrappers
apiGroup: rbac.authorization.k8s.io
ℹ️ After bootstrapping, the gardenlet has full administrative access to the garden cluster. You might be interested to harden this and limit its permissions to only resources related to the seed cluster it is responsible for. Please take a look at Scoped API Access for Gardenlets.
Prepare the gardenlet Helm Chart
This section only describes the minimal configuration, using the global configuration values of the gardenlet Helm chart. For an overview over all values, see the configuration values. We refer to the global configuration values as gardenlet configuration in the following procedure.
Create a gardenlet configuration
gardenlet-values.yaml
based on this template.Create a bootstrap
kubeconfig
based on the bootstrap token created in the garden cluster.Replace the
<bootstrap-token>
withtoken-id.token-secret
(from our previous example:07401b.f395accd246ae52d
) from the bootstrap token secret.apiVersion: v1 kind: Config current-context: gardenlet-bootstrap@default clusters: - cluster: certificate-authority-data: <ca-of-garden-cluster> server: https://<endpoint-of-garden-cluster> name: default contexts: - context: cluster: default user: gardenlet-bootstrap name: gardenlet-bootstrap@default users: - name: gardenlet-bootstrap user: token: <bootstrap-token>
In the
gardenClientConnection.bootstrapKubeconfig
section of your gardenlet configuration, provide the bootstrapkubeconfig
together with a name and namespace to the gardenlet Helm chart.gardenClientConnection: bootstrapKubeconfig: name: gardenlet-kubeconfig-bootstrap namespace: garden kubeconfig: | <bootstrap-kubeconfig> # will be base64 encoded by helm
The bootstrap
kubeconfig
is stored in the specified secret.In the
gardenClientConnection.kubeconfigSecret
section of your gardenlet configuration, define a name and a namespace where the gardenlet stores the realkubeconfig
that it creates during the bootstrap process. If the secret doesn’t exist, the gardenlet creates it for you.gardenClientConnection: kubeconfigSecret: name: gardenlet-kubeconfig namespace: garden
Updating the Garden Cluster CA
The kubeconfig created by the gardenlet in step 4 will not be recreated as long as it exists, even if a new bootstrap kubeconfig is provided. To enable rotation of the garden cluster CA certificate, a new bundle can be provided via the gardenClientConnection.gardenClusterCACert
field. If the provided bundle differs from the one currently in the gardenlet’s kubeconfig secret then it will be updated. To remove the CA completely (e.g. when switching to a publicly trusted endpoint), this field can be set to either none
or null
.
Automatically Register a Shoot Cluster as a Seed Cluster
A seed cluster can either be registered by manually creating
the Seed
resource
or automatically by the gardenlet.
This functionality is useful for managed seed clusters,
as the gardenlet in the garden cluster deploys a copy of itself
into the cluster with automatic registration of the Seed
configured.
However, it can also be used to have a streamlined seed cluster registration process when manually deploying the gardenlet.
This procedure doesn’t describe all the possible configurations for the
Seed
resource. For more information, see:
Adjust the gardenlet Component Configuration
Supply the
Seed
resource in theseedConfig
section of your gardenlet configurationgardenlet-values.yaml
.Add the
seedConfig
to your gardenlet configurationgardenlet-values.yaml
. The fieldseedConfig.spec.provider.type
specifies the infrastructure provider type (for example,aws
) of the seed cluster. For all supported infrastructure providers, see Known Extension Implementations.# ... seedConfig: metadata: name: sweet-seed labels: environment: evaluation annotations: custom.gardener.cloud/option: special spec: dns: provider: type: <provider> secretRef: name: ingress-secret namespace: garden ingress: # see prerequisites domain: ingress.dev.my-seed.example.com controller: kind: nginx networks: # see prerequisites nodes: 10.240.0.0/16 pods: 100.244.0.0/16 services: 100.32.0.0/13 shootDefaults: # optional: non-overlapping default CIDRs for shoot clusters of that Seed pods: 100.96.0.0/11 services: 100.64.0.0/13 provider: region: eu-west-1 type: <provider>
Apart from the seed’s name, seedConfig.metadata
can optionally contain labels
and annotations
.
gardenlet will set the labels of the registered Seed
object to the labels given in the seedConfig
plus gardener.cloud/role=seed
.
Any custom labels on the Seed
object will be removed on the next restart of gardenlet.
If a label is removed from the seedConfig
it is removed from the Seed
object as well.
In contrast to labels, annotations in the seedConfig
are added to existing annotations on the Seed
object.
Thus, custom annotations that are added to the Seed
object during runtime are not removed by gardenlet on restarts.
Furthermore, if an annotation is removed from the seedConfig
, gardenlet does not remove it from the Seed
object.
Optional: Enable HA Mode
You may consider running gardenlet
with multiple replicas, especially if the seed cluster is configured to host HA shoot control planes.
Therefore, the following Helm chart values define the degree of high availability you want to achieve for the gardenlet
deployment.
replicaCount: 2 # or more if a higher failure tolerance is required.
failureToleranceType: zone # One of `zone` or `node` - defines how replicas are spread.
Optional: Enable Backup and Restore
The seed cluster can be set up with backup and restore
for the main etcds
of shoot clusters.
Gardener uses etcd-backup-restore
that integrates with different storage providers
to store the shoot cluster’s main etcd
backups.
Make sure to obtain client credentials that have sufficient permissions with the chosen storage provider.
Create a secret in the garden cluster with client credentials for the storage provider. The format of the secret is cloud provider specific and can be found in the repository of the respective Gardener extension. For example, the secret for AWS S3 can be found in the AWS provider extension (30-etcd-backup-secret.yaml).
apiVersion: v1
kind: Secret
metadata:
name: sweet-seed-backup
namespace: garden
type: Opaque
data:
# client credentials format is provider specific
Configure the Seed
resource in the seedConfig
section of your gardenlet configuration to use backup and restore:
# ...
seedConfig:
metadata:
name: sweet-seed
spec:
backup:
provider: <provider>
secretRef:
name: sweet-seed-backup
namespace: garden
Deploy the gardenlet
The gardenlet doesn’t have to run in the same Kubernetes cluster as the seed cluster it’s registering and reconciling, but it is in most cases advantageous to use in-cluster communication to talk to the Seed API server. Running a gardenlet outside of the cluster is mostly used for local development.
The gardenlet-values.yaml
looks something like this
(with automatic Seed registration and backup for shoot clusters enabled):
# <default config>
# ...
config:
gardenClientConnection:
# ...
bootstrapKubeconfig:
name: gardenlet-bootstrap-kubeconfig
namespace: garden
kubeconfig: |
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: <dummy>
server: <my-garden-cluster-endpoint>
name: my-kubernetes-cluster
# ...
kubeconfigSecret:
name: gardenlet-kubeconfig
namespace: garden
# ...
# <default config>
# ...
seedConfig:
metadata:
name: sweet-seed
spec:
dns:
provider:
type: <provider>
secretRef:
name: ingress-secret
namespace: garden
ingress: # see prerequisites
domain: ingress.dev.my-seed.example.com
controller:
kind: nginx
networks:
nodes: 10.240.0.0/16
pods: 100.244.0.0/16
services: 100.32.0.0/13
shootDefaults:
pods: 100.96.0.0/11
services: 100.64.0.0/13
provider:
region: eu-west-1
type: <provider>
backup:
provider: <provider>
secretRef:
name: sweet-seed-backup
namespace: garden
Deploy the gardenlet Helm chart to the Kubernetes cluster:
helm install gardenlet charts/gardener/gardenlet \
--namespace garden \
-f gardenlet-values.yaml \
--wait
This helm chart creates:
- A service account
gardenlet
that the gardenlet can use to talk to the Seed API server. - RBAC roles for the service account (full admin rights at the moment).
- The secret (
garden
/gardenlet-bootstrap-kubeconfig
) containing the bootstrapkubeconfig
. - The gardenlet deployment in the
garden
namespace.
Check that the gardenlet Is Successfully Deployed
Check that the gardenlets certificate bootstrap was successful.
Check if the secret
gardenlet-kubeconfig
in the namespacegarden
in the seed cluster is created and contains akubeconfig
with a valid certificate.Get the
kubeconfig
from the created secret.$ kubectl -n garden get secret gardenlet-kubeconfig -o json | jq -r .data.kubeconfig | base64 -d
Test against the garden cluster and verify it’s working.
Extract the
client-certificate-data
from the usergardenlet
.View the certificate:
$ openssl x509 -in ./gardenlet-cert -noout -text
Check that the certificate is valid for a year (that is the lifetime of new certificates).
Check that the bootstrap secret
gardenlet-bootstrap-kubeconfig
has been deleted from the seed cluster in namespacegarden
.Check that the seed cluster is registered and
READY
in the garden cluster.Check that the seed cluster
sweet-seed
exists and all conditions indicate that it’s available. If so, the Gardenlet is sending regular heartbeats and the seed bootstrapping was successful.Check that the conditions on the
Seed
resource look similar to the following:$ kubectl get seed sweet-seed -o json | jq .status.conditions [ { "lastTransitionTime": "2020-07-17T09:17:29Z", "lastUpdateTime": "2020-07-17T09:17:29Z", "message": "Gardenlet is posting ready status.", "reason": "GardenletReady", "status": "True", "type": "GardenletReady" }, { "lastTransitionTime": "2020-07-17T09:17:49Z", "lastUpdateTime": "2020-07-17T09:53:17Z", "message": "Backup Buckets are available.", "reason": "BackupBucketsAvailable", "status": "True", "type": "BackupBucketsReady" } ]
Related Links
1.3.6 - Feature Gates
Feature Gates in Gardener
This page contains an overview of the various feature gates an administrator can specify on different Gardener components.
Overview
Feature gates are a set of key=value pairs that describe Gardener features. You can turn these features on or off using the component configuration file for a specific component.
Each Gardener component lets you enable or disable a set of feature gates that are relevant to that component. For example, this is the configuration of the gardenlet component.
The following tables are a summary of the feature gates that you can set on different Gardener components.
- The “Since” column contains the Gardener release when a feature is introduced or its release stage is changed.
- The “Until” column, if not empty, contains the last Gardener release in which you can still use a feature gate.
- If a feature is in the Alpha or Beta state, you can find the feature listed in the Alpha/Beta feature gate table.
- If a feature is stable you can find all stages for that feature listed in the Graduated/Deprecated feature gate table.
- The Graduated/Deprecated feature gate table also lists deprecated and withdrawn features.
Feature Gates for Alpha or Beta Features
Feature | Default | Stage | Since | Until |
---|---|---|---|---|
HVPA | false | Alpha | 0.31 | |
HVPAForShootedSeed | false | Alpha | 0.32 | |
DefaultSeccompProfile | false | Alpha | 1.54 | |
CoreDNSQueryRewriting | false | Alpha | 1.55 | |
IPv6SingleStack | false | Alpha | 1.63 | |
MutableShootSpecNetworkingNodes | false | Alpha | 1.64 | |
WorkerlessShoots | false | Alpha | 1.70 | 1.78 |
WorkerlessShoots | false | Beta | 1.79 | |
MachineControllerManagerDeployment | false | Alpha | 1.73 | |
MachineControllerManagerDeployment | true | Beta | 1.81 | 1.81 |
MachineControllerManagerDeployment | true | GA | 1.82 | |
ContainerdRegistryHostsDir | false | Alpha | 1.77 | 1.85 |
ContainerdRegistryHostsDir | false | Beta | 1.86 | |
ShootForceDeletion | false | Alpha | 1.81 | |
APIServerFastRollout | true | Beta | 1.82 | |
UseGardenerNodeAgent | false | Alpha | 1.82 |
Feature Gates for Graduated or Deprecated Features
Feature | Default | Stage | Since | Until |
---|---|---|---|---|
NodeLocalDNS | false | Alpha | 1.7 | |
NodeLocalDNS | Removed | 1.26 | ||
KonnectivityTunnel | false | Alpha | 1.6 | |
KonnectivityTunnel | Removed | 1.27 | ||
MountHostCADirectories | false | Alpha | 1.11 | 1.25 |
MountHostCADirectories | true | Beta | 1.26 | 1.27 |
MountHostCADirectories | true | GA | 1.27 | |
MountHostCADirectories | Removed | 1.30 | ||
DisallowKubeconfigRotationForShootInDeletion | false | Alpha | 1.28 | 1.31 |
DisallowKubeconfigRotationForShootInDeletion | true | Beta | 1.32 | 1.35 |
DisallowKubeconfigRotationForShootInDeletion | true | GA | 1.36 | |
DisallowKubeconfigRotationForShootInDeletion | Removed | 1.38 | ||
Logging | false | Alpha | 0.13 | 1.40 |
Logging | Removed | 1.41 | ||
AdminKubeconfigRequest | false | Alpha | 1.24 | 1.38 |
AdminKubeconfigRequest | true | Beta | 1.39 | 1.41 |
AdminKubeconfigRequest | true | GA | 1.42 | 1.49 |
AdminKubeconfigRequest | Removed | 1.50 | ||
UseDNSRecords | false | Alpha | 1.27 | 1.38 |
UseDNSRecords | true | Beta | 1.39 | 1.43 |
UseDNSRecords | true | GA | 1.44 | 1.49 |
UseDNSRecords | Removed | 1.50 | ||
CachedRuntimeClients | false | Alpha | 1.7 | 1.33 |
CachedRuntimeClients | true | Beta | 1.34 | 1.44 |
CachedRuntimeClients | true | GA | 1.45 | 1.49 |
CachedRuntimeClients | Removed | 1.50 | ||
DenyInvalidExtensionResources | false | Alpha | 1.31 | 1.41 |
DenyInvalidExtensionResources | true | Beta | 1.42 | 1.44 |
DenyInvalidExtensionResources | true | GA | 1.45 | 1.49 |
DenyInvalidExtensionResources | Removed | 1.50 | ||
RotateSSHKeypairOnMaintenance | false | Alpha | 1.28 | 1.44 |
RotateSSHKeypairOnMaintenance | true | Beta | 1.45 | 1.47 |
RotateSSHKeypairOnMaintenance (deprecated) | false | Beta | 1.48 | 1.50 |
RotateSSHKeypairOnMaintenance (deprecated) | Removed | 1.51 | ||
ShootMaxTokenExpirationOverwrite | false | Alpha | 1.43 | 1.44 |
ShootMaxTokenExpirationOverwrite | true | Beta | 1.45 | 1.47 |
ShootMaxTokenExpirationOverwrite | true | GA | 1.48 | 1.50 |
ShootMaxTokenExpirationOverwrite | Removed | 1.51 | ||
ShootMaxTokenExpirationValidation | false | Alpha | 1.43 | 1.45 |
ShootMaxTokenExpirationValidation | true | Beta | 1.46 | 1.47 |
ShootMaxTokenExpirationValidation | true | GA | 1.48 | 1.50 |
ShootMaxTokenExpirationValidation | Removed | 1.51 | ||
WorkerPoolKubernetesVersion | false | Alpha | 1.35 | 1.45 |
WorkerPoolKubernetesVersion | true | Beta | 1.46 | 1.49 |
WorkerPoolKubernetesVersion | true | GA | 1.50 | 1.51 |
WorkerPoolKubernetesVersion | Removed | 1.52 | ||
DisableDNSProviderManagement | false | Alpha | 1.41 | 1.49 |
DisableDNSProviderManagement | true | Beta | 1.50 | 1.51 |
DisableDNSProviderManagement | true | GA | 1.52 | 1.59 |
DisableDNSProviderManagement | Removed | 1.60 | ||
SecretBindingProviderValidation | false | Alpha | 1.38 | 1.50 |
SecretBindingProviderValidation | true | Beta | 1.51 | 1.52 |
SecretBindingProviderValidation | true | GA | 1.53 | 1.54 |
SecretBindingProviderValidation | Removed | 1.55 | ||
SeedKubeScheduler | false | Alpha | 1.15 | 1.54 |
SeedKubeScheduler | false | Deprecated | 1.55 | 1.60 |
SeedKubeScheduler | Removed | 1.61 | ||
ShootCARotation | false | Alpha | 1.42 | 1.50 |
ShootCARotation | true | Beta | 1.51 | 1.56 |
ShootCARotation | true | GA | 1.57 | 1.59 |
ShootCARotation | Removed | 1.60 | ||
ShootSARotation | false | Alpha | 1.48 | 1.50 |
ShootSARotation | true | Beta | 1.51 | 1.56 |
ShootSARotation | true | GA | 1.57 | 1.59 |
ShootSARotation | Removed | 1.60 | ||
ReversedVPN | false | Alpha | 1.22 | 1.41 |
ReversedVPN | true | Beta | 1.42 | 1.62 |
ReversedVPN | true | GA | 1.63 | 1.69 |
ReversedVPN | Removed | 1.70 | ||
ForceRestore | Removed | 1.66 | ||
SeedChange | false | Alpha | 1.12 | 1.52 |
SeedChange | true | Beta | 1.53 | 1.68 |
SeedChange | true | GA | 1.69 | 1.72 |
SeedChange | true | Removed | 1.73 | |
CopyEtcdBackupsDuringControlPlaneMigration | false | Alpha | 1.37 | 1.52 |
CopyEtcdBackupsDuringControlPlaneMigration | true | Beta | 1.53 | 1.68 |
CopyEtcdBackupsDuringControlPlaneMigration | true | GA | 1.69 | 1.72 |
CopyEtcdBackupsDuringControlPlaneMigration | true | Removed | 1.73 | |
ManagedIstio | false | Alpha | 1.5 | 1.18 |
ManagedIstio | true | Beta | 1.19 | |
ManagedIstio | true | Deprecated | 1.48 | 1.69 |
ManagedIstio | Removed | 1.70 | ||
APIServerSNI | false | Alpha | 1.7 | 1.18 |
APIServerSNI | true | Beta | 1.19 | |
APIServerSNI | true | Deprecated | 1.48 | 1.72 |
APIServerSNI | true | Removed | 1.73 | |
HAControlPlanes | false | Alpha | 1.49 | 1.70 |
HAControlPlanes | true | Beta | 1.71 | 1.72 |
HAControlPlanes | true | GA | 1.73 | 1.73 |
HAControlPlanes | true | Removed | 1.74 | |
FullNetworkPoliciesInRuntimeCluster | false | Alpha | 1.66 | 1.70 |
FullNetworkPoliciesInRuntimeCluster | true | Beta | 1.71 | 1.72 |
FullNetworkPoliciesInRuntimeCluster | true | GA | 1.73 | 1.73 |
FullNetworkPoliciesInRuntimeCluster | true | Removed | 1.74 | |
DisableScalingClassesForShoots | false | Alpha | 1.73 | 1.78 |
DisableScalingClassesForShoots | true | Beta | 1.79 | 1.80 |
DisableScalingClassesForShoots | true | GA | 1.81 | 1.81 |
DisableScalingClassesForShoots | true | Removed | 1.82 |
Using a Feature
A feature can be in Alpha, Beta or GA stage. An Alpha feature means:
- Disabled by default.
- Might be buggy. Enabling the feature may expose bugs.
- Support for feature may be dropped at any time without notice.
- The API may change in incompatible ways in a later software release without notice.
- Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
A Beta feature means:
- Enabled by default.
- The feature is well tested. Enabling the feature is considered safe.
- Support for the overall feature will not be dropped, though details may change.
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
- Recommended for only non-critical uses because of potential for incompatible changes in subsequent releases.
Please do try Beta features and give feedback on them! After they exit beta, it may not be practical for us to make more changes.
A General Availability (GA) feature is also referred to as a stable feature. It means:
- The feature is always enabled; you cannot disable it.
- The corresponding feature gate is no longer needed.
- Stable versions of features will appear in released software for many subsequent versions.
List of Feature Gates
Feature | Relevant Components | Description |
---|---|---|
HVPA | gardenlet , gardener-operator | Enables simultaneous horizontal and vertical scaling in garden or seed clusters. |
HVPAForShootedSeed | gardenlet | Enables simultaneous horizontal and vertical scaling in managed seed (aka “shooted seed”) clusters. |
DefaultSeccompProfile | gardenlet , gardener-operator | Enables the defaulting of the seccomp profile for Gardener managed workload in the garden or seed to RuntimeDefault . |
CoreDNSQueryRewriting | gardenlet | Enables automatic DNS query rewriting in shoot cluster’s CoreDNS to shortcut name resolution of fully qualified in-cluster and out-of-cluster names, which follow a user-defined pattern. Details can be found in DNS Search Path Optimization. |
IPv6SingleStack | gardener-apiserver , gardenlet | Allows creating seed and shoot clusters with IPv6 single-stack networking enabled in their spec (GEP-21). If enabled in gardenlet, the default behavior is unchanged, but setting ipFamilies=[IPv6] in the seedConfig is allowed. Only if the ipFamilies setting is changed, gardenlet behaves differently. |
MutableShootSpecNetworkingNodes | gardener-apiserver | Allows updating the field spec.networking.nodes . The validity of the values has to be checked in the provider extensions. Only enable this feature gate when your system runs provider extensions which have implemented the validation. |
WorkerlessShoots | gardener-apiserver | WorkerlessShoots allows creation of Shoot clusters with no worker pools. |
MachineControllerManagerDeployment | gardenlet | Enables Gardener to take over the deployment of the machine-controller-manager. If enabled, all registered provider extensions must support injecting the provider-specific MCM sidecar container into the deployment via the controlplane webhook. |
ContainerdRegistryHostsDir | gardenlet | Enables registry configuration in containerd based on the hosts directory pattern. The hosts directory pattern is the new way of configuring registries/mirrors in containerd. Ref https://github.com/containerd/containerd/blob/main/docs/hosts.md. |
ShootForceDeletion | gardener-apiserver | Allows forceful deletion of Shoots by annotating them with the confirmation.gardener.cloud/force-deletion annotation. |
APIServerFastRollout | gardenlet | Enables fast rollouts for Shoot kube-apiservers on the given Seed. When enabled, maxSurge for Shoot kube-apiserver deployments is set to 100%. |
UseGardenerNodeAgent | gardenlet | Enables the gardener-node-agent instead of the cloud-config-downloader for shoot worker nodes. |
1.3.7 - Getting Started Locally
Deploying Gardener Locally
This document will walk you through deploying Gardener on your local machine. If you encounter difficulties, please open an issue so that we can make this process easier.
Overview
Gardener runs in any Kubernetes cluster. In this guide, we will start a KinD cluster which is used as both garden and seed cluster (please refer to the architecture overview) for simplicity.
Based on Skaffold, the container images for all required components will be built and deployed into the cluster (via their Helm charts).
Alternatives
When deploying Gardener on your local machine you might face several limitations:
- Your machine doesn’t have enough compute resources (see prerequisites) for hosting a second seed cluster or multiple shoot clusters.
- Testing Gardener’s IPv6 features requires a Linux machine and native IPv6 connectivity to the internet, but you’re on macOS or don’t have IPv6 connectivity in your office environment or via your home ISP.
In these cases, you might want to check out one of the following options that run the setup described in this guide elsewhere for circumventing these limitations:
- remote local setup: deploy on a remote pod for more compute resources
- dev box on Google Cloud: deploy on a Google Cloud machine for more compute resource and/or simple IPv4/IPv6 dual-stack networking
Prerequisites
- Make sure that you have followed the Local Setup guide up until the Get the sources step.
- Make sure your Docker daemon is up-to-date, up and running and has enough resources (at least
8
CPUs and8Gi
memory; see here how to configure the resources for Docker for Mac).Please note that 8 CPU / 8Gi memory might not be enough for more than two
Shoot
clusters, i.e., you might need to increase these values if you want to run additionalShoot
s. If you plan on following the optional steps to create a second seed cluster, the required resources will be more - at least10
CPUs and18Gi
memory. Additionally, please configure at least120Gi
of disk size for the Docker daemon. Tip: You can clean up unused data withdocker system df
anddocker system prune -a
.
Setting Up the KinD Cluster (Garden and Seed)
make kind-up
If you want to setup an IPv6 KinD cluster, use
make kind-up IPFAMILY=ipv6
instead.
This command sets up a new KinD cluster named gardener-local
and stores the kubeconfig in the ./example/gardener-local/kind/local/kubeconfig
file.
It might be helpful to copy this file to
$HOME/.kube/config
, since you will need to target this KinD cluster multiple times. Alternatively, make sure to set yourKUBECONFIG
environment variable to./example/gardener-local/kind/local/kubeconfig
for all future steps viaexport KUBECONFIG=$PWD/example/gardener-local/kind/local/kubeconfig
.
All of the following steps assume that you are using this kubeconfig.
Additionally, this command also deploys a local container registry to the cluster, as well as a few registry mirrors, that are set up as a pull-through cache for all upstream registries Gardener uses by default.
This is done to speed up image pulls across local clusters.
The local registry can be accessed as localhost:5001
for pushing and pulling.
The storage directories of the registries are mounted to the host machine under dev/local-registry
.
With this, mirrored images don’t have to be pulled again after recreating the cluster.
The command also deploys a default calico installation as the cluster’s CNI implementation with NetworkPolicy
support (the default kindnet
CNI doesn’t provide NetworkPolicy
support).
Furthermore, it deploys the metrics-server in order to support HPA and VPA on the seed cluster.
Setting Up IPv6 Single-Stack Networking (optional)
First, ensure that your /etc/hosts
file contains an entry resolving localhost
to the IPv6 loopback address:
::1 localhost
Typically, only ip6-localhost
is mapped to ::1
on linux machines.
However, we need localhost
to resolve to both 127.0.0.1
and ::1
so that we can talk to our registry via a single address (localhost:5001
).
Next, we need to configure NAT for outgoing traffic from the kind network to the internet.
After executing make kind-up IPFAMILY=ipv6
, execute the following command to set up the corresponding iptables rules:
ip6tables -t nat -A POSTROUTING -o $(ip route show default | awk '{print $5}') -s fd00:10::/64 -j MASQUERADE
Setting Up Gardener
make gardener-up
If you want to setup an IPv6 ready Gardener, use
make gardener-up IPFAMILY=ipv6
instead.
This will first build the base images (which might take a bit if you do it for the first time). Afterwards, the Gardener resources will be deployed into the cluster.
Developing Gardener
make gardener-dev
This is similar to make gardener-up
but additionally starts a skaffold dev loop.
After the initial deployment, skaffold starts watching source files.
Once it has detected changes, press any key to trigger a new build and deployment of the changed components.
Tip: you can set the SKAFFOLD_MODULE
environment variable to select specific modules of the skaffold configuration (see skaffold.yaml
) that skaffold should watch, build, and deploy.
This significantly reduces turnaround times during development.
For example, if you want to develop changes to gardenlet:
# initial deployment of all components
make gardener-up
# start iterating on gardenlet without deploying other components
make gardener-dev SKAFFOLD_MODULE=gardenlet
Debugging Gardener
make gardener-debug
This is using skaffold debugging features. In the Gardener case, Go debugging using Delve is the most relevant use case. Please see the skaffold debugging documentation how to setup your IDE accordingly.
SKAFFOLD_MODULE
environment variable is working the same way as described for Developing Gardener. However, skaffold is not watching for changes when debugging,
because it would like to avoid interrupting your debugging session.
For example, if you want to debug gardenlet:
# initial deployment of all components
make gardener-up
# start debugging gardenlet without deploying other components
make gardener-debug SKAFFOLD_MODULE=gardenlet
In debugging flow, skaffold builds your container images, reconfigures your pods and creates port forwardings for the Delve
debugging ports to your localhost.
The default port is 56268
. If you debug multiple pods at the same time, the port of the second pod will be forwarded to 56269
and so on.
Please check your console output for the concrete port-forwarding on your machine.
Note: Resuming or stopping only a single goroutine (Go Issue 25578, 31132) is currently not supported, so the action will cause all the goroutines to get activated or paused. (vscode-go wiki)
This means that when a goroutine of gardenlet (or any other gardener-core component you try to debug) is paused on a breakpoint, all the other goroutines are paused. Hence, when the whole gardenlet process is paused, it can not renew its lease and can not respond to the liveness and readiness probes. Skaffold automatically increases timeoutSeconds
of liveness and readiness probes to 600. Anyway, we were facing problems when debugging that pods have been killed after a while.
Thus, leader election, health and readiness checks for gardener-admission-controller
, gardener-apiserver
, gardener-controller-manager
, gardener-scheduler
,gardenlet
and operator
are disabled when debugging.
If you have similar problems with other components which are not deployed by skaffold, you could temporarily turn off the leader election and disable liveness and readiness probes there too.
Creating a Shoot
Cluster
You can wait for the Seed
to be ready by running:
./hack/usage/wait-for.sh seed local GardenletReady SeedSystemComponentsHealthy ExtensionsReady
Alternatively, you can run kubectl get seed local
and wait for the STATUS
to indicate readiness:
NAME STATUS PROVIDER REGION AGE VERSION K8S VERSION
local Ready local local 4m42s vX.Y.Z-dev v1.25.1
In order to create a first shoot cluster, just run:
kubectl apply -f example/provider-local/shoot.yaml
You can wait for the Shoot
to be ready by running:
NAMESPACE=garden-local ./hack/usage/wait-for.sh shoot local APIServerAvailable ControlPlaneHealthy ObservabilityComponentsHealthy EveryNodeReady SystemComponentsHealthy
Alternatively, you can run kubectl -n garden-local get shoot local
and wait for the LAST OPERATION
to reach 100%
:
NAME CLOUDPROFILE PROVIDER REGION K8S VERSION HIBERNATION LAST OPERATION STATUS AGE
local local local local 1.25.1 Awake Create Processing (43%) healthy 94s
If you don’t need any worker pools, you can create a workerless Shoot
by running:
kubectl apply -f example/provider-local/shoot-workerless.yaml
(Optional): You could also execute a simple e2e test (creating and deleting a shoot) by running:
make test-e2e-local-simple KUBECONFIG="$PWD/example/gardener-local/kind/local/kubeconfig"
Accessing the Shoot
Cluster
⚠️ Please note that in this setup, shoot clusters are not accessible by default when you download the kubeconfig and try to communicate with them.
The reason is that your host most probably cannot resolve the DNS names of the clusters since provider-local
extension runs inside the KinD cluster (for more details, see DNSRecord).
Hence, if you want to access the shoot cluster, you have to run the following command which will extend your /etc/hosts
file with the required information to make the DNS names resolvable:
cat <<EOF | sudo tee -a /etc/hosts
# Begin of Gardener local setup section
# Shoot API server domains
127.0.0.1 api.local.local.external.local.gardener.cloud
127.0.0.1 api.local.local.internal.local.gardener.cloud
# Ingress
127.0.0.1 p-seed.ingress.local.seed.local.gardener.cloud
127.0.0.1 g-seed.ingress.local.seed.local.gardener.cloud
127.0.0.1 gu-local--local.ingress.local.seed.local.gardener.cloud
127.0.0.1 p-local--local.ingress.local.seed.local.gardener.cloud
127.0.0.1 v-local--local.ingress.local.seed.local.gardener.cloud
# E2e tests
127.0.0.1 api.e2e-managedseed.garden.external.local.gardener.cloud
127.0.0.1 api.e2e-managedseed.garden.internal.local.gardener.cloud
127.0.0.1 api.e2e-hib.local.external.local.gardener.cloud
127.0.0.1 api.e2e-hib.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-hib-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-hib-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-unpriv.local.external.local.gardener.cloud
127.0.0.1 api.e2e-unpriv.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-wake-up.local.external.local.gardener.cloud
127.0.0.1 api.e2e-wake-up.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-wake-up-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-wake-up-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-migrate.local.external.local.gardener.cloud
127.0.0.1 api.e2e-migrate.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-migrate-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-migrate-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-rotate.local.external.local.gardener.cloud
127.0.0.1 api.e2e-rotate.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-rotate-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-rotate-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-default.local.external.local.gardener.cloud
127.0.0.1 api.e2e-default.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-default-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-default-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-force-delete.local.external.local.gardener.cloud
127.0.0.1 api.e2e-force-delete.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-fd-hib.local.external.local.gardener.cloud
127.0.0.1 api.e2e-fd-hib.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upd-node.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upd-node.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upd-node-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upd-node-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upgrade.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upgrade.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upgrade-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upgrade-wl.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upg-hib.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upg-hib.local.internal.local.gardener.cloud
127.0.0.1 api.e2e-upg-hib-wl.local.external.local.gardener.cloud
127.0.0.1 api.e2e-upg-hib-wl.local.internal.local.gardener.cloud
# End of Gardener local setup section
EOF
To access the Shoot
, you can acquire a kubeconfig
by using the shoots/adminkubeconfig
subresource.
For convenience a helper script is provided in the hack
directory. By default the script will generate a kubeconfig for a Shoot
named “local” in the garden-local
namespace valid for one hour.
./hack/usage/generate-admin-kubeconf.sh > admin-kubeconf.yaml
If you want to change the default namespace or shoot name, you can do so by passing different values as arguments.
./hack/usage/generate-admin-kubeconf.sh --namespace <namespace> --shoot-name <shootname> > admin-kubeconf.yaml
To access an Ingress resource from the Seed
, use the Ingress host with port 8448
(https://<ingress-host>:8448
, for example https://gu-local--local.ingress.local.seed.local.gardener.cloud:8448
).
(Optional): Setting Up a Second Seed Cluster
There are cases where you would want to create a second seed cluster in your local setup. For example, if you want to test the control plane migration feature. The following steps describe how to do that.
If you are on macOS, add a new IP address on your loopback device which will be necessary for the new KinD cluster that you will create. On macOS, the default loopback device is lo0
.
sudo ip addr add 127.0.0.2 dev lo0 # adding 127.0.0.2 ip to the loopback interface
Next, setup the second KinD cluster:
make kind2-up
This command sets up a new KinD cluster named gardener-local2
and stores its kubeconfig in the ./example/gardener-local/kind/local2/kubeconfig
file.
In order to deploy required resources in the KinD cluster that you just created, run:
make gardenlet-kind2-up
The following steps assume that you are using the kubeconfig that points to the gardener-local
cluster (first KinD cluster): export KUBECONFIG=$PWD/example/gardener-local/kind/local/kubeconfig
.
You can wait for the local2
Seed
to be ready by running:
./hack/usage/wait-for.sh seed local2 GardenletReady SeedSystemComponentsHealthy ExtensionsReady
Alternatively, you can run kubectl get seed local2
and wait for the STATUS
to indicate readiness:
NAME STATUS PROVIDER REGION AGE VERSION K8S VERSION
local2 Ready local local 4m42s vX.Y.Z-dev v1.25.1
If you want to perform control plane migration, you can follow the steps outlined in Control Plane Migration to migrate the shoot cluster to the second seed you just created.
Deleting the Shoot
Cluster
./hack/usage/delete shoot local garden-local
(Optional): Tear Down the Second Seed Cluster
make kind2-down
Tear Down the Gardener Environment
make kind-down
Remote Local Setup
Just like Prow is executing the KinD based integration tests in a K8s pod, it is possible to interactively run this KinD based Gardener development environment, aka “local setup”, in a “remote” K8s pod.
k apply -f docs/deployment/content/remote-local-setup.yaml
k exec -it deployment/remote-local-setup -- sh
tmux -u a
Caveats
Please refer to the TMUX documentation for working effectively inside the remote-local-setup pod.
To access Plutono, Prometheus or other components in a browser, two port forwards are needed:
The port forward from the laptop to the pod:
k port-forward deployment/remote-local-setup 3000
The port forward in the remote-local-setup pod to the respective component:
k port-forward -n shoot--local--local deployment/plutono 3000
Related Links
1.3.8 - Getting Started Locally With Extensions
Deploying Gardener Locally and Enabling Provider-Extensions
This document will walk you through deploying Gardener on your local machine and bootstrapping your own seed clusters on an existing Kubernetes cluster. It is supposed to run your local Gardener developments on a real infrastructure. For running Gardener only entirely local, please check the getting started locally documentation. If you encounter difficulties, please open an issue so that we can make this process easier.
Overview
Gardener runs in any Kubernetes cluster. In this guide, we will start a KinD cluster which is used as garden cluster. Any Kubernetes cluster could be used as seed clusters in order to support provider extensions (please refer to the architecture overview). This guide is tested for using Kubernetes clusters provided by Gardener, AWS, Azure, and GCP as seed so far.
Based on Skaffold, the container images for all required components will be built and deployed into the clusters (via their Helm charts).
Prerequisites
- Make sure that you have followed the Local Setup guide up until the Get the sources step.
- Make sure your Docker daemon is up-to-date, up and running and has enough resources (at least
8
CPUs and8Gi
memory; see the Docker documentation for how to configure the resources for Docker for Mac).Additionally, please configure at least
120Gi
of disk size for the Docker daemon. Tip: You can clean up unused data withdocker system df
anddocker system prune -a
. - Make sure that you have access to a Kubernetes cluster you can use as a seed cluster in this setup.
- The seed cluster requires at least 16 CPUs in total to run one shoot cluster
- You could use any Kubernetes cluster for your seed cluster. However, using a Gardener shoot cluster for your seed simplifies some configuration steps.
- When bootstrapping
gardenlet
to the cluster, your new seed will have the same provider type as the shoot cluster you use - an AWS shoot will become an AWS seed, a GCP shoot will become a GCP seed, etc. (only relevant when using a Gardener shoot as seed).
Provide Infrastructure Credentials and Configuration
As this setup is running on a real infrastructure, you have to provide credentials for DNS, the infrastructure, and the kubeconfig for the Kubernetes cluster you want to use as seed.
There are
.gitignore
entries for all files and directories which include credentials. Nevertheless, please double check and make sure that credentials are not committed to the version control system.
DNS
Gardener control plane requires DNS for default and internal domains. Thus, you have to configure a valid DNS provider for your setup.
Please maintain your DNS provider configuration and credentials at ./example/provider-extensions/garden/controlplane/domain-secrets.yaml
.
You can find a template for the file at ./example/provider-extensions/garden/controlplane/domain-secrets.yaml.tmpl
.
Infrastructure
Infrastructure secrets and the corresponding secret bindings should be maintained at:
./example/provider-extensions/garden/project/credentials/infrastructure-secrets.yaml
./example/provider-extensions/garden/project/credentials/secretbindings.yaml
There are templates with .tmpl
suffixes for the files in the same folder.
Projects
The projects and the namespaces associated with them should be maintained at ./example/provider-extensions/garden/project/project.yaml
.
You can find a template for the file at ./example/provider-extensions/garden/project/project.yaml.tmpl
.
Seed Cluster Preparation
The kubeconfig
of your Kubernetes cluster you would like to use as seed should be placed at ./example/provider-extensions/seed/kubeconfig
.
Additionally, please maintain the configuration of your seed in ./example/provider-extensions/gardenlet/values.yaml
. It is automatically copied from values.yaml.tmpl
in the same directory when you run make gardener-extensions-up
for the first time. It also includes explanations of the properties you should set.
Using a Gardener Shoot cluster as seed simplifies the process, because some configuration options can be taken from shoot-info
and creating DNS entries and TLS certificates is automated.
However, you can use different Kubernetes clusters for your seed too and configure these things manually. Please configure the options of ./example/provider-extensions/gardenlet/values.yaml
upfront. For configuring DNS and TLS certificates, make gardener-extensions-up
, which is explained later, will pause and tell you what to do.
External Controllers
You might plan to deploy and register external controllers for networking, operating system, providers, etc. Please put ControllerDeployment
s and ControllerRegistration
s into the ./example/provider-extensions/garden/controllerregistrations
directory. The whole content of this folder will be applied to your KinD cluster.
CloudProfile
s
There are no demo CloudProfiles
yet. Thus, please copy CloudProfiles
from another landscape to the ./example/provider-extensions/garden/cloudprofiles
directory or create your own CloudProfiles
based on the gardener examples. Please check the GitHub repository of your desired provider-extension. Most of them include example CloudProfile
s. All files you place in this folder will be applied to your KinD cluster.
Setting Up the KinD Cluster
make kind-extensions-up
This command sets up a new KinD cluster named gardener-local
and stores the kubeconfig in the ./example/gardener-local/kind/extensions/kubeconfig
file.
It might be helpful to copy this file to
$HOME/.kube/config
, since you will need to target this KinD cluster multiple times. Alternatively, make sure to set yourKUBECONFIG
environment variable to./example/gardener-local/kind/extensions/kubeconfig
for all future steps viaexport KUBECONFIG=$PWD/example/gardener-local/kind/extensions/kubeconfig
.
All of the following steps assume that you are using this kubeconfig.
Additionally, this command deploys a local container registry to the cluster as well as a few registry mirrors that are set up as a pull-through cache for all upstream registries Gardener uses by default.
This is done to speed up image pulls across local clusters.
The local registry can be accessed as localhost:5001
for pushing and pulling.
The storage directories of the registries are mounted to your machine under dev/local-registry
.
With this, mirrored images don’t have to be pulled again after recreating the cluster.
The command also deploys a default calico installation as the cluster’s CNI implementation with NetworkPolicy
support (the default kindnet
CNI doesn’t provide NetworkPolicy
support).
Furthermore, it deploys the metrics-server in order to support HPA and VPA on the seed cluster.
Setting Up Gardener (Garden on KinD, Seed on Gardener Cluster)
make gardener-extensions-up
This will first prepare the basic configuration of your KinD and Gardener clusters.
Afterwards, the images for the Garden cluster are built and deployed into the KinD cluster.
Finally, the images for the Seed cluster are built, pushed to a container registry on the Seed, and the gardenlet
is started.
Adding Additional Seeds
Additional seed(s) can be added by running
make gardener-extensions-up SEED_NAME=<seed-name>
The seed cluster preparations are similar to the first seed:
The kubeconfig
of your Kubernetes cluster you would like to use as seed should be placed at ./example/provider-extensions/seed/kubeconfig-<seed-name>
.
Additionally, please maintain the configuration of your seed in ./example/provider-extensions/gardenlet/values-<seed-name>.yaml
. It is automatically copied from values.yaml.tmpl
in the same directory when you run make gardener-extensions-up SEED_NAME=<seed-name>
for the first time. It also includes explanations of the properties you should set.
Removing a Seed
If you have multiple seeds and want to remove one, just use
make gardener-extensions-down SEED_NAME=<seed-name>
If it is not the last seed, this command will only remove the seed, but leave the local Gardener cluster and the other seeds untouched. To remove all seeds and to cleanup the local Gardener cluster, you have to run the command for each seed.
Pause and Unpause the KinD Cluster
The KinD cluster can be paused by stopping and keeping its docker container. This can be done by running:
make kind-extensions-down
When you run make kind-extensions-up
again, you will start the docker container with your previous Gardener configuration again.
This provides the option to switch off your local KinD cluster fast without leaving orphaned infrastructure elements behind.
Creating a Shoot
Cluster
You can wait for the Seed
to be ready by running:
kubectl wait --for=condition=gardenletready seed provider-extensions --timeout=5m
make kind-extensions-up
already includes such a check. However, it might be useful when you wake up your Seed
from hibernation or unpause you KinD cluster.
Alternatively, you can run kubectl get seed provider-extensions
and wait for the STATUS
to indicate readiness:
NAME STATUS PROVIDER REGION AGE VERSION K8S VERSION
provider-extensions Ready gcp europe-west1 111m v1.61.0-dev v1.24.7
In order to create a first shoot cluster, please create your own Shoot
definition and apply it to your KinD cluster. gardener-scheduler
includes candidateDeterminationStrategy: MinimalDistance
configuration so you are able to run schedule Shoot
s of different providers on your Seed
.
You can wait for your Shoot
s to be ready by running kubectl -n garden-local get shoots
and wait for the LAST OPERATION
to reach 100%
. The output depends on your Shoot
definition. This is an example output:
NAME CLOUDPROFILE PROVIDER REGION K8S VERSION HIBERNATION LAST OPERATION STATUS AGE
aws aws aws eu-west-1 1.24.3 Awake Create Processing (43%) healthy 84s
aws-arm64 aws aws eu-west-1 1.24.3 Awake Create Processing (43%) healthy 65s
azure az azure westeurope 1.24.2 Awake Create Processing (43%) healthy 57s
gcp gcp gcp europe-west1 1.24.3 Awake Create Processing (43%) healthy 94s
Accessing the Shoot
Cluster
Your shoot clusters will have a public DNS entries for their API servers, so that they could be reached via the Internet via kubectl
after you have created their kubeconfig
.
We encourage you to use the adminkubeconfig subresource for accessing your shoot cluster. You can find an example how to use it in Accessing Shoot Clusters.
Deleting the Shoot
Clusters
Before tearing down your environment, you have to delete your shoot clusters. This is highly recommended because otherwise you would leave orphaned items on your infrastructure accounts.
./hack/usage/delete shoot <your-shoot> garden-local
Tear Down the Gardener Environment
Before you delete your local KinD cluster, you should shut down your Shoots
and Seed
in a clean way to avoid orphaned infrastructure elements in your projects.
Please ensure that your KinD and Seed clusters are online (not paused or hibernated) and run:
make gardener-extensions-down
This will delete all Shoots
first (this could take a couple of minutes), then uninstall gardenlet
from the Seed and the gardener components from the KinD. Finally, the additional components like container registry, etc., are deleted from both clusters.
When this is done, you can securely delete your local KinD cluster by running:
make kind-extensions-clean
1.3.9 - Image Vector
Image Vector
The Gardenlet is deploying several different container images into the seed and the shoot clusters. The image repositories and tags are defined in a central image vector file. Obviously, the image versions defined there must fit together with the deployment manifests (e.g., some command-line flags do only exist in certain versions).
Example
images:
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: registry.k8s.io/pause
tag: "3.4"
version: "1.20.x"
architectures:
- amd64
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: registry.k8s.io/pause
tag: "3.5"
version: ">= 1.21"
architectures:
- amd64
...
That means that the Gardenlet will use the pause-container
with tag 3.4
for all seed/shoot clusters with Kubernetes version 1.20.x
, and tag 3.5
for all clusters with Kubernetes >= 1.21
.
Image Vector Architecture
images:
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: registry.k8s.io/pause
tag: "3.5"
architectures:
- amd64
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: registry.k8s.io/pause
tag: "3.5"
architectures:
- arm64
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: registry.k8s.io/pause
tag: "3.5"
architectures:
- amd64
- arm64
...
architectures
is an optional field of image. It is a list of strings specifying CPU architecture of machines on which this image can be used. The valid options for the architectures field are as follows:
amd64
: This specifies that the image can run only on machines having CPU architectureamd64
.arm64
: This specifies that the image can run only on machines having CPU architecturearm64
.
If an image doesn’t specify any architectures, then by default it is considered to support both amd64
and arm64
architectures.
Overwrite Image Vector
In some environments it is not possible to use these “pre-defined” images that come with a Gardener release.
A prominent example for that is Alicloud in China, which does not allow access to Google’s GCR.
In these cases, you might want to overwrite certain images, e.g., point the pause-container
to a different registry.
⚠️ If you specify an image that does not fit to the resource manifest, then the seed/shoot reconciliation might fail.
In order to overwrite the images, you must provide a similar file to gardenlet:
images:
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: my-custom-image-registry/pause
tag: "3.4"
version: "1.20.x"
- name: pause-container
sourceRepository: github.com/kubernetes/kubernetes/blob/master/build/pause/Dockerfile
repository: my-custom-image-registry/pause
tag: "3.5"
version: ">= 1.21"
...
During deployment of the gardenlet, create a ConfigMap
containing the above content and mount it as a volume into the gardenlet pod.
Next, specify the environment variable IMAGEVECTOR_OVERWRITE
, whose value must be the path to the file you just mounted:
apiVersion: v1
kind: ConfigMap
metadata:
name: gardenlet-images-overwrite
namespace: garden
data:
images_overwrite.yaml: |
images:
- ...
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: gardenlet
namespace: garden
spec:
template:
...
spec:
containers:
- name: gardenlet
env:
- name: IMAGEVECTOR_OVERWRITE
value: /charts-overwrite/images_overwrite.yaml
volumeMounts:
- name: gardenlet-images-overwrite
mountPath: /charts-overwrite
...
volumes:
- name: gardenlet-images-overwrite
configMap:
name: gardenlet-images-overwrite
...
Image Vectors for Dependent Components
The gardenlet is deploying a lot of different components that might deploy other images themselves. These components might use an image vector as well. Operators might want to customize the image locations for these transitive images as well, hence, they might need to specify an image vector overwrite for the components directly deployed by Gardener.
It is possible to specify the IMAGEVECTOR_OVERWRITE_COMPONENTS
environment variable to the gardenlet that points to a file with the following content:
components:
- name: etcd-druid
imageVectorOverwrite: |
images:
- name: etcd
tag: v1.2.3
repository: etcd/etcd
...
The gardenlet will, if supported by the directly deployed component (etcd-druid
in this example), inject the given imageVectorOverwrite
into the Deployment
manifest.
The respective component is responsible for using the overwritten images instead of its defaults.
1.3.10 - Migration V0 To V1
Migration from Gardener v0
to v1
Please refer to the document for older Gardener versions.
1.3.11 - Scoped API Access for gardenlets and Extensions
Scoped API Access for gardenlets and Extensions
By default, gardenlet
s have administrative access in the garden cluster.
They are able to execute any API request on any object independent of whether the object is related to the seed cluster the gardenlet
is responsible for.
As RBAC is not powerful enough for fine-grained checks and for the sake of security, Gardener provides two optional but recommended configurations for your environments that scope the API access for gardenlet
s.
Similar to the Node
authorization mode in Kubernetes, Gardener features a SeedAuthorizer
plugin.
It is a special-purpose authorization plugin that specifically authorizes API requests made by the gardenlet
s.
Likewise, similar to the NodeRestriction
admission plugin in Kubernetes, Gardener features a SeedRestriction
plugin.
It is a special-purpose admission plugin that specifically limits the Kubernetes objects gardenlet
s can modify.
📚 You might be interested to look into the design proposal for scoped Kubelet API access from the Kubernetes community.
It can be translated to Gardener and Gardenlets with their Seed
and Shoot
resources.
Historically, gardenlet
has been the only component running in the seed cluster that has access to both the seed cluster and the garden cluster.
Starting from Gardener v1.74.0
, extensions running on seed clusters can also get access to the garden cluster using a token for a dedicated ServiceAccount.
Extensions using this mechanism only get permission to read global resources like CloudProfiles
(this is granted to all authenticated users) unless the plugins described in this document are enabled.
Generally, the plugins handle extension clients exactly like gardenlet clients with some minor exceptions.
Extension clients in the sense of the plugins are clients authenticated as a ServiceAccount
with the extension-
name prefix in a seed-
namespace of the garden cluster.
Other ServiceAccounts
are not considered as seed clients, not handled by the plugins, and only get the described read access to global resources.
Flow Diagram
The following diagram shows how the two plugins are included in the request flow of a gardenlet
.
When they are not enabled, then the kube-apiserver
is internally authorizing the request via RBAC before forwarding the request directly to the gardener-apiserver
, i.e., the gardener-admission-controller
would not be consulted (this is not entirely correct because it also serves other admission webhook handlers, but for simplicity reasons this document focuses on the API access scope only).
When enabling the plugins, there is one additional step for each before the gardener-apiserver
responds to the request.
Please note that the example shows a request to an object (Shoot
) residing in one of the API groups served by gardener-apiserver
.
However, the gardenlet
is also interacting with objects in API groups served by the kube-apiserver
(e.g., Secret
,ConfigMap
).
In this case, the consultation of the SeedRestriction
admission plugin is performed by the kube-apiserver
itself before it forwards the request to the gardener-apiserver
.
Implemented Rules
Today, the following rules are implemented:
Resource | Verbs | Path(s) | Description |
---|---|---|---|
BackupBucket | get , list , watch , create , update , patch , delete | BackupBucket -> Seed | Allow get , list , watch requests for all BackupBucket s. Allow only create , update , patch , delete requests for BackupBucket s assigned to the gardenlet ’s Seed . |
BackupEntry | get , list , watch , create , update , patch | BackupEntry -> Seed | Allow get , list , watch requests for all BackupEntry s. Allow only create , update , patch requests for BackupEntry s assigned to the gardenlet ’s Seed and referencing BackupBucket s assigned to the gardenlet ’s Seed . |
Bastion | get , list , watch , create , update , patch | Bastion -> Seed | Allow get , list , watch requests for all Bastion s. Allow only create , update , patch requests for Bastion s assigned to the gardenlet ’s Seed . |
CertificateSigningRequest | get , create | CertificateSigningRequest -> Seed | Allow only get , create requests for CertificateSigningRequest s related to the gardenlet ’s Seed . |
CloudProfile | get | CloudProfile -> Shoot -> Seed | Allow only get requests for CloudProfile s referenced by Shoot s that are assigned to the gardenlet ’s Seed . |
ClusterRoleBinding | create , get , update , patch , delete | ClusterRoleBinding -> ManagedSeed -> Shoot -> Seed | Allow create , get , update , patch requests for ManagedSeed s in the bootstrapping phase assigned to the gardenlet’s Seed s. Allow delete requests from gardenlets bootstrapped via ManagedSeed s. |
ConfigMap | get | ConfigMap -> Shoot -> Seed | Allow only get requests for ConfigMap s referenced by Shoot s that are assigned to the gardenlet ’s Seed . Allows reading the kube-system/cluster-identity ConfigMap . |
ControllerRegistration | get , list , watch | ControllerRegistration -> ControllerInstallation -> Seed | Allow get , list , watch requests for all ControllerRegistration s. |
ControllerDeployment | get | ControllerDeployment -> ControllerInstallation -> Seed | Allow get requests for ControllerDeployments s referenced by ControllerInstallation s assigned to the gardenlet ’s Seed . |
ControllerInstallation | get , list , watch , update , patch | ControllerInstallation -> Seed | Allow get , list , watch requests for all ControllerInstallation s. Allow only update , patch requests for ControllerInstallation s assigned to the gardenlet ’s Seed . |
Event | create , patch | none | Allow to create or patch all kinds of Event s. |
ExposureClass | get | ExposureClass -> Shoot -> Seed | Allow get requests for ExposureClass es referenced by Shoot s that are assigned to the gardenlet ’s Seed . Deny get requests to other ExposureClass es. |
Lease | create , get , watch , update | Lease -> Seed | Allow create , get , update , and delete requests for Lease s of the gardenlet ’s Seed . |
ManagedSeed | get , list , watch , update , patch | ManagedSeed -> Shoot -> Seed | Allow get , list , watch requests for all ManagedSeed s. Allow only update , patch requests for ManagedSeed s referencing a Shoot assigned to the gardenlet ’s Seed . |
Namespace | get | Namespace -> Shoot -> Seed | Allow get requests for Namespace s of Shoot s that are assigned to the gardenlet ’s Seed . Always allow get requests for the garden Namespace . |
Project | get | Project -> Namespace -> Shoot -> Seed | Allow get requests for Project s referenced by the Namespace of Shoot s that are assigned to the gardenlet ’s Seed . |
SecretBinding | get | SecretBinding -> Shoot -> Seed | Allow only get requests for SecretBinding s referenced by Shoot s that are assigned to the gardenlet ’s Seed . |
Secret | create , get , update , patch , delete (, list , watch ) | Secret -> Seed , Secret -> Shoot -> Seed , Secret -> SecretBinding -> Shoot -> Seed , BackupBucket -> Seed | Allow get , list , watch requests for all Secret s in the seed-<name> namespace. Allow only create , get , update , patch , delete requests for the Secret s related to resources assigned to the gardenlet ’s Seed s. |
Seed | get , list , watch , create , update , patch , delete | Seed | Allow get , list , watch requests for all Seed s. Allow only create , update , patch , delete requests for the gardenlet ’s Seed s. [1] |
ServiceAccount | create , get , update , patch , delete | ServiceAccount -> ManagedSeed -> Shoot -> Seed , ServiceAccount -> Namespace -> Seed | Allow create , get , update , patch requests for ManagedSeed s in the bootstrapping phase assigned to the gardenlet ’s Seed s. Allow delete requests from gardenlets bootstrapped via ManagedSeed s. Allow all verbs on ServiceAccount s in seed-specific namespace. |
Shoot | get , list , watch , update , patch | Shoot -> Seed | Allow get , list , watch requests for all Shoot s. Allow only update , patch requests for Shoot s assigned to the gardenlet ’s Seed . |
ShootState | get , create , update , patch | ShootState -> Shoot -> Seed | Allow only get , create , update , patch requests for ShootState s belonging by Shoot s that are assigned to the gardenlet ’s Seed . |
[1] If you use
ManagedSeed
resources then thegardenlet
reconciling them (“parentgardenlet
”) may be allowed to submit certain requests for theSeed
resources resulting out of suchManagedSeed
reconciliations (even if the “parentgardenlet
” is not responsible for them):
ℹ️ It is allowed to delete the Seed
resources if the corresponding ManagedSeed
objects already have a deletionTimestamp
(this is secure as gardenlet
s themselves don’t have permissions for deleting ManagedSeed
s).
Rule Exceptions for Extension Clients
Extension clients are allowed to perform the same operations as gardenlet clients with the following exceptions:
- Extension clients are granted the read-only subset of verbs for
CertificateSigningRequests
,ClusterRoleBindings
, andServiceAccounts
(to prevent privilege escalation). - Extension clients are granted full access to
Lease
objects but only in the seed-specific namespace.
When the need arises, more exceptions might be added to the access rules for resources that are already handled by the plugins.
E.g., if an extension needs to populate additional shoot-specific InternalSecrets
, according handling can be introduced.
Permissions for resources that are not handled by the plugins can be granted using additional RBAC rules (independent of the plugins).
SeedAuthorizer
Authorization Webhook Enablement
The SeedAuthorizer
is implemented as a Kubernetes authorization webhook and part of the gardener-admission-controller
component running in the garden cluster.
🎛 In order to activate it, you have to follow these steps:
Set the following flags for the
kube-apiserver
of the garden cluster (i.e., thekube-apiserver
whose API is extended by Gardener):--authorization-mode=RBAC,Node,Webhook
(please note thatWebhook
should appear afterRBAC
in the list [1];Node
might not be needed if you use a virtual garden cluster)--authorization-webhook-config-file=<path-to-the-webhook-config-file>
--authorization-webhook-cache-authorized-ttl=0
--authorization-webhook-cache-unauthorized-ttl=0
The webhook config file (stored at
<path-to-the-webhook-config-file>
) should look as follows:apiVersion: v1 kind: Config clusters: - name: garden cluster: certificate-authority-data: base64(CA-CERT-OF-GARDENER-ADMISSION-CONTROLLER) server: https://gardener-admission-controller.garden/webhooks/auth/seed users: - name: kube-apiserver user: {} contexts: - name: auth-webhook context: cluster: garden user: kube-apiserver current-context: auth-webhook
When deploying the Gardener
controlplane
Helm chart, set.global.rbac.seedAuthorizer.enabled=true
. This will ensure that the RBAC resources granting global access for allgardenlet
s will be deployed.Delete the existing RBAC resources granting global access for all
gardenlet
s by running:kubectl delete \ clusterrole.rbac.authorization.k8s.io/gardener.cloud:system:seeds \ clusterrolebinding.rbac.authorization.k8s.io/gardener.cloud:system:seeds \ --ignore-not-found
Please note that you should activate the SeedRestriction
admission handler as well.
[1] The reason for the fact that
Webhook
authorization plugin should appear afterRBAC
is that thekube-apiserver
will be depending on thegardener-admission-controller
(serving the webhook). However, thegardener-admission-controller
can only start whengardener-apiserver
runs, butgardener-apiserver
itself can only start whenkube-apiserver
runs. IfWebhook
is beforeRBAC
, thengardener-apiserver
might not be able to start, leading to a deadlock.
Authorizer Decisions
As mentioned earlier, it’s the authorizer’s job to evaluate API requests and return one of the following decisions:
DecisionAllow
: The request is allowed, further configured authorizers won’t be consulted.DecisionDeny
: The request is denied, further configured authorizers won’t be consulted.DecisionNoOpinion
: A decision cannot be made, further configured authorizers will be consulted.
For backwards compatibility, no requests are denied at the moment, so that they are still deferred to a subsequent authorizer like RBAC. Though, this might change in the future.
First, the SeedAuthorizer
extracts the Seed
name from the API request.
This step considers the following two cases:
- If the authenticated user belongs to the
gardener.cloud:system:seeds
group, it is considered a gardenlet client.- This requires a proper TLS certificate that the
gardenlet
uses to contact the API server and is automatically given if TLS bootstrapping is used. - The authorizer extracts the seed name from the username by stripping the
gardener.cloud:system:seed:
prefix. - In cases where this information is missing e.g., when a custom Kubeconfig is used, the authorizer cannot make any decision. Thus, RBAC is still a considerable option to restrict the
gardenlet
’s access permission if the above explained preconditions are not given.
- This requires a proper TLS certificate that the
- If the authenticated user belongs to the
system:serviceaccounts
group, it is considered an extension client under the following conditions:- The
ServiceAccount
must be located in aseed-
namespace. I.e., the user has to belong to a group with thesystem:serviceaccounts:seed-
prefix. The seed name is extracted from this group by stripping the prefix. - The
ServiceAccount
must have theextension-
prefix. I.e., the username must have thesystem:serviceaccount:seed-<seed-name>:extension-
prefix.
- The
With the Seed
name at hand, the authorizer checks for an existing path from the resource that a request is being made for to the Seed
belonging to the gardenlet
/extension.
Take a look at the Implementation Details section for more information.
Implementation Details
Internally, the SeedAuthorizer
uses a directed, acyclic graph data structure in order to efficiently respond to authorization requests for gardenlet
s/extensions:
- A vertex in this graph represents a Kubernetes resource with its kind, namespace, and name (e.g.,
Shoot:garden-my-project/my-shoot
). - An edge from vertex
u
to vertexv
in this graph exists when- (1)
v
is referred byu
andv
is aSeed
, or when - (2)
u
is referred byv
, or when - (3)
u
is strictly associated withv
.
- (1)
For example, a Shoot
refers to a Seed
, a CloudProfile
, a SecretBinding
, etc., so it has an outgoing edge to the Seed
(1) and incoming edges from the CloudProfile
and SecretBinding
vertices (2).
However, there might also be a ShootState
or a BackupEntry
resource strictly associated with this Shoot
, hence, it has incoming edges from these vertices (3).
In the above picture, the resources that are actively watched are shaded. Gardener resources are green, while Kubernetes resources are blue. It shows the dependencies between the resources and how the graph is built based on the above rules.
ℹ️ The above picture shows all resources that may be accessed by gardenlet
s/extensions, except for the Quota
resource which is only included for completeness.
Now, when a gardenlet
/extension wants to access certain resources, then the SeedAuthorizer
uses a Depth-First traversal starting from the vertex representing the resource in question, e.g., from a Project
vertex.
If there is a path from the Project
vertex to the vertex representing the Seed
the gardenlet
/extension is responsible for. then it allows the request.
Metrics
The SeedAuthorizer
registers the following metrics related to the mentioned graph implementation:
Metric | Description |
---|---|
gardener_admission_controller_seed_authorizer_graph_update_duration_seconds | Histogram of duration of resource dependency graph updates in seed authorizer, i.e., how long does it take to update the graph’s vertices/edges when a resource is created, changed, or deleted. |
gardener_admission_controller_seed_authorizer_graph_path_check_duration_seconds | Histogram of duration of checks whether a path exists in the resource dependency graph in seed authorizer. |
Debug Handler
When the .server.enableDebugHandlers
field in the gardener-admission-controller
’s component configuration is set to true
, then it serves a handler that can be used for debugging the resource dependency graph under /debug/resource-dependency-graph
.
🚨 Only use this setting for development purposes, as it enables unauthenticated users to view all data if they have access to the gardener-admission-controller
component.
The handler renders an HTML page displaying the current graph with a list of vertices and its associated incoming and outgoing edges to other vertices.
Depending on the size of the Gardener landscape (and consequently, the size of the graph), it might not be possible to render it in its entirety.
If there are more than 2000 vertices, then the default filtering will selected for kind=Seed
to prevent overloading the output.
Example output:
-------------------------------------------------------------------------------
|
| # Seed:my-seed
| <- (11)
| BackupBucket:73972fe2-3d7e-4f61-a406-b8f9e670e6b7
| BackupEntry:garden-my-project/shoot--dev--my-shoot--4656a460-1a69-4f00-9372-7452cbd38ee3
| ControllerInstallation:dns-external-mxt8m
| ControllerInstallation:extension-shoot-cert-service-4qw5j
| ControllerInstallation:networking-calico-bgrb2
| ControllerInstallation:os-gardenlinux-qvb5z
| ControllerInstallation:provider-gcp-w4mvf
| Secret:garden/backup
| Shoot:garden-my-project/my-shoot
|
-------------------------------------------------------------------------------
|
| # Shoot:garden-my-project/my-shoot
| <- (5)
| CloudProfile:gcp
| Namespace:garden-my-project
| Secret:garden-my-project/my-dns-secret
| SecretBinding:garden-my-project/my-credentials
| ShootState:garden-my-project/my-shoot
| -> (1)
| Seed:my-seed
|
-------------------------------------------------------------------------------
|
| # ShootState:garden-my-project/my-shoot
| -> (1)
| Shoot:garden-my-project/my-shoot
|
-------------------------------------------------------------------------------
... (etc., similarly for the other resources)
There are anchor links to easily jump from one resource to another, and the page provides means for filtering the results based on the kind
, namespace
, and/or name
.
Pitfalls
When there is a relevant update to an existing resource, i.e., when a reference to another resource is changed, then the corresponding vertex (along with all associated edges) is first deleted from the graph before it gets added again with the up-to-date edges.
However, this does only work for vertices belonging to resources that are only created in exactly one “watch handler”.
For example, the vertex for a SecretBinding
can either be created in the SecretBinding
handler itself or in the Shoot
handler.
In such cases, deleting the vertex before (re-)computing the edges might lead to race conditions and potentially renders the graph invalid.
Consequently, instead of deleting the vertex, only the edges the respective handler is responsible for are deleted.
If the vertex ends up with no remaining edges, then it also gets deleted automatically.
Afterwards, the vertex can either be added again or the updated edges can be created.
SeedRestriction
Admission Webhook Enablement
The SeedRestriction
is implemented as Kubernetes admission webhook and part of the gardener-admission-controller
component running in the garden cluster.
🎛 In order to activate it, you have to set .global.admission.seedRestriction.enabled=true
when using the Gardener controlplane
Helm chart.
This will add an additional webhook in the existing ValidatingWebhookConfiguration
of the gardener-admission-controller
which contains the configuration for the SeedRestriction
handler.
Please note that it should only be activated when the SeedAuthorizer
is active as well.
Admission Decisions
The admission’s purpose is to perform extended validation on requests which require the body of the object in question.
Additionally, it handles CREATE
requests of gardenlet
s/extensions (the above discussed resource dependency graph cannot be used in such cases because there won’t be any vertex/edge for non-existing resources).
Gardenlets/extensions are restricted to only create new resources which are somehow related to the seed clusters they are responsible for.
1.3.12 - Secret Binding Provider Controller
SecretBinding Provider Controller
This page describes the process on how to enable the SecretBinding provider controller.
Overview
With Gardener v1.38.0, the SecretBinding resource now contains a new optional field .provider.type
(details about the motivation can be found in https://github.com/gardener/gardener/issues/4888). To make the process of setting the new field automated and afterwards to enforce validation on the new field in backwards compatible manner, Gardener features the SecretBinding provider controller and a feature gate - SecretBindingProviderValidation
.
Process
A Gardener landscape operator can follow the following steps:
Enable the SecretBinding provider controller of Gardener Controller Manager.
The SecretBinding provider controller is responsible for populating the
.provider.type
field of a SecretBinding based on its current usage by Shoot resources. For example, if a Shootcrazy-botany
with.provider.type=aws
is using a SecretBindingmy-secret-binding
, then the SecretBinding provider controller will take care to set the.provider.type
field of the SecretBinding to the same provider type (aws
). To enable the SecretBinding provider controller, set thecontroller.secretBindingProvider.concurentSyncs
field in the ControllerManagerConfiguration (e.g set it to5
). Although that it is not recommended, the API allows Shoots from different provider types to reference the same SecretBinding (assuming that the backing Secret contains data for both of the provider types). To preserve the backwards compatibility for such SecretBindings, the provider controller will maintain the multiple provider types in the field (it will join them with the separator,
- for exampleaws,gcp
).Disable the SecretBinding provider controller and enable the
SecretBindingProviderValidation
feature gate of Gardener API server.The
SecretBindingProviderValidation
feature gate of Gardener API server enables a set of validations for the SecretBinding provider field. It forbids creating a Shoot that has a different provider type from the referenced SecretBinding’s one. It also enforces immutability on the field. After making sure that SecretBinding provider controller is enabled and it populated the.provider.type
field of a majority of the SecretBindings on a Gardener landscape (the SecretBindings that are unused will have their provider type unset), a Gardener landscape operator has to disable the SecretBinding provider controller and to enable theSecretBindingProviderValidation
feature gate of Gardener API server. To disable the SecretBinding provider controller, set thecontroller.secretBindingProvider.concurentSyncs
field in the ControllerManagerConfiguration to0
.
Implementation History
- Gardener v1.38: The SecretBinding resource has a new optional field
.provider.type
. The SecretBinding provider controller is disabled by default. TheSecretBindingProviderValidation
feature gate of Gardener API server is disabled by default. - Gardener v1.42: The SecretBinding provider controller is enabled by default.
- Gardener v1.51: The
SecretBindingProviderValidation
feature gate of Gardener API server is enabled by default and the SecretBinding provider controller is disabled by default. - Gardener v1.53: The
SecretBindingProviderValidation
feature gate of Gardener API server is unconditionally enabled (can no longer be disabled). - Gardener v1.55: The
SecretBindingProviderValidation
feature gate of Gardener API server and the SecretBinding provider controller are removed.
1.3.13 - Setup Gardener
Deploying Gardener into a Kubernetes Cluster
Similar to Kubernetes, Gardener consists out of control plane components (Gardener API server, Gardener controller manager, Gardener scheduler), and an agent component (gardenlet). The control plane is deployed in the so-called garden cluster, while the agent is installed into every seed cluster. Please note that it is possible to use the garden cluster as seed cluster by simply deploying the gardenlet into it.
We are providing Helm charts in order to manage the various resources of the components. Please always make sure that you use the Helm chart version that matches the Gardener version you want to deploy.
Deploying the Gardener Control Plane (API Server, Admission Controller, Controller Manager, Scheduler)
The configuration values depict the various options to configure the different components. Please consult Gardener Configuration and Usage for component specific configurations and Authentication of Gardener Control Plane Components Against the Garden Cluster for authentication related specifics.
Also, note that all resources and deployments need to be created in the garden
namespace (not overrideable).
If you enable the Gardener admission controller as part of you setup, please make sure the garden
namespace is labelled with app: gardener
.
Otherwise, the backing service account for the admission controller Pod might not be created successfully.
No action is necessary if you deploy the garden
namespace with the Gardener control plane Helm chart.
After preparing your values in a separate controlplane-values.yaml
file (values.yaml can be used as starting point), you can run the following command against your garden cluster:
helm install charts/gardener/controlplane \
--namespace garden \
--name gardener-controlplane \
-f controlplane-values.yaml \
--wait
Deploying Gardener Extensions
Gardener is an extensible system that does not contain the logic for provider-specific things like DNS management, cloud infrastructures, network plugins, operating system configs, and many more.
You have to install extension controllers for these parts. Please consult the documentation regarding extensions to get more information.
Deploying the Gardener Agent (gardenlet)
Please refer to Deploying Gardenlets on how to deploy a gardenlet.
1.3.14 - Version Skew Policy
Version Skew Policy
This document describes the maximum version skew supported between various Gardener components.
Supported Gardener Versions
Gardener versions are expressed as x.y.z
, where x
is the major version, y
is the minor version, and z
is the patch version, following Semantic Versioning terminology.
The Gardener project maintains release branches for the three most recent minor releases.
Applicable fixes, including security fixes, may be backported to those three release branches, depending on severity and feasibility. Patch releases are cut from those branches at a regular cadence, plus additional urgent releases when required.
For more information, see the Releases document.
Supported Version Skew
Technically, we follow the same policy as the Kubernetes project.
However, given that our release cadence is much more frequent compared to Kubernetes (every 14d
vs. every 120d
), in many cases it might be possible to skip versions, though we do not test these upgrade paths.
Consequently, in general it might not work, and to be on the safe side, it is highly recommended to follow the described policy.
🚨 Note that downgrading Gardener versions is generally not tested during development and should be considered unsupported.
gardener-apiserver
In multi-instance setups of Gardener, the newest and oldest gardener-apiserver
instances must be within one minor version.
Example:
- newest
gardener-apiserver
is at 1.37 - other
gardener-apiserver
instances are supported at 1.37 and 1.36
gardener-controller-manager, gardener-scheduler, gardener-admission-controller, gardenlet
gardener-controller-manager
, gardener-scheduler
, gardener-admission-controller
, and gardenlet
must not be newer than the gardener-apiserver
instances they communicate with.
They are expected to match the gardener-apiserver
minor version, but may be up to one minor version older (to allow live upgrades).
Example:
gardener-apiserver
is at 1.37gardener-controller-manager
,gardener-scheduler
,gardener-admission-controller
, andgardenlet
are supported at 1.37 and 1.36
gardener-operator
Since gardener-operator
manages the Gardener control plane components (gardener-apiserver
, gardener-controller-manager
, gardener-scheduler
, gardener-admission-controller
), it follows the same policy as for gardener-apiserver
.
It implements additional start-up checks to ensure adherence to this policy.
Concretely, gardener-operator
will crash when
- its gets downgraded.
- its version gets upgraded and skips at least one minor version.
Supported Component Upgrade Order
The supported version skew between components has implications on the order in which components must be upgraded. This section describes the order in which components must be upgraded to transition an existing Gardener installation from version 1.37 to version 1.38.
gardener-apiserver
Prerequisites:
- In a single-instance setup, the existing
gardener-apiserver
instance is 1.37. - In a multi-instance setup, all
gardener-apiserver
instances are at 1.37 or 1.38 (this ensures maximum skew of 1 minor version between the oldest and newestgardener-apiserver
instance). - The
gardener-controller-manager
,gardener-scheduler
,gardener-admission-controller
, andgardenlet
instances that communicate with thisgardener-apiserver
are at version 1.37 (this ensures they are not newer than the existing API server version and are within 1 minor version of the new API server version).
Actions:
- Upgrade
gardener-apiserver
to 1.38.
gardener-controller-manager, gardener-scheduler, gardener-admission-controller, gardenlet
Prerequisites:
- The
gardener-apiserver
instances these components communicate with are at 1.38 (in multi-instance setups in which these components can communicate with anygardener-apiserver
instance in the cluster, allgardener-apiserver
instances must be upgraded before upgrading these components).
Actions:
- Upgrade
gardener-controller-manager
,gardener-scheduler
,gardener-admission-controller
, andgardenlet
to 1.38
gardener-operator
Prerequisites:
- All
gardener-operator
instances are at 1.37.
Actions:
- Upgrade
gardener-operator
to 1.38.
Supported Gardener Extension Versions
Extensions are maintained and released separately and independently of the gardener/gardener
repository.
Consequently, providing version constraints is not possible in this document.
Sometimes, the documentation of extensions contains compatibility information (e.g., “this extension version is only compatible with Gardener versions higher than 1.80”, see this example).
However, since all extensions typically make use of the extensions library (example), a general constraint is that no extension must depend on a version of the extensions library higher than the version of gardenlet
.
Example 1:
gardener-apiserver
and other Gardener control plane components are at 1.37.- All
gardenlet
s are at 1.37. - Only extensions are supported which depend on 1.37 or lower of the extensions library.
Example 2:
gardener-apiserver
and other Gardener control plane components are at 1.37.- Some
gardenlet
s are at 1.37, others are at 1.36. - Only extensions are supported which depend on 1.36 or lower of the extensions library.
Supported Kubernetes Versions
Please refer to Supported Kubernetes Versions.
1.4 - Extensions
1.4.1 - Access to the Garden Cluster for Extensions
Access to the Garden Cluster for Extensions
Extensions that are installed on seed clusters via a ControllerInstallation
can simply read the kubeconfig file specified by the GARDEN_KUBECONFIG
environment variable to create a garden cluster client.
With this, they use a short-lived token (valid for 12h
) associated with a dedicated ServiceAccount
in the seed-<seed-name>
namespace to securely access the garden cluster.
The used ServiceAccounts
are granted permissions in the garden cluster similar to gardenlet clients.
Background
Historically, gardenlet
has been the only component running in the seed cluster that has access to both the seed cluster and the garden cluster.
Accordingly, extensions running on the seed cluster didn’t have access to the garden cluster.
Starting from Gardener v1.74.0
, there is a new mechanism for components running on seed clusters to get access to the garden cluster.
For this, gardenlet
runs an instance of the TokenRequestor
for requesting tokens that can be used to communicate with the garden cluster.
Manually Requesting a Token for the Garden Cluster
Seed components that need to communicate with the garden cluster can request a token in the garden cluster by creating a garden access secret.
This secret has to be labelled with resources.gardener.cloud/purpose=token-requestor
and resources.gardener.cloud/class=garden
, e.g.:
apiVersion: v1
kind: Secret
metadata:
name: garden-access-example
namespace: example
labels:
resources.gardener.cloud/purpose: token-requestor
resources.gardener.cloud/class: garden
annotations:
serviceaccount.resources.gardener.cloud/name: example
type: Opaque
This will instruct gardenlet to create a new ServiceAccount
named example
in its own seed-<seed-name>
namespace in the garden cluster, request a token for it, and populate the token in the secret’s data under the token
key.
Using Gardenlet-Managed Garden Access
By default, extensions are equipped with secure access to the garden cluster using a dedicated ServiceAccount
without requiring any additional action.
They can simply read the file specified by the GARDEN_KUBECONFIG
and construct a garden client with it.
When installing a ControllerInstallation
, gardenlet creates two secrets in the installation’s namespace: a generic garden kubeconfig (generic-garden-kubeconfig-<hash>
) and a garden access secret (garden-access-extension
).
Additionally, it injects volume
, volumeMounts
, and two environment variables into all (init) containers in all objects in the apps
and batch
API groups:
GARDEN_KUBECONFIG
: points to the path where the generic garden kubeconfig is mounted.SEED_NAME
: set to the name of theSeed
where the extension is installed. This is useful for restricting watches in the garden cluster to relevant objects.
If an object already contains the GARDEN_KUBECONFIG
environment variable, it is not overwritten and injection of volume
and volumeMounts
is skipped.
For example, a Deployment
deployed via a ControllerInstallation
will be mutated as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
name: gardener-extension-provider-local
annotations:
reference.resources.gardener.cloud/secret-795f7ca6: garden-access-extension
reference.resources.gardener.cloud/secret-d5f5a834: generic-garden-kubeconfig-81fb3a88
spec:
template:
metadata:
annotations:
reference.resources.gardener.cloud/secret-795f7ca6: garden-access-extension
reference.resources.gardener.cloud/secret-d5f5a834: generic-garden-kubeconfig-81fb3a88
spec:
containers:
- name: gardener-extension-provider-local
env:
- name: GARDEN_KUBECONFIG
value: /var/run/secrets/gardener.cloud/garden/generic-kubeconfig/kubeconfig
- name: SEED_NAME
value: local
volumeMounts:
- mountPath: /var/run/secrets/gardener.cloud/garden/generic-kubeconfig
name: garden-kubeconfig
readOnly: true
volumes:
- name: garden-kubeconfig
projected:
defaultMode: 420
sources:
- secret:
items:
- key: kubeconfig
path: kubeconfig
name: generic-garden-kubeconfig-81fb3a88
optional: false
- secret:
items:
- key: token
path: token
name: garden-access-extension
optional: false
The generic garden kubeconfig will look like this:
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: LS0t...
server: https://garden.local.gardener.cloud:6443
name: garden
contexts:
- context:
cluster: garden
user: extension
name: garden
current-context: garden
users:
- name: extension
user:
tokenFile: /var/run/secrets/gardener.cloud/garden/generic-kubeconfig/token
Permissions in the Garden Cluster
Both the SeedAuthorizer
and the SeedRestriction
plugin handle extensions clients and generally grant the same permissions in the garden cluster to them as to gardenlet clients.
With this, extensions are restricted to work with objects in the garden cluster that are related to seed they are running one just like gardenlet.
Note that if the plugins are not enabled, extension clients are only granted read access to global resources like CloudProfiles
(this is granted to all authenticated users).
There are a few exceptions to the granted permissions as documented here.
If an extension needs access to additional resources in the garden cluster (e.g., extension-specific custom resources), permissions need to be granted via the usual RBAC means. Note that this is done outside of Gardener and might require an additional controller that manages RBAC for extension clients in the garden cluster.
Renewing All Garden Access Secrets
Operators can trigger an automatic renewal of all garden access secrets in a given Seed
and their requested ServiceAccount
tokens, e.g., when rotating the garden cluster’s ServiceAccount
signing key.
For this, the Seed
has to be annotated with gardener.cloud/operation=renew-garden-access-secrets
.
1.4.2 - Admission
Extension Admission
The extensions are expected to validate their respective resources for their extension specific configurations, when the resources are newly created or updated. For example, provider extensions would validate spec.provider.infrastructureConfig
and spec.provider.controlPlaneConfig
in the Shoot
resource and spec.providerConfig
in the CloudProfile
resource, networking extensions would validate spec.networking.providerConfig
in the Shoot
resource. As best practice, the validation should be performed only if there is a change in the spec
of the resource. Please find an exemplary implementation in the gardener/gardener-extension-provider-aws repository.
When a resource is newly created or updated, Gardener adds an extension label for all the extension types referenced in the spec
of the resource. This label is of the form <extension-type>.extensions.gardener.cloud/<extension-name> : "true"
. For example, an extension label for a provider extension type aws
looks like provider.extensions.gardener.cloud/aws : "true"
. The extensions should add object selectors in their admission webhooks for these labels, to filter out the objects they are responsible for. At present, these labels are added to BackupEntry
s, BackupBucket
s, CloudProfile
s, Seed
s, SecretBinding
s and Shoot
s. Please see the types_constants.go file for the full list of extension labels.
1.4.3 - BackupBucket
Contract: BackupBucket
Resource
The Gardener project features a sub-project called etcd-backup-restore to take periodic backups of etcd backing Shoot clusters. It demands the bucket (or its equivalent in different object store providers) to be created and configured externally with appropriate credentials. The BackupBucket
resource takes this responsibility in Gardener.
Before introducing the BackupBucket
extension resource, Gardener was using Terraform in order to create and manage these provider-specific resources (e.g., see AWS Backup).
Now, Gardener commissions an external, provider-specific controller to take over this task. You can also refer to backupInfra proposal documentation to get an idea about how the transition was done and understand the resource in a broader scope.
What Is the Scope of a Bucket?
A bucket will be provisioned per Seed
. So, a backup of every Shoot
created on that Seed
will be stored under a different shoot specific prefix under the bucket.
For the backup of the Shoot
rescheduled on different Seed
, it will continue to use the same bucket.
What Is the Lifespan of a BackupBucket
?
The bucket associated with BackupBucket
will be created at the creation of the Seed
. And as per current implementation, it will also be deleted on deletion of the Seed
, if there isn’t any BackupEntry
resource associated with it.
In the future, we plan to introduce a schedule for BackupBucket
- the deletion logic for the BackupBucket
resource, which will reschedule it on different available Seed
s on deletion or failure of a health check for the currently associated seed
. In that case, the BackupBucket
will be deleted only if there isn’t any schedulable Seed
available and there isn’t any associated BackupEntry
resource.
What Needs to Be Implemented to Support a New Infrastructure Provider?
As part of the seed flow, Gardener will create a special CRD in the seed cluster that needs to be reconciled by an extension controller, for example:
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: BackupBucket
metadata:
name: foo
spec:
type: azure
providerConfig:
<some-optional-provider-specific-backupbucket-configuration>
region: eu-west-1
secretRef:
name: backupprovider
namespace: shoot--foo--bar
The .spec.secretRef
contains a reference to the provider secret pointing to the account that shall be used to create the needed resources. This provider secret will be configured by the Gardener operator in the Seed
resource and propagated over there by the seed controller.
After your controller has created the required bucket, if required, it generates the secret to access the objects in the bucket and put a reference to it in status
. This secret is supposed to be used by Gardener, or eventually a BackupEntry
resource and etcd-backup-restore component, to backup the etcd.
In order to support a new infrastructure provider, you need to write a controller that watches all BackupBucket
s with .spec.type=<my-provider-name>
. You can take a look at the below referenced example implementation for the Azure provider.
References and Additional Resources
1.4.4 - BackupEntry
Contract: BackupEntry
Resource
The Gardener project features a sub-project called etcd-backup-restore to take periodic backups of etcd backing Shoot clusters. It demands the bucket (or its equivalent in different object store providers) access credentials to be created and configured externally with appropriate credentials. The BackupEntry
resource takes this responsibility in Gardener to provide this information by creating a secret specific to the component.
That being said, the core motivation for introducing this resource was to support retention of backups post deletion of Shoot
. The etcd-backup-restore components take responsibility of garbage collecting old backups out of the defined period. Once a shoot is deleted, we need to persist the backups for few days. Hence, Gardener uses the BackupEntry
resource for this housekeeping work post deletion of a Shoot
. The BackupEntry
resource is responsible for shoot specific prefix under referred bucket.
Before introducing the BackupEntry
extension resource, Gardener was using Terraform in order to create and manage these provider-specific resources (e.g., see AWS Backup).
Now, Gardener commissions an external, provider-specific controller to take over this task. You can also refer to backupInfra proposal documentation to get idea about how the transition was done and understand the resource in broader scope.
What Is the Lifespan of a BackupEntry
?
The bucket associated with BackupEntry
will be created by using a BackupBucket
resource. The BackupEntry
resource will be created as a part of the Shoot
creation. But resources might continue to exist post deletion of a Shoot
(see gardenlet for more details).
What Needs to be Implemented to Support a New Infrastructure Provider?
As part of the shoot flow, Gardener will create a special CRD in the seed cluster that needs to be reconciled by an extension controller, for example:
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: BackupEntry
metadata:
name: shoot--foo--bar
spec:
type: azure
providerConfig:
<some-optional-provider-specific-backup-bucket-configuration>
backupBucketProviderStatus:
<some-optional-provider-specific-backup-bucket-status>
region: eu-west-1
bucketName: foo
secretRef:
name: backupprovider
namespace: shoot--foo--bar
The .spec.secretRef
contains a reference to the provider secret pointing to the account that shall be used to create the needed resources. This provider secret will be propagated from the BackupBucket
resource by the shoot controller.
Your controller is supposed to create the etcd-backup
secret in the control plane namespace of a shoot. This secret is supposed to be used by Gardener or eventually by the etcd-backup-restore component to backup the etcd. The controller implementation should clean up the objects created under the shoot specific prefix in the bucket equivalent to the name of the BackupEntry
resource.
In order to support a new infrastructure provider, you need to write a controller that watches all the BackupBucket
s with .spec.type=<my-provider-name>
. You can take a look at the below referenced example implementation for the Azure provider.
References and Additional Resources
1.4.5 - Bastion
Contract: Bastion
Resource
The Gardener project allows users to connect to Shoot worker nodes via SSH. As nodes are usually firewalled and not directly accessible from the public internet, GEP-15 introduced the concept of “Bastions”. A bastion is a dedicated server that only serves to allow SSH ingress to the worker nodes.
Bastion
resources contain the user’s public SSH key and IP address, in order to provision the server accordingly: The public key is put onto the Bastion and SSH ingress is only authorized for the given IP address (in fact, it’s not a single IP address, but a set of IP ranges, however for most purposes a single IP is be used).
What Is the Lifespan of a Bastion
?
Once a Bastion
has been created in the garden, it will be replicated to the appropriate seed cluster, where a controller then reconciles a server and firewall rules etc., on the cloud provider used by the target Shoot. When the Bastion is ready (i.e. has a public IP), that IP is stored in the Bastion
’s status and from there it is picked up by the garden cluster and gardenctl
eventually.
To make multiple SSH sessions possible, the existence of the Bastion
is not directly tied to the execution of gardenctl
: users can exit out of gardenctl
and use ssh
manually to connect to the bastion and worker nodes.
However, Bastion
s have an expiry date, after which they will be garbage collected.
When SSH access is set to false
for the Shoot
in the workers settings (see Shoot Worker Nodes Settings), Bastion
resources are deleted during Shoot
reconciliation and new Bastion
s are prevented from being created.
What Needs to Be Implemented to Support a New Infrastructure Provider?
As part of the shoot flow, Gardener will create a special CRD in the seed cluster that needs to be reconciled by an extension controller, for example:
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: Bastion
metadata:
name: mybastion
namespace: shoot--foo--bar
spec:
type: aws
# userData is base64-encoded cloud provider user data; this contains the
# user's SSH key
userData: IyEvYmluL2Jhc2ggL....Nlcgo=
ingress:
- ipBlock:
cidr: 192.88.99.0/32 # this is most likely the user's IP address
Your controller is supposed to create a new instance at the given cloud provider, firewall it to only allow SSH (TCP port 22) from the given IP blocks, and then configure the firewall for the worker nodes to allow SSH from the bastion instance. When a Bastion
is deleted, all these changes need to be reverted.
Implementation Details
ConfigValidator
Interface
For bastion controllers, the generic Reconciler
also delegates to a ConfigValidator
interface that contains a single Validate
method. This method is called by the generic Reconciler
at the beginning of every reconciliation, and can be implemented by the extension to validate the .spec.providerConfig
part of the Bastion
resource with the respective cloud provider, typically the existence and validity of cloud provider resources such as VPCs, images, etc.
The Validate
method returns a list of errors. If this list is non-empty, the generic Reconciler
will fail with an error. This error will have the error code ERR_CONFIGURATION_PROBLEM
, unless there is at least one error in the list that has its ErrorType
field set to field.ErrorTypeInternal
.
References and Additional Resources
1.4.6 - CA Rotation
CA Rotation in Extensions
GEP-18 proposes adding support for automated rotation of Shoot cluster certificate authorities (CAs). This document outlines all the requirements that Gardener extensions need to fulfill in order to support the CA rotation feature.
Requirements for Shoot Cluster CA Rotation
- Extensions must not rely on static CA
Secret
names managed by the gardenlet, because their names are changing during CA rotation. - Extensions cannot issue or use client certificates for authenticating against shoot API servers. Instead, they should use short-lived auto-rotated
ServiceAccount
tokens via gardener-resource-manager’sTokenRequestor
. Also see Conventions andTokenRequestor
documents. - Extensions need to generate dedicated CAs for signing server certificates (e.g.
cloud-controller-manager
). There should be one CA per controller and purpose in order to bind the lifecycle to the reconciliation cycle of the respective object for which it is created. - CAs managed by extensions should be rotated in lock-step with the shoot cluster CA.
When the user triggers a rotation, the gardenlet writes phase and initiation time to
Shoot.status.credentials.rotation.certificateAuthorities.{phase,lastInitiationTime}
. See GEP-18 for a detailed description on what needs to happen in each phase. Extensions can retrieve this information fromCluster.shoot.status
.
Utilities for Secrets Management
In order to fulfill the requirements listed above, extension controllers can reuse the SecretsManager
that the gardenlet uses to manage all shoot cluster CAs, certificates, and other secrets as well.
It implements the core logic for managing secrets that need to be rotated, auto-renewed, etc.
Additionally, there are utilities for reusing SecretsManager
in extension controllers.
They already implement the above requirements based on the Cluster
resource and allow focusing on the extension controllers’ business logic.
For example, a simple SecretsManager
usage in an extension controller could look like this:
const (
// identity for SecretsManager instance in ControlPlane controller
identity = "provider-foo-controlplane"
// secret config name of the dedicated CA
caControlPlaneName = "ca-provider-foo-controlplane"
)
func Reconcile() {
var (
cluster *extensionscontroller.Cluster
client client.Client
// define wanted secrets with options
secretConfigs = []extensionssecretsmanager.SecretConfigWithOptions{
{
// dedicated CA for ControlPlane controller
Config: &secretutils.CertificateSecretConfig{
Name: caControlPlaneName,
CommonName: "ca-provider-foo-controlplane",
CertType: secretutils.CACert,
},
// persist CA so that it gets restored on control plane migration
Options: []secretsmanager.GenerateOption{secretsmanager.Persist()},
},
{
// server cert for control plane component
Config: &secretutils.CertificateSecretConfig{
Name: "cloud-controller-manager",
CommonName: "cloud-controller-manager",
DNSNames: kutil.DNSNamesForService("cloud-controller-manager", namespace),
CertType: secretutils.ServerCert,
},
// sign with our dedicated CA
Options: []secretsmanager.GenerateOption{secretsmanager.SignedByCA(caControlPlaneName)},
},
}
)
// initialize SecretsManager based on Cluster object
sm, err := extensionssecretsmanager.SecretsManagerForCluster(ctx, logger.WithName("secretsmanager"), clock.RealClock{}, client, cluster, identity, secretConfigs)
// generate all wanted secrets (first CAs, then the rest)
secrets, err := extensionssecretsmanager.GenerateAllSecrets(ctx, sm, secretConfigs)
// cleanup any secrets that are not needed any more (e.g. after rotation)
err = sm.Cleanup(ctx)
}
Please pay attention to the following points:
- There should be one
SecretsManager
identity per controller (and purpose if applicable) in order to prevent conflicts between different instances. E.g., there should be different identities forInfrastructrue
,Worker
controller, etc., and theControlPlane
controller should use dedicatedSecretsManager
identities per purpose (e.g.provider-foo-controlplane
andprovider-foo-controlplane-exposure
). - All other points in Reusing the SecretsManager in Other Components.
1.4.7 - Cluster
Cluster
Resource
As part of the extensibility epic, a lot of responsibility that was previously taken over by Gardener directly has now been shifted to extension controllers running in the seed clusters. These extensions often serve a well-defined purpose, e.g. the management of DNS records, infrastructure, etc. We have introduced a couple of extension CRDs in the seeds whose specification is written by Gardener, and which are acted up by the extensions.
However, the extensions sometimes require more information that is not directly part of the specification.
One example of that is the GCP infrastructure controller which needs to know the shoot’s pod and service network.
Another example is the Azure infrastructure controller which requires some information out of the CloudProfile
resource.
The problem is that Gardener does not know which extension requires which information so that it can write it into their specific CRDs.
In order to deal with this problem we have introduced the Cluster
extension resource.
This CRD is written into the seeds, however, it does not contain a status
, so it is not expected that something acts upon it.
Instead, you can treat it like a ConfigMap
which contains data that might be interesting for you.
In the context of Gardener, seeds and shoots, and extensibility the Cluster
resource contains the CloudProfile
, Seed
, and Shoot
manifest.
Extension controllers can take whatever information they want out of it that might help completing their individual tasks.
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: Cluster
metadata:
name: shoot--foo--bar
spec:
cloudProfile:
apiVersion: core.gardener.cloud/v1beta1
kind: CloudProfile
...
seed:
apiVersion: core.gardener.cloud/v1beta1
kind: Seed
...
shoot:
apiVersion: core.gardener.cloud/v1beta1
kind: Shoot
...
The resource is written by Gardener before it starts the reconciliation flow of the shoot.
⚠️ All Gardener components use the core.gardener.cloud/v1beta1
version, i.e., the Cluster
resource will contain the objects in this version.
Important Information that Should Be Taken into Account
There are some fields in the Shoot
specification that might be interesting to take into account.
.spec.hibernation.enabled={true,false}
: Extension controllers might want to behave differently if the shoot is hibernated or not (probably they might want to scale down their control plane components, for example)..status.lastOperation.state=Failed
: If Gardener sets the shoot’s last operation state toFailed
, it means that Gardener won’t automatically retry to finish the reconciliation/deletion flow because an error occurred that could not be resolved within the last24h
(default). In this case, end-users are expected to manually re-trigger the reconciliation flow in case they want Gardener to try again. Extension controllers are expected to follow the same principle. This means they have to read the shoot state out of theCluster
resource.
Extension Resources Not Associated with a Shoot
In some cases, Gardener may create extension resources that are not associated with a shoot, but are needed to support some functionality internal to Gardener. Such resources will be created in the garden
namespace of a seed cluster.
For example, if the managed ingress controller is active on the seed, Gardener will create a DNSRecord resource(s) in the garden
namespace of the seed cluster for the ingress DNS record.
Extension controllers that may be expected to reconcile extension resources in the garden
namespace should make sure that they can tolerate the absence of a cluster resource. This means that they should not attempt to read the cluster resource in such cases, or if they do they should ignore the “not found” error.
References and Additional Resources
1.4.8 - ContainerRuntime
Gardener Container Runtime Extension
At the lowest layers of a Kubernetes node is the software that, among other things, starts and stops containers. It is called “Container Runtime”. The most widely known container runtime is Docker, but it is not alone in this space. In fact, the container runtime space has been rapidly evolving.
Kubernetes supports different container runtimes using Container Runtime Interface (CRI) – a plugin interface which enables kubelet to use a wide variety of container runtimes.
Gardener supports creation of Worker machines using CRI. For more information, see CRI Support.
Motivation
Prior to the Container Runtime Extensibility
concept, Gardener used Docker as the only
container runtime to use in shoot worker machines. Because of the wide variety of different container runtimes
offering multiple important features (for example, enhanced security concepts), it is important to enable end users to use other container runtimes as well.
The ContainerRuntime
Extension Resource
Here is what a typical ContainerRuntime
resource would look like:
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: ContainerRuntime
metadata:
name: my-container-runtime
spec:
binaryPath: /var/bin/containerruntimes
type: gvisor
workerPool:
name: worker-ubuntu
selector:
matchLabels:
worker.gardener.cloud/pool: worker-ubuntu
Gardener deploys one ContainerRuntime
resource per worker pool per CRI.
To exemplify this, consider a Shoot having two worker pools (worker-one
, worker-two
) using containerd
as the CRI as well as gvisor
and kata
as enabled container runtimes.
Gardener would deploy four ContainerRuntime
resources. For worker-one
: one ContainerRuntime
for type gvisor
and one for type kata
. The same resource are being deployed for worker-two
.
Supporting a New Container Runtime Provider
To add support for another container runtime (e.g., gvisor, kata-containers), a container runtime extension controller needs to be implemented. It should support Gardener’s supported CRI plugins.
The container runtime extension should install the necessary resources into the shoot cluster (e.g., RuntimeClass
es), and it should copy the runtime binaries to the relevant worker machines in path: spec.binaryPath
.
Gardener labels the shoot nodes according to the CRI configured: worker.gardener.cloud/cri-name=<value>
(e.g worker.gardener.cloud/cri-name=containerd
) and multiple labels for each of the container runtimes configured for the shoot Worker machine:
containerruntime.worker.gardener.cloud/<container-runtime-type-value>=true
(e.g containerruntime.worker.gardener.cloud/gvisor=true
).
The way to install the binaries is by creating a daemon set which copies the binaries from an image in a docker registry to the relevant labeled Worker’s nodes (avoid downloading binaries from the internet to also cater with isolated environments).
For additional reference, please have a look at the runtime-gvsior provider extension, which provides more information on how to configure the necessary charts, as well as the actuators required to reconcile container runtime inside the Shoot
cluster to the desired state.
1.4.9 - ControllerRegistration
Registering Extension Controllers
Extensions are registered in the garden cluster via ControllerRegistration
resources.
Deployment for respective extensions are specified via ControllerDeployment
resources.
Gardener evaluates the registrations and deployments and creates ControllerInstallation
resources which describe the request “please install this controller X
to this seed Y
”.
Similar to how CloudProfile
or Seed
resources get into the system, the Gardener administrator must deploy the ControllerRegistration
and ControllerDeployment
resources (this does not happen automatically in any way - the administrator decides which extensions shall be enabled).
The specification mainly describes which of Gardener’s extension CRDs are managed, for example:
apiVersion: core.gardener.cloud/v1beta1
kind: ControllerDeployment
metadata:
name: os-gardenlinux
type: helm
providerConfig:
chart: H4sIFAAAAAAA/yk... # <base64-gzip-chart>
values:
foo: bar
---
apiVersion: core.gardener.cloud/v1beta1
kind: ControllerRegistration
metadata:
name: os-gardenlinux
spec:
deployment:
deploymentRefs:
- name: os-gardenlinux
resources:
- kind: OperatingSystemConfig
type: gardenlinux
primary: true
This information tells Gardener that there is an extension controller that can handle OperatingSystemConfig
resources of type gardenlinux
.
A reference to the shown ControllerDeployment
specifies how the deployment of the extension controller is accomplished.
Also, it specifies that this controller is the primary one responsible for the lifecycle of the OperatingSystemConfig
resource.
Setting primary
to false
would allow to register additional, secondary controllers that may also watch/react on the OperatingSystemConfig/coreos
resources, however, only the primary controller may change/update the main status
of the extension object (that are used to “communicate” with the gardenlet).
Particularly, only the primary controller may set .status.lastOperation
, .status.lastError
, .status.observedGeneration
, and .status.state
.
Secondary controllers may contribute to the .status.conditions[]
if they like, of course.
Secondary controllers might be helpful in scenarios where additional tasks need to be completed which are not part of the reconciliation logic of the primary controller but separated out into a dedicated extension.
⚠️ There must be exactly one primary controller for every registered kind/type combination.
Also, please note that the primary
field cannot be changed after creation of the ControllerRegistration
.
Deploying Extension Controllers
Submitting the above ControllerDeployment
and ControllerRegistration
will create a ControllerInstallation
resource:
apiVersion: core.gardener.cloud/v1beta1
kind: ControllerInstallation
metadata:
name: os-gardenlinux
spec:
deploymentRef:
name: os-gardenlinux
registrationRef:
name: os-gardenlinux
seedRef:
name: aws-eu1
This resource expresses that Gardener requires the os-gardenlinux
extension controller to run on the aws-eu1
seed cluster.
The Gardener Controller Manager does automatically determine which extension is required on which seed cluster and will only create ControllerInstallation
objects for those.
Also, it will automatically delete ControllerInstallation
s referencing extension controllers that are no longer required on a seed (e.g., because all shoots on it have been deleted).
There are additional configuration options, please see the Deployment Configuration Options section.
How do extension controllers get deployed to seeds?
After Gardener has written the ControllerInstallation
resource, some component must satisfy this request and start deploying the extension controller to the seed.
Depending on the complexity of the controller’s lifecycle management, configuration, etc., there are two possible scenarios:
Scenario 1: Deployed by Gardener
In many cases, the extension controllers are easy to deploy and configure.
It is sufficient to simply create a Helm chart (standardized way of packaging software in the Kubernetes context) and deploy it together with some static configuration values.
Gardener supports this scenario and allows to provide arbitrary deployment information in the ControllerDeployment
resource’s .providerConfig
section:
...
type: helm
providerConfig:
chart: H4sIFAAAAAAA/yk...
values:
foo: bar
If .type=helm
, then Gardener itself will take over the responsibility the deployment.
It base64-decodes the provided Helm chart (.providerConfig.chart
) and deploys it with the provided static configuration (.providerConfig.values
).
The chart and the values can be updated at any time - Gardener will recognize and re-trigger the deployment process.
In order to allow extensions to get information about the garden and the seed cluster, Gardener does mix-in certain properties into the values (root level) of every deployed Helm chart:
gardener:
garden:
identifier: <uuid-of-gardener-installation>
seed:
identifier: <seed-name>
region: europe
spec: <complete-seed-spec>
Extensions can use this information in their Helm chart in case they require knowledge about the garden and the seed environment. The list might be extended in the future.
ℹ️ Gardener uses the UUID of the garden
Namespace
object in the .gardener.garden.identifier
property.
Scenario 2: Deployed by a (Non-Human) Kubernetes Operator
Some extension controllers might be more complex and require additional domain-specific knowledge wrt. lifecycle or configuration.
In this case, we encourage to follow the Kubernetes operator pattern and deploy a dedicated operator for this extension into the garden cluster.
The ControllerDeployments
’s .type
field would then not be helm
, and no Helm chart or values need to be provided there.
Instead, the operator itself knows how to deploy the extension into the seed.
It must watch ControllerInstallation
resources and act one those referencing a ControllerRegistration
the operator is responsible for.
In order to let Gardener know that the extension controller is ready and running in the seed, the ControllerInstallation
’s .status
field supports two conditions: RegistrationValid
and InstallationSuccessful
- both must be provided by the responsible operator:
...
status:
conditions:
- lastTransitionTime: "2019-01-22T11:51:11Z"
lastUpdateTime: "2019-01-22T11:51:11Z"
message: Chart could be rendered successfully.
reason: RegistrationValid
status: "True"
type: Valid
- lastTransitionTime: "2019-01-22T11:51:12Z"
lastUpdateTime: "2019-01-22T11:51:12Z"
message: Installation of new resources succeeded.
reason: InstallationSuccessful
status: "True"
type: Installed
Additionally, the .status
field has a providerStatus
section into which the operator can (optionally) put any arbitrary data associated with this installation.
Extensions in the Garden Cluster Itself
The Shoot
resource itself will contain some provider-specific data blobs.
As a result, some extensions might also want to run in the garden cluster, e.g., to provide ValidatingWebhookConfiguration
s for validating the correctness of their provider-specific blobs:
apiVersion: core.gardener.cloud/v1beta1
kind: Shoot
metadata:
name: johndoe-aws
namespace: garden-dev
spec:
...
cloud:
type: aws
region: eu-west-1
providerConfig:
apiVersion: aws.cloud.gardener.cloud/v1alpha1
kind: InfrastructureConfig
networks:
vpc: # specify either 'id' or 'cidr'
# id: vpc-123456
cidr: 10.250.0.0/16
internal:
- 10.250.112.0/22
public:
- 10.250.96.0/22
workers:
- 10.250.0.0/19
zones:
- eu-west-1a
...
In the above example, Gardener itself does not understand the AWS-specific provider configuration for the infrastructure.
However, if this part of the Shoot
resource should be validated, then you should run an AWS-specific component in the garden cluster that registers a webhook. You can do it similarly if you want to default some fields of a resource (by using a MutatingWebhookConfiguration
).
Again, similar to how Gardener is deployed to the garden cluster, these components must be deployed and managed by the Gardener administrator.
Extension
Resource Configurations
The Extension
resource allows injecting arbitrary steps into the shoot reconciliation flow that are unknown to Gardener.
Hence, it is slightly special and allows further configuration when registering it:
apiVersion: core.gardener.cloud/v1beta1
kind: ControllerRegistration
metadata:
name: extension-foo
spec:
resources:
- kind: Extension
type: foo
primary: true
globallyEnabled: true
reconcileTimeout: 30s
lifecycle:
reconcile: AfterKubeAPIServer
delete: BeforeKubeAPIServer
migrate: BeforeKubeAPIServer
The globallyEnabled=true
option specifies that the Extension/foo
object shall be created by default for all shoots (unless they opted out by setting .spec.extensions[].enabled=false
in the Shoot
spec).
The reconcileTimeout
tells Gardener how long it should wait during its shoot reconciliation flow for the Extension/foo
’s reconciliation to finish.
Extension
Lifecycle
The lifecycle
field tells Gardener when to perform a certain action on the Extension
resource during the reconciliation flows. If omitted, then the default behaviour will be applied. Please find more information on the defaults in the explanation below. Possible values for each control flow are AfterKubeAPIServer
and BeforeKubeAPIServer
. Let’s take the following configuration and explain it.
...
lifecycle:
reconcile: AfterKubeAPIServer
delete: BeforeKubeAPIServer
migrate: BeforeKubeAPIServer
reconcile: AfterKubeAPIServer
means that the extension resource will be reconciled after the successful reconciliation of thekube-apiserver
during shoot reconciliation. This is also the default behaviour if this value is not specified. During shoot hibernation, the opposite rule is applied, meaning that in this case the reconciliation of the extension will happen before thekube-apiserver
is scaled to 0 replicas. On the other hand, if the extension needs to be reconciled before thekube-apiserver
and scaled down after it, then the valueBeforeKubeAPIServer
should be used.delete: BeforeKubeAPIServer
means that the extension resource will be deleted before thekube-apiserver
is destroyed during shoot deletion. This is the default behaviour if this value is not specified.migrate: BeforeKubeAPIServer
means that the extension resource will be migrated before thekube-apiserver
is destroyed in the source cluster during control plane migration. This is the default behaviour if this value is not specified. The restoration of the control plane follows the reconciliation control flow.
Deployment Configuration Options
The .spec.deployment
resource allows to configure a deployment policy
.
There are the following policies:
OnDemand
(default): Gardener will demand the deployment and deletion of the extension controller to/from seed clusters dynamically. It will automatically determine (based on other resources likeShoot
s) whether it is required and decide accordingly.Always
: Gardener will demand the deployment of the extension controller to seed clusters independent of whether it is actually required or not. This might be helpful if you want to add a new component/controller to all seed clusters by default. Another use-case is to minimize the durations until extension controllers get deployed and ready in case you have highly fluctuating seed clusters.AlwaysExceptNoShoots
: Similar toAlways
, but if the seed does not have any shoots, then the extension is not being deployed. It will be deleted from a seed after the last shoot has been removed from it.
Also, the .spec.deployment.seedSelector
allows to specify a label selector for seed clusters.
Only if it matches the labels of a seed, then it will be deployed to it.
Please note that a seed selector can only be specified for secondary controllers (primary=false
for all .spec.resources[]
).
1.4.10 - ControlPlane
Contract: ControlPlane
Resource
Most Kubernetes clusters require a cloud-controller-manager
or CSI drivers in order to work properly.
Before introducing the ControlPlane
extension resource Gardener was having several different Helm charts for the cloud-controller-manager
deployments for the various providers.
Now, Gardener commissions an external, provider-specific controller to take over this task.
Which control plane resources are required?
As mentioned in the controlplane customization webhooks document, Gardener shall not deploy any cloud-controller-manager
or any other provider-specific component.
Instead, it creates a ControlPlane
CRD that should be picked up by provider extensions.
Its purpose is to trigger the deployment of such provider-specific components in the shoot namespace in the seed cluster.
What needs to be implemented to support a new infrastructure provider?
As part of the shoot flow Gardener will create a special CRD in the seed cluster that needs to be reconciled by an extension controller, for example:
---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: ControlPlane
metadata:
name: control-plane
namespace: shoot--foo--bar
spec:
type: openstack
region: europe-west1
secretRef:
name: cloudprovider
namespace: shoot--foo--bar
providerConfig:
apiVersion: openstack.provider.extensions.gardener.cloud/v1alpha1
kind: ControlPlaneConfig
loadBalancerProvider: provider
zone: eu-1a
cloudControllerManager:
featureGates:
CustomResourceValidation: true
infrastructureProviderStatus:
apiVersion: openstack.provider.extensions.gardener.cloud/v1alpha1
kind: InfrastructureStatus
networks:
floatingPool:
id: vpc-1234
subnets:
- purpose: nodes
id: subnetid
The .spec.secretRef
contains a reference to the provider secret pointing to the account that shall be used for the shoot cluster.
However, the most important section is the .spec.providerConfig
and the .spec.infrastructureProviderStatus
.
The first one contains an embedded declaration of the provider specific configuration for the control plane (that cannot be known by Gardener itself).
You are responsible for designing how this configuration looks like.
Gardener does not evaluate it but just copies this part from what has been provided by the end-user in the Shoot
resource.
The second one contains the output of the Infrastructure
resource (that might be relevant for the CCM config).
In order to support a new control plane provider, you need to write a controller that watches all ControlPlane
s with .spec.type=<my-provider-name>
.
You can take a look at the below referenced example implementation for the Alicloud provider.
The control plane controller as part of the ControlPlane
reconciliation often deploys resources (e.g. pods/deployments) into the Shoot namespace in the Seed
as part of its ControlPlane
reconciliation loop.
Because the namespace contains network policies that per default deny all ingress and egress traffic,
the pods may need to have proper labels matching to the selectors of the network policies in order to allow the required network traffic.
Otherwise, they won’t be allowed to talk to certain other components (e.g., the kube-apiserver of the shoot).
For more information, see NetworkPolicy
s In Garden, Seed, Shoot Clusters.
Non-Provider Specific Information Required for Infrastructure Creation
Most providers might require further information that is not provider specific but already part of the shoot resource.
One example for this is the GCP control plane controller, which needs the Kubernetes version of the shoot cluster (because it already uses the in-tree Kubernetes cloud-controller-manager).
As Gardener cannot know which information is required by providers, it simply mirrors the Shoot
, Seed
, and CloudProfile
resources into the seed.
They are part of the Cluster
extension resource and can be used to extract information that is not part of the Infrastructure
resource itself.
References and Additional Resources
1.4.11 - ControlPlane Exposure
Contract: ControlPlane
Resource with Purpose exposure
Some Kubernetes clusters require an additional deployments required by the seed cloud provider in order to work properly, e.g. AWS Load Balancer Readvertiser.
Before using ControlPlane resources with purpose exposure
, Gardener was having different Helm charts for the deployments for the various providers.
Now, Gardener commissions an external, provider-specific controller to take over this task.
Which control plane resources are required?
As mentioned in the controlplane document, Gardener shall not deploy any other provider-specific component.
Instead, it creates a ControlPlane
CRD with purpose exposure
that should be picked up by provider extensions.
Its purpose is to trigger the deployment of such provider-specific components in the shoot namespace in the seed cluster that are needed to expose the kube-apiserver.
The shoot cluster’s kube-apiserver are exposed via a Service
of type LoadBalancer
from the shoot provider (you may run the control plane of an Azure shoot in a GCP seed). It’s the seed provider extension controller that should act on the ControlPlane
resources with purpose exposure
.
If SNI is enabled, then the Service
from above is of type ClusterIP
and Gardner will not create ControlPlane
resources with purpose exposure
.
What needs to be implemented to support a new infrastructure provider?
As part of the shoot flow, Gardener will create a special CRD in the seed cluster that needs to be reconciled by an extension controller, for example:
apiVersion: extensions.gardener.cloud/v1alpha1
kind: ControlPlane
metadata:
name: control-plane-exposure
namespace: shoot--foo--bar
spec:
type: aws
purpose: exposure
region: europe-west1
secretRef:
name: cloudprovider
namespace: shoot--foo--bar
The .spec.secretRef
contains a reference to the provider secret pointing to the account that shall be used for the shoot cluster.
It is most likely not needed, however, still added for some potential corner cases.
If you don’t need it, then just ignore it.
The .spec.region
contains the region of the seed cluster.
In order to support a control plane provider with purpose exposure
, you need to write a controller or expand the existing controlplane controller that watches all ControlPlane
s with .spec.type=<my-provider-name>
and purpose exposure
.
You can take a look at the below referenced example implementation for the AWS provider.
Non-Provider Specific Information Required for Infrastructure Creation
Most providers might require further information that is not provider specific but already part of the shoot resource.
As Gardener cannot know which information is required by providers, it simply mirrors the Shoot
, Seed
, and CloudProfile
resources into the seed.
They are part of the Cluster
extension resource and can be used to extract information.
References and Additional Resources
1.4.12 - ControlPlane Webhooks
ControlPlane Customization Webhooks
Gardener creates the Shoot controlplane in several steps of the Shoot flow. At different point of this flow, it:
- Deploys standard controlplane components such as kube-apiserver, kube-controller-manager, and kube-scheduler by creating the corresponding deployments, services, and other resources in the Shoot namespace.
- Initiates the deployment of custom controlplane components by ControlPlane controllers by creating a
ControlPlane
resource in the Shoot namespace.
In order to apply any provider-specific changes to the configuration provided by Gardener for the standard controlplane components, cloud extension providers can install mutating admission webhooks for the resources created by Gardener in the Shoot namespace.
What needs to be implemented to support a new cloud provider?
In order to support a new cloud provider, you should install “controlplane” mutating webhooks for any of the following resources:
- Deployment with name
kube-apiserver
,kube-controller-manager
, orkube-scheduler
- Service with name
kube-apiserver
OperatingSystemConfig
with any name, and purposereconcile
See Contract Specification for more details on the contract that Gardener and webhooks should adhere to regarding the content of the above resources.
You can install 3 different kinds of controlplane webhooks:
Shoot
, orcontrolplane
webhooks apply changes needed by the Shoot cloud provider, for example the--cloud-provider
command line flag ofkube-apiserver
andkube-controller-manager
. Such webhooks should only operate on Shoot namespaces labeled withshoot.gardener.cloud/provider=<provider>
.Seed
, orcontrolplaneexposure
webhooks apply changes needed by the Seed cloud provider, for example annotations on thekube-apiserver
service to ensure cloud-specific load balancers are correctly provisioned for a service of typeLoadBalancer
. Such webhooks should only operate on Shoot namespaces labeled withseed.gardener.cloud/provider=<provider>
.
The labels shoot.gardener.cloud/provider
and seed.gardener.cloud/provider
are added by Gardener when it creates the Shoot namespace.
Contract Specification
This section specifies the contract that Gardener and webhooks should adhere to in order to ensure smooth interoperability. Note that this contract can’t be specified formally and is therefore easy to violate, especially by Gardener. The Gardener team will nevertheless do its best to adhere to this contract in the future and to ensure via additional measures (tests, validations) that it’s not unintentionally broken. If it needs to be changed intentionally, this can only happen after proper communication has taken place to ensure that the affected provider webhooks could be adapted to work with the new version of the contract.
Note: The contract described below may not necessarily be what Gardener does currently (as of May 2019). Rather, it reflects the target state after changes for Gardener extensibility have been introduced.
kube-apiserver
To deploy kube-apiserver, Gardener shall create a deployment and a service both named kube-apiserver
in the Shoot namespace. They can be mutated by webhooks to apply any provider-specific changes to the standard configuration provided by Gardener.
The pod template of the kube-apiserver
deployment shall contain a container named kube-apiserver
.
The command
field of the kube-apiserver
container shall contain the kube-apiserver command line. It shall contain a number of provider-independent flags that should be ignored by webhooks, such as:
- admission plugins (
--enable-admission-plugins
,--disable-admission-plugins
) - secure communications (
--etcd-cafile
,--etcd-certfile
,--etcd-keyfile
, …) - audit log (
--audit-log-*
) - ports (
--secure-port
)
The kube-apiserver command line shall not contain any provider-specific flags, such as:
--cloud-provider
--cloud-config
These flags can be added by webhooks if needed.
The kube-apiserver
command line may contain a number of additional provider-independent flags. In general, webhooks should ignore these unless they are known to interfere with the desired kube-apiserver behavior for the specific provider. Among the flags to be considered are:
--endpoint-reconciler-type
--advertise-address
--feature-gates
Gardener uses SNI to expose the apiserver. In this case, Gardener will label the kube-apiserver
’s Deployment
with core.gardener.cloud/apiserver-exposure: gardener-managed
label (deprecated, the label will no longer be added as of v1.80
) and expects that the --endpoint-reconciler-type
and --advertise-address
flags are not modified.
The --enable-admission-plugins
flag may contain admission plugins that are not compatible with CSI plugins such as PersistentVolumeLabel
. Webhooks should therefore ensure that such admission plugins are either explicitly enabled (if CSI plugins are not used) or disabled (otherwise).
The env
field of the kube-apiserver
container shall not contain any provider-specific environment variables (so it will be empty). If any provider-specific environment variables are needed, they should be added by webhooks.
The volumes
field of the pod template of the kube-apiserver
deployment, and respectively the volumeMounts
field of the kube-apiserver
container shall not contain any provider-specific Secret
or ConfigMap
resources. If such resources should be mounted as volumes, this should be done by webhooks.
The kube-apiserver
Service
may be of type LoadBalancer
, but shall not contain any provider-specific annotations that may be needed to actually provision a load balancer resource in the Seed provider’s cloud. If any such annotations are needed, they should be added by webhooks (typically controlplaneexposure
webhooks).
The kube-apiserver
Service
will be of type ClusterIP
. In this case, Gardener will label this Service
with core.gardener.cloud/apiserver-exposure: gardener-managed
label (deprecated, the label will no longer be added as of v1.80
) and expects that no mutations happen.
kube-controller-manager
To deploy kube-controller-manager, Gardener shall create a deployment named kube-controller-manager
in the Shoot namespace. It can be mutated by webhooks to apply any provider-specific changes to the standard configuration provided by Gardener.
The pod template of the kube-controller-manager
deployment shall contain a container named kube-controller-manager
.
The command
field of the kube-controller-manager
container shall contain the kube-controller-manager command line. It shall contain a number of provider-independent flags that should be ignored by webhooks, such as:
--kubeconfig
,--authentication-kubeconfig
,--authorization-kubeconfig
--leader-elect
- secure communications (
--tls-cert-file
,--tls-private-key-file
, …) - cluster CIDR and identity (
--cluster-cidr
,--cluster-name
) - sync settings (
--concurrent-deployment-syncs
,--concurrent-replicaset-syncs
) - horizontal pod autoscaler (
--horizontal-pod-autoscaler-*
) - ports (
--port
,--secure-port
)
The kube-controller-manager command line shall not contain any provider-specific flags, such as:
--cloud-provider
--cloud-config
--configure-cloud-routes
--external-cloud-volume-plugin
These flags can be added by webhooks if needed.
The kube-controller-manager command line may contain a number of additional provider-independent flags. In general, webhooks should ignore these unless they are known to interfere with the desired kube-controller-manager behavior for the specific provider. Among the flags to be considered are:
--feature-gates
The env
field of the kube-controller-manager
container shall not contain any provider-specific environment variables (so it will be empty). If any provider-specific environment variables are needed, they should be added by webhooks.
The volumes
field of the pod template of the kube-controller-manager
deployment, and respectively the volumeMounts
field of the kube-controller-manager
container shall not contain any provider-specific Secret
or ConfigMap
resources. If such resources should be mounted as volumes, this should be done by webhooks.
kube-scheduler
To deploy kube-scheduler, Gardener shall create a deployment named kube-scheduler
in the Shoot namespace. It can be mutated by webhooks to apply any provider-specific changes to the standard configuration provided by Gardener.
The pod template of the kube-scheduler
deployment shall contain a container named kube-scheduler
.
The command
field of the kube-scheduler
container shall contain the kube-scheduler command line. It shall contain a number of provider-independent flags that should be ignored by webhooks, such as:
--config
--authentication-kubeconfig
,--authorization-kubeconfig
- secure communications (
--tls-cert-file
,--tls-private-key-file
, …) - ports (
--port
,--secure-port
)
The kube-scheduler command line may contain additional provider-independent flags. In general, webhooks should ignore these unless they are known to interfere with the desired kube-controller-manager behavior for the specific provider. Among the flags to be considered are:
--feature-gates
The kube-scheduler command line can’t contain provider-specific flags, and it makes no sense to specify provider-specific environment variables or mount provider-specific Secret
or ConfigMap
resources as volumes.
etcd-main and etcd-events
To deploy etcd, Gardener shall create 2 Etcd named etcd-main
and etcd-events
in the Shoot namespace. They can be mutated by webhooks to apply any provider-specific changes to the standard configuration provided by Gardener.
Gardener shall configure the Etcd
resource completely to set up an etcd cluster which uses the default storage class of the seed cluster.
cloud-controller-manager
Gardener shall not deploy a cloud-controller-manager. If it is needed, it should be added by a ControlPlane
controller
CSI Controllers
Gardener shall not deploy a CSI controller. If it is needed, it should be added by a ControlPlane
controller
kubelet
To specify the kubelet configuration, Gardener shall create a OperatingSystemConfig
resource with any name and purpose reconcile
in the Shoot namespace. It can therefore also be mutated by webhooks to apply any provider-specific changes to the standard configuration provided by Gardener. Gardener may write multiple such resources with different type
to the same Shoot namespaces if multiple OSs are used.
The OSC resource shall contain a unit named kubelet.service
, containing the corresponding systemd unit configuration file. The [Service]
section of this file shall contain a single ExecStart
option having the kubelet command line as its value.
The OSC resource shall contain a file with path /var/lib/kubelet/config/kubelet
, which contains a KubeletConfiguration
resource in YAML format. Most of the flags that can be specified in the kubelet command line can alternatively be specified as options in this configuration as well.
The kubelet command line shall contain a number of provider-independent flags that should be ignored by webhooks, such as:
--config
--bootstrap-kubeconfig
,--kubeconfig
--network-plugin
(and, if it equalscni
, also--cni-bin-dir
and--cni-conf-dir
)--node-labels
The kubelet command line shall not contain any provider-specific flags, such as:
--cloud-provider
--cloud-config
--provider-id
These flags can be added by webhooks if needed.
The kubelet command line / configuration may contain a number of additional provider-independent flags / options. In general, webhooks should ignore these unless they are known to interfere with the desired kubelet behavior for the specific provider. Among the flags / options to be considered are:
--enable-controller-attach-detach
(enableControllerAttachDetach
) - should be set totrue
if CSI plugins are used, but in general can also be ignored since its default value is alsotrue
, and this should work both with and without CSI plugins.--feature-gates
(featureGates
) - should contain a list of specific feature gates if CSI plugins are used. If CSI plugins are not used, the corresponding feature gates can be ignored since enabling them should not harm in any way.
1.4.13 - Conventions
General Conventions
All the extensions that are registered to Gardener are deployed to the seed clusters on which they are required (also see ControllerRegistration).
Some of these extensions might need to create global resources in the seed (e.g., ClusterRole
s), i.e., it’s important to have a naming scheme to avoid conflicts as it cannot be checked or validated upfront that two extensions don’t use the same names.
Consequently, this page should help answering some general questions that might come up when it comes to developing an extension.
PriorityClass
es
Extensions are not supposed to create and use self-defined PriorityClasses
.
Instead, they can and should rely on well-known PriorityClasses
managed by gardenlet.
High Availability of Deployed Components
Extensions might deploy components via Deployment
s, StatefulSet
s, etc., as part of the shoot control plane, or the seed or shoot system components.
In case a seed or shoot cluster is highly available, there are various failure tolerance types. For more information, see Highly Available Shoot Control Plane.
Accordingly, the replicas
, topologySpreadConstraints
or affinity
settings of the deployed components might need to be adapted.
Instead of doing this one-by-one for each and every component, extensions can rely on a mutating webhook provided by Gardener. Please refer to High Availability of Deployed Components for details.
To reduce costs and to improve the network traffic latency in multi-zone clusters, extensions can make a Service topology-aware. Please refer to this document for details.
Is there a naming scheme for (global) resources?
As there is no formal process to validate non-existence of conflicts between two extensions, please follow these naming schemes when creating resources (especially, when creating global resources, but it’s in general a good idea for most created resources):
The resource name should be prefixed with extensions.gardener.cloud:<extension-type>-<extension-name>:<resource-name>
, for example:
extensions.gardener.cloud:provider-aws:some-controller-manager
extensions.gardener.cloud:extension-certificate-service:cert-broker
How to create resources in the shoot cluster?
Some extensions might not only create resources in the seed cluster itself but also in the shoot cluster. Usually, every extension comes with a ServiceAccount
and the required RBAC permissions when it gets installed to the seed.
However, there are no credentials for the shoot for every extension.
Extensions are supposed to use ManagedResources
to manage resources in shoot clusters.
gardenlet deploys gardener-resource-manager instances into all shoot control planes, that will reconcile ManagedResources
without a specified class (spec.class=null
) in shoot clusters. Mind that Gardener acts on ManagedResources
with the origin=gardener
label. In order to prevent unwanted behavior, extensions should omit the origin
label or provide their own unique value for it when creating such resources.
If you need to deploy a non-DaemonSet resource, Gardener automatically ensures that it only runs on nodes that are allowed to host system components and extensions. For more information, see System Components Webhook.
How to create kubeconfigs for the shoot cluster?
Historically, Gardener extensions used to generate kubeconfigs with client certificates for components they deploy into the shoot control plane.
For this, they reused the shoot cluster CA secret (ca
) to issue new client certificates.
With gardener/gardener#4661 we moved away from using client certificates in favor of short-lived, auto-rotated ServiceAccount
tokens. These tokens