Transferir dados do Cloud Storage durante o provisionamento dinâmico usando o GKE Volume Populator

Autopilot Standard

---

O GKE Volume Populator só está disponível por convite. Se você quiser solicitar acesso ao Populador de volumes do GKE no seu Google Cloud projeto, entre em contato com seu representante de vendas.

O Volume Populator do GKE permite pré-carregar dados de um armazenamento de origem para um PersistentVolumeClaim de destino durante o provisionamento dinâmico, sem a necessidade de executar scripts ou comandos CLI adicionais para transferência manual de dados. Esse recurso automatiza e simplifica o processo de transferência de dados usando o Kubernetes Volume Populator. Ela oferece portabilidade de dados perfeita para que você possa trocar os tipos de armazenamento e se beneficiar de otimizações de preço ou desempenho.

Use esse recurso se você precisar transferir grandes quantidades de dados de buckets do Cloud Storage para um PersistentVolumeClaim com suporte de outro Google Cloud tipo de armazenamento (como Parallelstore).

Você interage principalmente com o GKE Volume Populator usando a CLI gcloud e a CLI kubectl. O Volume Populator do GKE é compatível com clusters do Autopilot e Standard. Não é necessário ativar o Populador de volume do GKE. É um componente gerenciado pelo GKE ativado por padrão.

Vantagens

• Se você quiser aproveitar a performance de um sistema de arquivos paralelo gerenciado, mas seus dados estiverem armazenados no Cloud Storage, use o Populator de volume do GKE para simplificar a transferência de dados.
• O Volume Populator do GKE permite a portabilidade de dados. Você pode mover dados de acordo com suas necessidades.
• O Volume Populator do GKE oferece suporte à autenticação baseada no IAM para que você possa transferir dados e manter o controle de acesso refinado.

O diagrama mostra como os dados fluem do armazenamento de origem para o de destino e a criação do PersistentVolume para o armazenamento de destino usando o GKE Volume Populator.

Limitações

• O Volume Populator do GKE só oferece suporte a buckets do Cloud Storage como o armazenamento de origem e instâncias do Parallelstore como o tipo de armazenamento de destino.
• O Volume Populator do GKE só oferece suporte a recursos StorageClass com volumeBindingMode definido como Immediate.
• O recurso personalizado GCPDataSource precisa estar no mesmo namespace que a carga de trabalho do Kubernetes. Não há suporte para volumes com fontes de dados de namespace cruzado.
• O GKE Volume Populator oferece suporte apenas à federação de identidade da carga de trabalho para GKE vinculação de contas de serviço do IAM a uma conta de serviço do Kubernetes. Não é possível conceder permissões do IAM diretamente à conta de serviço do Kubernetes.

Antes de começar

Antes de começar, veja se você realizou as seguintes tarefas:

• Ative a API Parallelstore e a API Google Kubernetes Engine.
Ativar APIs
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a gcloud CLI anteriormente, instale a versão mais recente executando gcloud components update.
  Observação: para instalações atuais da gcloud CLI, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

• Consulte a visão geral do driver CSI do Parallelstore para ver as limitações e os requisitos.
• Crie buckets do Cloud Storage, preenchidos com os dados que você quer transferir.

Requisitos

Para usar o Volume Populator do GKE, os clusters precisam atender aos seguintes requisitos:

• Use o cluster do GKE versão 1.31.1-gke.1729000 ou mais recente.
• O driver CSI do Parallelstore está ativado. O GKE ativa o driver CSI por padrão em clusters novos e atuais do GKE Autopilot. Em clusters novos e atualizados do Standard, é necessário ativar o driver CSI.

Prepare o ambiente

Esta seção aborda as etapas para criar clusters do GKE e configurar as permissões necessárias para usar o Volume Populator do GKE.

Configurar a rede VPC

Observação: se você já configurou sua rede VPC como parte da configuração do driver CSI do Parallelstore, pule esta seção.

