Overview: Radius on Kubernetes platform

Learn how Radius can run on Kubernetes

Radius offers a Kubernetes-based platform for hosting the Radius control plane and Radius Environments.

Supported Kubernetes versions

Kubernetes version 1.23.8 or higher is recommended to run Radius.

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/configuration Kubernetes object
Applications.Core/containers apps/Deployment@v1

core/Service@v1 (if ports defined)
Applications.Core/containers connections core/Secret@v1
Mounted to the container as environment variables. Refer to the connections guide to learn more.
Applications.Core/gateways projectcontour.io/HTTPProxy@v1
Applications.Dapr/pubSubBrokers dapr.io/Component@v1alpha1
Applications.Dapr/secretStores dapr.io/Component@v1alpha1
Applications.Dapr/stateStores dapr.io/Component@v1alpha1

Namespace mapping

Application-scoped resources are by default generated in a new Kubernetes namespace with the name format '<envNamespace>-<appname>'. 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 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. 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:

Kubernetes metadata

Supported Kubernetes clusters

The following clusters have been tested and validated to ensure they support all of the features of Radius:


Azure Kubernetes Service (AKS) clusters are the easiest way to get up and running quickly with a Radius Environment. To learn how to setup a cluster visit the Azure docs.

Note that AKS-managed AAD is not supported currently.

To create a new AKS cluster and retrieve its kubecontext, you can run the following commands:

az aks create --subscription mySubscription --resource-group myResourceGroup --name myAKSCluster --node-count 1
az aks get-credentials --subscription mySubscription --resource-group myResourceGroup --name myAKSCluster

Once deployed and your kubectl context has been set as your default, you can run the following to create a Radius Environment and install the control plane:

rad init

k3d is a lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in Docker.

First, ensure that memory resource is 8GB or more in Resource setting of Preferences if you’re using Docker Desktop. Also make sure you’ve enabled Rosetta if you’re running on an Apple M1 chip:

softwareupdate --install-rosetta --agree-to-license

Use the following command to create a new cluster. and install the Radius control plane, along with a new environment:

  • The first parameter adds a port mapping which routes traffic from the local machine into the cluster.
  • The second parameter disables traefik pods because Radius provides an ingress controller.
  • The third parameter disables the k3d internal load balancer.

The rad install command is configured to route localhost traffic on port 8081 into the cluster.

k3d cluster create -p "8081:80@loadbalancer" --k3s-arg "--disable=traefik@server:*" --k3s-arg "--disable=servicelb@server:*"

Next, install the Radius control plane, along with a new environment. The rad install command below adds a parameter to override the default public endpoint so that Radius knows that traffic from the local machine will enter the pod on port 8081:

rad install kubernetes --set rp.publicEndpointOverride=localhost:8081
rad init

Kind is a tool for running local Kubernetes clusters inside Docker containers. Use the following setup to create a new cluster and install the Radius control plane, along with a new environment:

First, ensure that memory resource is 8GB or more in Resource setting of Preferences if you’re using Docker Desktop. Also make sure you’ve enabled Rosetta if you’re running on an Apple M1 chip:

softwareupdate --install-rosetta --agree-to-license

Second, copy the text below into a new file kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
  extraPortMappings:
  - containerPort: 80
    hostPort: 8080
    listenAddress: "0.0.0.0"  
  - containerPort: 443
    hostPort: 8443
    listenAddress: "0.0.0.0"

Then, create a kind cluster with this config and initialize your Radius Environment:

# Create the kind cluster
kind create cluster --config kind-config.yaml

# Verify that the nodes are ready
# (You should see 2 nodes listed with status Ready)
kubectl get nodes

# Install Radius
rad install kubernetes --set rp.publicEndpointOverride=localhost:8080
rad init

Amazon Elastic Kubernetes Service (Amazon EKS) is a managed service that you can use to run Kubernetes on AWS. Learn how to set up an EKS cluster on the AWS docs.

eksctl create cluster --name my-cluster --region region-code

Once deployed and your kubectl context has been set as your default, you can run the following to create a Radius Environment and install the control plane:

rad init

Configure container registry access

If you choose a private container registry you will need to take steps to configure your Kubernetes cluster to allow access. Follow the instructions provided by your cloud provider.


Visit the Kubernetes docs to learn how to configure your cluster to access a private registry, such as Docker Hub.


Visit the Azure docsto learn how to configure access to an ACR registry.

az aks update --name myAKSCluster --resource-group myResourceGroup --subscription mySubscription --attach-acr <acr-name>