Automatize a transferência de dados do Cloud Storage para o Parallelstore através do GKE Volume Populator

Autopilot Padrão

---

O GKE Volume Populator só está disponível por convite. Se quiser pedir acesso ao GKE Volume Populator no seu Google Cloud projeto, contacte o seu representante de vendas.

Este guia descreve como pode pré-carregar grandes quantidades de dados de um contentor do Cloud Storage para um volume Parallelstore do Google Kubernetes Engine (GKE) durante o aprovisionamento dinâmico através do GKE Volume Populator. Para mais informações, consulte o artigo Acerca do GKE Volume Populator.

Este guia destina-se a especialistas de armazenamento que criam e atribuem armazenamento, e gerem a segurança e o acesso aos dados. Para saber mais sobre as funções comuns e as tarefas de exemplo que referimos no Google Cloud conteúdo, consulte o artigo Funções e tarefas de utilizador comuns do GKE Enterprise.

Limitações

• O recurso personalizado GCPDataSource tem de estar no mesmo espaço de nomes que a sua carga de trabalho do Kubernetes. Os volumes com origens de dados entre espaços de nomes não são suportados.
• O GKE Volume Populator só suporta a federação de identidade da força de trabalho para o GKE vinculação de contas de serviço do IAM a uma conta de serviço do Kubernetes. A concessão de autorizações da IAM diretamente à conta de serviço do Kubernetes não é suportada.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

• Ative a API Parallelstore e a API Google Kubernetes Engine.
Ativar APIs
• Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.
  Nota: para instalações existentes da CLI gcloud, certifique-se de que define a compute/region propriedade. Se usar principalmente clusters zonais, defina o compute/zone. Ao definir uma localização predefinida, pode evitar erros na CLI gcloud, como os seguintes: One of [--zone, --region] must be supplied: Please specify location. Pode ter de especificar a localização em determinados comandos se a localização do seu cluster for diferente da predefinição que definiu.

• Consulte a vista geral do controlador CSI Parallelstore para ver as limitações e os requisitos.
• Crie os seus contentores do Cloud Storage, preenchidos com os dados que quer transferir.

Requisitos

Para usar o GKE Volume Populator, os seus clusters têm de cumprir os seguintes requisitos:

• Use a versão 1.31.1-gke.1729000 ou posterior do cluster do GKE.
• Ter o controlador CSI Parallelstore ativado. O GKE ativa o controlador CSI por predefinição em clusters do GKE Autopilot novos e existentes. Nos clusters padrão novos e existentes, tem de ativar o controlador CSI.

Prepare o seu ambiente

Esta secção aborda os passos para criar os seus clusters do GKE e configurar as autorizações necessárias para usar o GKE Volume Populator.

Configure a sua rede de VPC

Nota: se já configurou a sua rede VPC como parte da configuração do controlador CSI do Parallelstore, pode ignorar esta secção.

Tem de especificar a mesma rede da nuvem virtual privada (VPC) quando criar a instância do Parallelstore e as VMs do Compute Engine ou os clusters do GKE do cliente. Para permitir que a VPC se ligue de forma privada a serviços sem expor o tráfego à Internet pública, tem de fazer uma configuração única do acesso a serviços privados (PSA), se ainda não o tiver feito. Google Cloud

Para configurar o PSA, siga estes passos:

1. Para configurar a interligação de redes para o seu projeto, configure a autorização de IAM Administrador de rede de computação (roles/compute.networkAdmin).

   Para conceder a função, 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 email.

2. Ative a rede de serviços:

   gcloud services enable servicenetworking.googleapis.com
   

3. Crie uma rede de VPC:

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

   Substitua o seguinte:

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

4. Crie um intervalo de IP.

   O acesso a serviços privados requer um intervalo de endereços IP (bloco CIDR) com um comprimento do prefixo de, pelo menos, /24 (256 endereços). A Parallelstore reserva 64 endereços por instância, o que significa que pode reutilizar este intervalo de IP com outros serviços ou outras instâncias da 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 IPs da rede VPC.

5. Defina uma variável de ambiente com o intervalo CIDR associado ao intervalo que criou no passo 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 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 criou.

7. Associe a interligação:

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

Se tiver problemas ao configurar a rede da VPC, consulte o guia de resolução de problemas do Parallelstore.

Crie o seu cluster do GKE