É necessário especificar a mesma rede de nuvem privada virtual (VPC) ao criar a instância do Parallelstore e as VMs do Compute Engine ou clusters do GKE do cliente. Para permitir que a VPC se conecte de forma privada aos serviços do Google Cloud sem expor o tráfego à Internet pública, você precisa fazer uma configuração única do acesso a serviços privados (PSA, na sigla em inglês), se ainda não tiver feito isso.

Para configurar a PSA, siga estas etapas:

1. Configure a permissão do IAM Administrador de rede do Compute (roles/compute.networkAdmin) para configurar o peering de rede do seu projeto.

   Para conceder o papel, execute o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="user:EMAIL_ADDRESS" \
       --role=roles/compute.networkAdmin
   

   Substitua EMAIL_ADDRESS pelo seu endereço de e-mail.

2. Ative a rede de serviços:

   gcloud services enable servicenetworking.googleapis.com
   

3. Crie uma rede VPC:

   gcloud compute networks create NETWORK_NAME \
     --subnet-mode=auto \
     --mtu=8896 \
     --project=PROJECT_ID
   

   Substitua:

   • NETWORK_NAME: o nome da rede VPC em que você vai criar a instância do Parallelstore.
   • PROJECT_ID: o ID do projeto do Google Cloud .
   Observação: definir o valor de mtu (unidade máxima de transmissão, ou o tamanho do maior pacote IP que pode ser transmitido nessa rede) para o valor máximo permitido de 8896 melhora o desempenho em até 10% em comparação com o valor padrão de 1.460 bytes.

4. Crie um intervalo de IP.

   O acesso a serviços privados exige um intervalo de endereços IP (bloco CIDR) com um comprimento de prefixo de pelo menos /24 (256 endereços). O Parallelstore reserva 64 endereços por instância, o que significa que você pode reutilizar esse intervalo de IP com outros serviços ou outras instâncias do Parallelstore, se necessário.

   gcloud compute addresses create IP_RANGE_NAME \
     --global \
     --purpose=VPC_PEERING \
     --prefix-length=24 \
     --description="Parallelstore VPC Peering" \
     --network=NETWORK_NAME \
     --project=PROJECT_ID
   

   Substitua IP_RANGE_NAME pelo nome do intervalo de IP da rede VPC.

5. Defina uma variável de ambiente com o intervalo CIDR associado ao intervalo criado na etapa anterior:

   CIDR_RANGE=$(
     gcloud compute addresses describe IP_RANGE_NAME \
       --global  \
       --format="value[separator=/](address, prefixLength)" \
       --project=PROJECT_ID \
   )
   

6. Crie uma regra de firewall para permitir o tráfego TCP do intervalo de IP que você criou:

   gcloud compute firewall-rules create FIREWALL_NAME \
     --allow=tcp \
     --network=NETWORK_NAME \
     --source-ranges=$CIDR_RANGE \
     --project=PROJECT_ID
   

   Substitua FIREWALL_NAME pelo nome da regra de firewall para permitir o tráfego TCP do intervalo de IP que você vai criar.

7. Conecte o peering:

   gcloud services vpc-peerings connect \
     --network=NETWORK_NAME \
     --ranges=IP_RANGE_NAME \
     --project=PROJECT_ID \
     --service=servicenetworking.googleapis.com
   

Se você tiver problemas ao configurar a rede VPC, consulte o guia de solução de problemas da Parallelstore.

Criar seu cluster do GKE

Recomendamos que você use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Escolher um modo de operação do GKE.

Piloto automático

Para criar um cluster do GKE usando o Autopilot, execute o seguinte comando:

gcloud container clusters create-auto CLUSTER_NAME  \
    --network=NETWORK_NAME  \
    --cluster-version=CLUSTER_VERSION \
    --location=CLUSTER_LOCATION

O GKE ativa a federação de identidade da carga de trabalho para o GKE e o driver CSI do Parallelstore por padrão nos clusters do Autopilot.

