DOCSEARCHbyAlgolia
Submit Docs

pv-mounter

repository·main·Indexed 40 days ago

https://github.com/fenio/pv-mounter

A kubectl plugin to locally mount Kubernetes Persistent Volumes (PVs) using SSHFS or NFS. It automates the creation of helper pods or ephemeral containers and establishes port-forwarding to allow developers to work on cluster files directly on their local machines.

Tokens
4.3K
Snippets
18
Records
24
Agent score
96%

What's inside pv-mounter

  1. Use pv-mounter to mount and unmount Kubernetes PVCs

    main

    pv-mounter is a kubectl plugin designed to mount and unmount Kubernetes PersistentVolumeClaims (PVCs) to your local machine. It automates the complex steps required for local access, including managing pods, ephemeral containers, port-forwarding, and the underlying mount connections.

    To use it, you will primarily use the mount and unmount commands (detailed in their respective guides). You can choose between two backends using the --backend flag:

    • ssh: The default backend, which uses SSHFS.
    • nfs: Uses NFS-Ganesha.

    Before using pv-mounter, ensure you have the necessary prerequisites met for your chosen backend (SSH or NFS).

    # Example concept of selecting a backend (actual command syntax is in the mount guide)
# kubectl pv-mounter mount <pvc-name> <local-path> --backend nfs

  2. How pv-mounter works

    main

    pv-mounter uses SSHFS to mount volumes locally by creating a bridge between your machine and the Kubernetes cluster. The mechanism depends on the volume's access mode and current state:

    RWX (ReadWriteMany) or Unmounted RWO (ReadWriteOnce)

    1. Spawns a POD with a minimalistic image containing an SSH daemon, bound to the existing PVC.
    2. Creates a port-forward to make the SSH daemon locally accessible.
    3. Mounts the volume locally using SSHFS.

    Already Mounted RWO (ReadWriteOnce)

    For volumes already attached to a running pod, the process uses an ephemeral container to tunnel the data:

    1. Spawns a POD with a minimalistic image containing an SSH daemon that acts as a proxy to an ephemeral container.
    2. Creates an ephemeral container within the POD that currently holds the volume mount.
    3. Establishes a reverse SSH tunnel from the ephemeral container to the proxy POD.
    4. Creates a port-forward to the proxy POD on the port exposed by the tunnel.
    5. Mounts the volume locally using SSHFS.

  3. Security considerations for pv-mounter backends

    main

    pv-mounter implements different security models depending on the backend:

    SSH Backend

    • Credentials: SSH keys are generated from scratch every time. Once the environment is wiped, old credentials will not work.
    • Privileges: By default, containers use minimal privileges (allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, runAsNonRoot: true).
    • Configuration: sshd_config is hardened (PermitRootLogin no, PasswordAuthentication no) unless the --needs-root flag is used.

    NFS Backend

    • Capabilities: NFS-Ganesha requires higher privileges (SYS_ADMIN, DAC_READ_SEARCH, etc.) and runs with seccompProfile: Unconfined.
    • Privileges: Standalone NFS pods run as root; ephemeral NFS containers run as the workload pod's UID.
    • Traffic: NFS exports use No_Root_Squash and SecType = sys (AUTH_SYS), but this is considered safe because traffic is encapsulated within a kubectl port-forward tunnel (accessible only via localhost).

  4. How pv-mounter works: SSH vs NFS backends

    main

    pv-mounter automates the process of making Kubernetes volumes accessible locally by spawning backend components based on the volume's access mode:

    For RWX (ReadWriteMany) or unmounted RWO (ReadWriteOnce) volumes:

    1. Spawns a standalone Pod with the chosen backend (SSH daemon or NFS-Ganesha) and binds it to the existing PVC.
    2. Creates a port-forward to make the backend locally accessible.
    3. Mounts the volume locally using SSHFS (for SSH backend) or NFSv4 (for NFS backend).

    For already mounted RWO volumes:

    1. Creates an ephemeral container with the chosen backend within the Pod that currently mounts the volume.
    2. Creates a port-forward directly to the workload Pod.
    3. Mounts the volume locally using SSHFS or NFSv4.

  5. Use the pv-mounter mount command

    main

    The pv-mounter mount command allows you to mount a Kubernetes PersistentVolumeClaim (PVC) to a local directory on your machine. It automates the setup of necessary Kubernetes resources and establishes a connection to the volume using a specified backend.

    To use this command, you must provide the Kubernetes namespace, the name of the PVC, and the local directory where you want the volume to be mounted.

    pv-mounter mount [flags] <namespace> <pvc-name> <local-mount-point>

  6. Mount a Kubernetes Persistent Volume locally

    main

    Use the kubectl pv-mounter mount command to mount a PVC to a local directory. The tool supports two backends: ssh (default) and nfs.

    Command Syntax: kubectl pv-mounter mount [--backend ssh|nfs] [--needs-root] [--debug] [--image] [--image-secret] <namespace> <pvc-name> <local-mount-point>

    Options:

    • --backend <ssh|nfs>: Specifies the backend to use. Defaults to ssh.
    • --needs-root: Runs the backend with root privileges (use if your environment requires it, but note it bypasses some security defaults).
    • --debug: Enables debug logging.
    • --image <image-name>: Specifies a custom container image to use for the backend.
    • --image-secret <secret-name>: Specifies the image pull secret for the custom image.
    # Example: Mounting a PVC using the default SSH backend
kubectl pv-mounter mount my-namespace my-pvc /tmp/local-mount

# Example: Mounting a PVC using the NFS backend
kubectl pv-mounter mount --backend nfs my-namespace my-pvc /tmp/local-mount

  7. Clean up mounted Persistent Volumes

    main

    To remove the resources created by pv-mounter (such as standalone pods or port-forwards), use the clean command.

    Note: Due to Kubernetes limitations, ephemeral containers cannot be deleted. The tool will kill the process keeping the ephemeral container alive, but the container itself may remain in a 'limbo' state.

    # Example: Cleaning up an SSH mount
kubectl pv-mounter clean --backend ssh my-namespace my-pvc /tmp/local-mount

# Example: Cleaning up an NFS mount
kubectl pv-mounter clean --backend nfs my-namespace my-pvc /tmp/local-mount

  10. Mount a PVC to a local directory

    main

    Use the mount command to attach a Kubernetes PersistentVolumeClaim (PVC) to a directory on your local machine.

    Syntax: kubectl pv-mounter mount <namespace> <pvc-name> <local-mountpoint>

    Example:

    kubectl pv-mounter mount some-ns some-pvc some-mountpoint

  11. Prerequisites for SSH and NFS backends

    main

    Depending on the backend you choose, you must have the following client tools installed on your local machine:

    SSH Backend (Default)

    Requires SSHFS:

    • macOS: Install via macOSFUSE.
    • Linux: Install via your package manager (e.g., libfuse for SSHFS).

    NFS Backend

    Requires an NFS client:

    • macOS: Built-in, no installation required.
    • Linux: Install nfs-common (Debian/Ubuntu) or nfs-utils (RHEL/Fedora).