1 // Terraform Plugin RPC protocol version 5.0
3 // This file defines version 5.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.
7 // This file will be updated in-place in the source Terraform repository for
8 // any minor versions of protocol 5, but later minor versions will always be
9 // backwards compatible. Breaking changes, if any are required, will come
10 // in a subsequent major version with its own separate proto definition.
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 master
17 // branch or any other development branch.
23 // DynamicValue is an opaque encoding of terraform data, with the field name
24 // indicating the encoding scheme used.
25 message DynamicValue {
36 Severity severity = 1;
39 AttributePath attribute = 4;
42 message AttributePath {
45 // Set "attribute_name" to represent looking up an attribute
46 // in the current object value.
47 string attribute_name = 1;
48 // Set "element_key_*" to represent looking up an element in
49 // an indexable collection type.
50 string element_key_string = 2;
51 int64 element_key_int = 3;
54 repeated Step steps = 1;
65 // RawState holds the stored state for a resource to be upgraded by the
66 // provider. It can be in one of two formats, the current json encoded format
67 // in bytes, or the legacy flatmap format as a map of strings.
70 map<string, string> flatmap = 2;
73 // Schema is the configuration schema for a Resource, Provider, or Provisioner.
77 repeated Attribute attributes = 2;
78 repeated NestedBlock block_types = 3;
84 string description = 3;
101 string type_name = 1;
103 NestingMode nesting = 3;
108 // The version of the schema.
109 // Schemas are versioned, so that providers can upgrade a saved resource
110 // state when the schema is changed.
113 // Block is the top level configuration block for this schema.
118 //////// Information about what a provider supports/expects
119 rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response);
120 rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response);
121 rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response);
122 rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response);
123 rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response);
125 //////// One-time initialization, called before other functions below
126 rpc Configure(Configure.Request) returns (Configure.Response);
128 //////// Managed Resource Lifecycle
129 rpc ReadResource(ReadResource.Request) returns (ReadResource.Response);
130 rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response);
131 rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response);
132 rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response);
134 rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response);
136 //////// Graceful Shutdown
137 rpc Stop(Stop.Request) returns (Stop.Response);
140 message GetProviderSchema {
145 map<string, Schema> resource_schemas = 2;
146 map<string, Schema> data_source_schemas = 3;
147 repeated Diagnostic diagnostics = 4;
151 message PrepareProviderConfig {
153 DynamicValue config = 1;
156 DynamicValue prepared_config = 1;
157 repeated Diagnostic diagnostics = 2;
161 message UpgradeResourceState {
163 string type_name = 1;
165 // version is the schema_version number recorded in the state file
168 // raw_state is the raw states as stored for the resource. Core does
169 // not have access to the schema of prior_version, so it's the
170 // provider's responsibility to interpret this value using the
171 // appropriate older schema. The raw_state will be the json encoded
172 // state, or a legacy flat-mapped format.
173 RawState raw_state = 3;
176 // new_state is a msgpack-encoded data structure that, when interpreted with
177 // the _current_ schema for this resource type, is functionally equivalent to
178 // that which was given in prior_state_raw.
179 DynamicValue upgraded_state = 1;
181 // diagnostics describes any errors encountered during migration that could not
182 // be safely resolved, and warnings about any possibly-risky assumptions made
183 // in the upgrade process.
184 repeated Diagnostic diagnostics = 2;
188 message ValidateResourceTypeConfig {
190 string type_name = 1;
191 DynamicValue config = 2;
194 repeated Diagnostic diagnostics = 1;
198 message ValidateDataSourceConfig {
200 string type_name = 1;
201 DynamicValue config = 2;
204 repeated Diagnostic diagnostics = 1;
210 string terraform_version = 1;
211 DynamicValue config = 2;
214 repeated Diagnostic diagnostics = 1;
218 message ReadResource {
220 string type_name = 1;
221 DynamicValue current_state = 2;
224 DynamicValue new_state = 1;
225 repeated Diagnostic diagnostics = 2;
229 message PlanResourceChange {
231 string type_name = 1;
232 DynamicValue prior_state = 2;
233 DynamicValue proposed_new_state = 3;
234 DynamicValue config = 4;
235 bytes prior_private = 5;
239 DynamicValue planned_state = 1;
240 repeated AttributePath requires_replace = 2;
241 bytes planned_private = 3;
242 repeated Diagnostic diagnostics = 4;
245 // This may be set only by the helper/schema "SDK" in the main Terraform
246 // repository, to request that Terraform Core >=0.12 permit additional
247 // inconsistencies that can result from the legacy SDK type system
248 // and its imprecise mapping to the >=0.12 type system.
249 // The change in behavior implied by this flag makes sense only for the
250 // specific details of the legacy SDK type system, and are not a general
251 // mechanism to avoid proper type handling in providers.
253 // ==== DO NOT USE THIS ====
254 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ====
255 // ==== DO NOT USE THIS ====
256 bool legacy_type_system = 5;
260 message ApplyResourceChange {
262 string type_name = 1;
263 DynamicValue prior_state = 2;
264 DynamicValue planned_state = 3;
265 DynamicValue config = 4;
266 bytes planned_private = 5;
269 DynamicValue new_state = 1;
271 repeated Diagnostic diagnostics = 3;
273 // This may be set only by the helper/schema "SDK" in the main Terraform
274 // repository, to request that Terraform Core >=0.12 permit additional
275 // inconsistencies that can result from the legacy SDK type system
276 // and its imprecise mapping to the >=0.12 type system.
277 // The change in behavior implied by this flag makes sense only for the
278 // specific details of the legacy SDK type system, and are not a general
279 // mechanism to avoid proper type handling in providers.
281 // ==== DO NOT USE THIS ====
282 // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ====
283 // ==== DO NOT USE THIS ====
284 bool legacy_type_system = 4;
288 message ImportResourceState {
290 string type_name = 1;
294 message ImportedResource {
295 string type_name = 1;
296 DynamicValue state = 2;
301 repeated ImportedResource imported_resources = 1;
302 repeated Diagnostic diagnostics = 2;
306 message ReadDataSource {
308 string type_name = 1;
309 DynamicValue config = 2;
312 DynamicValue state = 1;
313 repeated Diagnostic diagnostics = 2;
317 service Provisioner {
318 rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response);
319 rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response);
320 rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response);
321 rpc Stop(Stop.Request) returns (Stop.Response);
324 message GetProvisionerSchema {
328 Schema provisioner = 1;
329 repeated Diagnostic diagnostics = 2;
333 message ValidateProvisionerConfig {
335 DynamicValue config = 1;
338 repeated Diagnostic diagnostics = 1;
342 message ProvisionResource {
344 DynamicValue config = 1;
345 DynamicValue connection = 2;
349 repeated Diagnostic diagnostics = 2;