Merge pull request #62523 from wackxu/ldoc

Automatic merge from submit-queue (batch tested with PRs 59592, 62308, 62523, 62635, 62243). If you want to cherry-pick this change to another branch, please follow the instructions <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md">here</a>.

 update comments for local volume

**What this PR does / why we need it**:

**Which issue(s) this PR fixes** *(optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the issue(s) when PR gets merged)*:
Fixes # https://github.com/kubernetes/kubernetes/issues/62278

**Special notes for your reviewer**:
/assign @jsafrane @msau42 

**Release note**:

```release-note
NONE
```

api/openapi-spec/swagger.json

@@ -77022,13 +77022,13 @@
     }
    },
    "io.k8s.api.core.v1.LocalVolumeSource": {
-    "description": "Local represents directly-attached storage with node affinity",
+    "description": "Local represents directly-attached storage with node affinity (Beta feature)",
     "required": [
      "path"
     ],
     "properties": {
      "path": {
-      "description": "The full path to the volume on the node For alpha, this path must be a directory Once block as a source is supported, then this path can point to a block device",
+      "description": "The full path to the volume on the node. It can be either a directory or block device (disk, partition, ...). Directories can be represented only by PersistentVolume with VolumeMode=Filesystem. Block devices can be represented only by VolumeMode=Block, which also requires the BlockVolume alpha feature gate to be enabled.",
       "type": "string"
      }
     }

api/swagger-spec/v1.json

@@ -19949,14 +19949,14 @@
    },
    "v1.LocalVolumeSource": {
     "id": "v1.LocalVolumeSource",
-    "description": "Local represents directly-attached storage with node affinity",
+    "description": "Local represents directly-attached storage with node affinity (Beta feature)",
     "required": [
      "path"
     ],
     "properties": {
      "path": {
       "type": "string",
-      "description": "The full path to the volume on the node For alpha, this path must be a directory Once block as a source is supported, then this path can point to a block device"
+      "description": "The full path to the volume on the node. It can be either a directory or block device (disk, partition, ...). Directories can be represented only by PersistentVolume with VolumeMode=Filesystem. Block devices can be represented only by VolumeMode=Block, which also requires the BlockVolume alpha feature gate to be enabled."
      }
     }
    },

docs/api-reference/v1/definitions.html

@@ -6491,7 +6491,7 @@ Examples:<br>
 <div class="sect2">
 <h3 id="_v1_localvolumesource">v1.LocalVolumeSource</h3>
 <div class="paragraph">
-<p>Local represents directly-attached storage with node affinity</p>
+<p>Local represents directly-attached storage with node affinity (Beta feature)</p>
 </div>
 <table class="tableblock frame-all grid-all" style="width:100%; ">
 <colgroup>
@@ -6513,7 +6513,7 @@ Examples:<br>
 <tbody>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The full path to the volume on the node For alpha, this path must be a directory Once block as a source is supported, then this path can point to a block device</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The full path to the volume on the node. It can be either a directory or block device (disk, partition, &#8230;). Directories can be represented only by PersistentVolume with VolumeMode=Filesystem. Block devices can be represented only by VolumeMode=Block, which also requires the BlockVolume alpha feature gate to be enabled.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>

pkg/apis/core/types.go

@@ -1434,11 +1434,13 @@ type KeyToPath struct {
 	Mode *int32
 }
 
-// Local represents directly-attached storage with node affinity
+// Local represents directly-attached storage with node affinity (Beta feature)
 type LocalVolumeSource struct {
-	// The full path to the volume on the node
+	// The full path to the volume on the node.
-	// For alpha, this path must be a directory
+	// It can be either a directory or block device (disk, partition, ...).
-	// Once block as a source is supported, then this path can point to a block device
+	// Directories can be represented only by PersistentVolume with VolumeMode=Filesystem.
+	// Block devices can be represented only by VolumeMode=Block, which also requires the
+	// BlockVolume alpha feature gate to be enabled.
 	Path string
 }
 

staging/src/k8s.io/api/core/v1/generated.proto

@@ -1659,11 +1659,13 @@ message LocalObjectReference {
   optional string name = 1;
 }
 
-// Local represents directly-attached storage with node affinity
+// Local represents directly-attached storage with node affinity (Beta feature)
 message LocalVolumeSource {
-  // The full path to the volume on the node
+  // The full path to the volume on the node.
-  // For alpha, this path must be a directory
+  // It can be either a directory or block device (disk, partition, ...).
-  // Once block as a source is supported, then this path can point to a block device
+  // Directories can be represented only by PersistentVolume with VolumeMode=Filesystem.
+  // Block devices can be represented only by VolumeMode=Block, which also requires the
+  // BlockVolume alpha feature gate to be enabled.
   optional string path = 1;
 }
 

staging/src/k8s.io/api/core/v1/types.go

@@ -1513,11 +1513,13 @@ type KeyToPath struct {
 	Mode *int32 `json:"mode,omitempty" protobuf:"varint,3,opt,name=mode"`
 }
 
-// Local represents directly-attached storage with node affinity
+// Local represents directly-attached storage with node affinity (Beta feature)
 type LocalVolumeSource struct {
-	// The full path to the volume on the node
+	// The full path to the volume on the node.
-	// For alpha, this path must be a directory
+	// It can be either a directory or block device (disk, partition, ...).
-	// Once block as a source is supported, then this path can point to a block device
+	// Directories can be represented only by PersistentVolume with VolumeMode=Filesystem.
+	// Block devices can be represented only by VolumeMode=Block, which also requires the
+	// BlockVolume alpha feature gate to be enabled.
 	Path string `json:"path" protobuf:"bytes,1,opt,name=path"`
 }
 

staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go

@@ -865,8 +865,8 @@ func (LocalObjectReference) SwaggerDoc() map[string]string {
 }
 
 var map_LocalVolumeSource = map[string]string{
-	"":     "Local represents directly-attached storage with node affinity",
+	"":     "Local represents directly-attached storage with node affinity (Beta feature)",
-	"path": "The full path to the volume on the node For alpha, this path must be a directory Once block as a source is supported, then this path can point to a block device",
+	"path": "The full path to the volume on the node. It can be either a directory or block device (disk, partition, ...). Directories can be represented only by PersistentVolume with VolumeMode=Filesystem. Block devices can be represented only by VolumeMode=Block, which also requires the BlockVolume alpha feature gate to be enabled.",
 }
 
 func (LocalVolumeSource) SwaggerDoc() map[string]string {