Apache Mesos
volume_manager.hpp
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 
17 #ifndef __CSI_VOLUME_MANAGER_HPP__
18 #define __CSI_VOLUME_MANAGER_HPP__
19 
20 #include <string>
21 #include <vector>
22 
23 #include <google/protobuf/map.h>
24 
25 #include <mesos/mesos.hpp>
26 
28 
29 #include <process/future.hpp>
30 #include <process/grpc.hpp>
31 #include <process/http.hpp>
32 #include <process/owned.hpp>
33 
34 #include <stout/bytes.hpp>
35 #include <stout/error.hpp>
36 #include <stout/hashset.hpp>
37 #include <stout/nothing.hpp>
38 #include <stout/option.hpp>
39 #include <stout/try.hpp>
40 
41 #include "csi/metrics.hpp"
42 #include "csi/service_manager.hpp"
43 #include "csi/state.hpp"
44 
45 namespace mesos {
46 namespace csi {
47 
48 struct VolumeInfo
49 {
51  std::string id;
52  google::protobuf::Map<std::string, std::string> context;
53 };
54 
55 
56 // Manages the volumes of a CSI plugin instance.
58 {
59 public:
61  const std::string& rootDir,
62  const CSIPluginInfo& info,
63  const hashset<Service>& services,
64  const std::string& apiVersion,
65  const process::grpc::client::Runtime& runtime,
66  ServiceManager* serviceManager,
68  SecretResolver* secretResolver = nullptr);
69 
70  virtual ~VolumeManager() = default;
71 
72  virtual process::Future<Nothing> recover() = 0;
73 
74  // Lists all volumes, which may include untracked ones. Returns an empty list
75  // if `LIST_VOLUMES` controller capability is not supported.
76  virtual process::Future<std::vector<VolumeInfo>> listVolumes() = 0;
77 
78  // Returns the capacity that can be used to provision volumes for the
79  // given capability and parameters. Returns zero bytes if `GET_CAPACITY`
80  // controller capability is not supported.
81  virtual process::Future<Bytes> getCapacity(
82  const Volume::Source::CSIVolume::VolumeCapability& capability,
83  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
84 
85  // The following methods are used to manage volume lifecycles. The lifecycle
86  // of a volume is shown as follows, where unboxed states are transient states
87  // that might be skipped depending on the plugin's capabilities.
88  //
89  // +------------+
90  // | CREATED |
91  // +---+----^---+
92  // CONTROLLER_PUBLISH | | CONTROLLER_UNPUBLISH
93  // +---v----+---+
94  // | NODE_READY |
95  // +---+----^---+
96  // NODE_STAGE | | NODE_UNSTAGE
97  // +---v----+---+
98  // | VOL_READY |
99  // +---+----^---+
100  // NODE_PUBLISH | | NODE_UNPUBLISH
101  // +---v----+---+
102  // | PUBLISHED |
103  // +------------+
104 
105  // Provisions and tracks a new volume in `CREATED` state.
106  virtual process::Future<VolumeInfo> createVolume(
107  const std::string& name,
108  const Bytes& capacity,
109  const Volume::Source::CSIVolume::VolumeCapability& capability,
110  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
111 
112  // Validates a volume against the given capability and parameters. Once
113  // validated, tracks the volume in `CREATED` state if it is previously
114  // untracked then returns None. Otherwise returns the validation error.
116  const VolumeInfo& volumeInfo,
117  const Volume::Source::CSIVolume::VolumeCapability& capability,
118  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
119 
120  // Deprovisions a volume and returns true if `CREATE_DELETE_VOLUME` controller
121  // capability is supported. Otherwise, transitions the volume to `CREATED`
122  // state and untracks it if it is previously tracked then returns false.
123  virtual process::Future<bool> deleteVolume(const std::string& volumeId) = 0;
124 
125  // Transitions a tracked volume to `NODE_READY` state from any state above.
126  virtual process::Future<Nothing> attachVolume(
127  const std::string& volumeId) = 0;
128 
129  // Transitions a tracked volume to `CREATED` state from any state below.
130  virtual process::Future<Nothing> detachVolume(
131  const std::string& volumeId) = 0;
132 
133  // Transitions a volume to `PUBLISHED` state. This method may be called on
134  // tracked or untracked volumes:
135  // * If `volumeState` is NONE, then `volumeId` must correspond to a tracked
136  // volume, and this method will transition the volume to `PUBLISHED` from
137  // any state above.
138  // * If `volumeState` is SOME, then `volumeId` must correspond to an untracked
139  // volume, and thus the ID should be unknown to the volume manager. The
140  // volume will be tracked by the manager and will become useable on the
141  // agent if the publish attempt succeeds.
142  virtual process::Future<Nothing> publishVolume(
143  const std::string& volumeId,
144  const Option<state::VolumeState>& volumeState = None()) = 0;
145 
146  // Transitions a tracked volume to `NODE_READY` state from any other state.
147  // If the volume was untracked when it was published (a pre-provisioned
148  // volume), then the volume's metadata is removed from the volume manager.
149  virtual process::Future<Nothing> unpublishVolume(
150  const std::string& volumeId) = 0;
151 };
152 
153 } // namespace csi {
154 } // namespace mesos {
155 
156 #endif // __CSI_VOLUME_MANAGER_HPP__
Definition: volume_manager.hpp:57
Protocol< RecoverRequest, RecoverResponse > recover
Definition: option.hpp:29
Definition: check.hpp:33
Definition: volume_manager.hpp:48
google::protobuf::Map< std::string, std::string > context
Definition: volume_manager.hpp:52
Definition: metrics.hpp:28
Definition: v0.hpp:49
Option< Error > validateVolume(const Volume &volume)
A copyable interface to manage an internal runtime process for asynchronous gRPC calls.
Definition: grpc.hpp:157
Definition: agent.hpp:25
Definition: none.hpp:27
std::string id
Definition: volume_manager.hpp:51
Bytes capacity
Definition: volume_manager.hpp:50
Try< Nothing > create(const std::string &hierarchy, const std::string &cgroup, bool recursive=false)
Definition: resolver.hpp:34
Definition: bytes.hpp:30
Definition: service_manager.hpp:51
PID< MetricsProcess > metrics
constexpr const char * name
Definition: shell.hpp:41