Repository: jina-ai/serve
Pull request: docs: create a kubernetes section
# Context

based on this issue : https://github.com/jina-ai/jina/issues/5243

This PR revamp the k8s documentation to make k8s more prominent 

Problem statement:
docs: make Kubernetes more prominent
Currently everything about Kubernetes is contained in one single how-to article.

"Deploy on Kubernetes" should become its own section on the same level as "Flow" and "Hub" etc. for the following reasons:
- It sends a signal that we are cloud native. Right now our kubernetes stuff is hidden away, and seem like an after thought, when in reality it is not
- It sends a signal that we are production ready and serious
- This is also a reminder for us to put attention into these topics
- It gives us more space to properly explain things. Right now the k8s yaml is just spit out without us ever telling the user why it looks the way it looks. This way we would have more room to explain the readiness probe, the linkerd dependency, the secret management in the future, etc

Hints from issue discussion:

Commit message: docs: small fix

Patch to review:
diff --git a/docs/fundamentals/executor/executor-serve.md b/docs/fundamentals/executor/executor-serve.md
index 39cf99fca4185..3b42a3c5571d5 100644
--- a/docs/fundamentals/executor/executor-serve.md
+++ b/docs/fundamentals/executor/executor-serve.md
@@ -72,6 +72,7 @@ the Executor, and `**kwargs` is passed to the internal {meth}`~jina.Flow` initia
 For more details on these arguments and the workings of a Flow, see the {ref}`Flow section <flow-cookbook>`.
 ````
 
+(kubernetes-executor)=
 ## Serve via Kubernetes
 You can generate Kubernetes configuration files for your containerized Executor by using the static `Executor.to_kubernetes_yaml()` method. This works like {ref}`deploying a Flow in Kubernetes <kubernetes>`, because your Executor is wrapped automatically in a Flow and uses the very same deployment techniques.
 
diff --git a/docs/fundamentals/flow/create-flow.md b/docs/fundamentals/flow/create-flow.md
index 22746de587260..4c6892c4f874b 100644
--- a/docs/fundamentals/flow/create-flow.md
+++ b/docs/fundamentals/flow/create-flow.md
@@ -239,7 +239,7 @@ This will generate a single `docker-compose.yml` file containing all the Executo
 
 For an advance utilisation of Docker Compose with jina please refer to this {ref}`How to <docker-compose>` 
 
