From 1d8a8de4b22ac8b66a1defaae275d63c94c34c3f Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 22 Sep 2023 17:21:43 -0400 Subject: [PATCH] Add Kubernetes overview page (#744) * Move Kubernetes overview content into dedicated page * Apply suggestions from code review Co-authored-by: Will <28876888+willtsai@users.noreply.github.com> * Fix path * Update docs/content/guides/operations/kubernetes/overview/index.md minor grammatical fix --------- Co-authored-by: Will <28876888+willtsai@users.noreply.github.com> --- .../author-apps/application/overview/index.md | 2 +- .../author-apps/azure/overview/index.md | 2 +- .../author-apps/containers/overview/index.md | 2 +- .../observability/logging/fluentd/index.md | 2 +- .../observability/metrics/prometheus/index.md | 2 +- .../groups/howto-resourcegroups/index.md | 2 +- .../guides/operations/kubernetes/_index.md | 1 - .../kubernetes/kubernetes-install.md | 2 +- .../kubernetes/kubernetes-mapping/index.md | 41 -------------- .../kubernetes/kubernetes-metadata/index.md | 2 +- .../index.md} | 53 +++++++++++++++--- .../kubernetes-mapping.png | Bin .../providers/howto-aws-provider/index.md | 2 +- .../core-schema/application-schema/_index.md | 2 +- docs/content/tutorials/tutorial-dapr/index.md | 2 +- 15 files changed, 55 insertions(+), 62 deletions(-) delete mode 100644 docs/content/guides/operations/kubernetes/kubernetes-mapping/index.md rename docs/content/guides/operations/kubernetes/{supported-clusters.md => overview/index.md} (57%) rename docs/content/guides/operations/kubernetes/{kubernetes-mapping => overview}/kubernetes-mapping.png (100%) diff --git a/docs/content/guides/author-apps/application/overview/index.md b/docs/content/guides/author-apps/application/overview/index.md index 6c6dbaa25..f3cc83663 100644 --- a/docs/content/guides/author-apps/application/overview/index.md +++ b/docs/content/guides/author-apps/application/overview/index.md @@ -26,7 +26,7 @@ Extensions allow you to customize how resources are generated or customized as p ### Kubernetes Namespace extension -The Kubernetes namespace extension allows you to customize how all of the resources within your application generate Kubernetes resources. See the [Kubernetes mapping guide]({{< ref kubernetes-mapping >}}) for more information on namespace mapping behavior. +The Kubernetes namespace extension allows you to customize how all of the resources within your application generate Kubernetes resources. See the [Kubernetes mapping guide]({{< ref "/guides/operations/kubernetes/overview#resource-mapping" >}}) for more information on namespace mapping behavior ### Kubernetes Metadata extension diff --git a/docs/content/guides/author-apps/azure/overview/index.md b/docs/content/guides/author-apps/azure/overview/index.md index b4831105c..166051eb4 100644 --- a/docs/content/guides/author-apps/azure/overview/index.md +++ b/docs/content/guides/author-apps/azure/overview/index.md @@ -12,7 +12,7 @@ Radius applications are able to connect to and leverage every Azure resource wit ## Configure an Azure Provider -The Azure provider allows you to deploy and connect to Azure resources from a Radius environment on any of the [supported clusters]({{< ref supported-clusters>}}). To configure an Azure provider, you can follow the documentation [here]({{< ref "/guides/operations/providers/howto-azure-provider" >}}). +The Azure provider allows you to deploy and connect to Azure resources from a Radius environment on any of the [supported clusters]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}). To configure an Azure provider, you can follow the documentation [here]({{< ref "/guides/operations/providers/howto-azure-provider" >}}). ## Resource library diff --git a/docs/content/guides/author-apps/containers/overview/index.md b/docs/content/guides/author-apps/containers/overview/index.md index b6b99a2ff..490368447 100644 --- a/docs/content/guides/author-apps/containers/overview/index.md +++ b/docs/content/guides/author-apps/containers/overview/index.md @@ -26,7 +26,7 @@ Additionally you can customize the behavior of the containers with the help of [ An image can be specified for your container workload to pull and run. Refer to the [container reference docs]({{< ref container-schema >}}) for more information on image requirements. -If you want to pull the container image from a private container register, you need to allow access from your Kubernetes cluster. Follow the documentation to [configure private container registries access]({{< ref "guides/operations/kubernetes/supported-clusters#configure-container-registry-access" >}}). +If you want to pull the container image from a private container register, you need to allow access from your Kubernetes cluster. Follow the documentation to [configure private container registries access]({{< ref "/guides/operations/kubernetes/overview#configure-container-registry-access" >}}). ### Ports diff --git a/docs/content/guides/operations/control-plane/observability/logging/fluentd/index.md b/docs/content/guides/operations/control-plane/observability/logging/fluentd/index.md index eec52a7aa..8babf8e80 100644 --- a/docs/content/guides/operations/control-plane/observability/logging/fluentd/index.md +++ b/docs/content/guides/operations/control-plane/observability/logging/fluentd/index.md @@ -10,7 +10,7 @@ tags: ["logs","observability"] ## Prerequisites -- [Supported Kubernetes cluster]({{< ref supported-clusters >}}) +- [Supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}) - [kubectl](https://kubernetes.io/docs/tasks/tools/) - [Helm 3](https://helm.sh/) diff --git a/docs/content/guides/operations/control-plane/observability/metrics/prometheus/index.md b/docs/content/guides/operations/control-plane/observability/metrics/prometheus/index.md index d46f7d20d..660b4e91f 100644 --- a/docs/content/guides/operations/control-plane/observability/metrics/prometheus/index.md +++ b/docs/content/guides/operations/control-plane/observability/metrics/prometheus/index.md @@ -14,7 +14,7 @@ tags: ["metrics", "observability"] 1. Make sure you have the following pre-requisites: - - [Supported Kubernetes cluster]({{< ref supported-clusters >}}) + - [Supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}) - [kubectl](https://kubernetes.io/docs/tasks/tools/) - [Helm 3](https://helm.sh/) - [Radius control plane installed]({{< ref kubernetes-install >}}) diff --git a/docs/content/guides/operations/groups/howto-resourcegroups/index.md b/docs/content/guides/operations/groups/howto-resourcegroups/index.md index 08c1fa1dd..5ab4a4681 100644 --- a/docs/content/guides/operations/groups/howto-resourcegroups/index.md +++ b/docs/content/guides/operations/groups/howto-resourcegroups/index.md @@ -10,7 +10,7 @@ This guide will walk you through the process of managing resource groups in Radi ## Pre-requisites -- [Supported Kubernetes cluster]({{< ref supported-clusters >}}) +- [Supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}) - [Radius CLI]({{< ref howto-rad-cli >}}) ## Step 1: Ensure Radius is installed diff --git a/docs/content/guides/operations/kubernetes/_index.md b/docs/content/guides/operations/kubernetes/_index.md index bd6df30b7..7853afc35 100644 --- a/docs/content/guides/operations/kubernetes/_index.md +++ b/docs/content/guides/operations/kubernetes/_index.md @@ -4,5 +4,4 @@ title: "Kubernetes platform" linkTitle: "Kubernetes" description: "Learn how Radius can run on Kubernetes" weight: 10 -tags: ["Kubernetes"] --- diff --git a/docs/content/guides/operations/kubernetes/kubernetes-install.md b/docs/content/guides/operations/kubernetes/kubernetes-install.md index 59e1692f2..3306323ba 100644 --- a/docs/content/guides/operations/kubernetes/kubernetes-install.md +++ b/docs/content/guides/operations/kubernetes/kubernetes-install.md @@ -1,6 +1,6 @@ --- type: docs -title: "Install Radius on Kubernetes" +title: "How-To: Install Radius on Kubernetes" linkTitle: "Installation" description: "Learn how to setup Radius on supported Kubernetes clusters" weight: 200 diff --git a/docs/content/guides/operations/kubernetes/kubernetes-mapping/index.md b/docs/content/guides/operations/kubernetes/kubernetes-mapping/index.md deleted file mode 100644 index 77989016f..000000000 --- a/docs/content/guides/operations/kubernetes/kubernetes-mapping/index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -type: docs -title: "Radius resource to Kubernetes object mapping" -linkTitle: "Resource mapping" -description: "Learn how Radius resources map to Kubernetes objects" -weight: 200 -slug: "resource-mapping" -categories: "Concept" -tags: ["Kubernetes"] ---- - -When deploying resources such as a containers to environments running on Kubernetes, Radius will map these resources into one or more Kubernetes objects. This page describes these mappings and naming conventions. - -Diagram showing Radius resources being mapped to Kubernetes objects - -## Namespace mapping - -Application-scoped resources are by default generated in a new Kubernetes namespace with the name format `-'`. This prevents multiple applications with resources of the same name from conflicting with each other. - -For example, let's take an application named `'myapp'` with a container named `'frontend'`. This application is deployed into an environment configured with with the `'default'` namespace. A Kubernetes Deployment named `'frontend'` is now deployed into the namespace `'default-myapp'`. - -If you wish to override the default behavior and specify your own namespace for application resources to be generated into, you can leverage the [`kubernetesNamespace` application extension]({{< ref "application-schema#kubernetesNamespace" >}}). All application-scoped resources will now be deployed into this namespace instead. - -## Resource mapping - -The following resources map to Kubernetes objects: - -| Radius resource | Kubernetes object | -|----------------------------------|-------------------| -| [`Applications.Core/containers`]({{< ref container-schema >}}) | `apps/Deployment@v1` | -| [`Applications.Core/httpRoutes`]({{< ref httproute >}}) | `core/Service@v1` | -| [`Applications.Core/gateways`]({{< ref gateway >}}) | `projectcontour.io/HTTPProxy@v1` | -| [`Applications.Dapr/pubSubBrokers`]({{< ref dapr-pubsub >}}) | `dapr.io/Component@v1alpha1` | -| [`Applications.Dapr/secretStores`]({{< ref dapr-secretstore >}}) | `dapr.io/Component@v1alpha1` | -| [`Applications.Dapr/stateStores`]({{< ref dapr-statestore >}}) | `dapr.io/Component@v1alpha1` | - -## Resource naming - -Resources that are generated in Kubernetes use the same name as the resource in Radius. For example, a Radius container named 'frontend' will map to a Kubernetes Deployment named 'frontend'. This makes it easy to conceptually map between Radius and Kubernetes resources. - -For multiple Radius resources that map to a single Kubernetes resources (_i.e. daprPubSubBrokers, daprSecretStores, and daprStateStores all map to a dapr.io/Component_), when there are collisions in naming Radius has conflict logic to allow the first resource to be deployed, but throw a warning for subsequent resource deployments that have the same name. This prevents Radius resources unintentionally overwriting the same generated resource. diff --git a/docs/content/guides/operations/kubernetes/kubernetes-metadata/index.md b/docs/content/guides/operations/kubernetes/kubernetes-metadata/index.md index adb56bc2d..57db8eefa 100644 --- a/docs/content/guides/operations/kubernetes/kubernetes-metadata/index.md +++ b/docs/content/guides/operations/kubernetes/kubernetes-metadata/index.md @@ -38,7 +38,7 @@ You can set labels and annotations on an environment, application, or container ## Cascading metadata -Kubernetes metadata can be applied at the environment, application, or container layers. Metadata cascades down from the environment to the application to the containers, gateway and route resources. For example, you can set labels and annotations at an environment level and all containers within the environment will gain these labels and annotation, without the need for an explicit extension on the containers. The following resources will gain the Kubernetes metadata for their [output resources]({{< ref kubernetes-mapping >}}) from labels, annotations set at Environment, Application levels: +Kubernetes metadata can be applied at the environment, application, or container layers. Metadata cascades down from the environment to the application to the containers, gateway and route resources. For example, you can set labels and annotations at an environment level and all containers within the environment will gain these labels and annotation, without the need for an explicit extension on the containers. The following resources will gain the Kubernetes metadata for their [output resources]({{< ref "/guides/operations/kubernetes/overview#resource-mapping" >}}) from labels, annotations set at Environment, Application levels: - Applications.Core/containers - Applications.Core/httpRoutes diff --git a/docs/content/guides/operations/kubernetes/supported-clusters.md b/docs/content/guides/operations/kubernetes/overview/index.md similarity index 57% rename from docs/content/guides/operations/kubernetes/supported-clusters.md rename to docs/content/guides/operations/kubernetes/overview/index.md index 390567eaa..740ec5447 100644 --- a/docs/content/guides/operations/kubernetes/supported-clusters.md +++ b/docs/content/guides/operations/kubernetes/overview/index.md @@ -1,20 +1,55 @@ --- type: docs -title: "Supported Kubernetes clusters" -linkTitle: "Supported clusters" -description: "Learn how to setup Radius on supported Kubernetes clusters" +title: "Overview: Radius on Kubernetes platform" +linkTitle: "Overview" +description: "Learn how Radius can run on Kubernetes" weight: 100 -categories: "How-To" -tags: ["Kubernetes", "control plane"] -aliases: - - /operations/kubernetes/supported-clusters/ +categories: ["Overview"] +tags: ["Kubernetes"] --- -## Minimum version +Radius offers a Kubernetes-based platform for hosting the [Radius control plane]({{< ref "/guides/operations/control-plane" >}}) and [Radius environments]({{< ref "/guides/deploy-apps/environments/overview" >}}). + +Diagram showing Radius resources being mapped to Kubernetes objects + +## Supported Kubernetes versions Kubernetes version `1.23.8` or higher is recommended to run Radius. -## Supported clusters +## Resource mapping + +Radius resources, when deployed to a Kubernetes environment, are mapped to one or more Kubernetes objects. The following table describes the mapping between Radius resources and Kubernetes objects: + +| Radius resource | Kubernetes object | +|----------------------------------|-------------------| +| [`Applications.Core/containers`]({{< ref container-schema >}}) | `apps/Deployment@v1` | +| [`Applications.Core/httpRoutes`]({{< ref httproute >}}) | `core/Service@v1` | +| [`Applications.Core/gateways`]({{< ref gateway >}}) | `projectcontour.io/HTTPProxy@v1` | +| [`Applications.Dapr/pubSubBrokers`]({{< ref dapr-pubsub >}}) | `dapr.io/Component@v1alpha1` | +| [`Applications.Dapr/secretStores`]({{< ref dapr-secretstore >}}) | `dapr.io/Component@v1alpha1` | +| [`Applications.Dapr/stateStores`]({{< ref dapr-statestore >}}) | `dapr.io/Component@v1alpha1` | + +### Namespace mapping + +Application-scoped resources are by default generated in a new Kubernetes namespace with the name format `'-'`. This prevents multiple applications with resources of the same name from conflicting with each other. + +For example, let's take an application named `'myapp'` with a container named `'frontend'`. This application is deployed into an environment configured with with the `'default'` namespace. A Kubernetes Deployment named `'frontend'` is now deployed into the namespace `'default-myapp'`. + +If you wish to override the default behavior and specify your own namespace for application resources to be generated into, you can leverage the [`kubernetesNamespace` application extension]({{< ref "application-schema#kubernetesNamespace" >}}). All application-scoped resources will now be deployed into this namespace instead. + +### Resource naming + +Resources that are generated in Kubernetes use the same name as the resource in Radius. For example, a Radius container named 'frontend' will map to a Kubernetes Deployment named `'frontend'`. This makes it easy to conceptually map between Radius and Kubernetes resources. + +For multiple Radius resources that map to a single Kubernetes resource (_e.g. daprPubSubBrokers, daprSecretStores, and daprStateStores all map to a dapr.io/Component_) and there are collisions in naming, Radius has conflict logic to allow the first resource to be deployed but will throw a warning for subsequent resource deployments that have the same name. This prevents Radius resources from unintentionally overwriting the same generated resource. + +## Kubernetes metadata + +Radius environments, applications, and resources can be annotated/labeled with Kubernetes metadata. Refer to the Kubernetes metadata page for more information: + +{{< button text="Kubernetes metadata" page="kubernetes-metadata" >}} + +## Supported Kubernetes clusters The following clusters have been tested and validated to ensure they support all of the features of Radius: diff --git a/docs/content/guides/operations/kubernetes/kubernetes-mapping/kubernetes-mapping.png b/docs/content/guides/operations/kubernetes/overview/kubernetes-mapping.png similarity index 100% rename from docs/content/guides/operations/kubernetes/kubernetes-mapping/kubernetes-mapping.png rename to docs/content/guides/operations/kubernetes/overview/kubernetes-mapping.png diff --git a/docs/content/guides/operations/providers/howto-aws-provider/index.md b/docs/content/guides/operations/providers/howto-aws-provider/index.md index bae7b513c..f273d3bf3 100644 --- a/docs/content/guides/operations/providers/howto-aws-provider/index.md +++ b/docs/content/guides/operations/providers/howto-aws-provider/index.md @@ -14,7 +14,7 @@ The AWS provider allows you to deploy and connect to AWS resources from a Radius ## Prerequisites -- [EKS cluster]({{< ref "guides/operations/kubernetes/supported-clusters" >}}) +- [EKS cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}) - [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account) and an [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) diff --git a/docs/content/reference/resource-schema/core-schema/application-schema/_index.md b/docs/content/reference/resource-schema/core-schema/application-schema/_index.md index af1bcd2fe..d6855ed02 100644 --- a/docs/content/reference/resource-schema/core-schema/application-schema/_index.md +++ b/docs/content/reference/resource-schema/core-schema/application-schema/_index.md @@ -31,7 +31,7 @@ Extensions allow you to customize how resources are generated or customized as p ##### kubernetesNamespace -The Kubernetes namespace extension allows you to customize how all of the resources within your application generate Kubernetes resources. See the [Kubernetes mapping guide]({{< ref kubernetes-mapping >}}) for more information on namespace mapping behavior. +The Kubernetes namespace extension allows you to customize how all of the resources within your application generate Kubernetes resources. See the [Kubernetes mapping guide]({{< ref "/guides/operations/kubernetes/overview#resource-mapping" >}}) for more information on namespace mapping behavior. | Key | Required | Description | Example | |------|:--------:|-------------|---------| diff --git a/docs/content/tutorials/tutorial-dapr/index.md b/docs/content/tutorials/tutorial-dapr/index.md index b23ba3dc0..503e69821 100644 --- a/docs/content/tutorials/tutorial-dapr/index.md +++ b/docs/content/tutorials/tutorial-dapr/index.md @@ -18,7 +18,7 @@ For more details on the app and access to the source code, visit the `tutorials/ ## Prerequisites -- [Kubernetes cluster]({{< ref "supported-clusters" >}}) +- [Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}}) - [Radius CLI]({{< ref "getting-started" >}}) - [Radius environment]({{< ref "/guides/deploy-apps/environments/overview" >}}) - [Dapr installed on your Kubernetes cluster](https://docs.dapr.io/operations/hosting/kubernetes/kubernetes-deploy/)