github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/docs/plugin-protocol/tfplugin5.2.proto (about) 1 // Durgaform Plugin RPC protocol version 5.2 2 // 3 // This file defines version 5.2 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 5 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/tfplugin5"; 21 22 package tfplugin5; 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 Stop { 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, Provider, or Provisioner. 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 string description = 3; 94 bool required = 4; 95 bool optional = 5; 96 bool computed = 6; 97 bool sensitive = 7; 98 StringKind description_kind = 8; 99 bool deprecated = 9; 100 } 101 102 message NestedBlock { 103 enum NestingMode { 104 INVALID = 0; 105 SINGLE = 1; 106 LIST = 2; 107 SET = 3; 108 MAP = 4; 109 GROUP = 5; 110 } 111 112 string type_name = 1; 113 Block block = 2; 114 NestingMode nesting = 3; 115 int64 min_items = 4; 116 int64 max_items = 5; 117 } 118 119 // The version of the schema. 120 // Schemas are versioned, so that providers can upgrade a saved resource 121 // state when the schema is changed. 122 int64 version = 1; 123 124 // Block is the top level configuration block for this schema. 125 Block block = 2; 126 } 127 128 service Provider { 129 //////// Information about what a provider supports/expects 130 rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); 131 rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); 132 rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); 133 rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); 134 rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); 135 136 //////// One-time initialization, called before other functions below 137 rpc Configure(Configure.Request) returns (Configure.Response); 138 139 //////// Managed Resource Lifecycle 140 rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); 141 rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); 142 rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); 143 rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); 144 145 rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); 146 147 //////// Graceful Shutdown 148 rpc Stop(Stop.Request) returns (Stop.Response); 149 } 150 151 message GetProviderSchema { 152 message Request { 153 } 154 message Response { 155 Schema provider = 1; 156 map<string, Schema> resource_schemas = 2; 157 map<string, Schema> data_source_schemas = 3; 158 repeated Diagnostic diagnostics = 4; 159 Schema provider_meta = 5; 160 } 161 } 162 163 message PrepareProviderConfig { 164 message Request { 165 DynamicValue config = 1; 166 } 167 message Response { 168 DynamicValue prepared_config = 1; 169 repeated Diagnostic diagnostics = 2; 170 } 171 } 172 173 message UpgradeResourceState { 174 message Request { 175 string type_name = 1; 176 177 // version is the schema_version number recorded in the state file 178 int64 version = 2; 179 180 // raw_state is the raw states as stored for the resource. Core does 181 // not have access to the schema of prior_version, so it's the 182 // provider's responsibility to interpret this value using the 183 // appropriate older schema. The raw_state will be the json encoded 184 // state, or a legacy flat-mapped format. 185 RawState raw_state = 3; 186 } 187 message Response { 188 // new_state is a msgpack-encoded data structure that, when interpreted with 189 // the _current_ schema for this resource type, is functionally equivalent to 190 // that which was given in prior_state_raw. 191 DynamicValue upgraded_state = 1; 192 193 // diagnostics describes any errors encountered during migration that could not 194 // be safely resolved, and warnings about any possibly-risky assumptions made 195 // in the upgrade process. 196 repeated Diagnostic diagnostics = 2; 197 } 198 } 199 200 message ValidateResourceTypeConfig { 201 message Request { 202 string type_name = 1; 203 DynamicValue config = 2; 204 } 205 message Response { 206 repeated Diagnostic diagnostics = 1; 207 } 208 } 209 210 message ValidateDataSourceConfig { 211 message Request { 212 string type_name = 1; 213 DynamicValue config = 2; 214 } 215 message Response { 216 repeated Diagnostic diagnostics = 1; 217 } 218 } 219 220 message Configure { 221 message Request { 222 string durgaform_version = 1; 223 DynamicValue config = 2; 224 } 225 message Response { 226 repeated Diagnostic diagnostics = 1; 227 } 228 } 229 230 message ReadResource { 231 message Request { 232 string type_name = 1; 233 DynamicValue current_state = 2; 234 bytes private = 3; 235 DynamicValue provider_meta = 4; 236 } 237 message Response { 238 DynamicValue new_state = 1; 239 repeated Diagnostic diagnostics = 2; 240 bytes private = 3; 241 } 242 } 243 244 message PlanResourceChange { 245 message Request { 246 string type_name = 1; 247 DynamicValue prior_state = 2; 248 DynamicValue proposed_new_state = 3; 249 DynamicValue config = 4; 250 bytes prior_private = 5; 251 DynamicValue provider_meta = 6; 252 } 253 254 message Response { 255 DynamicValue planned_state = 1; 256 repeated AttributePath requires_replace = 2; 257 bytes planned_private = 3; 258 repeated Diagnostic diagnostics = 4; 259 260 261 // This may be set only by the helper/schema "SDK" in the main Durgaform 262 // repository, to request that Durgaform Core >=0.12 permit additional 263 // inconsistencies that can result from the legacy SDK type system 264 // and its imprecise mapping to the >=0.12 type system. 265 // The change in behavior implied by this flag makes sense only for the 266 // specific details of the legacy SDK type system, and are not a general 267 // mechanism to avoid proper type handling in providers. 268 // 269 // ==== DO NOT USE THIS ==== 270 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== 271 // ==== DO NOT USE THIS ==== 272 bool legacy_type_system = 5; 273 } 274 } 275 276 message ApplyResourceChange { 277 message Request { 278 string type_name = 1; 279 DynamicValue prior_state = 2; 280 DynamicValue planned_state = 3; 281 DynamicValue config = 4; 282 bytes planned_private = 5; 283 DynamicValue provider_meta = 6; 284 } 285 message Response { 286 DynamicValue new_state = 1; 287 bytes private = 2; 288 repeated Diagnostic diagnostics = 3; 289 290 // This may be set only by the helper/schema "SDK" in the main Durgaform 291 // repository, to request that Durgaform Core >=0.12 permit additional 292 // inconsistencies that can result from the legacy SDK type system 293 // and its imprecise mapping to the >=0.12 type system. 294 // The change in behavior implied by this flag makes sense only for the 295 // specific details of the legacy SDK type system, and are not a general 296 // mechanism to avoid proper type handling in providers. 297 // 298 // ==== DO NOT USE THIS ==== 299 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== 300 // ==== DO NOT USE THIS ==== 301 bool legacy_type_system = 4; 302 } 303 } 304 305 message ImportResourceState { 306 message Request { 307 string type_name = 1; 308 string id = 2; 309 } 310 311 message ImportedResource { 312 string type_name = 1; 313 DynamicValue state = 2; 314 bytes private = 3; 315 } 316 317 message Response { 318 repeated ImportedResource imported_resources = 1; 319 repeated Diagnostic diagnostics = 2; 320 } 321 } 322 323 message ReadDataSource { 324 message Request { 325 string type_name = 1; 326 DynamicValue config = 2; 327 DynamicValue provider_meta = 3; 328 } 329 message Response { 330 DynamicValue state = 1; 331 repeated Diagnostic diagnostics = 2; 332 } 333 } 334 335 service Provisioner { 336 rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); 337 rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); 338 rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); 339 rpc Stop(Stop.Request) returns (Stop.Response); 340 } 341 342 message GetProvisionerSchema { 343 message Request { 344 } 345 message Response { 346 Schema provisioner = 1; 347 repeated Diagnostic diagnostics = 2; 348 } 349 } 350 351 message ValidateProvisionerConfig { 352 message Request { 353 DynamicValue config = 1; 354 } 355 message Response { 356 repeated Diagnostic diagnostics = 1; 357 } 358 } 359 360 message ProvisionResource { 361 message Request { 362 DynamicValue config = 1; 363 DynamicValue connection = 2; 364 } 365 message Response { 366 string output = 1; 367 repeated Diagnostic diagnostics = 2; 368 } 369 }