Merge pull request #574 from wking/config-optional-required

config: Use REQUIRED and OPTIONAL for properties

Author: Mrunal Patel

config-linux.md

@@ -26,7 +26,7 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man7/na
 Namespaces are specified as an array of entries inside the `namespaces` root field.
 The following parameters can be specified to setup namespaces:
 
-* **`type`** *(string, required)* - namespace type. The following namespaces types are supported:
+* **`type`** *(string, REQUIRED)* - namespace type. The following namespaces types are supported:
     * **`pid`** processes inside the container will only be able to see other processes inside the same container.
     * **`network`** the container will have its own network stack.
     * **`mount`** the container will have an isolated mount table.
@@ -35,7 +35,7 @@ The following parameters can be specified to setup namespaces:
     * **`user`** the container will be able to remap user and group IDs from the host to local users and groups within the container.
     * **`cgroup`** the container will have an isolated view of the cgroup hierarchy.
 
-* **`path`** *(string, optional)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
+* **`path`** *(string, OPTIONAL)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
 
 If a path is specified, that particular file is used to join that type of namespace.
 If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
@@ -99,19 +99,19 @@ There is a limit of 5 mappings which is the Linux kernel hard limit.
 
 ## Devices
 
-**`devices`** (array, optional) lists devices that MUST be available in the container.
+**`devices`** (array, OPTIONAL) lists devices that MUST be available in the container.
 The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
 
 The following parameters can be specified:
 
-* **`type`** *(string, required)* - type of device: `c`, `b`, `u` or `p`.
+* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`.
   More info in [mknod(1)][mknod.1].
-* **`path`** *(string, required)* - full path to device inside container.
-* **`major, minor`** *(int64, required unless **`type`** is `p`)* - [major, minor numbers][devices] for the device.
-* **`fileMode`** *(uint32, optional)* - file mode for the device.
+* **`path`** *(string, REQUIRED)* - full path to device inside container.
+* **`major, minor`** *(int64, REQUIRED unless **`type`** is `p`)* - [major, minor numbers][devices] for the device.
+* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device.
   You can also control access to devices [with cgroups](#device-whitelist).
-* **`uid`** *(uint32, optional)* - id of device owner.
-* **`gid`** *(uint32, optional)* - id of device group.
+* **`uid`** *(uint32, OPTIONAL)* - id of device owner.
+* **`gid`** *(uint32, OPTIONAL)* - id of device group.
 
 ###### Example
 
@@ -199,17 +199,17 @@ However, a runtime MAY attach the container process to additional cgroup control
 
 #### Device whitelist
 
-**`devices`** (array, optional) configures the [device whitelist][cgroup-v1-devices].
+**`devices`** (array, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
 The runtime MUST apply entries in the listed order.
 
 The following parameters can be specified:
 
-* **`allow`** *(boolean, required)* - whether the entry is allowed or denied.
-* **`type`** *(string, optional)* - type of device: `a` (all), `c` (char), or `b` (block).
+* **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied.
+* **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block).
   `null` or unset values mean "all", mapping to `a`.
-* **`major, minor`** *(int64, optional)* - [major, minor numbers][devices] for the device.
+* **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device.
   `null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
-* **`access`** *(string, optional)* - cgroup permissions for device.
+* **`access`** *(string, OPTIONAL)* - cgroup permissions for device.
   A composition of `r` (read), `w` (write), and `m` (mknod).
 
 ###### Example
@@ -245,7 +245,7 @@ The OOM killer is enabled by default in every cgroup using the `memory` subsyste
 To disable it, specify a value of `true`.
 For more information, see [the memory cgroup man page][cgroup-v1-memory].
 
-* **`disableOOMKiller`** *(bool, optional)* - enables or disables the OOM killer
+* **`disableOOMKiller`** *(bool, OPTIONAL)* - enables or disables the OOM killer
 
 ###### Example
 
@@ -260,7 +260,7 @@ For more information, see [the proc filesystem documentation section 3.1](https:
 This is a kernel/system level setting, where as `disableOOMKiller` is scoped for a memory cgroup.
 For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory].
 
-* **`oomScoreAdj`** *(int, optional)* - adjust the oom-killer score
+* **`oomScoreAdj`** *(int, OPTIONAL)* - adjust the oom-killer score
 
 ###### Example
 
@@ -275,17 +275,17 @@ For more information, see [the memory cgroup man page][cgroup-v1-memory].
 
 The following parameters can be specified to setup the controller:
 
-* **`limit`** *(uint64, optional)* - sets limit of memory usage in bytes
+* **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes
 
-* **`reservation`** *(uint64, optional)* - sets soft limit of memory usage in bytes
+* **`reservation`** *(uint64, OPTIONAL)* - sets soft limit of memory usage in bytes
 
