Default Recipe Packs for K8s

[nicolejms]

radius should support radius.core environments and recipe packs by default.

[willtsai]

Here is a summary of the desired behavior:

Today, when an Environment is created using rad environment create my-env, a Radius Environment is created without any Recipes registered to it. Despite not having any Recipes configured, the user is still able to deploy applications and container resources to this environment since there is imperative code in Radius core that can directly provision Kubernetes resources (containers, volumes, secrets) without requiring pre-defined Recipes. We want to preserve this "native" Kubernetes user experience in the new Radius compute extensibility model (i.e. with the new Radius.Core/environments).

To achieve this, Radius will make the Kubernetes Recipes available for all the core resource types (containers, routes, secrets, persistentVolumes) in every Environment, regardless of whether the user registered the Recipes for these types.

Case 1: Environment is created without any Recipes registered for the respective core resource types (e.g. Radius.Core/containers, Radius.Core/routes, Radius.Security/Secrets, Radius.Core/persistentVolumes)

1. Radius will make the Kubernetes Recipes available for all the core resource types.
2. Users will then be able to deploy applications and Kubernetes containers to this Environment even though they did not explicitly add any Recipe Packs, thus preserving the existing user experience.

Case 2: Environment is created and user registers their own Recipes for all the respective core resource types (e.g. Radius.Core/containers, Radius.Core/routes, Radius.Security/Secrets, Radius.Core/persistentVolumes)

1. Radius will use the user-registered Recipes for all the core resource types.
2. Users will be able to deploy applications and Kubernetes containers to this Environment using their own Recipes.

Case 3: Environment is created and user registers their own Recipes for some, but not all, of the respective core resource types (e.g. custom recipes for Radius.Core/routes and Radius.Security/Secrets but not Radius.Core/containers and Radius.Core/persistentVolumes)

1. Radius will use the user-registered Recipes for the core resource types that the user has registered Recipes for.
2. For the core resource types that the user did not register any Recipes for, Radius will make the Kubernetes Recipes available for those types.
3. Users will be able to deploy applications and Kubernetes containers to this Environment using a combination of their own Recipes and the default Kubernetes Recipes provided by Radius.

Note that I'm not prescribing the exact implementation details here, just the desired behavior. If registering default Kubernetes Recipe Packs is the chosen implementation approach, much care needs to be given to how conflicts with user-registered Recipe Packs are resolved. Specifically, refer to the behavior described in User Story 1 of the feature spec, referenced below. This conflict resolution behavior needs to be taken into account when implementing the solution - default Recipes should be overridden in the event of conflict with user-registered Recipes and not fail the environment deployment.

If Recipes are duplicated across the Recipe Packs added to an Environment, Radius will fail the environment deployment with a clear error message indicating the conflicting Recipes. This ensures that recipe conflicts are detected early and prevents unpredictable behavior. The duplication is detected at the Resource Type level, e.g. if both computeRecipePack and dataRecipePack contain a Recipe for the same Resource Type, the deployment will fail. Note that because we won't allow named Recipes in Recipe Packs, the conflict will only occur if the same Resource Type is specified in multiple Recipe Packs.

The various commands like rad recipe list and rad environment show should accurately reflect the Recipes that are effectively available in the Environment, including both user-registered Recipes and the default Kubernetes Recipes when applicable. Again, refer to User Story 1 for more details on the CLI behavior.

There is no preference for either Bicep or Terraform Recipes to use in the default Kubernetes Recipe Packs. This will be an implementation decision for the engineer, who will be expected to have a solution for how to handle the Recipe location (e.g. published to a registry for Bicep or referenced from a repo for Terraform, etc.)

[radius-triage-bot]

👍 We've reviewed this issue and have agreed to add it to our backlog. Please subscribe to this issue for notifications, we'll provide updates when we pick it up.

We also welcome community contributions! If you would like to pick this item up sooner and submit a pull request, please visit our contribution guidelines and assign this to yourself by commenting "/assign" on this issue.

For more information on our triage process please visit our triage overview

[willtsai]

Some additional details:

