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

This document (000020216) is provided subject to the disclaimer at the end of this document.

Situation

Issue

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

Pre-requisites

Root Cause

This behavior is a result of the containerized kubelet process in RKE and Rancher launched Kubernetes clusters, and is tracked in GitHub issue https://github.com/rancher/rancher/issues/14836

Pending resolution of this issue, you should avoid the use of the subPath option on hostPath volumes, to prevent encountering this.

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

  • Document ID:000020216
  • Creation Date: 06-May-2021
  • Modified Date:06-May-2021
    • SUSE Rancher

< Back to Support Search

For questions or concerns with the SUSE Knowledgebase please contact: tidfeedback[at]suse.com

SUSE Support Forums

Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

Join Our Community

Support Resources

Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.


SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
Support FAQ

Open an Incident

Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

Go to Customer Center