Substitua os seguintes valores:

• CLUSTER_NAME: o nome do cluster.
• CLUSTER_VERSION : o número da versão do GKE. É preciso especificar 1.31.1-gke.1729000 ou posterior.
• NETWORK_NAME: o nome da rede VPC criada para a instância do Parallelstore. Para saber mais, consulte Configurar uma rede VPC.
• CLUSTER_LOCATION: a região em que você quer criar o cluster. Recomendamos que você crie o cluster em um local do Parallelstore com suporte para melhor desempenho. Se você quiser criar seu cluster em um local de Parallelstore sem suporte, ao criar um StorageClass de Parallelstore, especifique uma topologia personalizada que use o local de Parallelstore com suporte. Caso contrário, o provisionamento vai falhar.

Padrão

Crie um cluster padrão com o driver CSI do Parallelstore e a federação de identidade da carga de trabalho para GKE ativados usando o seguinte comando:

gcloud container clusters create CLUSTER_NAME \
    --addons=ParallelstoreCsiDriver \
    --cluster-version=CLUSTER_VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --network=NETWORK_NAME \
    --location=CLUSTER_LOCATION

Substitua os seguintes valores:

• CLUSTER_NAME: o nome do cluster.
• CLUSTER_VERSION: o número da versão do GKE. É preciso especificar 1.31.1-gke.1729000 ou posterior.
• PROJECT_ID: o ID do projeto do Google Cloud .
• NETWORK_NAME: o nome da rede VPC criada para a instância do Parallelstore. Para saber mais, consulte Configurar uma rede VPC.
• CLUSTER_LOCATION: a região ou zona em que você quer criar o cluster. Recomendamos que você crie o cluster em um local do Parallelstore com suporte para melhor desempenho. Se você quiser criar seu cluster em um local de Parallelstore sem suporte, ao criar um StorageClass de Parallelstore, especifique uma topologia personalizada que use o local de Parallelstore com suporte. Caso contrário, o provisionamento vai falhar.

Configurar as permissões necessárias

Para transferir dados de um bucket do Cloud Storage, é necessário configurar permissões para a Federação de Identidade da Carga de Trabalho para GKE.

1. Crie um namespace do Kubernetes:

   kubectl create namespace NAMESPACE
   

   Substitua NAMESPACE pelo namespace em que as cargas de trabalho serão executadas.

2. Crie uma conta de serviço do Kubernetes.

   kubectl create serviceaccount KSA_NAME \
       --namespace=NAMESPACE
   

   Substitua KSA_NAME pelo nome da conta de serviço do Kubernetes que seu pod usa para autenticar nas APIs do Google Cloud .

   Atenção: reutilizar essa conta de serviço do Kubernetes em uma carga de trabalho no mesmo namespace permite que o pod acesse o bucket do Cloud Storage. Recomendamos não reutilizar essa conta de serviço para cargas de trabalho no namespace.

3. Crie uma conta de serviço do IAM. Também é possível usar qualquer conta de serviço do IAM em qualquer projeto da sua organização:

   gcloud iam service-accounts create IAM_SA_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • IAM_SA_NAME: o nome da sua conta de serviço do IAM.
   • PROJECT_ID: o ID do projeto do Google Cloud .

4. Conceda à conta de serviço do IAM o papel roles/storage.objectViewer para que ela possa acessar seu bucket do Cloud Storage:

   gcloud storage buckets \
       add-iam-policy-binding gs://GCS_BUCKET \
       --member "serviceAccount:IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role "roles/storage.objectViewer"
   

   Substitua GCS_BUCKET pelo nome do bucket do Cloud Storage.

5. Crie a política de permissão do IAM que conceda à conta de serviço do Kubernetes acesso para personificar a conta de serviço do IAM:

   gcloud iam service-accounts \
       add-iam-policy-binding IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --role roles/iam.workloadIdentityUser \
       --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
   

