Gestionar agentes de transferencia

Los agentes del Servicio de transferencia de Storage son aplicaciones que se ejecutan en un contenedor de Open Container Initiative (OCI) y que se coordinan con el Servicio de transferencia de Storage para realizar transferencias que impliquen sistemas de archivos o almacenamiento compatible con S3.

De forma predeterminada, el Servicio de transferencia de Storage usa Docker para compilar y ejecutar contenedores OCI. Storage Transfer Service también admite Podman para la gestión de contenedores. Para usar Podman, debes instalar los agentes con el comando podman run.

Si la transferencia no implica un sistema de archivos o un almacenamiento compatible con S3, no es necesario que configure agentes.

En este documento se describe cómo administrar agentes de transferencia en sus servidores.

Información general

  • Los procesos de los agentes son dinámicos. Mientras se esté realizando una transferencia, puedes añadir agentes para aumentar el rendimiento. Los agentes que se inician recientemente se unen al grupo de agentes asignado y realizan el trabajo de las transferencias existentes. Puedes usarlo para ajustar el número de agentes que se están ejecutando o para adaptar el rendimiento de las transferencias a los cambios en la demanda de transferencias.

  • Los procesos de los agentes son un colectivo tolerante a fallos. Si un agente deja de ejecutarse, los demás agentes siguen trabajando. Si todos tus agentes se detienen, cuando añadas nuevos agentes, la transferencia se reanudará en el punto en el que se detuvieron los agentes. De esta forma, no tendrás que monitorizar agentes, volver a intentar transferencias ni implementar lógica de recuperación. Puedes parchear, mover y escalar dinámicamente tus grupos de agentes sin que se produzca un tiempo de inactividad en la transferencia coordinando los agentes con Google Kubernetes Engine.

    Por ejemplo, envía dos transferencias mientras se están ejecutando dos agentes. Si uno de los agentes se detiene debido a un reinicio de la máquina o a un parche del sistema operativo, el agente restante sigue funcionando. Las dos transferencias siguen en curso, pero son más lentas, ya que un solo agente está moviendo los datos. Si el agente restante también se detiene, todas las transferencias dejarán de avanzar, ya que no habrá ningún agente en ejecución. Cuando reinicies los procesos del agente, las transferencias se reanudarán en el punto en el que se habían quedado.

  • Los procesos del agente pertenecen a un grupo. Mueven tus datos de forma colectiva en paralelo. Por este motivo, todos los agentes de un grupo deben tener el mismo acceso a todas las fuentes de datos que quieras transferir.

    Por ejemplo, si transfiere datos de un sistema de archivos concreto, debe montar el sistema de archivos en cada máquina que aloje agentes en su grupo de agentes. Si algunos agentes de tu grupo pueden acceder a una fuente de datos y otros no, las transferencias desde esa fuente de datos no se completarán.

Antes de empezar

Antes de configurar las transferencias, asegúrate de haber configurado el acceso: para usuarios y cuentas de servicio.

Si vas a usar comandos gcloud, instala gcloud CLI.

Instalar y ejecutar agentes de transferencia

Te recomendamos que instales un mínimo de tres agentes por grupo de agentes, preferiblemente en máquinas independientes. Para obtener más información sobre cómo determinar cuántos agentes se deben ejecutar, consulta Maximizar el rendimiento de los agentes de transferencia.

No incluyas información sensible, como información personal identificable (IPI) o datos de seguridad, en el prefijo del ID de tu agente. Los nombres de recursos pueden propagarse a los nombres de otros recursos de Google Cloud y pueden exponerse a sistemas internos de Google fuera de tu proyecto.

Para instalar y ejecutar agentes de transferencia, sigue estos pasos:

Google Cloud consola

  1. En la Google Cloud consola, ve a la página Grupos de agentes.

    Ir a Grupos de agentes

  2. Selecciona el grupo de agentes al que quieras añadir el nuevo agente.

  3. Haz clic en Instalar agente.

  4. Sigue las instrucciones para instalar y ejecutar el agente.

    Para obtener más información sobre las opciones de línea de comandos del agente, consulta Opciones de línea de comandos del agente.

CLI de gcloud

