Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: EKS cluster and EKS hybrid requirements #5661

Merged
merged 12 commits into from
Feb 6, 2025
16 changes: 15 additions & 1 deletion docs/docs-content/clusters/public-cloud/aws/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The following are some architectural highlights of the Amazon Web Services (AWS)
- The Kubernetes API Server endpoint is accessible through an Elastic Load Balancing (ELB), which load balances across
all the control plane nodes.

![A diagram of AWS architecture](/clusters_aws_architecture_aws_cluster_architecture.webp)
![A diagram of AWS architecture](/clusters_aws_architecture_aws_cluster_architecture.webp)

## AWS EKS Architecture

Expand All @@ -44,6 +44,20 @@ highlights pertaining to EKS when managed by Palette.

![eks_cluster_architecture.webp](/clusters_aws_create-and-manage-aws-eks-cluster_architecture.webp)

### Worker Node Requirements

Your Amazon EKS cluster must include at least one worker node to host the Palette agent, which is essential for Palette
to manage the cluster. Due to EKS architectural constraints, the Palette agent cannot be installed on the EKS control
plane.

- **Minimum Instance Type**: Worker nodes must use an instance type of at least **t3.xlarge** to ensure adequate
resources. AWS sets a default storage of 20 GB for Linux-based EKS worker nodes (the
[diskSize](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateNodegroup.html#API_CreateNodegroup_RequestSyntax)
parameter), and we recommend this as the minimum size.

- **Ongoing Node Availability**: To maintain continuous management capabilities, at least one worker node should remain
available at all times for the Palette agent to operate effectively.

### Disable OIDC Associate Provider

You can disable the OIDC associate provider if the service provider restricts the cluster deployment with the OIDC
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -189,3 +189,24 @@ Palette supports the following authentication methods for your hybrid nodes:
Refer to
[Prepare credentials for hybrid nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-creds.html) for
guidance on how to set up credentials for your hybrid nodes.

## Amazon EKS Cluster Requirements

- **Hybrid Node Enablement**: The cluster must be enabled for hybrid nodes, as outlined in
[Create an Amazon EKS cluster with hybrid nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-cluster-create.html).

- **Container Network Interface (CNI)**: The **AWS VPC CNI** must be used as the cluster’s CNI as it is needed for cloud
worker nodes to function. Although the AWS Console may display a warning indicating that the AWS VPC CNI is not
supported for hybrid nodes, this can be safely disregarded.

- **Worker Node Requirements for the Palette Agent**: At least one worker node is required to host the Palette agent,
which is essential for Palette to manage the cluster. Due to EKS architectural constraints, the Palette agent cannot
be installed on the EKS control plane.

- **Minimum Instance Type**: Worker nodes must use an instance type of at least **t3.xlarge** to ensure adequate
resources. AWS sets a default storage of 20 GB for Linux-based EKS worker nodes (the
[diskSize](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateNodegroup.html#API_CreateNodegroup_RequestSyntax)
parameter), and we recommend this as the minimum size.

- **Ongoing Node Availability**: To maintain continuous management capabilities, at least one worker node should
remain available at all times for the Palette agent to operate effectively.
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,15 @@ Import your Amazon EKS cluster and enable hybrid mode to be able to create edge
[Create an Amazon EKS cluster with hybrid nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-cluster-create.html)
for guidance.

- When selecting add-ons, you must use **AWS VPC CNI** as your container network interface as it is needed for cloud
worker nodes to function. If you are deploying through the AWS Console, a warning may state that AWS VPC CNI is not
supported for hybrid nodes. You can ignore this message.
- Your Amazon EKS cluster must include at least one worker node to host the Palette agent, which is necessary for
Palette to manage the cluster. Because of EKS architecture constraints, the agent cannot be installed on the control
plane.
- The minimum instance type required is **t3.xlarge** with at least 20 GB of storage.
- Be sure at least one worker node is always available so Palette can continue managing the cluster.
addetz marked this conversation as resolved.
Show resolved Hide resolved

- A Hybrid Nodes IAM Role with the required Kubernetes permissions to join your Amazon EKS cluster. Refer to
[Prepare cluster access for hybrid nodes](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-cluster-prep.html)
for guidance.
Expand Down Expand Up @@ -362,7 +371,7 @@ Cilium handles IP Address Management (IPAM) and Border Gateway Protocol (BGP) fo

5. In **Profile Layers**, click **Add New Pack**.

6. Enter **Cilium** in the search box, and select it. It appears in the **System App** category and must be version
6. Enter **Cilium** in the search box, and select it. It appears in the **Network** category and must be version
**1.16.0** or above.

7. Click the **Presets drop-down Menu**.
Expand Down Expand Up @@ -399,7 +408,7 @@ Cilium handles IP Address Management (IPAM) and Border Gateway Protocol (BGP) fo

:::info

The Cilium [Daemonset](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) is configured to
The Cilium [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) is configured to
operate on your hybrid nodes only. If no hybrid nodes are present in your cluster, the DaemonSet will remain
inactive.

Expand All @@ -413,7 +422,7 @@ Cilium handles IP Address Management (IPAM) and Border Gateway Protocol (BGP) fo

15. Select your cluster to view its **Overview** tab.

16. Click **Attach Profile**.
16. Select the **Profile** tab, and click **Attach Profile**.

17. Select the **Cilium** add-on profile that was created, and click **Confirm**.

Expand Down
4 changes: 4 additions & 0 deletions docs/docs-content/clusters/public-cloud/aws/eks.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ an AWS account. This section guides you on how to create an EKS cluster in AWS t
a key pair, refer to the
[Amazon EC2 key pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) resource.

- Your Amazon EKS cluster must be deployed with at least one worker node to host the Palette agent, which is necessary for Palette to manage the cluster. Because of EKS architecture constraints, the agent cannot be installed on the control plane.
- The minimum instance type required is **t3.xlarge** with at least 20 GB of storage.
- Be sure at least one worker node is always available so Palette can continue managing the cluster.

- To access your EKS cluster using kubectl, you will need the
[aws-iam-authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator) plugin installed. If you are using a
custom OIDC provider, you will need the [kubelogin](https://github.com/int128/kubelogin) plugin installed. Refer to
Expand Down