Uso de montajes de almacenamiento en Azure Container Apps

Al configurar el almacenamiento con ámbito de réplica mediante la CLI de Azure, debe utilizar una definición YAML para crear o actualizar su aplicación de contenedores.

1. Para actualizar una aplicación de contenedor existente de modo que use el almacenamiento con ámbito de réplica, exporte la especificación de la aplicación a un archivo YAML denominado app.yaml.

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

2. Realice los siguientes cambios en la especificación de la aplicación de contenedor.

   • Agregue una matriz volumes a la sección template de la definición de la aplicación de contenedor y defina un volumen. Si ya tiene una matriz de volumes, agregue un nuevo volumen a la matriz.
     • name es un identificador del volumen.
     • Use EmptyDir como storageType.
   • Para cada contenedor de la plantilla en el que desee montar el volumen, defina un montaje de volumen en la matriz volumeMounts de la definición del contenedor.
     • volumeName es el nombre definido en la matriz volumes.
     • mountPath es la ruta de acceso del contenedor en el que se va a montar el volumen.

   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. Actualice la aplicación contenedora mediante el archivo YAML.

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

Para obtener un ejemplo completo, consulte la especificación YAML.

Para crear un volumen con ámbito de réplica y montarlo en un contenedor, realice los siguientes cambios en el recurso de aplicaciones de contenedor de una plantilla de ARM:

• Agregue una matriz volumes a la sección template de la definición de la aplicación de contenedor y defina un volumen. Si ya tiene una matriz de volumes, agregue un nuevo volumen a la matriz.
  • name es un identificador del volumen.
  • Use EmptyDir como storageType.
• Para cada contenedor de la plantilla en el que desee montar el volumen, defina un montaje de volumen en la matriz volumeMounts de la definición del contenedor.
  • volumeName es el nombre definido en la matriz volumes.
  • mountPath es la ruta de acceso del contenedor en el que se va a montar el volumen.

Ejemplo de fragmento de código de plantilla de 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"
        }
      ]
    }
  }
}

Consulte la especificación de API de la plantilla de ARM para obtener un ejemplo completo.

Para crear un volumen con ámbito de réplica y montarlo en un contenedor, implemente una nueva revisión de su aplicación de contenedor mediante Azure Portal.

1. En el portal de Azure, vaya a la aplicación contenedora.

2. Seleccione Administración de revisiones en el menú izquierdo.

3. Seleccione Crear nueva revisión.

4. Seleccione el contenedor en el que desea montar el volumen.

5. En el panel de contexto Editar un contenedor, seleccione la pestaña Montajes de volúmenes.

6. En la sección Almacenamiento efímero , cree un nuevo volumen con la siguiente información:

   • Nombre del volumen: nombre del volumen efímero.
   • Ruta de acceso de montaje: ruta de acceso absoluta del contenedor para montar el volumen.

7. Seleccione Guardar para guardar los cambios y salir del panel de contexto.

8. Seleccione Crear para crear la nueva revisión.

Al configurar una aplicación contenedora para montar un volumen de Azure Files mediante CLI de Azure, debe usar una definición de YAML para crear o actualizar la aplicación contenedora.

Instala la última CLI de Azure y actualiza la extensión Container Apps:

az extension add --name containerapp --upgrade

Para ver un tutorial paso a paso sobre cómo montar un recurso compartido de archivos SMB, consulte Crear un montaje de almacenamiento de Azure Files en Azure Container Apps.

