diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md new file mode 100644 index 0000000000..53f46080f4 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md @@ -0,0 +1,70 @@ +--- +title: "Deploy an EKS cluster with Graviton nodes using Rafay" + +description: Use the Rafay Kubernetes Operations Platform to provision an Amazon EKS cluster with an Arm Graviton node group and deploy NGINX to verify the setup. + +draft: true +cascade: + draft: true + +minutes_to_complete: 60 + +who_is_this_for: > + This is an advanced topic for software developers familiar with Kubernetes and AWS who want to learn how to use the Rafay platform to provision and manage EKS clusters backed by Arm Graviton instances. + +learning_objectives: + - Connect your AWS account to the Rafay platform using a cross-account IAM role + - Provision an Amazon EKS cluster with an Arm Graviton node group using Rafay + - Deploy and verify NGINX on Arm nodes and clean up all cloud resources + +prerequisites: + - An Amazon Web Services (AWS) [account](https://aws.amazon.com/) + - A [Rafay account](https://rafay.co) + - The [AWS CLI](/install-guides/aws-cli/) installed and configured + +author: Jason Andrews + +generate_summary_faq: true +rerun_summary: false +rerun_faqs: false + +### Tags +skilllevels: Advanced +subjects: Containers and Virtualization +cloud_service_providers: + - AWS +armips: + - Neoverse +operatingsystems: + - Linux +tools_software_languages: + - Kubernetes + - AWS Elastic Kubernetes Service (EKS) + - Rafay + - NGINX + - rctl + +# FIXED, DO NOT MODIFY +# ================================================================================ +further_reading: + - resource: + title: Rafay CLI overview + link: https://docs.rafay.co/cli/overview/ + type: documentation + - resource: + title: Amazon EKS documentation + link: https://aws.amazon.com/eks/ + type: documentation + - resource: + title: AWS Graviton processors + link: https://aws.amazon.com/ec2/graviton/ + type: documentation + - resource: + title: Kubernetes documentation + link: https://kubernetes.io/docs/home/ + type: documentation + +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # Indicates this should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_next-steps.md new file mode 100644 index 0000000000..727b395ddd --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # The weight controls the order of the pages. _index.md always has weight 1. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md new file mode 100644 index 0000000000..b14b9ad2a5 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md @@ -0,0 +1,182 @@ +--- +title: "Create the EKS cluster" +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +In this section, you define and provision an EKS cluster with a Graviton-based node group using Rafay's declarative manifest format. You then apply the manifest with RCTL, wait for the cluster to reach a ready state, and download the kubeconfig so you can interact with the cluster. + +## Create the cluster manifest + +The Rafay platform uses a declarative YAML manifest to define your EKS cluster. Create a file named `demo-eks-graviton.yaml` with the following content: + +```yaml +apiVersion: infra.k8smgmt.io/v3 +kind: Cluster +metadata: + # The name of the cluster + name: demo-eks-graviton + # The name of the project the cluster will be created in + project: defaultproject +spec: + blueprintConfig: + # The name of the blueprint the cluster will use + name: minimal + # The version of the blueprint the cluster will use + version: latest + # The name of the cloud credential that will be used to create the cluster + cloudCredentials: aws-cloud-credential + config: + # The EKS addons that will be applied to the cluster + addons: + - name: kube-proxy + version: latest + - name: vpc-cni + version: latest + - name: coredns + version: latest + managedNodeGroups: + # The AWS AMI family type the nodes will use + - amiFamily: AmazonLinux2023 + # The desired number of nodes that can run in the node group + desiredCapacity: 1 + iam: + withAddonPolicies: + # Enables the IAM policy for cluster autoscaler + autoScaler: true + # Allows for full ECR (Elastic Container Registry) access. This is useful for building, for example, a CI server that needs to push images to ECR + imageBuilder: true + # The AWS EC2 instance type that will be used for the nodes + instanceType: m7g.large + # The maximum number of nodes that can run in the node group + maxSize: 1 + # The minimum number of nodes that can run in the node group + minSize: 1 + # The name of the node group that will be created in AWS + name: graviton + metadata: + # The name of the cluster + name: demo-eks-graviton + # The AWS region the cluster will be created in + region: us-east-1 + # The tags that will be applied to the AWS cluster resources + tags: + email: user@rafay.co + env: qa + # The Kubernetes version that will be installed on the cluster + version: latest + vpc: + # AutoAllocateIPV6 requests an IPv6 CIDR block with /56 prefix for the VPC + autoAllocateIPv6: false + clusterEndpoints: + # Enables private access to the Kubernetes API server endpoints + privateAccess: true + # Enables public access to the Kubernetes API server endpoints + publicAccess: false + # The CIDR that will be used by the cluster VPC + cidr: 192.168.0.0/16 + type: aws-eks +``` + +Key fields to note: + +- `cloudCredentials` — must exactly match the credential name you entered in the Rafay console +- `project` - must be the project you attached the credential to +- `instanceType: m7g.large` — a Graviton3 instance with Arm Neoverse processors +- `publicAccess: false` — the Kubernetes API server has no public endpoint. You reach the cluster exclusively through RCTL, which routes traffic through the Rafay control plane. + +## Apply the cluster manifest + +Submit the manifest to Rafay using `rctl`: + +```console +rctl apply -f demo-eks-graviton.yaml +``` + +The output is similar to: + +```output +[ + { + "tasksetId": "ko9176k", + "tasksetOperations": [ + { + "operationName": "ClusterCreation", + "resourceName": "demo-eks-graviton", + "operationStatus": "PROVISION_TASK_STATUS_INPROGRESS" + }, + { + "operationName": "NodegroupCreation", + "resourceName": "graviton", + "operationStatus": "PROVISION_TASK_STATUS_PENDING" + }, + { + "operationName": "BlueprintSync", + "resourceName": "demo-eks-graviton", + "operationStatus": "PROVISION_TASK_STATUS_PENDING" + } + ], + "tasksetStatus": "PROVISION_TASKSET_STATUS_INPROGRESS", + "comments": "Configuration is being applied to the cluster" + } +] +``` + +## Monitor cluster provisioning + +Poll the cluster status until it reports `READY`. Provisioning typically takes 15–20 minutes as Rafay creates the VPC, EKS control plane, and managed node group. + +```console +rctl get cluster demo-eks-graviton +``` + +The output is similar to: + +```output ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +| NAME | CREATED AT | TYPE | STATUS | BLUEPRINT | PROVISION STATUS | ENVIRONMENT CREATED | ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +| demo-eks-graviton | 2026-06-24T15:32:19.936269Z | aws-eks | NOT_READY | minimal | INFRA_CREATION_INPROGRESS | false | ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +``` + +While waiting, you can run the command again every few minutes. You will see various status values before the status changes to `READY`. You can also check the AWS CloudFormation console to see project and look for any stack errors. + +## Download the kubeconfig + +Once the cluster is `READY`, download the kubeconfig file: + +```console +rctl kubeconfig download --cluster demo-eks-graviton -f ~/.kube/demo-eks-graviton.kubeconfig +``` + +The output is similar to: + +```output +kubeconfig downloaded to ~/.kube/demo-eks-graviton.kubeconfig +``` + +Export the path so that `kubectl` uses this cluster: + +```console +export KUBECONFIG=~/.kube/demo-eks-graviton.kubeconfig +``` + +## Verify the nodes + +Confirm that the cluster has a running node and that it reports the `arm64` architecture: + +```console +kubectl get nodes -L kubernetes.io/arch +``` + +The output is similar to: + +```output +NAME STATUS ROLES AGE VERSION ARCH +ip-192-168-13-74.ec2.internal Ready 26m v1.36.2-eks-93b80c6 arm64 +``` + +The `arm64` value in the `ARCH` column confirms that the node is running on an AWS Graviton instance. Your EKS cluster is ready to accept workloads. In the next section, you will deploy NGINX to this cluster and verify it runs on the Graviton node. diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp b/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp new file mode 100644 index 0000000000..b9dd2a8265 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp differ diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md new file mode 100644 index 0000000000..6f1c2cbba1 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md @@ -0,0 +1,169 @@ +--- +title: "Deploy NGINX and clean up" +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +With the cluster running, you can now validate it by deploying a workload. In this section, you deploy NGINX using a manifest that pins pods to `arm64` nodes, verify the pod reaches a `Running` state, and test connectivity from inside the cluster. You then clean up all provisioned resources. + +## Deploy NGINX + +With the EKS cluster running on Graviton nodes, deploy NGINX to confirm that arm64 workloads schedule and run correctly. + +Create a file named `nginx-graviton.yaml` with the following content: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: nginx +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-arm-deployment + namespace: nginx +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-arm + template: + metadata: + labels: + app: nginx-arm + spec: + nodeSelector: + kubernetes.io/arch: arm64 # Pin pods to Graviton (arm64) nodes + containers: + - name: nginx + image: nginx:1.27 + ports: + - containerPort: 80 +--- +apiVersion: v1 +kind: Service +metadata: + name: nginx-arm-svc + namespace: nginx +spec: + selector: + app: nginx-arm + ports: + - protocol: TCP + port: 80 + targetPort: 80 + type: ClusterIP +``` + +The `nodeSelector: kubernetes.io/arch: arm64` field ensures the pod is scheduled only on nodes that report the `arm64` architecture label. The Graviton node you provisioned has this label. + +Apply the manifest: + +```console +kubectl apply -f nginx-graviton.yaml +``` + +The output is similar to: + +```output +namespace/nginx created +deployment.apps/nginx-arm-deployment created +service/nginx-arm-svc created +``` + +## Verify the deployment + +Check that the pod reaches the `Running` state: + +```console +kubectl get pods -n nginx +``` + +The output is similar to: + +```output +NAME READY STATUS RESTARTS AGE +nginx-arm-deployment-6d4f9b8c7d-xk2pq 1/1 Running 0 30s +``` + +Confirm the service was created: + +```console +kubectl get svc -n nginx +``` + +The output is similar to: + +```output +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx-arm-svc ClusterIP 10.100.42.137 80/TCP 30s +``` + +## Test NGINX connectivity + +The NGINX service is type `ClusterIP`, which means it has no external IP and is only reachable from within the cluster network. The cluster also has `publicAccess: false`, so there is no public Kubernetes API endpoint. Both constraints mean you cannot test connectivity from your laptop directly. Instead, run a one-off pod inside the cluster that sends a request to the service and then deletes itself: + +```console +kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- curl http://nginx-arm-svc.nginx.svc +``` + +The output is similar to: + +```output + + + +Welcome to nginx! + + +

Welcome to nginx!

+

If you see this page, the nginx web server is successfully installed and +working. Further configuration is required.

+ + +pod "curl-test" deleted +``` + +The NGINX welcome page confirms that the workload is running and reachable on your Graviton-backed EKS cluster. + +## Clean up + +Remove the NGINX workload and then delete the cluster to avoid ongoing AWS charges. + +Delete the NGINX resources: + +```console +kubectl delete -f nginx-graviton.yaml +``` + +The output is similar to: + +```output +namespace "nginx" deleted +deployment.apps "nginx-arm-deployment" deleted +service "nginx-arm-svc" deleted +``` + +{{< notice warning >}} +Deleting the cluster through RCTL triggers the removal of the EKS control plane, managed node group, and associated CloudFormation stacks in your AWS account. If you do not run this command, AWS will continue to charge you for the running EC2 instances and EKS control plane. +{{< /notice >}} + +Delete the EKS cluster through Rafay: + +```console +rctl delete cluster demo-eks-graviton +``` + +## Summary + +In this Learning Path you: + +- Connected your AWS account to the Rafay platform using a cross-account IAM role and cloud credential. +- Provisioned a private Amazon EKS cluster with a Graviton (`m7g.large`) node group using a declarative Rafay manifest and `rctl`. +- Deployed NGINX with a `nodeSelector` that pins workloads to `arm64` nodes, confirming that Arm-native containers schedule and run correctly. +- Tested in-cluster connectivity using a one-off curl pod, and cleaned up all AWS and Rafay resources. + +Rafay's control plane handles cluster access without requiring a public Kubernetes API endpoint, making it straightforward to run private, Graviton-backed EKS clusters at scale. diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md new file mode 100644 index 0000000000..981e9eed12 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md @@ -0,0 +1,441 @@ +--- +title: "Set up your environment" +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Before you begin + +[Rafay](https://rafay.co) is a Kubernetes operations platform that provisions, secures, and manages the full cluster lifecycle across public cloud, private, and hybrid environments. It provides a single control plane for fleet-wide operations including automated provisioning, upgrades, and governance. You can use Rafay to provision an Amazon EKS cluster with an Arm Graviton node group and deploy a workload to verify the setup. + +You need the following accounts and tools before starting this Learning Path: + +- An [AWS account](https://aws.amazon.com/) with sufficient IAM permissions to create roles, EKS clusters, EC2 instances, CloudFormation stacks, and related resources. +- A [Rafay account](https://console.rafay.dev). You can [sign up](https://console.rafay.dev/#/signup) if you do not have an account. +- The AWS CLI installed and configured with credentials that have the required permissions. + +Confirm your AWS CLI is working by running the following command, which prints your account and user information: + +```console +aws sts get-caller-identity +``` + +## Install kubectl + +Install the Kubernetes command-line tool, by following the [kubectl install guide](/install-guides/kubectl/). + +Confirm the installation: + +```console +kubectl version --client +``` + +The output is similar to: + +```output +Client Version: v1.32.1 +Kustomize Version: v5.5.0 +``` + +## Install RCTL + +RCTL is the Rafay CLI. You use it to submit cluster manifests, check cluster status, download kubeconfig files, and delete clusters. + +To download RCTL, log in to the Rafay console, navigate to **My Tools** > **Download CLI**, and download the binary for your operating system. + +The downloads are `.tar.bz2` files. + +On macOS with Apple Silicon extract the file with: + +```console +tar xvf rctl-darwin-arm64.tar.bz2 +``` + +On Arm Linux, use the filename: + +```console +tar xvf rctl-linux-arm64.tar.bz2 +``` + +{{% notice Note %}} +RCTL is also available for x86_64 Linux and Windows. Modify the filename to match your platform as needed. +{{% /notice %}} + +Move the binary to a directory in your search path: + +```console +sudo mv rctl /usr/local/bin/ +``` + +## Configure RCTL + +Download the RCTL configuration file from the Rafay console. Navigate to **My Tools** > **Download CLI Config** and save the file. + +The file name is formatted for your user information. + +Copy the downloaded file to a known location and initialize `rctl` with it: + +```console +cp ~/Downloads/.json ~/rafay-config.json +rctl config init ~/rafay-config.json +``` + +The config command doesn't have any output. + +Verify the installation: + +```console +rctl version +``` + +The output is similar to: + +```output +VERSION: r4.2.0 +BUILD: r4.2.0-1 +BUILD-TIME: Thu 04 Jun 2026 07:17:05 AM UTC +ARCH: darwin/arm64 +``` + +Confirm that `rctl` can reach the Rafay platform: + +```console +rctl config show +``` + +The output lists your account information, including the endpoints, keys, project, and organization information. + +## Create an AWS IAM role for Rafay + +Rafay provisions EKS resources in your AWS account using a cross-account IAM role. You need two values from the Rafay console before running the script: + +1. Log in to the Rafay console +2. Select **defaultproject** (or another project) from the project selector in the top navigation bar +3. Navigate to **Infrastructure** > **Cloud Credentials** > **New Credential**. +4. Select **AWS** as the provider select **ROLE**. Copy the **Rafay Account ID** and **External ID** displayed on the screen. You will pass these values to the script below. + +Save the following script as `create-rafay-role.sh`: + +```bash +#!/bin/bash +set -euo pipefail + +read -rp "Enter Rafay Account ID: " RAFAY_ACCOUNT_ID +read -rp "Enter External ID: " EXTERNAL_ID + +ROLE_NAME="RafayEKSProvisioner" +REGION="us-east-1" + +TRUST_POLICY=$(cat < **Cloud Credentials** > **New Credential** in the Rafay console +2. Paste the Role ARN into the **Role ARN** field. +4. Enter `aws-cloud-credential` as the credential name. +5. Click **Save**. + +![Screenshot of the Rafay console showing the cloud credential registration form with the AWS Role ARN field filled in #center](images/rafay-cloud-credential.webp "Registered AWS cloud credential in the Rafay console") + +You now have `kubectl` and `rctl` installed, `rctl` authenticated to Rafay, and an AWS cloud credential registered. You are ready to create the EKS cluster.