在 Azure 容器应用 中使用存储挂载

使用 Azure CLI 配置副本作用域存储时，必须通过 YAML 定义创建或更新容器应用。

1. 若要更新现有容器应用以使用副本范围的存储，请将应用的规范导出到名为 app.yaml 的 YAML 文件。

   az containerapp show -n <APP_NAME> -g <RESOURCE_GROUP_NAME> -o yaml > app.yaml
   

2. 对容器应用规范进行以下更改。

   • 将一个 volumes 数组添加到容器应用定义的 template 部分，并定义一个卷。 如果已有一个 volumes 数组，请将新卷添加到该数组。
     • name 是卷的标识符。
     • 使用 EmptyDir 作为 storageType。
   • 对于模板中每个需要装载卷的容器，请在容器定义中的 volumeMounts 数组中定义卷装载。
     • volumeName 是 volumes 数组中定义的名称。
     • mountPath 是容器中卷的装载路径。

   properties:
     managedEnvironmentId: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/managedEnvironments/<ENVIRONMENT_NAME>
     configuration:
       activeRevisionsMode: Single
     template:
       containers:
       - image: <IMAGE_NAME1>
         name: my-container-1
         volumeMounts:
         - mountPath: /myempty
           volumeName: myempty
       - image: <IMAGE_NAME_2>
         name: my-container-2
         volumeMounts:
         - mountPath: /myempty
           volumeName: myempty
       volumes:
       - name: myempty
         storageType: EmptyDir
   

3. 使用 YAML 文件更新容器应用。

   az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP_NAME> \
       --yaml app.yaml
   

有关完整示例，请参阅 YAML 规范。

若要创建副本作用域的卷并将其装载到容器中，请对 ARM 模板中的容器应用资源进行以下更改：

• 将一个 volumes 数组添加到容器应用定义的 template 部分，并定义一个卷。 如果已有一个 volumes 数组，请将新卷添加到该数组。
  • name 是卷的标识符。
  • 使用 EmptyDir 作为 storageType。
• 对于模板中每个需要装载卷的容器，请在容器定义中的 volumeMounts 数组中定义卷装载。
  • volumeName 是 volumes 数组中定义的名称。
  • mountPath 是容器中卷的装载路径。

ARM 模板代码片段示例：

{
  "apiVersion": "2022-03-01",
  "type": "Microsoft.App/containerApps",
  "name": "[parameters('containerappName')]",
  "location": "[parameters('location')]",
  "properties": {

    ...

    "template": {
      "revisionSuffix": "myrevision",
      "containers": [
        {
          "name": "main",
          "image": "[parameters('container_image')]",
          "resources": {
            "cpu": 0.5,
            "memory": "1Gi"
          },
          "volumeMounts": [
            {
              "mountPath": "/myempty",
              "volumeName": "myempty"
            }
          ]
        },
        {
          "name": "sidecar",
          "image": "[parameters('sidecar_image')]",
          "resources": {
            "cpu": 0.5,
            "memory": "1Gi"
          },
          "volumeMounts": [
            {
              "mountPath": "/myempty",
              "volumeName": "myempty"
            }
          ]
        }
      ],
      "scale": {
        "minReplicas": 1,
        "maxReplicas": 3
      },
      "volumes": [
        {
          "name": "myempty",
          "storageType": "EmptyDir"
        }
      ]
    }
  }
}

有关完整示例，请参阅 ARM 模板 API 规范。

若要创建具备副本范围的卷并将其安装到容器中，请使用 Azure 门户部署容器应用的新版本。

1. 在Azure门户中，转到容器应用。

2. 在左侧菜单中选择“修订版管理”。

3. 选择“创建新修订版”。

4. 选择要在其中装载卷的容器。

5. 在“编辑容器”上下文窗格中，选择“卷装载”选项卡。

6. 在 临时存储 部分下，创建包含以下信息的新卷：

   • 卷名称：临时卷的名称。
   • 装载路径：容器中用于装载卷的绝对路径。

7. 选择“保存”以保存更改并退出上下文窗格。

8. 选择“创建”以创建新修订版。

将容器应用配置为使用Azure CLI装载Azure 文件存储卷时，必须使用 YAML 定义来创建或更新容器应用。

安装最新的 Azure CLI 并更新 Container Apps 扩展：

az extension add --name containerapp --upgrade

有关挂载 SMB 文件共享的分步教程，请参阅 在 Azure 容器应用 中挂载 Azure 文件存储 存储。

