Skip to main content

​
Overview

This guide walks you through the process of importing an existing AWS EKS cluster into the Simplismart platform. By importing your cluster, you can leverage Simplismart’s deployment, monitoring, and scaling capabilities with your existing infrastructure.
Coming Soon: Warmpool functionality and automatic node group creation are currently only available for clusters created directly on the Simplismart platform.In an upcoming release, these features will be extended to imported clusters. You’ll be able to provide limited IAM access, and Simplismart will manage warmpool and node group creation automatically, just like it does for Simplismart-created clusters.

​
Prerequisites

Before importing your cluster, ensure you have the following:

​
EKS Cluster

You need an AWS EKS cluster. If you don’t already have one, follow the Create AWS EKS Cluster guide.

​
Node Group

Your cluster must have at least one node group with minimum 1 vCPU and the required label (see below). For auxiliary node groups where Simplismart cluster tools will be installed, use a minimum machine size of m6a.xlarge.

​
Node Group Label

All nodes in your cluster must have the required label. To add a label, navigate to Amazon Elastic Kubernetes Service > Clusters > <cluster_name> > <node_group> > edit and add a label in the format given below: 
simplismart.ai/node-group-name: <node-group-name>
Node Group Label This label is essential for the Simplismart platform to identify and manage your nodes correctly.
If you are importing a cluster, you need to create a node group yourself on AWS. Only then you can register it on the Simplismart platform. See the Create AWS EKS Cluster guide for detailed instructions on creating node groups with the required label.

​
Kubernetes Credentials

Configure your Kubernetes credentials as a secret in Simplismart to authenticate with your AWS EKS Cluster. AWS supports both token-based and certificate-based authentication. This guide covers token-based authentication using three different approaches.
Important Timing Constraint: AWS EKS tokens have a 15-minute validity period. Since cluster import on Simplismart takes approximately 10 minutes, you must generate the kubeconfig credentials and start the import process within 5 minutes. If the token expires during import, the cluster import will fail with an authentication error. If this happens, simply regenerate the credentials and retry the import.
This method uses the AWS CLI to generate kubeconfig credentials programmatically.
1

Configure AWS CLI

Ensure you have AWS CLI installed and configured with appropriate credentials:
aws configure
Enter your AWS Access Key ID, Secret Access Key, default region, and output format when prompted.
2

Update Kubeconfig

Update your local kubeconfig file to include the EKS cluster credentials:
aws eks update-kubeconfig --region <region> --name <cluster-name>
Replace <region> with your AWS region (e.g., us-east-1) and <cluster-name> with your EKS cluster name.This command will add the cluster context to your ~/.kube/config file.
3

Verify Connection

Test the connection to your cluster:
kubectl get nodes
If successful, you should see a list of nodes in your cluster.
4

Extract Kubeconfig

Extract the kubeconfig content to add as a secret in Simplismart:
cat ~/.kube/config
Copy the entire output. You’ll use this in the next step.
5

Add Secret in Simplismart

Go to the Secrets section in Simplismart and:
  • Click on the Kubernetes tab
  • Add a new secret with the kubeconfig content you copied
  • Follow the detailed configuration instructions in the Secrets documentation
This method uses the AWS Management Console to retrieve cluster connection information and build the kubeconfig manually.
1

Navigate to EKS Cluster

  • Open the AWS Management Console
  • Go to Amazon EKS service
  • Select your cluster from the list
2

Get Cluster Endpoint and Certificate

In the cluster details page, note down the following:
  • API server endpoint: Found in the Configuration tab
  • Certificate authority data: Found in the Configuration tab (click “Show” to reveal)
Copy both values—you’ll need them to construct the kubeconfig.
3

Create Kubeconfig File

Create a kubeconfig file with the following structure:
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: <CERTIFICATE_AUTHORITY_DATA>
    server: <API_SERVER_ENDPOINT>
  name: <CLUSTER_NAME>
