github.com/kanishk98/terraform@v1.3.0-dev.0.20220917174235-661ca8088a6a/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 message Request { 205 string type_name = 1; 206 207 // version is the schema_version number recorded in the state file 208 int64 version = 2; 209 210 // raw_state is the raw states as stored for the resource. Core does 211 // not have access to the schema of prior_version, so it's the 212 // provider's responsibility to interpret this value using the 213 // appropriate older schema. The raw_state will be the json encoded 214 // state, or a legacy flat-mapped format. 215 RawState raw_state = 3; 216 } 217 message Response { 218 // new_state is a msgpack-encoded data structure that, when interpreted with 219 // the _current_ schema for this resource type, is functionally equivalent to 220 // that which was given in prior_state_raw. 221 DynamicValue upgraded_state = 1; 222 223 // diagnostics describes any errors encountered during migration that could not 224 // be safely resolved, and warnings about any possibly-risky assumptions made 225 // in the upgrade process. 226 repeated Diagnostic diagnostics = 2; 227 } 228 } 229 230 message ValidateResourceConfig { 231 message Request { 232 string type_name = 1; 233 DynamicValue config = 2; 234 } 235 message Response { 236 repeated Diagnostic diagnostics = 1; 237 } 238 } 239 240 message ValidateDataResourceConfig { 241 message Request { 242 string type_name = 1; 243 DynamicValue config = 2; 244 } 245 message Response { 246 repeated Diagnostic diagnostics = 1; 247 } 248 } 249 250 message ConfigureProvider { 251 message Request { 252 string terraform_version = 1; 253 DynamicValue config = 2; 254 } 255 message Response { 256 repeated Diagnostic diagnostics = 1; 257 } 258 } 259 260 message ReadResource { 261 message Request { 262 string type_name = 1; 263 DynamicValue current_state = 2; 264 bytes private = 3; 265 DynamicValue provider_meta = 4; 266 } 267 message Response { 268 DynamicValue new_state = 1; 269 repeated Diagnostic diagnostics = 2; 270 bytes private = 3; 271 } 272 } 273 274 message PlanResourceChange { 275 message Request { 276 string type_name = 1; 277 DynamicValue prior_state = 2; 278 DynamicValue proposed_new_state = 3; 279 DynamicValue config = 4; 280 bytes prior_private = 5; 281 DynamicValue provider_meta = 6; 282 } 283 284 message Response { 285 DynamicValue planned_state = 1; 286 repeated AttributePath requires_replace = 2; 287 bytes planned_private = 3; 288 repeated Diagnostic diagnostics = 4; 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 }