From f6c7d70092a9c73d5006a4b6abf8aa5c826c89b2 Mon Sep 17 00:00:00 2001 From: Prashant Sharma Date: Thu, 2 Apr 2020 16:48:23 +0530 Subject: [PATCH] Minor, Api doc clarification for the mode value. (#88364) * Api doc clarification for the mode value. Apply suggestions from code review Co-Authored-By: Robert Kielty * Added a note regarding json and yaml api. * running hack/* scripts. Co-authored-by: Robert Kielty --- api/openapi-spec/swagger.json | 12 +++---- .../src/k8s.io/api/core/v1/generated.proto | 34 +++++++++++++------ staging/src/k8s.io/api/core/v1/types.go | 34 +++++++++++++------ .../core/v1/types_swagger_doc_generated.go | 12 +++---- 4 files changed, 58 insertions(+), 34 deletions(-) diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json index 2550a0906367c..14f5fdce2b174 100644 --- a/api/openapi-spec/swagger.json +++ b/api/openapi-spec/swagger.json @@ -5506,7 +5506,7 @@ "description": "Adapts a ConfigMap into a volume.\n\nThe contents of the target ConfigMap's Data field will be presented in a volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. ConfigMap volumes support ownership management and SELinux relabeling.", "properties": { "defaultMode": { - "description": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, @@ -5877,7 +5877,7 @@ "description": "Required: Selects a field of the pod: only annotations, labels, name and namespace are supported." }, "mode": { - "description": "Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, @@ -5899,7 +5899,7 @@ "description": "DownwardAPIVolumeSource represents a volume containing downward API info. Downward API volumes support ownership management and SELinux relabeling.", "properties": { "defaultMode": { - "description": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, @@ -6862,7 +6862,7 @@ "type": "string" }, "mode": { - "description": "Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, @@ -8835,7 +8835,7 @@ "description": "Represents a projected volume source", "properties": { "defaultMode": { - "description": "Mode bits to use on created files by default. Must be a value between 0 and 0777. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, @@ -9616,7 +9616,7 @@ "description": "Adapts a Secret into a volume.\n\nThe contents of the target Secret's Data field will be presented in a volume as files using the keys in the Data field as the file names. Secret volumes support ownership management and SELinux relabeling.", "properties": { "defaultMode": { - "description": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "description": "Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "format": "int32", "type": "integer" }, diff --git a/staging/src/k8s.io/api/core/v1/generated.proto b/staging/src/k8s.io/api/core/v1/generated.proto index 041f53008ac13..40843d0450d3f 100644 --- a/staging/src/k8s.io/api/core/v1/generated.proto +++ b/staging/src/k8s.io/api/core/v1/generated.proto @@ -588,8 +588,10 @@ message ConfigMapVolumeSource { // +optional repeated KeyToPath items = 2; - // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -957,8 +959,10 @@ message DownwardAPIVolumeFile { // +optional optional ResourceFieldSelector resourceFieldRef = 3; - // Optional: mode bits to use on this file, must be a value between 0 - // and 0777. If not specified, the volume defaultMode will be used. + // Optional: mode bits used to set permissions on this file, must be an octal value + // between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // If not specified, the volume defaultMode will be used. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. // +optional @@ -973,7 +977,10 @@ message DownwardAPIVolumeSource { repeated DownwardAPIVolumeFile items = 1; // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -1880,8 +1887,10 @@ message KeyToPath { // May not start with the string '..'. optional string path = 2; - // Optional: mode bits to use on this file, must be a value between 0 - // and 0777. If not specified, the volume defaultMode will be used. + // Optional: mode bits used to set permissions on this file. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // If not specified, the volume defaultMode will be used. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. // +optional @@ -3788,8 +3797,9 @@ message ProjectedVolumeSource { // list of volume projections repeated VolumeProjection sources = 1; - // Mode bits to use on created files by default. Must be a value between - // 0 and 0777. + // Mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -4419,8 +4429,10 @@ message SecretVolumeSource { // +optional repeated KeyToPath items = 2; - // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values + // for mode bits. Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go index 5bbf76bb19eb6..37a11b00bad6c 100644 --- a/staging/src/k8s.io/api/core/v1/types.go +++ b/staging/src/k8s.io/api/core/v1/types.go @@ -1092,8 +1092,10 @@ type SecretVolumeSource struct { // relative and may not contain the '..' path or start with '..'. // +optional Items []KeyToPath `json:"items,omitempty" protobuf:"bytes,2,rep,name=items"` - // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values + // for mode bits. Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -1518,8 +1520,10 @@ type ConfigMapVolumeSource struct { // relative and may not contain the '..' path or start with '..'. // +optional Items []KeyToPath `json:"items,omitempty" protobuf:"bytes,2,rep,name=items"` - // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -1585,8 +1589,9 @@ type ServiceAccountTokenProjection struct { type ProjectedVolumeSource struct { // list of volume projections Sources []VolumeProjection `json:"sources" protobuf:"bytes,1,rep,name=sources"` - // Mode bits to use on created files by default. Must be a value between - // 0 and 0777. + // Mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -1626,8 +1631,10 @@ type KeyToPath struct { // May not contain the path element '..'. // May not start with the string '..'. Path string `json:"path" protobuf:"bytes,2,opt,name=path"` - // Optional: mode bits to use on this file, must be a value between 0 - // and 0777. If not specified, the volume defaultMode will be used. + // Optional: mode bits used to set permissions on this file. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // If not specified, the volume defaultMode will be used. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. // +optional @@ -5730,7 +5737,10 @@ type DownwardAPIVolumeSource struct { // +optional Items []DownwardAPIVolumeFile `json:"items,omitempty" protobuf:"bytes,1,rep,name=items"` // Optional: mode bits to use on created files by default. Must be a - // value between 0 and 0777. Defaults to 0644. + // Optional: mode bits used to set permissions on created files by default. + // Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // Defaults to 0644. // Directories within the path are not affected by this setting. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. @@ -5753,8 +5763,10 @@ type DownwardAPIVolumeFile struct { // (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. // +optional ResourceFieldRef *ResourceFieldSelector `json:"resourceFieldRef,omitempty" protobuf:"bytes,3,opt,name=resourceFieldRef"` - // Optional: mode bits to use on this file, must be a value between 0 - // and 0777. If not specified, the volume defaultMode will be used. + // Optional: mode bits used to set permissions on this file, must be an octal value + // between 0000 and 0777 or a decimal value between 0 and 511. + // YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. + // If not specified, the volume defaultMode will be used. // This might be in conflict with other options that affect the file // mode, like fsGroup, and the result can be other mode bits set. // +optional diff --git a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go index cbefa2c053e69..12ce36f7f3970 100644 --- a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go +++ b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go @@ -316,7 +316,7 @@ func (ConfigMapProjection) SwaggerDoc() map[string]string { var map_ConfigMapVolumeSource = map[string]string{ "": "Adapts a ConfigMap into a volume.\n\nThe contents of the target ConfigMap's Data field will be presented in a volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. ConfigMap volumes support ownership management and SELinux relabeling.", "items": "If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'.", - "defaultMode": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "defaultMode": "Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "optional": "Specify whether the ConfigMap or its keys must be defined", } @@ -462,7 +462,7 @@ var map_DownwardAPIVolumeFile = map[string]string{ "path": "Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..'", "fieldRef": "Required: Selects a field of the pod: only annotations, labels, name and namespace are supported.", "resourceFieldRef": "Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.", - "mode": "Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "mode": "Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", } func (DownwardAPIVolumeFile) SwaggerDoc() map[string]string { @@ -472,7 +472,7 @@ func (DownwardAPIVolumeFile) SwaggerDoc() map[string]string { var map_DownwardAPIVolumeSource = map[string]string{ "": "DownwardAPIVolumeSource represents a volume containing downward API info. Downward API volumes support ownership management and SELinux relabeling.", "items": "Items is a list of downward API volume file", - "defaultMode": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "defaultMode": "Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", } func (DownwardAPIVolumeSource) SwaggerDoc() map[string]string { @@ -880,7 +880,7 @@ var map_KeyToPath = map[string]string{ "": "Maps a string key to a path within a volume.", "key": "The key to project.", "path": "The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'.", - "mode": "Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "mode": "Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", } func (KeyToPath) SwaggerDoc() map[string]string { @@ -1760,7 +1760,7 @@ func (Probe) SwaggerDoc() map[string]string { var map_ProjectedVolumeSource = map[string]string{ "": "Represents a projected volume source", "sources": "list of volume projections", - "defaultMode": "Mode bits to use on created files by default. Must be a value between 0 and 0777. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "defaultMode": "Mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", } func (ProjectedVolumeSource) SwaggerDoc() map[string]string { @@ -2081,7 +2081,7 @@ var map_SecretVolumeSource = map[string]string{ "": "Adapts a Secret into a volume.\n\nThe contents of the target Secret's Data field will be presented in a volume as files using the keys in the Data field as the file names. Secret volumes support ownership management and SELinux relabeling.", "secretName": "Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret", "items": "If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'.", - "defaultMode": "Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", + "defaultMode": "Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.", "optional": "Specify whether the Secret or its keys must be defined", }