Add specification and implementation plan for external Kubernetes deployments

[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

[Reshrahim]

Shouldn't this config be part of AWS provider now that we are deploying to an external cluster in AWS? It feels fragmented to configure the eks cluster with Kubernetes provider and AWS account/ region with AWS provider.

[nithyatsu]

Do we worry only about the recipes? UCP directly talks to AWS today using cloud control APIs too. Would we want this enhanced too or do we plan to deprecate this ability similar to applications RP?

[nithyatsu]

With this ability, would we worry about a radius instance local to eks simultaneously managing the same application in additional to radius on kind/k3d or is that out of scope?

[willdavsmith]

I think we do auto-create namespaces by default, but we might want to change this behavior

[zachcasper]

I see no evidence of creating namespaces in the Containers recipe. https://github.com/radius-project/resource-types-contrib/blob/main/Compute/containers/recipes/kubernetes/terraform/main.tf

[willdavsmith]

nit: I don't really like current as this keyword. maybe local or something else is better

[zachcasper]

All are bad. Kubernetes has no concept of a name or a symbol that references a cluster outside of the kube context. The closest to a reference is when connecting to the API server from within the cluster, the URL is https://kubernetes.default.svc.cluster.local. I worry about local referring to the user's local workstation. Possibly cluster.local is better.

[willtsai]

Would like to discuss the naming of the target property and whether current and external are good choices.

[sk593]

Why aren't we supporting external deployments across regions and resource groups? Are we scoping Azure resources to the resource group and AWS resources to the region (both denoted in the providers block) because of the scope of the credentials?

[zachcasper]

Is this a question relative to deploying to external Kubernetes clusters or a question in general about environments? Environments today are scoped to an AWS {accountId, region} or an Azure {subscription, resource group}.

[kachawla]

local sounds more intuitive than current to me

[DariuszPorowski]

+1

[kachawla]

What do we mean by recipe engine here?

[zachcasper]

Bicep or Terraform.

[kachawla]

Can you make that explicit here? Recipe engine is agnostic to how the recipe is getting deployed.

[brooke-hamilton]

🚀

[brooke-hamilton]

It might be helpful to diagram where the credentials are set and where they flow. For example, there is going to be an existing credential configured on the client machine in the local kubectl context, but there will also be credentials configured in the cluster. Those creds are for the current cluster and cloud environment.

This spec is adding new credentials for an external cloud environment and cluster, using "existing registered AWS credentials along with the AWS region", but where do those come from and how are they set?

[brooke-hamilton]

Thinking about this more, we really need an overall architecture diagram that depicts where credentials exist in the current version of Radius, plus the planed delta in this PR.

[brooke-hamilton]

I assume that there is no restriction on AWS clusters deploying to Azure clusters and vice versa, but I want to ask the question in case this is an invalid assumption.

We should add this scenario to the acceptance criteria.

[kachawla]

Only the AWS credentials are used for kubeconfig acquisition; the Azure provider is used for any Azure-targeted resources in the recipe, not for Kubernetes access.

Could you say more on the user scenario for this one?

[willtsai]

Would like to discuss this:

      kubernetes: {
        namespace: 'my-app'
        target: 'external'
        clusterType: 'eks'
        clusterName: 'my-eks-cluster'
      }

and whether something like this would be better for the user:

      kubernetes: {
        namespace: 'my-app'
        target: {
          type: 'external'
          clusterType: 'eks'
          clusterName: 'my-eks-cluster'
        }
      }

[kachawla]

Is clusterType required if target is current? If not, then could we merge the two properties? For example, target: current would mean local cluster, target: eks would be external eks

[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>'
      }
    }
  }
}