Administra el almacenamiento de objetos

Lineamientos para asignar nombres a bucket de almacenamiento

Los nombres de los buckets deben cumplir con las siguientes convenciones de nomenclatura:

• Ser único en el proyecto Un proyecto agrega un prefijo único al nombre del bucket, lo que garantiza que no haya conflictos dentro de la organización. En el improbable caso de que haya un conflicto entre el prefijo y el nombre del bucket en diferentes organizaciones, la creación del bucket fallará y se mostrará un error bucket name in use.
• Debe tener al menos un carácter y no más de 57.
• Evita incluir información de identificación personal (PII).
• Ser compatible con DNS
• Comenzar con una letra y contener solo letras, números y guiones

Instala la CLI de la herramienta s3cmd

La herramienta s3cmd es una herramienta de línea de comandos para administrar el almacenamiento de objetos.

1. Para descargar la herramienta, navega al directorio desde el que se extrajo el paquete de GDC.

2. Ejecuta los siguientes comandos para extraer la imagen de s3cmd, s3cmd.tar.tar.gz, a un directorio temporal vacío:

   tmpdir=$(mktemp -d)
   
   gdcloud artifacts extract oci/ $tmpdir \
     --image-name=$(gdcloud artifacts tree oci | grep s3cmd.tar | sed 's/^.* //')
   

3. scp el archivo tar en una máquina cliente en la que usas s3cmd para las operaciones de objetos; descomprime e instala la imagen.

Elige uno de los siguientes métodos de instalación para instalar la herramienta s3cmd:

Instalación a través de un archivo tar

1. Para descomprimir el archivo y, luego, instalar el paquete s3cmd, ejecuta los siguientes comandos. Debes tener el módulo distutils de Python para instalar el paquete. El módulo suele formar parte del paquete principal de Python, o bien puedes instalarlo con tu administrador de paquetes.

   tar xvf /tmp/gpc-system-tar-files/s3cmd.tar.tar.gz
   cd /tmp/gpc-system-tar-files/s3cmd
   sudo python3 setup.py install
   

2. Opcional: Limpia los archivos descargados:

   rm /tmp/gpc-system-tar-files/s3cmd.tar.tar.gz
   rm -r /tmp/gpc-system-tar-files/s3cmd
   

Instalación con imagen de Docker

Nota: Antepón el prefijo /g/ a todos los comandos que hagan referencia a archivos locales. Por ejemplo: s3cmd put /g/local_file s3://fully_qualified_bucket_name.

1. Para instalar la imagen de s3cmd, ejecuta los siguientes comandos:

   docker load --input s3cmd-docker.tar
   export S3CFG=/EMPTY_FOLDER_PATH/
   alias s3cmd="docker run -it --net=host --mount=type=bind,source=/$S3CFG/,target=/g/
   s3cmd-docker:latest -c /g/s3cfg"
   

   Nota: Solo se puede acceder a los archivos dentro de la carpeta S3CFG desde el contenedor de Docker. Agrega la marca --ca-certs=/g/certificate_file al comando de Docker anterior si es necesario o usa la marca --no-check-certificate para el modo no seguro.

2. Opcional: Limpia los archivos descargados:

   rm s3cmd-docker.tar
   

3. Agrega la exportación y el alias al archivo .bashrc para que persistan después de reiniciar el cliente.

Nota: Este comando solo instala la herramienta s3cmd en la máquina cliente, y se requiere configuración adicional.

Configura la herramienta s3cmd

Usa la herramienta s3cmd para las operaciones basadas en objetos.

Ejecuta el comando s3cmd --configure y especifica lo siguiente:

1. Clave de acceso: Ingresa la clave de acceso que obtuviste del secreto en cómo obtener credenciales de acceso.
2. Clave secreta: Ingresa la clave secreta que obtuviste del secreto en obtención de credenciales de acceso.
3. Región predeterminada: Presiona ENTER.
4. Extremo de S3: Ingresa el extremo que proporciona tu operador de infraestructura (IO).
5. Para el uso de nombres de buckets de estilo DNS, ingresa s3://%(bucket).
6. Opcional: Ingresa una contraseña de encriptación para proteger los archivos en tránsito.
7. En Ruta de acceso a GPG, ingresa /usr/bin/gpg.
8. Ingresa Yespara usar el protocolo HTTPS.
9. Presiona Enter para omitir el ingreso del nombre del servidor proxy.

