Move usage content into a designated place (2/3) (#10436)

* Moving usage content into a designated place and adapting links

* Address feedback

* Apply suggestions from code review

Co-authored-by: Ismail Alidzhikov <[email protected]>

* Fix typo of high-availability

* shoot instead of shoot-basics

* Change in readme

---------

Co-authored-by: Ismail Alidzhikov <[email protected]>

charts/gardener/operator/templates/crd-gardens.yaml

@@ -570,7 +570,7 @@ spec:
                                   Each item is a Kubernetes resource name in plural (resource or resource.group) that should be encrypted.
                                   Note that configuring a custom resource is only supported for versions >= 1.26.
                                   Wildcards are not supported for now.
-                                  See https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md for more details.
+                                  See https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md for more details.
                                 items:
                                   type: string
                                 type: array
@@ -1246,7 +1246,7 @@ spec:
                                   Each item is a Kubernetes resource name in plural (resource or resource.group) that should be encrypted.
                                   Note that configuring a custom resource is only supported for versions >= 1.26.
                                   Wildcards are not supported for now.
-                                  See https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md for more details.
+                                  See https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md for more details.
                                 items:
                                   type: string
                                 type: array

charts/gardener/provider-local/templates/coredns/custom-configmap.yaml

@@ -7,5 +7,5 @@ metadata:
   annotations:
     "resources.gardener.cloud/ignore": "true"
 data:
-  changeme.override: "# checkout the docs on how to use: https://github.com/gardener/gardener/blob/master/docs/usage/custom-dns-config.md"
+  changeme.override: "# checkout the docs on how to use: https://github.com/gardener/gardener/blob/master/docs/usage/networking/custom-dns-config.md"
 {{- end -}}

docs/README.md

@@ -25,53 +25,75 @@
 
 ## Usage
 
-* [Audit a Kubernetes cluster](usage/shoot_auditpolicy.md)
-* [Cleanup of Shoot clusters in deletion](usage/shoot_cleanup.md)
-* [`containerd` Registry Configuration](usage/containerd-registry-configuration.md)
-* [Custom `containerd` configuration](usage/custom-containerd-config.md)
-* [Custom `CoreDNS` configuration](usage/custom-dns-config.md)
-* [(Custom) CSI components](usage/csi_components.md)
-* [Default Seccomp Profile](usage/default_seccomp_profile.md)
-* [DNS Autoscaling](usage/dns-autoscaling.md)
-* [DNS Search Path Optimization](usage/dns-search-path-optimization.md)
-* [Endpoints and Ports of a Shoot Control-Plane](usage/control-plane-endpoints-and-ports.md)
-* [ETCD Encryption Config](usage/etcd_encryption_config.md)
-* [ExposureClasses](usage/exposureclasses.md)
-* [Hibernate a Cluster](usage/shoot_hibernate.md)
-* [IPv6 in Gardener Clusters](usage/ipv6.md)
-* [Logging](usage/logging.md)
-* [`NodeLocalDNS` feature](usage/node-local-dns.md)
-* [OpenIDConnect presets](usage/openidconnect-presets.md)
-* [Projects](usage/projects.md)
-* [Service Account Manager](usage/service-account-manager.md)
-* [Readiness of Shoot Worker Nodes](usage/node-readiness.md)
-* [Reversed Cluster VPN](usage/reversed-vpn-tunnel.md)
-* [Shoot Cluster Purposes](usage/shoot_purposes.md)
-* [Shoot Scheduling Profiles](usage/shoot_scheduling_profiles.md)
-* [Shoot Credentials Rotation](usage/shoot_credentials_rotation.md)
-* [Shoot Kubernetes and Operating System Versioning](usage/shoot_versions.md)
-* [Shoot `KUBERNETES_SERVICE_HOST` Environment Variable Injection](usage/shoot_kubernetes_service_host_injection.md)
-* [Shoot Networking](usage/shoot_networking.md)
-* [Shoot Maintenance](usage/shoot_maintenance.md)
-* [Shoot `ServiceAccount` Configurations](usage/shoot_serviceaccounts.md)
-* [Shoot Status](usage/shoot_status.md)
-* [Shoot Info `ConfigMap`](usage/shoot_info_configmap.md)
-* [Shoot Updates and Upgrades](usage/shoot_updates.md)
-* [Shoot Auto-Scaling Configuration](usage/shoot_autoscaling.md)
-* [Shoot Pod Auto-Scaling Best Practices](usage/shoot_pod_autoscaling_best_practices.md)
-* [Shoot High-Availability Control Plane](usage/shoot_high_availability.md)
-* [Shoot High-Availability Best Practices](usage/shoot_high_availability_best_practices.md)
-* [Shoot Workers Settings](usage/shoot_workers_settings.md)
-* [Accessing Shoot Clusters](usage/shoot_access.md)
-* [Supported Kubernetes versions](usage/supported_k8s_versions.md)
-* [Tolerations](usage/tolerations.md)
-* [Trigger shoot operations](usage/shoot_operations.md)
-* [Trusted TLS certificate for shoot control planes](usage/trusted-tls-for-control-planes.md)
-* [Trusted TLS certificate for garden runtime cluster](usage/trusted-tls-for-garden-runtime.md)
-* [Controlling the Kubernetes versions for specific worker pools](usage/worker_pool_k8s_versions.md)
-* [Admission Configuration for the `PodSecurity` Admission Plugin](usage/pod-security.md)
-* [Supported CPU Architectures for Shoot Worker Nodes](usage/shoot_supported_architectures.md)
-* [Workerless `Shoot`s](usage/shoot_workerless.md)
+### Project
+
+* [Projects](usage/project/projects.md)
+* [Service Account Manager](usage/project/service-account-manager.md)
+
+### Shoot
+
+* [Accessing Shoot Clusters](usage/shoot/shoot_access.md)
+* [Hibernate a Cluster](usage/shoot/shoot_hibernate.md)
+* [Shoot Info `ConfigMap`](usage/shoot/shoot_info_configmap.md)
+* [Shoot Maintenance](usage/shoot/shoot_maintenance.md)
+* [Shoot Cluster Purposes](usage/shoot/shoot_purposes.md)
+* [Shoot Scheduling Profiles](usage/shoot/shoot_scheduling_profiles.md)
+* [Shoot Status](usage/shoot/shoot_status.md)
+* [Supported CPU Architectures for Shoot Worker Nodes](usage/shoot/shoot_supported_architectures.md)
+* [Workerless `Shoot`s](usage/shoot/shoot_workerless.md)
+* [Shoot Workers Settings](usage/shoot/shoot_workers_settings.md)
+
+### Shoot Operations
+
+* [Shoot Credentials Rotation](usage/shoot-operations/shoot_credentials_rotation.md)
+* [Trigger shoot operations](usage/shoot-operations/shoot_operations.md)
+* [Shoot Updates and Upgrades](usage/shoot-operations/shoot_updates.md)
+* [Shoot Kubernetes and Operating System Versioning](usage/shoot-operations/shoot_versions.md)
+* [Supported Kubernetes versions](usage/shoot-operations/supported_k8s_versions.md)
+* [Controlling the Kubernetes versions for specific worker pools](usage/shoot-operations/worker_pool_k8s_versions.md)
+
+### High Avaliability
+
+* [Shoot High-Availability Control Plane](usage/high-availability/shoot_high_availability.md)
+* [Shoot High-Availability Best Practices](usage/high-availability/shoot_high_availability_best_practices.md)
+
+### Security
+
+* [Default Seccomp Profile](usage/security/default_seccomp_profile.md)
+* [ETCD Encryption Config](usage/security/etcd_encryption_config.md)
+* [OpenIDConnect presets](usage/security/openidconnect-presets.md)
+* [Admission Configuration for the `PodSecurity` Admission Plugin](usage/security/pod-security.md)
+* [Audit a Kubernetes cluster](usage/security/shoot_auditpolicy.md)
+* [Shoot `ServiceAccount` Configurations](usage/security/shoot_serviceaccounts.md)
+
+### Networking
+
+* [Custom `CoreDNS` configuration](usage/networking/custom-dns-config.md)
+* [DNS Search Path Optimization](usage/networking/dns-search-path-optimization.md)
+* [ExposureClasses](usage/networking/exposureclasses.md)
+* [`NodeLocalDNS` feature](usage/networking/node-local-dns.md)
+* [Shoot `KUBERNETES_SERVICE_HOST` Environment Variable Injection](usage/networking/shoot_kubernetes_service_host_injection.md)
+* [Shoot Networking](usage/networking/shoot_networking.md)
+
+### Autoscaling
+
+* [DNS Autoscaling](usage/autoscaling/dns-autoscaling.md)
+* [Shoot Auto-Scaling Configuration](usage/autoscaling/shoot_autoscaling.md)
+* [Shoot Pod Auto-Scaling Best Practices](usage/autoscaling/shoot_pod_autoscaling_best_practices.md)
+
+### Observability
+
+* [Logging](usage/observability/logging.md)
+
+### Advanced
+
+* [`containerd` Registry Configuration](usage/advanced/containerd-registry-configuration.md)
+* [Endpoints and Ports of a Shoot Control-Plane](usage/advanced/control-plane-endpoints-and-ports.md)
+* [(Custom) CSI components](usage/advanced/csi_components.md)
+* [Custom `containerd` configuration](usage/advanced/custom-containerd-config.md)
+* [Readiness of Shoot Worker Nodes](usage/advanced/node-readiness.md)
+* [Cleanup of Shoot clusters in deletion](usage/advanced/shoot_cleanup.md)
+* [Tolerations](usage/advanced/tolerations.md)
 
 ## [API Reference](api-reference/README.md)
 
@@ -127,7 +149,9 @@
 * [Logging in Gardener Components](development/logging.md)
 * [Changing the API](development/changing-the-api.md)
 * [Secrets Management for Seed and Shoot Clusters](development/secrets_management.md)
+* [IPv6 in Gardener Clusters](development/ipv6.md)
 * [Releases, Features, Hotfixes](development/process.md)
+* [Reversed Cluster VPN](development/reversed-vpn-tunnel.md)
 * [Adding New Cloud Providers](development/new-cloud-provider.md)
 * [Adding Support For A New Kubernetes Version](development/new-kubernetes-version.md)
 * [Extending the Monitoring Stack](development/monitoring-stack.md)
@@ -136,6 +160,7 @@
 * [High Availability Of Deployed Components](development/high-availability.md)
 * [Checklist For Adding New Components](development/component-checklist.md)
 * [Defaulting Strategy and Developer Guideline](development/defaulting.md)
+* [Autoscaling Specifics for Components](development/autoscaling-specifics-for-components.md)
 
 ## Extensions
 
@@ -208,6 +233,8 @@
 * [Seed Bootstrapping](operations/seed_bootstrapping.md)
 * [Seed Settings](operations/seed_settings.md)
 * [Topology-Aware Traffic Routing](operations/topology_aware_routing.md)
+* [Trusted TLS certificate for shoot control planes](operations/trusted-tls-for-control-planes.md)
+* [Trusted TLS certificate for garden runtime cluster](operations/trusted-tls-for-garden-runtime.md)
 
 ## Monitoring
 

docs/api-reference/core.md

@@ -4857,7 +4857,7 @@ triggered.</p>
 Each item is a Kubernetes resource name in plural (resource or resource.group) that should be encrypted.
 Note that configuring a custom resource is only supported for versions &gt;= 1.26.
 Wildcards are not supported for now.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md">https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md</a> for more details.</p>
+See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md">https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md</a> for more details.</p>
 </td>
 </tr>
 </tbody>
@@ -8359,7 +8359,7 @@ string
 <td>
 <em>(Optional)</em>
 <p>IPFamilies specifies the IP protocol versions to use for shoot networking. This field is immutable.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md</a>.
+See <a href="https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md</a>.
 Defaults to [&ldquo;IPv4&rdquo;].</p>
 </td>
 </tr>
@@ -9835,7 +9835,7 @@ in the seed cluster.</p>
 <td>
 <em>(Optional)</em>
 <p>IPFamilies specifies the IP protocol versions to use for seed networking. This field is immutable.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md</a>.
+See <a href="https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md</a>.
 Defaults to [&ldquo;IPv4&rdquo;].</p>
 </td>
 </tr>
@@ -12293,7 +12293,7 @@ LastMaintenance
 <em>(Optional)</em>
 <p>EncryptedResources is the list of resources in the Shoot which are currently encrypted.
 Secrets are encrypted by default and are not part of the list.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md">https://github.com/gardener/gardener/blob/master/docs/usage/etcd_encryption_config.md</a> for more details.</p>
+See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md">https://github.com/gardener/gardener/blob/master/docs/usage/security/etcd_encryption_config.md</a> for more details.</p>
 </td>
 </tr>
 <tr>

docs/api-reference/extensions.md

@@ -1300,7 +1300,7 @@ string
 <td>
 <em>(Optional)</em>
 <p>IPFamilies specifies the IP protocol versions to use for shoot networking. This field is immutable.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md</a></p>
+See <a href="https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md</a></p>
 </td>
 </tr>
 </table>
@@ -3767,7 +3767,7 @@ string
 <td>
 <em>(Optional)</em>
 <p>IPFamilies specifies the IP protocol versions to use for shoot networking. This field is immutable.
-See <a href="https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/usage/ipv6.md</a></p>
+See <a href="https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md">https://github.com/gardener/gardener/blob/master/docs/development/ipv6.md</a></p>
 </td>
 </tr>
 </tbody>

docs/concepts/apiserver-admission-plugins.md

@@ -47,7 +47,7 @@ It validates that the respective resource is annotated with a deletion confirmat
 Only if this annotation is present it allows the `DELETE` operation to pass.
 This prevents users from accidental/undesired deletions.
 In addition, it applies the "four-eyes principle for deletion" concept if the `Project` is configured accordingly.
-Find all information about it [in this document](../usage/projects.md#four-eyes-principle-for-resource-deletion).
+Find all information about it [in this document](../usage/project/projects.md#four-eyes-principle-for-resource-deletion).
 
 Furthermore, this admission controller reacts on `CREATE` or `UPDATE` operations for `Shoot`s.
 It makes sure that the `deletion.gardener.cloud/confirmed-by` annotation is properly maintained in case the `Shoot` deletion is confirmed with above mentioned annotation.
@@ -121,7 +121,7 @@ It also validates the DNS configuration (`.spec.dns`) for shoots.
 _(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](../usage/node-local-dns.md)) by setting `spec.systemComponents.nodeLocalDNS.enabled=true` for newly created Shoots.
+If enabled, it will enable node local dns within the shoot cluster (for more information, see [NodeLocalDNS Configuration](../usage/networking/node-local-dns.md)) 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.
 
@@ -151,7 +151,7 @@ If a shoot contains global resource reservations, then no per worker pool resour
 _(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](../usage/shoot_autoscaling.md#vertical-pod-auto-scaling)) 
+If enabled, it will enable the managed `VerticalPodAutoscaler` components (for more information, see [Vertical Pod Auto-Scaling](../usage/autoscaling/shoot_autoscaling.md#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.
@@ -202,7 +202,7 @@ It rejects the deletion if there are `Shoot`s that are scheduled onto the `Seed`
 _(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](../usage/dns-search-path-optimization.md)).
+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](../usage/networking/dns-search-path-optimization.md)).
 Already existing `Shoot`s will not be affected by this admission plugin.
 
 ## `NamespacedCloudProfileValidator`

docs/concepts/apiserver.md

@@ -46,7 +46,7 @@ End-users can read and/or write `Secret`s in their project namespaces in the gar
 `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](../usage/shoot_access.md#shootsadminkubeconfig-subresource) signs short-lived client certificates by retrieving the CA from the `InternalSecret`.
+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](../usage/shoot/shoot_access.md#shootsadminkubeconfig-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.
 
@@ -100,7 +100,7 @@ Please see [this](../../example/90-shoot.yaml) example manifest and consult the
 
 ## `(Cluster)OpenIDConnectPreset`s
 
-Please see [this](../usage/openidconnect-presets.md) separate documentation file.
+Please see [this](../usage/security/openidconnect-presets.md) separate documentation file.
 
 ## Overview Data Model