podman_rest_client/v5/models/
topology_requirement.rs

1use serde::{Deserialize, Serialize};
2#[derive(Default, Debug, Serialize, Deserialize)]
3/// TopologyRequirement expresses the user's requirements for a volume's
4/// accessible topology.
5pub struct TopologyRequirement {
6    /// Preferred is a list of Topologies that the volume should attempt to be
7    /// provisioned in.
8    ///
9    /// Taken from the CSI spec:
10    ///
11    /// Specifies the list of topologies the CO would prefer the volume to
12    /// be provisioned in.
13    ///
14    /// This field is OPTIONAL. If TopologyRequirement is specified either
15    /// requisite or preferred or both MUST be specified.
16    ///
17    /// An SP MUST attempt to make the provisioned volume available using
18    /// the preferred topologies in order from first to last.
19    ///
20    /// If requisite is specified, all topologies in preferred list MUST
21    /// also be present in the list of requisite topologies.
22    ///
23    /// If the SP is unable to make the provisioned volume available
24    /// from any of the preferred topologies, the SP MAY choose a topology
25    /// from the list of requisite topologies.
26    /// If the list of requisite topologies is not specified, then the SP
27    /// MAY choose from the list of all possible topologies.
28    /// If the list of requisite topologies is specified and the SP is
29    /// unable to make the provisioned volume available from any of the
30    /// requisite topologies it MUST fail the CreateVolume call.
31    ///
32    /// Example 1:
33    /// Given a volume should be accessible from a single zone, and
34    /// requisite =
35    /// {"region": "R1", "zone": "Z2"},
36    /// {"region": "R1", "zone": "Z3"}
37    /// preferred =
38    /// {"region": "R1", "zone": "Z3"}
39    /// then the SP SHOULD first attempt to make the provisioned volume
40    /// available from "zone" "Z3" in the "region" "R1" and fall back to
41    /// "zone" "Z2" in the "region" "R1" if that is not possible.
42    ///
43    /// Example 2:
44    /// Given a volume should be accessible from a single zone, and
45    /// requisite =
46    /// {"region": "R1", "zone": "Z2"},
47    /// {"region": "R1", "zone": "Z3"},
48    /// {"region": "R1", "zone": "Z4"},
49    /// {"region": "R1", "zone": "Z5"}
50    /// preferred =
51    /// {"region": "R1", "zone": "Z4"},
52    /// {"region": "R1", "zone": "Z2"}
53    /// then the SP SHOULD first attempt to make the provisioned volume
54    /// accessible from "zone" "Z4" in the "region" "R1" and fall back to
55    /// "zone" "Z2" in the "region" "R1" if that is not possible. If that
56    /// is not possible, the SP may choose between either the "zone"
57    /// "Z3" or "Z5" in the "region" "R1".
58    ///
59    /// Example 3:
60    /// Given a volume should be accessible from TWO zones (because an
61    /// opaque parameter in CreateVolumeRequest, for example, specifies
62    /// the volume is accessible from two zones, aka synchronously
63    /// replicated), and
64    /// requisite =
65    /// {"region": "R1", "zone": "Z2"},
66    /// {"region": "R1", "zone": "Z3"},
67    /// {"region": "R1", "zone": "Z4"},
68    /// {"region": "R1", "zone": "Z5"}
69    /// preferred =
70    /// {"region": "R1", "zone": "Z5"},
71    /// {"region": "R1", "zone": "Z3"}
72    /// then the SP SHOULD first attempt to make the provisioned volume
73    /// accessible from the combination of the two "zones" "Z5" and "Z3" in
74    /// the "region" "R1". If that's not possible, it should fall back to
75    /// a combination of "Z5" and other possibilities from the list of
76    /// requisite. If that's not possible, it should fall back  to a
77    /// combination of "Z3" and other possibilities from the list of
78    /// requisite. If that's not possible, it should fall back  to a
79    /// combination of other possibilities from the list of requisite.
80    #[serde(rename = "Preferred")]
81    pub preferred: Option<Vec<crate::v5::models::Topology>>,
82    /// Requisite specifies a list of Topologies, at least one of which the
83    /// volume must be accessible from.
84    ///
85    /// Taken verbatim from the CSI Spec:
86    ///
87    /// Specifies the list of topologies the provisioned volume MUST be
88    /// accessible from.
89    /// This field is OPTIONAL. If TopologyRequirement is specified either
90    /// requisite or preferred or both MUST be specified.
91    ///
92    /// If requisite is specified, the provisioned volume MUST be
93    /// accessible from at least one of the requisite topologies.
94    ///
95    /// Given
96    /// x = number of topologies provisioned volume is accessible from
97    /// n = number of requisite topologies
98    /// The CO MUST ensure n >= 1. The SP MUST ensure x >= 1
99    /// If x==n, then the SP MUST make the provisioned volume available to
100    /// all topologies from the list of requisite topologies. If it is
101    /// unable to do so, the SP MUST fail the CreateVolume call.
102    /// For example, if a volume should be accessible from a single zone,
103    /// and requisite =
104    /// {"region": "R1", "zone": "Z2"}
105    /// then the provisioned volume MUST be accessible from the "region"
106    /// "R1" and the "zone" "Z2".
107    /// Similarly, if a volume should be accessible from two zones, and
108    /// requisite =
109    /// {"region": "R1", "zone": "Z2"},
110    /// {"region": "R1", "zone": "Z3"}
111    /// then the provisioned volume MUST be accessible from the "region"
112    /// "R1" and both "zone" "Z2" and "zone" "Z3".
113    ///
114    /// If x<n, then the SP SHALL choose x unique topologies from the list
115    /// of requisite topologies. If it is unable to do so, the SP MUST fail
116    /// the CreateVolume call.
117    /// For example, if a volume should be accessible from a single zone,
118    /// and requisite =
119    /// {"region": "R1", "zone": "Z2"},
120    /// {"region": "R1", "zone": "Z3"}
121    /// then the SP may choose to make the provisioned volume available in
122    /// either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1".
123    /// Similarly, if a volume should be accessible from two zones, and
124    /// requisite =
125    /// {"region": "R1", "zone": "Z2"},
126    /// {"region": "R1", "zone": "Z3"},
127    /// {"region": "R1", "zone": "Z4"}
128    /// then the provisioned volume MUST be accessible from any combination
129    /// of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and
130    /// "R1/Z4", or "R1/Z3" and "R1/Z4".
131    ///
132    /// If x>n, then the SP MUST make the provisioned volume available from
133    /// all topologies from the list of requisite topologies and MAY choose
134    /// the remaining x-n unique topologies from the list of all possible
135    /// topologies. If it is unable to do so, the SP MUST fail the
136    /// CreateVolume call.
137    /// For example, if a volume should be accessible from two zones, and
138    /// requisite =
139    /// {"region": "R1", "zone": "Z2"}
140    /// then the provisioned volume MUST be accessible from the "region"
141    /// "R1" and the "zone" "Z2" and the SP may select the second zone
142    /// independently, e.g. "R1/Z4".
143    #[serde(rename = "Requisite")]
144    pub requisite: Option<Vec<crate::v5::models::Topology>>,
145}
podman_rest_client/v5/models/topology_requirement.rs

podman_rest_client/v5/models/
topology_requirement.rs
