[zachcasper]

This pull request introduces the foundational design documents and implementation plan for supporting deployment to external Kubernetes clusters (EKS and AKS) in Radius. It defines the new data model, validation rules, API contract, and outlines the required code changes and project structure. The documentation covers how users can configure environments and credentials to target external clusters, and provides a quickstart guide for both EKS and AKS scenarios.

The most important changes are:

Data Model & API Changes

• Extended the ProvidersKubernetes model with new fields: target, clusterType, and clusterName, including detailed validation rules and cross-entity dependencies.
• Updated the API contract for Radius.Core/environments to support these new fields, with examples and validation error responses for incorrect configurations.

Implementation Plan & Project Structure

• Added an implementation plan detailing technical context, constitution checks, affected code areas, and the introduction of a new pkg/kubernetes/kubeconfig/ package for cloud-specific kubeconfig acquisition.

User-Facing Documentation

• Provided a quickstart guide with step-by-step instructions for deploying to external EKS and AKS clusters, covering credential registration, environment creation, and verification.
• Added a specification quality checklist to ensure requirements are complete, clear, and ready for planning.# Description

Type of change

• This pull request is a design-note
  Fixes: Manage applications in multiple environments on separate Kubernetes clusters #6934

Contributor checklist

Please verify that the PR meets the following requirements, where applicable:

• An overview of proposed schema changes is included in a linked GitHub issue.
  • Yes
  • Not applicable
• A design document PR is created in the design-notes repository, if new APIs are being introduced.
  • Yes
  • Not applicable
• The design document has been reviewed and approved by Radius maintainers/approvers.
  • Yes
  • Not applicable
• A PR for the samples repository is created, if existing samples are affected by the changes in this PR.
  • Yes
  • Not applicable
• A PR for the documentation repository is created, if the changes in this PR affect the documentation or any user facing updates are made.
  • Yes
  • Not applicable
• A PR for the recipes repository is created, if existing recipes are affected by the changes in this PR.
  • Yes
  • Not applicable

[Copilot]

Pull request overview

This PR adds a set of design/plan documents for enabling Radius recipe execution against external Kubernetes clusters (EKS and AKS), including the proposed environment schema/API additions (target, clusterType, clusterName) and a phased implementation task plan.

Changes:

• Added feature spec covering user stories, requirements, and validation rules for external cluster targeting.
• Added implementation plan + research notes describing the intended EKS/AKS kubeconfig acquisition approach and impacted code areas.
• Added API contract examples, a quickstart, and a task breakdown/checklist for executing the work.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
specs/003-external-k8s-deploy/spec.md	Defines user stories, requirements, validation rules, and scope for external EKS/AKS targeting
specs/003-external-k8s-deploy/plan.md	Implementation plan, impacted components, and project structure for the feature
specs/003-external-k8s-deploy/research.md	Technical research on EKS token generation, AKS credential flow, Terraform/Bicep integration
specs/003-external-k8s-deploy/data-model.md	Proposed data model changes + validation rules + flow diagram
specs/003-external-k8s-deploy/contracts/environments-api.md	API contract changes and example payloads/error responses
specs/003-external-k8s-deploy/quickstart.md	Step-by-step usage guide for EKS/AKS scenarios
specs/003-external-k8s-deploy/tasks.md	Phased work plan with explicit file-level tasks
specs/003-external-k8s-deploy/checklists/requirements.md	Spec quality checklist for readiness

[brooke-hamilton]

🚀

[zachcasper]

In today's review, the general consensus was:

1. We should not mix cloud provider details and Kubernetes cluster details; e.g. if clusterName is an AWS/Azure name then it should be in the AWS/Azure block.
2. current is ambiguous and local is preferred.

Given this, one possibility is to model the environment as:

resource env 'Radius.Core/environments@2025-08-01-preview' = {
  name: 'my-radius-env'
  properties: {
    providers: {
      aws: {
        accountId: '<AWS_ACCOUNT_ID>'
        region: '<AWS_REGION>'
        eksClusterName: '<EKS_CLUSTER_NAME>'
      }
      // Can only specify aws or azure block
      azure: {
        subscriptionId: '<SUBSCRIPTION_ID>'
        resourceGroupName: '<RESOURCE_GROUP_NAME>'
        aksClusterName: '<AKS_CLUSTER_NAME>'
      }
      kubernetes: {
        namespace: '<KUBERNETES_NAMESPACE>'
      }
    }
  }
}

In the future, this can be generalized to support generic Kubernetes cluster with the addition of a Kubernetes credential resource such as:

resource env 'Radius.Core/environments@2025-08-01-preview' = {
  name: 'my-radius-env'
  properties: {
    providers: {
      kubernetes: {
        apiServerUrl: 'https://kubernetes.default.svc.cluster.local'
        namespace: '<KUBERNETES_NAMESPACE>'
        secretName: '<SECRET_NAME>'
      }
    }
  }
}

[sylvainsf]

Looks great!

[sylvainsf]

LGTM