Docs

Volcengine Kubernetes Engine

FSX client

Using IRSA to implement authentication for storage mounting

The csi-fsx add-on supports authentication with IAM roles for service accounts (IRSA). IRSA authentication enables permission isolation for cloud storage among IAM roles, which reduces security risks. This topic describes the steps of implementing storage mount authentication based on IRSA.

Background information

IRSA is a security mechanism that allows applications in a VKE cluster to use Volcano Engine IAM roles through Kubernetes service accounts. The IRSA mechanism associates a specific IAM role with a service account. This enables pods running in a VKE cluster to obtain the permissions granted to the role through the service account. In this way, the pods can access corresponding cloud service resources. For more details, see IRSA overview.

Limits

Currently, IRSA authentication is available only for mounting Torch Object Storage (TOS).

Prerequisites

A cluster has been created, and IRSA authentication has been enabled. For details, see Using IRSA in clusters.

An IAM role of the OIDC identity provider type has been created. For details, see Using IRSA in clusters.

warning

IRSA authentication can be enabled only after the cluster is created. To use the IRSA authentication capability of the csi-fsx add-on, do not install this add-on when creating the cluster.

After IRSA authentication is enabled for the csi-fsx add-on, you cannot directly switch to a different authentication method. To use another authentication method, uninstall the existing add-on and install it again.

Procedure

warning

Strictly follow the steps provided in this topic. Otherwise the required role is unavailable for enabling IRSA authentication for the csi-fsx add-on or the storage mount will fail due to incorrect role configuration.

Step 1: Configure a custom permission policy

In the left navigation bar, click Permissions policy. On the page that appears, click Create Policy.

Click JSON editor to configure a minimal permission policy for cloud storage. This example uses TOS.

Description

The Action field defines the operations included in the policy. When you configure this field, follow the principle of least privilege. For details, see TOS configuration and mounting.

Step 2: Configure a role trust relationship

Before configuring IRSA authentication for the csi-fsx add-on and selecting an IAM role, you must first configure role trust.

In the left navigation bar, click Role management. In the role list, find the IAM role of the OIDC identity provider type that has been created.

Click the role name to go to the details page of the role. Configure a trust relationship for the role.

Configure role permissions: On the Policy tab, click Authorize, and select the configured permission policy.

Configure a trust relationship: Click the Trust relationship tab and click Edit trust policy. In the Statement field, add the following content.

The complete code example is as follows:

tip

After you enable the IRSA capability for the cluster, you can obtain the Provider URL on the cluster overview page. For details, see Using IRSA in clusters.

The {serviceaccount} and {namespace} attributes of the csi-fsx add-on within the cluster can be obtained during installation of the csi-fsx add-on. For details, see Step 3.

Step 3: Install the csi-fsx add-on

In the left navigation bar of the cluster management page, click Addons.

On the Addons page, click the Storage tab. Then, move the pointer over the csi-fsx add-on card and click Deploy.

Select the Service account IAM Role (IRSA) check box to enable IRSA authentication and choose an IAM role.

Note

IRSA authentication cannot be used when IRSA OIDC is not enabled.

The IAM role must fall within the OIDC identity provider type and have a trust relationship bound to the service account of the add-on.

After the csi-fsx add-on is installed, you cannot change the authentication method. However, you can change the IAM role. The change applies only to a new PersistentVolume (PV), without affecting existing PVs. Additionally, note that changing IAM roles will trigger a brief restart of the add-on. We recommend that you perform this operation during off-peak hours.

Step 4: Create a PV

After you configure the IAM role trust relationship and install the csi-fsx add-on, the PV in the cluster can use IRSA for authentication.

In the left navigation bar on the cluster management page, click Storage > PersistentVolume.

In the upper left corner of the PersistentVolume list, click Create PersistentVolume.

On the Create PersistentVolume page, select TOS for StorageClass type and FSX for Access type. The system automatically detects the IRSA authentication configuration of the csi-fsx add-on.

Configure access key authentication. If independent access key authentication is not required, use IRSA authentication.

What to do next

After the PV is created, you can add the corresponding volume when creating a workload and mount the storage in the pod to use the PV. For details, see the FSX user guide for a specific storage service.

Last updated: 2026.07.24 10:53:33