Skip to content

Commit 24a2bd6

Browse files
jbardinjbardin
committed
tfproto version 6.1
Minor version increase to deprecate min_items and max_items in nested types. Nested types have MinItems and MaxItems fields that were inherited from the block implementation, but were never validated by Terraform, and are not supported by the HCL decoder validations. Mark these fields as deprecated, indicating that the SDK should handle the required validation.
1 parent c8cd0b1 commit 24a2bd6

3 files changed

Lines changed: 635 additions & 310 deletions

File tree

‎docs/plugin-protocol/tfplugin6.1.proto‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
// Terraform Plugin RPC protocol version 6.1
2+
//
3+
// This file defines version 6.1 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+
int64 min_items = 4 [deprecated = true];
132+
int64 max_items = 5 [deprecated = true];
133+
}
134+
135+
// The version of the schema.
136+
// Schemas are versioned, so that providers can upgrade a saved resource
137+
// state when the schema is changed.
138+
int64 version = 1;
139+
140+
// Block is the top level configuration block for this schema.
141+
Block block = 2;
142+
}
143+
144+
service Provider {
145+
//////// Information about what a provider supports/expects
146+
rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response);
147+
rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response);
148+
rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response);
149+
rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response);
150+
rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response);
151+
152+
//////// One-time initialization, called before other functions below
153+
rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response);
154+
155+
//////// Managed Resource Lifecycle
156+
rpc ReadResource(ReadResource.Request) returns (ReadResource.Response);
157+
rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response);
158+
rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response);
159+
rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response);
160+
161+
rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response);
162+
163+
//////// Graceful Shutdown
164+
rpc StopProvider(StopProvider.Request) returns (StopProvider.Response);
165+
}
166+
167+
message GetProviderSchema {
168+
message Request {
169+
}
170+
message Response {
171+
Schema provider = 1;
172+
map<string, Schema> resource_schemas = 2;
173+
map<string, Schema> data_source_schemas = 3;
174+
repeated Diagnostic diagnostics = 4;
175+
Schema provider_meta = 5;
176+
}
177+
}
178+
179+
message ValidateProviderConfig {
180+
message Request {
181+
DynamicValue config = 1;
182+
}
183+
message Response {
184+
repeated Diagnostic diagnostics = 2;
185+
}
186+
}
187+
188+
message UpgradeResourceState {
189+
message Request {
190+
string type_name = 1;
191+
192+
// version is the schema_version number recorded in the state file
193+
int64 version = 2;
194+
195+
// raw_state is the raw states as stored for the resource. Core does
196+
// not have access to the schema of prior_version, so it's the
197+
// provider's responsibility to interpret this value using the
198+
// appropriate older schema. The raw_state will be the json encoded
199+
// state, or a legacy flat-mapped format.
200+
RawState raw_state = 3;
201+
}
202+
message Response {
203+
// new_state is a msgpack-encoded data structure that, when interpreted with
204+
// the _current_ schema for this resource type, is functionally equivalent to
205+
// that which was given in prior_state_raw.
206+
DynamicValue upgraded_state = 1;
207+
208+
// diagnostics describes any errors encountered during migration that could not
209+
// be safely resolved, and warnings about any possibly-risky assumptions made
210+
// in the upgrade process.
211+
repeated Diagnostic diagnostics = 2;
212+
}
213+
}
214+
215+
message ValidateResourceConfig {
216+
message Request {
217+
string type_name = 1;
218+
DynamicValue config = 2;
219+
}
220+
message Response {
221+
repeated Diagnostic diagnostics = 1;
222+
}
223+
}
224+
225+
message ValidateDataResourceConfig {
226+
message Request {
227+
string type_name = 1;
228+
DynamicValue config = 2;
229+
}
230+
message Response {
231+
repeated Diagnostic diagnostics = 1;
232+
}
233+
}
234+
235+
message ConfigureProvider {
236+
message Request {
237+
string terraform_version = 1;
238+
DynamicValue config = 2;
239+
}
240+
message Response {
241+
repeated Diagnostic diagnostics = 1;
242+
}
243+
}
244+
245+
message ReadResource {
246+
message Request {
247+
string type_name = 1;
248+
DynamicValue current_state = 2;
249+
bytes private = 3;
250+
DynamicValue provider_meta = 4;
251+
}
252+
message Response {
253+
DynamicValue new_state = 1;
254+
repeated Diagnostic diagnostics = 2;
255+
bytes private = 3;
256+
}
257+
}
258+
259+
message PlanResourceChange {
260+
message Request {
261+
string type_name = 1;
262+
DynamicValue prior_state = 2;
263+
DynamicValue proposed_new_state = 3;
264+
DynamicValue config = 4;
265+
bytes prior_private = 5;
266+
DynamicValue provider_meta = 6;
267+
}
268+
269+
message Response {
270+
DynamicValue planned_state = 1;
271+
repeated AttributePath requires_replace = 2;
272+
bytes planned_private = 3;
273+
repeated Diagnostic diagnostics = 4;
274+
}
275+
}
276+
277+
message ApplyResourceChange {
278+
message Request {
279+
string type_name = 1;
280+
DynamicValue prior_state = 2;
281+
DynamicValue planned_state = 3;
282+
DynamicValue config = 4;
283+
bytes planned_private = 5;
284+
DynamicValue provider_meta = 6;
285+
}
286+
message Response {
287+
DynamicValue new_state = 1;
288+
bytes private = 2;
289+
repeated Diagnostic diagnostics = 3;
290+
}
291+
}
292+
293+
message ImportResourceState {
294+
message Request {
295+
string type_name = 1;
296+
string id = 2;
297+
}
298+
299+
message ImportedResource {
300+
string type_name = 1;
301+
DynamicValue state = 2;
302+
bytes private = 3;
303+
}
304+
305+
message Response {
306+
repeated ImportedResource imported_resources = 1;
307+
repeated Diagnostic diagnostics = 2;
308+
}
309+
}
310+
311+
message ReadDataSource {
312+
message Request {
313+
string type_name = 1;
314+
DynamicValue config = 2;
315+
DynamicValue provider_meta = 3;
316+
}
317+
message Response {
318+
DynamicValue state = 1;
319+
repeated Diagnostic diagnostics = 2;
320+
}
321+
}

0 commit comments

Comments
 (0)