1. 将存储定义添加到容器应用环境。

   • SMB
   • NFS

   托管身份认证（推荐）

   要使用环境的系统分配托管身份，首先启用它：

   az containerapp env identity assign --name my-env --resource-group my-group \
       --system-assigned
   

   在您的存储账户上赋予该身份“Storage File Data SMB MI Admin”角色，并按照前置条件启用 Managed Identity for SMB。 然后创建存储定义：

   az containerapp env storage set --name my-env --resource-group my-group \
       --storage-name mystorage \
       --storage-type AzureFile \
       --azure-file-account-name <STORAGE_ACCOUNT_NAME> \
       --azure-file-identity system \
       --azure-file-share-name <STORAGE_SHARE_NAME> \
       --access-mode ReadWrite
   

   用你的存储帐户名称和文件共享名称替换 <STORAGE_ACCOUNT_NAME> 和 <STORAGE_SHARE_NAME>。 该值 system 指定环境的系统分配托管标识。

   要使用用户分配的托管身份，可以将其分配给环境：

   az containerapp env identity assign --name my-env --resource-group my-group \
       --user-assigned <MANAGED_IDENTITY_RESOURCE_ID>
   

   在存储账户上赋予该身份相同的角色。 在存储命令中，将 --azure-file-identity system 替换为 --azure-file-identity <MANAGED_IDENTITY_RESOURCE_ID>，并使用该标识的完整 Azure 资源 ID，而不是其客户端 ID 或主体 ID。

   不要将 --azure-file-identity 与 --azure-file-account-key 或 --azure-file-key-vault-secret-url 组合使用。 这些认证模式是互斥的。

   存储账户密钥认证（替代方案）

   如果你不能使用托管身份认证，你可以用存储账户密钥代替：

   az containerapp env storage set --name my-env --resource-group my-group \
       --storage-name mystorage \
       --storage-type AzureFile \
       --azure-file-account-name <STORAGE_ACCOUNT_NAME> \
       --azure-file-account-key <STORAGE_ACCOUNT_KEY> \
       --azure-file-share-name <STORAGE_SHARE_NAME> \
       --access-mode ReadWrite
   

   请将 <STORAGE_ACCOUNT_NAME> 和 <STORAGE_ACCOUNT_KEY> 替换为你的存储帐户的名称和密钥。 请将 <STORAGE_SHARE_NAME> 替换为存储帐户中文件共享的名称。

   --access-mode 的有效值为 ReadWrite 和 ReadOnly。

2. 若要更新现有容器应用以装载文件共享，请将应用的规范导出到名为 app.yaml 的 YAML 文件。

   az containerapp show -n <APP_NAME> -g <RESOURCE_GROUP_NAME> -o yaml > app.yaml
   

3. 对容器应用规范进行以下更改。

   • 将一个 volumes 数组添加到容器应用定义的 template 部分，并定义一个卷。 如果已有一个 volumes 数组，请将新卷添加到该数组。
     • name 是卷的标识符。
     • 对于storageType，请对 SMB 使用AzureFile，或对 NFS 使用NfsAzureFile。 此值必须与环境中定义的存储类型匹配。
     • 对于 storageName，请使用在环境中定义的存储的名称。
     • mountOptions 是一个逗号分隔的装载选项字符串。 有关详细信息，请参阅 在 Azure 文件存储 中使用 mountOptions 设置。
     • secrets 列表是要在卷中装载的机密列表。 有关详细信息，请参阅 在卷中挂载机密。
   • 对于要装载Azure 文件存储存储的模板中的每个容器，请在容器定义的 volumeMounts 数组中定义卷装载。
     • volumeName 是 volumes 数组中定义的名称。
     • mountPath 是容器中卷的装载路径。
     • subPath 是要在卷中装载的路径。 如果未指定此值，则会挂载卷的根目录。 更多信息请参见 子路径。
   • SMB
   • NFS

   properties:
     managedEnvironmentId: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/managedEnvironments/<ENVIRONMENT_NAME>
     configuration:
     template:
       containers:
       - image: <IMAGE_NAME>
         name: my-container
         volumeMounts:
         - volumeName: azure-files-volume
           mountPath: /my-files
           subPath: my-sub-path
       volumes:
       - name: azure-files-volume
         storageType: AzureFile
         storageName: mystorage
   

4. 使用 YAML 文件更新容器应用。

   az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP_NAME> \
       --yaml app.yaml
   