1. Agregue una definición de almacenamiento en el entorno de Container Apps.

   • SMB
   • NFS

   Autenticación de identidad gestionada (recomendada)

   Para usar la identidad administrada asignada por el sistema del entorno, primero habilítala:

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

   Concede a la identidad el rol Storage File Data SMB MI Admin en tu cuenta de almacenamiento y activa Managed Identity for SMB según se describe en los requisitos previos. Luego crea la definición de almacenamiento:

   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
   

   Sustituya <STORAGE_ACCOUNT_NAME> y <STORAGE_SHARE_NAME> con los nombres de la cuenta de almacenamiento y de los recursos compartidos de archivos. El valor system selecciona la identidad gestionada asignada por el sistema al entorno.

   Para usar una identidad gestionada asignada por el usuario en su lugar, asignala al entorno:

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

   Asigna a esa identidad el mismo rol en la cuenta de almacenamiento. En el comando de almacenamiento, reemplazar --azure-file-identity system por --azure-file-identity <MANAGED_IDENTITY_RESOURCE_ID>, usando el identificador completo del recurso de Azure de la identidad, no su ID de cliente ni su identificador principal.

   No se combine --azure-file-identity con --azure-file-account-key ni --azure-file-key-vault-secret-url. Estos modos de autenticación son mutuamente excluyentes.

   Autenticación de la clave de cuenta de almacenamiento (alternativa)

   Si no puedes usar autenticación de identidad gestionada, puedes usar una clave de cuenta de almacenamiento en su lugar:

   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
   

   Reemplace <STORAGE_ACCOUNT_NAME> y <STORAGE_ACCOUNT_KEY> por el nombre y la clave de su cuenta de almacenamiento. Reemplace <STORAGE_SHARE_NAME> por el nombre del recurso compartido de archivos de la cuenta de almacenamiento.

   Los valores válidos para --access-mode son ReadWrite y ReadOnly.

2. Para actualizar una aplicación de contenedor existente para que monte un recurso compartido de archivos, exporte la especificación de la aplicación a un archivo YAML denominado app.yaml.

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

3. Realice los siguientes cambios en la especificación de la aplicación de contenedor.

   • Agregue una matriz volumes a la sección template de la definición de la aplicación de contenedor y defina un volumen. Si ya tiene una matriz de volumes, agregue un nuevo volumen a la matriz.
     • name es un identificador del volumen.
     • Para storageType, use AzureFile para SMB o NfsAzureFile para NFS. Este valor debe coincidir con el tipo de almacenamiento que definió en el entorno.
     • Para storageName, use el nombre del almacenamiento que definió en el entorno.
     • mountOptions es una cadena separada por comas de opciones de montaje. Para obtener más información, consulte Uso de la configuración mountOptions en Azure Files.
     • La secrets lista es una lista de secretos que se van a montar en el volumen. Para obtener más información, consulte Montaje de secretos en un volumen.
   • Para cada contenedor de la plantilla en el que desee montar almacenamiento de Azure Files, defina un punto de montaje de volumen en la matriz volumeMounts de la definición de contenedor.
     • volumeName es el nombre definido en la matriz volumes.
     • mountPath es la ruta de acceso del contenedor en el que se va a montar el volumen.
     • subPath es la ruta de acceso del volumen que se va a montar. Si no especifica este valor, se monta la raíz del volumen. Para más información, consulta Subcamino.
   • 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. Actualice la aplicación contenedora mediante el archivo YAML.

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

Para obtener un ejemplo completo, consulte la especificación YAML.

Los siguientes fragmentos de código de plantilla de ARM muestran cómo agregar un recurso compartido de Azure Files a un entorno de Container Apps y usarlo en una aplicación contenedora. Para la autenticación de identidad gestionada por SMB, habilita o asigna la identidad en el entorno y completa los requisitos previos de la cuenta de almacenamiento antes de desplegar la definición de almacenamiento.

