Acessar instâncias com o driver CSI do Filestore

Autopilot Standard

O driver CSI do Filestore é a principal maneira de usar instâncias do Filestore com o Google Kubernetes Engine (GKE). O driver CSI do Filestore oferece uma experiência totalmente gerenciada com a tecnologia de código aberto do driver CSI do Google Cloud Filestore.

A versão do driver CSI do Filestore está vinculada aos números de versão secundários do Kubernetes. Normalmente, a versão do driver CSI do FileFile é o mais recente disponível no momento em que a versão secundária do Kubernetes é lançada. Os drivers são atualizados automaticamente quando o cluster é atualizado para o patch do GKE mais recente.

Benefícios

O driver CSI do Filestore oferece os seguintes benefícios:

Você tem acesso ao armazenamento NFS totalmente gerenciado por meio das APIs do Kubernetes (kubectl).
É possível usar o driver CSI do Filestore para GKE a fim de provisionar dinamicamente PersistentVolumes.
É possível usar snapshots de volume com o driver CSI do Filestore para GKE. Os snapshots de volume CSI podem ser usados para criar backups do Filestore.

Um backup do Filestore cria uma cópia diferencial do compartilhamento de arquivos, incluindo todos os dados e metadados de arquivo, e a armazena separadamente da instância. Só é possível restaurar essa cópia em uma nova instância do Filestore. Não é possível restaurá-la em uma instância atual do Filestore. É possível usar a API de snapshot de volume CSI para acionar backups do Filestore por meio da adição de um campo type:backup na classe de snapshot de volume.
É possível usar a expansão de volume com o driver CSI do Filestore para GKE. A expansão de volume permite redimensionar a capacidade do volume.
É fácil acessar instâncias atuais do Filestore usando instâncias pré-provisionadas do Filestore em cargas de trabalho do Kubernetes. Também é possível criar ou excluir instâncias do Filestore dinamicamente e usá-las em cargas de trabalho do Kubernetes com um StorageClass ou uma Deployment.
Compatível com multicompartilhamentos do Filestore para o GKE. Com esse recurso, é possível criar uma instância do Filestore e alocar vários PersistentVolumes menores montados por NFS para ela simultaneamente em qualquer número de clusters do GKE.

Requisitos

Para usar o driver CSI do Filestore, seus clusters precisam usar a versão 1.21 ou posterior do GKE.
Para usar o recurso Multicompartilhamentos do Filestore, os clusters precisam usar a versão 1.23 ou posterior do GKE.
O driver CSI do Filestore é compatível com clusters que usam apenas Linux. Os nós do Windows Server não são compatíveis.
O tamanho mínimo da instância do Filestore é de pelo menos 1 TiB. O tamanho mínimo da instância depende do nível de serviço selecionado do Filestore. Para saber mais, consulte Níveis de serviço.
O Filestore usa o protocolo do sistema de arquivos NFSv3 na instância do Filestore e é compatível com qualquer cliente compatível com NFSv3.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Ative a API Cloud Filestore 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 CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
Observação: para instalações atuais da CLI gcloud, 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.

Se você quiser usar o Filestore em uma rede VPC compartilhada, consulte as instruções de configuração adicionais em Usar o Filestore com VPC compartilhada.

Como ativar o driver CSI do Filestore em um novo cluster

Para ativar o driver CSI do Filestore da Filestore ao criar um novo cluster padrão, siga estas etapas com a CLI do Google Cloud ou o Console do Google Cloud.

gcloud

gcloud container clusters create CLUSTER_NAME \
    --addons=GcpFilestoreCsiDriver \
    --cluster-version=VERSION

Substitua:

CLUSTER_NAME: o nome do cluster.
VERSION: o número da versão do GKE. Selecione a versão 1.21 ou uma mais recente para usar esse recurso. Como alternativa, é possível usar a sinalização --release-channel e especificar um canal de lançamento.

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Clique em Criar.
Escolha o modo de cluster Padrão e clique em Configurar.
Configure o cluster como quiser.
No painel de navegação, em Cluster, clique em Recursos.
Marque a caixa de seleção Ativar driver CSI do Filestore.
Clique em Criar.

Se você quiser usar o Filestore em uma rede VPC compartilhada, consulte Ativar o driver CSI do Filestore em um novo cluster com a VPC compartilhada.

