Skip to content

Commit cd0f4c1

Browse files
carlbraganzacarlbraganza
committed
GRPC spec
1 parent a42d41e commit cd0f4c1

File tree

1 file changed

+158
-0
lines changed
  • keps/sig-storage/3314-csi-changed-block-tracking

1 file changed

+158
-0
lines changed

‎keps/sig-storage/3314-csi-changed-block-tracking/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -584,6 +584,164 @@ message GetDeltaResponse {
584584
}
585585
```
586586

587+
#### Metadata Format
588+
Block volume data ranges are specified by a sequence of `(ByteOffset, Length)` tuples,
589+
with the tuples in ascending order of `ByteOffset` and no overlap between adjacent tuples.
590+
There are two prevalent styles, *extent-based* or *block-based*,
591+
which describe if the `Length` field of the tuples in a sequence can
592+
**vary** or are **fixed** across all the tuples in the sequence.
593+
The **SnapshotMetadata** service permits either style at the discretion of the plugin,
594+
and it is required that a client of this service be able to handle both styles.
595+
596+
The `BlockMetadataType` enumeration specifies the style used: `FIXED_LENGTH` or `VARIABLE_LENGTH`.
597+
When the *block-based* style (`FIXED_LENGTH`) is used it is up to the SP plugin to define the
598+
block size.
599+
600+
An individual tuple is identified by the `BlockMetadata` message, and the sequence is
601+
defined collectively across the tuple lists returned in the RPC
602+
[message stream](https://grpc.io/docs/what-is-grpc/core-concepts/#server-streaming-rpc).
603+
Note that the plugin must ensure that the style is not change mid-stream in any given RPC invocation.
604+
605+
#### GetAllocated RPC
606+
The `GetAllocated` RPC returns metadata on the ***allocated blocks*** of a snapshot -
607+
i.e. this identifies the data ranges that have valid data as they were the target of
608+
some previous write operation.
609+
Backup applications typically make an initial **full** backup of a volume followed
610+
by a series of **incremental** backups, and the size of the initial full backup can
611+
be reduced considerably if only the allocated blocks are saved.
612+
613+
The RPC's input arguments are specified by the `GetAllocatedRequest` message,
614+
and it returns a
615+
[stream](https://grpc.io/docs/what-is-grpc/core-concepts/#server-streaming-rpc)
616+
of `GetAllocatedResponse` messages.
617+
The fields of the `GetAllocatedRequest` message are defined as follows:
618+
- `session_token`<br>
619+
This is an opaque string that has identifies a snapshot session.
620+
It is obtained through a mechanism defined by the CO system.
621+
622+
- `volume_id`<br>
623+
The identifier of the volume in the nomenclature of the plugin.
624+
625+
- `snapshot`<br>
626+
The identifier of a snapshot of the specified volume, in the nomenclature of the plugin.
627+
628+
- `starting_offset`<br>
629+
This specifies the 0 based starting byte position in the volume snapshot from which the result should be computed.
630+
It is intended to be used to continue a previously interrupted call.
631+
The server may round down this offset to the nearest alignment boundary based on the `BlockMetadataType`
632+
it will use.
633+
634+
- `max_results`<br>
635+
This is an optional field. If non-zero it specifies the maximum length of the `block_metadata` list
636+
that the client wants to process in a given `GetAllocateResponse` element.
637+
The server will determine an appropriate value if 0, and is always free to send less than the requested
638+
maximum.
639+
640+
The fields of the `GetAllocatedResponse` message are defined as follows:
641+
- `block_metadata_type`<br>
642+
This specifies the metadata format as described in the [Metadata Format](#metadata-format) section above.
643+
644+
- `volume_size_bytes`<br>
645+
The size of the underlying volume, in bytes.
646+
647+
- `block_metadata`<br>
648+
This is a list of `BlockMetadata` tuples as described in the
649+
[Metadata Format](#metadata-format) section above.
650+
The caller may request a maximum length of this list in the `max_results` field
651+
of the `GetAllocatedRequest` message, otherwise the length is determined by the server.
652+
653+
Note that while the `block_metadata_type` and `volume_size_bytes` fields are
654+
repeated in each `GetAllocatedResponse` message by the nature of the syntax of the
655+
specification language, their values in a given RPC invocation must be constant.
656+
i.e. a plugin is not free to modify these value mid-stream.
657+
658+
##### GetAllocated Errors
659+
If the plugin is unable to complete the `GetAllocated` call successfully it
660+
must return a non-OK gRPC code in the gRPC status.
661+
662+
The following conditions are well defined:
663+
664+
| Condition | gRPC Code | Description | Recovery Behavior |
665+
|-----------|-----------|-------------|-------------------|
666+
| Missing or otherwise invalid argument | 3 INVALID_ARGUMENT | Indicates that a required argument field was not specified or an argument value is invalid | The caller should correct the error and resubmit the call. |
667+
| Invalid `volume_id` or `snapshot` | 5 NOT_FOUND | Indicates that the volume or snapshot specified were not found. | The caller should re-check that these objects exist. |
668+
| Invalid `starting_offset` | 11 OUT_OF_RANGE | The starting offset exceeds the volume size. | The caller should specify a `starting_offset` less than the volume's size. |
669+
| Invalid `session_token` | 16 UNAUTHENTICATED | The specified session token is invalid or has expired. | The caller should create a new snapshot session. |
670+
671+
#### GetDelta RPC
672+
The `GetDelta` RPC returns the metadata on the blocks that have changed between
673+
a pair of snapshots from the same volume.
674+
675+
The RPC's input arguments are specified by the `GetDeltaRequest` message,
676+
and it returns a
677+
[stream](https://grpc.io/docs/what-is-grpc/core-concepts/#server-streaming-rpc)
678+
of `GetDeltaResponse` messages.
679+
The fields of the `GetDeltaRequest` message are defined as follows:
680+
- `session_token`<br>
681+
This is an opaque string that has identifies a snapshot session.
682+
It is obtained through a mechanism defined by the CO system.
683+
684+
- `volume_id`<br>
685+
The identifier of the volume in the nomenclature of the plugin.
686+
687+
- `base_snapshot`<br>
688+
The identifier of a snapshot of the specified volume, in the nomenclature of the plugin.
689+
690+
- `target_snapshot`<br>
691+
The identifier of a second snapshot of the specified volume, in the nomenclature of the plugin.
692+
This snapshot should have been created after the `base_snapshot`, and the RPC will return the changes
693+
made since the `base_snapshot` was created.
694+
695+
- `starting_offset`<br>
696+
This specifies the 0 based starting byte position in the `target_snapshot` from which the result should be computed.
697+
It is intended to be used to continue a previously interrupted call.
698+
The server may round down this offset to the nearest alignment boundary based on the `BlockMetadataType`
699+
it will use.
700+
701+
- `max_results`<br>
702+
This is an optional field. If non-zero it specifies the maximum length of the `block_metadata` list
703+
that the client wants to process in a given `GetDeltaResponse` element.
704+
The server will determine an appropriate value if 0, and is always free to send less than the requested
705+
maximum.
706+
707+
The fields of the `GetDeltaResponse` message are defined as follows:
708+
- `block_metadata_type`<br>
709+
This specifies the metadata format as described in the [Metadata Format](#metadata-format) section above.
710+
711+
- `volume_size_bytes`<br>
712+
The size of the underlying volume, in bytes.
713+
714+
- `block_metadata`<br>
715+
This is a list of `BlockMetadata` tuples as described in the
716+
[Metadata Format](#metadata-format) section above.
717+
The caller may request a maximum length of this list in the `max_results` field
718+
of the `GetDeltaRequest` message, otherwise the length is determined by the server.
719+
720+
Note that while the `block_metadata_type` and `volume_size_bytes` fields are
721+
repeated in each `GetDeltaResponse` message by the nature of the syntax of the
722+
specification language, their values in a given RPC invocation must be constant.
723+
i.e. a plugin is not free to modify these value mid-stream.
724+
725+
##### GetDelta Errors
726+
If the plugin is unable to complete the `GetDelta` call successfully it
727+
must return a non-OK gRPC code in the gRPC status.
728+
729+
The following conditions are well defined:
730+
731+
| Condition | gRPC Code | Description | Recovery Behavior |
732+
|-----------|-----------|-------------|-------------------|
733+
| Missing or otherwise invalid argument | 3 INVALID_ARGUMENT | Indicates that a required argument field was not specified or an argument value is invalid | The caller should correct the error and resubmit the call. |
734+
| Invalid `volume_id`, `base_snapshot` or `target_snapshot` | 5 NOT_FOUND | Indicates that the volume or snapshots specified were not found. | The caller should re-check that these objects exist. |
735+
| Invalid `starting_offset` | 11 OUT_OF_RANGE | The starting offset exceeds the volume size. | The caller should specify a `starting_offset` less than the volume's size. |
736+
| Invalid `session_token` | 16 UNAUTHENTICATED | The specified session token is invalid or has expired. | The caller should create a new snapshot session. |
737+
738+
#### Capability Flags
739+
740+
The gRPC service is optional and its availability is indicated by ...
741+
> @TODO How should the availability of this service be advertised through CSI interfaces?
742+
> Is this mandatory?
743+
> It is pretty obviously sensed in K8s by looking for SnapshotSessionConfiguration objects.
744+
587745

588746
### Kubernetes Components
589747
The following Kubernetes components are involved at runtime:

0 commit comments

Comments
 (0)