Acessar instâncias com o driver CSI do Filestore

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 o número de versão do GKE aplicável ao seu nível de serviço. Apenas os níveis de serviço do Filestore a seguir têm suporte:

    • HDD básico com o GKE versão 1.21 ou posterior
    • SSD básico com o GKE versão 1.21 ou posterior
    • Por zona (10 TiB a 100 TiB) com o GKE versão 1.27 ou mais recente
    • Enterprise com o GKE versão 1.25 ou posterior
    • Para usar o recurso Multicompartilhamentos do Filestore, os clusters precisam usar a versão 1.25 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.

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 um número de versão com suporte para usar esse recurso. Consulte [#requirements] para saber mais. Como alternativa, é possível usar a sinalização --release-channel e especificar um canal de lançamento.

Console

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

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Escolha o modo de cluster Padrão e clique em Configurar.

  4. Configure o cluster de acordo com suas necessidades.

  5. No painel de navegação, em Cluster, clique em Recursos.

  6. Marque a caixa de seleção Ativar driver CSI do Filestore.

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

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

    Acessar o Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que você quer modificar.

  3. Em Recursos, ao lado do campo Driver CSI do Filestore, clique em Editar driver CSI do Filestore.

  4. Marque a caixa de seleção Ativar driver CSI do Filestore.

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

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

    Acessar o Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que você quer modificar.

  3. Em Recursos, ao lado do campo Driver CSI do Filestore, clique em Editar driver CSI do Filestore.

  4. Desmarque a caixa de seleção Ativar driver CSI do Filestore.

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

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

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

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

Cada StorageClass só está disponível em clusters do GKE executados nos respectivos números de versão do GKE com suporte. Para conferir uma lista de versões compatíveis com cada nível de serviço, consulte Requisitos.

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.

O Filestore precisa saber em qual rede criar a nova instância. As StorageClasses instaladas automaticamente usam a rede padrão criada para clusters do GKE. Se você excluiu essa rede ou quer usar uma rede diferente, crie uma nova classe de armazenamento, conforme descrito nas etapas a seguir. Caso contrário, as StorageClasses instaladas automaticamente não funcionarão.

  1. 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 com suporte 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.

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

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

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

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

    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

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

  3. 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 tem suporte para regras de controle de acesso baseadas em IP para volumes. Esse recurso está disponível em clusters do GKE com a versão 1.29.5 ou mais recente.

Esse recurso permite que os administradores especifiquem quais intervalos de endereços IP podem acessar uma instância do Filestore provisionada dinamicamente pelo GKE. Isso aumenta a segurança ao restringir o acesso apenas a clientes autorizados, especialmente em cenários em que o intervalo de IP do cluster do GKE é muito amplo, expondo potencialmente a instância do Filestore a usuários ou aplicativos não autorizados.

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": "ROOT_SQUASH",
      "anonUid": "1003",
      "anonGid": "1003"
    },
    {
      "accessMode": "READ_WRITE",
      "ipRanges": [
        "10.0.0.0/28"
      ],
      "squashMode": "NO_ROOT_SQUASH"
    }
  ]'

Opções de segurança

As regras de acesso de IP do Filestore simplificam a configuração de permissões de armazenamento de arquivos compartilhados para suas cargas de trabalho do GKE. No entanto, para entender como ele gerencia a propriedade e o acesso a arquivos, é preciso compreender alguns conceitos importantes:

  • Mapeamentos de usuários e NFS: o NFS (sistema de arquivos de rede) é o protocolo usado pelo Filestore. Ele funciona mapeando usuários em sistemas de cliente (seus pods do GKE) para usuários no servidor do Filestore. Se um arquivo no servidor for de propriedade do ID do usuário 1003 e um cliente se conectar com o ID do usuário 1003, ele terá acesso ao arquivo.

  • Root squashing e anonUid:

    • O root squashing ROOT_SQUASH é um recurso de segurança que impede que os clientes acessem a instância do Filestore com privilégios raiz completos. Quando o root squashing está ativado, os usuários raiz em sistemas clientes são mapeados para um usuário sem privilégios especificado pela configuração anonUid.

    • Sem root squash (NO_ROOT_SQUASH): permite que os clientes acessem a instância do Filestore com privilégios raiz completos, o que é conveniente para a configuração inicial, mas menos seguro para operações regulares.

  • Configuração inicial e permissões: por padrão, uma nova instância do Filestore é totalmente de propriedade do usuário raiz. Se você ativar o root squashing sem configurar permissões para outros usuários, perderá o acesso. É por isso que você precisa de pelo menos uma regra de exportação NFS com NO_ROOT_SQUASH para configurar inicialmente o acesso de outros usuários e grupos.

Recomendações

  • Configuração inicial: sempre comece com pelo menos uma regra de exportação do NFS que especifique um intervalo de administrador com permissões READ_WRITE e permita acesso NO_ROOT_SQUASH. Use esse acesso para criar diretórios, definir permissões e atribuir a propriedade conforme necessário.
  • Segurança: ative o root squashing (ROOT_SQUASH) para melhorar a segurança. Após a criação de um volume, só é possível modificar as regras de acesso pela API Filestore.
  • Acesso compartilhado:use fsGroup nos contextos de segurança do pod para gerenciar a propriedade de grupo de volumes compartilhados. Não sobreponha a configuração com o modo ROOT_SQUASH. Isso retorna uma mensagem de erro Access denied.

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:

  1. Criar um projeto host e de serviço
  2. Ative a API Google Kubernetes Engine nos projetos de host e de serviço.
  3. No projeto host, crie uma rede e uma sub-rede.
  4. Ativar a VPC compartilhada no projeto host.
  5. No projeto host, conceda a vinculação de papel do usuário HostServiceAgent para a conta de serviço do GKE do projeto de serviço.
  6. Ative o acesso a serviços privados na rede VPC compartilhada.

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:

  1. 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 │
└──────────────────────┴───────────────┴─────────────────────────────┘

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

    Piloto automático

    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

  3. 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 versão 1.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.

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

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

  3. Reimplante a especificação do PersistentVolumeClaim. Em volumeName, lembre-se de referenciar o mesmo nome do PersistentVolume da etapa 2.

  4. Verifique o status de vinculação do PersistentVolumeClaim e do PersistentVolume executando kubectl get pvc.

  5. Reimplante a especificação do pod e verifique se ele consegue acessar o compartilhamento do Filestore novamente.

A seguir