AWS eks medium security documentation change
Summary
Restructured documentation to add prerequisites, IAM role creation steps, EKS add-on installation guidance, and performance tuning section. Updated requirements for eksctl version and added EKS Pod Identity agent requirement.
Security assessment
Added explicit requirement for EKS Pod Identity agent to prevent authentication failures ('Amazon EKS Pod Identity agent is not installed' error). This addresses a potential misconfiguration that could prevent CSI driver from functioning securely. Added IAM role creation steps with security note about blocking IMDS access, which relates to security best practices for pod identity management.
Diff
diff --git a/eks/latest/userguide/fsx-csi-create.md b/eks/latest/userguide/fsx-csi-create.md index 8261ac1c1..9855ab922 100644 --- a//eks/latest/userguide/fsx-csi-create.md +++ b//eks/latest/userguide/fsx-csi-create.md @@ -5 +5 @@ -Step 1: Deploy the FSx for Lustre CSI driverStep 2: Deploy a storage class, persistent volume claim, and sample app +PrerequisitesStep 1: Create an IAM roleStep 2: Install the Amazon FSx CSI driverStep 3: Deploy a storage class, persistent volume claim, and sample appPerformance tuning for FSx for Lustre @@ -21 +21 @@ For detailed descriptions of the available parameters and complete examples that -You must have: +## Prerequisites @@ -23,3 +23 @@ You must have: - * Version `2.12.3` or later or version `1.27.160` or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use `aws --version | cut -d / -f2 | cut -d ' ' -f1`. Package managers such `yum`, `apt-get`, or Homebrew for macOS are often several versions behind the latest version of the AWS CLI. To install the latest version, see [Installing](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Quick configuration with aws configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) in the _AWS Command Line Interface User Guide_. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see [Installing AWS CLI to your home directory](https://docs.aws.amazon.com/cloudshell/latest/userguide/vm-specs.html#install-cli-software) in the _AWS CloudShell User Guide_. - - * Version `0.207.0` or later of the `eksctl` command line tool installed on your device or AWS CloudShell. To install or update `eksctl`, see [Installation](https://eksctl.io/installation) in the `eksctl` documentation. + * An existing cluster. @@ -27 +25 @@ You must have: - * The `kubectl` command line tool is installed on your device or AWS CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is `1.29`, you can use `kubectl` version `1.28`, `1.29`, or `1.30` with it. To install or upgrade `kubectl`, see [Set up kubectl and eksctl](./install-kubectl.html). + * The Amazon FSx CSI Driver EKS add-on requires the EKS Pod Identity agent for authentication. Without this component, the add-on will fail with the error `Amazon EKS Pod Identity agent is not installed in the cluster`, preventing volume operations. Install the Pod Identity agent before or after deploying the FSx CSI Driver add-on. For more information, see [Set up the Amazon EKS Pod Identity Agent](./pod-id-agent-setup.html). @@ -28,0 +27 @@ You must have: + * Version `2.12.3` or later or version `1.27.160` or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use `aws --version | cut -d / -f2 | cut -d ' ' -f1`. Package managers such `yum`, `apt-get`, or Homebrew for macOS are often several versions behind the latest version of the AWS CLI. To install the latest version, see [Installing](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Quick configuration with aws configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) in the _AWS Command Line Interface User Guide_. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see [Installing AWS CLI to your home directory](https://docs.aws.amazon.com/cloudshell/latest/userguide/vm-specs.html#install-cli-software) in the _AWS CloudShell User Guide_. @@ -29,0 +29 @@ You must have: + * Version `0.208.0` or later of the `eksctl` command line tool installed on your device or AWS CloudShell. To install or update `eksctl`, see [Installation](https://eksctl.io/installation) in the `eksctl` documentation. @@ -30,0 +31 @@ You must have: + * The `kubectl` command line tool is installed on your device or AWS CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is `1.29`, you can use `kubectl` version `1.28`, `1.29`, or `1.30` with it. To install or upgrade `kubectl`, see [Set up kubectl and eksctl](./install-kubectl.html). @@ -32 +32,0 @@ You must have: -The following procedures help you create a simple test cluster with the FSx for Lustre CSI driver so that you can see how it works. We don’t recommend using the testing cluster for production workloads. For this tutorial, we recommend using the `example values`, except where it’s noted to replace them. You can replace any `example value` when completing the steps for your production cluster. We recommend completing all steps in the same terminal because variables are set and used throughout the steps and won’t exist in different terminals. @@ -34 +33,0 @@ The following procedures help you create a simple test cluster with the FSx for -## Step 1: Deploy the FSx for Lustre CSI driver @@ -36 +34,0 @@ The following procedures help you create a simple test cluster with the FSx for - 1. Set a few variables to use in the remaining steps. Replace `my-csi-fsx-cluster` with the name of the test cluster you want to create and `region-code` with the AWS Region that you want to create your test cluster in. @@ -38,2 +36 @@ The following procedures help you create a simple test cluster with the FSx for - export cluster_name=my-csi-fsx-cluster - export region_code=region-code +## Step 1: Create an IAM role @@ -41 +38 @@ The following procedures help you create a simple test cluster with the FSx for - 2. Create a test cluster. +The Amazon FSx CSI plugin requires IAM permissions to make calls to AWS APIs on your behalf. @@ -43,6 +40 @@ The following procedures help you create a simple test cluster with the FSx for - eksctl create cluster \ - --name $cluster_name \ - --region $region_code \ - --with-oidc \ - --ssh-access \ - --ssh-public-key my-key +###### Note @@ -50 +42 @@ The following procedures help you create a simple test cluster with the FSx for -Cluster provisioning takes several minutes. During cluster creation, you’ll see several lines of output. The last line of output is similar to the following example line. +Pods will have access to the permissions that are assigned to the IAM role unless you block access to IMDS. For more information, see [Secure Amazon EKS clusters with best practices](./security-best-practices.html). @@ -52 +44 @@ Cluster provisioning takes several minutes. During cluster creation, you’ll se - [✓] EKS cluster "my-csi-fsx-cluster" in "region-code" region is ready +The following procedure shows you how to create an IAM role and attach the AWS managed policy to it. @@ -54 +46 @@ Cluster provisioning takes several minutes. During cluster creation, you’ll se - 3. Create a Kubernetes service account for the driver and attach the `AmazonFSxFullAccess` AWS-managed policy to the service account with the following command. + 1. Create an IAM role and attach the AWS managed policy with the following command. Replace `my-cluster` with the name of the cluster you want to use. The command deploys an AWS CloudFormation stack that creates an IAM role and attaches the IAM policy to it. @@ -59 +51,3 @@ Cluster provisioning takes several minutes. During cluster creation, you’ll se - --cluster $cluster_name \ + --cluster my-cluster \ + --role-name AmazonEKS_FSx_CSI_DriverRole \ + --role-only \ @@ -61,3 +55 @@ Cluster provisioning takes several minutes. During cluster creation, you’ll se - --approve \ - --role-name AmazonEKSFSxLustreCSIDriverFullAccess \ - --region $region_code + --approve @@ -72,3 +64,3 @@ You’ll see several lines of output as the service account is created. The last - [ℹ] building iamserviceaccount stack "eksctl-my-csi-fsx-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" - [ℹ] deploying stack "eksctl-my-csi-fsx-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" - [ℹ] waiting for CloudFormation stack "eksctl-my-csi-fsx-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" + [ℹ] building iamserviceaccount stack "eksctl-my-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" + [ℹ] deploying stack "eksctl-my-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" + [ℹ] waiting for CloudFormation stack "eksctl-my-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa" @@ -77,3 +69 @@ You’ll see several lines of output as the service account is created. The last -Note the name of the AWS CloudFormation stack that was deployed. In the previous example output, the stack is named `eksctl-my-csi-fsx-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa`. - - 4. Deploy the driver with the following command. Replace `release-X.XX` with your desired branch. The master branch isn’t supported because it may contain upcoming features incompatible with the currently released stable version of the driver. We recommend using the latest released version. For a list of branches, see `aws-fsx-csi-driver` [Branches](https://github.com/kubernetes-sigs/aws-fsx-csi-driver/branches/all) on GitHub. +Note the name of the AWS CloudFormation stack that was deployed. In the previous example output, the stack is named `eksctl-my-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa`. @@ -81 +70,0 @@ Note the name of the AWS CloudFormation stack that was deployed. In the previous -###### Note @@ -83 +71,0 @@ Note the name of the AWS CloudFormation stack that was deployed. In the previous -You can view the content being applied in [aws-fsx-csi-driver/deploy/kubernetes/overlays/stable](https://github.com/kubernetes-sigs/aws-fsx-csi-driver/tree/master/deploy/kubernetes/overlays/stable) on GitHub. @@ -85 +72,0 @@ You can view the content being applied in [aws-fsx-csi-driver/deploy/kubernetes/ - kubectl apply -k "github.com/kubernetes-sigs/aws-fsx-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-X.XX" @@ -87 +74 @@ You can view the content being applied in [aws-fsx-csi-driver/deploy/kubernetes/ -An example output is as follows. +Now that you have created the Amazon FSx CSI driver IAM role, you can continue to the next section. When you deploy the add-on with this IAM role, it creates and is configured to use a service account that’s named `fsx-csi-controller-sa`. The service account is bound to a Kubernetes `clusterrole` that’s assigned the required Kubernetes permissions. @@ -89,9 +76 @@ An example output is as follows. - serviceaccount/fsx-csi-controller-sa created - serviceaccount/fsx-csi-node-sa created - clusterrole.rbac.authorization.k8s.io/fsx-csi-external-provisioner-role created - clusterrole.rbac.authorization.k8s.io/fsx-external-resizer-role created - clusterrolebinding.rbac.authorization.k8s.io/fsx-csi-external-provisioner-binding created - clusterrolebinding.rbac.authorization.k8s.io/fsx-csi-resizer-binding created - deployment.apps/fsx-csi-controller created - daemonset.apps/fsx-csi-node created - csidriver.storage.k8s.io/fsx.csi.aws.com created +## Step 2: Install the Amazon FSx CSI driver @@ -99 +78 @@ An example output is as follows. - 5. Note the ARN for the role that was created. If you didn’t note it earlier and don’t have it available anymore in the AWS CLI output, you can do the following to see it in the AWS Management Console. +We recommend that you install the Amazon FSx CSI driver through the Amazon EKS add-on to improve security and reduce the amount of work. To add an Amazon EKS add-on to your cluster, see [Create an Amazon EKS add-on](./creating-an-add-on.html). For more information about add-ons, see [Amazon EKS add-ons](./eks-add-ons.html). @@ -101 +80 @@ An example output is as follows. - 1. Open the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation/). +###### Important @@ -103 +82 @@ An example output is as follows. - 2. Ensure that the console is set to the AWS Region that you created your IAM role in and then select **Stacks**. +Pre-existing Amazon FSx CSI driver installations in the cluster can cause add-on installation failures. When you attempt to install the Amazon EKS add-on version while a non-EKS FSx CSI Driver exists, the installation will fail due to resource conflicts. Use the `OVERWRITE` flag during installation to resolve this issue. @@ -105 +83,0 @@ An example output is as follows. - 3. Select the stack named `eksctl-my-csi-fsx-cluster-addon-iamserviceaccount-kube-system-fsx-csi-controller-sa`. @@ -107 +85 @@ An example output is as follows. - 4. Select the **Outputs** tab. The **Role1** ARN is listed on the **Outputs (1)** page. + aws eks create-addon --addon-name aws-fsx-csi-driver --cluster-name my-cluster --resolve-conflicts OVERWRITE @@ -109 +87 @@ An example output is as follows. - 6. Patch the driver deployment to add the service account that you created earlier with the following command. Replace the ARN with the ARN that you noted. Replace `111122223333` with your account ID. +Alternatively, if you want a self-managed installation of the Amazon FSx CSI driver, see [Installation](https://github.com/kubernetes-sigs/aws-fsx-csi-driver/blob/master/docs/install.md) on GitHub. @@ -111,11 +89 @@ An example output is as follows. - kubectl annotate serviceaccount -n kube-system fsx-csi-controller-sa \ - eks.amazonaws.com/role-arn=arn:aws:iam::111122223333:role/AmazonEKSFSxLustreCSIDriverFullAccess --overwrite=true - -An example output is as follows. - - serviceaccount/fsx-csi-controller-sa annotated - - - - -## Step 2: Deploy a storage class, persistent volume claim, and sample app +## Step 3: Deploy a storage class, persistent volume claim, and sample app @@ -125 +93 @@ This procedure uses the [FSx for Lustre Container Storage Interface (CSI) driver - 1. Note the security group for your cluster. You can see it in the AWS Management Console under the **Networking** section or by using the following AWS CLI command. + 1. Note the security group for your cluster. You can see it in the AWS Management Console under the **Networking** section or by using the following AWS CLI command. Replace `my-cluster` with the name of the cluster you want to use. @@ -127 +95 @@ This procedure uses the [FSx for Lustre Container Storage Interface (CSI) driver - aws eks describe-cluster --name $cluster_name --query cluster.resourcesVpcConfig.clusterSecurityGroupId + aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.clusterSecurityGroupId @@ -135 +103 @@ This procedure uses the [FSx for Lustre Container Storage Interface (CSI) driver - 4. Edit the parameters section of the `storageclass.yaml` file. Replace every `example value` with your own values. + 4. Edit the parameters section of the `storageclass.yaml` file. Replace every example value with your own values. @@ -251,0 +220,28 @@ Before deleting the cluster, make sure to delete the FSx for Lustre file system. +## Performance tuning for FSx for Lustre + +When using FSx for Lustre with Amazon EKS, you can optimize performance by applying Lustre tunings during node initialization. The recommended approach is to use launch template user data to ensure consistent configuration across all nodes. + +These tunings include: + + * Network and RPC optimizations + + * Lustre module management + + * LRU (Lock Resource Unit) tunings + + * Client cache control settings + + * RPC controls for OST and MDC + + + + +For detailed instructions on implementing these performance tunings: + + * For optimizing performance for standard nodes (non-EFA), see [Optimize Amazon FSx for Lustre performance on nodes (non-EFA)](./fsx-csi-tuning-non-efa.html) for a complete script that can be added to your launch template user data. + + * For optimizing performance for EFA-enabled nodes, see [Optimize Amazon FSx for Lustre performance on nodes (EFA)](./fsx-csi-tuning-efa.html). + + + +