Crea buckets de almacenamiento

Antes de comenzar

Un espacio de nombres del proyecto administra los recursos del bucket en el clúster de administrador raíz. Debes tener un proyecto para crear un bucket. Para crear un proyecto nuevo, consulta Crea un proyecto. Debes tener los permisos de bucket adecuados para realizar las siguientes operaciones. Consulta cómo otorgar acceso a un bucket.

Crea un bucket

Para crear un bucket, aplica una especificación de bucket al espacio de nombres de tu proyecto:

    kubectl apply -f bucket.yaml

A continuación, se muestra un ejemplo de una especificación de bucket:

    apiVersion: object.gdc.goog/v1alpha1
    kind: Bucket
    metadata:
      name: BUCKET_NAME
      namespace: NAMESPACE_NAME
    spec:
      description: DESCRIPTION
      storageClass: standard-rwo
      bucketPolicy :
        lockingPolicy :
          defaultObjectRetentionDays: RETENTION_DAY_COUNT

Para obtener más detalles, consulta la referencia de la API de Bucket.

Enumera los buckets de almacenamiento

Para enumerar todos los buckets a los que tienes acceso en un arrendatario de almacenamiento de objetos determinado, completa los siguientes pasos:

1. Ejecuta los siguientes comandos para enumerar todos los buckets:

   kubectl get buckets --all-namespaces
   kubectl get buckets --namespace NAMESPACE_NAME
   

Borrar buckets de almacenamiento

Puedes borrar buckets de almacenamiento con la CLI. Los buckets deben estar vacíos antes de que puedas borrarlos.

1. Usa el comando GET o DESCRIBE en la sección Ver configuración del bucket para obtener el nombre completamente calificado del bucket.

2. Si el bucket no está vacío, vacíalo:

   s3cmd rm --recursive -—force s3://FULLY_QUALIFIED_BUCKET_NAME
   

3. Borra el bucket vacío:

   kubectl delete buckets/BUCKET_NAME --namespace NAMESPACE_NAME
   

Cómo ver la configuración del bucket

Usa cualquiera de los siguientes comandos para ver los detalles de configuración de un bucket:

    kubectl describe buckets/BUCKET_NAME --namespace NAMESPACE_NAME

    kubectl get buckets/BUCKET_NAME --namespace NAMESPACE_NAME -o yaml

Cómo establecer un período de retención de objetos

De forma predeterminada, puedes borrar objetos en cualquier momento. Habilita el bloqueo de objetos con un período de retención para evitar que se borren todos los objetos del bucket durante la cantidad de días especificada. No puedes borrar un bucket hasta que borres todos los objetos después del período de retención.

Debes habilitar el bloqueo de objetos cuando crees el bucket. No puedes habilitar ni inhabilitar el bloqueo de objetos después de crear un bucket. Sin embargo, puedes modificar el período de retención predeterminado del objeto.

Puedes crear un bucket con o sin habilitar el bloqueo de objetos. Si habilitaste el bloqueo de objetos, especificar un período de retención predeterminado es opcional.

Para modificar el período de retención, actualiza el campo Bucket.spec.bucketPolicy.lockingPolicy.defaultObjectRetentionDays en el recurso Bucket.

A continuación, se muestra un ejemplo de cómo actualizar el campo en el recurso Bucket:

apiVersion: object.gdc.goog/v1alpha1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This bucket has a default retention period specified."
  storageClass: standard-rwo
  bucketPolicy :
    lockingPolicy :
      defaultObjectRetentionDays: RETENTION_DAY_COUNT
---
apiVersion: object.gdc.goog/v1alpha1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This would enable object locking but not specify a default retention period."
  storageClass: standard-rwo
  bucketPolicy :
    lockingPolicy :
