github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/docs/plugin-protocol/tfplugin6.0.proto (about) 1 // Durgaform Plugin RPC protocol version 6.0 2 // 3 // This file defines version 6.0 of the RPC protocol. To implement a plugin 4 // against this protocol, copy this definition into your own codebase and 5 // use protoc to generate stubs for your target language. 6 // 7 // This file will not be updated. Any minor versions of protocol 6 to follow 8 // should copy this file and modify the copy while maintaing backwards 9 // compatibility. Breaking changes, if any are required, will come 10 // in a subsequent major version with its own separate proto definition. 11 // 12 // Note that only the proto files included in a release tag of Durgaform are 13 // official protocol releases. Proto files taken from other commits may include 14 // incomplete changes or features that did not make it into a final release. 15 // In all reasonable cases, plugin developers should take the proto file from 16 // the tag of the most recent release of Durgaform, and not from the main 17 // branch or any other development branch. 18 // 19 syntax = "proto3"; 20 option go_package = "github.com/hashicorp/durgaform/internal/tfplugin6"; 21 22 package tfplugin6; 23 24 // DynamicValue is an opaque encoding of durgaform data, with the field name 25 // indicating the encoding scheme used. 26 message DynamicValue { 27 bytes msgpack = 1; 28 bytes json = 2; 29 } 30 31 message Diagnostic { 32 enum Severity { 33 INVALID = 0; 34 ERROR = 1; 35 WARNING = 2; 36 } 37 Severity severity = 1; 38 string summary = 2; 39 string detail = 3; 40 AttributePath attribute = 4; 41 } 42 43 message AttributePath { 44 message Step { 45 oneof selector { 46 // Set "attribute_name" to represent looking up an attribute 47 // in the current object value. 48 string attribute_name = 1; 49 // Set "element_key_*" to represent looking up an element in 50 // an indexable collection type. 51 string element_key_string = 2; 52 int64 element_key_int = 3; 53 } 54 } 55 repeated Step steps = 1; 56 } 57 58 message StopProvider { 59 message Request { 60 } 61 message Response { 62 string Error = 1; 63 } 64 } 65 66 // RawState holds the stored state for a resource to be upgraded by the 67 // provider. It can be in one of two formats, the current json encoded format 68 // in bytes, or the legacy flatmap format as a map of strings. 69 message RawState { 70 bytes json = 1; 71 map<string, string> flatmap = 2; 72 } 73 74 enum StringKind { 75 PLAIN = 0; 76 MARKDOWN = 1; 77 } 78 79 // Schema is the configuration schema for a Resource or Provider. 80 message Schema { 81 message Block { 82 int64 version = 1; 83 repeated Attribute attributes = 2; 84 repeated NestedBlock block_types = 3; 85 string description = 4; 86 StringKind description_kind = 5; 87 bool deprecated = 6; 88 } 89 90 message Attribute { 91 string name = 1; 92 bytes type = 2; 93 Object nested_type = 10; 94 string description = 3; 95 bool required = 4; 96 bool optional = 5; 97 bool computed = 6; 98 bool sensitive = 7; 99 StringKind description_kind = 8; 100 bool deprecated = 9; 101 } 102 103 message NestedBlock { 104 enum NestingMode { 105 INVALID = 0; 106 SINGLE = 1; 107 LIST = 2; 108 SET = 3; 109 MAP = 4; 110 GROUP = 5; 111 } 112 113 string type_name = 1; 114 Block block = 2; 115 NestingMode nesting = 3; 116 int64 min_items = 4; 117 int64 max_items = 5; 118 } 119 120 message Object { 121 enum NestingMode { 122 INVALID = 0; 123 SINGLE = 1; 124 LIST = 2; 125 SET = 3; 126 MAP = 4; 127 } 128 129 repeated Attribute attributes = 1; 130 NestingMode nesting = 3; 131 int64 min_items = 4; 132 int64 max_items = 5; 133 } 134 135 // The version of the schema. 136 // Schemas are versioned, so that providers can upgrade a saved resource 137 // state when the schema is changed. 138 int64 version = 1; 139 140 // Block is the top level configuration block for this schema. 141 Block block = 2; 142 } 143 144 service Provider { 145 //////// Information about what a provider supports/expects 146 rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); 147 rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); 148 rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); 149 rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); 150 rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); 151 152 //////// One-time initialization, called before other functions below 153 rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); 154 155 //////// Managed Resource Lifecycle 156 rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); 157 rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); 158 rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); 159 rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); 160 161 rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); 162 163 //////// Graceful Shutdown 164 rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); 165 } 166 167 message GetProviderSchema { 168 message Request { 169 } 170 message Response { 171 Schema provider = 1; 172 map<string, Schema> resource_schemas = 2; 173 map<string, Schema> data_source_schemas = 3; 174 repeated Diagnostic diagnostics = 4; 175 Schema provider_meta = 5; 176 } 177 } 178 179 message ValidateProviderConfig { 180 message Request { 181 DynamicValue config = 1; 182 } 183 message Response { 184 repeated Diagnostic diagnostics = 2; 185 } 186 } 187 188 message UpgradeResourceState { 189 message Request { 190 string type_name = 1; 191 192 // version is the schema_version number recorded in the state file 193 int64 version = 2; 194 195 // raw_state is the raw states as stored for the resource. Core does 196 // not have access to the schema of prior_version, so it's the 197 // provider's responsibility to interpret this value using the 198 // appropriate older schema. The raw_state will be the json encoded 199 // state, or a legacy flat-mapped format. 200 RawState raw_state = 3; 201 } 202 message Response { 203 // new_state is a msgpack-encoded data structure that, when interpreted with 204 // the _current_ schema for this resource type, is functionally equivalent to 205 // that which was given in prior_state_raw. 206 DynamicValue upgraded_state = 1; 207 208 // diagnostics describes any errors encountered during migration that could not 209 // be safely resolved, and warnings about any possibly-risky assumptions made 210 // in the upgrade process. 211 repeated Diagnostic diagnostics = 2; 212 } 213 } 214 215 message ValidateResourceConfig { 216 message Request { 217 string type_name = 1; 218 DynamicValue config = 2; 219 } 220 message Response { 221 repeated Diagnostic diagnostics = 1; 222 } 223 } 224 225 message ValidateDataResourceConfig { 226 message Request { 227 string type_name = 1; 228 DynamicValue config = 2; 229 } 230 message Response { 231 repeated Diagnostic diagnostics = 1; 232 } 233 } 234 235 message ConfigureProvider { 236 message Request { 237 string durgaform_version = 1; 238 DynamicValue config = 2; 239 } 240 message Response { 241 repeated Diagnostic diagnostics = 1; 242 } 243 } 244 245 message ReadResource { 246 message Request { 247 string type_name = 1; 248 DynamicValue current_state = 2; 249 bytes private = 3; 250 DynamicValue provider_meta = 4; 251 } 252 message Response { 253 DynamicValue new_state = 1; 254 repeated Diagnostic diagnostics = 2; 255 bytes private = 3; 256 } 257 } 258 259 message PlanResourceChange { 260 message Request { 261 string type_name = 1; 262 DynamicValue prior_state = 2; 263 DynamicValue proposed_new_state = 3; 264 DynamicValue config = 4; 265 bytes prior_private = 5; 266 DynamicValue provider_meta = 6; 267 } 268 269 message Response { 270 DynamicValue planned_state = 1; 271 repeated AttributePath requires_replace = 2; 272 bytes planned_private = 3; 273 repeated Diagnostic diagnostics = 4; 274 } 275 } 276 277 message ApplyResourceChange { 278 message Request { 279 string type_name = 1; 280 DynamicValue prior_state = 2; 281 DynamicValue planned_state = 3; 282 DynamicValue config = 4; 283 bytes planned_private = 5; 284 DynamicValue provider_meta = 6; 285 } 286 message Response { 287 DynamicValue new_state = 1; 288 bytes private = 2; 289 repeated Diagnostic diagnostics = 3; 290 } 291 } 292 293 message ImportResourceState { 294 message Request { 295 string type_name = 1; 296 string id = 2; 297 } 298 299 message ImportedResource { 300 string type_name = 1; 301 DynamicValue state = 2; 302 bytes private = 3; 303 } 304 305 message Response { 306 repeated ImportedResource imported_resources = 1; 307 repeated Diagnostic diagnostics = 2; 308 } 309 } 310 311 message ReadDataSource { 312 message Request { 313 string type_name = 1; 314 DynamicValue config = 2; 315 DynamicValue provider_meta = 3; 316 } 317 message Response { 318 DynamicValue state = 1; 319 repeated Diagnostic diagnostics = 2; 320 } 321 }