有关完整示例，请参阅 YAML 规范。

以下 ARM 模板代码片段演示如何将Azure 文件存储共享添加到容器应用环境并在容器应用中使用它。 对于SMB托管身份认证，在部署存储定义前，先在环境中启用或分配身份，并完成存储账户的前置条件。

1. 将 storages 子资源添加到容器应用环境。

   • SMB
   • NFS

   托管身份认证（推荐）

   首先，在 Microsoft.App/managedEnvironments 资源上启用托管身份，而不是在 Microsoft.App/containerApps 资源上启用。 要启用环境的系统分配身份，请在你的环境资源中添加以下顶层 identity 属性：

   {
     "identity": {
       "type": "SystemAssigned"
     }
   }
   

   将该片段合并到你现有的环境资源中，保留其其他配置。 使用支持托管身份的环境API版本，如 2026-03-02-preview。 关于资源架构，请参见 Microsoft.App/managedEnvironments。

   在存储账户上启用SMBOAuth（），并按照先决条件中的说明，在存储账户范围内将存储文件数据 SMB MI 管理员角色分配给环境标识。

   然后对该存储资源使用 API 版本 2026-03-02-preview。 将 properties.azureFile.identity 设置为 system，以选择环境的系统分配标识：

   {
     "type": "Microsoft.App/managedEnvironments/storages",
     "apiVersion": "2026-03-02-preview",
     "name": "[concat(parameters('environment_name'), '/myazurefiles')]",
     "properties": {
       "azureFile": {
         "accountName": "[parameters('storage_account_name')]",
         "identity": "system",
         "shareName": "[parameters('storage_share_name')]",
         "accessMode": "ReadWrite"
       }
     }
   }
   

   要改用用户分配的托管身份，应将其添加到环境的顶层 identity 属性中：

   {
     "identity": {
       "type": "UserAssigned",
       "userAssignedIdentities": {
         "[parameters('managed_identity_resource_id')]": {}
       }
     }
   }
   

   将 managed_identity_resource_id 参数定义为包含该标识完整 Azure 资源 ID 的 string。 在存储资源中，将 properties.azureFile.identity 设置为 [parameters('managed_identity_resource_id')]，而不是 system。 在存储账户上赋予该身份相同的角色。

   保留已分配给环境的任何标识。 如果你启用了两种身份类型，就使用 SystemAssigned,UserAssigned 作为该环境的 identity.type，并保留其 userAssignedIdentities 条目。

   使用托管身份认证时不要包含 accountKey 或 accountKeyVaultProperties 使用。 关于存储资源架构，请参见 Microsoft.App/managedEnvironments/storages。

   存储账户密钥认证（替代方案）

   如果想用存储账户密钥，可以设置 accountKey 并省略 identity。 定义 storage_account_key 模板参数为 secureString。

   {
     "type": "Microsoft.App/managedEnvironments/storages",
     "apiVersion": "2022-03-01",
     "name": "[concat(parameters('environment_name'), '/myazurefiles')]",
     "properties": {
       "azureFile": {
         "accountName": "[parameters('storage_account_name')]",
         "accountKey": "[parameters('storage_account_key')]",
         "shareName": "[parameters('storage_share_name')]",
         "accessMode": "ReadWrite"
       }
     }
   }
   

   这些存储片段假设环境和文件共享已经存在。 如果你在同一模板中部署它们，将环境和文件共享资源添加到存储资源的 dependsOn 数组中。 对于托管身份验证，如果你在该模板中创建了角色分配，还要添加对角色分配的依赖。 部署依赖并不能消除角色分配传播的延迟。