---
apiVersion: object.gdc.goog/v1alpha1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This bucket does not have locking or retention enabled."
  storageClass: standard-rwo

Las actualizaciones del período de retención se aplican a los objetos creados en el bucket después de la actualización. En el caso de los objetos existentes, el período de retención no cambia.

Cuando habilitas el bloqueo de objetos, si intentas reemplazar un objeto, agregas una nueva versión de este. Puedes recuperar ambas versiones del objeto. Para obtener detalles sobre cómo enumerar versiones de objetos, consulta ListObjectVersions en la documentación de Amazon Web Services: https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html

Para crear un bucket de escritura única y lectura múltiple (WORM), consulta la sección Bucket WORM.

Cómo otorgar acceso al bucket

Puedes proporcionar acceso a bucket a otros usuarios o cuentas de servicio creando y aplicando RoleBindings con roles predefinidos.

Funciones predefinidas

• project-bucket-object-viewer: Este rol permite que un usuario enumere todos los buckets del proyecto, enumere los objetos de esos buckets y lea los objetos y los metadatos de objetos. Este rol no te permite realizar operaciones de escritura en objetos, como subir, reemplazar o borrar.

• project-bucket-object-admin: Este rol permite que un usuario enumere todos los buckets del proyecto y realice operaciones de lectura y escritura en objetos, como subir, reemplazar o borrar.

• project-bucket-admin: Este rol permite a los usuarios administrar todos los buckets en el espacio de nombres determinado, así como todos los objetos en esos buckets.

Para ver una lista completa de los permisos otorgados para estos roles, consulta la sección permisos de roles predeterminados.

Para obtener los permisos que necesitas para crear vinculaciones de roles del proyecto, pídele a tu administrador de IAM del proyecto que te otorgue el rol de administrador de IAM del proyecto (project-iam-admin).

A continuación, se muestra un ejemplo de cómo crear un objeto RoleBinding para otorgar acceso a un usuario y a una cuenta de servicio:

