From 26aa51a940923b7718f04891bb53532490960769 Mon Sep 17 00:00:00 2001
From: Sascha Grunert <sgrunert@redhat.com>
Date: Tue, 23 Nov 2021 09:58:06 +0100
Subject: [PATCH] Add CRI architecture to cluster concepts

Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
---
 content/en/docs/concepts/architecture/cri.md  | 51 +++++++++++++++++++
 .../glossary/container-runtime-interface.md   | 22 ++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 content/en/docs/concepts/architecture/cri.md
 create mode 100644 content/en/docs/reference/glossary/container-runtime-interface.md

diff --git a/content/en/docs/concepts/architecture/cri.md b/content/en/docs/concepts/architecture/cri.md
new file mode 100644
index 0000000000..e8391ca34b
--- /dev/null
+++ b/content/en/docs/concepts/architecture/cri.md
@@ -0,0 +1,51 @@
+---
+title: Container Runtime Interface (CRI)
+content_type: concept
+weight: 50
+---
+
+<!-- overview -->
+
+The CRI is a plugin interface which enables the kubelet to use a wide variety of
+container runtimes, without having a need to recompile the cluster components.
+
+You need a working
+{{<glossary_tooltip text="container runtime" term_id="container-runtime">}} on
+each Node in your cluster, so that the
+{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} can launch
+{{< glossary_tooltip text="Pods" term_id="pod" >}} and their containers.
+
+{{< glossary_definition term_id="container-runtime-interface" length="all" >}}
+
+<!-- body -->
+
+## The API {#api}
+
+{{< feature-state for_k8s_version="v1.23" state="stable" >}}
+
+The kubelet acts as a client when connecting to the container runtime via gRPC.
+The runtime and image service endpoints have to be available in the container
+runtime, which can be configured separately within the kubelet by using the
+`--image-service-endpoint` and `--container-runtime-endpoint` [command line
+flags](/docs/reference/command-line-tools-reference/kubelet)
+
+For Kubernetes v{{< skew currentVersion >}}, the kubelet prefers to use CRI `v1`.
+If a container runtime does not support `v1` of the CRI, then the kubelet tries to
+negotiate any older supported version.
+The v{{< skew currentVersion >}} kubelet can also negotiate CRI `v1alpha2`, but
+this version is considered as deprecated.
+If the kubelet cannot negotiate a supported CRI version, the kubelet gives up
+and doesn't register as a node.
+
+## Upgrading
+
+When upgrading Kubernetes, then the kubelet tries to automatically select the
+latest CRI version on restart of the component. If that fails, then the fallback
+will take place as mentioned above. If a gRPC re-dial was required because the
+container runtime has been upgraded, then the container runtime must also
+support the initially selected version or the redial is expected to fail. This
+requires a restart of the kubelet.
+
+## {{% heading "whatsnext" %}}
+
+- Learn more about the CRI [protocol definition](https://github.com/kubernetes/cri-api/blob/c75ef5b/pkg/apis/runtime/v1/api.proto)
diff --git a/content/en/docs/reference/glossary/container-runtime-interface.md b/content/en/docs/reference/glossary/container-runtime-interface.md
new file mode 100644
index 0000000000..11f7bc50f4
--- /dev/null
+++ b/content/en/docs/reference/glossary/container-runtime-interface.md
@@ -0,0 +1,22 @@
+---
+title: Container Runtime Interface
+id: container-runtime-interface
+date: 2021-11-24
+full_link: /docs/concepts/architecture/cri
+short_description: >
+  The main protocol for the communication between the kubelet and Container Runtime.
+
+aka:
+tags:
+  - cri
+---
+
+The main protocol for the communication between the kubelet and Container Runtime.
+
+<!--more-->
+
+The Kubernetes Container Runtime Interface (CRI) defines the main
+[gRPC](https://grpc.io) protocol for the communication between the
+[cluster components](/docs/concepts/overview/components/#node-components)
+{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} and
+{{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}.