Merge pull request #48447 from sftim/20241020_cluster_diagram_details

Redo cluster diagram details on architecture page

Author: k8s-ci-robot

assets/scss/_documentation.scss

@@ -238,6 +238,21 @@ body.td-home #deprecation-warning {
     margin-right: auto;
 }
 
+// <details> shortcode
+
+details > summary {
+  margin-bottom: 1em;
+  color: $primary;
+  background: transparent;
+}
+
+details:not([open]) > summary:after {
+  content: '…';
+  display: inline-block;
+}
+
+// glossary
+
 body.glossary {
   main {
     ul.glossary-terms > li {

content/en/docs/concepts/architecture/_index.md

@@ -15,9 +15,19 @@ usually runs multiple nodes, providing fault-tolerance and high availability.
 
 This document outlines the various components you need to have for a complete and working Kubernetes cluster.
 
-{{< figure src="/images/docs/kubernetes-cluster-architecture.svg" alt="The control plane (kube-apiserver, etcd, kube-controller-manager, kube-scheduler) and several nodes. Each node is running a kubelet and kube-proxy."
-title="Kubernetes cluster components"
-caption="**Note:** This diagram presents an example reference architecture for a Kubernetes cluster. The actual distribution of components can vary based on specific cluster setups and requirements." class="diagram-large" >}}
+{{< figure src="/images/docs/kubernetes-cluster-architecture.svg" alt="The control plane (kube-apiserver, etcd, kube-controller-manager, kube-scheduler) and several nodes. Each node is running a kubelet and kube-proxy." caption="Figure 1. Kubernetes cluster components." class="diagram-large" >}}
+
+{{< details summary="About this architecture" >}}
+The diagram in Figure 1 presents an example reference architecture for a Kubernetes cluster.
+The actual distribution of components can vary based on specific cluster setups and requirements.
+
+In the diagram, each node runs the [`kube-proxy`](#kube-proxy) component. You need a
+network proxy component on each node to ensure that the
+{{< glossary_tooltip text="Service" term_id="service">}} API and associated behaviors
+are available on your cluster network. However, some network plugins provide their own,
+third party implementation of proxying. When you use that kind of network plugin,
+the node does not need to run `kube-proxy`.
+{{< /details >}}
 
 ## Control plane components
 
@@ -75,6 +85,8 @@ The following controllers can have cloud provider dependencies:
 - Route controller: For setting up routes in the underlying cloud infrastructure
 - Service controller: For creating, updating and deleting cloud provider load balancers
 
+---
+
 ## Node components
 
 Node components run on every node, maintaining running pods and providing the Kubernetes runtime environment.

content/en/docs/contribute/style/hugo-shortcodes/index.md

@@ -370,6 +370,34 @@ Add the shortcode:
 
 before the item, or just below the heading for the specific item.
 
+## Details
+
+You can render a `<details>` HTML element using a shortcode:
+
+```markdown
+{{</* details summary="More about widgets" */>}}
+The frobnicator extension API implements _widgets_ using example running text.
+
+Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur,
+adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et
+dolore magnam aliquam quaerat voluptatem.
+{{</* /details */>}}
+```
+
+This renders as:
+{{< details summary="More about widgets" >}}
+The frobnicator extension API implements _widgets_ using example running text.
+
+Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur,
+adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et
+dolore magnam aliquam quaerat voluptatem.
+{{< /details >}}
+
+{{< note >}}
+Use this shortcode sparingly; it is usually best to have all of the text directly shown
+to readers.
+{{< /note >}}
+
 ## Version strings
 
 To generate a version string for inclusion in the documentation, you can choose from

layouts/shortcodes/details.html

@@ -0,0 +1,12 @@
+{{- $summary := "" -}}
+{{- if .IsNamedParams -}}
+  {{- $summary = .Get "summary" -}}
+{{- end -}}
+<details>
+  {{- if ne $summary "" -}}
+    <summary>{{ $summary }}</summary>
+  {{- end -}}
+  <div class="details-inner">
+    {{ .Inner | markdownify }}
+  </div>
+</details>