Para instalar uno o varios agentes con gcloud CLI, ejecuta el siguiente comando: gcloud transfer agents install

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

La herramienta te guiará por los pasos necesarios para instalar los agentes. Este comando instala NUM_AGENTS agentes en tu máquina, asignados al nombre del grupo especificado como POOL_NAME, y autentica al agente con tus credenciales de gcloud. El nombre del grupo debe existir o se devolverá un error.

La marca --mount-directories es opcional, pero muy recomendable. Su valor es una lista separada por comas de los directorios del sistema de archivos a los que se debe conceder acceso al agente. Si se omite esta marca, se montará todo el sistema de archivos en el contenedor del agente. Consulta más información en la referencia de gcloud.

Fuentes compatibles con S3

Cuando instales agentes para usarlos con una fuente compatible con S3, debes proporcionar las credenciales de AWS como variables de entorno con los valores de AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY, o bien almacenarlas como credenciales predeterminadas en los archivos de configuración de tu sistema.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Usar una clave de cuenta de servicio

Para ejecutar agentes con una clave de cuenta de servicio, usa la opción --creds-file:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Más información

Para ver una lista completa de las marcas opcionales, ejecuta gcloud transfer agents install --help o consulta la referencia de gcloud transfer.

Docker

Antes de usar Docker para instalar agentes, sigue las instrucciones para instalar Docker.

El comando docker run instala un agente. Para aumentar el número de agentes de tu grupo, vuelve a ejecutar este comando tantas veces como sea necesario.

Al instalar agentes, puedes autenticarte con tus gcloud credenciales predeterminadas o con una cuenta de servicio.

Credenciales predeterminadas

Si quieres que el contenedor Docker pueda autenticarse con tus credenciales predeterminadas de gcloud, usa el comando que aparece a continuación para crear un volumen Docker que contenga un archivo con tus credenciales de aplicación predeterminadas:

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

A continuación, usa el siguiente comando para instalar un agente. Utiliza la marca --volumes-from para montar el volumen de credenciales gcloud-config:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Autenticación de cuenta de servicio

Para instalar y ejecutar agentes de transferencia docker run con credenciales de cuenta de servicio, especifica la ruta a la clave de la cuenta de servicio en formato JSON mediante la marca --creds-file.

La ruta debe incluir el prefijo /transfer_root.

Consulta el artículo Crear y gestionar claves de cuentas de servicio para obtener más información sobre las claves de cuentas de servicio.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opciones y flags

Sustituye las variables de los ejemplos anteriores por la siguiente información:

  • HOST_DIRECTORY es el directorio de la máquina host desde el que quieres copiar. Puedes usar más de una marca -v para especificar directorios adicionales desde los que copiar.
  • CONTAINER_DIRECTORY es el directorio asignado en el contenedor del agente. Debe ser la misma que la de HOST_DIRECTORY.
  • PROJECT_ID es el ID del proyecto que aloja la transferencia.
  • POOL_NAME es el nombre del grupo de agentes en el que se instalará este agente. Si omites esta marca, el agente se instalará en el grupo transfer_service_default de tu proyecto.