Recomendamos que use um cluster do Autopilot para uma experiência do Kubernetes totalmente gerida. Para escolher o modo de funcionamento do GKE mais adequado às suas necessidades de carga de trabalho, consulte o artigo Escolha um modo de funcionamento do GKE.

Piloto automático

Para criar um cluster do GKE com 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 Workload Identity Federation para o GKE e o controlador CSI Parallelstore por predefinição em clusters do Autopilot.

Substitua os seguintes valores:

• CLUSTER_NAME: o nome do cluster.
• CLUSTER_VERSION : o número da versão do GKE. Tem de especificar a versão 1.31.1-gke.1729000 ou posterior.
• NETWORK_NAME: o nome da rede VPC que criou para a instância do Parallelstore. Para saber mais, consulte o artigo Configure uma rede VPC.
• CLUSTER_LOCATION: a região onde quer criar o cluster. Recomendamos que crie o cluster numa localização da Parallelstore suportada para ter o melhor desempenho. Se quiser criar o cluster numa localização do Parallelstore não suportada, quando criar uma StorageClass do Parallelstore, tem de especificar uma topologia personalizada que use uma localização do Parallelstore suportada. Caso contrário, o aprovisionamento falha.

Standard

Crie um cluster padrão com o controlador CSI Parallelstore e a Workload Identity Federation para o GKE ativada através do 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. Tem de especificar a versão 1.31.1-gke.1729000 ou posterior.
• PROJECT_ID: o ID Google Cloud do projeto.
• NETWORK_NAME: o nome da rede VPC que criou para a instância do Parallelstore. Para saber mais, consulte o artigo Configure uma rede VPC.
• CLUSTER_LOCATION: a região ou a zona onde quer criar o cluster. Recomendamos que crie o cluster numa localização da Parallelstore suportada para ter o melhor desempenho. Se quiser criar o cluster numa localização do Parallelstore não suportada, quando criar uma StorageClass do Parallelstore, tem de especificar uma topologia personalizada que use uma localização do Parallelstore suportada. Caso contrário, o aprovisionamento falha.

Configure as autorizações necessárias

Para transferir dados de um contentor do Cloud Storage, tem de configurar autorizações para a Federação do Workload Identity para o GKE.

1. Crie um namespace do Kubernetes:

   kubectl create namespace NAMESPACE
   

   Substitua NAMESPACE pelo espaço de nomes no qual as suas cargas de trabalho vão ser 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 o seu pod usa para autenticar nas APIs. Google Cloud

   Aviso: a reutilização desta conta de serviço do Kubernetes numa carga de trabalho no mesmo espaço de nomes permite que esse pod aceda ao contentor do Cloud Storage. Recomendamos que não volte a usar esta conta de serviço para cargas de trabalho no espaço de nomes.

3. Crie uma conta de serviço do IAM. Também pode usar qualquer conta de serviço do IAM existente em qualquer projeto na sua organização:

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

   Substitua o seguinte:

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

4. Conceda à sua conta de serviço do IAM a função roles/storage.objectViewer para que possa aceder ao seu contentor 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 contentor do Cloud Storage.

5. Crie a política de autorização do IAM que concede à conta de serviço do Kubernetes acesso à representação da 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 a associação 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 Parallelstore:

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

8. Para permitir que a identidade de serviço do Parallelstore use a identidade da conta de serviço do IAM, conceda a função roles/iam.serviceAccountTokenCreator à identidade de serviço do Parallelstore. Defina a variável de ambiente PROJECT_NUMBER para que a possa usar nos passos subsequentes.

   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 o seu projeto. Para encontrar este valor, consulte o artigo Criar e gerir projetos.

9. Para permitir que a identidade de serviço do Parallelstore aceda a todos os recursos aos quais a conta de serviço do IAM pode aceder, atribua a função roles/iam.serviceAccountUser à identidade de serviço do Parallelstore:

   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. Para permitir que a identidade de serviço do GKE aceda a todos os recursos aos quais a conta de serviço do IAM pode aceder, conceda a função roles/iam.serviceAccountUser à identidade de serviço do GKE. Este passo não é necessário 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
    

Crie um volume do Parallelstore com dados pré-carregados

As secções seguintes descrevem o processo típico de criação de um volume do Parallelstore com dados pré-carregados a partir de um contentor do Cloud Storage, através do GKE Volume Populator.

