github.com/graywolf-at-work-2/terraform-vendor@v1.4.5/docs/plugin-protocol/tfplugin5.3.proto (about) 1 // Terraform Plugin RPC protocol version 5.3 2 // 3 // This file defines version 5.3 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 Terraform 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 Terraform, and not from the main 17 // branch or any other development branch. 18 // 19 syntax = "proto3"; 20 option go_package = "github.com/hashicorp/terraform/internal/tfplugin5"; 21 22 package tfplugin5; 23 24 // DynamicValue is an opaque encoding of terraform 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 ServerCapabilities server_capabilities = 6; 161 } 162 163 164 // ServerCapabilities allows providers to communicate extra information 165 // regarding supported protocol features. This is used to indicate 166 // availability of certain forward-compatible changes which may be optional 167 // in a major protocol version, but cannot be tested for directly. 168 message ServerCapabilities { 169 // The plan_destroy capability signals that a provider expects a call 170 // to PlanResourceChange when a resource is going to be destroyed. 171 bool plan_destroy = 1; 172 } 173 } 174 175 message PrepareProviderConfig { 176 message Request { 177 DynamicValue config = 1; 178 } 179 message Response { 180 DynamicValue prepared_config = 1; 181 repeated Diagnostic diagnostics = 2; 182 } 183 } 184 185 message UpgradeResourceState { 186 // Request is the message that is sent to the provider during the 187 // UpgradeResourceState RPC. 188 // 189 // This message intentionally does not include configuration data as any 190 // configuration-based or configuration-conditional changes should occur 191 // during the PlanResourceChange RPC. Additionally, the configuration is 192 // not guaranteed to exist (in the case of resource destruction), be wholly 193 // known, nor match the given prior state, which could lead to unexpected 194 // provider behaviors for practitioners. 195 message Request { 196 string type_name = 1; 197 198 // version is the schema_version number recorded in the state file 199 int64 version = 2; 200 201 // raw_state is the raw states as stored for the resource. Core does 202 // not have access to the schema of prior_version, so it's the 203 // provider's responsibility to interpret this value using the 204 // appropriate older schema. The raw_state will be the json encoded 205 // state, or a legacy flat-mapped format. 206 RawState raw_state = 3; 207 } 208 message Response { 209 // new_state is a msgpack-encoded data structure that, when interpreted with 210 // the _current_ schema for this resource type, is functionally equivalent to 211 // that which was given in prior_state_raw. 212 DynamicValue upgraded_state = 1; 213 214 // diagnostics describes any errors encountered during migration that could not 215 // be safely resolved, and warnings about any possibly-risky assumptions made 216 // in the upgrade process. 217 repeated Diagnostic diagnostics = 2; 218 } 219 } 220 221 message ValidateResourceTypeConfig { 222 message Request { 223 string type_name = 1; 224 DynamicValue config = 2; 225 } 226 message Response { 227 repeated Diagnostic diagnostics = 1; 228 } 229 } 230 231 message ValidateDataSourceConfig { 232 message Request { 233 string type_name = 1; 234 DynamicValue config = 2; 235 } 236 message Response { 237 repeated Diagnostic diagnostics = 1; 238 } 239 } 240 241 message Configure { 242 message Request { 243 string terraform_version = 1; 244 DynamicValue config = 2; 245 } 246 message Response { 247 repeated Diagnostic diagnostics = 1; 248 } 249 } 250 251 message ReadResource { 252 // Request is the message that is sent to the provider during the 253 // ReadResource RPC. 254 // 255 // This message intentionally does not include configuration data as any 256 // configuration-based or configuration-conditional changes should occur 257 // during the PlanResourceChange RPC. Additionally, the configuration is 258 // not guaranteed to be wholly known nor match the given prior state, which 259 // could lead to unexpected provider behaviors for practitioners. 260 message Request { 261 string type_name = 1; 262 DynamicValue current_state = 2; 263 bytes private = 3; 264 DynamicValue provider_meta = 4; 265 } 266 message Response { 267 DynamicValue new_state = 1; 268 repeated Diagnostic diagnostics = 2; 269 bytes private = 3; 270 } 271 } 272 273 message PlanResourceChange { 274 message Request { 275 string type_name = 1; 276 DynamicValue prior_state = 2; 277 DynamicValue proposed_new_state = 3; 278 DynamicValue config = 4; 279 bytes prior_private = 5; 280 DynamicValue provider_meta = 6; 281 } 282 283 message Response { 284 DynamicValue planned_state = 1; 285 repeated AttributePath requires_replace = 2; 286 bytes planned_private = 3; 287 repeated Diagnostic diagnostics = 4; 288 289 290 // This may be set only by the helper/schema "SDK" in the main Terraform 291 // repository, to request that Terraform 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 = 5; 302 } 303 } 304 305 message ApplyResourceChange { 306 message Request { 307 string type_name = 1; 308 DynamicValue prior_state = 2; 309 DynamicValue planned_state = 3; 310 DynamicValue config = 4; 311 bytes planned_private = 5; 312 DynamicValue provider_meta = 6; 313 } 314 message Response { 315 DynamicValue new_state = 1; 316 bytes private = 2; 317 repeated Diagnostic diagnostics = 3; 318 319 // This may be set only by the helper/schema "SDK" in the main Terraform 320 // repository, to request that Terraform Core >=0.12 permit additional 321 // inconsistencies that can result from the legacy SDK type system 322 // and its imprecise mapping to the >=0.12 type system. 323 // The change in behavior implied by this flag makes sense only for the 324 // specific details of the legacy SDK type system, and are not a general 325 // mechanism to avoid proper type handling in providers. 326 // 327 // ==== DO NOT USE THIS ==== 328 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== 329 // ==== DO NOT USE THIS ==== 330 bool legacy_type_system = 4; 331 } 332 } 333 334 message ImportResourceState { 335 message Request { 336 string type_name = 1; 337 string id = 2; 338 } 339 340 message ImportedResource { 341 string type_name = 1; 342 DynamicValue state = 2; 343 bytes private = 3; 344 } 345 346 message Response { 347 repeated ImportedResource imported_resources = 1; 348 repeated Diagnostic diagnostics = 2; 349 } 350 } 351 352 message ReadDataSource { 353 message Request { 354 string type_name = 1; 355 DynamicValue config = 2; 356 DynamicValue provider_meta = 3; 357 } 358 message Response { 359 DynamicValue state = 1; 360 repeated Diagnostic diagnostics = 2; 361 } 362 } 363 364 service Provisioner { 365 rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); 366 rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); 367 rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); 368 rpc Stop(Stop.Request) returns (Stop.Response); 369 } 370 371 message GetProvisionerSchema { 372 message Request { 373 } 374 message Response { 375 Schema provisioner = 1; 376 repeated Diagnostic diagnostics = 2; 377 } 378 } 379 380 message ValidateProvisionerConfig { 381 message Request { 382 DynamicValue config = 1; 383 } 384 message Response { 385 repeated Diagnostic diagnostics = 1; 386 } 387 } 388 389 message ProvisionResource { 390 message Request { 391 DynamicValue config = 1; 392 DynamicValue connection = 2; 393 } 394 message Response { 395 string output = 1; 396 repeated Diagnostic diagnostics = 2; 397 } 398 }