-* **`swap`** *(uint64, optional)* - sets limit of memory+Swap usage
+* **`swap`** *(uint64, OPTIONAL)* - sets limit of memory+Swap usage
 
-* **`kernel`** *(uint64, optional)* - sets hard limit for kernel memory
+* **`kernel`** *(uint64, OPTIONAL)* - sets hard limit for kernel memory
 
-* **`kernelTCP`** *(uint64, optional)* - sets hard limit in bytes for kernel TCP buffer memory
+* **`kernelTCP`** *(uint64, OPTIONAL)* - sets hard limit in bytes for kernel TCP buffer memory
 
-* **`swappiness`** *(uint64, optional)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
+* **`swappiness`** *(uint64, OPTIONAL)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
 
 ###### Example
 
@@ -307,19 +307,19 @@ For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
 
 The following parameters can be specified to setup the controller:
 
-* **`shares`** *(uint64, optional)* - specifies a relative share of CPU time available to the tasks in a cgroup
+* **`shares`** *(uint64, OPTIONAL)* - specifies a relative share of CPU time available to the tasks in a cgroup
 
-* **`quota`** *(uint64, optional)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below)
+* **`quota`** *(uint64, OPTIONAL)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below)
 
-* **`period`** *(uint64, optional)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only)
+* **`period`** *(uint64, OPTIONAL)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only)
 
-* **`realtimeRuntime`** *(uint64, optional)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources
+* **`realtimeRuntime`** *(uint64, OPTIONAL)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources
 
-* **`realtimePeriod`** *(uint64, optional)* - same as **`period`** but applies to realtime scheduler only
+* **`realtimePeriod`** *(uint64, OPTIONAL)* - same as **`period`** but applies to realtime scheduler only
 
-* **`cpus`** *(string, optional)* - list of CPUs the container will run in
+* **`cpus`** *(string, OPTIONAL)* - list of CPUs the container will run in
 
-* **`mems`** *(string, optional)* - list of Memory Nodes the container will run in
+* **`mems`** *(string, OPTIONAL)* - list of Memory Nodes the container will run in
 
 ###### Example
 
@@ -342,20 +342,20 @@ For more information, see [the kernel cgroups documentation about blkio][cgroup-
 
 The following parameters can be specified to setup the controller:
 
-* **`blkioWeight`** *(uint16, optional)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000.
+* **`blkioWeight`** *(uint16, OPTIONAL)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000.
 
-* **`blkioLeafWeight`** *(uint16, optional)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000.
+* **`blkioLeafWeight`** *(uint16, OPTIONAL)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000.
 
-* **`blkioWeightDevice`** *(array, optional)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
-    * **`major, minor`** *(int64, required)* - major, minor numbers for device. More info in `man mknod`.
-    * **`weight`** *(uint16, optional)* - bandwidth rate for the device, range is from 10 to 1000
-    * **`leafWeight`** *(uint16, optional)* - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
+* **`blkioWeightDevice`** *(array, OPTIONAL)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
+    * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in `man mknod`.
+    * **`weight`** *(uint16, OPTIONAL)* - bandwidth rate for the device, range is from 10 to 1000
+    * **`leafWeight`** *(uint16, OPTIONAL)* - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
 
     You must specify at least one of `weight` or `leafWeight` in a given entry, and can specify both.
 
-* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array, optional)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device:
-    * **`major, minor`** *(int64, required)* - major, minor numbers for device. More info in `man mknod`.
-    * **`rate`** *(uint64, required)* - IO rate limit for the device
+* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array, OPTIONAL)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device:
+    * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in `man mknod`.
+    * **`rate`** *(uint64, REQUIRED)* - IO rate limit for the device
 
 ###### Example
 