1. Crie um recurso GCPDataSource.
2. Crie uma StorageClass Parallelstore.
3. Crie um PersistentVolumeClaim para aceder ao volume.
4. (Opcional) Veja o progresso da transferência de dados.
5. Crie uma carga de trabalho que consuma o volume.

Crie um recurso GCPDataSource

Para usar o GKE Volume Populator, crie um recurso personalizado GCPDataSource. Este recurso define as propriedades de armazenamento de origem a usar para o preenchimento de volumes.

1. Guarde o seguinte manifesto num ficheiro com o nome 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 que contém uma referência ao seu contentor do Cloud Storage.GCPDataSource Consulte a GCPDataSource referência CRD para mais detalhes.
   • NAMESPACE: o espaço de nomes no qual as suas cargas de trabalho vão ser executadas. O valor do espaço de nomes deve ser igual ao espaço de nomes da carga de trabalho.
   • KSA_NAME: o nome da conta de serviço do Kubernetes que o seu pod usa para autenticar nas APIs Google Cloud . O valor de cloudStorage.serviceAccountName deve ser a conta de serviço do Kubernetes que configurou para a federação de identidades da carga de trabalho para o GKE no passo Configure as autorizações necessárias.
   • GCS_BUCKET: o nome do seu contentor do Cloud Storage. Em alternativa, também pode especificar gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ para o campo uri.

2. Execute este comando para criar o recurso GCPDataSource:

   kubectl apply -f gcpdatasource.yaml
   

Crie uma StorageClass Parallelstore

Crie uma StorageClass para direcionar o controlador CSI do Parallelstore para aprovisionar instâncias do Parallelstore na mesma região que o seu cluster do GKE. Isto ajuda a garantir um desempenho de E/S ideal.

1. Guarde o seguinte manifesto como parallelstore-class.yaml.

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

2. Execute este comando para criar a StorageClass:

   kubectl apply -f parallelstore-class.yaml
   

Se quiser criar uma StorageClass personalizada com uma topologia específica, consulte o guia do CSI Parallelstore.

Crie uma PersistentVolumeClaim para aceder ao volume

O ficheiro de manifesto seguinte mostra um exemplo de como criar um PersistentVolumeClaim no ReadWriteMany modo de acesso que faz referência à StorageClass que criou anteriormente.

1. Guarde o seguinte manifesto num ficheiro com o nome 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 onde quer transferir os seus dados. O PersistentVolumeClaim tem de ser suportado por uma instância do Parallelstore.
   • NAMESPACE: o espaço de nomes onde as suas cargas de trabalho serão executadas. O valor do espaço de nomes deve ser igual ao espaço de nomes da carga de trabalho.
   • GCP_DATA_SOURCE: o nome do CRD que contém uma referência ao seu contentor do Cloud Storage.GCPDataSource Para mais detalhes, consulte a GCPDataSource referência do CRD.

2. Crie o PersistentVolumeClaim executando o seguinte comando:

   kubectl apply -f volume-populator-pvc.yaml
   

O GKE não agenda o pod de carga de trabalho até que o aprovisionamento de PersistentVolumeClaim esteja concluído. Para verificar o progresso da transferência de dados, consulte o artigo Veja o progresso da transferência de dados. Se encontrar erros durante o aprovisionamento, consulte a resolução de problemas.

(Opcional) Veja o progresso da transferência de dados

Esta secção mostra como pode acompanhar o progresso das suas transferências de dados de um contentor do Cloud Storage para um volume do Parallelstore. Pode fazê-lo para monitorizar o estado da transferência e garantir que os dados são copiados com êxito. Também deve executar este comando se a operação de associação PersistentVolumeClaim demorar demasiado tempo.

1. Valide o estado do PersistentVolumeClaim executando o seguinte comando:

   kubectl describe pvc PVC_NAME -n NAMESPACE
   

2. Verifique a mensagem de eventos PersistentVolumeClaim para encontrar o progresso da transferência de dados. O GKE regista as mensagens cerca de uma vez por minuto. O resultado é semelhante ao seguinte:

   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
   

A operação de preenchimento pode demorar algum tempo a ser iniciada. Esta operação depende do tamanho do ficheiro. Se não vir qualquer progresso na transferência de dados após vários minutos, consulte a secção Resolução de problemas.

Crie uma carga de trabalho que consuma o volume