Upon creation of an Environment (either through rad init or rad env create), Radius will check to see if there is a default Recipe Pack containing Recipes for the core resource types:

1. If there is not a default Recipe Pack containing Recipes for the core resource types available in the Resource Group already, Radius will fetch the default Recipe Pack from the resource-types-contrib source and add it to the Resource Group, and then register that default Recipe Pack to the created Environment.
2. If there is a default Recipe Pack available in the Resource Group containing Recipes for the core resource types, Radius will register that default Recipe Pack to the created Environment.

Afterwards, the user might choose to customize the Recipes in the default Recipe Pack, e.g. swapping out the default Routes Recipe for a custom Routes Recipe that better suits their needs:

1. User refers to the documentation or resource-types-contrib repo to get the .bicep file for the default Kubernetes Recipe Pack.
2. They modify the .bicep file to replace the default Routes Recipe with their custom Routes Recipe.
3. They then run rad deploy modified-default-recipe-pack.bicep to deploy the modified default Recipe Pack to their Resource Group.
4. All Environments that reference the default Recipe Pack will now be using the modified version with the custom Routes Recipe instead of the original default Routes Recipe.

After customizing the default Recipe Pack, users may create new Environments. These new Environments will automatically use the modified default Recipe Pack with the custom Routes Recipe, since that modified default Recipe Pack is now the one available in the Resource Group.

1. User creates a new Environment (e.g. rad env create my-new-env).
2. Radius checks to see if there is a default Recipe Pack containing Recipes for the core resource types available in the Resource Group. Since the user has already deployed a modified default Recipe Pack, Radius finds that default Recipe Pack in the Resource Group.
3. Radius registers the existing default Recipe Pack (which now contains the custom Routes Recipe) to the newly created Environment.
4. The new Environment is now using the modified default Recipe Pack with the custom Routes Recipe.

If, for a given Environment, the user wants to use a non-default Recipe Pack for the core resource types instead of the default Kubernetes Recipe Pack (e.g. they want to register an ACI Recipe Pack for an Azure Container Instances Environment), they can do so by deregistering the default Recipe Pack from the Environment and registering their preferred non-default Recipe Pack to the Environment:

1. User deploys the non-default Recipe Pack (e.g. azure-aci-pack) to the Resource Group if it is not already deployed:

   rad deploy azure-aci-pack.bicep
   

2. User creates a new Environment and specifies that they want to use an ACI Recipe Pack for the core resource types instead of the default Kubernetes Recipe Pack:

   rad environment create my-aci-env \
   --provider azure.subscriptionId='mySubscriptionId' \
   --provider azure.resourceGroupName='my-resource-group' \
   --recipe-pack azure-aci-pack
   

3. Radius creates the Environment and detects that the supplied azure-aci-pack Recipe Pack contains Recipes for the core resource types, so Radius skips registering the default Kubernetes Recipe Pack to the Environment since the user has explicitly indicated that they want to use the azure-aci-pack Recipe Pack for the Environment.

[kachawla]

@willtsai a few questions -

1. How's a default recipe pack identified? Any specific flag or reserved name?

2. User refers to the documentation or resource-types-contrib repo to get the .bicep file for the default Kubernetes Recipe Pack.

   We don't have this file today. Where in the resource-types-contrib repo were you thinking of adding it?

3. They then run rad deploy modified-default-recipe-pack.bicep to deploy the modified default Recipe Pack to their Resource Group.

   What is the benefit of allowing this override?

4. All Environments that reference the default Recipe Pack will now be using the modified version with the custom Routes Recipe instead of the original default Routes Recipe.

   How does an update like this impact applications deployed using the recipe pack before it was edited?

5. they can do so by deregistering the default Recipe Pack from the Environment and registering their preferred non-default Recipe Pack to the Environment

   Could you point me to the user experience/relevant command that enables deregisteration of a recipe pack?

6. What does registration of a recipe pack mean?

7. How many recipe packs can one environment reference?

[zachcasper]

Can we simplify this even further?

