CSI S3

Última atualização em 12 de fevereiro de 2026

Integrar o S3 ao Kubernetes permite que as aplicações interajam com o armazenamento de objetos como se fosse um sistema de arquivos tradicional. No Hostman, isso é feito usando o CSI S3 (Container Storage Interface), possibilitando a conexão transparente de buckets S3 aos pods do Kubernetes.
Abaixo está um guia passo a passo para configurar e usar o CSI S3 em um cluster Kubernetes.

Instalar o CSI S3 
Copiar link

Se o cluster já existir, siga estes passos para instalar o CSI S3:

  1. Vá para a seção Kubernetes e clique no cluster.
  2. Abra a aba Complementos.
  3. Clique nos três pontos ao lado do complemento CSI S3 e selecione Instalar.
  4. Escolha um bucket S3 existente, crie um novo ou conecte um bucket S3 externo.
  5. Clique em Instalar e aguarde a conclusão do processo.

Após a instalação, o bucket estará disponível para uso no cluster sem necessidade de configurações adicionais.

Verificar a instalação
Copiar link

Para garantir que o CSI S3 foi instalado e conectado corretamente, execute os seguintes comandos:

  • Para verificar a StorageClass:
kubectl get storageclass csi-s3 -o yaml
  • Para visualizar os detalhes de conexão com o S3:
kubectl get secret csi-s3-secret -n csi-s3 -o yaml

Os detalhes de conexão aparecerão na seção data em formato Base64.

Usar o CSI S3 no Kubernetes
Copiar link

Como o S3 é um sistema de armazenamento de objetos, o Kubernetes não pode interagir com ele diretamente. O Kubernetes trabalha com sistemas de arquivos e dispositivos de bloco, por isso é usado um PersistentVolumeClaim (PVC) para fazer a ponte por meio do driver CSI.

Uma camada FUSE, como o geesefs, é utilizada para montar o bucket S3 e tornar os arquivos acessíveis como um sistema de arquivos comum.

Observe que o CSI S3 não é totalmente compatível com POSIX. Ele é mais adequado para armazenar arquivos estáticos, como imagens, CSS, JS, arquivos de configuração ou outros dados que não exijam operações intensivas de disco. Problemas podem ocorrer ao hospedar bancos de dados ou aplicações que modificam permissões ou propriedade de arquivos.

Não há suporte para:

  • sobrescrita parcial de arquivos
  • criação de links físicos (hardlinks)

O PVC funciona como uma “solicitação” de armazenamento. O Kubernetes responde criando um PersistentVolume (PV), que é vinculado ao PVC e fornece acesso ao armazenamento.

Abaixo está um exemplo de manifesto PVC para conectar ao S3:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-s3-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: csi-s3

Parâmetros principais do manifesto PVC:

  • apiVersion e kind: definem o recurso como um PersistentVolumeClaim (versão v1).
  • metadata: especifica o nome do PVC (csi-s3-pvc) e o namespace (default).
  • accessModes: define o modo de acesso ao armazenamento. ReadWriteMany permite que vários pods leiam e gravem no mesmo volume.
  • resources.requests.storage: solicita 5 GiB de espaço de armazenamento para a aplicação.
  • storageClassName: indica o nome da StorageClass (csi-s3).

Conectar o PVC a um Deployment
Copiar link

Para permitir que uma aplicação use um PersistentVolumeClaim, é necessário configurá-lo no manifesto do Deployment. Abaixo está um exemplo mostrando como um contêiner Nginx usa um PVC conectado:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: s3-app-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: s3-app
  template:
    metadata:
      labels:
        app: s3-app
    spec:
      containers:
        - name: s3-app-container
          image: nginx
          volumeMounts:
            - name: s3-storage
              mountPath: /usr/share/nginx/html
      volumes:
        - name: s3-storage
          persistentVolumeClaim:
            claimName: csi-s3-pvc

Elementos principais do manifesto do Deployment:

  • apiVersion e kind: especificam que o recurso é um Deployment da versão apps/v1.
  • metadata: define o nome do Deployment (s3-app-deployment) e o namespace (default).
  • replicas: define o número de réplicas (1 neste exemplo), permitindo escalar a aplicação.
  • template: contém a especificação do pod do Deployment.
  • containers: descreve os contêineres incluídos no pod. Neste exemplo, há um contêiner executando a imagem Nginx.
  • volumeMounts: define o ponto de montagem do volume dentro do contêiner. Aqui, o PVC é montado em /usr/share/nginx/html, permitindo que o contêiner acesse dados armazenados no S3 por meio do volume.
  • volumes: especifica os volumes usados pelo pod. O volume s3-storage é vinculado ao PVC chamado csi-s3-pvc, garantindo que os dados do S3 estejam acessíveis por meio desse volume.

O uso de PVC permite que a aplicação acesse dados no S3 e também simplifica o controle de acesso e o escalonamento, garantindo que cada réplica tenha acesso aos dados compartilhados.