@@ -401,9 +401,9 @@ For more information, see the [kernel cgroups documentation about HugeTLB][cgrou
 
 `hugepageLimits` is an array of entries, each having the following structure:
 
-* **`pageSize`** *(string, required)* - hugepage size
+* **`pageSize`** *(string, REQUIRED)* - hugepage size
 
-* **`limit`** *(uint64, required)* - limit in bytes of *hugepagesize* HugeTLB usage
+* **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage
 
 ###### Example
 
@@ -423,12 +423,12 @@ For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and
 
 The following parameters can be specified to setup these cgroup controllers:
 
-* **`classID`** *(uint32, optional)* - is the network class identifier the cgroup's network packets will be tagged with
+* **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with
 
-* **`priorities`** *(array, optional)* - specifies a list of objects of the priorities assigned to traffic originating from
+* **`priorities`** *(array, OPTIONAL)* - specifies a list of objects of the priorities assigned to traffic originating from
 processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority:
-    * **`name`** *(string, required)* - interface name
-    * **`priority`** *(uint32, required)* - priority applied to the interface
+    * **`name`** *(string, REQUIRED)* - interface name
+    * **`priority`** *(uint32, REQUIRED)* - priority applied to the interface
 
 ###### Example
 
@@ -455,7 +455,7 @@ For more information, see [the pids cgroup man page][cgroup-v1-pids].
 
 The following parameters can be specified to setup the controller:
 
-* **`limit`** *(int64, required)* - specifies the maximum number of tasks in the cgroup
+* **`limit`** *(int64, REQUIRED)* - specifies the maximum number of tasks in the cgroup
 
 ###### Example
 

config-solaris.md

@@ -5,7 +5,7 @@ Solaris application containers can be configured using the following properties,
 ## milestone
 The SMF(Service Management Facility) FMRI which should go to "online" state before we start the desired process within the container.
 
-**`milestone`** *(string, optional)*
+**`milestone`** *(string, OPTIONAL)*
 
 ### Example
 ```json
@@ -16,7 +16,7 @@ The SMF(Service Management Facility) FMRI which should go to "online" state befo
 The maximum set of privileges any process in this container can obtain.
 The property should consist of a comma-separated privilege set specification as described in priv_str_to_set(3C) man page for the respective release of Solaris.
 
-**`limitpriv`** *(string, optional)*
+**`limitpriv`** *(string, OPTIONAL)*
 
 ### Example
 ```json
@@ -28,7 +28,7 @@ The maximum amount of shared memory allowed for this application container.
 A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte).
 Mapped to max-shm-memory in zonecfg(1M) man page.
 
-**`maxShmMemory`** *(string, optional)*
+**`maxShmMemory`** *(string, OPTIONAL)*
 
 ### Example
 ```json
@@ -42,7 +42,7 @@ An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75%
 When projects within a capped container have their own caps, the minimum value takes precedence.
 cappedCPU is mapped to capped-cpu in zonecfg(1M) man page.
 
-* **`ncpus`** *(string, optional)*
+* **`ncpus`** *(string, OPTIONAL)*
 
 ### Example
 ```json
@@ -56,8 +56,8 @@ The physical and swap caps on the memory that can be used by this application co
 A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte).
 cappedMemory is mapped to capped-memory in zonecfg(1M) man page.
 
-* **`physical`** *(string, optional)*
-* **`swap`** *(string, optional)*
+* **`physical`** *(string, OPTIONAL)*
+* **`swap`** *(string, OPTIONAL)*
 
 ### Example
 ```json
@@ -80,22 +80,22 @@ The VNIC is deleted when the container is torn down.
 The following properties can be used to setup automatic networks.
 For additional information on properties check zonecfg(1M) man page for the respective release of Solaris.
 
-* **`linkname`** *(string, optional)* Specify a name for the automatically created VNIC datalink.
-* **`lowerLink`** *(string, optional)* Specify the link over which the VNIC will be created.
+* **`linkname`** *(string, OPTIONAL)* Specify a name for the automatically created VNIC datalink.
+* **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created.
 Mapped to lower-link in the zonecfg(1M) man page.
-* **`allowedAddress`** *(string, optional)* The set of IP addresses that the container can use might be constrained by specifying the allowedAddress property.
+* **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the allowedAddress property.
 If allowedAddress has not been specified, then they can use any IP address on the associated physical interface for the network resource.
 Otherwise, when allowedAddress is specified, the container cannot use IP addresses that are not in the allowedAddress list for the physical address.
 Mapped to allowed-address in the zonecfg(1M) man page.
-* **`configureAllowedAddress`** *(string, optional)* If configureAllowedAddress is set to true, the addresses specified by allowedAddress are automatically configured on the interface each time the container starts.
+* **`configureAllowedAddress`** *(string, OPTIONAL)* If configureAllowedAddress is set to true, the addresses specified by allowedAddress are automatically configured on the interface each time the container starts.
 When it is set to false, the allowedAddress will not be configured on container start.
 Mapped to configure-allowed-address in the zonecfg(1M) man page.
-* **`defrouter`** *(string, optional)* The value for the optional default router.
-* **`macAddress`** *(string, optional)* Set the VNIC's MAC addresses based on the specified value or keyword.
+* **`defrouter`** *(string, OPTIONAL)* The value for the OPTIONAL default router.
+* **`macAddress`** *(string, OPTIONAL)* Set the VNIC's MAC addresses based on the specified value or keyword.
 If not a keyword, it is interpreted as a unicast MAC address.
 For a list of the supported keywords please refer to the zonecfg(1M) man page of the respective Solaris release.
 Mapped to mac-address in the zonecfg(1M) man page.
-* **`linkProtection`** *(string, optional)* Enables one or more types of link protection using comma-separated values.
+* **`linkProtection`** *(string, OPTIONAL)* Enables one or more types of link protection using comma-separated values.
 See the protection property in dladm(8) for supported values in respective release of Solaris.
 Mapped to link-protection in the zonecfg(1M) man page.