• rad init and rad install kubernetes both create a default-kubernetes-bicep Recipe Pack in the default resource group.
• The default value for the recipePack property on a new environment is default/default-kubernetes-bicep unless otherwise specified
• Users can modify, or even delete the Recipe Pack using the standard rad deploy and rad resource delete commands without restriction
• If the environment references a deleted Recipe Pack or a Recipe Pack without a recipe for a specific Resource Type, they will get a helpful error message

I think this ends up being the same as what Will has written with the addition of the resource group detail and the creation on rad install.

[willtsai]

@kachawla - a few answers :)

1. How's a default recipe pack identified? Any specific flag or reserved name?

No strong opinions here. default, default-k8s, or something to that effect if going the reserved name route. The other option would be for Radius to keep track of whether there are Recipe Pack(s) in the Resource Group containing Recipes for containers, persistentVolumes, routes, secrets.

2. User refers to the documentation or resource-types-contrib repo to get the .bicep file for the default Kubernetes Recipe Pack.
   We don't have this file today. Where in the resource-types-contrib repo were you thinking of adding it?

No strong opinion here either, but github.com/radius-project/resource-types-contrib/recipe-packs should be fine.

3. They then run rad deploy modified-default-recipe-pack.bicep to deploy the modified default Recipe Pack to their Resource Group.
   What is the benefit of allowing this override?

Platform teams would want to customize the default behavior for their Radius installation across all their users. For example, they might want to replace just the Routes Recipes in the default Recipe Pack and would like this behavior to propagate across all current and future environments that make use of the default Recipe Pack.

4. All Environments that reference the default Recipe Pack will now be using the modified version with the custom Routes Recipe instead of the original default Routes Recipe.
   How does an update like this impact applications deployed using the recipe pack before it was edited?

The next time the application is deployed, it will deploy using the new Recipes in the Pack.

5. they can do so by deregistering the default Recipe Pack from the Environment and registering their preferred non-default Recipe Pack to the Environment
   Could you point me to the user experience/relevant command that enables deregisteration of a recipe pack?

Remove reference of the default Recipe Pack in the env.bicep file, then rad deploy env.bicep

6. What does registration of a recipe pack mean?

Run rad deploy recipe-pack.bicep. Reference the Recipe Pack in the env.bicep file, then rad deploy env.bicep (or alternatively just runnning rad environment update my-env --recipe-packs recipe-pack)

8. How many recipe packs can one environment reference?

Many, it's an array, see https://github.com/radius-project/design-notes/blob/main/features/2025-06-compute-extensibility-feature-spec.md#user-story-1-as-a-platform-engineer-i-want-to-create-a-recipe-pack-that-bundles-multiple-recipes-for-core-resource-types-so-that-i-can-easily-register-and-manage-them-in-a-radius-environment

[nithyatsu]

Adding examples for the above design approach

Approach 1

we want to edit the "default" recipepack to accomodate conflicts/ missing types everytime an environment is created or updated

case 1

1. rad init # creates default pack, creates default env, links default pack to default env
2. rad deploy app.bicep will work, provided app.bicep has just the core type resources.

case 2

Ops persona is responsible for configuring radius for 2 applications - one uses kubernetes compute and the other uses aci (or the two teams prefer different routes recipe).

1. rad install kubernetes

2. rad env create kube-env #set up env for the kubernetes app to run.