Depois de ativar o driver CSI do Filestore, é possível usar o driver nos volumes do Kubernetes usando o nome do driver e do provisionador: filestore.csi.storage.gke.io.

Ativar o driver CSI do Filestore em um cluster atual

Para ativar o driver CSI do Filestore em clusters atuais, use a Google Cloud CLI ou o Console do Google Cloud.

Para ativar o driver em um cluster existente, conclua as etapas a seguir:

gcloud

gcloud container clusters update CLUSTER_NAME \
   --update-addons=GcpFilestoreCsiDriver=ENABLED

Substitua CLUSTER_NAME pelo nome do cluster atual.

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que você quer modificar.
Em Recursos, ao lado do campo Driver CSI do Filestore, clique em Editar driver CSI do Filestore.
Marque a caixa de seleção Ativar driver CSI do Filestore.
Clique em Salvar alterações.

Desativar o driver CSI do Filestore

É possível desativar o driver CSI do Filestore em um cluster atual do Autopilot ou padrão usando a Google Cloud CLI ou o Console do Google Cloud.

gcloud

gcloud container clusters update CLUSTER_NAME \
    --update-addons=GcpFilestoreCsiDriver=DISABLED \
    --region REGION

Substitua os seguintes valores:

CLUSTER_NAME: o nome do cluster existente.
REGION: a região do cluster (como us-central1).

Console

No Console do Google Cloud, acesse o menu do Google Kubernetes Engine.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que você quer modificar.
Em Recursos, ao lado do campo Driver CSI do Filestore, clique em Editar driver CSI do Filestore.
Desmarque a caixa de seleção Ativar driver CSI do Filestore.
Clique em Salvar alterações.

Acessar instâncias preeexistentes do Filestore usando o driver CSI do Filestore

Nesta seção, descrevemos o processo típico de uso de um volume do Kubernetes para acessar instâncias preexistentes do Filestore usando o driver CSI do Filestore no GKE:

Criar um PersistentVolume e um PersistentVolumeClaim para acessar a instância

Crie um arquivo de manifesto como o mostrado no exemplo a seguir e nomeie-o como preprov-filestore.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: PV_NAME
spec:
  storageClassName: ""
  capacity:
    storage: 1Ti
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem
  csi:
    driver: filestore.csi.storage.gke.io
    volumeHandle: "modeInstance/FILESTORE_INSTANCE_LOCATION/FILESTORE_INSTANCE_NAME/FILESTORE_SHARE_NAME"
    volumeAttributes:
      ip: FILESTORE_INSTANCE_IP
      volume: FILESTORE_SHARE_NAME
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: ""
  volumeName: PV_NAME
  resources:
    requests:
      storage: 1Ti

Para criar os recursos PersistentVolumeClaim e PersistentVolume com base no arquivo de manifesto preprov-filestore.yaml, execute o seguinte comando:
```
kubectl apply -f preprov-filestore.yaml
```

Depois, crie uma implantação que consuma o volume.

Criar um volume usando o driver CSI do Filestore

As seções a seguir descrevem o processo típico de uso de um volume do Kubernetes compatível com um driver CSI do Filestore no GKE.

Criar um StorageClass
Usar um PersistentVolumeClaim para acessar o volume
Criar uma implantação que consuma o volume

Criar um StorageClass

Depois que você ativa o driver CSI do Filestore, o GKE instala automaticamente os StorageClasses a seguir para provisionar instâncias do Filestore:

zonal-rwx, usando o nível do Filestore zonal. Disponível apenas para a banda de maior capacidade. Esse StorageClass está disponível nos clusters do GKE com a versão 1.27 ou posterior.
enterprise-rwx, usando o nível empresarial do Filestore, em que cada PersistentVolume do Kubernetes é mapeado com uma instância do Filestore. Esse StorageClass está disponível nos clusters do GKE com a versão 1.23 ou posterior.
enterprise-multishare-rwx, usando o nível empresarial do Filestore, em que cada PersistentVolume do Kubernetes é mapeado com uma parcela de uma determinada instância do Filestore. Esse StorageClass está disponível nos clusters do GKE com a versão 1.23 ou posterior. Para saber mais, consulte Multicompartilhamentos do Filestore para o Google Kubernetes Engine.
standard-rwx, usando o nível de serviço Basic HDD Filestore.
premium-rwx, usando o nível de serviço Basic SSD Filestore.

