--- title: "Updates a single volume with given spec." method: PUT path: "/osd-volumes/{id}" tags: ["volume", "update"] --- # Updates a single volume with given spec. `PUT /osd-volumes/{id}` ## Query parameters - `id` string, required ## Request body - VolumeSetRequest - `action` VolumeStateAction - `attach` integer - `device_path` string — DevicePath Path returned in attach - `mount` integer - `mount_path` string — MountPath Path where the device is mounted - `locator` VolumeLocator — VolumeLocator is a structure that is attached to a volume and is used to carry opaque metadata. - `name` string — User friendly identifier - `volume_labels` object — A set of name-value pairs that acts as search filters - `options` object — additional options required for the Set operation. - `spec` VolumeSpec - `aggregation_level` integer — Aggregatiokn level Specifies the number of parts the volume can be aggregated from. - `block_size` integer — BlockSize for the filesystem. - `cascaded` boolean — Cascaded is true if this volume can be populated on any node from an external source. - `compressed` boolean — Compressed is true if this volume is to be compressed. - `cos` integer - `dedupe` boolean — Dedupe specifies if the volume data is to be de-duplicated. - `encrypted` boolean — Encrypted is true if this volume will be cryptographically secured. - `ephemeral` boolean — Ephemeral storage - `format` integer - `group` Group — Group represents VolumeGroup / namespace All volumes in the same group share this object. - `id` string — Id common identifier across volumes that have the same group. - `group_enforced` boolean — GroupEnforced is true if consistency group creation is enforced. - `ha_level` integer — HaLevel specifies the number of copies of data. - `io_profile` integer - `journal` boolean — Journal is true if data for the volume goes into the journal. - `nfs` boolean — Nfs is true if this volume can be accessed via nfs. - `passphrase` string — Passphrase for an encrypted volume - `replica_set` ReplicaSet — ReplicaSet set of machine IDs (nodes) to which part of this volume is erasure coded - for clustered storage arrays - `nodes` string[] - `scale` integer — Scale allows autocreation of volumes. - `shared` boolean — Shared is true if this volume can be remotely accessed. - `size` integer — Size specifies the thin provisioned volume size. - `snapshot_interval` integer — SnapshotInterval in minutes, set to 0 to disable snapshots - `snapshot_schedule` string — SnapshotSchedule a well known string that specifies when snapshots should be taken. - `sticky` boolean — Sticky volumes cannot be deleted until the flag is removed. - `volume_labels` object — VolumeLabels configuration labels ## Response `200` volume set response - VolumeSetResponse - `volume` Volume — Volume represents an abstract storage volume. - `attach_info` object — AttachInfo is a list of name value mappings that provides attach information. - `attach_path` string[] — AttachPath is the mounted path in the host namespace. - `attached_on` string — AttachedOn is the node instance identifier for clustered systems. - `attached_state` integer - `ctime` Timestamp — # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required, though only UTC (as indicated by "Z") is presently supported. For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()) to obtain a formatter capable of generating timestamps in this format. - `nanos` integer — Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. - `seconds` integer — Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. - `device_path` string — DevicePath is the device exported by block device implementations. - `error` string — Error is the Last recorded error. - `format` integer - `group` Group — Group represents VolumeGroup / namespace All volumes in the same group share this object. - `id` string — Id common identifier across volumes that have the same group. - `id` string — Self referential volume ID. - `last_scan` Timestamp — # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required, though only UTC (as indicated by "Z") is presently supported. For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()) to obtain a formatter capable of generating timestamps in this format. - `nanos` integer — Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. - `seconds` integer — Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. - `locator` VolumeLocator — VolumeLocator is a structure that is attached to a volume and is used to carry opaque metadata. - `name` string — User friendly identifier - `volume_labels` object — A set of name-value pairs that acts as search filters - `readonly` boolean — Readonly is true if this volume is to be mounted with readonly access. - `replica_sets` ReplicaSet[] — ReplicatSets storage for this volumefor clustered storage arrays. - `nodes` string[] - `runtime_state` RuntimeStateMap[] — RuntimeState is a lst of name value mapping of driver specific runtime information. - `runtime_state` object - `secure_device_path` string — SecureDevicePath is the device path for an encrypted volume. - `source` Source — Source is a structure that can be given to a volume to seed the volume with data. - `parent` string — A volume id, if specified will create a clone of the parent. - `seed` string — Seed will seed the volume from the specified URI Any additional config for the source comes from the labels in the spec - `spec` VolumeSpec - `aggregation_level` integer — Aggregatiokn level Specifies the number of parts the volume can be aggregated from. - `block_size` integer — BlockSize for the filesystem. - `cascaded` boolean — Cascaded is true if this volume can be populated on any node from an external source. - `compressed` boolean — Compressed is true if this volume is to be compressed. - `cos` integer - `dedupe` boolean — Dedupe specifies if the volume data is to be de-duplicated. - `encrypted` boolean — Encrypted is true if this volume will be cryptographically secured. - `ephemeral` boolean — Ephemeral storage - `format` integer - `group` Group — Group represents VolumeGroup / namespace All volumes in the same group share this object. - `id` string — Id common identifier across volumes that have the same group. - `group_enforced` boolean — GroupEnforced is true if consistency group creation is enforced. - `ha_level` integer — HaLevel specifies the number of copies of data. - `io_profile` integer - `journal` boolean — Journal is true if data for the volume goes into the journal. - `nfs` boolean — Nfs is true if this volume can be accessed via nfs. - `passphrase` string — Passphrase for an encrypted volume - `replica_set` ReplicaSet — ReplicaSet set of machine IDs (nodes) to which part of this volume is erasure coded - for clustered storage arrays - `nodes` string[] - `scale` integer — Scale allows autocreation of volumes. - `shared` boolean — Shared is true if this volume can be remotely accessed. - `size` integer — Size specifies the thin provisioned volume size. - `snapshot_interval` integer — SnapshotInterval in minutes, set to 0 to disable snapshots - `snapshot_schedule` string — SnapshotSchedule a well known string that specifies when snapshots should be taken. - `sticky` boolean — Sticky volumes cannot be deleted until the flag is removed. - `volume_labels` object — VolumeLabels configuration labels - `state` integer - `status` integer - `usage` integer — Usage is bytes consumed by vtheis volume. - `volume_response` VolumeResponse - `error` string ## Other responses - `default` — unexpected error ## Changes - **2017-12-05** `d79082f863d1` — 1 breaking, 1 warning, 1 info - added the new required `query` request parameter `id` - deleted the `path` request parameter `id` - api tag `update` added [Change history](https://skmtc.dev/libopenstorage/apis/osd-api/changes/osd-volumes/:id/put.md) --- [API](https://skmtc.dev/libopenstorage/apis/osd-api.md) · [All operations](https://skmtc.dev/libopenstorage/apis/osd-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/libopenstorage/osd-api/revisions/d79082f863d1/schema)