Ubuntu下Docker Desktop的Kubernetes HostPath挂载失效求助

kind: PersistentVolume
apiVersion: v1
metadata:
name: shared-vol-pv
namespace: default
spec:
volumeMode: Filesystem
persistentVolumeReclaimPolicy: Retain
storageClassName: manual
capacity:
storage: 100Mi
accessModes:
- ReadWriteOnce
hostPath:
path: /home/Documents/ #

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: shared-vol-pvc
namespace: default
spec:
storageClassName: manual
volumeName: shared-vol-pv
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 100Mi

运行后，通过`kubectl exec -it busybox -- bash`进入Pod，导航到`/home/data/`执行`ls`无结果；在Pod内执行`touch testFile`创建文件，本地Ubuntu系统的`/home/Documents/`目录也未同步出现该文件。

**运行环境**：Ubuntu系统上的`docker-desktop`（Kubernetes版本1.25.4，Docker Desktop版本4.17.0 (99724)）

**补充信息**：
### `kubectl get pv shared-vol-pv`输出

Name: shared-vol-pv
Labels:
Annotations: pv.kubernetes.io/bound-by-controller: yes
Finalizers: [kubernetes.io/pv-protection]
StorageClass: manual
Status: Bound
Claim: default/shared-vol-pvc
Reclaim Policy: Retain
Access Modes: RWO
VolumeMode: Filesystem
Capacity: 100Mi
Node Affinity:
Message:
Source:
Type: HostPath (bare host directory volume)
Path: /home/Documents/
HostPathType:
Events:

### `kubectl describe pod busybox`输出

Name: busybox
Namespace: default
Priority: 0
Service Account: default
Node: docker-desktop/192.168.65.4
Start Time: Fri, 24 Mar 2023 00:34:22 +0800
Labels:
Annotations:
Status: Running
IP: 10.1.1.1
IPs:
IP: 10.1.1.1
Containers:
busybox:
Container ID: docker://c1441be57becbf00d028f761b35606e49694a5c944c3f3735ddac8dc3e59447a
Image: ubuntu
Image ID: docker-pullable://ubuntu@sha256:67211c14fa74f070d27cc59d69a7fa9aeff8e28ea118ef3babc295a0428a6d21
Port:
Host Port:
Command:
sleep
3600
State: Running
Started: Fri, 24 Mar 2023 21:40:56 +0800
Last State: Terminated
Reason: Error
Exit Code: 255
Started: Fri, 24 Mar 2023 00:34:23 +0800
Finished: Fri, 24 Mar 2023 21:40:44 +0800
Ready: True
Restart Count: 1
Environment:
Mounts:
/home/data/ from shared-vol-extensions (rw)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-4s5jp (ro)
Conditions:
Type Status
Initialized True
Ready True
ContainersReady True
PodScheduled True
Volumes:
shared-vol-extensions:
Type: PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
ClaimName: shared-vol-pvc
ReadOnly: false
kube-api-access-4s5jp:
Type: Projected (a volume that contains injected data from multiple sources)
TokenExpirationSeconds: 3607
ConfigMapName: kube-root-ca.crt
ConfigMapOptional:
DownwardAPI: true
QoS Class: BestEffort
Node-Selectors:
Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
Type Reason Age From Message

Warning FailedScheduling 21h default-scheduler 0/1 nodes are available: 1 persistentvolumeclaim "shared-vol-pvc" not found. preemption: 0/1 nodes are available: 1 Preemption is not helpful for scheduling.
Normal Scheduled 21h default-scheduler Successfully assigned default/busybox to docker-desktop
Normal Pulled 21h kubelet Container image "ubuntu" already present on machine
Normal Created 21h kubelet Created container busybox
Normal Started 21h kubelet Started container busybox
Normal SandboxChanged 4m5s kubelet Pod sandbox changed, it will be killed and re-created.
Normal Pulled 4m4s kubelet Container image "ubuntu" already present on machine
Normal Created 4m4s kubelet Created container busybox
Normal Started 4m4s kubelet Started container busybox

请问出现该问题的原因是什么？有哪些可行的解决办法？

---

# 原因分析
Docker Desktop在Ubuntu上运行时，Kubernetes节点实际是一个独立的**虚拟机**，并非直接运行在你的Ubuntu主机系统中。你在PV里指定的`/home/Documents/`路径，指向的是这个虚拟机内部的目录，而非你Ubuntu主机的`/home/Documents/`。这就是Pod内的文件操作无法同步到本地主机的核心原因。

从Pod描述可以看到，Pod被调度到`docker-desktop/192.168.65.4`节点，这个节点就是Docker Desktop创建的隔离虚拟机，和你的本地主机环境完全分开。

# 解决办法
### 1. 使用Docker Desktop的主机映射路径
Docker Desktop默认会将主机的部分目录共享到虚拟机，比如`/home`通常会被自动共享。你需要修改PV的`hostPath`为虚拟机内映射主机目录的路径：
- 先打开Docker Desktop设置 -> Resources -> File Sharing，确认`/home`已在共享列表中，若没有则添加并重启Docker Desktop。
- 修改PV的`hostPath`为`/run/desktop/mnt/host/home/Documents/`，这是虚拟机映射主机`/home/Documents/`的标准路径，同时建议添加`type`字段确保目录不存在时自动创建。

修改后的PV片段：
```yaml
kind: PersistentVolume
apiVersion: v1
metadata:
  name: shared-vol-pv
  namespace: default
spec:
  volumeMode: Filesystem
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  capacity:
    storage: 100Mi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /run/desktop/mnt/host/home/Documents/
    type: DirectoryOrCreate

2. 简化配置，直接在Pod中挂载hostPath #

如果只是测试hostPath功能，可以跳过PV/PVC，直接在Pod定义中挂载hostPath：

apiVersion: v1
kind: Pod
metadata:
  name: busybox
  namespace: default
spec:
  containers:
    - image: ubuntu
      command:
        - sleep
        - "3600"
      imagePullPolicy: IfNotPresent
      name: busybox
      volumeMounts:
        - mountPath: /home/data/
          name: shared-vol
  volumes:
    - name: shared-vol
      hostPath:
        path: /run/desktop/mnt/host/home/Documents/
        type: DirectoryOrCreate
  restartPolicy: Always

3. 验证挂载有效性 #

应用修改后的配置后，执行以下步骤验证：

# 进入Pod
kubectl exec -it busybox -- bash
# 进入挂载目录
cd /home/data/
# 创建测试文件
touch testFromPod.txt
# 查看文件是否存在
ls

回到Ubuntu主机的/home/Documents/目录，检查是否出现testFromPod.txt文件，确认同步正常。

内容的提问来源于stack exchange，提问作者jake wong