6. Anote a conta de serviço do Kubernetes para que o GKE veja o link entre as contas de serviço.

   kubectl annotate serviceaccount KSA_NAME \
       --namespace NAMESPACE \
       iam.gke.io/gcp-service-account=IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   

7. Crie a identidade do serviço do Parallelstore:

   gcloud beta services identity create \
       --service=parallelstore.googleapis.com \
       --project=PROJECT_ID
   

8. Conceda à identidade do serviço do Parallelstore o papel roles/iam.serviceAccountTokenCreator para permitir que ele represente a conta de serviço do IAM. Defina a variável de ambiente PROJECT_NUMBER para poder usá-la nas etapas seguintes.

   export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   gcloud iam service-accounts \
       add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
       --role=roles/iam.serviceAccountTokenCreator
   

   O valor PROJECT_NUMBER é o identificador exclusivo gerado automaticamente para seu projeto. Para encontrar esse valor, consulte Como criar e gerenciar projetos.

9. Conceda o papel roles/iam.serviceAccountUser à identidade do serviço do Parallelstore para que ela possa acessar todos os recursos a que a conta de serviço do IAM tem acesso:

   gcloud iam service-accounts \
       add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
       --role=roles/iam.serviceAccountUser
   

10. Conceda à identidade do serviço do GKE o papel roles/iam.serviceAccountUser para permitir que ela acesse todos os recursos que a conta de serviço do IAM pode acessar. Esta etapa não é necessária se o cluster do GKE e a conta de serviço do IAM estiverem no mesmo projeto.

    gcloud iam service-accounts \
        add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --member=serviceAccount:"service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
        --role=roles/iam.serviceAccountUser
    

Criar um volume do Parallelstore com dados pré-carregados

As seções a seguir descrevem o processo típico de criação de um volume do Parallelstore com dados pré-carregados de um bucket do Cloud Storage, usando o Populador de volume do GKE.

1. Crie um recurso GCPDataSource.
2. Crie um StorageClass do Parallelstore.
3. Crie um PersistentVolumeClaim para acessar o volume.
4. Verifique se o provisionamento do PersistentVolumeClaim foi concluído.
5. (Opcional) Confira o andamento da transferência de dados.
6. Criar uma carga de trabalho que consuma o volume.

Criar um recurso GCPDataSource

Para usar o Volume Populator do GKE, crie um recurso personalizado GCPDataSource. Esse recurso define as propriedades de armazenamento de origem a serem usadas para a população de volume.

1. Salve o manifesto em um arquivo chamado gcpdatasource.yaml.

   apiVersion: datalayer.gke.io/v1
   kind: GCPDataSource
   metadata:
     name: GCP_DATA_SOURCE
     namespace: NAMESPACE
   spec:
     cloudStorage:
       serviceAccountName: KSA_NAME
       uri: gs://GCS_BUCKET/
   

   Substitua os seguintes valores:

   • GCP_DATA_SOURCE: o nome do CRD GCPDataSource que contém uma referência ao bucket do Cloud Storage. Consulte a referência do CRD GCPDataSource para mais detalhes.
   • NAMESPACE: o namespace em que as cargas de trabalho serão executadas. O valor do namespace precisa ser igual ao namespace da carga de trabalho.
   • KSA_NAME: o nome da conta de serviço do Kubernetes que o pod usa para autenticação nas APIs do Google Cloud . O valor cloudStorage.serviceAccountName deve ser a conta de serviço do Kubernetes que você configurou para a Federação de Identidade da Carga de Trabalho para GKE na etapa Configurar as permissões necessárias.
   • GCS_BUCKET: seu nome do bucket do Cloud Storage Como alternativa, você também pode especificar gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ para o campo uri.

2. Crie o recurso GCPDataSource executando este comando:

   kubectl apply -f gcpdatasource.yaml
   

Criar um StorageClass do Parallelstore

Crie um StorageClass para direcionar o driver CSI do Parallelstore a provisionar instâncias do Parallelstore na mesma região do cluster do GKE. Isso garante o desempenho ideal de E/S.