Encontre o nome do StorageClass instalado executando o seguinte comando:

kubectl get sc

Também é possível instalar um StorageClass diferente que use o driver CSI do Filestore adicionando filestore.csi.storage.gke.io no campo provisioner.

Salve o seguinte manifesto como filestore-example-class.yaml:
```
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-example
provisioner: filestore.csi.storage.gke.io
volumeBindingMode: Immediate
allowVolumeExpansion: true
parameters:
  tier: standard
  network: default
```
No manifesto, considere a seguinte configuração de parâmetros:
- Definir volumeBindingMode como Immediate permite que o provisionamento do volume comece imediatamente. Isso é possível porque as instâncias do Filestore são acessíveis em qualquer zona. Portanto, o GKE não precisa saber a zona em que o pod está programado, ao contrário do disco permanente do Compute Engine. Quando definido como WaitForFirstConsumer, o GKE começa a provisionar apenas após o pod ser programado. Para mais informações, consulte VolumeBindingMode.
- Qualquer nível do Filestore pode ser especificado no parâmetro tier (por exemplo, BASIC_HDD, BASIC_SSD, ZONAL ou ENTERPRISE).
- O parâmetro network pode ser usado ao provisionar instâncias do Filestore em VPCs não padrão. As VPCs não padrão exigem que regras de firewallespeciais sejam configuradas.
Para criar um recurso StorageClass com base no arquivo de manifesto filestore-example-class.yaml, execute o seguinte comando:
```
kubectl create -f filestore-example-class.yaml
```

Se você quiser usar o Filestore em uma rede VPC compartilhada, consulte Criar um StorageClass ao usar o driver CSI do Filestore com VPC compartilhada.

Usar um PersistentVolumeClaim para acessar o volume

É possível criar um recurso PersistentVolumeClaim que faça referência ao StorageClass do driver CSI do Filestore.

É possível usar um StorageClass pré-instalado ou personalizado.

O arquivo de manifesto de exemplo a seguir cria uma PersistentVolumeClaim que referencia o StorageClass chamado filestore-example.

Salve o seguinte arquivo de manifesto como pvc-example.yaml:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
  - ReadWriteMany
  storageClassName: filestore-example
  resources:
    requests:
      storage: 1Ti

Para criar um recurso PersistentVolume com base no arquivo de manifesto pvc-example.yaml, execute o seguinte comando:
```
kubectl create -f pvc-example.yaml
```

Criar uma implantação que consuma o volume

O exemplo de manifesto de implantação a seguir consome o recurso PersistentVolume chamado pvc-example.yaml.

Vários pods podem compartilhar o mesmo recurso PersistentVolumeClaim.

Salve o seguinte manifesto filestore-example-deployment.yaml como:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-server-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        volumeMounts:
        - mountPath: /usr/share/nginx/html
          name: mypvc
      volumes:
      - name: mypvc
        persistentVolumeClaim:
          claimName: podpvc
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: filestore-example
  resources:
    requests:
      storage: 1Ti

Para criar uma implantação com base no arquivo de manifesto filestore-example-deployment.yaml, execute o seguinte comando:
```
kubectl apply -f filestore-example-deployment.yaml
```
Confirme se a implantação foi criada com sucesso:
```
kubectl get deployment
```
Pode levar algum tempo para que as instâncias do Filestore concluam o provisionamento. Antes disso, as implantações não informarão um status READY. É possível verificar o progresso monitorando o status do PVC. Para isso, execute o comando a seguir:
```
kubectl get pvc
```
Você verá o PVC atingir um status BOUND quando o provisionamento de volume for concluído.

Rotular instâncias do Filestore

Use rótulos para agrupar instâncias relacionadas e armazenar metadados sobre uma instância. Um rótulo é um par de chave-valor que ajuda a organizar as instâncias do Filestore. Se você anexar rótulos aos recursos, poderá filtrá-los depois.

É possível fornecer rótulos usando a tecla labels em StorageClass.parameters. Uma instância do Filestore pode ser rotulada com informações sobre para que PersistentVolumeClaim/PersistentVolume a instância foi criada. As chaves e os valores de rótulo personalizados precisam estar em conformidade com a convenção de nomenclatura do rótulo. Veja o exemplo de classe de armazenamento do Kubernetes para aplicar rótulos personalizados à instância do Filestore.