contexts:
- context:
    cluster: <CLUSTER_NAME>
    user: <CLUSTER_NAME>
  name: <CLUSTER_NAME>
current-context: <CLUSTER_NAME>
users:
- name: <CLUSTER_NAME>
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args:
        - eks
        - get-token
        - --cluster-name
        - <CLUSTER_NAME>
        - --region
        - <REGION>
Replace the placeholders:
  • <CERTIFICATE_AUTHORITY_DATA>: Certificate authority data from Step 2
  • <API_SERVER_ENDPOINT>: API server endpoint from Step 2
  • <CLUSTER_NAME>: Your EKS cluster name
  • <REGION>: Your AWS region (e.g., us-east-1)
4

Verify Configuration

Save the kubeconfig file and test the connection:
export KUBECONFIG=/path/to/your/kubeconfig
kubectl get nodes
If successful, you should see a list of nodes in your cluster.
5

Add Secret in Simplismart

Go to the Secrets section in Simplismart and:
  • Click on the Kubernetes tab
  • Add a new secret with the kubeconfig content you created
  • Follow the detailed configuration instructions in the Secrets documentation
This method uses eksctl, a simple CLI tool for creating and managing EKS clusters.
1

Install eksctl

If you haven’t installed eksctl yet, follow the eksctl installation guide.For macOS:
brew tap weaveworks/tap
brew install weaveworks/tap/eksctl
For Linux:
curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/eksctl /usr/local/bin
2

Generate Kubeconfig

Use eksctl to write the cluster credentials to your kubeconfig:
eksctl utils write-kubeconfig --cluster <cluster-name> --region <region>
Replace <cluster-name> with your EKS cluster name and <region> with your AWS region.This will automatically update your ~/.kube/config file.
3

Verify Connection

Test the connection to your cluster:
kubectl get nodes
If successful, you should see a list of nodes in your cluster.
4

Extract Kubeconfig

Extract the kubeconfig content:
cat ~/.kube/config
Copy the entire output.
5

Add Secret in Simplismart

Go to the Secrets section in Simplismart and:
  • Click on the Kubernetes tab
  • Add a new secret with the kubeconfig content you copied
  • Follow the detailed configuration instructions in the Secrets documentation
For production environments, it’s recommended to create a dedicated IAM role with minimal required permissions for Simplismart access, rather than using admin credentials.

​
Import Cluster

1

Enter Basic Details

Basic detailsProvide the following information about your cluster:
FieldDescription
Cluster NameA unique name to identify your cluster in the Simplismart platform
Cloud ProviderSelect AWS as your cloud provider
SecretSelect a secret to authenticate with AWS. See the Secrets section for configuration details
RegionThe AWS region where your EKS cluster is deployed
Hosted ZoneThe DNS hosted zone for your cluster. See Hosted Zone documentation
EnvironmentSelect your environment type: Production, Development, Demo, or Custom
Custom Environment DescriptionProvide a description if you selected “Custom” environment
2

Configure Cluster Tools

Select the tools to install on your cluster during the import process. All tools shown below are mandatory for core cluster functionality.Cluster Tools

​
Scaling Tools

Collects basic pod and node resource usage (CPU/memory) to enable Kubernetes Horizontal Pod Autoscaling and efficient resource management.
Automatically adds or removes nodes in your cluster based on workload demand, optimizing costs by scaling infrastructure dynamically.
The Prometheus Adapter is a fallback in case we want to switch to use HPA and scale based on number of requests or custom metrics.
Our main event-driven autoscaler that scales applications based on workload activity (e.g., queue length, message count), improving performance and reducing costs during idle periods. It is required for scale to 0.

​
Observability Tools