1. Salve o seguinte manifesto parallelstore-class.yaml como : Verifique se o campo volumeBindingMode na definição de StorageClass está definido como Immediate.

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: parallelstore-class
   provisioner: parallelstore.csi.storage.gke.io
   volumeBindingMode: Immediate
   reclaimPolicy: Delete
   

2. Crie o StorageClass executando este comando:

   kubectl apply -f parallelstore-class.yaml
   

Se você quiser criar um StorageClass personalizado com uma topologia específica, consulte o guia do CSI do Parallelstore.

Criar um PersistentVolumeClaim para acessar o volume

O arquivo de manifesto a seguir mostra um exemplo de como criar um PersistentVolumeClaim no modo de acesso ReadWriteMany que faz referência ao StorageClass criado anteriormente.

1. Salve o manifesto em um arquivo chamado volume-populator-pvc.yaml.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: PVC_NAME
     namespace: NAMESPACE
   spec:
     accessModes:
     - ReadWriteMany
     storageClassName: parallelstore-class
     resources:
       requests:
         storage: 12Gi
     dataSourceRef:
       apiGroup: datalayer.gke.io
       kind: GCPDataSource
       name: GCP_DATA_SOURCE
   

   Substitua os seguintes valores:

   • PVC_NAME: o nome do PersistentVolumeClaim para onde você quer transferir seus dados. O PersistentVolumeClaim precisa ser apoiado por uma instância do Parallelstore.
   • NAMESPACE: o namespace em que as cargas de trabalho serão executadas. O valor do namespace precisa ser igual ao namespace da carga de trabalho.
   • GCP_DATA_SOURCE: o nome do CRD GCPDataSource que contém uma referência ao bucket do Cloud Storage. Consulte a referência do CRD GCPDataSource para mais detalhes.

2. Crie o PersistentVolumeClaim executando o seguinte comando:

   kubectl apply -f volume-populator-pvc.yaml
   

O GKE não vai programar o pod de carga de trabalho até que o provisionamento do PersistentVolumeClaim seja concluído. Para conferir o andamento da transferência de dados, consulte Conferir o andamento da transferência de dados. Se você encontrar erros durante o provisionamento, consulte Solução de problemas.

Verificar se o provisionamento do PersistentVolumeClaim foi concluído

Atenção: se você estiver usando o Autopilot, antes de realizar essa verificação, crie uma carga de trabalho que consuma o volume. Essa etapa é necessária para acionar o GKE e criar um nó. Se isso não for feito, um erro como este poderá ser gerado e persistir por vários minutos: "error generating accessibility requirements: no available topology found".

O Volume Populator do GKE usa um PersistentVolumeClaim temporário no namespace gke-managed-volumepopulator para provisionamento de volume.

O PersistentVolumeClaim temporário é basicamente um snapshot do PersistentVolumeClaim que ainda está em trânsito (aguardando a carga completa dos dados). O nome tem o formato prime-YOUR_PVC_UID.

Para verificar o status:

1. Execute os comandos a seguir:

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   
   kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator
   

   Se a saída estiver vazia, isso significa que o PersistentVolumeClaim temporário não foi criado. Nesse caso, consulte a seção Solução de problemas.

   Se o provisionamento for bem-sucedido, a saída será semelhante a esta. Procure o registro ProvisioningSucceeded:

   Warning  ProvisioningFailed     9m12s                   parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = context deadline exceeded
   Warning  ProvisioningFailed     3m41s (x11 over 9m11s)  parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = Volume pvc-808e41a4-b688-4afe-9131-162fe5d672ec not ready, current state: CREATING
   Normal   ExternalProvisioning   3m10s (x43 over 13m)    persistentvolume-controller                                                                                  Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
   Normal  Provisioning  8s (x13 over 10m)  "xxx"  External provisioner is provisioning volume for claim "xxx"
   Normal  ProvisioningSucceeded  7s  "xxx"  Successfully provisioned volume "xxx"
   

   Observação: os avisos na saída são esperados, porque o provisionamento de CSI está tentando reconciliar o estado de provisionamento de volume. O provisionamento de volume do Parallelstore geralmente leva cerca de 10 minutos.

