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  }