El comando docker run admite más marcas.

  • --enable-mount-directory monta todo el sistema de archivos en el directorio /transfer_root del contenedor. Si se especifica --enable-mount-directory, no se aplican las restricciones de directorio mediante la marca -v.

  • --creds-file=/etc/gcloud/key.json especifica la ruta al archivo de credenciales de la cuenta de servicio en formato JSON en el contenedor. Este archivo se monta con la marca -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro en el comando.

  • --enable-s3 especifica que este agente se usa para transferencias desde almacenamiento compatible con S3. Los agentes instalados con esta opción no se pueden usar para transferencias desde sistemas de archivos POSIX.

    Si la transferencia se realiza desde AWS S3 o un almacenamiento compatible con S3, envía el ID de clave de acceso y la clave secreta mediante variables de entorno:

    -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY

  • --gcs-api-endpoint=storage.LOCATION.rep.googleapis.com especifica un endpoint regional de Cloud Storage. Cuando se especifica un endpoint regional de Cloud Storage, todo el tráfico de transferencia de datos a través del agente permanece en esa región. Google Cloud Consulta más información sobre los endpoints regionales.

  • --env HTTPS_PROXY=PROXY especifica un proxy de reenvío en tu red. El valor de PROXY es la URL HTTP y el puerto del servidor proxy. Asegúrese de especificar la URL HTTP y no una URL HTTPS para evitar que las solicitudes se envuelvan dos veces en el cifrado TLS. Las solicitudes envueltas dos veces impiden que el servidor proxy envíe solicitudes salientes válidas.

  • --agent-id-prefix=ID_PREFIX especifica un prefijo opcional que se añade al ID del agente para ayudar a identificar al agente o a su máquina en la Google Cloud consola. Cuando se usa un prefijo, el ID de agente tiene el formato prefix + hostname + Docker container ID.

  • --log-dir=LOGS_DIRECTORY modifica el directorio en el que el agente escribe los registros. El directorio predeterminado es /tmp/.

    Si no has especificado --enable_mount_directory, debes añadir el prefijo /transfer_root a esta ruta. Por ejemplo, /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: los agentes usan de forma predeterminada un máximo de 8 GiB de memoria del sistema. Si el valor predeterminado no se ajusta a tu entorno, puedes especificar un uso máximo de memoria relevante en los siguientes formatos:

    Valor de max-physical-mem Ajuste de memoria máximo
    6g 6 gigabytes
    6gb 6 gigabytes
    6GiB 6 gibibytes

  • --network=DOCKER_NETWORK: especifica la red de Docker de este contenedor. Si especificas --network=host puedes mejorar el rendimiento reduciendo la sobrecarga de la red, pero el contenedor tendrá acceso completo a la red del host.

Podman

Antes de usar Podman para instalar agentes, instala Podman:

sudo apt-get update
sudo apt-get -y install podman

Al instalar agentes, puedes autenticarte con tus gcloud credenciales predeterminadas o con una cuenta de servicio.

Credenciales predeterminadas

Para que el contenedor del agente pueda autenticarse con tus credenciales predeterminadas de la CLI de Google Cloud, crea un volumen que contenga un archivo con tus credenciales de aplicación predeterminadas ejecutando el siguiente comando:

gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io
sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth application-default login

A continuación, usa el siguiente comando para instalar un agente. Utiliza la marca --volumes-from para montar el volumen de credenciales gcloud-config. El comando instala un agente. Para aumentar el número de agentes de tu grupo, vuelve a ejecutar este comando tantas veces como sea necesario.

sudo podman run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Autenticación de cuenta de servicio

Para instalar y ejecutar agentes de transferencia con credenciales de cuenta de servicio, debes poner a disposición del contenedor la clave de tu cuenta de servicio en formato JSON. Para ello:

  1. Monta la ubicación del host de la clave en cualquier ruta del contenedor. Por ejemplo: -v $HOME/.config/gcloud/credentials.json:/key.json:ro. Esto especifica que la clave se encuentra en el equipo host en $HOME/.config/gcloud/credentials.json y que se debe activar como /key.json en el contenedor. El ro indica que el archivo está disponible como de solo lectura para el contenedor.
  2. Especifica la ruta del contenedor de la clave como valor de --creds-file. En el ejemplo del paso anterior, especifica --creds-file=/key.json.

Consulta el artículo Crear y gestionar claves de cuentas de servicio para obtener más información sobre las claves de cuentas de servicio.

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opciones y flags

Sustituye las variables de los ejemplos anteriores por la siguiente información:

  • HOST_DIRECTORY es el directorio de la máquina host desde el que quieres copiar. Puedes usar más de una marca -v para especificar directorios adicionales desde los que copiar.
  • CONTAINER_DIRECTORY es el directorio asignado en el contenedor del agente. Debe ser la misma que la de HOST_DIRECTORY.
  • PROJECT_ID es el ID del proyecto que aloja la transferencia.
  • POOL_NAME es el nombre del grupo de agentes en el que se instalará este agente. Si omites esta marca, el agente se instalará en el grupo transfer_service_default de tu proyecto.