nithya@MacBook-Pro prototype % rad env show kube-env -o json --preview # redacted output showing only relevant fields.
{
  "id": "/planes/radius/local/resourcegroups/default/providers/Radius.Core/environments/default",
  <redacted>
  "properties": {
    "providers": {
     
    "recipePacks": [
      "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/default",
    ]
  },


nithya@MacBook-Pro prototype % rad recipe-pack show default -g default #ignore recipe path correctness please
RECIPE PACK      GROUP
default                 fixed

RECIPES:
Radius.Compute/containers
   Kind: bicep
   Location: ghcr.io/nithyatsu/recipes/kubernetes-container:latest

Radius.Compute/routes
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/routes:latest

Radius.Compute/routes
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/persistent-volume:latest

Radius.Compute/routes
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/secrets:latest
  
3. rad env create aci-env  # setup env for the aci app to run.

At this point aci-env looks identical to kube-env, with default kubernetes recipe packs. "default" recipe pack looks the same as in step 2. Continue with remaining steps to make the env work for aci apps.

4. rad deploy aci-pack.bicep # has a recipe for aci and a few  other non-core types
 
5. rad env update --recipe-pack-id aci-pack-id 

At this point Radius looks at aci-pack, sees there is a recipe for Radius.Core/containers type and prioritizes it. 
- It therefore updates the default recipe pack (shared between the apps) to remove the containers recipe.  
-Then it updates the env to point to both user's aci-pack and default pack so that all resource types are covered

6.  rad env show aci-env -o json --preview # redacted output showing only relevant fields.
{
  "id": "/planes/radius/local/resourcegroups/default/providers/Radius.Core/environments/default",
  <redacted>
  "properties": {
    "providers": {
     
    "recipePacks": [
      "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/default",
 "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/aci-pack",
    ]
  },

nithya@MacBook-Pro prototype % rad recipe-pack show default -g default # no containers
RECIPE PACK      GROUP
default                 fixed

RECIPES:

Radius.Compute/routes
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/routes:latest

Radius.Compute/persistant-volumes
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/persistent-volume:latest

Radius.Compute/secrets
   Kind: bicep
   Location: ghcr.io/radius-project/recipes/local-dev/secrets:latest

• we are choosing to rely on operator to NOT do this. Instead what steps would he take?

rad env update --recipepacks <pass in the id of recipe-pack that conatins all core types, with aci recipe defined for container type>

Then, since Radius detects all core types are covered by user and therefore it wont modify the default recipepack.

pros : no singleton recipe pack confusion
cons:
If the user does not read the doc, the breaking scenario we discussed is possible.
It feels wrong to update a shared resource to comply with requirements for each resource that uses it.

approach 2

Use singleton recipe-packs. Working PR at
#11212

In this case, for each of the core types, we make a recipe pack containing just that core type. So we have

nithya@MacBook-Pro prototype % rad recipe-pack list
RECIPE PACK GROUP
containers default
persistentvolumes default
routes default
secrets default

Then,

1. rad env create kube-env

2. rad env show kube-env -o json
   nithya@MacBook-Pro prototype % rad env show default -o json --preview
   {
   "id": "/planes/radius/local/resourcegroups/default/providers/Radius.Core/environments/default",
   "location": "global",
   "name": "default",
   "properties": {
   "providers": {
   "kubernetes": {
   "namespace": "default"
   }
   },
   "provisioningState": "Succeeded",
   "recipePacks": [
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/containers",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/persistentvolumes",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/routes",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/secrets"
   ]
   },

3. rad env create aci-env

4. rad env update --recipe-pack-id aci-pack-id
   nithya@MacBook-Pro prototype % rad env show default -o json --preview
   {
   "id": "/planes/radius/local/resourcegroups/default/providers/Radius.Core/environments/default",
   "location": "global",
   "name": "default",
   "properties": {
   "providers": {
   "kubernetes": {
   "namespace": "default"
   }
   },
   "provisioningState": "Succeeded",
   "recipePacks": [
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/aci-pack",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/persistentvolumes",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/routes",
   "/planes/radius/local/resourceGroups/default/providers/Radius.Core/recipePacks/secrets"
   ]
   },

• pro: default recipe packs stay the same. The environments use/ not use what defaults they need and can bring in their own for selected core types. Feels clean.

• con here is that recipe-pack is typically used to bundle multiple recipes, and here we have not done that. The users might find it confusing that there are 4 recipepacks one per resource when they create an environment. The original deisgn decisions/ implementation for recipe-pack does not disallow the scenario of recipe-pack containing single recipe though.

approach 3

We create a default recipe pack when we create an environment, providing the out of box kubernetes deployment we have today. But if user chooses to make recipe packs for core types, and run rad env update to link to this pack, then we remove the default recipe-pack from the environment. We could provide a doc link on how they can add the missing core types into their pack, pointing to our recipes.

pros: This feels cleanest, considering the scope of the feature.
cons: user has to manually add the recipe defintions into the pack and deploy it, if it had some core types missing, based on our docs link.