control.proto 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554
  1. syntax = "proto3";
  2. package docker.swarmkit.v1;
  3. import "specs.proto";
  4. import "objects.proto";
  5. import "types.proto";
  6. import "gogoproto/gogo.proto";
  7. import "plugin/plugin.proto";
  8. // Control defines the RPC methods for controlling a cluster.
  9. service Control {
  10. rpc GetNode(GetNodeRequest) returns (GetNodeResponse) {
  11. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  12. };
  13. rpc ListNodes(ListNodesRequest) returns (ListNodesResponse) {
  14. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  15. };
  16. rpc UpdateNode(UpdateNodeRequest) returns (UpdateNodeResponse) {
  17. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  18. };
  19. rpc RemoveNode(RemoveNodeRequest) returns (RemoveNodeResponse) {
  20. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  21. };
  22. rpc GetTask(GetTaskRequest) returns (GetTaskResponse) {
  23. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  24. };
  25. rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
  26. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  27. };
  28. rpc RemoveTask(RemoveTaskRequest) returns (RemoveTaskResponse) {
  29. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  30. };
  31. rpc GetService(GetServiceRequest) returns (GetServiceResponse) {
  32. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  33. };
  34. rpc ListServices(ListServicesRequest) returns (ListServicesResponse) {
  35. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  36. };
  37. rpc CreateService(CreateServiceRequest) returns (CreateServiceResponse) {
  38. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  39. };
  40. rpc UpdateService(UpdateServiceRequest) returns (UpdateServiceResponse) {
  41. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  42. };
  43. rpc RemoveService(RemoveServiceRequest) returns (RemoveServiceResponse) {
  44. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  45. };
  46. rpc GetNetwork(GetNetworkRequest) returns (GetNetworkResponse) {
  47. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  48. };
  49. rpc ListNetworks(ListNetworksRequest) returns (ListNetworksResponse) {
  50. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  51. };
  52. rpc CreateNetwork(CreateNetworkRequest) returns (CreateNetworkResponse) {
  53. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  54. };
  55. rpc RemoveNetwork(RemoveNetworkRequest) returns (RemoveNetworkResponse) {
  56. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  57. };
  58. rpc GetCluster(GetClusterRequest) returns (GetClusterResponse) {
  59. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  60. };
  61. rpc ListClusters(ListClustersRequest) returns (ListClustersResponse) {
  62. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  63. };
  64. rpc UpdateCluster(UpdateClusterRequest) returns (UpdateClusterResponse) {
  65. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  66. };
  67. // --- secret APIs ---
  68. // GetSecret returns a `GetSecretResponse` with a `Secret` with the same
  69. // id as `GetSecretRequest.SecretID`
  70. // - Returns `NotFound` if the Secret with the given id is not found.
  71. // - Returns `InvalidArgument` if the `GetSecretRequest.SecretID` is empty.
  72. // - Returns an error if getting fails.
  73. rpc GetSecret(GetSecretRequest) returns (GetSecretResponse) {
  74. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  75. }
  76. // UpdateSecret returns a `UpdateSecretResponse` with a `Secret` with the same
  77. // id as `GetSecretRequest.SecretID`
  78. // - Returns `NotFound` if the Secret with the given id is not found.
  79. // - Returns `InvalidArgument` if the `GetSecretRequest.SecretID` is empty.
  80. // - Returns an error if updating fails.
  81. rpc UpdateSecret(UpdateSecretRequest) returns (UpdateSecretResponse) {
  82. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  83. };
  84. // ListSecrets returns a `ListSecretResponse` with a list of all non-internal `Secret`s being
  85. // managed, or all secrets matching any name in `ListSecretsRequest.Names`, any
  86. // name prefix in `ListSecretsRequest.NamePrefixes`, any id in
  87. // `ListSecretsRequest.SecretIDs`, or any id prefix in `ListSecretsRequest.IDPrefixes`.
  88. // - Returns an error if listing fails.
  89. rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse) {
  90. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  91. }
  92. // CreateSecret creates and return a `CreateSecretResponse` with a `Secret` based
  93. // on the provided `CreateSecretRequest.SecretSpec`.
  94. // - Returns `InvalidArgument` if the `CreateSecretRequest.SecretSpec` is malformed,
  95. // or if the secret data is too long or contains invalid characters.
  96. // - Returns an error if the creation fails.
  97. rpc CreateSecret(CreateSecretRequest) returns (CreateSecretResponse) {
  98. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  99. }
  100. // RemoveSecret removes the secret referenced by `RemoveSecretRequest.ID`.
  101. // - Returns `InvalidArgument` if `RemoveSecretRequest.ID` is empty.
  102. // - Returns `NotFound` if the a secret named `RemoveSecretRequest.ID` is not found.
  103. // - Returns an error if the deletion fails.
  104. rpc RemoveSecret(RemoveSecretRequest) returns (RemoveSecretResponse) {
  105. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  106. }
  107. // --- config APIs ---
  108. // GetConfig returns a `GetConfigResponse` with a `Config` with the same
  109. // id as `GetConfigRequest.ConfigID`
  110. // - Returns `NotFound` if the Config with the given id is not found.
  111. // - Returns `InvalidArgument` if the `GetConfigRequest.ConfigID` is empty.
  112. // - Returns an error if getting fails.
  113. rpc GetConfig(GetConfigRequest) returns (GetConfigResponse) {
  114. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  115. }
  116. // UpdateConfig returns a `UpdateConfigResponse` with a `Config` with the same
  117. // id as `GetConfigRequest.ConfigID`
  118. // - Returns `NotFound` if the Config with the given id is not found.
  119. // - Returns `InvalidArgument` if the `GetConfigRequest.ConfigID` is empty.
  120. // - Returns an error if updating fails.
  121. rpc UpdateConfig(UpdateConfigRequest) returns (UpdateConfigResponse) {
  122. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  123. };
  124. // ListConfigs returns a `ListConfigResponse` with a list of `Config`s being
  125. // managed, or all configs matching any name in `ListConfigsRequest.Names`, any
  126. // name prefix in `ListConfigsRequest.NamePrefixes`, any id in
  127. // `ListConfigsRequest.ConfigIDs`, or any id prefix in `ListConfigsRequest.IDPrefixes`.
  128. // - Returns an error if listing fails.
  129. rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) {
  130. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  131. }
  132. // CreateConfig creates and return a `CreateConfigResponse` with a `Config` based
  133. // on the provided `CreateConfigRequest.ConfigSpec`.
  134. // - Returns `InvalidArgument` if the `CreateConfigRequest.ConfigSpec` is malformed,
  135. // or if the config data is too long or contains invalid characters.
  136. // - Returns an error if the creation fails.
  137. rpc CreateConfig(CreateConfigRequest) returns (CreateConfigResponse) {
  138. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  139. }
  140. // RemoveConfig removes the config referenced by `RemoveConfigRequest.ID`.
  141. // - Returns `InvalidArgument` if `RemoveConfigRequest.ID` is empty.
  142. // - Returns `NotFound` if the a config named `RemoveConfigRequest.ID` is not found.
  143. // - Returns an error if the deletion fails.
  144. rpc RemoveConfig(RemoveConfigRequest) returns (RemoveConfigResponse) {
  145. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  146. }
  147. }
  148. message GetNodeRequest {
  149. string node_id = 1;
  150. }
  151. message GetNodeResponse {
  152. Node node = 1;
  153. }
  154. message ListNodesRequest {
  155. message Filters {
  156. repeated string names = 1;
  157. repeated string id_prefixes = 2;
  158. map<string, string> labels = 3;
  159. repeated NodeSpec.Membership memberships = 4 [packed=false];
  160. repeated NodeRole roles = 5 [packed=false];
  161. // NamePrefixes matches all objects with the given prefixes
  162. repeated string name_prefixes = 6;
  163. }
  164. Filters filters = 1;
  165. }
  166. message ListNodesResponse {
  167. repeated Node nodes = 1;
  168. }
  169. // UpdateNodeRequest requests an update to the specified node. This may be used
  170. // to request a new availability for a node, such as PAUSE. Invalid updates
  171. // will be denied and cause an error.
  172. message UpdateNodeRequest {
  173. string node_id = 1;
  174. Version node_version = 2;
  175. NodeSpec spec = 3;
  176. }
  177. message UpdateNodeResponse {
  178. Node node = 1;
  179. }
  180. // RemoveNodeRequest requests to delete the specified node from store.
  181. message RemoveNodeRequest {
  182. string node_id = 1;
  183. bool force = 2;
  184. }
  185. message RemoveNodeResponse {
  186. }
  187. message GetTaskRequest {
  188. string task_id = 1;
  189. }
  190. message GetTaskResponse {
  191. Task task = 1;
  192. }
  193. message RemoveTaskRequest {
  194. string task_id = 1;
  195. }
  196. message RemoveTaskResponse {
  197. }
  198. message ListTasksRequest {
  199. message Filters {
  200. repeated string names = 1;
  201. repeated string id_prefixes = 2;
  202. map<string, string> labels = 3;
  203. repeated string service_ids = 4;
  204. repeated string node_ids = 5;
  205. repeated docker.swarmkit.v1.TaskState desired_states = 6 [packed=false];
  206. // NamePrefixes matches all objects with the given prefixes
  207. repeated string name_prefixes = 7;
  208. repeated string runtimes = 9;
  209. // UpToDate matches tasks that are consistent with the current
  210. // service definition.
  211. // Note: this is intended for internal status reporting rather
  212. // than being exposed to users. It may be removed in the future.
  213. bool up_to_date = 8;
  214. }
  215. Filters filters = 1;
  216. }
  217. message ListTasksResponse {
  218. repeated Task tasks = 1;
  219. }
  220. message CreateServiceRequest {
  221. ServiceSpec spec = 1;
  222. }
  223. message CreateServiceResponse {
  224. Service service = 1;
  225. }
  226. message GetServiceRequest {
  227. string service_id = 1;
  228. bool insert_defaults = 2;
  229. }
  230. message GetServiceResponse {
  231. Service service = 1;
  232. }
  233. message UpdateServiceRequest {
  234. string service_id = 1;
  235. Version service_version = 2;
  236. ServiceSpec spec = 3;
  237. enum Rollback {
  238. // This is not a rollback. The spec field of the request will
  239. // be honored.
  240. NONE = 0;
  241. // Roll back the service - get spec from the service's
  242. // previous_spec.
  243. PREVIOUS = 1;
  244. }
  245. // Rollback may be set to PREVIOUS to request a rollback (the service's
  246. // spec will be set to the value of its previous_spec field). In this
  247. // case, the spec field of this request is ignored.
  248. Rollback rollback = 4;
  249. }
  250. message UpdateServiceResponse {
  251. Service service = 1;
  252. }
  253. message RemoveServiceRequest {
  254. string service_id = 1;
  255. }
  256. message RemoveServiceResponse {
  257. }
  258. message ListServicesRequest {
  259. message Filters {
  260. repeated string names = 1;
  261. repeated string id_prefixes = 2;
  262. map<string, string> labels = 3;
  263. // NamePrefixes matches all objects with the given prefixes
  264. repeated string name_prefixes = 4;
  265. repeated string runtimes = 5;
  266. }
  267. Filters filters = 1;
  268. }
  269. message ListServicesResponse {
  270. repeated Service services = 1;
  271. }
  272. message CreateNetworkRequest {
  273. NetworkSpec spec = 1;
  274. }
  275. message CreateNetworkResponse {
  276. Network network = 1;
  277. }
  278. message GetNetworkRequest {
  279. string name = 1;
  280. string network_id = 2;
  281. }
  282. message GetNetworkResponse {
  283. Network network = 1;
  284. }
  285. message RemoveNetworkRequest {
  286. string name = 1;
  287. string network_id = 2;
  288. }
  289. message RemoveNetworkResponse {}
  290. message ListNetworksRequest {
  291. message Filters {
  292. repeated string names = 1;
  293. repeated string id_prefixes = 2;
  294. map<string, string> labels = 3;
  295. // NamePrefixes matches all objects with the given prefixes
  296. repeated string name_prefixes = 4;
  297. }
  298. Filters filters = 1;
  299. }
  300. message ListNetworksResponse {
  301. repeated Network networks = 1;
  302. }
  303. message GetClusterRequest {
  304. string cluster_id = 1;
  305. }
  306. message GetClusterResponse {
  307. Cluster cluster = 1;
  308. }
  309. message ListClustersRequest {
  310. message Filters {
  311. repeated string names = 1;
  312. repeated string id_prefixes = 2;
  313. map<string, string> labels = 3;
  314. // NamePrefixes matches all objects with the given prefixes
  315. repeated string name_prefixes = 4;
  316. }
  317. Filters filters = 1;
  318. }
  319. message ListClustersResponse {
  320. repeated Cluster clusters = 1;
  321. }
  322. // KeyRotation tells UpdateCluster what items to rotate
  323. message KeyRotation {
  324. // WorkerJoinToken tells UpdateCluster to rotate the worker secret token.
  325. bool worker_join_token = 1;
  326. // ManagerJoinToken tells UpdateCluster to rotate the manager secret token.
  327. bool manager_join_token = 2;
  328. // ManagerUnlockKey tells UpdateCluster to rotate the manager unlock key
  329. bool manager_unlock_key = 3;
  330. }
  331. message UpdateClusterRequest {
  332. // ClusterID is the cluster ID to update.
  333. string cluster_id = 1;
  334. // ClusterVersion is the version of the cluster being updated.
  335. Version cluster_version = 2;
  336. // Spec is the new spec to apply to the cluster.
  337. ClusterSpec spec = 3;
  338. // Rotation contains flags for join token and unlock key rotation
  339. KeyRotation rotation = 4 [(gogoproto.nullable) = false];
  340. }
  341. message UpdateClusterResponse {
  342. Cluster cluster = 1;
  343. }
  344. // GetSecretRequest is the request to get a `Secret` object given a secret id.
  345. message GetSecretRequest {
  346. string secret_id = 1;
  347. }
  348. // GetSecretResponse contains the Secret corresponding to the id in
  349. // `GetSecretRequest`, but the `Secret.Spec.Data` field in each `Secret`
  350. // object should be nil instead of actually containing the secret bytes.
  351. message GetSecretResponse {
  352. Secret secret = 1;
  353. }
  354. message UpdateSecretRequest {
  355. // SecretID is the secret ID to update.
  356. string secret_id = 1;
  357. // SecretVersion is the version of the secret being updated.
  358. Version secret_version = 2;
  359. // Spec is the new spec to apply to the Secret
  360. // Only some fields are allowed to be updated.
  361. SecretSpec spec = 3;
  362. }
  363. message UpdateSecretResponse {
  364. Secret secret = 1;
  365. }
  366. // ListSecretRequest is the request to list all non-internal secrets in the secret store,
  367. // or all secrets filtered by (name or name prefix or id prefix) and labels.
  368. message ListSecretsRequest {
  369. message Filters {
  370. repeated string names = 1;
  371. repeated string id_prefixes = 2;
  372. map<string, string> labels = 3;
  373. repeated string name_prefixes = 4;
  374. }
  375. Filters filters = 1;
  376. }
  377. // ListSecretResponse contains a list of all the secrets that match the name or
  378. // name prefix filters provided in `ListSecretRequest`. The `Secret.Spec.Data`
  379. // field in each `Secret` object should be nil instead of actually containing
  380. // the secret bytes.
  381. message ListSecretsResponse {
  382. repeated Secret secrets = 1;
  383. }
  384. // CreateSecretRequest specifies a new secret (it will not update an existing
  385. // secret) to create.
  386. message CreateSecretRequest {
  387. SecretSpec spec = 1;
  388. }
  389. // CreateSecretResponse contains the newly created `Secret` corresponding to the
  390. // name in `CreateSecretRequest`. The `Secret.Spec.Data` field should be nil instead
  391. // of actually containing the secret bytes.
  392. message CreateSecretResponse {
  393. Secret secret = 1;
  394. }
  395. // RemoveSecretRequest contains the ID of the secret that should be removed. This
  396. // removes all versions of the secret.
  397. message RemoveSecretRequest {
  398. string secret_id = 1;
  399. }
  400. // RemoveSecretResponse is an empty object indicating the successful removal of
  401. // a secret.
  402. message RemoveSecretResponse {}
  403. // GetConfigRequest is the request to get a `Config` object given a config id.
  404. message GetConfigRequest {
  405. string config_id = 1;
  406. }
  407. // GetConfigResponse contains the Config corresponding to the id in
  408. // `GetConfigRequest`.
  409. message GetConfigResponse {
  410. Config config = 1;
  411. }
  412. message UpdateConfigRequest {
  413. // ConfigID is the config ID to update.
  414. string config_id = 1;
  415. // ConfigVersion is the version of the config being updated.
  416. Version config_version = 2;
  417. // Spec is the new spec to apply to the Config
  418. // Only some fields are allowed to be updated.
  419. ConfigSpec spec = 3;
  420. }
  421. message UpdateConfigResponse {
  422. Config config = 1;
  423. }
  424. // ListConfigRequest is the request to list all configs in the config store,
  425. // or all configs filtered by (name or name prefix or id prefix) and labels.
  426. message ListConfigsRequest {
  427. message Filters {
  428. repeated string names = 1;
  429. repeated string id_prefixes = 2;
  430. map<string, string> labels = 3;
  431. repeated string name_prefixes = 4;
  432. }
  433. Filters filters = 1;
  434. }
  435. // ListConfigResponse contains a list of all the configs that match the name or
  436. // name prefix filters provided in `ListConfigRequest`.
  437. message ListConfigsResponse {
  438. repeated Config configs = 1;
  439. }
  440. // CreateConfigRequest specifies a new config (it will not update an existing
  441. // config) to create.
  442. message CreateConfigRequest {
  443. ConfigSpec spec = 1;
  444. }
  445. // CreateConfigResponse contains the newly created `Config` corresponding to the
  446. // name in `CreateConfigRequest`.
  447. message CreateConfigResponse {
  448. Config config = 1;
  449. }
  450. // RemoveConfigRequest contains the ID of the config that should be removed. This
  451. // removes all versions of the config.
  452. message RemoveConfigRequest {
  453. string config_id = 1;
  454. }
  455. // RemoveConfigResponse is an empty object indicating the successful removal of
  456. // a config.
  457. message RemoveConfigResponse {}