Esta secção mostra um exemplo de como criar um Pod que consuma o recurso PersistentVolumeClaim que criou anteriormente.

1. Guarde o seguinte manifesto YAML para o 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 agrupamento que executa a sua carga de trabalho.
   • NAMESPACE: o espaço de nomes onde as suas cargas de trabalho serão executadas. O valor do espaço de nomes deve ser igual ao espaço de nomes da carga de trabalho.
   • PVC_NAME: o nome do PersistentVolumeClaim onde quer transferir os seus dados. O PersistentVolumeClaim tem de ser suportado por uma instância do Parallelstore.

2. Execute o seguinte comando para aplicar o manifesto ao cluster:

   kubectl apply -f pod.yaml
   

3. Verifique o estado do Pod e aguarde até que o estado seja RUNNING. O PersistentVolumeClaim deve estar associado antes de a carga de trabalho poder ser executada.

   kubectl describe pod POD_NAME -n NAMESPACE
   

4. Verifique se os ficheiros foram transferidos com êxito e se a sua carga de trabalho pode aceder aos mesmos.

   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
   

   O resultado deve apresentar todos os ficheiros existentes no URI do contentor do Cloud Storage.

Elimine um PersistentVolumeClaim durante o aprovisionamento dinâmico

Se precisar de eliminar o PersistentVolumeClaim enquanto os dados ainda estão a ser transferidos durante o aprovisionamento dinâmico, tem duas opções: eliminação graciosa e eliminação forçada.

A eliminação gradual requer menos esforço, mas pode demorar mais tempo e não tem em conta a configuração incorreta do utilizador que impede a conclusão da transferência de dados. A eliminação forçada oferece uma alternativa mais rápida que permite maior flexibilidade e controlo. Esta opção é adequada quando precisa de reiniciar ou corrigir rapidamente configurações incorretas.

Eliminação suave

Use esta opção de eliminação para garantir que o processo de transferência de dados é concluído antes de o GKE eliminar os recursos associados.

1. Elimine o pod de carga de trabalho, se 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 o resultado estiver vazio, significa que o PersistentVolume ainda não foi criado.

4. Elimine o PersistentVolumeClaim executando este comando.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

   Aguarde pela conclusão da transferência de dados. O GKE acaba por eliminar a PersistentVolumeClaim, o PersistentVolume e a instância Parallelstore.

5. Verifique se os recursos PersistentVolumeClaim, PersistentVolume e PersistentVolumeClaim temporários foram eliminados:

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

6. Verifique se a instância do Parallelstore foi eliminada. A instância do Parallelstore partilha o mesmo nome que o PersistentVolume.

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

Eliminação forçada

Use esta opção de eliminação quando precisar de eliminar um PersistentVolumeClaim e os respetivos recursos associados antes de o processo de transferência de dados estar concluído. Pode ter de usar esta opção em situações em que a transferência de dados demore demasiado tempo ou tenha encontrado erros, ou se precisar de reaver recursos rapidamente.

1. Elimine o pod de carga de trabalho, se existir:

   kubectl delete pod POD_NAME -n NAMESPACE
   

2. Atualize a política de recuperação de PersistentVolume para Delete. Esta definição garante que o PersistentVolume, juntamente com o armazenamento subjacente, é eliminado automaticamente quando o PersistentVolumeClaim associado é eliminado.

   Ignore o seguinte comando se se aplicar alguma das seguintes situações:

   • Não quer eliminar o PersistentVolume nem o armazenamento subjacente.
   • A sua política de recuperação atual é Retain e quer manter o armazenamento subjacente. Limpe o PersistentVolume e a instância de armazenamento manualmente, conforme necessário.

   • O comando echo $PV_NAME seguinte produz 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 um passo 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. Elimine o PersistentVolumeClaim executando este comando. O finalizador bloqueia a operação de eliminação. Prima Control+C e, de seguida, avance para o passo seguinte.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

5. Remova o finalizador datalayer.gke.io/populate-target-protection do seu PersistentVolumeClaim. Este passo é necessário após a eliminação do PersistentVolumeClaim. Caso contrário, o gke-volume-populator adiciona o finalizador novamente ao PersistentVolumeClaim.

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

6. Elimine o PersistentVolumeClaim temporário no espaço de nomes gke-managed-volumepopulator.

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

