Esta página foi traduzida pela API Cloud Translation.

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

Autopilot Standard

O GKE Volume Populator só está disponível por convite. Se você quiser solicitar acesso ao Populador de volume do GKE no seu projeto Google Cloud , 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 executar outros scripts ou comandos da CLI para transferência manual de dados. Esse recurso automatiza e simplifica o processo de transferência de dados aproveitando o recurso Kubernetes Volume Populator. Ele oferece portabilidade de dados perfeita para que você possa trocar os tipos de armazenamento e aproveitar as 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 tipo de armazenamentoGoogle Cloud (como o 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. Ele é um componente gerenciado pelo GKE ativado por padrão.

Vantagens

Se você quiser aproveitar o desempenho de um sistema de arquivos paralelo gerenciado, mas seus dados estiverem armazenados no Cloud Storage, use o GKE Volume Populator para simplificar a transferência de dados.
O GKE Volume Populator 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.

Transferência de dados do armazenamento de dados de origem e criação de PV para o armazenamento de destino usando o
GKE Volume Populator

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 armazenamento de origem e instâncias do Parallelstore como o tipo de armazenamento de destino.
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 só oferece suporte à vinculação de Federação de Identidade da Carga de Trabalho para GKE 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 limitações e requisitos.
Crie seus buckets do Cloud Storage, preenchidos com os dados que você quer transferir.

Requisitos

Para usar o Volume Populator do GKE, seus 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 atualizados do GKE Autopilot. Em clusters padrão novos e atualizados, é necessário ativar o driver CSI.

Preparar o ambiente

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

Configurar a rede VPC

É 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 maneira particular aos serviços Google Cloudsem expor o tráfego à Internet pública, você precisa fazer uma configuração única do acesso a serviços particulares (PSA, na sigla em inglês), se ainda não tiver feito isso.

Para configurar a PSA, siga estas etapas:

Para configurar o peering de rede no seu projeto, configure a permissão do IAM Administrador de rede do Compute (roles/compute.networkAdmin).

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.

Ative a rede de serviços:

gcloud services enable servicenetworking.googleapis.com

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 Google Cloud ID do projeto.
Observação: definir o valor de mtu (unidade de transmissão máxima, 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.
Crie um intervalo de IP.

O acesso a serviços particulares 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.

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 \
)

Crie uma regra de firewall para permitir o tráfego TCP do intervalo de IP criado:
```
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ê criou.

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 de Parallelstore com suporte para ter o melhor desempenho. Se você querer criar seu cluster em um local do Parallelstore que não tem suporte, ao criar um StorageClass do Parallelstore, é necessário especificar uma topologia personalizada que use um local do Parallelstore compatível. Caso contrário, o provisionamento 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 Google Cloud ID do projeto.
NETWORK_NAME: o nome da rede VPC que você criou 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 de Parallelstore com suporte para ter o melhor desempenho. Se você querer criar o cluster em um local do Parallelstore que não tem suporte, ao criar um StorageClass do Parallelstore, especifique uma topologia personalizada que use um local do Parallelstore compatível. Caso contrário, o provisionamento 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.

Crie um namespace do Kubernetes:
```
kubectl create namespace NAMESPACE
```
Substitua NAMESPACE pelo namespace em que as cargas de trabalho serão executadas.
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 pod usa para se autenticar nas APIs 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.
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 Google Cloud ID do projeto.

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.

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

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

Crie a identidade do serviço do Parallelstore:

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

Para permitir que a identidade do serviço do Parallelstore represente a conta de serviço do IAM, conceda o papel roles/iam.serviceAccountTokenCreator à identidade do serviço do Parallelstore. 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.

Para permitir que a identidade do serviço do Parallelstore acesse todos os recursos que a conta de serviço do IAM pode acessar, conceda o papel roles/iam.serviceAccountUser à identidade do 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

Para permitir que a identidade do serviço do GKE acesse todos os recursos que a conta de serviço do IAM pode acessar, conceda o papel roles/iam.serviceAccountUser à identidade do serviço do GKE. 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 Populator de volume do GKE.

Crie um recurso GCPDataSource.
Crie um StorageClass do Parallelstore.
Crie um PersistentVolumeClaim para acessar o volume.
(Opcional) Confira o andamento da transferência de dados.
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.

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 se autenticar nas APIs Google Cloud . O valor cloudStorage.serviceAccountName precisa ser a conta de serviço do Kubernetes que você configurou para a Federação de Identidade da Carga de Trabalho do GKE na etapa Configurar as permissões necessárias.
- GCS_BUCKET: seu nome do bucket do Cloud Storage Como alternativa, também é possível especificar gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ para o campo uri.
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 ajuda a garantir a melhor performance de E/S.

Salve o seguinte manifesto parallelstore-class.yaml como :

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

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 CSI da 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.

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 sua carga de trabalho.
- GCP_DATA_SOURCE: o nome do CRD GCPDataSource que contém uma referência ao bucket do Cloud Storage. Para mais detalhes, consulte a referência do CRD GCPDataSource.
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.

(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.

Para verificar o status do PersistentVolumeClaim, execute o seguinte comando:
```
kubectl describe pvc PVC_NAME -n NAMESPACE
```

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.

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 sua 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.
Execute o comando a seguir para aplicar o manifesto ao cluster:
```
kubectl apply -f pod.yaml
```
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
```
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.

Exclua o pod da carga de trabalho, se ele existir, executando este comando:
```
kubectl delete pod POD_NAME -n NAMESPACE
```

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

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.

Execute este comando para excluir o PersistentVolumeClaim.
```
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.
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?}"
```
Verifique se a instância do Parallelstore foi excluída. A instância do Parallelstore vai compartilhar o mesmo nome do PersistentVolume.
```
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. Talvez seja necessário usar essa opção em situações em que a transferência de dados está demorando muito ou encontrou erros, ou se você precisar recuperar recursos rapidamente.

Exclua o pod de carga de trabalho, se ele existir:
```
kubectl delete pod POD_NAME -n NAMESPACE
```
Atualize a política de recuperação de PersistentVolume para Delete. Essa configuração garante que o PersistentVolume, junto com o armazenamento, 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 o PersistentVolume e a instância de armazenamento 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"}}'
```

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

Exclua o PersistentVolumeClaim executando este comando. O finalizador bloqueia a operação de exclusão. Pressione Control+C e siga para a próxima etapa.
```
kubectl delete pvc PVC_NAME -n NAMESPACE
```
Remova o finalizador datalayer.gke.io/populate-target-protection do PersistentVolumeClaim. Esta 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 -
```
Exclua o PersistentVolumeClaim temporário no namespace gke-managed-volumepopulator.
```
kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator
```
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?}"
```
Verifique se a instância do Parallelstore foi excluída. A instância do Parallelstore vai compartilhar o mesmo nome do PersistentVolume.
```
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:

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?}

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}')

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
Permissões ausentes 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 erros, verifique o seguinte:

Acesso ao bucket do Cloud Storage: verifique se o bucket existe e se a conta de serviço tem 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 a conta de serviço do Parallelstore 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.

Verificar se o provisionamento do PersistentVolumeClaim foi concluído

O Volume Populator do GKE usa um PersistentVolumeClaim temporário no namespace gke-managed-volumepopulator para provisionar volumes.

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:

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. Execute o comando abaixo para verificar os avisos de evento do PersistentVolumeClaim:

kubectl describe pvc PVC_NAME -n NAMESPACE

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"

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.