2. Verifique se a criação da instância do Parallelstore foi iniciada.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=-
   

   A resposta será semelhante a esta: Verifique se o volume está no estado CREATING. Quando a criação da instância do Parallelstore for concluída, o estado mudará para ACTIVE.

   "projects/PROJECT_ID/locations/<my-location>/<my-volume>"  12000  2024-10-09T17:59:42.582857261Z  2024-10-09T17:59:42.582857261Z  CREATING  projects/PROJECT_ID/global/NETWORK_NAME
   

Se o provisionamento falhar, consulte o guia de solução de problemas do Parallelstore para mais orientações.

(Opcional) Conferir o andamento da transferência de dados

Esta seção mostra como acompanhar o progresso das transferências de dados de um bucket do Cloud Storage para um volume do Parallelstore. Isso pode ser feito para monitorar o status da transferência e garantir que os dados sejam copiados com sucesso. Você também precisa executar esse comando se a operação de vinculação do PersistentVolumeClaim estiver demorando muito.

1. Verifique o status do PersistentVolumeClaim executando o seguinte comando:

   kubectl describe pvc PVC_NAME -n NAMESPACE
   

2. Verifique a mensagem de eventos do PersistentVolumeClaim para encontrar o progresso da transferência de dados. O GKE registra as mensagens aproximadamente uma vez por minuto. A resposta será semelhante a:

   Reason                          Message
   ------                          -------
   PopulateOperationStartSuccess   Populate operation started
   PopulateOperationStartSuccess   Populate operation started
   Provisioning                    External provisioner is provisioning volume for claim "my-namespace/my-pvc"
   Provisioning                    Assuming an external populator will provision the volume
   ExternalProvisioning            Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
   PopulateOperationStartSuccess   Populate operation started
   PopulatorPVCCreationProgress    objects found 7, objects copied 7, objects skipped 0. bytes found 1000020010, bytes copied 1000020010, bytes skipped 0
   PopulateOperationFinished       Populate operation finished
   PopulatorFinished               Populator finished
   

Pode levar algum tempo para que a operação de preenchimento seja iniciada. Essa operação depende do tamanho do arquivo. Se você não notar nenhum progresso na transferência de dados após vários minutos, consulte a seção Solução de problemas.

Criar uma carga de trabalho que consuma o volume

Esta seção mostra um exemplo de como criar um pod que consome o recurso PersistentVolumeClaim criado anteriormente.

1. Salve o seguinte manifesto YAML para seu pod como pod.yaml.

   apiVersion: v1
   kind: Pod
   metadata:
     name: POD_NAME
     namespace: NAMESPACE
   spec:
     volumes:
     - name: parallelstore-volume
       persistentVolumeClaim:
         claimName: PVC_NAME
     containers:
     - image: nginx
       name: nginx
       volumeMounts:
       - name: parallelstore-volume
         mountPath: /mnt/data
   

   Substitua os seguintes valores:

   • POD_NAME: o nome do pod que executa sua carga de trabalho.
   • NAMESPACE: o namespace em que as cargas de trabalho serão executadas. O valor do namespace precisa ser igual ao namespace da carga de trabalho.
   • PVC_NAME: o nome do PersistentVolumeClaim para onde você quer transferir seus dados. O PersistentVolumeClaim precisa ser apoiado por uma instância do Parallelstore.

2. Execute o comando a seguir para aplicar o manifesto ao cluster:

   kubectl apply -f pod.yaml
   

3. Verifique o status do pod e aguarde até que ele seja RUNNING. O PersistentVolumeClaim precisa ser vinculado antes que a carga de trabalho possa ser executada.

   kubectl describe pod POD_NAME -n NAMESPACE
   