2. 更新容器应用资源以添加卷和卷装载。

   SMB 认证是在环境的存储定义中配置的。 应用层的卷配置在托管身份和存储账户密钥认证方面是相同的。 如果你在同一个模板中部署存储资源和容器应用，将存储资源添加到容器应用的 dependsOn 数组中。

   • SMB
   • NFS

   {
     "apiVersion": "2023-05-01",
     "type": "Microsoft.App/containerApps",
     "name": "[parameters('containerappName')]",
     "location": "[parameters('location')]",
     "properties": {
   
       ...
   
       "template": {
         "revisionSuffix": "myrevision",
         "containers": [
           {
             "name": "main",
             "image": "[parameters('container_image')]",
             "resources": {
               "cpu": 0.5,
               "memory": "1Gi"
             },
             "volumeMounts": [
               {
                 "mountPath": "/myfiles",
                 "volumeName": "azure-files-volume",
                 "subPath": "my-sub-path"
               }
             ]
           }
         ],
         "scale": {
           "minReplicas": 1,
           "maxReplicas": 3
         },
         "volumes": [
           {
             "name": "azure-files-volume",
             "storageType": "AzureFile",
             "storageName": "myazurefiles"
           }
         ]
       }
     }
   }
   

   • 将一个 volumes 数组添加到容器应用定义的 template 部分，并定义一个卷。 如果已有一个 volumes 数组，请将新卷添加到该数组。
     • name 是卷的标识符。
     • 对于storageType，请对 SMB 使用AzureFile，或对 NFS 使用NfsAzureFile。 此值必须与环境中定义的存储类型匹配。
     • 对于 storageName，请使用在环境中定义的存储的名称。
     • mountOptions 是一个逗号分隔的装载选项字符串。 有关详细信息，请参阅 在 Azure 文件存储 中使用 mountOptions 设置。
     • secrets 列表是要在卷中装载的机密列表。 有关详细信息，请参阅 在卷中挂载机密。
   • 对于要装载Azure 文件存储存储的模板中的每个容器，请在容器定义的 volumeMounts 数组中定义卷装载。
     • volumeName 是 volumes 数组中定义的名称。
     • mountPath 是容器中卷的装载路径。
     • subPath（可选）是要在卷中装载的路径。 如果未指定，则装载卷的根目录。 更多信息请参见 子路径。

有关完整示例，请参阅 ARM 模板 API 规范。

若要在Azure门户中为Azure 文件存储存储配置卷挂载，请先将文件共享添加到容器应用的环境中，然后通过创建新的版本，将卷挂载添加到容器应用。 对于新的 SMB 挂载，选择托管标识身份验证。

1. 在Azure门户中，导航到容器应用环境。

2. 对于SMB托管身份认证，选择 设置>身份 ，启用系统分配身份或向环境添加用户分配身份。 在添加共享之前，请完成 Azure 文件存储 前置条件中描述的存储账户设置和角色分配。

3. 在导航窗格中的“设置”下，选择“卷装载”。

4. 选择 添加 。

5. 根据文件共享使用的协议，选择“服务器消息块 (SMB)”或“网络文件系统 (NFS)”。

6. 在“添加文件共享”上下文菜单中输入以下信息：

   • SMB
   • NFS

   • 名称：环境存储定义的名称。
   • 存储帐户名称：包含文件共享的存储帐户的名称。
   • 认证：选择 托管身份 （推荐）。
   • 身份：从管理身份列表中选择环境的系统分配身份或用户分配给环境的身份。 选择存储账户中带有 存储文件数据SMB MI管理员 角色的身份。
   • 文件共享名称：SMB文件共享的名称。
   • 访问模式：文件共享的访问模式。 有效值为“读/写”和“只读”。

   要使用存储账户密钥认证，请在认证下选择存储账户密钥，然后输入存储账户的访问密钥。 选择一种存储定义的认证方法。

7. 选择“添加”以退出上下文窗格。

8. 选择“保存”以提交更改。

9. 进入容器应用。

10. 在导航窗格的“应用程序”下，选择“修订和副本”。

11. 选择“创建新修订版”。

12. 在“创建并部署新修订”页面中，选择“卷”选项卡。

13. 选择 添加 。

14. 在 “添加卷”上下文窗格中，设置以下值。

    • Volume 类型：Azure 文件卷。
    • 名称：输入卷名称。
    • 文件共享名称：选择之前创建的文件共享。
    • 装载选项：（可选）输入以逗号分隔的装载选项字符串。 有关详细信息，请参阅 在 Azure 文件存储 中使用 mountOptions 设置。

15. 选择“添加”以退出上下文窗格。

16. 在“创建并部署新修订版”页面，选择容器标签页。

17. 选择要在其中装载卷的容器。

18. 在“编辑容器”上下文窗格中，选择“卷装载”选项卡。

19. 在“卷名称”下方，选择你之前创建的卷。

20. 在“装载路径”中输入容器中用于装载卷的绝对路径。

21. 在 子路径（可选）中，输入要装载的卷中的路径。 如果未指定此值，则会挂载卷的根目录。 更多信息请参见 子路径。

22. 选择“保存”以保存更改并退出上下文窗格。

23. 选择“创建”以创建新修订版。