1. Agregue un recurso secundario storages al entorno de Container Apps.

   • SMB
   • NFS

   Autenticación de identidad gestionada (recomendada)

   Primero, habilita una identidad gestionada en el Microsoft.App/managedEnvironments recurso, no en el Microsoft.App/containerApps recurso. Para habilitar la identidad asignada por el sistema del entorno, añade la siguiente propiedad de nivel superior identity a tu recurso de entorno:

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

   Fusiona este fragmento con tu recurso de entorno existente, manteniendo su otra configuración. Utiliza una versión de API de entorno que soporte identidades gestionadas, como 2026-03-02-preview. Para el esquema de recursos, consulta Microsoft.App/managedEnvironments.

   Habilite la identidad administrada para SMB (SMBOAuth) en la cuenta de almacenamiento y asigne a la identidad del entorno el rol Storage File Data SMB MI Admin en el ámbito de la cuenta de almacenamiento, tal como se describe en los requisitos previos.

   Luego usa la versión de API 2026-03-02-preview para el recurso de almacenamiento. Establezca properties.azureFile.identity en system para seleccionar la identidad asignada por el sistema del entorno:

   {
     "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"
       }
     }
   }
   

   Para usar una identidad gestionada asignada por el usuario en su lugar, añádela a la propiedad de nivel identity superior del entorno:

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

   Defina el managed_identity_resource_id parámetro como un string que contiene el ID completo de recurso de Azure de la identidad. En el recurso de almacenamiento, establezca properties.azureFile.identity en [parameters('managed_identity_resource_id')] en lugar de system. Asigne a esa identidad el mismo rol en la cuenta de almacenamiento.

   Conserva cualquier identidad ya asignada al entorno. Si activa ambos tipos de identidad, use SystemAssigned,UserAssigned para el entorno identity.type y conserve sus entradas de userAssignedIdentities.

   No incluyas accountKey ni accountKeyVaultProperties al usar la autenticación de identidad gestionada. Para el esquema de recursos de almacenamiento, véase Microsoft.App/managedEnvironments/storages.

   Autenticación de la clave de cuenta de almacenamiento (alternativa)

   Para usar una clave de cuenta de almacenamiento en su lugar, establece accountKey y omite identity. Defina el storage_account_key parámetro plantilla como un 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"
       }
     }
   }
   

   Estos fragmentos de almacenamiento asumen que el entorno y el recurso compartido de archivos ya existen. Si los despliega en la misma plantilla, añada los recursos de entorno y de recurso compartido de archivos a la matriz de dependsOn del recurso de almacenamiento. Para la autenticación de identidad gestionada, también añade una dependencia a la asignación de rol si la creas en esa plantilla. Una dependencia de despliegue no elimina los retrasos en la propagación de asignación de roles.

2. Actualice el recurso de la aplicación de contenedor para que agregue un volumen y un montaje de volumen.

   La autenticación SMB se configura en la definición de almacenamiento del entorno. La configuración de volúmenes a nivel de aplicación es la misma para la autenticación de identidad gestionada y clave de cuenta de almacenamiento. Si despliegas el recurso de almacenamiento y la aplicación contenedora en la misma plantilla, añade el recurso de almacenamiento a la matriz dependsOn de la aplicación contenedora.

   • 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"
           }
         ]
       }
     }
   }
   

   • Agregue una matriz volumes a la sección template de la definición de la aplicación de contenedor y defina un volumen. Si ya tiene una matriz de volumes, agregue un nuevo volumen a la matriz.
     • name es un identificador del volumen.
     • Para storageType, use AzureFile para SMB o NfsAzureFile para NFS. Este valor debe coincidir con el tipo de almacenamiento que definió en el entorno.
     • Para storageName, use el nombre del almacenamiento que definió en el entorno.
     • mountOptions es una cadena separada por comas de opciones de montaje. Para obtener más información, consulte Uso de la configuración mountOptions en Azure Files.
     • La secrets lista es una lista de secretos que se van a montar en el volumen. Para obtener más información, consulte Montaje de secretos en un volumen.
   • Para cada contenedor de la plantilla en el que desee montar almacenamiento de Azure Files, defina un punto de montaje de volumen en la matriz volumeMounts de la definición de contenedor.
     • volumeName es el nombre definido en la matriz volumes.
     • mountPath es la ruta de acceso del contenedor en el que se va a montar el volumen.
     • subPath (opcional) es la ruta de acceso del volumen que se va a montar. Si no lo especifica, se monta la raíz del volumen. Para más información, consulta Subcamino.