4. Verifique se os arquivos foram transferidos e podem ser acessados pela carga de trabalho.

   kubectl exec -it POD_NAME -n NAMESPACE -c nginx -- /bin/sh
   

   Mude para o diretório /mnt/data e execute ls:

   cd /mnt/data
   ls
   

   A saída vai listar todos os arquivos que existem no URI do bucket do Cloud Storage.

Excluir um PersistentVolumeClaim durante o provisionamento dinâmico

Se você precisar excluir o PersistentVolumeClaim enquanto os dados ainda estão sendo transferidos durante o provisionamento dinâmico, terá duas opções: exclusão suave e forçada.

A exclusão suave exige menos esforço, mas pode levar mais tempo e não considera a configuração incorreta do usuário que impede a conclusão da transferência de dados. A exclusão forçada oferece uma alternativa mais rápida que permite maior flexibilidade e controle. Essa opção é adequada quando você precisa reiniciar ou corrigir rapidamente as configurações incorretas.

Exclusão suave

Use essa opção de exclusão para garantir que o processo de transferência de dados seja concluído antes que o GKE exclua os recursos associados.

1. Exclua o pod da carga de trabalho, se ele existir, executando este comando:

   kubectl delete pod POD_NAME -n NAMESPACE
   

2. Encontre o nome do PersistentVolumeClaim temporário:

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   

3. Encontre o nome do PersistentVolume:

   PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   
   echo ${PV_NAME?}
   

   Se a saída estiver vazia, significa que o PersistentVolume ainda não foi criado.

4. Execute este comando para excluir o PersistentVolumeClaim. O finalizador bloqueia a operação de exclusão. Pressione Ctrl+C e avance para a próxima etapa.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

   Aguarde a conclusão da transferência de dados. O GKE vai excluir o PersistentVolumeClaim, o PersistentVolume e a instância do Parallelstore.

5. Verifique se os recursos temporários PersistentVolumeClaim, PersistentVolumeClaim e PersistentVolume foram excluídos:

   kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
   

6. Verifique se a instância do Parallelstore foi excluída. A instância do Parallelstore vai compartilhar o mesmo nome do PersistentVolume. Não será necessário executar este comando se você confirmou na etapa 3 que o PersistentVolume não foi criado.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=- | grep ${PV_NAME?}
   

Exclusão forçada

Use essa opção de exclusão quando precisar excluir um PersistentVolumeClaim e os recursos associados antes que o processo de transferência de dados seja concluído. Isso pode ser necessário em situações em que a transferência de dados está demorando muito ou encontrou erros ou se você precisa recuperar recursos rapidamente.

1. Exclua o pod de carga de trabalho, se ele existir:

   kubectl delete pod POD_NAME -n NAMESPACE
   

