pillar-csi

pillar-csi é um driver CSI do Kubernetes para clusters bare-metal auto-hospedados. Ele pega zvols ZFS locais ou volumes lógicos LVM em um nó de armazenamento dedicado e os exporta para o restante do cluster via NVMe-oF/TCP, gravando diretamente no kernel através do configfs em vez de depender de SSH, daemons Python ou CLIs de target externas. Ele explicitamente não é um sistema de arquivos distribuído: não replica, faz striping nem agrupa armazenamento entre nós. A arquitetura consiste em três workloads. O pillar-controller roda como um Deployment e reconcilia CRDs Pillar* com escopo de cluster. O pillar-agent roda como um DaemonSet apenas nos nós de armazenamento e é responsável por todas as gravações em configfs no host. O pillar-node roda em cada worker e lida com o serviço CSI Node (conexão do iniciador, mkfs, bind-mount). Ambos os DaemonSets usam hostNetwork para que o plano de dados NVMe-oF/TCP possa se vincular ao namespace de rede do host. A configuração é declarativa através de CRDs: PillarAgent localiza um agente de armazenamento, PillarStore descreve um pool de armazenamento (nome do pool ZFS, VG LVM, configuração de backend), PillarProtocol descreve a configuração do protocolo de rede, e PillarStorageClass combina pool e protocolo em uma StorageClass gerada automaticamente. Um CRD interno PillarVolumeState registra estado durável para recuperação de falhas parciais de provisionamento e rastreamento de publicação; o controller impõe exclusividade de modo de acesso CSI a partir desse registro. Um elemento de design notável é o fencing de operações obsoletas. Toda chamada ao agente que altera os recursos de um volume carrega um token de fencing composto pelo UID do estado do volume (identidade do ciclo de vida) e um contador publicationGeneration incrementado via compare-and-swap. O agente mantém marcas duráveis por volume no disco local do nó de armazenamento em /var/lib/pillar-csi/agent/generations/, montado como hostPath para que as marcas sobrevivam a reinicializações e reboots. Requisições mais antigas que a marca, de um ciclo de vida encerrado ou substituído, ou sem token, são rejeitadas com FAILED_PRECONDITION. O README observa uma ressalva de upgrade: desanexe todos os volumes antes de atualizar, já que versões anteriores não registravam publicações, ciclos de vida ou gerações, e nenhum shim de migração é fornecido. O estado de stage do nó é registrado em /var/lib/pillar-csi/node/ no worker, gravado atomicamente via arquivo temporário, sync e rename. NodeUnstageVolume lê o registro de volta porque o CO não envia nem volume capability nem volume context no unstage. As decisões de unmount delegam ao Unmount idempotente do mounter, tratando erros de sondagem de montagem corrompida (EIO, ENOTCONN, ESTALE, EACCES) como ainda montados para que o kubelet possa eliminar pods cujo sistema de arquivos entrou em shutdown do kernel. Matriz suportada: ZFS zvol e LVM LV sobre NVMe-oF/TCP são entregues; iSCSI é projetado mas ainda não entregue; NFS para datasets ZFS é projetado mas ainda não entregue. As operações CSI incluem CreateVolume, DeleteVolume, ControllerPublish/Unpublish, ControllerExpandVolume, NodeStage/Unstage, NodePublish/Unpublish, NodeExpandVolume, NodeGetVolumeStats, ValidateVolumeCapabilities e GetCapacity. Os modos de acesso são ReadWriteOnce, ReadWriteOncePod e ReadOnlyMany; os modos de volume são Filesystem (ext4/xfs) e Block. A instalação é via Helm. mTLS entre controller e agent é opt-in (modo cert-manager ou modo Secret fornecido); o padrão é gRPC em texto simples. É necessário Kubernetes 1.24 ou mais recente. Nós de armazenamento precisam dos módulos de kernel nvmet e nvmet_tcp; nós worker precisam de nvme_tcp e nvme_fabrics; init-containers executam modprobe na inicialização. O README inclui um quickstart com exemplos de YAML de CRD, solução de problemas via kubectl describe e logs padrão, e um procedimento detalhado de recuperação para volumes legados presos em ExportSpecMissing, enfatizando decisões explícitas do operador para bindAddress, port e aclEnabled em vez de adivinhar a partir de observações em tempo de execução.