diff --git a/app/_redirects b/app/_redirects index b94ad99c0..87752f442 100644 --- a/app/_redirects +++ b/app/_redirects @@ -30,6 +30,7 @@ /transparent-proxying-reachable-services/ /docs/LATEST_RELEASE/reference/kubernetes-annotations/#kumaiotransparent-proxying-reachable-services 302 /virtual-probes-port/ /docs/LATEST_RELEASE/reference/kubernetes-annotations/#kumaiovirtual-probes-port 302 /virtual-probes/ /docs/LATEST_RELEASE/reference/kubernetes-annotations/#kumaiovirtual-probes 302 +/wait-for-dataplane-ready/ /docs/LATEST_RELEASE/reference/kubernetes-annotations/#kumaiowait-for-dataplane-ready 302 # kuma.io subdomain redirects https://prometheus.metrics.kuma.io/port /docs/LATEST_RELEASE/reference/kubernetes-annotations/#prometheus-metrics-kuma-io-port/ 302 diff --git a/app/_src/production/dp-config/dpp-on-kubernetes.md b/app/_src/production/dp-config/dpp-on-kubernetes.md index 566f4a643..a2855af8a 100644 --- a/app/_src/production/dp-config/dpp-on-kubernetes.md +++ b/app/_src/production/dp-config/dpp-on-kubernetes.md @@ -184,6 +184,32 @@ To join the mesh in a graceful way, we need to first make sure the application i When `Pod` is converted to a `Dataplane` object it will be marked as unhealthy until Kubernetes considers all containers to be ready. +{% if_version gte:2.4.x %} +### Waiting for the dataplane to be ready + +By default, containers start in any order, so an app container can start even though a dataplane container might not be ready to receive traffic. + +Making initial requests, such as connecting to a database, can fail for a brief period after the pod starts. + +To mitigate this problem try setting +* `runtime.kubernetes.injector.sidecarContainer.waitForDataplaneReady` to `true`, or +* [kuma.io/wait-for-dataplane-ready](/docs/{{ page.version }}/reference/kubernetes-annotations/#kumaiowait-for-dataplane-ready) annotation to `true` +so that the app container waits for the dataplane container to be ready to serve traffic. + +{% warning %} + +The `waitForDataplaneReady` setting relies on the fact that defining a `postStart` hook causes Kubernetes to run containers sequentially based on their order of occurrence in the `containers` list. +This isn't documented and could change in the future. +It also depends on injecting the kuma-sidecar container as the first container in the pod, which isn't guaranteed since other mutating webhooks can rearrange the containers. + + +A better solution will be available when [sidecar containers](https://kubernetes.io/blog/2023/08/25/native-sidecar-containers/) are more stable and widely available. + +{% endwarning %} + +{% endif_version %} + + ### Leaving the mesh To leave the mesh in a graceful shutdown, we need to remove the traffic destination from all the clients before shutting it down. diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index 31f50f664..3f304a482 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -605,6 +605,14 @@ spec: [...] ``` +{% if_version gte:2.4.x %} +### `kuma.io/wait-for-dataplane-ready` + +Define if you want the kuma-sidecar container to wait for the dataplane to be ready before starting app container. +Read relevant [Data plane on Kubernetes](/docs/{{ page.version }}/production/dp-config/dpp-on-kubernetes/#waiting-for-the-dataplane-to-be-ready) section for more information. + +{% endif_version %} + ### `prometheus.metrics.kuma.io/aggregate--enabled` Define if `kuma-dp` should scrape metrics from the application that has been defined in the `Mesh` configuration. Default value: `true`. For more details see the [applications metrics docs](/docs/{{ page.version }}/policies/traffic-metrics#expose-metrics-from-applications)