github.com/graywolf-at-work-2/terraform-vendor@v1.4.5/docs/plugin-protocol/tfplugin6.3.proto (about) 1 // Terraform Plugin RPC protocol version 6.3 2 // 3 // This file defines version 6.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 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 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/tfplugin6"; 21 22 package tfplugin6; 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 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 132 // MinItems and MaxItems were never used in the protocol, and have no 133 // effect on validation. 134 int64 min_items = 4 [deprecated = true]; 135 int64 max_items = 5 [deprecated = true]; 136 } 137 138 // The version of the schema. 139 // Schemas are versioned, so that providers can upgrade a saved resource 140 // state when the schema is changed. 141 int64 version = 1; 142 143 // Block is the top level configuration block for this schema. 144 Block block = 2; 145 } 146 147 service Provider { 148 //////// Information about what a provider supports/expects 149 rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); 150 rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); 151 rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); 152 rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); 153 rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); 154 155 //////// One-time initialization, called before other functions below 156 rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); 157 158 //////// Managed Resource Lifecycle 159 rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); 160 rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); 161 rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); 162 rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); 163 164 rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); 165 166 //////// Graceful Shutdown 167 rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); 168 } 169 170 message GetProviderSchema { 171 message Request { 172 } 173 message Response { 174 Schema provider = 1; 175 map<string, Schema> resource_schemas = 2; 176 map<string, Schema> data_source_schemas = 3; 177 repeated Diagnostic diagnostics = 4; 178 Schema provider_meta = 5; 179 ServerCapabilities server_capabilities = 6; 180 } 181 182 183 // ServerCapabilities allows providers to communicate extra information 184 // regarding supported protocol features. This is used to indicate 185 // availability of certain forward-compatible changes which may be optional 186 // in a major protocol version, but cannot be tested for directly. 187 message ServerCapabilities { 188 // The plan_destroy capability signals that a provider expects a call 189 // to PlanResourceChange when a resource is going to be destroyed. 190 bool plan_destroy = 1; 191 } 192 } 193 194 message ValidateProviderConfig { 195 message Request { 196 DynamicValue config = 1; 197 } 198 message Response { 199 repeated Diagnostic diagnostics = 2; 200 } 201 } 202 203 message UpgradeResourceState { 204 // Request is the message that is sent to the provider during the 205 // UpgradeResourceState RPC. 206 // 207 // This message intentionally does not include configuration data as any 208 // configuration-based or configuration-conditional changes should occur 209 // during the PlanResourceChange RPC. Additionally, the configuration is 210 // not guaranteed to exist (in the case of resource destruction), be wholly 211 // known, nor match the given prior state, which could lead to unexpected 212 // provider behaviors for practitioners. 213 message Request { 214 string type_name = 1; 215 216 // version is the schema_version number recorded in the state file 217 int64 version = 2; 218 219 // raw_state is the raw states as stored for the resource. Core does 220 // not have access to the schema of prior_version, so it's the 221 // provider's responsibility to interpret this value using the 222 // appropriate older schema. The raw_state will be the json encoded 223 // state, or a legacy flat-mapped format. 224 RawState raw_state = 3; 225 } 226 message Response { 227 // new_state is a msgpack-encoded data structure that, when interpreted with 228 // the _current_ schema for this resource type, is functionally equivalent to 229 // that which was given in prior_state_raw. 230 DynamicValue upgraded_state = 1; 231 232 // diagnostics describes any errors encountered during migration that could not 233 // be safely resolved, and warnings about any possibly-risky assumptions made 234 // in the upgrade process. 235 repeated Diagnostic diagnostics = 2; 236 } 237 } 238 239 message ValidateResourceConfig { 240 message Request { 241 string type_name = 1; 242 DynamicValue config = 2; 243 } 244 message Response { 245 repeated Diagnostic diagnostics = 1; 246 } 247 } 248 249 message ValidateDataResourceConfig { 250 message Request { 251 string type_name = 1; 252 DynamicValue config = 2; 253 } 254 message Response { 255 repeated Diagnostic diagnostics = 1; 256 } 257 } 258 259 message ConfigureProvider { 260 message Request { 261 string terraform_version = 1; 262 DynamicValue config = 2; 263 } 264 message Response { 265 repeated Diagnostic diagnostics = 1; 266 } 267 } 268 269 message ReadResource { 270 // Request is the message that is sent to the provider during the 271 // ReadResource RPC. 272 // 273 // This message intentionally does not include configuration data as any 274 // configuration-based or configuration-conditional changes should occur 275 // during the PlanResourceChange RPC. Additionally, the configuration is 276 // not guaranteed to be wholly known nor match the given prior state, which 277 // could lead to unexpected provider behaviors for practitioners. 278 message Request { 279 string type_name = 1; 280 DynamicValue current_state = 2; 281 bytes private = 3; 282 DynamicValue provider_meta = 4; 283 } 284 message Response { 285 DynamicValue new_state = 1; 286 repeated Diagnostic diagnostics = 2; 287 bytes private = 3; 288 } 289 } 290 291 message PlanResourceChange { 292 message Request { 293 string type_name = 1; 294 DynamicValue prior_state = 2; 295 DynamicValue proposed_new_state = 3; 296 DynamicValue config = 4; 297 bytes prior_private = 5; 298 DynamicValue provider_meta = 6; 299 } 300 301 message Response { 302 DynamicValue planned_state = 1; 303 repeated AttributePath requires_replace = 2; 304 bytes planned_private = 3; 305 repeated Diagnostic diagnostics = 4; 306 307 // This may be set only by the helper/schema "SDK" in the main Terraform 308 // repository, to request that Terraform Core >=0.12 permit additional 309 // inconsistencies that can result from the legacy SDK type system 310 // and its imprecise mapping to the >=0.12 type system. 311 // The change in behavior implied by this flag makes sense only for the 312 // specific details of the legacy SDK type system, and are not a general 313 // mechanism to avoid proper type handling in providers. 314 // 315 // ==== DO NOT USE THIS ==== 316 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== 317 // ==== DO NOT USE THIS ==== 318 bool legacy_type_system = 5; 319 } 320 } 321 322 message ApplyResourceChange { 323 message Request { 324 string type_name = 1; 325 DynamicValue prior_state = 2; 326 DynamicValue planned_state = 3; 327 DynamicValue config = 4; 328 bytes planned_private = 5; 329 DynamicValue provider_meta = 6; 330 } 331 message Response { 332 DynamicValue new_state = 1; 333 bytes private = 2; 334 repeated Diagnostic diagnostics = 3; 335 336 // This may be set only by the helper/schema "SDK" in the main Terraform 337 // repository, to request that Terraform Core >=0.12 permit additional 338 // inconsistencies that can result from the legacy SDK type system 339 // and its imprecise mapping to the >=0.12 type system. 340 // The change in behavior implied by this flag makes sense only for the 341 // specific details of the legacy SDK type system, and are not a general 342 // mechanism to avoid proper type handling in providers. 343 // 344 // ==== DO NOT USE THIS ==== 345 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== 346 // ==== DO NOT USE THIS ==== 347 bool legacy_type_system = 4; 348 } 349 } 350 351 message ImportResourceState { 352 message Request { 353 string type_name = 1; 354 string id = 2; 355 } 356 357 message ImportedResource { 358 string type_name = 1; 359 DynamicValue state = 2; 360 bytes private = 3; 361 } 362 363 message Response { 364 repeated ImportedResource imported_resources = 1; 365 repeated Diagnostic diagnostics = 2; 366 } 367 } 368 369 message ReadDataSource { 370 message Request { 371 string type_name = 1; 372 DynamicValue config = 2; 373 DynamicValue provider_meta = 3; 374 } 375 message Response { 376 DynamicValue state = 1; 377 repeated Diagnostic diagnostics = 2; 378 } 379 }