Getting Started with EKS - Rafay Product Documentation

Getting Started with EKS

Overview

This self-paced guide demonstrates how to leverage Rafay's system templates for complete lifecycle management of Amazon EKS clusters. You'll learn to streamline cluster provisioning, management, and Day 2 operations using pre-configured, customizable templates from the template catalog.

Why Use System Templates for EKS?

System templates provide significant advantages for EKS cluster management:

Prerequisites

Required Access & Permissions

Required Components

Agent Deployment & Permissions When deploying the Rafay agent:

Alternatively, the Rafay Agent can be deployed as a pod on your Kubernetes cluster.

Look for the cd-agent-<some hash id> pod and check the NODE column.

This setup allows the agent pod to assume the necessary role for EKS provisioning and management operations.

AWS Role Configuration

1. Create Required IAM Roles

EC2 Machine Role

Attach this role to the EC2 instance hosting the Rafay agent:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "STSPermissions",
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IAMPermissions",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

Security Best Practice The above policy uses broad permissions for simplicity. For production environments:

System Template Role

Create a dedicated role with the required EKS Permissions for cluster provisioning.

2. Configure Trust Relationships

Both roles require trust relationships with each other. System Template Role Trust Policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::xxxxxxxxxx:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "aa4a-6418-ca23-3ece-6c1d"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::xxxxxxxxxx:role/role-test"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

EC2 Machine Role Trust Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com",
        "AWS": "arn:aws:iam::xxxxxxx:role/eks-cluster-provisioning-role"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Update ARNs Replace the ARNs in the trust policies with your actual AWS account IDs and role names.

3. Configure EKS Security Groups

The EKS cluster's additional security group must allow inbound access from the Rafay agent:

Step-by-Step Guide

1. Select and Share the AWS EKS System Template

1.1 Create a Project

Create a logically isolated environment for template management:

  1. Navigate to Home > Your Projects
  2. Click Create a New Project
  3. Name it eks-template

1.2 Access and Share the Template

  1. As an Org Admin, go to Settings > Template Catalog
  2. Select Cluster LCM category
  3. Choose the AWS EKS System template
  4. Click Get Started
  5. Provide the following details:
  6. Template Name: Unique identifier for your shared template
  7. Version: Version name (e.g., v1)
  8. Target Project: Select eks-template project
  9. After sharing, you'll be redirected to the selected project

1.3 Configure the Agent

  1. Go to Agents
  2. Configure the required Agent to drive the workflow
  3. Select an existing Agent if already deployed on your AWS private network

1.4 Customize Template Configuration

Configure EKS Parameters

Customize and templatize EKS configurations using input variables:

Set Parameter Restrictions

Control user access to specific variables:

Configure AWS Credentials

Navigate to Config Context and provide AWS authentication:

1.5 Save Template Version

  1. Save as Draft for ongoing edits
  2. Set as Active Version when configuration is finalized
  3. Learn more about version management

2. Launch Template to Create EKS Cluster

2.1 Access the Template

  1. Navigate to Environments section in the eks-template project (or shared project)
  2. Locate the shared template in the list

2.2 Launch the Template

  1. Click Launch
  2. Configure the exposed parameters only:
  3. Kubernetes Version
  4. Blueprint Name and Version
  5. Node Group Configuration
  6. Other parameters as defined in template
  7. All other EKS configurations are pre-configured with override: Not Allowed

EC2 IMDS Error Troubleshooting If you encounter an EC2 IMDS error during deployment:

Error: failed to refresh cached credentials, no EC2 IMDS role found,
operation error ec2imds: GetMetadata, http response error StatusCode: 404,
request to EC2 IMDS failed

Solutions:

References:

3. Day 2 Operations

3.1 Kubernetes Upgrades

Control Plane Upgrade

  1. Navigate to the EKS cluster environment
  2. Click Edit
  3. Update Kubernetes version (e.g., from 1.31 to 1.32)
  4. Click Redeploy to initiate upgrade

Node Group Upgrade

  1. Edit the environment
  2. Update the cluster_version for node groups
  3. Click Redeploy to apply changes

Independent Upgrades Control plane and node groups can be upgraded independently of each other.

3.2 Cluster Deletion

  1. Navigate to the EKS cluster environment
  2. Click Destroy
  3. Confirm by selecting Yes
  4. This will delete the EKS cluster and all dependent resources

Additional Resources

Conclusion

You have successfully completed the following:

System templates provide a powerful foundation for: