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 
27 #include <mesos/csi/types.hpp>
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 
44 namespace mesos {
45 namespace csi {
46 
47 struct VolumeInfo
48 {
50  std::string id;
51  google::protobuf::Map<std::string, std::string> context;
52 };
53 
54 
55 // Manages the volumes of a CSI plugin instance.
57 {
58 public:
60  const std::string& rootDir,
61  const CSIPluginInfo& info,
62  const hashset<Service>& services,
63  const std::string& apiVersion,
64  const process::grpc::client::Runtime& runtime,
65  ServiceManager* serviceManager,
66  Metrics* metrics);
67 
68  virtual ~VolumeManager() = default;
69 
70  virtual process::Future<Nothing> recover() = 0;
71 
72  // Lists all volumes, which may include untracked ones. Returns an empty list
73  // if `LIST_VOLUMES` controller capability is not supported.
74  virtual process::Future<std::vector<VolumeInfo>> listVolumes() = 0;
75 
76  // Returns the capacity that can be used to provision volumes for the
77  // given capability and parameters. Returns zero bytes if `GET_CAPACITY`
78  // controller capability is not supported.
79  virtual process::Future<Bytes> getCapacity(
80  const types::VolumeCapability& capability,
81  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
82 
83  // The following methods are used to manage volume lifecycles. The lifecycle
84  // of a volume is shown as follows, where unboxed states are transient states
85  // that might be skipped depending on the plugin's capabilities.
86  //
87  // +------------+
88  // | CREATED |
89  // +---+----^---+
90  // CONTROLLER_PUBLISH | | CONTROLLER_UNPUBLISH
91  // +---v----+---+
92  // | NODE_READY |
93  // +---+----^---+
94  // NODE_STAGE | | NODE_UNSTAGE
95  // +---v----+---+
96  // | VOL_READY |
97  // +---+----^---+
98  // NODE_PUBLISH | | NODE_UNPUBLISH
99  // +---v----+---+
100  // | PUBLISHED |
101  // +------------+
102 
103  // Provisions and tracks a new volume in `CREATED` state.
104  virtual process::Future<VolumeInfo> createVolume(
105  const std::string& name,
106  const Bytes& capacity,
107  const types::VolumeCapability& capability,
108  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
109 
110  // Validates a volume against the given capability and parameters. Once
111  // validated, tracks the volume in `CREATED` state if it is previously
112  // untracked then returns None. Otherwise returns the validation error.
114  const VolumeInfo& volumeInfo,
115  const types::VolumeCapability& capability,
116  const google::protobuf::Map<std::string, std::string>& parameters) = 0;
117 
118  // Deprovisions a volume and returns true if `CREATE_DELETE_VOLUME` controller
119  // capability is supported. Otherwise, transitions the volume to `CREATED`
120  // state and untracks it if it is previously tracked then returns false.
121  virtual process::Future<bool> deleteVolume(const std::string& volumeId) = 0;
122 
123  // Transitions a tracked volume to `NODE_READY` state from any state above.
124  virtual process::Future<Nothing> attachVolume(
125  const std::string& volumeId) = 0;
126 
127  // Transitions a tracked volume to `CREATED` state from any state below.
128  virtual process::Future<Nothing> detachVolume(
129  const std::string& volumeId) = 0;
130 
131  // Transitions a tracked volume to `PUBLISHED` state from any state above.
132  virtual process::Future<Nothing> publishVolume(
133  const std::string& volumeId) = 0;
134 
135  // Transitions a tracked volume to `NODE_READY` state from any state below.
136  virtual process::Future<Nothing> unpublishVolume(
137  const std::string& volumeId) = 0;
138 };
139 
140 } // namespace csi {
141 } // namespace mesos {
142 
143 #endif // __CSI_VOLUME_MANAGER_HPP__
Definition: volume_manager.hpp:56
Protocol< RecoverRequest, RecoverResponse > recover
Definition: check.hpp:33
Definition: volume_manager.hpp:47
google::protobuf::Map< std::string, std::string > context
Definition: volume_manager.hpp:51
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
std::string id
Definition: volume_manager.hpp:50
Bytes capacity
Definition: volume_manager.hpp:49
Try< Nothing > create(const std::string &hierarchy, const std::string &cgroup, bool recursive=false)
Definition: bytes.hpp:30
Definition: service_manager.hpp:51
PID< MetricsProcess > metrics
constexpr const char * name
Definition: shell.hpp:43