2. Atualize a política de recuperação de PersistentVolume para Delete. Isso garante que o PersistentVolume, junto com o armazenamento subjacente, seja excluído automaticamente quando o PersistentVolumeClaim associado for excluído.

   Ignore o comando a seguir se uma das seguintes condições for verdadeira:

   • Você não quer excluir o PersistentVolume ou o armazenamento subjacente.
   • Sua política de recuperação atual é Retain, e você quer manter o armazenamento. Limpe a instância de armazenamento e o PersistentVolume manualmente, conforme necessário.
   • O comando echo $PV_NAME a seguir gera uma string vazia, o que significa que o PersistentVolume ainda não foi criado.

   PV_NAME=$(kubectl describe pvc $TEMP_PVC -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   
   echo $PV_NAME
   
   kubectl patch pv $PV_NAME -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'
   

3. Encontre o nome do PersistentVolumeClaim temporário e defina a variável de ambiente para uma etapa posterior:

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   

4. Exclua o PersistentVolumeClaim executando este comando. O finalizador bloqueia a operação de exclusão. Pressione Ctrl+C e avance para a próxima etapa.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

5. Remova o finalizador datalayer.gke.io/populate-target-protection do PersistentVolumeClaim. Essa etapa é necessária após a exclusão do PersistentVolumeClaim. Caso contrário, gke-volume-populator adiciona o finalizador de volta ao PersistentVolumeClaim.

   kubectl get pvc PVC_NAME -n NAMESPACE -o=json | \
   jq '.metadata.finalizers = null' | kubectl apply -f -
   

6. Exclua o PersistentVolumeClaim temporário no namespace gke-managed-volumepopulator.

   kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator
   

7. Verifique se os recursos temporários PersistentVolumeClaim, PersistentVolumeClaim e PersistentVolume foram excluídos:

   kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
   

8. Verifique se a instância do Parallelstore foi excluída. A instância do Parallelstore vai compartilhar o mesmo nome do PersistentVolume. Não será necessário executar este comando se você confirmou na etapa 2 que o PersistentVolume não foi criado.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=- | grep ${PV_NAME?}
   

Solução de problemas

Nesta seção, mostramos como resolver problemas relacionados ao Volume Populator do GKE.

Antes de continuar, execute o comando a seguir para verificar os avisos de evento do PersistentVolumeClaim:

kubectl describe pvc PVC_NAME -n NAMESPACE

Erro: An internal error has occurred

Se você encontrar o erro abaixo, isso indica que ocorreu um erro interno da API Parallelstore.

Warning
PopulateOperationStartError
gkevolumepopulator-populator                                                            Failed to start populate operation: populate data for PVC "xxx". Import data failed, error: rpc error: code = Internal desc = An internal error has occurred ("xxx")

Para resolver esse problema, siga estas etapas para coletar dados para o suporte:

1. Execute os comandos abaixo para conferir o nome do PersistentVolumeClaim temporário, substituindo os marcadores de posição pelos nomes reais:

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-${PVC_UID?}
   
   echo ${TEMP_PVC?}
   

2. Execute o comando a seguir para conferir o nome do volume:

   PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   

3. Entre em contato com a equipe de suporte com a mensagem de erro, o nome do projeto e o nome do volume.

Problemas de permissão

Se você encontrar erros como o seguinte durante a população de volume, isso indica que o GKE encontrou um problema de permissões:

• O bucket do Cloud Storage não existe: PopulateOperationStartError com code = PermissionDenied
• Sem permissões no bucket do Cloud Storage ou nas contas de serviço: PopulateOperationFailed com "code: "xxx" message:"Verify if bucket "xxx" exists and grant access".
• Conta de serviço não encontrada: PopulateOperationStartError com code = Unauthenticated.

Para resolver esses problemas, verifique o seguinte:

• Acesso ao bucket do Cloud Storage: verifique se o bucket existe e se a conta de serviço tem a permissão roles/storage.objectViewer permission.
• Contas de serviço: confirme se a conta de serviço do Kubernetes e a conta de serviço do IAM existem e estão vinculadas corretamente.
• Conta de serviço do Parallelstore: verifique se ela existe e tem as permissões necessárias (roles/iam.serviceAccountTokenCreator e roles/iam.serviceAccountUser na conta do IAM).

Para conferir etapas detalhadas e comandos de verificação, consulte Configurar as permissões necessárias. Se os erros persistirem, entre em contato com o suporte com a mensagem de erro, o nome do projeto e o nome do bucket do Cloud Storage.

Erros de argumento inválido

Se você encontrar erros InvalidArgument, provavelmente forneceu valores incorretos em GCPDataSource ou PersistentVolumeClaim. O registro de erros vai identificar os campos exatos que contêm os dados inválidos. Verifique se o URI do bucket do Cloud Storage e outros campos relevantes estão corretos.

A seguir

• Confira a documentação de referência do CSI do Parallelstore.
• Aprenda a usar a biblioteca de interceptação do Parallelstore para melhorar a performance da carga de trabalho.
• Teste o tutorial para treinar um modelo do TensorFlow com o Keras no GKE.