Skip to content

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

sequenceDiagram
    autonumber
    participant User
    participant Azure
    participant Rafay

    User->>Azure: Create AKS cluster
    User->>Rafay: Launch "aks-import-cluster" template
    User->>Rafay: Enter AKS and Azure details
    Rafay->>Azure: Discover existing AKS cluster
    Rafay->>Rafay: Create environment
    Rafay-->>User: Show status: In Progress → Evaluating

Deploy and Manage the Imported AKS Cluster

sequenceDiagram
    participant User
    participant Rafay
    participant AKS Cluster

    User->>Rafay: Select generated environment
    User->>Rafay: Click "Edit" to review config
    User->>Rafay: Click "Deploy" (system-aks-takeover)

    Rafay->>AKS Cluster: Finalize environment setup
    AKS Cluster-->>Rafay: Send status

    Rafay-->>User: Status = "Success"
    User->>Rafay: Open Cluster Dashboard
    Rafay-->>User: 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

Template Triggered By Purpose User Input Required
aks-import-cluster User Discover AKS cluster and create environment ✅ Yes
system-aks-takeover Rafay (automatic) Finalize setup and register the cluster ❌ No

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.

Customize Cluster

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.

Note:
During the import and takeover process, the workflow performs an az login operation, which requires outbound network access to login.microsoftonline.com. Additionally, ensure that the Rafay Controller IP addresses (see the official whitelist documentation) are whitelisted in the network where your AKS clusters reside. This is necessary to enable successful communication between your clusters and the rafay controller.

Customize 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

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.

Customize Cluster

  • 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.

Customize Cluster

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.

Customize Cluster

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.

Customize Cluster

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.

Customize Cluster

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