Long-term metrics storage system that provides reliable, scalable storage for time-series data, enabling historical analysis and trend monitoring.
Centralized log aggregation system that collects and stores logs from all applications, making it easy to search, filter, and debug issues across your cluster.
Log shipping agent that collects logs from your applications and forwards them to Loki, making all logs searchable in the Simplismart platform.
Complete monitoring solution providing dashboards, metrics collection, and alerting capabilities to monitor workload health and system performance.
GPU monitoring tool that tracks NVIDIA GPU utilization, temperature, and health metrics, essential for optimizing AI/ML workloads.
Simplismart’s internal monitoring agent that collects operational metrics and system health data like disk pressure, node readiness, degraded pod, etc for platform integration.
3

Register Node Groups

Configure your node groups to be managed by the Simplismart platform. Node group configuration allows you to manage your cluster resources based on workload types, hardware requirements, and scaling policies.Using the given configuration, Simplismart is able to intelligently manage the nodes and effectively distribute the resources.Register Node Group

​
Node Group Label

Provide the node group label you configured earlier in the Prerequisites section. This label allows Simplismart to identify and manage your node group.
You can register multiple node groups with different configurations to use your cluster resources effectively on the Simplismart platform.

​
Node Group Configuration

Enable Use Node Group Configuration to have Simplismart automatically allocates the resource during the deployment. If not selected, you need to provide node configuration every time you deploy.
FieldDescription
Accelerator TypeSelect either CPU or GPU based on your workload requirements
Accelerator CountNumber of accelerators (GPUs) per node
Min Node CountMinimum number of nodes to maintain in this node group
Max Node CountMaximum number of nodes allowed in this node group for autoscaling
CPUNumber of CPU cores per node
MemoryMemory allocation in GB per node
When this option is enabled, Simplismart will manage the specified node group in your EKS cluster based on the resource configuration provided. The node group must already exist in your cluster.

​
Auxiliary Node Group

Enable Mark as Auxiliary if this node group should be reserved for supporting workloads rather than primary AI/ML operations.Common use cases for auxiliary node groups:
  • Monitoring and logging services (refer to Step 2 for details)
  • Internal tooling and platform services
4

Add Tags (Optional)

Add custom tags to manage and identify your cluster for billing, cost allocation, and resource management. Tags will be auto-populated in the billing section as well as the event center for better tracking and visualization. Moreover, you can create environment tags for Testing, Staging or Production based on your requirements. Environment specific tags will help you in billing and how much each environment is generating the bills.Click Add Tag and provide key-value pairs as needed.

​
Post-Import Steps

After successfully importing your cluster, follow these steps to get started:

Verify Cluster Health

Check that the cluster status shows as “Success” in the Simplismart dashboard. Verify all cluster tools are running correctly.

Deploy Models

Start deploying AI/ML models to your imported cluster using the Simplismart platform.

Monitor Performance

Use the observability tools (Grafana, Prometheus, Loki) to monitor cluster health and performance metrics.

Bring Your Own Container

Deploy custom Docker containers to your cluster for custom models.

​
Deployment Capabilities

​
Current Support

Imported clusters currently support container-based deployments. You can deploy Docker/Depot containers with full integration into the Simplismart platform, including:
  • Monitoring via the observability stack (Grafana, Prometheus, Loki)
  • Auto-scaling via the scalability stack (Metrics Server, Cluster Autoscaler, KEDA)
  • Resource management and optimization

​
Coming Soon

In future releases, imported clusters will support:
Full support for custom Helm chart deployments with complete lifecycle management. Your Helm deployments will be:
  • Fully monitored via the Simplismart observability stack
  • Fully scalable via the Simplismart scalability stack
Once warmpool support is enabled for imported clusters, you’ll benefit from:
  • Rapid auto-scaling for faster response to workload demands
  • Reduced cold-start times through pre-warmed resources
  • Same capabilities as clusters created directly on the Simplismart platform
This will enable the same rapid scaling performance you get with Simplismart-created clusters.

​
Troubleshooting

If you encounter issues during the cluster import process, please feel free to reach out to our support team at [email protected].