Stay organized with collections
Save and categorize content based on your preferences.
Use an Azure File share
GKE on Azure supports mounting
Azure Files
shares. If you already have an Azure File share to use with
GKE on Azure, you can create a PersistentVolume (PV) object and
reserve it for a specific PersistentVolumeClaim (PVC).
This page explains how to create a PV by using an existing share
populated with data, and how to use the PV in a Pod.
GKE on Azure stores information to access your Azure storage account
in a Secret. If you haven't created a Secret in your cluster, you must add one.
If you have this Secret in you cluster, skip to
Create a PersistentVolume for a pre-existing share.
To create the Secret, copy the following manifest into a file named
'azure-service-account-key.yaml'.
VOLUME_CAPACITY: size of the volume. For example, 30Gi.
For more information on specifying volume capacity in Kubernetes, see the
Meaning of memory.
VOLUME_ID: a unique ID for the volume, formatted as a string
of
RESOURCE_GROUP_NAME#STORAGE_ACCOUNT_NAME#FILESHARE_NAME#
where
FILE_SHARE_NAME: the Azure File share name
If your storage account is in a different resource group than your
cluster, you need to add a reference to a Secret that contains your
storage account key. To add the reference, insert the following in the
spec.csi section:
# Optional. Only required if your storageAccount is in a different resource group than the cluster.nodeStageSecretRef:name:NODE_STAGE_SECRET_NAMEnamespace:NODE_STAGE_SECRET_NAMESPACE
Replace the following:
NODE_STAGE_SECRET_NAME: the name of the Secret
NODE_STAGE_SECRET_NAMESPACE the Namespace that contains the
Secret
Apply the YAML to your cluster.
kubectlapply-fexisting-volume.yaml
Confirm the creation of your PV with kubectl describe pv.
kubectldescribepvVOLUME_NAME
The output of this command contains the status of the PV.
Use the volume with a PersistentVolumeClaim and Pod
After you have imported your volume, you can create a PVC and a Pod that
mounts the PVC.
The following YAML creates a PVC and attaches it to a Pod running the Nginx web
server. Copy it into a file named nginx.yaml:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Use an Azure File share\n=======================\n\nGKE on Azure supports mounting\n[Azure Files](https://azure.microsoft.com/en-us/services/storage/files/#documentation)\nshares. If you already have an Azure File share to use with\nGKE on Azure, you can create a PersistentVolume (PV) object and\nreserve it for a specific PersistentVolumeClaim (PVC).\n\nThis page explains how to create a PV by using an existing share\npopulated with data, and how to use the PV in a Pod.\n\nBefore you begin\n----------------\n\n- [Connect to your cluster](/kubernetes-engine/multi-cloud/docs/azure/how-to/connect-and-authenticate-to-your-cluster)\n- Have access to or create an Azure File share. For more information, see [Create an Azure file share](https://docs.microsoft.com/en-us/azure/storage/files/storage-how-to-create-file-share?tabs=azure-portal).\n\nStore your Azure storage account information\n--------------------------------------------\n\nGKE on Azure stores information to access your Azure storage account\nin a Secret. If you haven't created a Secret in your cluster, you must add one.\nIf you have this Secret in you cluster, skip to\n[Create a PersistentVolume for a pre-existing share](#create).\n\n1. To create the Secret, copy the following manifest into a file named\n 'azure-service-account-key.yaml'.\n\n ---\n apiVersion: v1\n kind: Secret\n metadata:\n name: azure-secret-account-key\n type: Opaque\n stringData:\n accountname: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSTORAGE_ACCOUNT_NAME\u003c/span\u003e\u003c/var\u003e\n accountkey: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSTORAGE_ACCOUNT_KEY\u003c/span\u003e\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSTORAGE_ACCOUNT_NAME\u003c/var\u003e: your Azure storage account name\n - \u003cvar translate=\"no\"\u003eSTORAGE_ACCOUNT_KEY\u003c/var\u003e: your Azure storage account key\n2. Apply the file to your cluster with the `kubectl` tool:\n\n kubectl apply -f azure-service-account-key.yaml\n\nCreate a PersistentVolume for a pre-existing share\n--------------------------------------------------\n\nYou import an existing Azure File share by specifying a new PV in your cluster.\nTo create the PV, do the following:\n\n1. Copy the following YAML into a file named `existing-volume.yaml`:\n\n apiVersion: v1\n kind: PersistentVolume\n metadata:\n name: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eVOLUME_NAME\u003c/span\u003e\u003c/var\u003e\n spec:\n capacity:\n storage: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eVOLUME_CAPACITY\u003c/span\u003e\u003c/var\u003e\n storageClassName: standard-rwx\n accessModes:\n - ReadWriteMany\n persistentVolumeReclaimPolicy: Retain\n csi:\n driver: file.csi.azure.com\n readOnly: false\n volumeHandle: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eVOLUME_ID\u003c/span\u003e\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eVOLUME_NAME\u003c/var\u003e: a name for the volume\n - \u003cvar translate=\"no\"\u003eVOLUME_CAPACITY\u003c/var\u003e: size of the volume. For example, `30Gi`. For more information on specifying volume capacity in Kubernetes, see the [Meaning of memory](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory).\n - \u003cvar translate=\"no\"\u003eVOLUME_ID\u003c/var\u003e: a unique ID for the volume, formatted as a string of \u003cvar translate=\"no\"\u003eRESOURCE_GROUP_NAME\u003c/var\u003e`#`\u003cvar translate=\"no\"\u003eSTORAGE_ACCOUNT_NAME\u003c/var\u003e`#`\u003cvar translate=\"no\"\u003eFILESHARE_NAME\u003c/var\u003e`#` where\n - \u003cvar translate=\"no\"\u003eFILE_SHARE_NAME\u003c/var\u003e: the Azure File share name\n\n If your storage account is in a different resource group than your\n cluster, you need to add a reference to a Secret that contains your\n storage account key. To add the reference, insert the following in the\n `spec.csi` section: \n\n # Optional. Only required if your storageAccount is in a different resource group than the cluster.\n nodeStageSecretRef:\n name: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eNODE_STAGE_SECRET_NAME\u003c/span\u003e\u003c/var\u003e\n namespace: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eNODE_STAGE_SECRET_NAMESPACE\u003c/span\u003e\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eNODE_STAGE_SECRET_NAME\u003c/var\u003e: the name of the Secret\n - \u003cvar translate=\"no\"\u003eNODE_STAGE_SECRET_NAMESPACE\u003c/var\u003e the Namespace that contains the Secret\n2. Apply the YAML to your cluster.\n\n kubectl apply -f existing-volume.yaml\n\n3. Confirm the creation of your PV with `kubectl describe pv`.\n\n kubectl describe pv \u003cvar translate=\"no\"\u003eVOLUME_NAME\u003c/var\u003e\n\n The output of this command contains the status of the PV.\n\nUse the volume with a PersistentVolumeClaim and Pod\n---------------------------------------------------\n\nAfter you have imported your volume, you can create a PVC and a Pod that\nmounts the PVC.\n\n1. The following YAML creates a PVC and attaches it to a Pod running the Nginx web\n server. Copy it into a file named `nginx.yaml`:\n\n apiVersion: v1\n kind: PersistentVolumeClaim\n metadata:\n name: my-pvc\n spec:\n storageClassName: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSTORAGE_CLASS_NAME\u003c/span\u003e\u003c/var\u003e\n volumeName: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eVOLUME_NAME\u003c/span\u003e\u003c/var\u003e\n accessModes:\n - \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eACCESS_MODE\u003c/span\u003e\u003c/var\u003e\n resources:\n requests:\n storage: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eVOLUME_CAPACITY\u003c/span\u003e\u003c/var\u003e\n ---\n\n apiVersion: v1\n kind: Pod\n metadata:\n name: web-server\n spec:\n containers:\n - name: web-server\n image: nginx\n volumeMounts:\n - mountPath: /var/lib/www/html\n name: data\n volumes:\n - name: data\n persistentVolumeClaim:\n claimName: my-pvc\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSTORAGE_CLASS\u003c/var\u003e: the name of the StorageClass from the PersistentVolume you created previously. For example, `standard-rwo`.\n - \u003cvar translate=\"no\"\u003eACCESS_MODE\u003c/var\u003e: the access mode of the volume. For Azure Disk, use `ReadWriteOnce`. For Azure File, use `ReadWriteMany`.\n - \u003cvar translate=\"no\"\u003eVOLUME_CAPACITY\u003c/var\u003e: size of the volume. For example, `30Gi`.\n2. Apply the YAML to your cluster.\n\n kubectl apply -f nginx.yaml\n\n3. Check the status of your Nginx instance with `kubectl describe`. The output\n should have a `STATUS` of `Running`.\n\n kubectl describe pod web-server\n\n4. To delete the Pod, use the `kubectl delete` command.\n\n kubectl delete -f nginx.yaml\n\nWhat's next\n-----------\n\n- Use additional [storage drivers](/kubernetes-engine/multi-cloud/docs/azure/how-to/storage-drivers) with GKE on Azure.\n- Read the documentation for the [Azure File CSI driver](https://github.com/kubernetes-sigs/azurefile-csi-driver/tree/v1.7.0/docs)."]]