Usar um Volume de Imagem com um Pod

ESTADO DA FUNCIONALIDADE: Kubernetes v1.36 [stable](habilitado por padrão)

Esta página mostra como configurar um pod usando volumes de imagem. Isso permite que você monte conteúdo de registros OCI dentro de contêineres.

Antes de você começar

Você precisa ter um cluster do Kubernetes e a ferramenta de linha de comando kubectl deve estar configurada para se comunicar com seu cluster. É recomendado executar esse tutorial em um cluster com pelo menos dois nós que não estejam atuando como hosts de camada de gerenciamento. Se você ainda não possui um cluster, pode criar um usando o minikube ou pode usar um dos seguintes ambientes:

O seu servidor Kubernetes deve estar numa versão igual ou superior a v1.31.

Para verificar a versão, digite kubectl version.

  • O agente de execução de contêiner precisa suportar a funcionalidade de volumes de imagem
  • Você precisa executar comandos no host
  • Você precisa ser capaz de executar comandos dentro dos pods

Executar um Pod que usa um volume de imagem

Um volume de imagem para um pod é habilitado definindo o campo volumes[*].image de .spec como uma referência válida e consumindo-o nos volumeMounts do contêiner. Por exemplo:

pods/image-volumes.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: image-volume
spec:
  containers:
  - name: shell
    command: ["sleep", "infinity"]
    image: debian
    volumeMounts:
    - name: volume
      mountPath: /volume
  volumes:
  - name: volume
    image:
      reference: quay.io/crio/artifact:v2
      pullPolicy: IfNotPresent

  1. Crie o pod no seu cluster:

    kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml

  2. Acesse o contêiner:

    kubectl exec image-volume -it -- bash

  3. Verifique o conteúdo de um arquivo no volume:

    cat /volume/dir/file

    A saída é semelhante a:

    1

    Você também pode verificar outro arquivo em um caminho diferente:

    cat /volume/file

    A saída é semelhante a:

    2

Usar subPath (ou subPathExpr)

É possível utilizar subPath ou subPathExpr a partir do Kubernetes v1.33 ao usar a funcionalidade de volumes de imagem.

pods/image-volumes-subpath.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: image-volume
spec:
  containers:
  - name: shell
    command: ["sleep", "infinity"]
    image: debian
    volumeMounts:
    - name: volume
      mountPath: /volume
      subPath: dir
  volumes:
  - name: volume
    image:
      reference: quay.io/crio/artifact:v2
      pullPolicy: IfNotPresent

  1. Crie o pod no seu cluster:

    kubectl apply -f https://k8s.io/examples/pods/image-volumes-subpath.yaml

  2. Acesse o contêiner:

    kubectl exec image-volume -it -- bash

  3. Verifique o conteúdo do arquivo a partir do subdiretório dir no volume:

    cat /volume/file

    A saída é semelhante a:

    1

Leitura adicional

Última modificação March 08, 2026 at 6:39 PM PST: [pt-br] Add tasks/configure-pod-container/image-volumes.md (05d8872753)