> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplismart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import AWS EKS Cluster to Simplismart Platform

> Learn how to import an existing AWS EKS cluster into the Simplismart platform and configure its settings

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

<Info>
  **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.
</Info>

## 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](/model-suite/clusters/import-cluster/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:

```bash theme={null}
simplismart.ai/node-group-name: <node-group-name>
```

<img src="https://mintcdn.com/simplismart-3f10d72e/VLUnUVTHga2W8xuR/images/model-suite/clusters/import-cluster/import-aws-cluster/4-node-group-label.png?fit=max&auto=format&n=VLUnUVTHga2W8xuR&q=85&s=b7fb9f099e5b6f6c89cba3bfd2c7724e" alt="Node Group Label" width="1633" height="685" data-path="images/model-suite/clusters/import-cluster/import-aws-cluster/4-node-group-label.png" />

This label is essential for the Simplismart platform to identify and manage your nodes correctly.

<Info>
  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](/model-suite/clusters/import-cluster/create-aws-eks-cluster#create-node-groups) for detailed instructions on creating node groups with the required label.
</Info>

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

<Warning>
  **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.
</Warning>

<AccordionGroup>
  <Accordion title="Method 1: Using AWS CLI" icon="terminal">
    This method uses the AWS CLI to generate kubeconfig credentials programmatically.

    <Steps>
      <Step title="Configure AWS CLI">
        Ensure you have AWS CLI installed and configured with appropriate credentials:

        ```bash theme={null}
        aws configure
        ```

        Enter your AWS Access Key ID, Secret Access Key, default region, and output format when prompted.
      </Step>

      <Step title="Update Kubeconfig">
        Update your local kubeconfig file to include the EKS cluster credentials:

        ```bash theme={null}
        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.
      </Step>

      <Step title="Verify Connection">
        Test the connection to your cluster:

        ```bash theme={null}
        kubectl get nodes
        ```

        If successful, you should see a list of nodes in your cluster.
      </Step>

      <Step title="Extract Kubeconfig">
        Extract the kubeconfig content to add as a secret in Simplismart:

        ```bash theme={null}
        cat ~/.kube/config
        ```

        Copy the entire output. You'll use this in the next step.
      </Step>

      <Step title="Add Secret in Simplismart">
        Go to the [Secrets](/model-suite/integrations/secrets#json-format-for-adding-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
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Method 2: Using AWS Management Console" icon="browser">
    This method uses the AWS Management Console to retrieve cluster connection information and build the kubeconfig manually.

    <Steps>
      <Step title="Navigate to EKS Cluster">
        * Open the **AWS Management Console**
        * Go to **Amazon EKS** service
        * Select your cluster from the list
      </Step>

      <Step title="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.
      </Step>

      <Step title="Create Kubeconfig File">
        Create a kubeconfig file with the following structure:

        ```yaml theme={null}
        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`)
      </Step>

      <Step title="Verify Configuration">
        Save the kubeconfig file and test the connection:

        ```bash theme={null}
        export KUBECONFIG=/path/to/your/kubeconfig
        kubectl get nodes
        ```

        If successful, you should see a list of nodes in your cluster.
      </Step>

      <Step title="Add Secret in Simplismart">
        Go to the [Secrets](/model-suite/integrations/secrets#json-format-for-adding-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
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Method 3: Using eksctl" icon="code">
    This method uses eksctl, a simple CLI tool for creating and managing EKS clusters.

    <Steps>
      <Step title="Install eksctl">
        If you haven't installed eksctl yet, follow the [eksctl installation guide](https://eksctl.io/installation/).

        For macOS:

        ```bash theme={null}
        brew tap weaveworks/tap
        brew install weaveworks/tap/eksctl
        ```

        For Linux:

        ```bash theme={null}
        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
        ```
      </Step>

      <Step title="Generate Kubeconfig">
        Use eksctl to write the cluster credentials to your kubeconfig:

        ```bash theme={null}
        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.
      </Step>

      <Step title="Verify Connection">
        Test the connection to your cluster:

        ```bash theme={null}
        kubectl get nodes
        ```

        If successful, you should see a list of nodes in your cluster.
      </Step>

      <Step title="Extract Kubeconfig">
        Extract the kubeconfig content:

        ```bash theme={null}
        cat ~/.kube/config
        ```

        Copy the entire output.
      </Step>

      <Step title="Add Secret in Simplismart">
        Go to the [Secrets](/model-suite/integrations/secrets#json-format-for-adding-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
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Note>
  For production environments, it's recommended to create a dedicated IAM role with minimal required permissions for Simplismart access, rather than using admin credentials.
</Note>

***

## Import Cluster

<Steps>
  <Step title="Enter Basic Details">
    <img src="https://mintcdn.com/simplismart-3f10d72e/VLUnUVTHga2W8xuR/images/model-suite/clusters/import-cluster/import-aws-cluster/1-basic-details.png?fit=max&auto=format&n=VLUnUVTHga2W8xuR&q=85&s=cb7300b691d6a17704497f5d6c9a9c9a" alt="Basic details" width="2864" height="1154" data-path="images/model-suite/clusters/import-cluster/import-aws-cluster/1-basic-details.png" />

    Provide the following information about your cluster:

    | Field                              | Description                                                                                                                      |
    | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
    | **Cluster Name**                   | A unique name to identify your cluster in the Simplismart platform                                                               |
    | **Cloud Provider**                 | Select AWS as your cloud provider                                                                                                |
    | **Secret**                         | Select a secret to authenticate with AWS. See the [Secrets](/model-suite/integrations/secrets) section for configuration details |
    | **Region**                         | The AWS region where your EKS cluster is deployed                                                                                |
    | **Hosted Zone**                    | The DNS hosted zone for your cluster. See [Hosted Zone](/model-suite/integrations/hosted-zone) documentation                     |
    | **Environment**                    | Select your environment type: Production, Development, Demo, or Custom                                                           |
    | **Custom Environment Description** | Provide a description if you selected "Custom" environment                                                                       |
  </Step>

  <Step title="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.

    <img src="https://mintcdn.com/simplismart-3f10d72e/VLUnUVTHga2W8xuR/images/model-suite/clusters/import-cluster/import-aws-cluster/2-cluster-tools.png?fit=max&auto=format&n=VLUnUVTHga2W8xuR&q=85&s=a07dd230ea4e91115ca458d17627ea0d" alt="Cluster Tools" width="2864" height="780" data-path="images/model-suite/clusters/import-cluster/import-aws-cluster/2-cluster-tools.png" />

    ### Scaling Tools

    <AccordionGroup>
      <Accordion title="Metrics Server" icon="chart-line">
        Collects basic pod and node resource usage (CPU/memory) to enable Kubernetes Horizontal Pod Autoscaling and efficient resource management.
      </Accordion>

      <Accordion title="Cluster Autoscaler" icon="arrows-maximize">
        Automatically adds or removes nodes in your cluster based on workload demand, optimizing costs by scaling infrastructure dynamically.
      </Accordion>

      <Accordion title="Prometheus Adapter" icon="gauge">
        The [Prometheus Adapter](https://github.com/kubernetes-sigs/prometheus-adapter) is a fallback in case we want to switch to use HPA  and  scale based on number of requests or custom metrics.
      </Accordion>

      <Accordion title="KEDA" icon="bolt">
        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.
      </Accordion>
    </AccordionGroup>

    ### Observability Tools

    <AccordionGroup>
      <Accordion title="Mimir" icon="database">
        Long-term metrics storage system that provides reliable, scalable storage for time-series data, enabling historical analysis and trend monitoring.
      </Accordion>

      <Accordion title="Loki" icon="file-lines">
        Centralized log aggregation system that collects and stores logs from all applications, making it easy to search, filter, and debug issues across your cluster.
      </Accordion>

      <Accordion title="Promtail" icon="paper-plane">
        Log shipping agent that collects logs from your applications and forwards them to Loki, making all logs searchable in the Simplismart platform.
      </Accordion>

      <Accordion title="Grafana Prometheus Stack" icon="chart-mixed">
        Complete monitoring solution providing dashboards, metrics collection, and alerting capabilities to monitor workload health and system performance.
      </Accordion>

      <Accordion title="DCGM Exporter" icon="microchip">
        GPU monitoring tool that tracks NVIDIA GPU utilization, temperature, and health metrics, essential for optimizing AI/ML workloads.
      </Accordion>

      <Accordion title="Simplismart Agent" icon="robot">
        Simplismart's internal monitoring agent that collects operational metrics and system health data like disk pressure, node readiness, degraded pod, etc for platform integration.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="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.

    <img src="https://mintcdn.com/simplismart-3f10d72e/VLUnUVTHga2W8xuR/images/model-suite/clusters/import-cluster/import-aws-cluster/3-register-node-group.png?fit=max&auto=format&n=VLUnUVTHga2W8xuR&q=85&s=fd3a7843bd92d44a88a093526b316fb0" alt="Register Node Group" width="2864" height="1066" data-path="images/model-suite/clusters/import-cluster/import-aws-cluster/3-register-node-group.png" />

    ### Node Group Label

    Provide the node group label you configured earlier in the [Prerequisites](#node-group-label) section. This label allows Simplismart to identify and manage your node group.

    <Note>
      You can register multiple node groups with different configurations to use your cluster resources effectively on the Simplismart platform.
    </Note>

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

    | Field                 | Description                                                          |
    | --------------------- | -------------------------------------------------------------------- |
    | **Accelerator Type**  | Select either **CPU** or **GPU** based on your workload requirements |
    | **Accelerator Count** | Number of accelerators (GPUs) per node                               |
    | **Min Node Count**    | Minimum number of nodes to maintain in this node group               |
    | **Max Node Count**    | Maximum number of nodes allowed in this node group for autoscaling   |
    | **CPU**               | Number of CPU cores per node                                         |
    | **Memory**            | Memory allocation in GB per node                                     |

    <Note>
      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.
    </Note>

    ### 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
  </Step>

  <Step title="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](/model-suite/settings/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.
  </Step>
</Steps>

***

## Post-Import Steps

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

<CardGroup cols={2}>
  <Card title="Verify Cluster Health" icon="heart-pulse">
    Check that the cluster status shows as "Success" in the Simplismart dashboard. Verify all cluster tools are running correctly.
  </Card>

  <Card title="Deploy Models" icon="rocket" href="/quickstart/deploy">
    Start deploying AI/ML models to your imported cluster using the Simplismart platform.
  </Card>

  <Card title="Monitor Performance" icon="chart-line">
    Use the observability tools (Grafana, Prometheus, Loki) to monitor cluster health and performance metrics.
  </Card>

  <Card title="Bring Your Own Container" icon="box" href="/model-suite/add-container">
    Deploy custom Docker containers to your cluster for custom models.
  </Card>
</CardGroup>

***

## 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:

<AccordionGroup>
  <Accordion title="Custom Helm Deployments" icon="ship">
    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
  </Accordion>

  <Accordion title="Warmpool & Rapid Auto-scaling" icon="bolt">
    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.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

If you encounter issues during the cluster import process, please feel free to reach out to our support team at [support@simplismart.ai](mailto:support@simplismart.ai).