Workflow

Follow the steps below to import an existing AKS cluster from the Azure Portal and manage it through Rafay's centralized platform. This guided workflow uses predefined system templates to simplify the import and takeover process.

Sequence Diagram

AKS Cluster Import: Setup Process

Rafay
Azure User
Create AKS cluster

1. Launch "aks-import-cluster" template
2. Enter AKS and Azure details
3. Discover existing AKS cluster
4. Create environment
5. Show status: In Progress → Evaluating

Deploy and Manage the Imported AKS Cluster

AKS Cluster
Rafay User
Select generated environment
Click "Edit" to review config
Click "Deploy" (system-aks-takeover)
Finalize environment setup
Send status
Status = "Success"
Open Cluster Dashboard
Display imported AKS cluster with "Template" banner

AKS Cluster Import and Takeover Templates

When bringing an existing AKS (Azure Kubernetes Service) cluster under Rafay's centralized management, two system templates are used as part of the workflow:

1. system-aks-cluster-import (User-facing Template)

• The user manually launches this template from the Environment Manager page in the Rafay Console.
• It prompts the user to provide:
  • AKS cluster name
  • Azure Service Principal (SPN) credentials
  • Azure subscription and tenant details
  • Agent and environment configuration
• The template uses this information to:
• Discover the existing AKS cluster on Azure
• Retrieve configuration and metadata
• Create a new environment on the Rafay platform

This phase handles the discovery and initial setup of the cluster and is user-driven.

2. system-aks-takeover (Reference Template)

• This template is automatically triggered by the system and not launched manually by the user.
• Once the aks-import-cluster template creates an environment, this template:
  • Finalizes the cluster configuration
  • Registers the AKS cluster fully under Rafay's management

🎯 This step completes the takeover process and enables full lifecycle management of the imported cluster.

Summary Table

End-to-End AKS Import and Takeover Process

Step 1: Prerequisite – Existing AKS Cluster

If you already have AKS clusters running in your Azure subscription and you want Rafay to manage them—and eventually use them in a self-service manner—follow the steps below starting from Step 2.

Step 2: Create an Environment Template

• Log in to the Rafay Console and navigate to Environment from the left menu.
• Select the aks-cluster-import template and click Launch.

Step 3: Configure Cluster Parameters

Important Note About Agent Configuration

If the customer's cluster is using a public cluster endpoint (i.e., the control plane is accessible over the internet), the agent does not need to be in the same network as the cluster, as long as it can reach the Azure public endpoint.

If the customer's cluster is using a private cluster endpoint, the agent must be deployed on a virtual machine that resides within the same network (VNet) as the AKS cluster. This ensures that the agent can connect to the private control plane endpoint and perform the takeover.

Credential Requirements Reference

For detailed steps on setting up the required credentials and permissions for AKS import and takeover, refer to the following documentation:

• Azure Service Principal Setup
• Restricted Roles and Identities Required for Creating an AKS Cluster

Ensure that the Service Principal and roles are configured as described to enable a successful import and management of your AKS cluster.

The template configuration is divided into three main sections:

3.1 Cluster Details Section

This section captures information about the existing AKS cluster:

• Cluster Name: Name of the existing AKS cluster you want to import
• Project Name: The Rafay project where the cluster will be imported
• Resource Group: Azure resource group containing the AKS cluster

3.2 General Section

This section defines the reference template configuration:

• Environment Template Name: Name for your environment template
• Environment Version: Select the version of the environment template
• Agent: Choose the agent that will manage the cluster import process
• Agent Name: Enter the name of the selected agent

3.3 Others Section (Azure & Rafay Credentials)

This section requires authentication credentials (all sensitive information is encrypted):

• Azure Tenant ID: Your Azure AD directory (tenant) ID
• Azure Client ID: Service Principal (SPN) client ID
• Azure Client Secret: Service Principal secret key
• Azure Subscription ID: Your Azure subscription ID
• Controller Endpoint: Rafay Controller endpoint (e.g., console.rafay.dev)
• API Key: Your Rafay user API key for authentication

Credential Requirements Reference

For detailed steps on setting up the required credentials and permissions for AKS import and takeover, refer to the following documentation:

Ensure that the Service Principal and roles are configured as described to enable a successful import and management of your AKS cluster.

After providing all required information across these sections, click Save & Deploy to:

1. Start the cluster import process
2. Create a new environment using the system-aks-takeover template
3. Begin the conversion to a managed cluster in Rafay

The process will complete with the creation of a new cluster object under Infrastructure > Clusters in your Rafay Console.

• Click Save & Deploy.

• The initial status will be Pending, which will then change to In Progress. View the activities that occur while the deployment is in progress as shown below. The deployment may take approximately 5 minutes to complete.

• Once the deployment is successful, a new environment system-aks-takeover is automatically created using the AKS cluster name provided during previous environment creation with the aks-import-cluster template. In this case, the generated environment will be named aks-cluster1, and the status displayed will be Evaluating Status.

Step 4: Review the Configuration

• Select the newly generated environment (created using the system-aks-takeover template) and click the Edit icon.
• Review the configuration parameters of the imported cluster.

Step 5: Deploy the system-aks-takeover Template

• Once the review is complete and all parameters are up to date, click Deploy to initiate the deployment of the newly generated system-aks-takeover environment and complete the cluster takeover.

Deploying this environment will:

• Finalize the environment setup for the imported AKS cluster.
• Register the cluster under full lifecycle management within the Rafay platform.
• Transition the environment status from Evaluating Status to Success, indicating successful onboarding.

Once deployed, the AKS cluster will be fully managed through Rafay's centralized interface, enabling features such as monitoring, governance, and blueprint application.

Step 6: Verify Imported Cluster

Once the cluster takeover is complete, navigate to the Cluster Dashboard to view the imported AKS cluster. A Template banner will be displayed on the card, indicating that the cluster was imported using a template.

Clusters that are imported using system templates are managed exclusively through their corresponding environments.