-
+(kubernetes-export)=
 ### Kubernetes
 
 ```python
diff --git a/docs/fundamentals/k8s.md b/docs/fundamentals/k8s.md
new file mode 100644
index 0000000000000..c38728904da7c
--- /dev/null
+++ b/docs/fundamentals/k8s.md
@@ -0,0 +1,159 @@
+(kubernetes-docs)=
+# Kubernetes Support
+
+Jina is a cloud native framework and therefore run natively and easily on Kubernetes.
+Deploying a Jina Flow on Kubernetes is actually the recommended way to use Jina in production.
+
+
+A {class}`~jina.Flow` is composed of different microservices called {class}`~jina.Executor`s which natively run in container. This mean that Kubernetes can natively take over the lifetime management of Executors. 
+
+Deploying a {class}`~jina.Flow` on Kubernetes means wrapping these microservices container in the appropriate K8s abstraction (Deployment, StatefulSet, ...) expose them internally via K8s Service and 
+connecting them together by passing the right set of parameters.
+
+## Automatically translate a Flow to Kubernetes concept
+
+
+```{hint}
+Manually building these Kubernetes YAML object is long and cumbersome. Therefore we provide a helper function {meth}`~jina.Flow.to_kubernetes_yaml` that does most of this
+translation work automatically. 
+```
+
+This helper function can be called from:
+* our Python interface to translate a Flow define in Python to k8s yaml files
+* our CLI interface to export a YAML Flow to k8s yaml files
+
+```{seealso}
+More detail in the {ref}`Flow export documentation <kubernetes-export>`
+```
+
+
+## Extra Kubernetes options
+
+In general, Jina follows the following principle when it comes to deploying in Kubernetes:
+You, the user, know your use case and requirements the best.
+This means that while Jina generates configurations for you that run out of the box, as a professional user you should
+always see them as just a starting point to get you off the ground.
+
+```{hint}
+The export funciton{meth}`~jina.Flow.to_kubernetes_yaml` is a helper function to get your stared off the ground. **There are meant to be updated and adapted to every use case**
+```
+````{admonition} Matching jina versions
+:class: caution
+If you change the Docker images for {class}`~jina.Executor` and {class}`~jina.Gateway` in your Kubernetes generated file, ensure that al of them are built with the same Jina version to guarantee compatibility.
+````
+
+You can't add basic Kubernetes feature like `Secrets`, `ConfigMap` or `Labels` via the Pythonic or YAML interface. This is intentional
+and doesn't mean that we don't support these features. On the contrary, we let you fully express your Kubernetes configuration by using the Kubernetes API to add you own Kubernetes standard to Jina.
+
+````{admonition} Hint
+:class: hint
+We recommend dumping the Kubernetes configuration files and then editing the files to suit your needs.
+````
+
+Here are possible configuration options you may need to add or change
+
+- Add labels `selector`s to the Deployments to suit your case
+- Add `requests` and `limits` for the resources of the different Pods 
+- Set up persistent volume storage to save your data on disk
+- Pass custom configuration to your Executor with `ConfigMap` 
+- Manage credentials of your Executor with secrets
+- Edit the default rolling update configuration
+
+
+(service-mesh-k8s)=
+## Required Service Mesh 
+
+```{caution}
+A Service Mesh is required to be installed and correctly configured in the K8s clusteri in which your deployed your Flow.
+```
+
+Service meshes work by attaching a tiny proxy to each of your Kubernetes pods, allowing for smart rerouting, load balancing,
+request retrying, and host of other [features](https://linkerd.io/2.11/features/).
+
+Jina relies on a service mesh to load balance request between replicas of the same Executor.
+You can use your favourite Kubernetes service mesh in combination with your Jina Flow, but the configuration files
+generated by `to_kubernetes_config()` already include all necessary annotations for the [Linkerd service mesh](https://linkerd.io).
+
+````{admonition} Hint
+:class: hint
+You can use any service mesh with Jina, but Jina Kubernetes configurations come with Linkerd annotations out of the box.
+````
+
+To use Linkerd you can follow the [install the Linkerd CLI](https://linkerd.io/2.11/getting-started/).
+
+````{admonition} Caution
+:class: caution
+
+Many service meshes can perform retries themselves.
+Be careful about setting up service mesh level retries in combination with Jina, as it may lead to unwanted behaviour in combination with
+Jina's own {ref}`retry policy <flow-error-handling>`.
+
+Instead, you can disable Jina level retries by setting `Flow(retries=0)` in Python, or `retries: 0` in the Flow
+YAML `with` block.
+````
+
+
+(kubernetes-replicas)=
+## Scaling Executors: Replicas and shards
+
+Jina supports two ways of scaling:
+
+- **Replicas** can be used with any Executor type and are typically used for performance and availability.
+- **Shards** are used for partitioning data and should only be used with indexers since they store state.
+
+Check {ref}`here <scale-out>` for more information about these scaling mechanisms.
+
+For shards, Jina creates a separate Deployment in Kubernetes per Shard.
+Setting `f.add(..., shards=num_shards)` is sufficient to create a corresponding Kubernetes configuration.
+
+For replicas, Jina uses [Kubernetes native replica scaling](https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/) and **relies on a service mesh** to load balance requests between replicas of the same Executor.
+Without a service mesh installed in your Kubernetes cluster, all traffic will be routed to the same replica.
+
+````{admonition} See Also
+:class: seealso
+
+The impossibility of load balancing between different replicas is a limitation of Kubernetes in combination with gRPC.
+If you want to learn more about this limitation, see [this](https://kubernetes.io/blog/2018/11/07/grpc-load-balancing-on-kubernetes-without-tears/) Kubernetes Blog post.
+````
+
+## Scaling the Gateway
+The Gateway is responsible for providing the API of the {ref}`Flow <flow>`.
+If you have a large Flow with many Clients and many replicated Executors, the Gateway can become the bottleneck.
+In this case you can also scale up the Gateway deployment to be backed by multiple Kubernetes Pods.
+This is done by the regular means of Kubernetes: Either increase the number of replicas in the  {ref}`generated yaml configuration files <kubernetes-deploy>` or [add replicas while running](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment).
+To expose your Gateway replicas outside Kubernetes, you can add a load balancer as described {ref}`here <kubernetes-expose>`.
+
+````{admonition} Hint
+:class: hint
+You can use a custom Docker image for the Gateway deployment by setting the envrironment variable `JINA_GATEWAY_IMAGE` to the desired image before generating the configuration.
+````
+
+
+## Deploying On Jina AI Cloud
+
+Jina AI host its own Cloud based on Kubernetes cluster to manage your Flow:
+
+```{hint}
+Check out {ref}`jcloud` if you want a **one-click** solution to deploy and host Jina, leveraging a cloud-native stack of Kubernetes, Prometheus and Grafana, **without worrying about provisioning**.
+```
+
+:::::{grid} 2
+:gutter: 3
+
+::::{grid-item-card} {octicon}`cpu;1.5em` Deploy a Flow to JCloud
+:link: fundamentals/jcloud/index
+:link-type: doc
+:class-card: color-gradient-card-2
+
+JCloud is a free CPU/GPU hosting platform for Jina projects.
+::::
+:::::
+
+
+
+## See further
+- {ref}`Step by Step deployement of a Jina Flow on K8s <kubernetes>`
+- {ref}`Flow export documentation <kubernetes-export>`
+-{meth}`~jina.Flow.to_kubernetes_yaml`
+- {ref}`Documentation on deploying a standalone Executor on K8s <kubernetes-executor>`
+- [Kubernetes Documentation](https://kubernetes.io/docs/home/)
\ No newline at end of file
diff --git a/docs/how-to/kubernetes.md b/docs/how-to/kubernetes.md
index 81ef04fcd27f4..963c563a0af2a 100644
--- a/docs/how-to/kubernetes.md
+++ b/docs/how-to/kubernetes.md
@@ -1,8 +1,20 @@
 (kubernetes)=
-# Deploy with Kubernetes
+# Deploy on Kubernetes
 
+This how-to will go through deploying a simple Flow using Kubernetes, customizing the Kubernetes configuration
+to your needs, and scaling Executors using replicas and shards.
+
+Deploying a {class}`~jina.Flow` in Kubernetes is the recommended way to use Jina in production.
+
+Since a {class}`~jina.Flow` is composed of {class}`~jina.Executor`s which can run in different runtimes depending on how you deploy
+the Flow, Kubernetes can easily take over the lifetime management of Executors.  
+
+```{seelaso}
+This page is a step by step guide, refer to the {ref}`Kubernetes support documentation <kubernetes-docs>` for more details
+```
 
-```{tip}
+
+```{hint}
 This guide is designed for users who want to **manually** deploy a Jina project on Kubernetes.
 
 Check out {ref}`jcloud` if you want a **one-click** solution to deploy and host Jina, leveraging a cloud-native stack of Kubernetes, Prometheus and Grafana, **without worrying about provisioning**.
@@ -21,20 +33,6 @@ JCloud is a free CPU/GPU hosting platform for Jina projects.
 ::::
 :::::
 
-
-Deploying a {class}`~jina.Flow` in Kubernetes is the recommended way to use Jina in production.
-
-Since a {class}`~jina.Flow` is composed of {class}`~jina.Executor`s which can run in different runtimes depending on how you deploy
-the Flow, Kubernetes can easily take over the lifetime management of Executors. 
-
-In general, Jina follows the following principle when it comes to deploying in Kubernetes:
-You, the user, know your use case and requirements the best.
-This means that while Jina generates configurations for you that run out of the box, as a professional user you should
-always see them as just a starting point to get you off the ground.
-
-This how-to will go through deploying a simple Flow using Kubernetes, customizing the Kubernetes configuration
-to your needs, and scaling Executors using replicas and shards.
-
 ## Preliminaries
 
 To follow this how-to, you need access to a Kubernetes cluster.
@@ -46,8 +44,12 @@ solutions in the cloud:
 - [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service)
 - [Digital Ocean](https://www.digitalocean.com/products/kubernetes/)
 
+And you need to install Linkerd in your K8s cluster.  To use Linkerd, [install the Linkerd CLI](https://linkerd.io/2.11/getting-started/).
+After that, [install its control plane](https://linkerd.io/2.11/getting-started/) in your cluster.
+This automatically sets up and manages the service mesh proxies when you deploy the Flow.
+
+To understand why you need to install a service mesh like Linkerd refer to this  {ref}`section <service-mesh-k8s>`
 
-(kubernetes-deploy)=
 ## Deploy a simple Flow
 
 By *simple* in this context we mean a Flow without replicated or sharded Executors - you can see how to use those in
@@ -162,67 +164,6 @@ with portforward.forward('custom-namespace', 'gateway-7df8765bd9-xf5tf', 8080, 8
     print(f' Indexed documents: {len(docs)}')
 ```
 
