subPath does not work with hostPath volumes in Rancher v2.x or RKE CLI launched Kubernetes clusters

• Any Rancher Kubernetes Enginer (RKE) cluster, both those provisioned by the RKE CLI or Rancher v2.x launched Kubernetes cluster

Attempting to use the subPath option with a hostPath volume in a Rancher Kubernetes Engine (RKE) CLI, or Rancher v2.x, launched Kubernetes fails. The particular failure type depends upon the value of the type field specified on the hostPath volume.

type undefined

If no type is specified (defined as Anything: do not check the target path within the Rancher UI), per the example spec below, then the Pod will fail to start and the Pod events will show an error of the format Error: lstat /site-data: no such file or directory

spec:
  containers:
  - name: nginx
    image: nginx:latest
    volumeMounts:
    - mountPath: /volume/nginx
      name: site-data
      subPath: nginx
  volumes:
  - name: site-data
    hostPath:
      path: /site-data

type: Directory

If the type is specified as Directory (defined as An existing directory within the Rancher UI), per the example spec below, then the Pod will fail to start and the Pod events will show an error of the format MountVolume.SetUp failed for volume "site-data" : hostPath type check failed: /site-data is not a directory

spec:
  containers:
  - name: nginx
    image: nginx:latest
    volumeMounts:
    - mountPath: /volume/nginx
      name: site-data
      subPath: nginx
  volumes:
  - name: site-data
    hostPath:
      path: /site-data
      type: Directory

type: DirectoryOrCreate

If the type is specified as DirectoryOrCreate (defined as A directory, or create if it does not exist within the Rancher UI), per the example spec below, then the Pod will start successfully; however, an empty local volume will be mounted in the container at the mountPath, rather than this being bind-mounted to the path on the host as expected.

spec:
  containers:
  - name: nginx
    image: nginx:latest
    volumeMounts:
    - mountPath: /volume/nginx
      name: site-data
      subPath: nginx
  volumes:
  - name: site-data
    hostPath:
      path: /site-data
      type: DirectoryOrCreate

Instead of using a hostPath volume with a subPath, multiple hostPath volumes without a subPath can be used.

This behavior is a result of the containerized kubelet process in RKE clusters, and a detailed description can be found in https://github.com/rancher/rancher/issues/14836#issuecomment-624186494