1. Crea un archivo YAML en tu sistema, como rolebinding-object-admin-all-buckets.yaml.

    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      namespace: NAMESPACE_NAME
      name: readwrite-all-buckets
    roleRef:
      kind: Role
      name: project-bucket-object-admin
      apiGroup: rbac.authorization.k8s.io
    subjects:
    - kind: ServiceAccount
      namespace: NAMESPACE_NAME
      name: SA_NAME
    - kind: User
      namespace: NAMESPACE_NAME
      name: [e-mail]  # Could be bob or [e-mail] based on your organization settings.
      apiGroup: rbac.authorization.k8s.io
    ```
   

2. Aplica el archivo YAML:

   kubectl apply \
   -f rolebinding-object-admin-all-buckets.yaml
   

Obtén credenciales de acceso al bucket

Cuando otorgas acceso a un bucket, las credenciales de acceso se crean en un secreto.

El formato del nombre del secreto es object-storage-key-SUBJECT_TYPE-SUBJECT_HASH.

• Los valores de SUBJECT_TYPE son los siguientes:
  • user: El usuario
  • sa: Es el ServiceAccount.
• SUBJECT_HASH es el hash SHA256 codificado en base32 del nombre del sujeto.

Por ejemplo, el usuario [e-mail] tiene el secreto llamado:

object-storage-key-user-oy6jdqd6bxfoqcecn2ozv6utepr5bgh355vfku7th5pmejqubdja

Accede al secreto del usuario

Para un sujeto de usuario, el Secret se encuentra en el espacio de nombres object-storage-access-keys del clúster de administrador raíz.

1. Busca el nombre del secreto:

   kubectl auth can-i --list --namespace object-storage-access-keys | grep object-storage-key-
   

   Obtendrás un resultado similar al siguiente:

   secrets        []        [object-storage-key-nl-user-oy6jdqd6bxfoqcecn2ozv6utepr5bgh355vfku7th5pmejqubdja,object-storage-key-std-user-oy6jdqd6bxfoqcecn2ozv6utepr5bgh355vfku7th5pmejqubdja]        [get]
   

2. Obtén el contenido del Secret correspondiente para acceder a los buckets:

   kubectl get -o yaml --namespace object-storage-access-keys secret
   object-storage-key-rm-user-oy6jdqd6bxfoqcecn2ozv6utepr5bgh355vfku7th5pmejqubdja
   

   Obtendrás un resultado similar al siguiente:

   data:
     access-key-id: MEhYM08wWUMySjcyMkVKTFBKRU8=
     create-time: MjAyMi0wNy0yMiAwMTowODo1OS40MTQyMTE3MDMgKzAwMDAgVVRDIG09KzE5OTAuMzQ3OTE2MTc3
     secret-access-key: Ump0MVRleVN4SmhCSVJhbmlnVDAwbTJZc0IvRlJVendqR0JuYVhiVA==
   

3. Decodifica el ID de clave de acceso y el secreto:

   echo "MEhYM08wWUMySjcyMkVKTFBKRU8=" | base64 -d \
       && echo \
       && echo "Ump0MVRleVN4SmhCSVJhbmlnVDAwbTJZc0IvRlJVendqR0JuYVhiVA==" | base64 -d
   

   Obtendrás un resultado similar al siguiente:

   0HX3O0YC2J722EJLPJEO
   Rjt1TeySxJhBIRanigT00m2YsB/FRUzwjGBnaXbT
   

4. Sigue la sección Configura s3cmd con la información resultante.

Accede al secreto de la cuenta de servicio

En el caso de un sujeto de cuenta de servicio (SA), el secreto se encuentra en el mismo espacio de nombres que el bucket. Para encontrar el nombre, ejecuta el siguiente comando:

  kubectl get --namespace NAMESPACE_NAME secrets -o=jsonpath=
  '{.items[?(@.metadata.annotations.object\.gdc\.goog/subject=="SA_NAME")].metadata.name}'

Obtendrás un resultado similar al siguiente:

  object-storage-key-rm-sa-mng3olp3vsynhswzasowzu3jgzct2ert72pjp6wsbzqhdwckwzbq

Puedes hacer referencia al Secret en tu Pod como variables de entorno (https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-environment-variables) o archivos (https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod).

Permisos de roles predeterminados

Permisos de project-bucket-object-viewer

Este rol otorga permisos para obtener y enumerar objetos y sus metadatos en el bucket.

La función project-bucket-object-viewer tiene los siguientes permisos:

• Permisos de la API de Bucket:

  1. Obtener
  2. Lista
  3. Mirar

• Permisos de almacenamiento de objetos de S3:

  1. GetObject
  2. GetObjectAcl
  3. GetObjectVersion
  4. ListBucket
  5. ListBucketVersions
  6. ListBucketMultipartUploads
  7. ListMultipartUploadParts

Permisos de administrador de objetos y bucket del proyecto

Este rol otorga permisos para colocar y borrar objetos, versiones de objetos y etiquetas en el bucket. Además, también otorga todos los permisos en project-bucket-object-viewer.

El rol project-bucket-object-admin tiene los siguientes permisos de almacenamiento de objetos:

• Permisos de almacenamiento de objetos de S3:

  1. AbortMultipartUpload
  2. DeleteObject
  3. DeleteObjectVersion
  4. PutObject
  5. RestoreObject

Permisos de administrador de bucket del proyecto

Este rol otorga permisos para crear, actualizar o borrar recursos de Bucket en el espacio de nombres del proyecto. Además, también otorga todos los permisos en project-bucket-object-admin.

La función project-bucket-object-admin tiene los siguientes permisos:

• Permisos de la API de Bucket:

  1. Crear
  2. Actualizar
  3. Borrar

Crea un bucket WORM

Un bucket WORM garantiza que nada más sobrescriba los objetos y los retiene durante un período mínimo. El registro de auditoría es un ejemplo de caso de uso para un bucket WORM.

Nota: Si intentas reemplazar un objeto en un bucket WORM, agregarás una versión nueva del objeto. Solo después de que finalice el período de retención de un objeto WORM, según lo indica la política de bloqueo del bucket, puedes proceder con la eliminación del objeto, el bucket y el proyecto.

Sigue estos pasos para crear un bucket WORM:

1. Establece un período de retención cuando crees el bucket. Por ejemplo, el siguiente bucket de ejemplo tiene un período de retención de 365 días.

   apiVersion: object.gdc.goog/v1alpha1
   kind: Bucket
   metadata:
     name: foo logging-bucket
     namespace: foo-service
   spec:
     description: "Audit logs for foo"
     storageClass: standard-rwo
     bucketPolicy :
       lockingPolicy :
         defaultObjectRetentionDays: 365
   

2. Otorga el rol project-bucket-object-viewer a todos los usuarios que necesiten acceso de solo lectura:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     namespace: foo-service
     name: object-readonly-access
   roleRef:
     kind: Role
     name: project-bucket-object-viewer
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - kind: ServiceAccount
     namespace: foo-service
     name: foo-log-processor
   - kind: User
     name: [e-mail]
     apiGroup: rbac.authorization.k8s.io
   

3. Otorga el rol project-bucket-object-admin a los usuarios que necesitan escribir contenido en el bucket:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     namespace: foo-service
     name: object-write-access
   roleRef:
     kind: Role
     name: project-bucket-object-viewer
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - kind: ServiceAccount
     namespace: foo-service
     name: foo-service-account
   

Restablece el almacenamiento de objetos en el sistema de archivos del almacenamiento en bloque

Asigna un volumen persistente

Para restablecer archivos desde un extremo de almacenamiento de objetos, sigue estos pasos:

1. Asigna un volumen persistente (PV) como destino en el restablecimiento. Usa un reclamo de volumen persistente (PVC) para asignar el volumen, como se muestra en el siguiente ejemplo:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: restore-pvc
     namespace: restore-ns
   spec:
     storageClassName: standard-rwo
     accessModes:
   ReadWriteOnce
     resources:
       requests:
         storage: 1Gi # Need sufficient capacity for full restoration.
   

2. Verifica el estado del PVC:

   kubectl get pvc restore-pvc -n restore-ns
   

   Una vez que el PVC se encuentra en estado Bound, está listo para consumirse dentro del Pod que lo rehidrata.

3. Si un conjunto de Stateful finalmente consume el PV, debes hacer coincidir los PVC de StatefulSet renderizados. Los Pods que produce StatefulSet consumen los volúmenes hidratados. En el siguiente ejemplo, se muestran plantillas de reclamo de volumen en un StatefulSet llamado ss.

     volumeClaimTemplates:
     - metadata:
         name: pvc-name
       spec:
         accessModes: [ "ReadWriteOnce" ]
         storageClassName: standard-rwo
         resources:
           requests:
             storage: 1Gi
   

4. Asigna previamente PVC con nombres como ss-pvc-name-0 y ss-pvc-name-1 para garantizar que los Pods resultantes consuman los volúmenes asignados previamente.

Hidrata el volumen persistente (PV)

Después de que el PVC se vincule a un PV, inicia Job para propagar el PV:

apiVersion: batch/v1
kind: Job
metadata:
  name: transfer-job
  namespace: transfer
spec:
  template:
    spec:
      serviceAccountName: data-transfer-sa
      volumes:
      - name: data-transfer-restore-volume
        persistentVolumeClaim:
          claimName: restore-pvc
      containers:
      - name: storage-transfer-pod
        image: gcr.io/private-cloud-staging/storage-transfer:latest
        command: /storage-transfer
        args:
        - --src_endpoint=https://your-src-endpoint.com
        - --src_path=/your-src-bucket
        - --src_credentials=transfer/src-secret
        - --dst_path=/restore-pv-mnt-path
        - --src_type=s3
        - --dst_type=local
      volumeMounts:
      - mountPath: /restore-pv-mnt-path
        name: data-transfer-restore-volume

Una vez que finaliza la ejecución de Job, los datos del bucket de almacenamiento de objetos completan el volumen. Un pod independiente puede consumir los datos con los mismos mecanismos estándar para montar un volumen.