-(kubernetes-replicas)=
-## Scaling Executors: Replicas and shards
-
-Jina supports two ways of scaling:
-
-- **Replicas** can be used with any Executor type and are typically used for performance and availability.
-- **Shards** are used for partitioning data and should only be used with indexers since they store state.
-
-Check {ref}`here <scale-out>` for more information about these scaling mechanisms.
-
-For shards, Jina creates a separate Deployment in Kubernetes per Shard.
-Setting `f.add(..., shards=num_shards)` is sufficient to create a corresponding Kubernetes configuration.
-
-For replicas, Jina uses [Kubernetes native replica scaling](https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/) and **relies on a service mesh** to load balance requests between replicas of the same Executor.
-Without a service mesh installed in your Kubernetes cluster, all traffic will be routed to the same replica.
-
-````{admonition} See Also
-:class: seealso
-
-The impossibility of load balancing between different replicas is a limitation of Kubernetes in combination with gRPC.
-If you want to learn more about this limitation, see [this](https://kubernetes.io/blog/2018/11/07/grpc-load-balancing-on-kubernetes-without-tears/) Kubernetes Blog post.
-````
-
-### Install a service mesh
-
-Service meshes work by attaching a tiny proxy to each of your Kubernetes pods, allowing for smart rerouting, load balancing,
-request retrying, and host of other [features](https://linkerd.io/2.11/features/).
-
-Jina relies on a service mesh to load balance request between replicas of the same Executor.
-You can use your favourite Kubernetes service mesh in combination with your Jina Flow, but the configuration files
-generated by `to_kubernetes_config()` already include all necessary annotations for the [Linkerd service mesh](https://linkerd.io).
-
-````{admonition} Hint
-:class: hint
-You can use any service mesh with Jina, but Jina Kubernetes configurations come with Linkerd annotations out of the box.
-````
-
-To use Linkerd, [install the Linkerd CLI](https://linkerd.io/2.11/getting-started/).
-After that, [install its control plane](https://linkerd.io/2.11/getting-started/) in your cluster.
-This automatically sets up and manages the service mesh proxies when you deploy the Flow.
-
-Once the Flow is deployed on Kubernetes, you can use all the native Kubernetes tools like `kubectl` to perform operations on the Pods and Deployments. 
-
-You can use this to [add or remove replicas](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment), to run [rolling update](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#updating-a-deployment) operations, etc ...
-
-````{admonition} Caution
-:class: caution
-
-Many service meshes can perform retries themselves.
-Be careful about setting up service mesh level retries in combination with Jina, as it may lead to unwanted behaviour in combination with
-Jina's own {ref}`retry policy <flow-error-handling>`.
-
-Instead, you can disable Jina level retries by setting `Flow(retries=0)` in Python, or `retries: 0` in the Flow
-YAML `with` block.
-````
-
-````{admonition} Matching jina versions
-:class: caution
-If you change the Docker images in your Docker Compose generated file, ensure that all services included in the gateway are built with the same Jina version to guarantee compatibility.
-````
-
 ### Deploy Flow with shards and replicas
 
 After your service mesh is installed, your cluster is ready to run a Flow with scaled Executors.
@@ -275,37 +216,6 @@ If you already have the simple Flow from the first example running on your clust
 kubectl apply -R -f ./k8s_flow
 ```
 
-## Scaling the Gateway
-The Gateway is responsible for providing the API of the {ref}`Flow <flow>`.
-If you have a large Flow with many Clients and many replicated Executors, the Gateway can become the bottleneck.
-In this case you can also scale up the Gateway deployment to be backed by multiple Kubernetes Pods.
-This is done by the regular means of Kubernetes: Either increase the number of replicas in the  {ref}`generated yaml configuration files <kubernetes-deploy>` or [add replicas while running](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment).
-To expose your Gateway replicas outside Kubernetes, you can add a load balancer as described {ref}`here <kubernetes-expose>`.
-
-````{admonition} Hint
-:class: hint
-You can use a custom Docker image for the Gateway deployment by setting the envrironment variable `JINA_GATEWAY_IMAGE` to the desired image before generating the configuration.
-````
-
-## Extra Kubernetes options
-
-You can't add basic Kubernetes feature like `Secrets`, `ConfigMap` or `Labels` via the Pythonic interface. This is intentional
-and doesn't mean that we don't support these features. On the contrary, we let you fully express your Kubernetes configuration by using the Kubernetes API to add you own Kubernetes standard to Jina.
-
-````{admonition} Hint
-:class: hint
-We recommend dumping the Kubernetes configuration files and then editing the files to suit your needs.
-````
-
-Here are possible configuration options you may need to add or change
-
-- Add labels `selector`s to the Deployments to suit your case
-- Add `requests` and `limits` for the resources of the different Pods 
-- Set up persistent volume storage to save your data on disk
-- Pass custom configuration to your Executor with `ConfigMap` 
-- Manage credentials of your Executor with secrets
-- Edit the default rolling update configuration
-
 
 (kubernetes-expose)=
 ## Exposing the Flow
@@ -407,14 +317,14 @@ You can find more information about these commands in the [official Kubernetes d
 
 ## Key takeaways
 
-To put it briefly, there are just three key takeaways about deploying a Jina Flow on Kubernetes:
+To put it briefly, there are just three key steps about deploying a Jina Flow on Kubernetes:
 
 1. Use `f.to_kubernetes_yaml()` to generate Kubernetes configuration files from a Jina Flow object.
-2. Modify the generated files freely - you know better what you need than we do!
-3. Use a service mesh to enable replicated Executors.
+2. Apply the generated file via `kubectl`(Modify the generated files if necessary)
+3. Expose your Flow outside the K8s cluster
 
 ## See also
-
+- {ref}`Kubernetes support documentation <kubernetes-docs>`
 - {ref}`Monitor the Flow once it is deployed <monitoring>`
 - {ref}`See how failures and retries are handled <flow-error-handling>`
 - {ref}`Learn more about scaling Executors <scale-out>`
diff --git a/docs/index.md b/docs/index.md
index c60b6b6b81f65..aa6897ef6b8e5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -142,6 +142,7 @@ fundamentals/executor/index
 fundamentals/flow/index
 fundamentals/gateway/index
 fundamentals/client/client
+fundamentals/k8s
 jina-ai-cloud/index
 how-to/index
 ```


Code review comments:
diff_hunk: @@ -0,0 +1,159 @@
+(kubernetes-docs)=
+# Kubernetes Support
+
+Jina is a cloud native framework and therefore run natively and easily on Kubernetes.
+Deploying a Jina Flow on Kubernetes is actually the recommended way to use Jina in production.
+
+
+A {class}`~jina.Flow` is composed of different microservices called {class}`~jina.Executor`s which natively run in container. This mean that Kubernetes can natively take over the lifetime management of Executors. 
+
+Deploying a {class}`~jina.Flow` on Kubernetes means wrapping these microservices container in the appropriate K8s abstraction (Deployment, StatefulSet, ...) expose them internally via K8s Service and 
+connecting them together by passing the right set of parameters.
+
+## Automatically translate a Flow to Kubernetes concept
+
+
+```{hint}
+Manually building these Kubernetes YAML object is long and cumbersome. Therefore we provide a helper function {meth}`~jina.Flow.to_kubernetes_yaml` that does most of this
+translation work automatically. 
+```
+
+This helper function can be called from:
+* our Python interface to translate a Flow define in Python to k8s yaml files
+* our CLI interface to export a YAML Flow to k8s yaml files
+
+```{seealso}
+More detail in the {ref}`Flow export documentation <kubernetes-export>`
+```
+
+
+## Extra Kubernetes options
+
+In general, Jina follows the following principle when it comes to deploying in Kubernetes:
+You, the user, know your use case and requirements the best.
+This means that while Jina generates configurations for you that run out of the box, as a professional user you should
+always see them as just a starting point to get you off the ground.
+
+```{hint}
+The export funciton{meth}`~jina.Flow.to_kubernetes_yaml` is a helper function to get your stared off the ground. **There are meant to be updated and adapted to every use case**
+```
+````{admonition} Matching jina versions
+:class: caution
+If you change the Docker images for {class}`~jina.Executor` and {class}`~jina.Gateway` in your Kubernetes generated file, ensure that al of them are built with the same Jina version to guarantee compatibility.
+````
+
+You can't add basic Kubernetes feature like `Secrets`, `ConfigMap` or `Labels` via the Pythonic or YAML interface. This is intentional
+and doesn't mean that we don't support these features. On the contrary, we let you fully express your Kubernetes configuration by using the Kubernetes API to add you own Kubernetes standard to Jina.
+
+````{admonition} Hint
+:class: hint
+We recommend dumping the Kubernetes configuration files and then editing the files to suit your needs.
+````
+
+Here are possible configuration options you may need to add or change
+
+- Add labels `selector`s to the Deployments to suit your case
+- Add `requests` and `limits` for the resources of the different Pods 
+- Set up persistent volume storage to save your data on disk
+- Pass custom configuration to your Executor with `ConfigMap` 
+- Manage credentials of your Executor with secrets
+- Edit the default rolling update configuration
+
+
+(service-mesh-k8s)=
+## Required Service Mesh 
+
+```{caution}
+A Service Mesh is required to be installed and correctly configured in the K8s clusteri in which your deployed your Flow.
+```
+
+Service meshes work by attaching a tiny proxy to each of your Kubernetes pods, allowing for smart rerouting, load balancing,
+request retrying, and host of other [features](https://linkerd.io/2.11/features/).
+
+Jina relies on a service mesh to load balance request between replicas of the same Executor.
+You can use your favourite Kubernetes service mesh in combination with your Jina Flow, but the configuration files
+generated by `to_kubernetes_config()` already include all necessary annotations for the [Linkerd service mesh](https://linkerd.io).
+
+````{admonition} Hint
+:class: hint
+You can use any service mesh with Jina, but Jina Kubernetes configurations come with Linkerd annotations out of the box.
+````
+
+To use Linkerd you can follow the [install the Linkerd CLI](https://linkerd.io/2.11/getting-started/).
+
+````{admonition} Caution
+:class: caution
+
+Many service meshes can perform retries themselves.
+Be careful about setting up service mesh level retries in combination with Jina, as it may lead to unwanted behaviour in combination with
+Jina's own {ref}`retry policy <flow-error-handling>`.
+
+Instead, you can disable Jina level retries by setting `Flow(retries=0)` in Python, or `retries: 0` in the Flow
+YAML `with` block.
+````
+
+
+(kubernetes-replicas)=
+## Scaling Executors: Replicas and shards
+
+Jina supports two ways of scaling:
+
+- **Replicas** can be used with any Executor type and are typically used for performance and availability.
+- **Shards** are used for partitioning data and should only be used with indexers since they store state.
+
+Check {ref}`here <scale-out>` for more information about these scaling mechanisms.
+
+For shards, Jina creates a separate Deployment in Kubernetes per Shard.
+Setting `f.add(..., shards=num_shards)` is sufficient to create a corresponding Kubernetes configuration.
+
+For replicas, Jina uses [Kubernetes native replica scaling](https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/) and **relies on a service mesh** to load balance requests between replicas of the same Executor.
+Without a service mesh installed in your Kubernetes cluster, all traffic will be routed to the same replica.
+
+````{admonition} See Also
+:class: seealso
+
+The impossibility of load balancing between different replicas is a limitation of Kubernetes in combination with gRPC.
+If you want to learn more about this limitation, see [this](https://kubernetes.io/blog/2018/11/07/grpc-load-balancing-on-kubernetes-without-tears/) Kubernetes Blog post.
+````
+
+## Scaling the Gateway
+The Gateway is responsible for providing the API of the {ref}`Flow <flow>`.
+If you have a large Flow with many Clients and many replicated Executors, the Gateway can become the bottleneck.
+In this case you can also scale up the Gateway deployment to be backed by multiple Kubernetes Pods.
+This is done by the regular means of Kubernetes: Either increase the number of replicas in the  {ref}`generated yaml configuration files <kubernetes-deploy>` or [add replicas while running](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment).
+To expose your Gateway replicas outside Kubernetes, you can add a load balancer as described {ref}`here <kubernetes-expose>`.
+
+````{admonition} Hint
+:class: hint
+You can use a custom Docker image for the Gateway deployment by setting the envrironment variable `JINA_GATEWAY_IMAGE` to the desired image before generating the configuration.
+````
+
+
+## Deploying On Jina AI Cloud
+
+Jina AI host its own Cloud based on Kubernetes cluster to manage your Flow:
path: docs/fundamentals/k8s.md
text: @user1:
~Jina AI host~ Jina AI hosts? This sentence is a bit strange.

Check out Jina AI Cloud, the one-click solution to deploy and host Jina Flows, leveraging a cloud-native stack of Kubernetes, Prometheus and Grafana, without worrying about provisioning.

And then remove the Hint and update the JCloud page to also introduce Jina AI Cloud directly (?)

diff_hunk: @@ -0,0 +1,159 @@
+(kubernetes-docs)=
+# Kubernetes Support
+
+Jina is a cloud native framework and therefore run natively and easily on Kubernetes.
+Deploying a Jina Flow on Kubernetes is actually the recommended way to use Jina in production.
+
+
+A {class}`~jina.Flow` is composed of different microservices called {class}`~jina.Executor`s which natively run in container. This mean that Kubernetes can natively take over the lifetime management of Executors. 
+
+Deploying a {class}`~jina.Flow` on Kubernetes means wrapping these microservices container in the appropriate K8s abstraction (Deployment, StatefulSet, ...) expose them internally via K8s Service and 
+connecting them together by passing the right set of parameters.
+
+## Automatically translate a Flow to Kubernetes concept
+
+
+```{hint}
+Manually building these Kubernetes YAML object is long and cumbersome. Therefore we provide a helper function {meth}`~jina.Flow.to_kubernetes_yaml` that does most of this
+translation work automatically. 
+```
+
+This helper function can be called from:
+* our Python interface to translate a Flow define in Python to k8s yaml files
+* our CLI interface to export a YAML Flow to k8s yaml files
+
+```{seealso}
+More detail in the {ref}`Flow export documentation <kubernetes-export>`
+```
+
+
+## Extra Kubernetes options
+
+In general, Jina follows the following principle when it comes to deploying in Kubernetes:
+You, the user, know your use case and requirements the best.
+This means that while Jina generates configurations for you that run out of the box, as a professional user you should
+always see them as just a starting point to get you off the ground.
+
+```{hint}
+The export funciton{meth}`~jina.Flow.to_kubernetes_yaml` is a helper function to get your stared off the ground. **There are meant to be updated and adapted to every use case**
+```
+````{admonition} Matching jina versions
+:class: caution
+If you change the Docker images for {class}`~jina.Executor` and {class}`~jina.Gateway` in your Kubernetes generated file, ensure that al of them are built with the same Jina version to guarantee compatibility.
+````
+
+You can't add basic Kubernetes feature like `Secrets`, `ConfigMap` or `Labels` via the Pythonic or YAML interface. This is intentional
+and doesn't mean that we don't support these features. On the contrary, we let you fully express your Kubernetes configuration by using the Kubernetes API to add you own Kubernetes standard to Jina.
+
+````{admonition} Hint
+:class: hint
+We recommend dumping the Kubernetes configuration files and then editing the files to suit your needs.
+````
+
+Here are possible configuration options you may need to add or change
+
+- Add labels `selector`s to the Deployments to suit your case
+- Add `requests` and `limits` for the resources of the different Pods 
+- Set up persistent volume storage to save your data on disk
+- Pass custom configuration to your Executor with `ConfigMap` 
+- Manage credentials of your Executor with secrets
+- Edit the default rolling update configuration
+
+
+(service-mesh-k8s)=
+## Required Service Mesh 
+
+```{caution}
+A Service Mesh is required to be installed and correctly configured in the K8s clusteri in which your deployed your Flow.
+```
+
+Service meshes work by attaching a tiny proxy to each of your Kubernetes pods, allowing for smart rerouting, load balancing,
+request retrying, and host of other [features](https://linkerd.io/2.11/features/).
+
+Jina relies on a service mesh to load balance request between replicas of the same Executor.
path: docs/fundamentals/k8s.md
text: @user1:
~to load balance request~ to load balance requests