7. Verifique se os recursos PersistentVolumeClaim, PersistentVolume e PersistentVolumeClaim temporários foram eliminados:

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

8. Verifique se a instância do Parallelstore foi eliminada. A instância do Parallelstore partilha o mesmo nome que o PersistentVolume.

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

Resolução de problemas

Esta secção mostra-lhe como resolver problemas relacionados com o GKE Volume Populator.

Antes de continuar, execute o seguinte comando para verificar se existem avisos de eventos PersistentVolumeClaim:

kubectl describe pvc PVC_NAME -n NAMESPACE

Erro: An internal error has occurred

Se encontrar o seguinte erro, significa 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 este problema, tem de seguir estes passos para recolher dados para o apoio técnico:

1. Execute os seguintes comandos para obter 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 seguinte comando para obter o nome do volume:

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

3. Contacte a equipa de apoio técnico com a mensagem de erro, o nome do projeto e o nome do volume.

Problemas de autorização

Se encontrar erros como os seguintes durante o preenchimento de volumes, significa que o GKE encontrou um problema de autorizações:

• O contentor do Cloud Storage não existe: PopulateOperationStartError com code = PermissionDenied
• Autorizações em falta no contentor 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 estes erros, verifique novamente o seguinte:

• Acesso ao contentor do Cloud Storage: verifique se o contentor existe e se a conta de serviço tem o papel 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 corretamente associadas.
• Conta de serviço do Parallelstore: certifique-se de que a conta de serviço do Parallelstore existe e tem as autorizações necessárias (roles/iam.serviceAccountTokenCreator e roles/iam.serviceAccountUser na conta do IAM).

Para ver passos detalhados e comandos de validação, consulte o artigo Configure as autorizações necessárias. Se os erros persistirem, contacte o apoio técnico com a mensagem de erro, o nome do projeto e o nome do contentor do Cloud Storage.

Erros de argumento inválido

Se encontrar erros InvalidArgument, significa que, provavelmente, forneceu valores incorretos no recurso GCPDataSource ou no PersistentVolumeClaim. O registo de erros indica os campos exatos que contêm os dados inválidos. Verifique o URI do contentor do Cloud Storage e outros campos relevantes para garantir a precisão.

Verifique se o aprovisionamento de PersistentVolumeClaim foi concluído

Aviso: se estiver a usar o Autopilot, antes de realizar esta verificação, certifique-se de que cria primeiro uma carga de trabalho que consuma o volume. Este passo é necessário para acionar o GKE de modo a criar um nó. Se não o fizer, pode ocorrer um erro, como o seguinte, que persiste durante vários minutos: "error generating accessibility requirements: no available topology found".

O GKE Volume Populator usa um PersistentVolumeClaim temporário no espaço de nomes gke-managed-volumepopulator para o aprovisionamento de volumes.

O PersistentVolumeClaim temporário é essencialmente uma captura instantânea do seu PersistentVolumeClaim que ainda está em trânsito (a aguardar que os dados sejam totalmente carregados). O nome tem o formato prime-YOUR_PVC_UID.

Para verificar o respetivo estado:

1. Execute os seguintes comandos:

   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 o resultado estiver vazio, significa que o PersistentVolumeClaim temporário não foi criado. Execute o seguinte comando para verificar se existem avisos de eventos PersistentVolumeClaim:

   kubectl describe pvc PVC_NAME -n NAMESPACE
   

   Se o aprovisionamento for bem-sucedido, o resultado é semelhante ao seguinte. Procure o registo 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"
   

   Nota: os avisos na saída são esperados, uma vez que o aprovisionamento de CSI está a tentar conciliar o estado de aprovisionamento de volumes. Normalmente, o aprovisionamento de volumes do Parallelstore demora 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=-
   

   O resultado é semelhante ao seguinte. Confirme se o volume está no estado CREATING. Quando a criação da instância do Parallelstore estiver concluída, o estado muda 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 aprovisionamento falhar, consulte o guia de resolução de problemas da Parallelstore para obter orientações adicionais.

O que se segue?

• Saiba mais sobre o GKE Volume Populator.
• Explore a documentação de referência do CSI Parallelstore.
• Saiba como usar a biblioteca de interceção Parallelstore para melhorar o desempenho da carga de trabalho.
• Experimente o tutorial para preparar um modelo do TensorFlow com o Keras no GKE.