Consulte la especificación de API de la plantilla de ARM para obtener un ejemplo completo.

Para configurar un punto de montaje de volumen para el almacenamiento de Azure Files en el portal de Azure, agregue un recurso compartido de archivos al entorno de Container Apps y, a continuación, añada un punto de montaje de volumen a la aplicación contenedora al crear una nueva revisión. Para montajes nuevos de SMB, selecciona autenticación de identidad gestionada.

1. En el portal de Azure, vaya al entorno de Container Apps.

2. Para la autenticación de identidad administrada por SMB, selecciona Configuración>Identidad y activa una identidad asignada por el sistema o añade una identidad asignada por el usuario al entorno. Completa la configuración de la cuenta de almacenamiento y la asignación de roles descritos en los prerrequisitos de Azure Files antes de añadir el recurso compartido.

3. En el panel de navegación, en Configuración, seleccione Montajes de volumen.

4. Seleccione Agregar.

5. Seleccione Bloque de mensajes del servidor (SMB) o Network File System (NFS), en función del protocolo usado por el recurso compartido de archivos.

6. En el panel de contexto Agregar recurso compartido de archivos, escriba la siguiente información:

   • SMB
   • NFS

   • Nombre: Un nombre para la definición de almacenamiento del entorno.
   • Nombre de la cuenta de almacenamiento: nombre de la cuenta de almacenamiento que contiene el recurso compartido de archivos.
   • Autenticación: Seleccione identidad administrada (recomendada).
   • Identidad: Seleccione la identidad asignada por el sistema del entorno o una identidad asignada por el usuario asignada al entorno desde la lista de identidad gestionada. Selecciona la identidad que tenga el rol Storage File Data SMB MI Admin en la cuenta de almacenamiento.
   • Nombre del recurso compartido de archivos: El nombre del recurso compartido de archivos SMB.
   • Modo de acceso: modo de acceso del recurso compartido de archivos. Los valores válidos son Lectura y escritura y Solo lectura.

   Para usar la autenticación por clave de cuenta de almacenamiento en su lugar, selecciona Clave de cuenta de almacenamiento en Autenticación e introduce la clave de acceso de la cuenta de almacenamiento. Elija un método de autenticación para la definición de almacenamiento.

7. Seleccione Agregar para salir del panel de contexto.

8. Haga clic en Guardar para confirmar los cambios.

9. Ve a tu aplicación de contenedores.

10. En el panel de navegación, en Aplicación, seleccione Revisiones y réplicas.

11. Seleccione Crear nueva revisión.

12. En la página Crear e implementar una nueva revisión, seleccione la pestaña Volúmenes.

13. Seleccione Agregar.

14. En el panel de contexto Agregar volumen, establezca los valores siguientes.

    • Tipo de volumen: volumen de archivos de Azure.
    • Nombre: escriba un nombre de volumen.
    • Nombre del recurso compartido de archivos: seleccione el recurso compartido de archivos que creó anteriormente.
    • Opciones de montaje: opcionalmente, escriba una cadena separada por comas de opciones de montaje. Para obtener más información, consulte Uso de la configuración mountOptions en Azure Files.

15. Seleccione Agregar para salir del panel de contexto.

16. En la página de Crear y desplegar nueva revisión , selecciona la pestaña Contenedor .

17. Seleccione el contenedor en el que desea montar el volumen.

18. En el panel de contexto Editar un contenedor, seleccione la pestaña Montajes de volúmenes.

19. En Nombre del volumen, seleccione el volumen que creó anteriormente.

20. En Ruta de acceso de montaje, escriba la ruta de acceso absoluta del contenedor para montar el volumen.

21. En Ruta de acceso secundaria (opcional), escriba la ruta de acceso en el volumen que se va a montar. Si no especifica este valor, se monta la raíz del volumen. Para más información, consulta Subcamino.

22. Seleccione Guardar para guardar los cambios y salir del panel de contexto.

23. Seleccione Crear para crear la nueva revisión.