Skip to content

Getting Started with EKS

Overview

This self-paced guide helps you explore the platform's capabilities for lifecycle management of EKS clusters on AWS using system templates from the template catalog.

Why Use System Templates for EKS on AWS?

System templates streamline the creation and management of EKS clusters by offering pre-configured, customizable templates. These templates:

  • Ensure consistency and reduce setup time
  • Enable organization administrators to enforce standards while allowing teams to customize configurations
  • Simplify workflows by integrating tools like ServiceNow or Jira
  • Enhance collaboration and efficiency in managing EKS on AWS environments

Prerequisites

Before proceeding, ensure the following:

  • Access to an AWS environment
  • Sufficient privileges to create EKS clusters on AWS
  • Rafay Agent deployed in your network (an AWS EC2 machine with permissions to interact with AWS). Follow these instructions to deploy an agent
  • A Rafay API key. Follow these instructions to generate an API key
  • An AWS Role ARN or AWS Access Key & Secret with EKS Permissions to create EKS clusters and resources

Note on Agent Deployment and Permissions

When deploying the Rafay agent, ensure that the EC2 instance where the agent is running has an IAM role attached with the required permissions. This role should allow the agent to interact with AWS services, which is critical for the agent to assume roles during execution. The agent must have permissions to perform actions such as listing resources and fetching metadata.

If you prefer to provide an AWS Role ARN instead of Access Key and Secret as input in the template, the EC2 instance must have the necessary permissions to assume that role for driving the execution.

Role-Based Credentials Setup

1. Create Required Roles

EC2 Machine Role

This role is attached to the EC2 instance where the Rafay agent is deployed:

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

IAM Policy

The above policy provides broad permissions (sts:*) to all AWS Security Token Service (STS) actions. While this works, it's recommended to restrict the permissions to only what's needed:

  • Replace sts:* with specific actions like sts:AssumeRole, sts:GetCallerIdentity
  • Limit the Resource field to specific role ARNs instead of *
  • Consider adding conditions to restrict which roles can be assumed

System Template Role

Create a role for the System Template with the required EKS Permissions.

2. Configure Trust Relationships

The EC2 Machine IAM Role needs a trust relationship policy to assume Role:

{
  "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"
    }
  ]
}

Note

Replace arn:aws:iam::xxxxxxx:role/eks-cluster-provisioning-role with your System Template Role.

Part 1: Select and Share the AWS EKS Cluster System Template

This section guides you through selecting and sharing the AWS EKS system template with a central project where the Org admin can customize it before sharing it with other projects.

Step 1: Create a Project

To begin, create a logically isolated “operating environment” (sub-tenant):

  • Navigate to Home > Your Projects.
  • Click Create a New Project and name it eks-template.

Create Project

Step 2: Select and Share the AWS EKS System Template
  • As an Org Admin, go to Settings > Template Catalog.

Catelog

  • Select the Cluster LCM category and choose the AWS EKS System template.
  • Click Get Started.
  • Provide the following details:
  • A unique name for the shared template.
  • A version name (e.g., v1).

  • Select the project to share the template with (e.g., eks-template).

  • After sharing, the platform redirects you to the selected project (eks-template).

Template

  • Go to Agents and configure the required Agent to drive the workflow. If an Agent is already added and deployed on the AWS Private Network (as part of the prerequisites), you can select and use that Agent.

Agent EM

Configuration Customization

  • Customize and templatize all EKS-related configurations using input variables, including:

    • Networking: VPC ID, Subnets, Security Groups etc
    • Node Groups: Instance types, Node counts etc

  • Restrict user edits for specific variables by:

    • Setting overrides to Not Allowed
    • Defining default values

  • Pre-configure up to 45 parameters, ensuring a minimal, user-friendly setup with reduced manual input.

EKS

  • Provide AWS credentials by either using an AWS Access Key and Secret or an AWS Role ARN. Navigate to Config Context and edit the configuration as shown below. If you prefer not to provide the Access Key and Secret, ensure that the machine where the agent is deployed has the necessary permissions to assume the role for driving the execution.

Config Context

CC Configuration

This ensures consistency and prevents unauthorized changes by end users.

  • Save the template as a Draft to allow ongoing edits until the configuration is finalized. Once all changes are complete, set it as an Active Version to freeze the version. Learn more about version management.

Save Version

Part 2: Launch the Template to Create an EKS Cluster

You can launch the template within the same project or share it with other projects for end-user access.

  • Go to the Environments section within the eks-template project or the shared project.

  • The shared template will be listed and ready for use.

EKS Template

  • Click Launch.

  • Provide only the configuration options exposed to the template consumer, such as:

    • Kubernetes Version
    • Blueprint Name and Version
    • Node Group Configuration

  • All other EKS configurations are pre-configured and set as override: Not Allowed to ensure a simple and streamlined experience for the end user.

Launch Template

EC2 IMDS Error During Template Deployment via Agent

When deploying a template using an agent running on an EC2 instance, you may encounter the following error:

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

This happens because the agent attempts to retrieve AWS credentials through the EC2 Instance Metadata Service (IMDS), and the instance's metadata configuration restricts access.

How to Fix:

  • Option 1: Modify the instance metadata settings to make IMDSv2 optional, allowing credential retrieval without strict IMDSv2 enforcement.
  • Option 2: If IMDSv2 must remain required for security reasons, increase the hop limit (recommended greater than 2) to allow connections from the agent to the metadata service.

Refer to AWS documentation for detailed steps: - Retrieving Instance Metadata - Configuring IMDS for Existing Instances

Part 3: Day 2 Operations on the Created EKS Cluster

Upgrading Kubernetes Control Plane and Node Groups

  • Navigate to the environment of the created EKS cluster.

  • To upgrade the control plane:

    • Click Edit and update the Kubernetes version from 1.31 to 1.32.
    • Click Redeploy to initiate the control plane upgrade.

  • To upgrade managed node groups:

    • Edit the environment and update the node group version cluster_version
    • Click Redeploy to apply the node group upgrade.

Note: Control plane and node groups can be upgraded independently of each other.

Deleting/Destroying the EKS Cluster
  • Navigate to the environment of the created EKS cluster.
  • Click Destroy and confirm the action by selecting Yes.
  • This will delete the EKS cluster along with all dependent resources created as part of the cluster.

For detailed examples of EKS system template configurations, please refer to our EKS System Template Examples guide.

Conclusion

By following these steps, you have successfully:

  • Selected and shared the AWS EKS system template.
  • Used the template to do Lifecycle Management of AWS EKS cluster.

These system templates simplify EKS cluster management, ensure compliance with organizational standards, and provide flexibility for specific workflows.