El comando podman run admite más marcas.

  • --enable-mount-directory monta todo el sistema de archivos en el directorio /transfer_root del contenedor. Si se especifica --enable-mount-directory, no se aplican las restricciones de directorio mediante la marca -v.

  • --creds-file=/etc/gcloud/key.json especifica la ruta al archivo de credenciales de la cuenta de servicio en formato JSON en el contenedor. Este archivo se monta con la marca -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro en el comando.

  • --enable-s3 especifica que este agente se usa para transferencias desde almacenamiento compatible con S3. Los agentes instalados con esta opción no se pueden usar para transferencias desde sistemas de archivos POSIX.

  • Si la transferencia se realiza desde AWS S3 o un almacenamiento compatible con S3, envía el ID de clave de acceso y la clave secreta mediante variables de entorno:

      -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  ```

  • --env HTTPS_PROXY=PROXY especifica un proxy de reenvío en tu red. El valor de PROXY es la URL HTTP y el puerto del servidor proxy. Asegúrese de especificar la URL HTTP y no una URL HTTPS para evitar que las solicitudes se envuelvan dos veces en el cifrado TLS. Las solicitudes envueltas dos veces impiden que el servidor proxy envíe solicitudes salientes válidas.

  • --agent-id-prefix=ID_PREFIX especifica un prefijo opcional que se añade al ID del agente para ayudar a identificar al agente o a su máquina en la Google Cloud consola. Cuando se usa un prefijo, el ID de agente tiene el formato prefix + hostname + OCI container ID.

  • --log-dir=LOGS_DIRECTORY modifica el directorio en el que el agente escribe los registros. El directorio predeterminado es /tmp/.

    Si no has especificado --enable_mount_directory, debes añadir el prefijo /transfer_root a esta ruta. Por ejemplo, /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: los agentes usan de forma predeterminada un máximo de 8 GiB de memoria del sistema. Si el valor predeterminado no se ajusta a tu entorno, puedes especificar un uso máximo de memoria relevante en los siguientes formatos:

    Valor de max-physical-mem Ajuste de memoria máximo
    6g 6 gigabytes
    6gb 6 gigabytes
    6GiB 6 gibibytes

  • --network=DOCKER_NETWORK: especifica la red de Docker de este contenedor. Si especificas --network=host puedes mejorar el rendimiento reduciendo la sobrecarga de la red, pero el contenedor tendrá acceso completo a la red del host.

Solución de problemas

Si la configuración de SELinux requiere que se coloquen etiquetas en el contenido del volumen montado en un contenedor, añade la marca :Z al volumen:

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json:ro \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Si no se incluye una etiqueta, es posible que el sistema de seguridad impida que los procesos que se ejecutan en el contenedor usen el contenido. De forma predeterminada, Podman no cambia las etiquetas definidas por el SO.

Confirmar las conexiones de agentes

Para confirmar que tus agentes están conectados, haz lo siguiente:

  1. En la Google Cloud consola, ve a la página Grupos de agentes.

    Ir a Grupos de agentes

    Se muestran tus grupos de agentes, junto con el número de agentes conectados.

  2. Selecciona un grupo de agentes para ver los detalles de los agentes conectados.

Si un nuevo agente no aparece en la página del grupo de agentes en los 10 minutos posteriores a su creación, consulta el artículo Los agentes no están conectados.

Monitorizar la actividad de los agentes

Puedes usar Cloud Monitoring para monitorizar la actividad del agente.

La monitorización está disponible en las dimensiones project, agent_pool y agent_id.

Con estos datos de monitorización, puede configurar alertas para que le avisen de posibles problemas con su transferencia. Para ello, crea una alerta en una de las siguientes métricas: Google Cloud

Nombre de la métrica Qué describe Usos sugeridos
storagetransfer.googleapis.com/agent/transferred_bytes_count Mide la velocidad con la que un agente específico mueve datos en todos los trabajos que atiende en un momento dado. Alerta de bajadas en el rendimiento.
storagetransfer.googleapis.com/agent/connected Valor booleano que es True para cada agente que Google Cloud ha recibido un mensaje de latido reciente.
  • Alerta de agentes que no funcionan
  • No alcanzar el número de agentes que consideras necesario para obtener un rendimiento razonable
  • Informar de un problema con las máquinas de los agentes

Detener un agente

Para detener un agente, ejecuta docker stop en el ID del contenedor Docker del agente. Para encontrar el ID y detener al agente, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Grupos de agentes.

    Ir a Grupos de agentes

  2. Selecciona el grupo de agentes que contenga el agente que quieras detener.

  3. Selecciona un agente de la lista. Usa el campo Filtrar para buscar prefijos, estados de agentes, antigüedad de agentes y más.

  4. Haz clic en Detener agente. Se muestra el comando docker stop con el ID de contenedor específico.

  5. Ejecuta el comando en el equipo en el que se está ejecutando el agente. Un comando docker stop correcto devuelve el ID del contenedor.

Una vez detenido, el agente se muestra en la lista de grupos de agentes como Desconectado.

Reiniciar un agente

Los agentes detenidos no se pueden reiniciar. En su lugar, instala agentes nuevos en el grupo de agentes.

Eliminar un agente

Para eliminar agentes específicos, enumera los agentes que se estén ejecutando en tu máquina:

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

A continuación, pasa los IDs de agente a transfer agents delete:

gcloud transfer agents delete --ids=id1,id2,…

Para eliminar todos los agentes que se estén ejecutando en la máquina, usa la marca --all o la marca --uninstall. Ambas marcas eliminan todos los agentes de la máquina. La marca --uninstall también desinstala la imagen Docker del agente.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Detalles de la transferencia del sistema de archivos

Transferencias incrementales

El Servicio de Transferencia de Almacenamiento inicia todas las transferencias calculando los datos presentes en el origen y el destino para determinar qué archivos de origen son nuevos y cuáles se han actualizado o eliminado desde la última transferencia. Lo hacemos para reducir la cantidad de datos que enviamos desde tus máquinas, usar el ancho de banda de forma eficaz y reducir los tiempos de transferencia.

Para detectar si un archivo ha cambiado, comprobamos la hora de la última modificación y el tamaño del archivo de origen, y los comparamos con la hora de la última modificación y el tamaño registrados cuando se copió el archivo por última vez. Cuando detectamos un archivo nuevo o modificado, copiamos todo el archivo en su destino. Para obtener más información sobre la actualización de los archivos, consulta Detalles sobre la coherencia de los datos.

De forma predeterminada, detectamos los archivos eliminados en la fuente, pero no hacemos nada al respecto. Si eliges la opción de sincronización Eliminar los archivos de destino que no estén también en el origen al crear o editar una transferencia, se eliminará el objeto correspondiente en el destino.

Si eliges la opción de sincronización Eliminar los archivos de destino que no estén también en el origen, los archivos que se eliminen accidentalmente en el origen también se eliminarán en el destino. Para evitar la pérdida de datos por eliminaciones accidentales, te recomendamos que habilites el control de versiones de objetos en tu cubo de destino si decides usar esta opción. De esta forma, si eliminas un archivo por error, puedes restaurar tus objetos en Cloud Storage a una versión anterior.

Detalles de la coherencia de los datos

Si la transferencia se realiza correctamente, se transferirán todos los archivos de origen que existieran y no se hubieran modificado durante todo el tiempo que haya durado la operación. Es posible que los archivos de origen que se hayan creado, actualizado o eliminado durante una transferencia reflejen o no esos cambios en el conjunto de datos de destino.

El Servicio de transferencia de Storage usa la hora de la última modificación y el tamaño de un archivo para determinar si ha cambiado. Si se actualiza un archivo sin cambiar la hora de la última modificación ni el tamaño, y habilitas la opción delete-objects-from-source, es posible que pierdas datos de ese cambio.

Cuando utilices la función delete-objects-from-source, te recomendamos que inhabilites las escrituras en la fuente durante la transferencia para evitar que se pierdan datos.

Para inhabilitar las escrituras en tu fuente, haz una de las siguientes acciones:

  • Clona el directorio que quieras transferir y, a continuación, utiliza el directorio clonado como origen de la transferencia.
  • Detén las aplicaciones que escriban en el directorio de origen.

Si es importante registrar los cambios que se hayan producido durante una transferencia, puedes volver a ejecutarla o definir el sistema de archivos de origen como de solo lectura mientras se esté ejecutando la operación.

Como Cloud Storage no tiene el concepto de directorios, los directorios de origen vacíos no se transfieren.