Usar fsgroup com volumes do Filestore

O Kubernetes usa fsGroup para alterar as permissões e a propriedade do volume para corresponder a um fsGroup solicitado pelo usuário no SecurityContext do pod. Um fsGroup é um grupo complementar que se aplica a todos os contêineres em um pod. É possível aplicar um fsgroup aos volumes provisionados pelo driver CSI do Filestore.

Configurar regras de acesso de IP com volumes do Filestore

O Filestore permite regras de controle de acesso baseadas em IP para volumes.

Essas regras podem ser configuradas diretamente pela API Filestore ou pelo driver CSI do Filestore quando um volume é criado. É possível fornecer a configuração selecionada no formato JSON no StorageClass usando o parâmetro nfs-export-options-on-create.

O exemplo de manifesto a seguir mostra como especificar a configuração:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-example
provisioner: filestore.csi.storage.gke.io
volumeBindingMode: Immediate
allowVolumeExpansion: true
parameters:
  tier: "enterprise"
  nfs-export-options-on-create: '[
    {
      "accessMode": "READ_WRITE",
      "ipRanges": [
        "10.0.0.0/24"
      ],
      "squashMode": "NO_ROOT_SQUASH"
    },
    {
      "accessMode": "READ_ONLY",
      "ipRanges": [
        "10.0.0.0/28"
      ],
    }
  ]'

Especifique pelo menos um intervalo de administrador com as permissões READ_WRITE e o squashMode definido como NO_ROOT_SQUASH.

Após a criação de um volume, só é possível modificar as regras de acesso pela API Filestore.

Usar o Filestore com uma VPC compartilhada

Nesta seção, falamos sobre como usar uma instância do Filestore em uma rede VPC compartilhada de um projeto de serviço.

Configurar um cluster com VPC compartilhada.

Para configurar os clusters com uma rede VPC compartilhada, siga estas etapas:

Ativar o driver CSI do Filestore em um novo cluster com a VPC compartilhada

Para ativar o driver CSI do Filestore em um novo cluster com a VPC compartilhada, siga estas etapas:

Verifique as sub-redes utilizáveis e os intervalos secundários. Ao criar um cluster, é preciso especificar uma sub-rede e os intervalos de endereços IP secundários a serem usados para os pods e serviços do cluster.

gcloud container subnets list-usable \
   --project=SERVICE_PROJECT_ID \
   --network-project=HOST_PROJECT_ID

O resultado será assim:

PROJECT                   REGION       NETWORK     SUBNET  RANGE
HOST_PROJECT_ID  us-central1  shared-net  tier-1  10.0.4.0/22
┌──────────────────────┬───────────────┬─────────────────────────────┐
│ SECONDARY_RANGE_NAME │ IP_CIDR_RANGE │            STATUS           │
├──────────────────────┼───────────────┼─────────────────────────────┤
│ tier-1-pods          │ 10.4.0.0/14   │ usable for pods or services │
│ tier-1-services      │ 10.0.32.0/20  │ usable for pods or services │
└──────────────────────┴───────────────┴─────────────────────────────┘

Criar um cluster do GKE. Os exemplos a seguir mostram como é possível usar a CLI gcloud para criar um cluster do Autopilot ou Standard configurado para a VPC compartilhada. Os exemplos a seguir usam a rede, a sub-rede e os nomes de intervalos de Como criar uma rede e duas sub-redes.

Autopilot

gcloud container clusters create-auto tier-1-cluster \
   --project=SERVICE_PROJECT_ID \
   --region=COMPUTE_REGION \
   --network=projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME \
   --subnetwork=projects/HOST_PROJECT_ID/regions/COMPUTE_REGION/subnetworks/SUBNET_NAME \
   --cluster-secondary-range-name=tier-1-pods \
   --services-secondary-range-name=tier-1-services

Standard

gcloud container clusters create tier-1-cluster \
   --project=SERVICE_PROJECT_ID \
   --zone=COMPUTE_REGION \
   --enable-ip-alias \
   --network=projects/HOST_PROJECT_ID/global/networks/NETWORK_NAME \
   --subnetwork=projects/HOST_PROJECT_ID/regions/COMPUTE_REGION/subnetworks/SUBNET_NAME \
   --cluster-secondary-range-name=tier-1-pods \
   --services-secondary-range-name=tier-1-services \
   --addons=GcpFilestoreCsiDriver

Crie regras de firewall para permitir a comunicação entre nós, pods e serviços no cluster. No exemplo a seguir, mostramos como criar uma regra do firewall chamada my-shared-net-rule-2.
```
gcloud compute firewall-rules create my-shared-net-rule-2 \
   --project HOST_PROJECT_ID \
   --network=NETWORK_NAME \
   --allow=tcp,udp \
   --direction=INGRESS \
   --source-ranges=10.0.4.0/22,10.4.0.0/14,10.0.32.0/20
```
No exemplo, os valores de IP dos intervalos de origem vêm da etapa anterior, em que você verificou as sub-redes e os intervalos secundários utilizáveis.

Criar um StorageClass ao usar o driver CSI do Filestore com VPC compartilhada

O exemplo a seguir mostra como criar um StorageClass ao usar o piloto do CSI do Filestore com a VPC compartilhada:

cat <<EOF | kubectl apply -f -

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: filestore-sharedvpc-example
provisioner: filestore.csi.storage.gke.io
parameters:
  network: "projects/HOST_PROJECT_ID/global/networks/SHARED_VPC_NAME"
  connect-mode: PRIVATE_SERVICE_ACCESS
  reserved-ip-range: RESERVED_IP_RANGE_NAME
allowVolumeExpansion: true

EOF

Substitua:

HOST_PROJECT_ID: o ID ou o nome do projeto host da rede VPC compartilhada.
SHARED_VPC_NAME: o nome da rede VPC compartilhada que você criou anteriormente.
RESERVED_IP_RANGE_NAME: o nome do intervalo específico de endereços IP reservados para provisionar a instância do Filestore. Este campo é opcional. Se um intervalo de endereço IP reservado for especificado, ele precisará ser um intervalo de endereços nomeado em vez de um valor de CIDR direto.

Se você quiser provisionar um volume respaldado por multicompartilhamentos do Filestore em clusters do GKE que executam a v1.23 ou posterior, consulte Otimizar o armazenamento com multicompartilhamentos do Filestore para o GKE.

Reconectar volumes de compartilhamento único do Filestore

Se você está usando o Filestore com o nível HDD básico, SSD básico ou empresarial (compartilhamento único), siga estas instruções para reconectar a instância atual do Filestore às suas cargas de trabalho do GKE.

Para encontrar os detalhes da instância pré-provisionada do Filestore, siga as instruções em Como ver informações sobre uma instância específica.
Reimplante a especificação do PersistentVolume. No campo volumeAttributes, modifique os seguintes campos para usar os mesmos valores da sua instância do Filestore da etapa 1:
- ip: modifique esse valor para o endereço IP da instância pré-provisionada do Filestore.
- volume: modifique esse valor para o nome de compartilhamento da instância pré-provisionada do Filestore.
Reimplante a especificação do PersistentVolumeClaim. Em volumeName, lembre-se de referenciar o mesmo nome do PersistentVolume da etapa 2.
Verifique o status de vinculação do PersistentVolumeClaim e do PersistentVolume executando kubectl get pvc.
Reimplante a especificação do pod e verifique se ele consegue acessar o compartilhamento do Filestore novamente.

Acessar instâncias com o driver CSI do Filestore

Benefícios

Requisitos

Antes de começar

Como ativar o driver CSI do Filestore em um novo cluster

gcloud

Console

Ativar o driver CSI do Filestore em um cluster atual

gcloud

Console

Desativar o driver CSI do Filestore

gcloud

Console

Acessar instâncias preeexistentes do Filestore usando o driver CSI do Filestore

Criar um PersistentVolume e um PersistentVolumeClaim para acessar a instância

Criar um volume usando o driver CSI do Filestore

Criar um StorageClass

Usar um PersistentVolumeClaim para acessar o volume

Criar uma implantação que consuma o volume

Rotular instâncias do Filestore

Usar fsgroup com volumes do Filestore

Configurar regras de acesso de IP com volumes do Filestore

Usar o Filestore com uma VPC compartilhada

Configurar um cluster com VPC compartilhada.

Ativar o driver CSI do Filestore em um novo cluster com a VPC compartilhada

Autopilot

Standard

Criar um StorageClass ao usar o driver CSI do Filestore com VPC compartilhada

Reconectar volumes de compartilhamento único do Filestore

A seguir