diff --git a/network-poc/static/avatars/gecko_notext.png b/network-poc/static/avatars/gecko_notext.png new file mode 100644 index 0000000..8968876 Binary files /dev/null and b/network-poc/static/avatars/gecko_notext.png differ diff --git a/network-poc/static/docs/README.md b/network-poc/static/docs/README.md new file mode 100644 index 0000000..c783ed0 --- /dev/null +++ b/network-poc/static/docs/README.md @@ -0,0 +1,43 @@ +# OpenTofu Core Codebase Documentation + +This directory contains some documentation about the OpenTofu Core codebase, +aimed at readers who are interested in making code contributions. + +If you're looking for information on _using_ OpenTofu, please instead refer +to [the main OpenTofu CLI documentation](https://opentofu.org/docs/cli/index.html). + +## OpenTofu Core Architecture Documents + +* [OpenTofu Core Architecture Summary](./architecture.md): an overview of the + main components of OpenTofu Core and how they interact. This is the best + starting point if you are diving in to this codebase for the first time. + +* [Resource Instance Change Lifecycle](./resource-instance-change-lifecycle.md): + a description of the steps in validating, planning, and applying a change + to a resource instance, from the perspective of the provider plugin RPC + operations. This may be useful for understanding the various expectations + OpenTofu enforces about provider behavior, either if you intend to make + changes to those behaviors or if you are implementing a new OpenTofu plugin + SDK and so wish to conform to them. + + (If you are planning to write a new provider using the _official_ SDK then + please refer to [the Extend documentation](https://github.com/hashicorp/terraform-docs-common) + instead; it presents similar information from the perspective of the SDK + API, rather than the plugin wire protocol.) + +* [Diagnostics](./diagnostics): how we report errors and warnings to end-users + in OpenTofu. + +* [Plugin Protocol](./plugin-protocol/): gRPC/protobuf definitions for the + plugin wire protocol and information about its versioning strategy. + + This documentation is for SDK developers, and is not necessary reading for + those implementing a provider using the official SDK. + +* [How OpenTofu Uses Unicode](./unicode.md): an overview of the various + features of OpenTofu that rely on Unicode and how to change those features + to adopt new versions of Unicode. + +## Contribution Guides + +* [Contributing to OpenTofu](../CONTRIBUTING.md): a complete guideline for those who want to contribute to this project. diff --git a/network-poc/static/docs/architecture.md b/network-poc/static/docs/architecture.md new file mode 100644 index 0000000..000d245 --- /dev/null +++ b/network-poc/static/docs/architecture.md @@ -0,0 +1,374 @@ +# OpenTofu Core Architecture Summary + +This document is a summary of the main components of OpenTofu Core and how +data and requests flow between these components. It's intended as a primer +to help navigate the codebase to dig into more details. + +We assume some familiarity with user-facing OpenTofu concepts like +configuration, state, CLI workflow, etc. The OpenTofu website has +documentation on these ideas. + +## OpenTofu Request Flow + +The following diagram shows an approximation of how a user command is +executed in OpenTofu: + +![OpenTofu Architecture Diagram, described in text below](./images/architecture-overview.png) + +Each of the different subsystems (solid boxes) in this diagram is described +in more detail in a corresponding section below. + +## CLI (`command` package) + +Each time a user runs the `tofu` program, aside from some initial +bootstrapping in the root package (not shown in the diagram) execution +transfers immediately into one of the "command" implementations in +[the `command` package](https://pkg.go.dev/github.com/opentofu/opentofu/internal/command). +The mapping between the user-facing command names and +their corresponding `command` package types can be found in the `commands.go` +file under the `cmd/tofu` directory (package `main`). + +The full flow illustrated above does not actually apply to _all_ commands, +but it applies to the main OpenTofu workflow commands `tofu plan` and +`tofu apply`, along with a few others. + +For these commands, the role of the command implementation is to read and parse +any command line arguments, command line options, and environment variables +that are needed for the given command and use them to produce a +[`backend.Operation`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/backend#Operation) +object that describes an action to be taken. + +An _operation_ consists of: + +* The action to be taken (e.g. "plan", "apply"). +* The name of the [workspace](https://opentofu.org/docs/language/state/workspaces) + where the action will be taken. +* Root module input variables to use for the action. +* For the "plan" operation, a path to the directory containing the configuration's root module. +* For the "apply" operation, the plan to apply. +* Various other less-common options/settings such as `-target` addresses, the +"force" flag, etc. + +The operation is then passed to the currently-selected +[backend](https://opentofu.org/docs/language/settings/backends/configuration). Each backend name +corresponds to an implementation of +[`backend.Backend`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/backend#Backend), using a +mapping table in +[the `backend/init` package](https://pkg.go.dev/github.com/opentofu/opentofu/internal/backend/init). + +Backends that are able to execute operations additionally implement +[`backend.Enhanced`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/backend#Enhanced); +the command-handling code calls `Operation` with the operation it has +constructed, and then the backend is responsible for executing that action. + +Backends that execute operations, however, do so as an architectural implementation detail and not a +general feature of backends. That is, the term 'backend' as a OpenTofu feature is used to refer to +a plugin that determines where OpenTofu stores its state snapshots - only the default `local`, `remote` and `cloud` backends perform operations. + +Thus, most backends do _not_ implement this interface, and so the `command` package wraps these +backends in an instance of +[`local.Local`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/backend/local#Local), +causing the operation to be executed locally within the `tofu` process itself. + +## Backends + +A _backend_ determines where OpenTofu should store its state snapshots. + +As described above, the `local` backend also executes operations on behalf of most other +backends. It uses a _state manager_ +(either +[`statemgr.Filesystem`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states/statemgr#Filesystem) if the +local backend is being used directly, or an implementation provided by whatever +backend is being wrapped) to retrieve the current state for the workspace +specified in the operation, then uses the _config loader_ to load and do +initial processing/validation of the configuration specified in the +operation. It then uses these, along with the other settings given in the +operation, to construct a +[`tofu.Context`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#Context), +which is the main object that actually performs OpenTofu operations. + +The `local` backend finally calls an appropriate method on that context to +begin execution of the relevant command, such as +[`Plan`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#Context.Plan) +or +[`Apply`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#Context.Apply), which in turn constructs a graph using a _graph builder_, +described in a later section. + +## Configuration Loader + +The top-level configuration structure is represented by model types in +[package `configs`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/configs). +A whole configuration (the root module plus all of its descendent modules) +is represented by +[`configs.Config`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/configs#Config). + +The `configs` package contains some low-level functionality for constructing +configuration objects, but the main entry point is in the sub-package +[`configload`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/configs/configload]), +via +[`configload.Loader`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/configs/configload#Loader). +A loader deals with all of the details of installing child modules +(during `tofu init`) and then locating those modules again when a +configuration is loaded by a backend. It takes the path to a root module +and recursively loads all of the child modules to produce a single +[`configs.Config`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/configs#Config) +representing the entire configuration. + +OpenTofu expects configuration files written in the OpenTofu language, which +is a DSL built on top of +[HCL](https://github.com/hashicorp/hcl). Some parts of the configuration +cannot be interpreted until we build and walk the graph, since they depend +on the outcome of other parts of the configuration, and so these parts of +the configuration remain represented as the low-level HCL types +[`hcl.Body`](https://pkg.go.dev/github.com/hashicorp/hcl/v2/#Body) +and +[`hcl.Expression`](https://pkg.go.dev/github.com/hashicorp/hcl/v2/#Expression), +allowing OpenTofu to interpret them at a more appropriate time. + +## State Manager + +A _state manager_ is responsible for storing and retrieving snapshots of the +[OpenTofu state](https://opentofu.org/docs/language/state/index.html) +for a particular workspace. Each manager is an implementation of +some combination of interfaces in +[the `statemgr` package](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states/statemgr), +with most practical managers implementing the full set of operations +described by +[`statemgr.Full`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states/statemgr#Full) +provided by a _backend_. The smaller interfaces exist primarily for use in +other function signatures to be explicit about what actions the function might +take on the state manager; there is little reason to write a state manager +that does not implement all of `statemgr.Full`. + +The implementation +[`statemgr.Filesystem`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states/statemgr#Filesystem) is used +by default (by the `local` backend) and is responsible for the familiar +`terraform.tfstate` local file that most OpenTofu users start with, before +they switch to [remote state](https://opentofu.org/docs/language/state/remote). +Other implementations of `statemgr.Full` are used to implement remote state. +Each of these saves and retrieves state via a remote network service +appropriate to the backend that creates it. + +A state manager accepts and returns a state snapshot as a +[`states.State`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states#State) +object. The state manager is responsible for exactly how that object is +serialized and stored, but all state managers at the time of writing use +the same JSON serialization format, storing the resulting JSON bytes in some +kind of arbitrary blob store. + +## Graph Builder + +A _graph builder_ is called by a +[`tofu.Context`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#Context) +method (e.g. `Plan` or `Apply`) to produce the graph that will be used +to represent the necessary steps for that operation and the dependency +relationships between them. + +In most cases, the +[vertices](https://en.wikipedia.org/wiki/Vertex_(graph_theory)) of OpenTofu's +graphs each represent a specific object in the configuration, or something +derived from those configuration objects. For example, each `resource` block +in the configuration has one corresponding +[`GraphNodeConfigResource`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#GraphNodeConfigResource) +vertex representing it in the "plan" graph. (OpenTofu Core uses terminology +inconsistently, describing graph _vertices_ also as graph _nodes_ in various +places. These both describe the same concept.) + +The [edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory_terms#edge) +in the graph represent "must happen after" relationships. These define the +order in which the vertices are evaluated, ensuring that e.g. one resource is +created before another resource that depends on it. + +Each operation has its own graph builder, because the graph building process +is different for each. For example, a "plan" operation needs a graph built +directly from the configuration, but an "apply" operation instead builds its +graph from the set of changes described in the plan that is being applied. + +The graph builders all work in terms of a sequence of _transforms_, which +are implementations of +[`tofu.GraphTransformer`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#GraphTransformer). +Implementations of this interface just take a graph and mutate it in any +way needed, and so the set of available transforms is quite varied. Some +important examples include: + +* [`ConfigTransformer`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#ConfigTransformer), + which creates a graph vertex for each `resource` block in the configuration. + +* [`StateTransformer`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#StateTransformer), + which creates a graph vertex for each resource instance currently tracked + in the state. + +* [`ReferenceTransformer`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#ReferenceTransformer), + which analyses the configuration to find dependencies between resources and + other objects and creates any necessary "happens after" edges for these. + +* [`ProviderTransformer`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#ProviderTransformer), + which associates each resource or resource instance with exactly one + provider configuration (implementing + [the inheritance rules](https://opentofu.org/docs/language/providers/)) + and then creates "happens after" edges to ensure that the providers are + initialized before taking any actions with the resources that belong to + them. + +There are many more different graph transforms, which can be discovered +by reading the source code for the different graph builders. Each graph +builder uses a different subset of these depending on the needs of the +operation that is being performed. + +The result of graph building is a +[`tofu.Graph`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#Graph), which +can then be processed using a _graph walker_. + +## Graph Walk + +The process of walking the graph visits each vertex of that graph in a way +which respects the "happens after" edges in the graph. The walk algorithm +itself is implemented in +[the low-level `dag` package](https://pkg.go.dev/github.com/opentofu/opentofu/internal/dag#AcyclicGraph.Walk) +(where "DAG" is short for [_Directed Acyclic Graph_](https://en.wikipedia.org/wiki/Directed_acyclic_graph)), in +[`AcyclicGraph.Walk`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/dag#AcyclicGraph.Walk). +However, the "interesting" OpenTofu walk functionality is implemented in +[`tofu.ContextGraphWalker`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#ContextGraphWalker), +which implements a small set of higher-level operations that are performed +during the graph walk: + +* `EnterPath` is called once for each module in the configuration, taking a + module address and returning a + [`tofu.EvalContext`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#EvalContext) + that tracks objects within that module. `tofu.Context` is the _global_ + context for the entire operation, while `tofu.EvalContext` is a + context for processing within a single module, and is the primary means + by which the namespaces in each module are kept separate. + +Each vertex in the graph is evaluated, in an order that guarantees that the +"happens after" edges will be respected. If possible, the graph walk algorithm +will evaluate multiple vertices concurrently. Vertex evaluation code must +therefore make careful use of concurrency primitives such as mutexes in order +to coordinate access to shared objects such as the `states.State` object. +In most cases, we use the helper wrapper +[`states.SyncState`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/states#SyncState) +to safely implement concurrent reads and writes from the shared state. + +## Vertex Evaluation + +The action taken for each vertex during the graph walk is called +_execution_. Execution runs a sequence of arbitrary actions that make sense +for a particular vertex type. + +For example, evaluation of a vertex representing a resource instance during +a plan operation would include the following high-level steps: + +* Retrieve the resource's associated provider from the `EvalContext`. This + should already be initialized earlier by the provider's own graph vertex, + due to the "happens after" edge between the resource node and the provider + node. + +* Retrieve from the state the portion relevant to the specific resource + instance being evaluated. + +* Evaluate the attribute expressions given for the resource in configuration. + This often involves retrieving the state of _other_ resource instances so + that their values can be copied or transformed into the current instance's + attributes, which is coordinated by the `EvalContext`. + +* Pass the current instance state and the resource configuration to the + provider, asking the provider to produce an _instance diff_ representing the + differences between the state and the configuration. + +* Save the instance diff as part of the plan that is being constructed by + this operation. + +Each execution step for a vertex is an implementation of +[`tofu.Execute`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#GraphNodeExecutable.Execute). +As with graph transforms, the behavior of these implementations varies widely: +whereas graph transforms can take any action against the graph, an `Execute` +implementation can take any action against the `EvalContext`. + +The implementation of `tofu.EvalContext` used in real processing +(as opposed to testing) is +[`tofu.BuiltinEvalContext`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#BuiltinEvalContext). +It provides coordinated access to plugins, the current state, and the current +plan via the `EvalContext` interface methods. + +In order to be executed, a vertex must implement +[`tofu.GraphNodeExecutable`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#GraphNodeExecutable), +which has a single `Execute` method that handles. There are numerous `Execute` +implementations with different behaviors, but some prominent examples are: + +* [NodePlannableResource.Execute](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#NodePlannableResourceInstance.Execute), which handles the `plan` operation. + +* [`NodeApplyableResourceInstance.Execute`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#NodeApplyableResourceInstance.Execute), which handles the main `apply` operation. + +* [`NodeDestroyResourceInstance.Execute`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#EvalWriteState), which handles the main `destroy` operation. + +A vertex must complete successfully before the graph walk will begin evaluation +for other vertices that have "happens after" edges. Evaluation can fail with one +or more errors, in which case the graph walk is halted and the errors are +returned to the user. + +### Expression Evaluation + +An important part of vertex evaluation for most vertex types is evaluating +any expressions in the configuration block associated with the vertex. This +completes the processing of the portions of the configuration that were not +processed by the configuration loader. + +The high-level process for expression evaluation is: + +1. Analyze the configuration expressions to see which other objects they refer + to. For example, the expression `aws_instance.example[1]` refers to one of + the instances created by a `resource "aws_instance" "example"` block in + configuration. This analysis is performed by + [`lang.References`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#References), + or more often one of the helper wrappers around it: + [`lang.ReferencesInBlock`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#ReferencesInBlock) + or + [`lang.ReferencesInExpr`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#ReferencesInExpr) + +1. Retrieve from the state the data for the objects that are referred to and + create a lookup table of the values from these objects that the + HCL evaluation code can refer to. + +1. Prepare the table of built-in functions so that HCL evaluation can refer to + them. + +1. Ask HCL to evaluate each attribute's expression (a + [`hcl.Expression`](https://pkg.go.dev/github.com/hashicorp/hcl/v2/#Expression) + object) against the data and function lookup tables. + +In practice, steps 2 through 4 are usually run all together using one +of the methods on [`lang.Scope`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#Scope); +most commonly, +[`lang.EvalBlock`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#Scope.EvalBlock) +or +[`lang.EvalExpr`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/lang#Scope.EvalExpr). + +Expression evaluation produces a dynamic value represented as a +[`cty.Value`](https://pkg.go.dev/github.com/zclconf/go-cty/cty#Value). +This Go type represents values from the OpenTofu language and such values +are eventually passed to provider plugins. + +### Sub-graphs + +Some vertices have a special additional behavior that happens after their +evaluation steps are complete, where the vertex implementation is given +the opportunity to build another separate graph which will be walked as part +of the evaluation of the vertex. + +The main example of this is when a `resource` block has the `count` argument +set. In that case, the plan graph initially contains one vertex for each +`resource` block, but that graph then _dynamically expands_ to have a sub-graph +containing one vertex for each instance requested by the count. That is, the +sub-graph of `aws_instance.example` might contain vertices for +`aws_instance.example[0]`, `aws_instance.example[1]`, etc. This is necessary +because the `count` argument may refer to other objects whose values are not +known when the main graph is constructed, but become known while evaluating +other vertices in the main graph. + +This special behavior applies to vertex objects that implement +[`tofu.GraphNodeDynamicExpandable`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tofu#GraphNodeDynamicExpandable). +Such vertices have their own nested _graph builder_, _graph walk_, +and _vertex evaluation_ steps, with the same behaviors as described in these +sections for the main graph. The difference is in which graph transforms +are used to construct the graph and in which evaluation steps apply to the +nodes in that sub-graph. diff --git a/network-poc/static/docs/destroying.md b/network-poc/static/docs/destroying.md new file mode 100644 index 0000000..2a0fbcd --- /dev/null +++ b/network-poc/static/docs/destroying.md @@ -0,0 +1,361 @@ +# OpenTofu Core Resource Destruction Notes + +This document intends to describe some of the details and complications +involved in the destruction of resources. It covers the ordering defined for +related create and destroy operations, as well as changes to the lifecycle +ordering imposed by `create_before_destroy`. It is not intended to enumerate +all possible combinations of dependency ordering, only to outline the basics +and document some of the more complicated aspects of resource destruction. + +The graph diagrams here will continue to use the inverted graph structure used +internally by OpenTofu, where edges represent dependencies rather than order +of operations. + +## Simple Resource Creation + +In order to describe resource destruction, we first need to create the +resources and define their order. The order of creation is that which fulfills +the dependencies for each resource. In this example, `A` has no dependencies, +`B` depends on `A`, and `C` depends on `B`, and transitively depends on `A`. + +![Simple Resource Creation](./images/simple_create.png) + + +Order of operations: +1. `A` is created +1. `B` is created +1. `C` is created + +## Resource Updates + +An existing resource may be updated with references to a newly created +resource. The ordering here is exactly the same as one would expect for +creation. + +![Simple Resource Updates](./images/simple_update.png) + + +Order of operations: +1. `A` is created +1. `B` is created +1. `C` is created + +## Simple Resource Destruction + +The order for destroying resource is exactly the inverse used to create them. +This example shows the graph for the destruction of the same nodes defined +above. While destroy nodes will not contain attribute references, we will +continue to use the inverted edges showing dependencies for destroy, so the +operational ordering is still opposite the flow of the arrows. + +![Simple Resource Destruction](./images/simple_destroy.png) + + +Order of operations: +1. `C` is destroyed +1. `B` is destroyed +1. `A` is Destroyed + +## Resource Replacement + +Resource replacement is the logical combination of the above scenarios. Here we +will show the replacement steps involved when `B` depends on `A`. + +In this first example, we simultaneously replace both `A` and `B`. Here `B` is +destroyed before `A`, then `A` is recreated before `B`. + +![Replace All](./images/replace_all.png) + + +Order of operations: +1. `B` is destroyed +1. `A` is destroyed +1. `A` is created +1. `B` is created + + +This second example replaces only `A`, while updating `B`. Resource `B` is only +updated once `A` has been destroyed and recreated. + +![Replace Dependency](./images/replace_one.png) + + +Order of operations: +1. `A` is destroyed +1. `A` is created +1. `B` is updated + + +While the dependency edge from `B update` to `A destroy` isn't necessary in +these examples, it is shown here as an implementation detail which will be +mentioned later on. + +A final example based on the replacement graph; starting with the above +configuration where `B` depends on `A`. The graph is reduced to an update of +`A` while only destroying `B`. The interesting feature here is the remaining +dependency of `A update` on `B destroy`. We can derive this ordering of +operations from the full replacement example above, by replacing `A create` +with `A update` and removing the unused nodes. + +![Replace All](./images/destroy_then_update.png) + +## Create Before Destroy + +Currently, the only user-controllable method for changing the ordering of +create and destroy operations is with the `create_before_destroy` resource +`lifecycle` attribute. This has the obvious effect of causing a resource to be +created before it is destroyed when replacement is required, but has a couple +of other effects we will detail here. + +Taking the previous replacement examples, we can change the behavior of `A` to +be that of `create_before_destroy`. + +![Replace all, dependency is create_before_destroy](./images/replace_all_cbd_dep.png) + + + +Order of operations: +1. `B` is destroyed +2. `A` is created +1. `B` is created +1. `A` is destroyed + +Note that in this first example, the creation of `B` is inserted in between the +creation of `A` and the destruction of `A`. This becomes more important in the +update example below. + + +![Replace dependency, dependency is create_before_destroy](./images/replace_dep_cbd_dep.png) + + +Order of operations: +1. `A` is created +1. `B` is updated +1. `A` is destroyed + +Here we can see clearly how `B` is updated after the creation of `A` and before +the destruction of the _deposed_ resource `A`. (The prior resource `A` is +sometimes referred to as "deposed" before it is destroyed, to disambiguate it +from the newly created `A`.) This ordering is important for resource that +"register" other resources, and require updating before the dependent resource +can be destroyed. + +The transformation used to create these graphs is also where we use the extra +edges mentioned above connecting `B` to `A destroy`. The algorithm to change a +resource from the default ordering to `create_before_destroy` simply inverts +any incoming edges from other resources, which automatically creates the +necessary dependency ordering for dependent updates. This also ensures that +reduced versions of this example still adhere to the same ordering rules, such +as when the dependency is only being removed: + +![Update a destroyed create_before_destroy dependency](./images/update_destroy_cbd.png) + + +Order of operations: +1. `B` is updated +1. `A` is destroyed + +### Forced Create Before Destroy + +In the previous examples, only resource `A` was being used as is it were +`create_before_destroy`. The minimal graphs used show that it works in +isolation, but that is only when the `create_before_destroy` resource has no +dependencies of it own. When a `create_before_resource` depends on another +resource, that dependency is "infected" by the `create_before_destroy` +lifecycle attribute. + +This example demonstrates why forcing `create_before_destroy` is necessary. `B` +has `create_before_destroy` while `A` does not. If we only invert the ordering +for `B`, we can see that results in a cycle. + +![Incorrect create_before_destroy replacement](./images/replace_cbd_incorrect.png) + + +In order to resolve these cycles, all resources that precede a resource +with `create_before_destroy` must in turn be handled in the same manner. +Reversing the incoming edges to `A destroy` resolves the problem: + +![Correct create_before_destroy replacement](./images/replace_all_cbd.png) + + +Order of operations: +1. `A` is created +1. `B` is created +1. `B` is destroyed +1. `A` is destroyed + +This also demonstrates why `create_before_destroy` cannot be overridden when +it is inherited; changing the behavior here isn't possible without removing +the initial reason for `create_before_destroy`; otherwise cycles are always +introduced into the graph. diff --git a/network-poc/static/docs/diagnostics.md b/network-poc/static/docs/diagnostics.md new file mode 100644 index 0000000..46a5ffe --- /dev/null +++ b/network-poc/static/docs/diagnostics.md @@ -0,0 +1,495 @@ +# OpenTofu Diagnostics Guide + +"Diagnostics" is the general term we use to describe the error and warning +messages that OpenTofu returns when there are problems with the configuration, +or when interactions with external systems fail. + +This document is an overview of how we typically use diagnostics in OpenTofu. +It includes both some technical information about how we represent diagnostics +in code, and some more subjective information about the writing style we most +often use in diagnostic messages. + +## Diagnostics in Code + +Diagnostics are modelled using the types from +[the `tfdiags` package](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags). + +In particular: +- [`tfdiags.Diagnostics`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostics) + represents a set of zero or more diagnostics. + + A total lack of diagnostics is usually represented by a `nil` value of this + type. + + When constructing sets of diagnostics to return we typically don't worry + about the order they are returned in, even though we return them using a + slice type. The UI-layer code uses + [`tfdiags.Diagnostics.Sort`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostics.Sort) + to place all of the collected diagnostics into a predictable order before + rendering them, and so that function effectively turns the set of + diagnostics into an ordered list of diagnostics _just in time_. + +- [`tfdiags.Diagnostic`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostic) + is an interface type that all diagnostic values implement. + + In practice values of this type are often created automatically as an + implementation detail of [`Diagnostics.Append`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostics.Append), + which accepts various types that _don't_ directly implement + `Diagnostic` and then automatically wraps them in a type that does. + In particular: + + - We often use [`hcl.Diagnostic`](https://pkg.go.dev/github.com/hashicorp/hcl/v2#Diagnostic) + to describe problems related to the configuration or operations that are + strongly related to parts of the configuration, because it is the most + fully-fledged type of diagnostic we allow including support for source + ranges and relevant expressions as described later. + + It's also acceptable to append a whole `hcl.Diagnostics` (the HCL + equivalent of `tfdiags.Diagnostics`) in which case each diagnostic + will be wrapped and appended in turn. This is common when calling + HCL's own functions and passing on its diagnostics verbatim. + - Normal `error` values can be appended to a `tfdiags.Diagnostics`, but + that's mainly for historical reasons -- adapting code that was present + before the diagnostic models were added -- and should not be used in new + code because it typically results in low-quality diagnostics that don't + meet the style guidelines later in this document. + + One exception is for "should never happen" cases: we sometimes use + `error` directly in that case to avoid overwhelming the surrounding + code with the construction of a full diagnostic. + + Package `tfdiags` also includes some functions for constructing other kinds + of diagnostics, including: + + - [`tfdiags.Sourceless`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Sourceless) + is good for diagnostics that don't relate to any part of the configuration, + such as when reporting incorrect usage of a command line argument. + - [`tfdiags.AttributeValue`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#AttributeValue) and + [`tfdiags.WholeContainingBody`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#WholeContainingBody) + produce special "contextual diagnostics" that must be transformed by + calling [`InConfigBody`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostics.InConfigBody) + on the resulting `Diagnostics` value. This is a special mechanism used + when the subsystem generating the diagnostic does not have direct access + to the configuration itself, such as when a provider returns a diagnostic + via the provider wire protocol. +- [`tfdiags.Severity`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Severity) + (and its HCL equivalent [`hcl.DiagnosticSeverity`](https://pkg.go.dev/github.com/hashicorp/hcl/v2#DiagnosticSeverity)) + are how we distinguish between "error" and "warning" diagnostics. + + The `tfdiags.Diagnostics.HasErrors` method returns true if the diagnostics + contains at least one with the severity `tfdiags.Error`. + +The most common pattern for handling diagnostics in code is: +1. Declare `var diags tfdiags.Diagnostics` at the very start of a function. +2. During the function's body, whenever calling another function that might + produce its own diagnostics, capture them into a separate variable + (often called `moreDiags`, or `hclDiags` if the return type is + `hcl.Diagnostics`) and then immediately append them to the main `diags` + using `tfdiags.Diagnostics.Append`. + + If subsequent code depends on the success of the call, check + `moreDiags.HasErrors()` (or similar) and return early if it returns `true`. +3. If the function generates any diagnostics of its own, append them directly + to `diags`. +4. At all exit points of the function, return `diags` regardless of whether + it has been assigned to or whether it contains errors. This ensures that + we always return any warnings that might have been produced and avoids + the risk of missing certain return paths under future maintenance if we + introduce additional diagnostics later. + +Here's a code-example version of the above advice: + +```go +func Example() (anything, tfdiags.Diagnostics) { + var diags tfdiags.Diagnostics + + somethingElse, moreDiags := otherFunction() + diags = diags.Append(moreDiags) + if moreDiags.HasErrors() { + // NOTE: it isn't _always_ necessary to return immediately when there + // are errors, as long as the callee clearly documents what it + // guarantees about an errored result and the caller is able to + // work within those limitations. Collecting multiple errors to + // return together is often desirable. + // + // If the caller cannot continue at all though, or if continuing is + // likely to cause redundant errors that just restate the same problem + // in more confusing terms, then... + return nil, diags + } + if isProblematic(somethingElse) { + // A function might need to generate its own diagnostics if it detects + // a problem directly. + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + // ... + }) + return nil, diags + } + + // ... + + // The final return statement should include diags even if no errors + // were detected along the way, because it might contain warnings. + return something, diags +} +``` + +Some functions diverge from this pattern for special reasons, such as capturing +multiple sets of child function diagnostics and then using some logic to decide +which ones to append, or processing multiple items in a loop and appending +new diagnostics for each iteration. The above is just a general example of the +most common case, not a fixed template to follow in all cases. + +## Information in a Diagnostic + +The general model of `tfdiags.Diagnostic` has the following parts, though not +all implementations of the interface make use of all of them: + +- Severity: either `tfdiags.Error` or `tfdiags.Warning`. +- Description: the main human-readable text describing the problem. This + has the following fields: + + - Summary: A short, terse description of the general type of problem + that has occurred. + - Detail: A longer description of the problem, sometimes including multiple + paragraphs of information. + - Address: The address of some object that the error relates to, which + is most often a resource instance address. + + OpenTofu does not currently have a localized UI, so built-in diagnostics + always have their summary and detail written in US English. There's more + subjective guidance about the content of these fields in sections below. +- Source location information: optional references to parts of the configuration + that the problem relates to. This has the following fields: + + - Subject: source range for the part of the configuration that caused the + problem or that the problem is directly about. + - Context: optional source range of a larger section of configuration that + might make the cause of the problem easier to quickly understand if + included in the diagnostic message. The Context source range must always + contain the Subject source range within it. + + The UI uses the context and subject together to display a source code + snippet. The lines of code included in the snippet cover both the context + and the subject, and then the subject itself is rendered with an underline + if we're rendering into a terminal that supports that style. + + We don't use "context" very often, but it can be useful if the problem + we're describing is that just one part of a larger source element is + problematic. For example, if one of the operands to the `+` operator + isn't a number then that operand would be the "subject" but the entire + addition operation could be returned as "context", so that both of the + operands and the `+` symbol will definitely be included in the rendered + diagnostic too. +- Expression-related information: optional information about an expression whose + evaluation cause the problem. This has the following fields: + + - Expression: The `hcl.Expression` representing the expression itself. + - EvalContext: The `hcl.EvalContext` that the expression was being evaluated + in. + + The diagnostic renderer for the UI uses this information, when available, + to offer some extra hints about the values of any symbols that were used + in the expression, because it's often the dynamic values that cause a + problem, rather than the syntax used to obtain them. +- Extra info: this is a rather underspecified collection of assorted other + information that's only relevant in very specific contexts. Refer to the + `tfdiags` package documentation for more information. + + There's _some_ guidance on this later in this document, but it's focused + only on a few main cases. + +## Diagnostic Description Writing Style + +Although there is some variation in diagnostic writing style, particularly in +parts of the system like state storage backends which were originally written by +third-parties, most of the _built-in_ diagnostics follow a relatively consistent +writing style that is in turn based on the writing style used by HCL itself in +its own diagnostics, because HCL and OpenTofu diagnostics often mix together +in the same set of problems. + +The "summary" should typically be a very short and concise description of +what was wrong and what was wrong about it. Our summaries typically don't +include any user-chosen information such as symbol names, because that means a +particular kind of problem is always described using the same text and so +readers can become familiar enough with the summaries of problems they see +frequently to skip reading the rest of the diagnostic when skimming. + +The following are some real examples of summaries currently used across both +HCL and OpenTofu: + +- Unsupported operator +- Duplicate argument +- Invalid index +- Unexpected end of template +- Invalid template interpolation value +- Invalid default value for variable +- Required variable not set +- Invalid "count" attribute + +The "detail" text is where we tend to put most of the information, and so +there's a lot more variation here but ideally a good diagnostic detail +should mention the following information, usually in the following order: + +- What was wrong and what was wrong about it: similar to the summary but this + time including information about specifically what was wrong, such as the + name of the input variable whose default value was invalid. +- Why the situation is problematic, if knowing that relies on some + characteristic of OpenTofu's design that might not be obvious to a newcomer. +- What should be done to fix it, or (if it's unclear what the author's intention + was) a question-sentence that implies a _possible_ solution, often starting + with the words "Did you mean" and ending with a question mark. + +While the summary message is often terse and uses only minimal punctuation, +the detail message should always be written in full sentences including +end-of-sentence punctuation (`.`, `?`). If "what was wrong about it" is +coming from the string representation of an `error` value, we typically +present it with a prefix ending with a colon and then append a period `.` +after the error string, and format the error itself using `tfdiags.FormatError`, +like this: + +```go + Detail: fmt.Sprintf("Unsuitable value for thingy: %s.", tfdiags.FormatError(err)) +``` + +If the second and third items in the above take more than a few words, it's +helpful to split them into their own paragraphs for easier scanning. When +writing multiple paragraphs in a detail message they should be separated by +`\n\n` -- two newline characters. + +In many cases our diagnostics only include a subset of this information because +either the reason why it's problematic is relatively clear or because we don't +have any specific suggestion for how to solve the problem, but the following +is an example of a real diagnostic message from OpenTofu at the time of writing +this documentation which includes all of these parts: + +``` +Error: Invalid for_each argument + +The "for_each" map includes keys derived from resource attributes that cannot +be determined until apply, and so OpenTofu cannot determine the full set of keys +that will identify the instances of this resource. + +When working with unknown values in for_each, it's better to define the map keys +statically in your configuration and place apply-time results only in the map +values. + +Alternatively, you could use the planning option -exclude=aws_instance.example +to first apply without this object, and then apply normally to converge. +``` + +The text immediately after "Error:" above is the summary for this diagnostic. +The paragraphs that follow are all a single "detail" string. + +That was a particularly extreme diagnostic message with lots of information to +communicate. Most diagnostics are not so complicated; the following is an +example with less information to communicate: + +``` +Error: Invalid value for input variable + +The given value is not suitable for var.example declared +at example.tf:12,1: a string is required. +``` + +This example also illustrates a situation where there are two different source +locations that could be relevant: the input variable's declaration or the +expression that's used to define its value. Because this message is talking +about a problem with the _value_, the diagnostic should have the source +"Subject" set to the expression that defined it, but it also mentions the +location of the declaration as part of the detail text as some additional +context. + +Some other notes about some other specific situations that arise sometimes: + +- If a diagnostic message includes a suggestion for a shell command to run + or a URL to visit for more information, use a paragraph that ends with a + colon, followed by a single newline, four spaces for indentation, and then the + command or URL: + + ``` + To view the root module output values, run: + tofu output + ``` + + The goal of this formatting is to make it very clear what part of the + message is intended to be copied and used elsewhere, by placing it on a + line of its own without any surrounding punctuation. The indented text + should ideally be formatted so that the user can copy it _verbatim_ into + whatever place it will be used. + + The diagnostic renderer also has a special case where it will not try to + word-wrap a line that begins with spaces, and so this layout has the + useful side-effect of avoiding introducing extra newline characters into + a command line that is intended to be copied. + +- There are some terminology choices we use to refer to some OpenTofu-specific + ideas and concepts that disagree slightly with terminology used in the code. + These differences are the result of learning from feedback from folks who + had been confused by the original terminology, even though the code still + often uses the original terminology: + + - Instead of referring to "unknown values" or "computed values" we say that + values are "known after apply" or "cannot be determined until apply". + - In HCL the word "variable" means anything that's available to refer to + in the current evaluation context, which is confusing because OpenTofu + itself uses that word to refer only to input variables. + + Sometimes messages are generated by HCL itself and so it's unavoidably + confusing, but when we're generating messages _inside OpenTofu_ we + use the two words "input variable" to refer to an input variable, + and "symbol" or "object" (depending on whether we're talking about + the name itself or what the name refers to) as the general word for + something you can refer to in an expression. + - For consistency with our use of "input variable" to distinguish from + HCL's more general meaning of "variable", we also tend to write + "local value" and "output value" when referring to those concepts, rather + than using the shorthands "locals" and "outputs". + - HCL distinguishes between "attributes" meaning the named keys inside an + object type, and "arguments" meaning the names used for individual + settings inside a configuration block. + + OpenTofu itself uses those words a little more interchangeably because + in _many_ cases the configuration arguments in a block directly + correspond to the attributes of an object created by evaluating that + block. + + However, if a particular error message is talking about a configuration + setting inside a block it's better to use "argument" rather than + "attribute" because that's then consistent with error messages that + HCL itself might generate. + + Go uses the term "field" to describe an element of a struct type, and + JavaScript and JSON use the word "property" to describe an element of + an object type. We don't use either of those words in OpenTofu: the + elements of an object are its _attributes_, and the settings available + in a configuration block are its _arguments_. The string values that + identify elements of a map are called "keys". + - The `cty` terminology "marks" or "value marks" refers to an implementation + detail that should never be mentioned directly in an error message. + + Instead, we use specific terminology related to what each mark type + is representing: "sensitive values", "ephemeral values", etc. + - `aws_instance` is an example of a "resource _type_", not of a "resource", + even though the provider protocol uses the single noun "resource" to refer + to both ideas. + + A "resource" is what's declared by a `resource`, `data`, or `ephemeral` + block. A "resource _instance_" is what such a block can declare zero + or more of, when using the `count`, `for_each`, or `enabled` arguments. + - Although there are certainly some historical diagnostic messages that + predate this adjustment of terminology, new error messages should use + "managed resource" to refer to the kind of resource that's declared + using a `resource` block, "data resource" for `data` blocks, and + "ephemeral resource" for an `ephemeral` block. + + In the code we refer to these three as "resource _modes_", but that is + internal terminology that should never appear in a diagnostic message. +- When a file or directory path appears as part of a diagnostic message, it + should typically be presented relative to the current working directory and + should use the syntax conventions of the platform where OpenTofu is running. + + In particular, we return paths using backslashes as the separator when we + are running on Windows, but normal slashes otherwise. Using the Go + `filepath` package is a good way to get this right, though you might need + to add some complexity to your tests to make them pass on all platforms. +- If an error message is describing a "should never happen" case, we typically + end the detail string with the sentence "This is a bug in OpenTofu.". This + hopefully prompts the reader that this wasn't directly caused by something + they did, and so they should probably open a bug report in the + OpenTofu repository instead of just trying to solve it themselves. + + For this kind of error message we often relax our preference against + mentioning implementation details in the error message, because the most + likely next step is for the user to copy-paste the entire message into their + bug report text and so the final reader of the message is OpenTofu + maintainers rather than OpenTofu users. + + For example, it can be okay to use internal terminology like "cty marks" and + use the `GoString` representations of values in a "This is a bug in + OpenTofu" detail message, if that's the most concise way to capture the + information the OpenTofu maintainers would need to debug the problem. + +## Diagnostics caused by unknown or sensitive values + +When a diagnostic has expression information associated with it, the diagnostic +renderer for the UI includes some additional information about the values +that were in scope, like this: + +``` + var.greeting is "Hello" + var.items is list of string with 5 elements +``` + +By default, this renderer will not mention any symbol which refers to an unknown +or sensitive value. That was not historically true: originally, this could +say something like "var.example is a string, known only after apply". + +Those who are less familiar with these concepts often misunderstood the +"known only after apply" part of the message as being _the problem itself_, +rather than just context to help diagnose the problem, and so the UI no longer +mentions "unknown-ness" or "sensitive-ness" in most cases. + +However, there are some diagnostics messages that _are_ directly caused by the +presence of an unknown or sensitive value, in which case it's helpful to +mention that in the summary of values that were in scope. + +To allow for this, we set the "extra info" field of a diagnostic to contain +an implementation of one of the following interfaces: + +- [`tfdiags.DiagnosticExtraBecauseUnknown`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#DiagnosticExtraBecauseUnknown) + for a problem that's caused by an unknown value. + + (Remember that the _text_ of the error message should refer to this as "known + only after apply", or similar.) +- [`tfdiags.DiagnosticExtraBecauseSensitive`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#DiagnosticExtraBecauseSensitive) + for situations where a sensitive value was used in a location that OpenTofu + cannot permit it, such as in the instance key of a resource instance. + +These extra markers should be used only when mentioning the unknown or sensitive +values in the diagnostic message is likely to help with debugging a problem. +If the problem is not directly caused by unknown or sensitive values then +neither of these should be used, to avoid creating a distracting +[red herring](https://en.wikipedia.org/wiki/Red_herring) for the reader. + +## Consolidation of Diagnostics + +The UI layer has some special rules for finding sets of similar diagnostics +and showing them as just a single diagnostic referring to the first example +of a problem, with a short extra note about how many other similar diagnostics +there are. + +``` +(and 2 similar warnings elsewhere) +``` + +The main implementation of this behavior is in +[`tfdiags.Diagnostics.Consolidate`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Diagnostics.Consolidate), +but we allow end-users to customize (using command line options) whether this +consolidation applies to errors or warnings separately. By default, we +consolidate only warnings. + +For a severity that is subject to consolidation, the main behavior is to group +together diagnostics that have the same "summary" text, and this is part of +why we tend to use terse, fixed strings in the summary field. + +There are two extra mechanisms for customizing this behavior for specific +diagnostic messages: + +- If the "extra info" of a diagnostic contains an implementation of + [`tfdiags.DiagnosticExtraDoNotConsolidate`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#DiagnosticExtraDoNotConsolidate) + then that diagnostic is not eligible for consolidation at all, regardless + of how similar it might be to other diagnostics in the same set. +- If the "extra info" of a diagnostic contains an implementation of + [`tfdiags.Keyable`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tfdiags#Keyable) + then the string returned by its `ExtraInfoKey` method is used _in addition to_ + the summary text for deciding what to consolidate. + + For example, if there were three warnings with the same summary text but + two of them have the same `ExtraInfoKey` and the third has a different + one then only the first two would be able to consolidate. + + The `ExtraInfoKey` is an internal key used for comparison only and is never + exposed in the UI, so it can be set to whatever makes sense to define + separate consolidation groups for diagnostics with a specific summary. diff --git a/network-poc/static/docs/glossary.md b/network-poc/static/docs/glossary.md new file mode 100644 index 0000000..b94cd0f --- /dev/null +++ b/network-poc/static/docs/glossary.md @@ -0,0 +1,78 @@ +# OpenTofu glossary +This document is intended for anyone who wants to gain more knowledge about the terms and vocabulary used to talk about different concepts in OpenTofu. + +> [!NOTE] +> This was created with the intent of gathering more knowledge over time. +> The state that you find this in right now could be incomplete. +> Once you discover and learn about a new concept that would benefit others, +> feel free to open a PR to update this. + +> [!NOTE] +> When adding new content to this document, try to place it in such a way to match the alphabetical order of the already existing content. +> +> Optionally, also add a reference link if possible (GitHub conversation, issue, other docs, etc). + +## OpenTofu +### Attribute/argument/field +* Attribute - a named key inside an object type. +* Argument - a name used for an individual setting inside a configuration block. + +It is recommended to avoid using popular programming language terms such as "field" or "property" to describe an element of an object in OpenTofu. + +Reference: [link](./diagnostics.md#diagnostic-description-writing-style) + +### Data sources/data resource +* Data source - the remote thing that the data resource reads from. +* Data resource - refers to a block of type `data`, and the associated object it declares. +* Data resource type - is what is represented by the first label in a `data` block header, and the associated declarations and code for it in the provider plugin. + +Reference: [link](https://github.com/opentofu/opentofu/pull/3389#discussion_r2440264786) + +### Diagnostic +"Diagnostic" is the general term we use to describe the error or warning +message that OpenTofu returns when there are problems with the configuration, +or when interactions with external systems fail. + +Reference: [link](./diagnostics.md) + +### Mark/value mark +OpenTofu uses cty.Value to represent the result of expressions (and other data). +Occasionally, we will want to annotate that data with additional properties, without actually modifying the underlying value. +Marks are used for that purpose and are the preferred method of doing so with go-cty. + +### Resource/resource instance/resource type +* Resource - is what is declared by a `resource`, `data` or `ephemeral` block. +* Resource instance - is what such a block can declare zero or more of, when using the `count`, `for_each`, or `enabled` arguments. +* Resource type - the type of a "resource". E.g., `aws_instance` is a "resource type". + +It is recommended to use the following terms when discussing about "resource" blocks: +* managed resource - a block declared as `resource "type" "name" {}` +* data resource - a block declared as `data "type" "name" {}` +* ephemeral resource - a block declared as `ephemeral "type" "name" {}` + +Reference: [link](./diagnostics.md#diagnostic-description-writing-style) + +### Unknown value/Computed value +* Unknown value - Unknown values are the result of expressions that have unknown inputs. E.g.: a value that will not be known until a resource is created. + Right now the main source of this type of values is resources, but we are considering adding others like unknown inputs. + Another place where an unknown value can be encountered is from using some of the built-in functions like `timestamp`, `bcrypt` and `uuid`. +* Computed value - Computed is more of a resource specific concept that a provider can specify in its resource schema. + When set to true, the provider does not expect a value and may instead produce one that may or may not be unknown. + With other flags, the actual functionality is a bit more subtle. + +References: [link](https://github.com/opentofu/opentofu/blob/490762343322eff42c0586f7a4c267b579fe80ef/internal/configs/configschema/schema.go#L65), [link](https://github.com/opentofu/opentofu/blob/490762343322eff42c0586f7a4c267b579fe80ef/internal/lang/functions.go#L22) +## HCL +### Evaluation context (HCL) +A set of already known functions, input values, local values, resources, etc. that is used to evaluate an expression that can reference any of the concepts listed above. + +The list of concepts above, in the context of HCL evaluation, are called [variables](#variable-hcl). + +### Expression +An expression is any right hand side of an assignment that will be evaluated to generate the value that will be associated with key on the left hand side of the assignment. +The simplest expressions are just literal values, like "hello" or 5, but the OpenTofu language also allows more complex +expressions such as references to data exported by resources, arithmetic, conditional evaluation, and a number of built-in and provider-defined functions. + +Reference: [link](https://opentofu.org/docs/language/expressions/) + +### Variable (HCL) +Anything that's available to refer to in the current evaluation context. \ No newline at end of file diff --git a/network-poc/static/docs/images/architecture-overview.png b/network-poc/static/docs/images/architecture-overview.png new file mode 100644 index 0000000..146cc48 Binary files /dev/null and b/network-poc/static/docs/images/architecture-overview.png differ diff --git a/network-poc/static/docs/images/destroy_then_update.png b/network-poc/static/docs/images/destroy_then_update.png new file mode 100644 index 0000000..f4f3d20 Binary files /dev/null and b/network-poc/static/docs/images/destroy_then_update.png differ diff --git a/network-poc/static/docs/images/replace_all.png b/network-poc/static/docs/images/replace_all.png new file mode 100644 index 0000000..54d5ad6 Binary files /dev/null and b/network-poc/static/docs/images/replace_all.png differ diff --git a/network-poc/static/docs/images/replace_all_cbd.png b/network-poc/static/docs/images/replace_all_cbd.png new file mode 100644 index 0000000..da72fe4 Binary files /dev/null and b/network-poc/static/docs/images/replace_all_cbd.png differ diff --git a/network-poc/static/docs/images/replace_all_cbd_dep.png b/network-poc/static/docs/images/replace_all_cbd_dep.png new file mode 100644 index 0000000..98bdbde Binary files /dev/null and b/network-poc/static/docs/images/replace_all_cbd_dep.png differ diff --git a/network-poc/static/docs/images/replace_cbd_incorrect.png b/network-poc/static/docs/images/replace_cbd_incorrect.png new file mode 100644 index 0000000..72591d0 Binary files /dev/null and b/network-poc/static/docs/images/replace_cbd_incorrect.png differ diff --git a/network-poc/static/docs/images/replace_dep_cbd_dep.png b/network-poc/static/docs/images/replace_dep_cbd_dep.png new file mode 100644 index 0000000..35b7936 Binary files /dev/null and b/network-poc/static/docs/images/replace_dep_cbd_dep.png differ diff --git a/network-poc/static/docs/images/replace_one.png b/network-poc/static/docs/images/replace_one.png new file mode 100644 index 0000000..fe1aa1d Binary files /dev/null and b/network-poc/static/docs/images/replace_one.png differ diff --git a/network-poc/static/docs/images/resource-instance-change-lifecycle.png b/network-poc/static/docs/images/resource-instance-change-lifecycle.png new file mode 100644 index 0000000..b6cf16e Binary files /dev/null and b/network-poc/static/docs/images/resource-instance-change-lifecycle.png differ diff --git a/network-poc/static/docs/images/simple_create.png b/network-poc/static/docs/images/simple_create.png new file mode 100644 index 0000000..5c82954 Binary files /dev/null and b/network-poc/static/docs/images/simple_create.png differ diff --git a/network-poc/static/docs/images/simple_destroy.png b/network-poc/static/docs/images/simple_destroy.png new file mode 100644 index 0000000..be2e8fc Binary files /dev/null and b/network-poc/static/docs/images/simple_destroy.png differ diff --git a/network-poc/static/docs/images/simple_update.png b/network-poc/static/docs/images/simple_update.png new file mode 100644 index 0000000..ada18b2 Binary files /dev/null and b/network-poc/static/docs/images/simple_update.png differ diff --git a/network-poc/static/docs/images/update_destroy_cbd.png b/network-poc/static/docs/images/update_destroy_cbd.png new file mode 100644 index 0000000..2ad04c9 Binary files /dev/null and b/network-poc/static/docs/images/update_destroy_cbd.png differ diff --git a/network-poc/static/docs/planning-behaviors.md b/network-poc/static/docs/planning-behaviors.md new file mode 100644 index 0000000..0fcd0a9 --- /dev/null +++ b/network-poc/static/docs/planning-behaviors.md @@ -0,0 +1,294 @@ +# Planning Behaviors + +A key design tenet for OpenTofu is that any actions with externally-visible +side-effects should be carried out via the standard process of creating a +plan and then applying it. Any new features should typically fit within this +model. + +There are also some historical exceptions to this rule, which we hope to +supplement with plan-and-apply-based equivalents over time. + +This document describes the default planning behavior of OpenTofu in the +absence of any special instructions, and also describes the three main +design approaches we can choose from when modelling non-default behaviors that +require additional information from outside OpenTofu Core. + +This document focuses primarily on actions relating to _resource instances_, +because that is OpenTofu's main concern. However, these design principles can +potentially generalize to other externally-visible objects, if we can describe +their behaviors in a way comparable to the resource instance behaviors. + +This is developer-oriented documentation rather than user-oriented +documentation. See +[the main OpenTofu documentation](https://opentofu.org/docs) for +information on existing planning behaviors and other behaviors as viewed from +an end-user perspective. + +## Default Planning Behavior + +When given no explicit information to the contrary, OpenTofu Core will +automatically propose taking the following actions in the appropriate +situations: + +- **Create**, if either of the following are true: + - There is a `resource` block in the configuration that has no corresponding + managed resource in the prior state. + - There is a `resource` block in the configuration that is recorded in the + prior state but whose `count` or `for_each` argument (or lack thereof) + describes an instance key that is not tracked in the prior state. +- **Delete**, if either of the following are true: + - There is a managed resource tracked in the prior state which has no + corresponding `resource` block in the configuration. + - There is a managed resource tracked in the prior state which has a + corresponding `resource` block in the configuration _but_ its `count` + or `for_each` argument (or lack thereof) lacks an instance key that is + tracked in the prior state. +- **Update**, if there is a corresponding resource instance both declared in the + configuration (in a `resource` block) and recorded in the prior state + (unless it's marked as "tainted") but there are differences between the prior + state and the configuration which the corresponding provider doesn't + explicitly classify as just being normalization. +- **Replace**, if there is a corresponding resource instance both declared in + the configuration (in a `resource` block) and recorded in the prior state + _marked as "tainted"_. The special "tainted" status means that the process + of creating the object failed partway through and so the existing object does + not necessarily match the configuration, so OpenTofu plans to replace it + in order to ensure that the resulting object is complete. +- **Read**, if there is a `data` block in the configuration. + - If possible, OpenTofu will eagerly perform this action during the planning + phase, rather than waiting until the apply phase. + - If the configuration contains at least one unknown value, or if the + data resource directly depends on a managed resource that has any change + proposed elsewhere in the plan, OpenTofu will instead delay this action + to the apply phase so that it can react to the completion of modification + actions on other objects. +- **No-op**, to explicitly represent that OpenTofu considered a particular + resource instance but concluded that no action was required. + +The **Replace** action described above is really a sort of "meta-action", which +OpenTofu expands into separate **Create** and **Delete** operations. There are +two possible orderings, and the first one is the default planning behavior +unless overridden by a special planning behavior as described later. The +two possible lowerings of **Replace** are: +1. **Delete** then **Create**: first delete the existing object bound to an + instance, and then create a new object at the same address based on the + current configuration. +2. **Create** then **Delete**: mark the existing object bound to an instance as + "deposed" (still exists but not current), create a new current object at the + same address based on the current configuration, and then delete the deposed + object. + +## Special Planning Behaviors + +For the sake of this document, a "special" planning behavior is one where +OpenTofu Core will select a different action than the defaults above, +based on explicit instructions given either by a module author, an operator, +or a provider. + +There are broadly three different design patterns for special planning +behaviors, and so each "special" use-case will typically be met by one or more +of the following depending on which stakeholder is activating the behavior: + +- [Configuration-driven Behaviors](#configuration-driven-behaviors) are + activated by additional annotations given in the source code of a module. + + This design pattern is good for situations where the behavior relates to + a particular module and so should be activated for anyone using that + module. These behaviors are therefore specified by the module author, such + that any caller of the module will automatically benefit with no additional + work. +- [Provider-driven Behaviors](#provider-driven-behaviors) are activated by + optional fields in a provider's response when asked to help plan one of the + default actions given above. + + This design pattern is good for situations where the behavior relates to + the behavior of the remote system that a provider is wrapping, and so from + the perspective of a user of the provider the behavior should appear + "automatic". + + Because these special behaviors are activated by values in the provider's + response to the planning request from OpenTofu Core, behaviors of this + sort will typically represent "tweaks" to or variants of the default + planning behaviors, rather than entirely different behaviors. +- [Single-run Behaviors](#single-run-behaviors) are activated by explicitly + setting additional "plan options" when calling OpenTofu Core's plan + operation. + + This design pattern is good for situations where the direct operator of + OpenTofu needs to do something exceptional or one-off, such as when the + configuration is correct but the real system has become degraded or damaged + in a way that OpenTofu cannot automatically understand. + + However, this design pattern has the disadvantage that each new single-run + behavior type requires custom work in every wrapping UI or automaton around + OpenTofu Core, in order provide the user of that wrapper some way + to directly activate the special option, or to offer an "escape hatch" to + use OpenTofu CLI directly and bypass the wrapping automation for a + particular change. + +We've also encountered use-cases that seem to call for a hybrid between these +different patterns. For example, a configuration construct might cause OpenTofu +Core to _invite_ a provider to activate a special behavior, but let the +provider make the final call about whether to do it. Or conversely, a provider +might advertise the possibility of a special behavior but require the user to +specify something in the configuration to activate it. The above are just +broad categories to help us think through potential designs; some problems +will require more creative combinations of these patterns than others. + +### Configuration-driven Behaviors + +Within the space of configuration-driven behaviors, we've encountered two +main sub-categories: +- Resource-specific behaviors, whose effect is scoped to a particular resource. + The configuration for these often lives inside the `resource` or `data` + block that declares the resource. +- Global behaviors, whose effect can span across more than one resource and + sometimes between resources in different modules. The configuration for + these often lives in a separate location in a module, such as a separate + top-level block which refers to other resources using the typical address + syntax. + +The following is a non-exhaustive list of existing examples of +configuration-driven behaviors, selected to illustrate some different variations +that might be useful inspiration for new designs: + +- The `ignore_changes` argument inside `resource` block `lifecycle` blocks + tells OpenTofu that if there is an existing object bound to a particular + resource instance address then OpenTofu should ignore the configured value + for a particular argument and use the corresponding value from the prior + state instead. + + This can therefore potentially cause what would've been an **Update** to be + a **No-op** instead. +- The `replace_triggered_by` argument inside `resource` block `lifecycle` + blocks can use a proposed change elsewhere in a module to force OpenTofu + to propose one of the two **Replace** variants for a particular resource. +- The `create_before_destroy` argument inside `resource` block `lifecycle` + blocks only takes effect if a particular resource instance has a proposed + **Replace** action. If not set or set to `false`, OpenTofu will decompose + it to **Destroy** then **Create**, but if set to `true` OpenTofu will use + the inverted ordering. + + Because OpenTofu Core will never select a **Replace** action automatically + by itself, this is an example of a hybrid design where the config-driven + `create_before_destroy` combines with any other behavior (config-driven or + otherwise) that might cause **Replace** to customize exactly what that + **Replace** will mean. +- Top-level `moved` blocks in a module activate a special behavior during the + planning phase, where OpenTofu will first try to change the bindings of + existing objects in the prior state to attach to new addresses before running + the normal planning process. This therefore allows a module author to + document certain kinds of refactoring so that OpenTofu can update the + state automatically once users upgrade to a new version of the module. + + This special behavior is interesting because it doesn't _directly_ change + what actions OpenTofu will propose, but instead it adds an extra + preparation step before the typical planning process which changes the + addresses that the planning process will consider. It can therefore + _indirectly_ cause different proposed actions for affected resource + instances, such as transforming what by default might've been a **Delete** + of one instance and a **Create** of another into just a **No-op** or + **Update** of the second instance. + + This one is an example of a "global behavior", because at minimum it + affects two resource instance addresses and, if working with whole resource + or whole module addresses, can potentially affect a large number of resource + instances all at once. + +### Provider-driven Behaviors + +Providers get an opportunity to activate some special behaviors for a particular +resource instance when they respond to the `PlanResourceChange` function of +the provider plugin protocol. + +When OpenTofu Core executes this RPC, it has already selected between +**Create**, **Delete**, or **Update** actions for the particular resource +instance, and so the special behaviors a provider may activate will typically +serve as modifiers or tweaks to that base action, and will not allow +the provider to select another base action altogether. The provider wire +protocol does not talk about the action types explicitly, and instead only +implies them via other content of the request and response, with OpenTofu Core +making the final decision about how to react to that information. + +The following is a non-exhaustive list of existing examples of +provider-driven behaviors, selected to illustrate some different variations +that might be useful inspiration for new designs: + +- When the base action is **Update**, a provider may optionally return one or + more paths to attributes which have changes that the provider cannot + implement as an in-place update due to limitations of the remote system. + + In that case, OpenTofu Core will replace the **Update** action with one of + the two **Replace** variants, which means that from the provider's + perspective the apply phase will really be two separate calls for the + decomposed **Create** and **Delete** actions (in either order), rather + than **Update** directly. +- When the base action is **Update**, a provider may optionally return a + proposed new object where one or more of the arguments has its value set + to what was in the prior state rather than what was set in the configuration. + This represents any situation where a remote system supports multiple + different serializations of the same value that are all equivalent, and + so changing from one to another doesn't represent a real change in the + remote system. + + If all of those taken together causes the new object to match the prior + state, OpenTofu Core will treat the update as a **No-op** instead. + +Of the three genres of special behaviors, provider-driven behaviors is the one +we've made the least use of historically but one that seems to have a lot of +opportunities for future exploration. Provider-driven behaviors can often be +ideal because their effects appear as if they are built in to OpenTofu so +that "it just works", with OpenTofu automatically deciding and explaining what +needs to happen and why, without any special effort on the user's part. + +### Single-run Behaviors + +OpenTofu Core's "plan" operation takes a set of arguments that we collectively +call "plan options", that can modify OpenTofu's planning behavior on a per-run +basis without any configuration changes or special provider behaviors. + +As noted above, this particular genre of designs is the most burdensome to +implement because any wrapping software that can ask OpenTofu Core to create +a plan must ideally offer some way to set all of the available planning options, +or else some part of OpenTofu's functionality won't be available to anyone +using that wrapper. + +However, we've seen various situations where single-run behaviors really are the +most appropriate way to handle a particular use-case, because the need for the +behavior originates in some process happening outside of the scope of any +particular OpenTofu module or provider. + +The following is a non-exhaustive list of existing examples of +single-run behaviors, selected to illustrate some different variations +that might be useful inspiration for new designs: + +- The "replace" planning option specifies zero or more resource instance + addresses. + + For any resource instance specified, OpenTofu Core will transform any + **Update** or **No-op** action for that instance into one of the + **Replace** actions, thereby allowing an operator to respond to something + having become degraded in a way that OpenTofu and providers cannot + automatically detect and force OpenTofu to replace that object with + a new one that will hopefully function correctly. +- The "refresh only" planning mode ("planning mode" is a single planning option + that selects between a few mutually-exclusive behaviors) forces OpenTofu + to treat every resource instance as **No-op**, regardless of what is bound + to that address in state or present in the configuration. + +## Legacy Operations + +Some of the legacy operations OpenTofu CLI offers that _aren't_ integrated +with the plan and apply flow could be thought of as various degenerate kinds +of single-run behaviors. Most don't offer any opportunity to preview an effect +before applying it, but do meet a similar set of use-cases where an operator +needs to take some action to respond to changes to the context OpenTofu is +in rather than to the OpenTofu configuration itself. + +Most of these legacy operations could therefore most readily be translated to +single-run behaviors, but before doing so it's worth researching whether people +are using them as a workaround for missing configuration-driven and/or +provider-driven behaviors. A particular legacy operation might be better +replaced with a different sort of special behavior, or potentially by multiple +different special behaviors of different genres if it's currently serving as +a workaround for many different unmet needs. diff --git a/network-poc/static/docs/plugin-protocol/README.md b/network-poc/static/docs/plugin-protocol/README.md new file mode 100644 index 0000000..65fda33 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/README.md @@ -0,0 +1,213 @@ +# OpenTofu Plugin Protocol + +This directory contains documentation about the physical wire protocol that +OpenTofu Core uses to communicate with provider plugins. + +Most providers are not written directly against this protocol. Instead, prefer +to use an SDK that implements this protocol and write the provider against +the SDK's API. + +---- + +**If you want to write a plugin for OpenTofu, please refer to +[Extending OpenTofu](https://github.com/hashicorp/terraform-docs-common) instead.** + +This documentation is for those who are developing _OpenTofu SDKs_, rather +than those implementing plugins. + +---- + +From OpenTofu v0.12.0 onwards, OpenTofu's plugin protocol is built on +[gRPC](https://grpc.io/). This directory contains `.proto` definitions of +different versions of OpenTofu's protocol. + +Only `.proto` files published as part of OpenTofu release tags are actually +official protocol versions. If you are reading this directory on the `main` +branch or any other development branch then it may contain protocol definitions +that are not yet finalized and that may change before final release. + +## RPC Plugin Model + +OpenTofu plugins are normal executable programs that, when launched, expose +gRPC services on a server accessed via the loopback interface. OpenTofu Core +discovers and launches plugins, waits for a handshake to be printed on the +plugin's `stdout`, and then connects to the indicated port number as a +gRPC client. + +For this reason, we commonly refer to OpenTofu Core itself as the plugin +"client" and the plugin program itself as the plugin "server". Both of these +processes run locally, with the server process appearing as a child process +of the client. OpenTofu Core controls the lifecycle of these server processes +and will terminate them when they are no longer required. + +The startup and handshake protocol is not currently documented. We hope to +document it here or to link to external documentation on it in future. + +## Versioning Strategy + +The Plugin Protocol uses a versioning strategy that aims to allow gradual +enhancements to the protocol while retaining compatibility, but also to allow +more significant breaking changes from time to time while allowing old and +new plugins to be used together for some period. + +The versioning strategy described below was introduced with protocol version +5.0 in OpenTofu v0.12. Prior versions of OpenTofu and prior protocol versions +do not follow this strategy. + +The authoritative definition for each protocol version is in this directory +as a Protocol Buffers (protobuf) service definition. The files follow the +naming pattern `tfpluginX.Y.proto`, where X is the major version and Y +is the minor version. + +### Major and minor versioning + +The minor version increases for each change introducing optional new +functionality that can be ignored by implementations of prior versions. For +example, if a new field were added to an response message, it could be a minor +release as long as OpenTofu Core can provide some default behavior when that +field is not populated. + +The major version increases for any significant change to the protocol where +compatibility is broken. However, OpenTofu Core and an SDK may both choose +to support multiple major versions at once: the plugin handshake includes a +negotiation step where client and server can work together to select a +mutually-supported major version. + +The major version number is encoded into the protobuf package name: major +version 5 uses the package name `tfplugin5`, and one day major version 6 +will switch to `tfplugin6`. This change of name allows a plugin server to +implement multiple major versions at once, by exporting multiple gRPC services. +Minor version differences rely instead on feature-detection mechanisms, so they +are not represented directly on the wire and exist primarily as a human +communication tool to help us easily talk about which software supports which +features. + +## Version compatibility for Core, SDK, and Providers + +A particular version of OpenTofu Core has both a minimum minor version it +requires and a maximum major version that it supports. A particular version of +OpenTofu Core may also be able to optionally use a newer minor version when +available, but fall back on older behavior when that functionality is not +available. + +Likewise, each provider plugin release is compatible with a set of versions. +The compatible versions for a provider are a list of major and minor version +pairs, such as "4.0", "5.2", which indicates that the provider supports the +baseline features of major version 4 and supports major version 5 including +the enhancements from both minor versions 1 and 2. This provider would +therefore be compatible with a OpenTofu Core release that supports only +protocol version 5.0, since major version 5 is supported and the optional +5.1 and 5.2 enhancements will be ignored. + +If OpenTofu Core and the plugin do not have at least one mutually-supported +major version, OpenTofu Core will return an error from `tofu init` +during plugin installation: + +``` +Provider "aws" v1.0.0 is not compatible with OpenTofu v0.12.0. + +Provider version v2.0.0 is the earliest compatible version. +Select it with the following version constraint: + + version = "~> 2.0.0" +``` + +``` +Provider "aws" v3.0.0 is not compatible with OpenTofu v0.12.0. +Provider version v2.34.0 is the latest compatible version. Select +it with the following constraint: + + version = "~> 2.34.0" + +Alternatively, upgrade to the latest version of OpenTofu for compatibility with newer provider releases. +``` + +The above messages are for plugins installed via `tofu init` from a +OpenTofu registry, where the registry API allows OpenTofu Core to recognize +the protocol compatibility for each provider release. For plugins that are +installed manually to a local plugin directory, OpenTofu Core has no way to +suggest specific versions to upgrade or downgrade to, and so the error message +is more generic: + +``` +The installed version of provider "example" is not compatible with OpenTofu v0.12.0. + +This provider was loaded from: + /usr/local/bin/terraform-provider-example_v0.1.0 +``` + +## Adding/removing major version support in SDK and Providers + +The set of supported major versions is decided by the SDK used by the plugin. +Over time, SDKs will add support for new major versions and phase out support +for older major versions. + +In doing so, the SDK developer passes those capabilities and constraints on to +any provider using their SDK, and that will in turn affect the compatibility +of the plugin in ways that affect its semver-based version numbering: + +- If an SDK upgrade adds support for a new provider protocol, that will usually + be considered a new feature and thus warrant a new minor version. +- If an SDK upgrade removes support for an old provider protocol, that is + always a breaking change and thus requires a major release of the provider. + +For this reason, SDK developers must be clear in their release notes about +the addition and removal of support for major versions. + +OpenTofu Core also makes an assumption about major version support when +it produces actionable error messages for users about incompatibilities: +a particular protocol major version is supported for a single consecutive +range of provider releases, with no "gaps". + +## Using the protobuf specifications in an SDK + +If you wish to build an SDK for OpenTofu plugins, an early step will be to +copy one or more `.proto` files from this directory into your own repository +(depending on which protocol versions you intend to support) and use the +`protoc` protocol buffers compiler (with gRPC extensions) to generate suitable +RPC stubs and types for your target language. + +For example, if you happen to be targeting Python, you might generate the +stubs using a command like this: + +``` +protoc --python_out=. --grpc_python_out=. tfplugin5.1.proto +``` + +You can find out more about the tool usage for each target language in +[the gRPC Quick Start guides](https://grpc.io/docs/quickstart/). + +The protobuf specification for a version is immutable after it has been +included in at least one OpenTofu release. Any changes will be documented in +a new `.proto` file establishing a new protocol version. + +The protocol buffer compiler will produce some sort of library object appropriate +for the target language, which depending on the language might be called a +module, or a package, or something else. We recommend to include the protocol +major version in your module or package name so that you can potentially +support multiple versions concurrently in future. For example, if you are +targeting major version 5 you might call your package or module `tfplugin5`. + +To upgrade to a newer minor protocol version, copy the new `.proto` file +from this directory into the same location as your previous version, delete +the previous version, and then run the protocol buffers compiler again +against the new `.proto` file. Because minor releases are backward-compatible, +you can simply update your previous stubs in-place rather than creating a +new set alongside. + +To support a new _major_ protocol version, create a new package or module +and copy the relevant `.proto` file into it, creating a separate set of stubs +that can in principle allow your SDK to support both major versions at the +same time. We recommend supporting both the previous and current major versions +together for a while across a major version upgrade so that users can avoid +having to upgrade both OpenTofu Core and all of their providers at the same +time, but you can delete the previous major version stubs once you remove +support for that version. + +**Note:** Some of the `.proto` files contain statements about being updated +in-place for minor versions. This reflects an earlier version management +strategy which is no longer followed. The current process is to create a +new file in this directory for each new minor version and consider all +previously-tagged definitions as immutable. The outdated comments in those +files are retained in order to keep the promise of immutability, even though +it is now incorrect. diff --git a/network-poc/static/docs/plugin-protocol/object-wire-format.md b/network-poc/static/docs/plugin-protocol/object-wire-format.md new file mode 100644 index 0000000..4aa854c --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/object-wire-format.md @@ -0,0 +1,267 @@ +# Wire Format for OpenTofu Objects and Associated Values + +The provider wire protocol (as of major version 5) includes a protobuf message +type `DynamicValue` which OpenTofu uses to represent values from the OpenTofu +Language type system, which result from evaluating the content of `resource`, +`data`, and `provider` blocks, based on a schema defined by the corresponding +provider. + +Because the structure of these values is determined at runtime, `DynamicValue` +uses one of two possible dynamic serialization formats for the values +themselves: MessagePack or JSON. OpenTofu most commonly uses MessagePack, +because it offers a compact binary representation of a value. However, a server +implementation of the provider protocol should fall back to JSON if the +MessagePack field is not populated, in order to support both formats. + +The remainder of this document describes how OpenTofu translates from its own +type system into the type system of the two supported serialization formats. +A server implementation of the OpenTofu provider protocol can use this +information to decode `DynamicValue` values from incoming messages into +whatever representation is convenient for the provider implementation. + +A server implementation must also be able to _produce_ `DynamicValue` messages +as part of various response messages. When doing so, servers should always +use MessagePack encoding, because OpenTofu does not consistently support +JSON responses across all request types and all OpenTofu versions. + +Both the MessagePack and JSON serializations are driven by information the +provider previously returned in a `Schema` message. OpenTofu will encode each +value depending on the type constraint given for it in the corresponding schema, +using the closest possible MessagePack or JSON type to the OpenTofu language +type. Therefore a server implementation can decode a serialized value using a +standard MessagePack or JSON library and assume it will conform to the +serialization rules described below. + +## MessagePack Serialization Rules + +The MessagePack types referenced in this section are those defined in +[The MessagePack type system specification](https://github.com/msgpack/msgpack/blob/master/spec.md#type-system). + +Note that MessagePack defines several possible serialization formats for each +type, and OpenTofu may choose any of the formats of a specified type. +The exact serialization chosen for a given value may vary between OpenTofu +versions, but the types given here are contractual. + +Conversely, server implementations that are _producing_ MessagePack-encoded +values are free to use any of the valid serialization formats for a particular +type. However, we recommend choosing the most compact format that can represent +the value without a loss of range. + +### `Schema.Block` Mapping Rules for MessagePack + +To represent the content of a block as MessagePack, OpenTofu constructs a +MessagePack map that contains one key-value pair per attribute and one +key-value pair per distinct nested block described in the `Schema.Block` message. + +The key-value pairs representing attributes have values based on +[the `Schema.Attribute` mapping rules](#Schema.Attribute-mapping-rules-for-messagepack). +The key-value pairs representing nested block types have values based on +[the `Schema.NestedBlock` mapping rules](#Schema.NestedBlock-mapping-rules-for-messagepack). + +### `Schema.Attribute` Mapping Rules for MessagePack + +The MessagePack serialization of an attribute value depends on the value of the +`type` field of the corresponding `Schema.Attribute` message. The `type` field is +a compact JSON serialization of a +[OpenTofu type constraint](https://opentofu.org/docs/language/expressions/type-constraints/), +which consists either of a single +string value (for primitive types) or a two-element array giving a type kind +and a type argument. + +The following table describes the type-specific mapping rules. Along with those +type-specific rules there are two special rules that override the mappings +in the table below, regardless of type: + +* A null value is represented as a MessagePack nil value. +* An unknown value (that is, a placeholder for a value that will be decided + only during the apply operation) is represented as a + [MessagePack extension](https://github.com/msgpack/msgpack/blob/master/spec.md#extension-types) + value, described in more detail below. + +| `type` Pattern | MessagePack Representation | +|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `"string"` | A MessagePack string containing the Unicode characters from the string value serialized as normalized UTF-8. | +| `"number"` | Either MessagePack integer, MessagePack float, or MessagePack string representing the number. If a number is represented as a string then the string contains a decimal representation of the number which may have a larger mantissa than can be represented by a 64-bit float. | +| `"bool"` | A MessagePack boolean value corresponding to the value. | +| `["list",T]` | A MessagePack array with the same number of elements as the list value, each of which is represented by the result of applying these same mapping rules to the nested type `T`. | +| `["set",T]` | Identical in representation to `["list",T]`, but the order of elements is undefined because OpenTofu sets are unordered. | +| `["map",T]` | A MessagePack map with one key-value pair per element of the map value, where the element key is serialized as the map key (always a MessagePack string) and the element value is represented by a value constructed by applying these same mapping rules to the nested type `T`. | +| `["object",ATTRS]` | A MessagePack map with one key-value pair per attribute defined in the `ATTRS` object. The attribute name is serialized as the map key (always a MessagePack string) and the attribute value is represented by a value constructed by applying these same mapping rules to each attribute's own type. | +| `["tuple",TYPES]` | A MessagePack array with one element per element described by the `TYPES` array. The element values are constructed by applying these same mapping rules to the corresponding element of `TYPES`. | +| `"dynamic"` | A MessagePack array with exactly two elements. The first element is a MessagePack binary value containing a JSON-serialized type constraint in the same format described in this table. The second element is the result of applying these same mapping rules to the value with the type given in the first element. This special type constraint represents values whose types will be decided only at runtime. | + +Unknown values have two possible representations, both using +[MessagePack extension](https://github.com/msgpack/msgpack/blob/master/spec.md#extension-types) +values. + +The older encoding is for unrefined unknown values and uses an extension +code of zero, with the extension value payload completely ignored. + +Newer OpenTofu versions can produce "refined" unknown values which carry some +additional information that constrains the possible range of the final value/ +Refined unknown values have extension code 12 and then the extension object's +payload is a MessagePack-encoded map using integer keys to represent different +kinds of refinement: + +* `1` represents "nullness", and the value of that key will be a boolean + value that is true if the value is definitely null or false if it is + definitely not null. If this key isn't present at all then the value may or + may not be null. It's not actually useful to encode that an unknown value + is null; use a known null value instead in that case, because there is only + one null value of each type. +* `2` represents string prefix, and the value is a string that the final + value is known to begin with. This is valid only for unknown values of string + type. +* `3` and `4` represent the lower and upper bounds respectively of a number + value, and the value of both is a two-element msgpack array whose + first element is a valid encoding of a number (as in the table above) + and whose second element is a boolean value that is true for an inclusive + bound and false for an exclusive bound. This is valid only for unknown values + of number type. +* `5` and `6` represent the lower and upper bounds respectively of the length + of a collection value. The value of both is an integer representing an + inclusive bound. This is valid only for unknown values of the three kinds of + collection types: list, set, and map. + +Unknown value refinements are an optional way to reduce the range of possible +values for situations where that makes it possible to produce a known result +for unknown inputs or where it allows detecting an error during the planning +phase that would otherwise be detected only during the apply phase. It's always +safe to ignore refinements and just treat an unknown value as wholly unknown, +but considering refinements may allow a more precise answer. A provider that +produces refined values in its planned new state (from `PlanResourceChange`) +_must_ honor those refinements in the final state (from `ApplyResourceChange`). + +Unmarshalling code should ignore refinement map keys that they don't know about, +because future versions of the protocol might define additional refinements. + +When encoding an unknown value without any refinements, always use the older +format with extension code zero instead of using extension code 12 with an +empty refinement map. Any refined unknown value _must_ have at least one +refinement map entry. This rule ensures backward compatibility with older +implementations that predate the value refinements concept. + +A server implementation of the protocol should treat _any_ MessagePack extension +code as representing an unknown value, but should ignore the payload of that +extension value entirely unless the extension code is 12 to indicate that +the body represents refinements. Future versions of this protocol may define +specific formats for other extension codes, but they will always represent +unknown values. + +### `Schema.NestedBlock` Mapping Rules for MessagePack + +The MessagePack serialization of a collection of blocks of a particular type +depends on the `nesting` field of the corresponding `Schema.NestedBlock` message. +The `nesting` field is a value from the `Schema.NestingBlock.NestingMode` +enumeration. + +All `nesting` values cause the individual blocks of a type to be represented +by applying +[the `Schema.Block` mapping rules](#Schema.Block-mapping-rules-for-messagepack) +to the block's contents based on the `block` field, producing what we'll call +a _block value_ in the table below. + +The `nesting` value then in turn defines how OpenTofu will collect all of the +individual block values together to produce a single property value representing +the nested block type. For all `nesting` values other than `MAP`, blocks may +not have any labels. For the `nesting` value `MAP`, blocks must have exactly +one label, which is a string we'll call a _block label_ in the table below. + +| `nesting` Value | MessagePack Representation | +|---|---| +| `SINGLE` | The block value of the single block of this type, or nil if there is no block of that type. | +| `LIST` | A MessagePack array of all of the block values, preserving the order of definition of the blocks in the configuration. | +| `SET` | A MessagePack array of all of the block values in no particular order. | +| `MAP` | A MessagePack map with one key-value pair per block value, where the key is the block label and the value is the block value. | +| `GROUP` | The same as with `SINGLE`, except that if there is no block of that type OpenTofu will synthesize a block value by pretending that all of the declared attributes are null and that there are zero blocks of each declared block type. | + +For the `LIST` and `SET` nesting modes, OpenTofu guarantees that the +MessagePack array will have a number of elements between the `min_items` and +`max_items` values given in the schema, _unless_ any of the block values contain +nested unknown values. When unknown values are present, OpenTofu considers +the value to be potentially incomplete and so OpenTofu defers validation of +the number of blocks. For example, if the configuration includes a `dynamic` +block whose `for_each` argument is unknown then the final number of blocks is +not predictable until the apply phase. + +## JSON Serialization Rules + +The JSON serialization is a secondary representation for `DynamicValue`, with +MessagePack preferred due to its ability to represent unknown values via an +extension. + +The JSON encoding described in this section is also used for the `json` field +of the `RawValue` message that forms part of an `UpgradeResourceState` request. +However, in that case the data is serialized per the schema of the provider +version that created it, which won't necessarily match the schema of the +_current_ version of that provider. + +### `Schema.Block` Mapping Rules for JSON + +To represent the content of a block as JSON, OpenTofu constructs a +JSON object that contains one property per attribute and one property per +distinct nested block described in the `Schema.Block` message. + +The properties representing attributes have property values based on +[the `Schema.Attribute` mapping rules](#Schema.Attribute-mapping-rules-for-json). +The properties representing nested block types have property values based on +[the `Schema.NestedBlock` mapping rules](#Schema.NestedBlock-mapping-rules-for-json). + +### `Schema.Attribute` Mapping Rules for JSON + +The JSON serialization of an attribute value depends on the value of the `type` +field of the corresponding `Schema.Attribute` message. The `type` field is +a compact JSON serialization of a +[OpenTofu type constraint](https://opentofu.org/docs/language/expressions/type-constraints/), +which consists either of a single +string value (for primitive types) or a two-element array giving a type kind +and a type argument. + +The following table describes the type-specific mapping rules. Along with those +type-specific rules there is one special rule that overrides the rules in the +table regardless of type: + +* A null value is always represented as JSON `null`. + +| `type` Pattern | JSON Representation | +|---|---| +| `"string"` | A JSON string containing the Unicode characters from the string value. | +| `"number"` | A JSON number representing the number value. OpenTofu numbers are arbitrary-precision floating point, so the value may have a larger mantissa than can be represented by a 64-bit float. | +| `"bool"` | Either JSON `true` or JSON `false`, depending on the boolean value. | +| `["list",T]` | A JSON array with the same number of elements as the list value, each of which is represented by the result of applying these same mapping rules to the nested type `T`. | +| `["set",T]` | Identical in representation to `["list",T]`, but the order of elements is undefined because OpenTofu sets are unordered. | +| `["map",T]` | A JSON object with one property per element of the map value, where the element key is serialized as the property name string and the element value is represented by a property value constructed by applying these same mapping rules to the nested type `T`. | +| `["object",ATTRS]` | A JSON object with one property per attribute defined in the `ATTRS` object. The attribute name is serialized as the property name string and the attribute value is represented by a property value constructed by applying these same mapping rules to each attribute's own type. | +| `["tuple",TYPES]` | A JSON array with one element per element described by the `TYPES` array. The element values are constructed by applying these same mapping rules to the corresponding element of `TYPES`. | +| `"dynamic"` | A JSON object with two properties: `"type"` specifying one of the `type` patterns described in this table in-band, giving the exact runtime type of the value, and `"value"` specifying the result of applying these same mapping rules to the table for the specified runtime type. This special type constraint represents values whose types will be decided only at runtime. | + +### `Schema.NestedBlock` Mapping Rules for JSON + +The JSON serialization of a collection of blocks of a particular type depends +on the `nesting` field of the corresponding `Schema.NestedBlock` message. +The `nesting` field is a value from the `Schema.NestingBlock.NestingMode` +enumeration. + +All `nesting` values cause the individual blocks of a type to be represented +by applying +[the `Schema.Block` mapping rules](#Schema.Block-mapping-rules-for-json) +to the block's contents based on the `block` field, producing what we'll call +a _block value_ in the table below. + +The `nesting` value then in turn defines how OpenTofu will collect all of the +individual block values together to produce a single property value representing +the nested block type. For all `nesting` values other than `MAP`, blocks may +not have any labels. For the `nesting` value `MAP`, blocks must have exactly +one label, which is a string we'll call a _block label_ in the table below. + +| `nesting` Value | JSON Representation | +|---|---| +| `SINGLE` | The block value of the single block of this type, or `null` if there is no block of that type. | +| `LIST` | A JSON array of all of the block values, preserving the order of definition of the blocks in the configuration. | +| `SET` | A JSON array of all of the block values in no particular order. | +| `MAP` | A JSON object with one property per block value, where the property name is the block label and the value is the block value. | +| `GROUP` | The same as with `SINGLE`, except that if there is no block of that type OpenTofu will synthesize a block value by pretending that all of the declared attributes are null and that there are zero blocks of each declared block type. | + +For the `LIST` and `SET` nesting modes, OpenTofu guarantees that the JSON +array will have a number of elements between the `min_items` and `max_items` +values given in the schema. diff --git a/network-poc/static/docs/plugin-protocol/releasing-new-version.md b/network-poc/static/docs/plugin-protocol/releasing-new-version.md new file mode 100644 index 0000000..22373ae --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/releasing-new-version.md @@ -0,0 +1,53 @@ +# Releasing a New Version of the Protocol + +OpenTofu's plugin protocol is the contract between OpenTofu's plugins and +OpenTofu, and as such releasing a new version requires some coordination +between those pieces. This document is intended to be a checklist to consult +when adding a new major version of the protocol (X in X.Y) to ensure that +everything that needs to be is aware of it. + +## New Protobuf File + +The protocol is defined in protobuf files that live in the opentofu/opentofu +repository. Adding a new version of the protocol involves creating a new +`.proto` file in that directory. It is recommended that you copy the latest +protocol file, and modify it accordingly. + +## New terraform-plugin-go Package + +The +[hashicorp/terraform-plugin-go](https://github.com/hashicorp/terraform-plugin-go) +repository serves as the foundation for OpenTofu's plugin ecosystem. It needs +to know about the new major protocol version. Either open an issue in that repo +to have the Plugin SDK team add the new package, or if you would like to +contribute it yourself, open a PR. It is recommended that you copy the package +for the latest protocol version and modify it accordingly. + +## Update the Registry's List of Allowed Versions + +The OpenTofu Registry validates the protocol versions a provider advertises +support for when ingesting providers. Providers will not be able to advertise +support for the new protocol version until it is added to that list. + +## Update OpenTofu's Version Constraints + +OpenTofu only downloads providers that speak protocol versions it is +compatible with from the Registry during `tofu init`. When adding support +for a new protocol, you need to tell OpenTofu it knows that protocol version. +Modify the `SupportedPluginProtocols` variable in opentofu/opentofu's +`internal/getproviders/registry_client.go` file to include the new protocol. + +## Test Running a Provider With the Test Framework + +Use the provider test framework to test a provider written with the new +protocol. This end-to-end test ensures that providers written with the new +protocol work correctly with the test framework, especially in communicating +the protocol version between the test framework and OpenTofu. + +## Test Retrieving and Running a Provider From the Registry + +Publish a provider, either to the public registry or to the staging registry, +and test running `tofu init` and `tofu apply`, along with exercising +any of the new functionality the protocol version introduces. This end-to-end +test ensures that all the pieces needing to be updated before practitioners can +use providers built with the new protocol have been updated. diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.0.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.0.proto new file mode 100644 index 0000000..dc94639 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.0.proto @@ -0,0 +1,358 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.0 +// +// This file defines version 5.0 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will be updated in-place in the source Terraform repository for +// any minor versions of protocol 5, but later minor versions will always be +// backwards compatible. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.1.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.1.proto new file mode 100644 index 0000000..4dc9ca1 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.1.proto @@ -0,0 +1,358 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.1 +// +// This file defines version 5.1 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will be updated in-place in the source Terraform repository for +// any minor versions of protocol 5, but later minor versions will always be +// backwards compatible. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.10.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.10.proto new file mode 100644 index 0000000..a0731a3 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.10.proto @@ -0,0 +1,953 @@ +// Copyright IBM Corp. 2014, 2026 +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.10 +// +// This file defines version 5.10 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// Any minor versions of protocol 5 to follow should modify this file while +// maintaining backwards compatibility. Breaking changes, if any are required, +// will come in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// ResourceIdentitySchema represents the structure and types of data used to identify +// a managed resource type. Effectively, resource identity is a versioned object +// that can be used to compare resources, whether already managed and/or being +// discovered. +message ResourceIdentitySchema { + // IdentityAttribute represents one value of data within resource identity. These + // are always used in resource identity comparisons. + message IdentityAttribute { + // name is the identity attribute name + string name = 1; + + // type is the identity attribute type + bytes type = 2; + + // required_for_import when enabled signifies that this attribute must be + // defined for ImportResourceState to complete successfully + bool required_for_import = 3; + + // optional_for_import when enabled signifies that this attribute is not + // required for ImportResourceState, because it can be supplied by the + // provider. It is still possible to supply this attribute during import. + bool optional_for_import = 4; + + // description is a human-readable description of the attribute in Markdown + string description = 5; + } + + // version is the identity version and separate from the Schema version. + // Any time the structure or format of identity_attributes changes, this version + // should be incremented. Versioning implicitly starts at 0 and by convention + // should be incremented by 1 each change. + // + // When comparing identity_attributes data, differing versions should always be treated + // as inequal. + int64 version = 1; + + // identity_attributes are the individual value definitions which define identity data + // for a managed resource type. This information is used to decode DynamicValue of + // identity data. + // + // These attributes are intended for permanent identity data and must be wholly + // representative of all data necessary to compare two managed resource instances + // with no other data. This generally should include account, endpoint, location, + // and automatically generated identifiers. For some resources, this may include + // configuration-based data, such as a required name which must be unique. + repeated IdentityAttribute identity_attributes = 2; +} + +message ResourceIdentityData { + // identity_data is the resource identity data for the given definition. It should + // be decoded using the identity schema. + // + // This data is considered permanent for the identity version and suitable for + // longer-term storage. + DynamicValue identity_data = 1; +} + +// ActionSchema defines the schema for an action that can be invoked by Terraform. +message ActionSchema { + Schema schema = 1; // of the action itself +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + string deprecation_message = 7; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + bool write_only = 10; + string deprecation_message = 11; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // Return is the function return parameter. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; + + // The generate_resource_config capability signals that a provider supports + // GenerateResourceConfig. + bool generate_resource_config = 4; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. + // This method is CURRENTLY UNUSED and it serves mostly for convenience + // of code generation inside of terraform-plugin-mux. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + // GetResourceIdentitySchemas returns the identity schemas for all managed + // resources. + rpc GetResourceIdentitySchemas(GetResourceIdentitySchemas.Request) returns (GetResourceIdentitySchemas.Response); + // UpgradeResourceIdentityData should return the upgraded resource identity + // data for a managed resource type. + rpc UpgradeResourceIdentity(UpgradeResourceIdentity.Request) returns (UpgradeResourceIdentity.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + rpc GenerateResourceConfig(GenerateResourceConfig.Request) returns (GenerateResourceConfig.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + /////// List + rpc ListResource(ListResource.Request) returns (stream ListResource.Event); + rpc ValidateListResourceConfig(ValidateListResourceConfig.Request) returns (ValidateListResourceConfig.Response); + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + //////// Provider-contributed Functions + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Actions + rpc PlanAction(PlanAction.Request) returns (PlanAction.Response); + rpc InvokeAction(InvokeAction.Request) returns (stream InvokeAction.Event); + rpc ValidateActionConfig(ValidateActionConfig.Request) returns (ValidateActionConfig.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralMetadata ephemeral_resources = 6; + repeated ListResourceMetadata list_resources = 7; + repeated ActionMetadata actions = 8; + } + + message EphemeralMetadata { + string type_name = 1; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message ListResourceMetadata { + string type_name = 1; + } + + message ActionMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + map functions = 7; + map ephemeral_resource_schemas = 8; + map list_resource_schemas = 9; + reserved 10; // Field number 10 is used by state stores in version 6 + map action_schemas = 11; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message GetResourceIdentitySchemas { + message Request { + } + + message Response { + // identity_schemas is a mapping of resource type names to their identity schemas. + map identity_schemas = 1; + + // diagnostics is the collection of warning and error diagnostics for this request. + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceIdentity { + message Request { + // type_name is the managed resource type name + string type_name = 1; + + // version is the version of the resource identity data to upgrade + int64 version = 2; + + // raw_identity is the raw identity as stored for the resource. Core does + // not have access to the identity schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_identity will be json encoded. + RawState raw_identity = 3; + } + + message Response { + // upgraded_identity returns the upgraded resource identity data + ResourceIdentityData upgraded_identity = 1; + + // diagnostics is the collection of warning and error diagnostics for this request + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + ResourceIdentityData current_identity = 6; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + ResourceIdentityData new_identity = 5; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + ResourceIdentityData prior_identity = 8; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + + ResourceIdentityData planned_identity = 7; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + ResourceIdentityData planned_identity = 7; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + + ResourceIdentityData new_identity = 5; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + ResourceIdentityData identity = 4; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + ResourceIdentityData identity = 4; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GenerateResourceConfig { + message Request { + string type_name = 1; + DynamicValue state = 2; + } + + message Response { + // config is the provided state modified such that it represents a valid resource configuration value. + DynamicValue config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + + // The raw identity of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_identity = 7; + + // The identity schema version of the resource type that the resource + // is being moved from. + int64 source_identity_schema_version = 8; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + + ResourceIdentityData target_identity = 4; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + string name = 1; + repeated DynamicValue arguments = 2; + } + message Response { + DynamicValue result = 1; + FunctionError error = 2; + } +} + +message ListResource { + message Request { + // type_name is the list resource type name. + string type_name = 1; + + // configuration is the list ConfigSchema-based configuration data. + DynamicValue config = 2; + + // when include_resource_object is set to true, the provider should + // include the full resource object for each result + bool include_resource_object = 3; + + // The maximum number of results that Terraform is expecting. + // The stream will stop, once this limit is reached. + int64 limit = 4; + } + + message Event { + // identity is the resource identity data of the resource instance. + ResourceIdentityData identity = 1; + + // display_name can be displayed in a UI to make it easier for humans to identify a resource + string display_name = 2; + + // optional resource object which can be useful when combining list blocks in configuration + optional DynamicValue resource_object = 3; + + // A warning or error diagnostics for this event + repeated Diagnostic diagnostic = 4; + } +} + +message ValidateListResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue include_resource_object = 3; + DynamicValue limit = 4; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message PlanAction { + message Request { + string action_type = 1; + // config of the action, based on the schema of the actual action + DynamicValue config = 2; + // metadata + ClientCapabilities client_capabilities = 3; + } + + message Response { + repeated Diagnostic diagnostics = 1; + // metadata + Deferred deferred = 2; + } +} + +message InvokeAction { + message Request { + string action_type = 1; + // response from the plan + DynamicValue config = 2; + // metadata + ClientCapabilities client_capabilities = 3; + } + + message Event { + message Progress { + // message to be printed in the console / HCPT + string message = 1; + } + message Completed { + repeated Diagnostic diagnostics = 1; + } + + oneof type { + Progress progress = 1; + Completed completed = 2; + } + } +} + +message ValidateActionConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.2.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.2.proto new file mode 100644 index 0000000..f7e921a --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.2.proto @@ -0,0 +1,374 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.2 +// +// This file defines version 5.2 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.3.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.3.proto new file mode 100644 index 0000000..eb9f682 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.3.proto @@ -0,0 +1,403 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.3 +// +// This file defines version 5.3 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } + + + // ServerCapabilities allows providers to communicate extra information + // regarding supported protocol features. This is used to indicate + // availability of certain forward-compatible changes which may be optional + // in a major protocol version, but cannot be tested for directly. + message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.4.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.4.proto new file mode 100644 index 0000000..fc91152 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.4.proto @@ -0,0 +1,409 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.4 +// +// This file defines version 5.4 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } + + + // ServerCapabilities allows providers to communicate extra information + // regarding supported protocol features. This is used to indicate + // availability of certain forward-compatible changes which may be optional + // in a major protocol version, but cannot be tested for directly. + message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.5.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.5.proto new file mode 100644 index 0000000..2ee2534 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.5.proto @@ -0,0 +1,591 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.5 +// +// This file defines version 5.5 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.6.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.6.proto new file mode 100644 index 0000000..1818550 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.6.proto @@ -0,0 +1,637 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.6 +// +// This file defines version 5.6 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.7.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.7.proto new file mode 100644 index 0000000..137b765 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.7.proto @@ -0,0 +1,700 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.7 +// +// This file defines version 5.7 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} \ No newline at end of file diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.8.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.8.proto new file mode 100644 index 0000000..e671656 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.8.proto @@ -0,0 +1,707 @@ +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.8 +// +// This file defines version 5.8 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + // write_only indicates that the attribute value will be provided via + // configuration and must be omitted from state. write_only must be + // combined with optional or required, and is only valid for managed + // resource schemas. + bool write_only = 10; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} \ No newline at end of file diff --git a/network-poc/static/docs/plugin-protocol/tfplugin5.9.proto b/network-poc/static/docs/plugin-protocol/tfplugin5.9.proto new file mode 100644 index 0000000..f4dcd0b --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin5.9.proto @@ -0,0 +1,826 @@ +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 5.9 +// +// This file defines version 5.9 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 5 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin5"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin5; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message Stop { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource, Provider, or Provisioner. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + // write_only indicates that the attribute value will be provided via + // configuration and must be omitted from state. write_only must be + // combined with optional or required, and is only valid for managed + // resource schemas. + bool write_only = 10; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ResourceIdentitySchema represents the structure and types of data used to identify +// a managed resource type. Effectively, resource identity is a versioned object +// that can be used to compare resources, whether already managed and/or being +// discovered. +message ResourceIdentitySchema { + // IdentityAttribute represents one value of data within resource identity. + // These are always used in resource identity comparisons. + message IdentityAttribute { + // name is the identity attribute name + string name = 1; + + // type is the identity attribute type + bytes type = 2; + + // required_for_import when enabled signifies that this attribute must be + // defined for ImportResourceState to complete successfully + bool required_for_import = 3; + + // optional_for_import when enabled signifies that this attribute is not + // required for ImportResourceState, because it can be supplied by the + // provider. It is still possible to supply this attribute during import. + bool optional_for_import = 4; + + // description is a human-readable description of the attribute in Markdown + string description = 5; + } + + // version is the identity version and separate from the Schema version. + // Any time the structure or format of identity_attributes changes, this version + // should be incremented. Versioning implicitly starts at 0 and by convention + // should be incremented by 1 each change. + // + // When comparing identity_attributes data, differing versions should always be treated + // as inequal. + int64 version = 1; + + // identity_attributes are the individual value definitions which define identity data + // for a managed resource type. This information is used to decode DynamicValue of + // identity data. + // + // These attributes are intended for permanent identity data and must be wholly + // representative of all data necessary to compare two managed resource instances + // with no other data. This generally should include account, endpoint, location, + // and automatically generated identifiers. For some resources, this may include + // configuration-based data, such as a required name which must be unique. + repeated IdentityAttribute identity_attributes = 2; +} + +// ResourceIdentityData is a separate message for better extensibility +message ResourceIdentityData { + // identity_data is the resource identity data for the given definition. It should + // be decoded using the identity schema. + // + // This data is considered permanent for the identity version and suitable for + // longer-term storage. + DynamicValue identity_data = 1; +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + // GetResourceIdentitySchemas returns the identity schemas for all managed + // resources. + rpc GetResourceIdentitySchemas(GetResourceIdentitySchemas.Request) returns (GetResourceIdentitySchemas.Response); + rpc PrepareProviderConfig(PrepareProviderConfig.Request) returns (PrepareProviderConfig.Response); + rpc ValidateResourceTypeConfig(ValidateResourceTypeConfig.Request) returns (ValidateResourceTypeConfig.Response); + rpc ValidateDataSourceConfig(ValidateDataSourceConfig.Request) returns (ValidateDataSourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + // UpgradeResourceIdentityData should return the upgraded resource identity + // data for a managed resource type. + rpc UpgradeResourceIdentity(UpgradeResourceIdentity.Request) returns (UpgradeResourceIdentity.Response); + + //////// One-time initialization, called before other functions below + rpc Configure(Configure.Request) returns (Configure.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message PrepareProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + DynamicValue prepared_config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceTypeConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataSourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message Configure { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + ResourceIdentityData current_identity = 6; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + ResourceIdentityData new_identity = 5; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + ResourceIdentityData prior_identity = 8; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + ResourceIdentityData planned_identity = 7; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + ResourceIdentityData planned_identity = 7; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + ResourceIdentityData new_identity = 5; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + ResourceIdentityData identity = 4; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + ResourceIdentityData identity = 4; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + + // The raw identity of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_identity = 7; + + // The identity schema version of the resource type that the resource + // is being moved from. + int64 source_identity_schema_version = 8; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + + ResourceIdentityData target_identity = 4; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +service Provisioner { + rpc GetSchema(GetProvisionerSchema.Request) returns (GetProvisionerSchema.Response); + rpc ValidateProvisionerConfig(ValidateProvisionerConfig.Request) returns (ValidateProvisionerConfig.Response); + rpc ProvisionResource(ProvisionResource.Request) returns (stream ProvisionResource.Response); + rpc Stop(Stop.Request) returns (Stop.Response); +} + +message GetProvisionerSchema { + message Request { + } + message Response { + Schema provisioner = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateProvisionerConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ProvisionResource { + message Request { + DynamicValue config = 1; + DynamicValue connection = 2; + } + message Response { + string output = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +// Returns resource identity schemas for all resources +message GetResourceIdentitySchemas { + message Request { + } + message Response { + // identity_schemas is a mapping of resource type names to their identity schemas. + map identity_schemas = 1; + + // diagnostics is the collection of warning and error diagnostics for this request. + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceIdentity { + message Request { + // type_name is the managed resource type name + string type_name = 1; + + // version is the version of the resource identity data to upgrade + int64 version = 2; + + // raw_identity is the raw identity as stored for the resource. Core does + // not have access to the identity schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_identity will be json encoded. + RawState raw_identity = 3; + } + message Response { + // upgraded_identity returns the upgraded resource identity data + ResourceIdentityData upgraded_identity = 1; + + // diagnostics is the collection of warning and error diagnostics for this request + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.0.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.0.proto new file mode 100644 index 0000000..81eeb3e --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.0.proto @@ -0,0 +1,326 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.0 +// +// This file defines version 6.0 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.1.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.1.proto new file mode 100644 index 0000000..c5ff41c --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.1.proto @@ -0,0 +1,329 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.1 +// +// This file defines version 6.1 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.10.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.10.proto new file mode 100644 index 0000000..bcc4f2f --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.10.proto @@ -0,0 +1,1078 @@ +// Copyright IBM Corp. 2014, 2026 +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.10 +// +// This file defines version 6.10 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// Any minor versions of protocol 6 to follow should modify this file while +// maintaining backwards compatibility. Breaking changes, if any are required, +// will come in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// ResourceIdentitySchema represents the structure and types of data used to identify +// a managed resource type. Effectively, resource identity is a versioned object +// that can be used to compare resources, whether already managed and/or being +// discovered. +message ResourceIdentitySchema { + // IdentityAttribute represents one value of data within resource identity. These + // are always used in resource identity comparisons. + message IdentityAttribute { + // name is the identity attribute name + string name = 1; + + // type is the identity attribute type + bytes type = 2; + + // required_for_import when enabled signifies that this attribute must be + // defined for ImportResourceState to complete successfully + bool required_for_import = 3; + + // optional_for_import when enabled signifies that this attribute is not + // required for ImportResourceState, because it can be supplied by the + // provider. It is still possible to supply this attribute during import. + bool optional_for_import = 4; + + // description is a human-readable description of the attribute in Markdown + string description = 5; + } + + // version is the identity version and separate from the Schema version. + // Any time the structure or format of identity_attributes changes, this version + // should be incremented. Versioning implicitly starts at 0 and by convention + // should be incremented by 1 each change. + // + // When comparing identity_attributes data, differing versions should always be treated + // as inequal. + int64 version = 1; + + // identity_attributes are the individual value definitions which define identity data + // for a managed resource type. This information is used to decode DynamicValue of + // identity data. + // + // These attributes are intended for permanent identity data and must be wholly + // representative of all data necessary to compare two managed resource instances + // with no other data. This generally should include account, endpoint, location, + // and automatically generated identifiers. For some resources, this may include + // configuration-based data, such as a required name which must be unique. + repeated IdentityAttribute identity_attributes = 2; +} + +message ResourceIdentityData { + // identity_data is the resource identity data for the given definition. It should + // be decoded using the identity schema. + // + // This data is considered permanent for the identity version and suitable for + // longer-term storage. + DynamicValue identity_data = 1; +} + +// ActionSchema defines the schema for an action that can be invoked by Terraform. +message ActionSchema { + Schema schema = 1; // of the action itself +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + string deprecation_message = 7; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + bool write_only = 11; + string deprecation_message = 12; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [ deprecated = true ]; + int64 max_items = 5 [ deprecated = true ]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // Return is the function return parameter. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; + + // The generate_resource_config capability signals that a provider supports + // GenerateResourceConfig. + bool generate_resource_config = 4; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. + // This method is CURRENTLY UNUSED and it serves mostly for convenience + // of code generation inside of terraform-plugin-mux. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + // GetResourceIdentitySchemas returns the identity schemas for all managed + // resources. + rpc GetResourceIdentitySchemas(GetResourceIdentitySchemas.Request) returns (GetResourceIdentitySchemas.Response); + // UpgradeResourceIdentityData should return the upgraded resource identity + // data for a managed resource type. + rpc UpgradeResourceIdentity(UpgradeResourceIdentity.Request) returns (UpgradeResourceIdentity.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + rpc GenerateResourceConfig(GenerateResourceConfig.Request) returns (GenerateResourceConfig.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + /////// List + rpc ListResource(ListResource.Request) returns (stream ListResource.Event); + rpc ValidateListResourceConfig(ValidateListResourceConfig.Request) returns (ValidateListResourceConfig.Response); + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + //////// Provider-contributed Functions + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + // ValidateStateStoreConfig performs configuration validation + rpc ValidateStateStoreConfig(ValidateStateStore.Request) returns (ValidateStateStore.Response); + // ConfigureStateStore configures the state store, such as S3 connection in the context of already configured provider + rpc ConfigureStateStore(ConfigureStateStore.Request) returns (ConfigureStateStore.Response); + + // ReadStateBytes streams byte chunks of a given state file from a state store + rpc ReadStateBytes(ReadStateBytes.Request) returns (stream ReadStateBytes.Response); + // WriteStateBytes streams byte chunks of a given state file into a state store + rpc WriteStateBytes(stream WriteStateBytes.RequestChunk) returns (WriteStateBytes.Response); + + // LockState locks a given state (i.e. CE workspace) + rpc LockState(LockState.Request) returns (LockState.Response); + // UnlockState unlocks a given state (i.e. CE workspace) + rpc UnlockState(UnlockState.Request) returns (UnlockState.Response); + + // GetStates returns a list of all states (i.e. CE workspaces) managed by a given state store + rpc GetStates(GetStates.Request) returns (GetStates.Response); + // DeleteState instructs a given state store to delete a specific state (i.e. a CE workspace) + rpc DeleteState(DeleteState.Request) returns (DeleteState.Response); + + //////// Actions + rpc PlanAction(PlanAction.Request) returns (PlanAction.Response); + rpc InvokeAction(InvokeAction.Request) returns (stream InvokeAction.Event); + rpc ValidateActionConfig(ValidateActionConfig.Request) returns (ValidateActionConfig.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralMetadata ephemeral_resources = 6; + repeated ListResourceMetadata list_resources = 7; + repeated StateStoreMetadata state_stores = 8; + repeated ActionMetadata actions = 9; + } + + message EphemeralMetadata { + string type_name = 1; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message ListResourceMetadata { + string type_name = 1; + } + + message StateStoreMetadata { + string type_name = 1; + } + + message ActionMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + map functions = 7; + map ephemeral_resource_schemas = 8; + map list_resource_schemas = 9; + map state_store_schemas = 10; + map action_schemas = 11; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message GetResourceIdentitySchemas { + message Request { + } + + message Response { + // identity_schemas is a mapping of resource type names to their identity schemas. + map identity_schemas = 1; + + // diagnostics is the collection of warning and error diagnostics for this request. + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceIdentity { + message Request { + // type_name is the managed resource type name + string type_name = 1; + + // version is the version of the resource identity data to upgrade + int64 version = 2; + + // raw_identity is the raw identity as stored for the resource. Core does + // not have access to the identity schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_identity will be json encoded. + RawState raw_identity = 3; + } + + message Response { + // upgraded_identity returns the upgraded resource identity data + ResourceIdentityData upgraded_identity = 1; + + // diagnostics is the collection of warning and error diagnostics for this request + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + ResourceIdentityData current_identity = 6; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + ResourceIdentityData new_identity = 5; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + ResourceIdentityData prior_identity = 8; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + + ResourceIdentityData planned_identity = 7; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + ResourceIdentityData planned_identity = 7; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + + ResourceIdentityData new_identity = 5; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + ResourceIdentityData identity = 4; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + ResourceIdentityData identity = 4; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GenerateResourceConfig { + message Request { + string type_name = 1; + DynamicValue state = 2; + } + + message Response { + // config is the provided state modified such that it represents a valid resource configuration value. + DynamicValue config = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + + // The raw identity of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_identity = 7; + + // The identity schema version of the resource type that the resource + // is being moved from. + int64 source_identity_schema_version = 8; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + + ResourceIdentityData target_identity = 4; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + string name = 1; + repeated DynamicValue arguments = 2; + } + message Response { + DynamicValue result = 1; + FunctionError error = 2; + } +} + +message ListResource { + message Request { + // type_name is the list resource type name. + string type_name = 1; + + // configuration is the list ConfigSchema-based configuration data. + DynamicValue config = 2; + + // when include_resource_object is set to true, the provider should + // include the full resource object for each result + bool include_resource_object = 3; + + // The maximum number of results that Terraform is expecting. + // The stream will stop, once this limit is reached. + int64 limit = 4; + } + + message Event { + // identity is the resource identity data of the resource instance. + ResourceIdentityData identity = 1; + + // display_name can be displayed in a UI to make it easier for humans to identify a resource + string display_name = 2; + + // optional resource object which can be useful when combining list blocks in configuration + optional DynamicValue resource_object = 3; + + // A warning or error diagnostics for this event + repeated Diagnostic diagnostic = 4; + } +} + +message ValidateListResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue include_resource_object = 3; + DynamicValue limit = 4; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateStateStore { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureStateStore { + message Request { + string type_name = 1; + DynamicValue config = 2; + StateStoreClientCapabilities capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + StateStoreServerCapabilities capabilities = 2; + } +} + +message StateStoreClientCapabilities { + int64 chunk_size = 1; // suggested chunk size by Core +} + +message StateStoreServerCapabilities { + int64 chunk_size = 1; // chosen chunk size by plugin +} + +message ReadStateBytes { + message Request { + string type_name = 1; + string state_id = 2; + } + message Response { + bytes bytes = 1; + // total_length is the overall size of all of the state byte chunks that will be received + int64 total_length = 2; + StateRange range = 3; + repeated Diagnostic diagnostics = 4; + } +} + +message WriteStateBytes { + message RequestChunk { + // meta is sent with the first chunk only + optional RequestChunkMeta meta = 1; + + bytes bytes = 2; + // total_length is the overall size of all of the state byte chunks that will be sent. + int64 total_length = 3; + StateRange range = 4; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message RequestChunkMeta { + string type_name = 1; + string state_id = 2; +} + +message StateRange { + // start is the starting byte index for a chunk of state byte data. + // This index is in relation to the entire byte array that will be sent or received. + int64 start = 1; + // end is the ending byte index for a chunk of state byte data. + // This index is in relation to the entire byte array that will be sent or received. + int64 end = 2; +} + +message LockState { + message Request { + string type_name = 1; + string state_id = 2; + // operation represents an ongoing operation due to which lock is held (e.g. refresh, plan, apply) + string operation = 3; + } + message Response { + string lock_id = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message UnlockState { + message Request { + string type_name = 1; + string state_id = 2; + string lock_id = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message GetStates { + message Request { + string type_name = 1; + } + message Response { + repeated string state_id = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message DeleteState { + message Request { + string type_name = 1; + string state_id = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message PlanAction { + message Request { + string action_type = 1; + // config of the action, based on the schema of the actual action + DynamicValue config = 2; + // metadata + ClientCapabilities client_capabilities = 3; + } + + message Response { + repeated Diagnostic diagnostics = 1; + // metadata + Deferred deferred = 2; + } +} + +message InvokeAction { + message Request { + string action_type = 1; + // response from the plan + DynamicValue config = 2; + // metadata + ClientCapabilities client_capabilities = 3; + } + + message Event { + message Progress { + // message to be printed in the console / HCPT + string message = 1; + } + + message Completed { + repeated Diagnostic diagnostics = 1; + } + + oneof type { + Progress progress = 1; + Completed completed = 2; + } + } +} + +message ValidateActionConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.2.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.2.proto new file mode 100644 index 0000000..1ce3b0e --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.2.proto @@ -0,0 +1,355 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.2 +// +// This file defines version 6.2 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.3.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.3.proto new file mode 100644 index 0000000..182609c --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.3.proto @@ -0,0 +1,384 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.3 +// +// This file defines version 6.3 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } + + + // ServerCapabilities allows providers to communicate extra information + // regarding supported protocol features. This is used to indicate + // availability of certain forward-compatible changes which may be optional + // in a major protocol version, but cannot be tested for directly. + message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.4.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.4.proto new file mode 100644 index 0000000..609569c --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.4.proto @@ -0,0 +1,390 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2023 HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.4 +// +// This file defines version 6.4 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +service Provider { + //////// Information about what a provider supports/expects + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + } + + + // ServerCapabilities allows providers to communicate extra information + // regarding supported protocol features. This is used to indicate + // availability of certain forward-compatible changes which may be optional + // in a major protocol version, but cannot be tested for directly. + message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.5.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.5.proto new file mode 100644 index 0000000..93ad967 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.5.proto @@ -0,0 +1,572 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.5 +// +// This file defines version 6.5 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetProviderSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any errors from the function logic. + FunctionError error = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.6.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.6.proto new file mode 100644 index 0000000..6820bdf --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.6.proto @@ -0,0 +1,618 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.6 +// +// This file defines version 6.6 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetProviderSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any errors from the function logic. + FunctionError error = 2; + } +} diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.7.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.7.proto new file mode 100644 index 0000000..dd175c7 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.7.proto @@ -0,0 +1,682 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.7 +// +// This file defines version 6.7 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetProviderSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} \ No newline at end of file diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.8.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.8.proto new file mode 100644 index 0000000..1a38463 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.8.proto @@ -0,0 +1,691 @@ +// Copyright (c) The OpenTofu Authors +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.8 +// +// This file defines version 6.8 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaing backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + // write_only indicates that the attribute value will be provided via + // configuration and must be omitted from state. write_only must be + // combined with optional or required, and is only valid for managed + // resource schemas. + bool write_only = 11; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetProviderSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} \ No newline at end of file diff --git a/network-poc/static/docs/plugin-protocol/tfplugin6.9.proto b/network-poc/static/docs/plugin-protocol/tfplugin6.9.proto new file mode 100644 index 0000000..6b61662 --- /dev/null +++ b/network-poc/static/docs/plugin-protocol/tfplugin6.9.proto @@ -0,0 +1,809 @@ +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +// Terraform Plugin RPC protocol version 6.9 +// +// This file defines version 6.9 of the RPC protocol. To implement a plugin +// against this protocol, copy this definition into your own codebase and +// use protoc to generate stubs for your target language. +// +// This file will not be updated. Any minor versions of protocol 6 to follow +// should copy this file and modify the copy while maintaining backwards +// compatibility. Breaking changes, if any are required, will come +// in a subsequent major version with its own separate proto definition. +// +// Note that only the proto files included in a release tag of Terraform are +// official protocol releases. Proto files taken from other commits may include +// incomplete changes or features that did not make it into a final release. +// In all reasonable cases, plugin developers should take the proto file from +// the tag of the most recent release of Terraform, and not from the main +// branch or any other development branch. +// +syntax = "proto3"; +option go_package = "github.com/opentofu/opentofu/internal/tfplugin6"; + +import "google/protobuf/timestamp.proto"; + +package tfplugin6; + +// DynamicValue is an opaque encoding of terraform data, with the field name +// indicating the encoding scheme used. +message DynamicValue { + bytes msgpack = 1; + bytes json = 2; +} + +message Diagnostic { + enum Severity { + INVALID = 0; + ERROR = 1; + WARNING = 2; + } + Severity severity = 1; + string summary = 2; + string detail = 3; + AttributePath attribute = 4; +} + +message FunctionError { + string text = 1; + // The optional function_argument records the index position of the + // argument which caused the error. + optional int64 function_argument = 2; +} + +message AttributePath { + message Step { + oneof selector { + // Set "attribute_name" to represent looking up an attribute + // in the current object value. + string attribute_name = 1; + // Set "element_key_*" to represent looking up an element in + // an indexable collection type. + string element_key_string = 2; + int64 element_key_int = 3; + } + } + repeated Step steps = 1; +} + +message StopProvider { + message Request { + } + message Response { + string Error = 1; + } +} + +// RawState holds the stored state for a resource to be upgraded by the +// provider. It can be in one of two formats, the current json encoded format +// in bytes, or the legacy flatmap format as a map of strings. +message RawState { + bytes json = 1; + map flatmap = 2; +} + +enum StringKind { + PLAIN = 0; + MARKDOWN = 1; +} + +// Schema is the configuration schema for a Resource or Provider. +message Schema { + message Block { + int64 version = 1; + repeated Attribute attributes = 2; + repeated NestedBlock block_types = 3; + string description = 4; + StringKind description_kind = 5; + bool deprecated = 6; + } + + message Attribute { + string name = 1; + bytes type = 2; + Object nested_type = 10; + string description = 3; + bool required = 4; + bool optional = 5; + bool computed = 6; + bool sensitive = 7; + StringKind description_kind = 8; + bool deprecated = 9; + // write_only indicates that the attribute value will be provided via + // configuration and must be omitted from state. write_only must be + // combined with optional or required, and is only valid for managed + // resource schemas. + bool write_only = 11; + } + + message NestedBlock { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + GROUP = 5; + } + + string type_name = 1; + Block block = 2; + NestingMode nesting = 3; + int64 min_items = 4; + int64 max_items = 5; + } + + message Object { + enum NestingMode { + INVALID = 0; + SINGLE = 1; + LIST = 2; + SET = 3; + MAP = 4; + } + + repeated Attribute attributes = 1; + NestingMode nesting = 3; + + // MinItems and MaxItems were never used in the protocol, and have no + // effect on validation. + int64 min_items = 4 [deprecated = true]; + int64 max_items = 5 [deprecated = true]; + } + + // The version of the schema. + // Schemas are versioned, so that providers can upgrade a saved resource + // state when the schema is changed. + int64 version = 1; + + // Block is the top level configuration block for this schema. + Block block = 2; +} + +// ResourceIdentitySchema represents the structure and types of data used to identify +// a managed resource type. Effectively, resource identity is a versioned object +// that can be used to compare resources, whether already managed and/or being +// discovered. +message ResourceIdentitySchema { + // IdentityAttribute represents one value of data within resource identity. + // These are always used in resource identity comparisons. + message IdentityAttribute { + // name is the identity attribute name + string name = 1; + + // type is the identity attribute type + bytes type = 2; + + // required_for_import when enabled signifies that this attribute must be + // defined for ImportResourceState to complete successfully + bool required_for_import = 3; + + // optional_for_import when enabled signifies that this attribute is not + // required for ImportResourceState, because it can be supplied by the + // provider. It is still possible to supply this attribute during import. + bool optional_for_import = 4; + + // description is a human-readable description of the attribute in Markdown + string description = 5; + } + + // version is the identity version and separate from the Schema version. + // Any time the structure or format of identity_attributes changes, this version + // should be incremented. Versioning implicitly starts at 0 and by convention + // should be incremented by 1 each change. + // + // When comparing identity_attributes data, differing versions should always be treated + // as inequal. + int64 version = 1; + + // identity_attributes are the individual value definitions which define identity data + // for a managed resource type. This information is used to decode DynamicValue of + // identity data. + // + // These attributes are intended for permanent identity data and must be wholly + // representative of all data necessary to compare two managed resource instances + // with no other data. This generally should include account, endpoint, location, + // and automatically generated identifiers. For some resources, this may include + // configuration-based data, such as a required name which must be unique. + repeated IdentityAttribute identity_attributes = 2; +} + +// ResourceIdentityData is a separate message for better extensibility +message ResourceIdentityData { + // identity_data is the resource identity data for the given definition. It should + // be decoded using the identity schema. + // + // This data is considered permanent for the identity version and suitable for + // longer-term storage. + DynamicValue identity_data = 1; +} + + +message Function { + // parameters is the ordered list of positional function parameters. + repeated Parameter parameters = 1; + + // variadic_parameter is an optional final parameter which accepts + // zero or more argument values, in which Terraform will send an + // ordered list of the parameter type. + Parameter variadic_parameter = 2; + + // return is the function result. + Return return = 3; + + // summary is the human-readable shortened documentation for the function. + string summary = 4; + + // description is human-readable documentation for the function. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + + // deprecation_message is human-readable documentation if the + // function is deprecated. + string deprecation_message = 7; + + message Parameter { + // name is the human-readable display name for the parameter. + string name = 1; + + // type is the type constraint for the parameter. + bytes type = 2; + + // allow_null_value when enabled denotes that a null argument value can + // be passed to the provider. When disabled, Terraform returns an error + // if the argument value is null. + bool allow_null_value = 3; + + // allow_unknown_values when enabled denotes that only wholly known + // argument values will be passed to the provider. When disabled, + // Terraform skips the function call entirely and assumes an unknown + // value result from the function. + bool allow_unknown_values = 4; + + // description is human-readable documentation for the parameter. + string description = 5; + + // description_kind is the formatting of the description. + StringKind description_kind = 6; + } + + message Return { + // type is the type constraint for the function result. + bytes type = 1; + } +} + +// ServerCapabilities allows providers to communicate extra information +// regarding supported protocol features. This is used to indicate +// availability of certain forward-compatible changes which may be optional +// in a major protocol version, but cannot be tested for directly. +message ServerCapabilities { + // The plan_destroy capability signals that a provider expects a call + // to PlanResourceChange when a resource is going to be destroyed. + bool plan_destroy = 1; + + // The get_provider_schema_optional capability indicates that this + // provider does not require calling GetProviderSchema to operate + // normally, and the caller can used a cached copy of the provider's + // schema. + bool get_provider_schema_optional = 2; + + // The move_resource_state capability signals that a provider supports the + // MoveResourceState RPC. + bool move_resource_state = 3; +} + +// ClientCapabilities allows Terraform to publish information regarding +// supported protocol features. This is used to indicate availability of +// certain forward-compatible changes which may be optional in a major +// protocol version, but cannot be tested for directly. +message ClientCapabilities { + // The deferral_allowed capability signals that the client is able to + // handle deferred responses from the provider. + bool deferral_allowed = 1; + // The write_only_attributes_allowed capability signals that the client + // is able to handle write_only attributes for managed resources. + bool write_only_attributes_allowed = 2; +} + +// Deferred is a message that indicates that change is deferred for a reason. +message Deferred { + // Reason is the reason for deferring the change. + enum Reason { + // UNKNOWN is the default value, and should not be used. + UNKNOWN = 0; + // RESOURCE_CONFIG_UNKNOWN is used when the config is partially unknown and the real + // values need to be known before the change can be planned. + RESOURCE_CONFIG_UNKNOWN = 1; + // PROVIDER_CONFIG_UNKNOWN is used when parts of the provider configuration + // are unknown, e.g. the provider configuration is only known after the apply is done. + PROVIDER_CONFIG_UNKNOWN = 2; + // ABSENT_PREREQ is used when a hard dependency has not been satisfied. + ABSENT_PREREQ = 3; + } + // reason is the reason for deferring the change. + Reason reason = 1; +} + +service Provider { + //////// Information about what a provider supports/expects + + // GetMetadata returns upfront information about server capabilities and + // supported resource types without requiring the server to instantiate all + // schema information, which may be memory intensive. This RPC is optional, + // where clients may receive an unimplemented RPC error. Clients should + // ignore the error and call the GetProviderSchema RPC as a fallback. + rpc GetMetadata(GetMetadata.Request) returns (GetMetadata.Response); + + // GetSchema returns schema information for the provider, data resources, + // and managed resources. + rpc GetProviderSchema(GetProviderSchema.Request) returns (GetProviderSchema.Response); + // GetResourceIdentitySchemas returns the identity schemas for all managed + // resources. + rpc GetResourceIdentitySchemas(GetResourceIdentitySchemas.Request) returns (GetResourceIdentitySchemas.Response); + rpc ValidateProviderConfig(ValidateProviderConfig.Request) returns (ValidateProviderConfig.Response); + rpc ValidateResourceConfig(ValidateResourceConfig.Request) returns (ValidateResourceConfig.Response); + rpc ValidateDataResourceConfig(ValidateDataResourceConfig.Request) returns (ValidateDataResourceConfig.Response); + rpc UpgradeResourceState(UpgradeResourceState.Request) returns (UpgradeResourceState.Response); + // UpgradeResourceIdentityData should return the upgraded resource identity + // data for a managed resource type. + rpc UpgradeResourceIdentity(UpgradeResourceIdentity.Request) returns (UpgradeResourceIdentity.Response); + + //////// One-time initialization, called before other functions below + rpc ConfigureProvider(ConfigureProvider.Request) returns (ConfigureProvider.Response); + + //////// Managed Resource Lifecycle + rpc ReadResource(ReadResource.Request) returns (ReadResource.Response); + rpc PlanResourceChange(PlanResourceChange.Request) returns (PlanResourceChange.Response); + rpc ApplyResourceChange(ApplyResourceChange.Request) returns (ApplyResourceChange.Response); + rpc ImportResourceState(ImportResourceState.Request) returns (ImportResourceState.Response); + rpc MoveResourceState(MoveResourceState.Request) returns (MoveResourceState.Response); + rpc ReadDataSource(ReadDataSource.Request) returns (ReadDataSource.Response); + + //////// Ephemeral Resource Lifecycle + rpc ValidateEphemeralResourceConfig(ValidateEphemeralResourceConfig.Request) returns (ValidateEphemeralResourceConfig.Response); + rpc OpenEphemeralResource(OpenEphemeralResource.Request) returns (OpenEphemeralResource.Response); + rpc RenewEphemeralResource(RenewEphemeralResource.Request) returns (RenewEphemeralResource.Response); + rpc CloseEphemeralResource(CloseEphemeralResource.Request) returns (CloseEphemeralResource.Response); + + // Functions + + // GetFunctions returns the definitions of all functions. + rpc GetFunctions(GetFunctions.Request) returns (GetFunctions.Response); + + // CallFunction runs the provider-defined function logic and returns + // the result with any diagnostics. + rpc CallFunction(CallFunction.Request) returns (CallFunction.Response); + + //////// Graceful Shutdown + rpc StopProvider(StopProvider.Request) returns (StopProvider.Response); +} + +message GetMetadata { + message Request { + } + + message Response { + ServerCapabilities server_capabilities = 1; + repeated Diagnostic diagnostics = 2; + repeated DataSourceMetadata data_sources = 3; + repeated ResourceMetadata resources = 4; + + // functions returns metadata for any functions. + repeated FunctionMetadata functions = 5; + repeated EphemeralResourceMetadata ephemeral_resources = 6; + } + + message FunctionMetadata { + // name is the function name. + string name = 1; + } + + message DataSourceMetadata { + string type_name = 1; + } + + message ResourceMetadata { + string type_name = 1; + } + + message EphemeralResourceMetadata { + string type_name = 1; + } +} + +message GetProviderSchema { + message Request { + } + message Response { + Schema provider = 1; + map resource_schemas = 2; + map data_source_schemas = 3; + repeated Diagnostic diagnostics = 4; + Schema provider_meta = 5; + ServerCapabilities server_capabilities = 6; + + // functions is a mapping of function names to definitions. + map functions = 7; + map ephemeral_resource_schemas = 8; + } +} + +message ValidateProviderConfig { + message Request { + DynamicValue config = 1; + } + message Response { + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. + message Request { + string type_name = 1; + + // version is the schema_version number recorded in the state file + int64 version = 2; + + // raw_state is the raw states as stored for the resource. Core does + // not have access to the schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_state will be the json encoded + // state, or a legacy flat-mapped format. + RawState raw_state = 3; + } + message Response { + // new_state is a msgpack-encoded data structure that, when interpreted with + // the _current_ schema for this resource type, is functionally equivalent to + // that which was given in prior_state_raw. + DynamicValue upgraded_state = 1; + + // diagnostics describes any errors encountered during migration that could not + // be safely resolved, and warnings about any possibly-risky assumptions made + // in the upgrade process. + repeated Diagnostic diagnostics = 2; + } +} + +message ValidateResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ValidateDataResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ConfigureProvider { + message Request { + string terraform_version = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. + message Request { + string type_name = 1; + DynamicValue current_state = 2; + bytes private = 3; + DynamicValue provider_meta = 4; + ClientCapabilities client_capabilities = 5; + ResourceIdentityData current_identity = 6; + } + message Response { + DynamicValue new_state = 1; + repeated Diagnostic diagnostics = 2; + bytes private = 3; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 4; + ResourceIdentityData new_identity = 5; + } +} + +message PlanResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue proposed_new_state = 3; + DynamicValue config = 4; + bytes prior_private = 5; + DynamicValue provider_meta = 6; + ClientCapabilities client_capabilities = 7; + ResourceIdentityData prior_identity = 8; + } + + message Response { + DynamicValue planned_state = 1; + repeated AttributePath requires_replace = 2; + bytes planned_private = 3; + repeated Diagnostic diagnostics = 4; + + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 5; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 6; + ResourceIdentityData planned_identity = 7; + } +} + +message ApplyResourceChange { + message Request { + string type_name = 1; + DynamicValue prior_state = 2; + DynamicValue planned_state = 3; + DynamicValue config = 4; + bytes planned_private = 5; + DynamicValue provider_meta = 6; + ResourceIdentityData planned_identity = 7; + } + message Response { + DynamicValue new_state = 1; + bytes private = 2; + repeated Diagnostic diagnostics = 3; + + // This may be set only by the helper/schema "SDK" in the main Terraform + // repository, to request that Terraform Core >=0.12 permit additional + // inconsistencies that can result from the legacy SDK type system + // and its imprecise mapping to the >=0.12 type system. + // The change in behavior implied by this flag makes sense only for the + // specific details of the legacy SDK type system, and are not a general + // mechanism to avoid proper type handling in providers. + // + // ==== DO NOT USE THIS ==== + // ==== THIS MUST BE LEFT UNSET IN ALL OTHER SDKS ==== + // ==== DO NOT USE THIS ==== + bool legacy_type_system = 4; + ResourceIdentityData new_identity = 5; + } +} + +message ImportResourceState { + message Request { + string type_name = 1; + string id = 2; + ClientCapabilities client_capabilities = 3; + ResourceIdentityData identity = 4; + } + + message ImportedResource { + string type_name = 1; + DynamicValue state = 2; + bytes private = 3; + ResourceIdentityData identity = 4; + } + + message Response { + repeated ImportedResource imported_resources = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message MoveResourceState { + message Request { + // The address of the provider the resource is being moved from. + string source_provider_address = 1; + + // The resource type that the resource is being moved from. + string source_type_name = 2; + + // The schema version of the resource type that the resource is being + // moved from. + int64 source_schema_version = 3; + + // The raw state of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_state = 4; + + // The resource type that the resource is being moved to. + string target_type_name = 5; + + // The private state of the resource being moved. + bytes source_private = 6; + + // The raw identity of the resource being moved. Only the json field is + // populated, as there should be no legacy providers using the flatmap + // format that support newly introduced RPCs. + RawState source_identity = 7; + + // The identity schema version of the resource type that the resource + // is being moved from. + int64 source_identity_schema_version = 8; + } + + message Response { + // The state of the resource after it has been moved. + DynamicValue target_state = 1; + + // Any diagnostics that occurred during the move. + repeated Diagnostic diagnostics = 2; + + // The private state of the resource after it has been moved. + bytes target_private = 3; + + ResourceIdentityData target_identity = 4; + } +} + +message ReadDataSource { + message Request { + string type_name = 1; + DynamicValue config = 2; + DynamicValue provider_meta = 3; + ClientCapabilities client_capabilities = 4; + } + message Response { + DynamicValue state = 1; + repeated Diagnostic diagnostics = 2; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 3; + } +} + +message GetFunctions { + message Request {} + + message Response { + // functions is a mapping of function names to definitions. + map functions = 1; + + // diagnostics is any warnings or errors. + repeated Diagnostic diagnostics = 2; + } +} + +message CallFunction { + message Request { + // name is the name of the function being called. + string name = 1; + + // arguments is the data of each function argument value. + repeated DynamicValue arguments = 2; + } + + message Response { + // result is result value after running the function logic. + DynamicValue result = 1; + + // error is any error from the function logic. + FunctionError error = 2; + } +} + +message ValidateEphemeralResourceConfig { + message Request { + string type_name = 1; + DynamicValue config = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +message OpenEphemeralResource { + message Request { + string type_name = 1; + DynamicValue config = 2; + ClientCapabilities client_capabilities = 3; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + DynamicValue result = 3; + optional bytes private = 4; + // deferred is set if the provider is deferring the change. If set the caller + // needs to handle the deferral. + Deferred deferred = 5; + } +} + +message RenewEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + optional google.protobuf.Timestamp renew_at = 2; + optional bytes private = 3; + } +} + +message CloseEphemeralResource { + message Request { + string type_name = 1; + optional bytes private = 2; + } + message Response { + repeated Diagnostic diagnostics = 1; + } +} + +// Returns resource identity schemas for all resources +message GetResourceIdentitySchemas { + message Request { + } + message Response { + // identity_schemas is a mapping of resource type names to their identity schemas. + map identity_schemas = 1; + + // diagnostics is the collection of warning and error diagnostics for this request. + repeated Diagnostic diagnostics = 2; + } +} + +message UpgradeResourceIdentity { + message Request { + // type_name is the managed resource type name + string type_name = 1; + + // version is the version of the resource identity data to upgrade + int64 version = 2; + + // raw_identity is the raw identity as stored for the resource. Core does + // not have access to the identity schema of prior_version, so it's the + // provider's responsibility to interpret this value using the + // appropriate older schema. The raw_identity will be json encoded. + RawState raw_identity = 3; + } + message Response { + // upgraded_identity returns the upgraded resource identity data + ResourceIdentityData upgraded_identity = 1; + + // diagnostics is the collection of warning and error diagnostics for this request + repeated Diagnostic diagnostics = 2; + } +} diff --git a/network-poc/static/docs/provider-references.md b/network-poc/static/docs/provider-references.md new file mode 100644 index 0000000..d117856 --- /dev/null +++ b/network-poc/static/docs/provider-references.md @@ -0,0 +1,398 @@ +# Provider References Through the OpenTofu Language, Codebase and State + +The concept of Providers has changed and evolved over the lifetime of OpenTofu, with many of the legacy configuration options still supported today. This document aims to walk through examples and map them to structures within OpenTofu's code. + +## Existing Documentation + +It is recommended that you have the following open when reading through the rest of this document: +* https://opentofu.org/docs/language/providers/ +* https://opentofu.org/docs/language/providers/requirements/ +* https://opentofu.org/docs/language/providers/configuration/ + +## What is a Provider? + +In general terms, a provider is a piece of code which interfaces OpenTofu with resources. For example, the AWS provider describes what resources it is able to read/manage, such as s3 buckets and ec2 instances. + +In most cases providers live in a registry, are downloaded into the local path, and executed to provide a versioned GRPC server to OpenTofu. They could potentially be dynamically loaded directly into the running OpenTofu application, but a distinct process helps with fault tolerance and potential isolation issues. + +Providers also may define functions that can be called from the OpenTofu configuration. See [Provider Functions](#Provider-Functions) below for more information. + +It is HIGHLY recommended to vet all providers you execute locally as they are not sandboxed at all. There are discussions ongoing on how to improve safety in that respect. + +Providers also may be configured with values in a HCL block. This allows the provider have some "global" configuration that does not need to be passed in every resource/data instance, a common example being credentials. + + +## Language References + +### History and Addressing of Providers + +Provider references and configuration have an interesting history, which leads to the system we have today. Note: some of this history has been summarized or omitted for clarity. + +#### Provider Type + +Prior to v0.10.0, providers were built directly into the binary and not released/versioned separately. They only had a single identifier, which we now call "Provider Type". + +Example: +```hcl +provider "aws" { + region = "us-east-1" +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" +} +``` + +This requires the `addrs.Provider{Type = "aws"}` provider, gives it some configuration, and then creates a `s3_bucket` with it due to the type prefix of `aws`. This provider also is referenceable via `addrs.LocalProviderConfig{LocalName = "aws"}`. Note: the Type and LocalName used to be the same field. These are distinct concepts that diverge in later examples. + + +#### Provider Alias + +You also may need to have multiple configurations of the "aws" provider, perhaps with different credentials or regions. These configurations are distinguished by "Provider Alias". + + +Example: +```hcl +provider "aws" { + region = "us-east-1" + alias = "default" +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = aws.default +} +``` + +As with the previous example, this requires the `addrs.Provider{Type = "aws"}` provider, gives it some configuration under the alias "default". The `s3_bucket` resource now refers to the provider explicitly via `addrs.LocalProviderConfig{LocalName = "aws", Alias = "default"}`. Note: the `addrs.Provider{Type = "aws"}` reference is still partially used due to some odd legacy interactions. + + +#### Provider Versions + +Since v0.10.0, providers are distributed via a registry. This allows provider versions to be decoupled from the main application version. Provider bugfixes and new features can be released independently of the main application. All providers/configs with the same `addrs.Provider` must use the same binary and must have compatible version constraints. + +```hcl +provider "aws" { + region = "us-east-1" + alias = "default" + version = 0.124 # Deprecated by required_providers +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = aws.default +} +``` + +The result is identical to the previous case, except now the version constraint is tracked in the `config.Module` structure, with `addrs.Provider{Type = "aws"}` as the key. Once all constraints are known, `tofu init` downloads the providers from the registry into a local cache for later execution. + +#### Module Provider References + +Prior to 0.11.0, modules would share/override provider configurations. There was no distinction between configuration of parent or child module's providers. This implicit inheritance caused a variety of issues and limitations. The `module -> providers` map field was introduced to allow explicit passing of provider configurations to child modules. + +```hcl +# main.tf + +provider "aws" { + region = "us-east-1" + alias = "default" + version = 0.124 # Deprecated by required_providers +} + +module "my_mod" { + source = "./mod" + # Only the "unaliased" providers are passed if this is omitted. + providers = { + aws = aws.default + } +} +``` + +```hcl +# ./mod/mod.tf +provider "aws" { # Deprecated by required_providers + version = ">= 0.1" # Deprecated by required_providers +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = aws +} +``` + +In the root module (main configuration), we require the `addrs.Provider{Type = "aws"}` with a version constraint of "0.124". A configuration for that provider exists at `addrs.LocalProviderConfig{LocalName = "aws", Alias = "default"}` within the root module and is not automatically accessible from the child module. A new reference is introduced, which can be used globally: `addrs.AbsProviderConfig{Module: Root, Provider: addrs.Provider{Type = "aws"}, Alias = "default"}`. + +The child module is passed the `addrs.AbsProviderConfig` and is internally referenceable within the module under `addrs.LocalProviderConfig{LocalName: "aws"}`. That global configuration is copied and merged with the configuration within that module, which in this case adds an additional version constraint. + +Within that module, `addrs.LocalProviderConfig{LocalName: "aws"}` now refers to `addrs.Provider{Type = "aws"}` and the merged configuration for that provider. + +If multiple instances of the same provider are needed, the alias can be provided in the module's "providers" block + +```hcl +# main.tf + +provider "aws" { + region = "us-east-1" + alias = "default" + version = 0.124 # Deprecated by required_providers +} + +module "my_mod" { + source = "./mod" + # Only the "unaliased" providers are passed if this is omitted. + providers = { + aws.foo = aws.default + } +} +``` + +```hcl +# ./mod/mod.tf +provider "aws" { # Deprecated by required_providers + version = ">= 0.1" # Deprecated by required_providers + alias = "foo" +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = aws.foo +} +``` + +The root module's explanation is nearly identical, the primary change is to the addressing in the child module. + +The child module is passed the `addrs.AbsProviderConfig` and is internally referenceable within the module under `addrs.LocalProviderConfig{LocalName: "aws", Alias = "foo"}`. That global configuration is copied and merged with the configuration within that module, which in this case adds an additional version constraint. + +Within that module, `addrs.LocalProviderConfig{LocalName: "aws", Alias = "foo"}` now refers to `addrs.Provider{Type = "aws"}` and the merged configuration for that provider. + +#### Required Providers (Legacy) + +With the change in 0.11.0 adding the `providers` field, it is still unclear when a child module's provider is "incorrectly configured" or if the parent module has forgotten an entry in the `providers` field. + +To solve this, `terraform -> required_providers` was introduced. The initial version of this feature was a direct mapping between "Provider Type" and "Provider Version Constraint". + +```hcl +terraform { + required_providers { + aws = "0.124" + } +} + +provider "aws" { + region = "us-east-1" + alias = "default" +} + +module "my_mod" { + source = "./mod" + providers = { + aws = aws.default + } +} +``` + +```hcl +# ./mod/mod.tf +terraform { + required_providers { + aws = ">= 0.1" + } +} + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = aws +} +``` + +The references are unchanged, except for the dependencies are now more explicit. This form of `required_providers` is no longer supported. + + +#### Provider Names / Namespaces / Registries + +Other organizations started to create providers over time (along with their own registries) and the concept of referencing a provider needed to be expanded. In v0.13.0 the concept of `addrs.Provider` was expanded to include `Namespace` and `Hostname`. + +Previously, all providers within the registry had global names "aws", "datadog", "gcp", etc... As forks were introduced and the authoring of providers took off, the `Namespace` concept was introduced. It usually maps to the GitHub user/org that owns it, but it is not a strict requirement (especially in third-party registries). + +Organizations also wanted more control over their providers for both development and security purposes. The providers registry hostname was included in the spec. + +Additionally, the previous understanding of "datadog" may refer to "datadog/datadog" or "user/datadog" and is unclear if they are both included in the project. By decoupling `addrs.Provider.Type` and `addrs.LocalProviderConfig.LocalName`, both could be used in the same module under different names. Additionally the same concept can be used to have the LocalName "datadog" refer to "user/datadog-fork" without having to rewrite the whole project's config. + + +```hcl +terraform { + required_providers { + awsname = { # name added for clarity, usually Type == LocalName + #source = "aws" + #source = "hashicorp/aws" + source = "registry.opentofu.org/hashicorp/aws" + version = "0.124" + } + } +} + +provider "awsname" { + region = "us-east-1" + alias = "default" +} + +module "my_mod" { + source = "./mod" + providers = { + modaws = awsname.default + } +} +``` + +```hcl +# ./mod/mod.tf +terraform { + required_providers { + modaws = { + source = "aws" + version = ">= 0.1" + } + } +} + + +resource "aws_s3_bucket" "foo" { + bucket_name = "foo" + provider = modaws +} +``` + +The required_providers "source" field in the root module decomposed into `addrs.Provider{Type="aws", Namespace="hashicorp", Hostname="registry.opentofu.org"}`. As the default namespace is "hashicorp" and the default hostname is "registry.opentofu.org", we will continue to use the shorthand `addrs.Provider{Type="aws"}`. Next `addrs.LocalProviderConfig{LocalName: "aws_name"}` is created and within the root module maps to `addrs.Provider{Type="aws"}`. This provider local name is then used in all subsequent references within the root module. The configuration is then mapped to `addrs.AbsProviderConfig{Module: Root, Provider: addrs.Provider{Type = "aws"}, Alias = "default"}` globally. + +The child module is passed the `addrs.AbsProviderConfig` and is internally referenceable within the module under `addrs.LocalProviderConfig{LocalName: "modaws"}`. + +Within that module, `addrs.LocalProviderConfig{LocalName: "modaws"}` now points at `addrs.Provider{Type = "aws"}` and is effectively replaced with `addrs.AbsProviderConfig{Module: Root, Provider: addrs.Provider{Type = "aws"}, Alias = "default"}` at runtime. This optimizes running as few provider instances as possible. + +If a new provider configuration were added to the module: +```hcl +provider "modaws" { + region = "us-west-2" +} +``` +This would negate the override / deduplication above and result in `addrs.AbsProviderConfig{Module: MyMod, Provider: addrs.Provider{Type = "aws"}}`. + +#### Multiple Provider Aliases + +Multiple provider aliases can be supplied in required_providers via `configuration_aliases`. This requires that a caller of the module provide the requested aliases explicitly. + +Example: + +```hcl +terraform { + required_providers { + awsname = { # name added for clarity, usually Type == LocalName + source = "registry.opentofu.org/hashicorp/aws" + version = "0.124" + } + } +} + +provider "awsname" { + region = "us-east-1" + alias = "default" +} + +module "my_mod" { + source = "./mod" + providers = { + modaws.foo = awsname.default + modaws.bar = awsname + } +} +``` + +```hcl +# ./mod/mod.tf +terraform { + required_providers { + modaws = { + source = "aws" + version = ">= 0.1" + configuration_aliases = [ modaws.foo, modaws.bar ] + } + } +} +``` + +### Multiple Provider Instances + +In OpenTofu 1.9.0, we introduced the concept of a "provider instance". This allows an aliased provider to have multiple instances based on the same configuration differentiated by a for_each expression. + +```hcl +# main.tofu + +provider "cloudflare" { + alias = "by_account" + for_each = local.cloudflare_accounts + account_id = each.key + auth_key = each.value +} + +locals { + enabled_cloudflare_accounts = { + for acct, cfg in local.cloudflare_accounts : acct => cfg + if cfg.enabled + } +} + +module "my_mod" { + source = "./foo" + for_each = local.enabled_cloudflare_accounts + account_id = each.key + + providers { + cloudflare = cloudflare.by_account[each.key] + } +} + +resource "cloudflare_r2_bucket" "bucket" { + for_each = local.cloudflare_accounts + account_id = each.key + provider = cloudflare.by_account[each.key] +} +``` + +### Representation in State + +Resources in the state file note the `addrs.AbsProviderConfig` required to modify them. + +Prior to 1.9.0, all instances (for_each/count) of a resource must use the same provider and would have the provider stored in a single field at the resource level, not resource instance level. + +After 1.9.0 (provider iteration), the "provider" field can now exist on either the resource or the resource instance and can include a "provider instance key" appended to the `addrs.AbsProviderConfig`. + * If provider config instances differ per resource instance, the "provider" field will exist only on the resource instances. + - Although the provider instance key may vary between resource instances of the same resource, the `addrs.AbsProviderConfig` component must be identical. + * If the provider config instances are identical per resource instance, the provider field will only exist on the resource. + +Note: This section should be expanded with examples. + +Note: `tofu show -json` and the internal statefile format are different and do not always line up one-to-one. + +## Provider Workflow + +When `config.Module` is built from `config.Files`, each module maintains: +* ProviderConfigs: map of `provider_name.provider_alias -> config.Provider` from provider config blocks in the parsed config +* ProviderRequirements: map of `provider_local_name -> config.RequiredProvider` from `terraform -> required_providers` +* ProviderLocalNames: map of `addrs.Provider -> provider_name` + +The full list of required provider types is collated, downloaded, hashed and cached in the .terraform directory during init. + +Providers are then added to the graph in a few transformers: +* ProviderConfigTransformer: Adds configured providers to the graph +* MissingProviderTransformer: Adds unconfigured but required providers to the graph +* ProviderTransformer: Links provider nodes to self reported nodes that require them +* ProviderFunctionTransformer: Links provider nodes to other nodes by inspecting their "OpenTofu Function References" +* ProviderPruneTransformer: Removes provider nodes that are not in use by other nodes + +Providers are then managed and scoped by the EvalContextBuiltin where the actual `provider.Interface`s are created and attached to resources. + + +## Provider Functions + +Providers also may supply functions, either unconfigured or configured. +* `providers::aws::arn_parse(var.arn)` +* `providers::aws::us::arn_parse(var.arn)` diff --git a/network-poc/static/docs/resource-instance-change-lifecycle.md b/network-poc/static/docs/resource-instance-change-lifecycle.md new file mode 100644 index 0000000..6357521 --- /dev/null +++ b/network-poc/static/docs/resource-instance-change-lifecycle.md @@ -0,0 +1,372 @@ +# OpenTofu Resource Instance Change Lifecycle + +This document describes the relationships between the different operations +called on a OpenTofu Provider to handle a change to a resource instance. + +![](https://user-images.githubusercontent.com/20180/172506401-777597dc-3e6e-411d-9580-b192fd34adba.png) + +The resource instance operations all both consume and produce objects that +conform to the schema of the selected resource type. + +The overall goal of this process is to take a **Configuration** and a +**Previous Run State**, merge them together using resource-type-specific +planning logic to produce a **Planned State**, and then change the remote +system to match that planned state before finally producing the **New State** +that will be saved in order to become the **Previous Run State** for the next +operation. + +The various object values used in different parts of this process are: + +* **Configuration**: Represents the values the user wrote in the configuration, + after any automatic type conversions to match the resource type schema. + + Any attributes not defined by the user appear as null in the configuration + object. If an argument value is derived from an unknown result of another + resource instance, its value in the configuration object could also be + unknown. + +* **Prior State**: The provider's representation of the current state of the + remote object at the time of the most recent read. + +* **Proposed New State**: OpenTofu Core uses some built-in logic to perform + an initial basic merger of the **Configuration** and the **Prior State** + which a provider may use as a starting point for its planning operation. + + The built-in logic primarily deals with the expected behavior for attributes + marked in the schema as "computed". If an attribute is only "computed", + OpenTofu expects the value to only be chosen by the provider and it will + preserve any Prior State. If an attribute is marked as "computed" and + "optional", this means that the user may either set it or may leave it + unset to allow the provider to choose a value. + + OpenTofu Core therefore constructs the proposed new state by taking the + attribute value from Configuration if it is non-null, and then using the + Prior State as a fallback otherwise, thereby helping a provider to + preserve its previously-chosen value for the attribute where appropriate. + +* **Initial Planned State** and **Final Planned State** are both descriptions + of what the associated remote object ought to look like after completing + the planned action. + + There will often be parts of the object that the provider isn't yet able to + predict, either because they will be decided by the remote system during + the apply step or because they are derived from configuration values from + other resource instances that are themselves not yet known. The provider + must mark these by including unknown values in the state objects. + + The distinction between the _Initial_ and _Final_ planned states is that + the initial one is created during OpenTofu Core's planning phase based + on a possibly-incomplete configuration, whereas the final one is created + during the apply step once all of the dependencies have already been + updated and so the configuration should then be wholly known. + +* **New State** is a representation of the result of whatever modifications + were made to the remote system by the provider during the apply step. + + The new state must always be wholly known, because it represents the + actual state of the system, rather than a hypothetical future state. + +* **Previous Run State** is the same object as the **New State** from + the previous run of OpenTofu. This is exactly what the provider most + recently returned, and so it will not take into account any changes that + may have been made outside of OpenTofu in the meantime, and it may conform + to an earlier version of the resource type schema and therefore be + incompatible with the _current_ schema. + +* **Upgraded State** is derived from **Previous Run State** by using some + provider-specified logic to upgrade the existing data to the latest schema. + However, it still represents the remote system as it was at the end of the + last run, and so still doesn't take into account any changes that may have + been made outside of OpenTofu. + +* The **Import ID** and **Import Stub State** are both details of the special + process of importing pre-existing objects into a OpenTofu state, and so + we'll wait to discuss those in a later section on importing. + + +## Provider Protocol API Functions + +The following sections describe the three provider API functions that are +called to plan and apply a change, including the expectations OpenTofu Core +enforces for each. + +For historical reasons, the original OpenTofu SDK is exempt from error +messages produced when certain assumptions are violated, but violating them +will often cause downstream errors nonetheless, because OpenTofu's workflow +depends on these contracts being met. + +The following section uses the word "attribute" to refer to the named +attributes described in the resource type schema. A schema may also include +nested blocks, which contain their _own_ set of attributes; the constraints +apply recursively to these nested attributes too. + +The following are the function names used in provider protocol version 6. +Protocol version 5 has the same set of operations but uses some +marginally-different names for them, because we used protocol version 6 as an +opportunity to tidy up some names that had been awkward before. + +### ValidateResourceConfig + +`ValidateResourceConfig` takes the **Configuration** object alone, and +may return error or warning diagnostics in response to its attribute values. + +`ValidateResourceConfig` is the provider's opportunity to apply custom +validation rules to the schema, allowing for constraints that could not be +expressed via schema alone. + +In principle a provider can make any rule it wants here, although in practice +providers should typically avoid reporting errors for values that are unknown. +OpenTofu Core will call this function multiple times at different phases +of evaluation, and guarantees to _eventually_ call with a wholly-known +configuration so that the provider will have an opportunity to belatedly catch +problems related to values that are initially unknown during planning. + +If a provider intends to choose a default value for a particular +optional+computed attribute when left as null in the configuration, the +provider _must_ tolerate that attribute being unknown in the configuration in +order to get an opportunity to choose the default value during the later +plan or apply phase. + +The validation step does not produce a new object itself and so it cannot +modify the user's supplied configuration. + +### PlanResourceChange + +The purpose of `PlanResourceChange` is to predict the approximate effect of +a subsequent apply operation, allowing OpenTofu to render the plan for the +user and to propagate the predictable subset of results downstream through +expressions in the configuration. + +This operation can base its decision on any combination of **Configuration**, +**Prior State**, and **Proposed New State**, as long as its result fits the +following constraints: + +* Any attribute that was non-null in the configuration must either preserve + the exact configuration value or return the corresponding attribute value + from the prior state. (Do the latter if you determine that the change is not + functionally significant, such as if the value is a JSON string that has + changed only in the positioning of whitespace.) + +* Any attribute that is marked as computed in the schema _and_ is null in the + configuration may be set by the provider to any arbitrary value of the + expected type. + +* If a computed attribute has any _known_ value in the planned new state, the + provider will be required to ensure that it is unchanged in the new state + returned by `ApplyResourceChange`, or return an error explaining why it + changed. Set an attribute to an unknown value to indicate that its final + result will be determined during `ApplyResourceChange`. + +`PlanResourceChange` is actually called twice per run for each resource type. + +The first call is during the planning phase, before OpenTofu prints out a +diff to the user for confirmation. Because no changes at all have been applied +at that point, the given **Configuration** may contain unknown values as +placeholders for the results of expressions that derive from unknown values +of other resource instances. The result of this initial call is the +**Initial Planned State**. + +If the user accepts the plan, OpenTofu will call `PlanResourceChange` a +second time during the apply step, and that call is guaranteed to have a +wholly-known **Configuration** with any values from upstream dependencies +taken into account already. The result of this second call is the +**Final Planned State**. + +OpenTofu Core compares the final with the initial planned state, enforcing +the following additional constraints along with those listed above: + +* Any attribute that had a known value in the **Initial Planned State** must + have an identical value in the **Final Planned State**. + +* Any attribute that had an unknown value in the **Initial Planned State** may + either remain unknown in the second _or_ take on any known value that + conforms to the unknown value's type constraint. + +The **Final Planned State** is what passes to `ApplyResourceChange`, as +described in the following section. + +### ApplyResourceChange + +The `ApplyResourceChange` function is responsible for making calls into the +remote system to make remote objects match the **Final Planned State**. During +that operation, the provider should decide on final values for any attributes +that were left unknown in the **Final Planned State**, and thus produce the +**New State** object. + +`ApplyResourceChange` also receives the **Prior State** so that it can use it +to potentially implement more "surgical" changes to particular parts of +the remote objects by detecting portions that are unchanged, in cases where the +remote API supports partial-update operations. + +The **New State** object returned from the provider must meet the following +constraints: + +* Any attribute that had a known value in the **Final Planned State** must have + an identical value in the new state. In particular, if the remote API + returned a different serialization of the same value then the provider must + preserve the form the user wrote in the configuration, and _must not_ return + the normalized form produced by the provider. + +* Any attribute that had an unknown value in the **Final Planned State** must + take on a known value whose type conforms to the type constraint of the + unknown value. No unknown values are permitted in the **New State**. + +After calling `ApplyResourceChange` for each resource instance in the plan, +and dealing with any other bookkeeping to return the results to the user, +a single OpenTofu run is complete. OpenTofu Core saves the **New State** +in a state snapshot for the entire configuration, so it'll be preserved for +use on the next run. + +When the user subsequently runs OpenTofu again, the **New State** becomes +the **Previous Run State** verbatim, and passes into `UpgradeResourceState`. + +### UpgradeResourceState + +Because the state values for a particular resource instance persist in a +saved state snapshot from one run to the next, OpenTofu Core must deal with +the possibility that the user has upgraded to a newer version of the provider +since the last run, and that the new provider version has an incompatible +schema for the relevant resource type. + +OpenTofu Core therefore begins by calling `UpgradeResourceState` and passing +the **Previous Run State** in a _raw_ form, which in current protocol versions +is the raw JSON data structure as was stored in the state snapshot. OpenTofu +Core doesn't have access to the previous schema versions for a provider's +resource types, so the provider itself must handle the data decoding in this +upgrade function. + +The provider can then use whatever logic is appropriate to update the shape +of the data to conform to the current schema for the resource type. Although +OpenTofu Core has no way to enforce it, a provider should only change the +shape of the data structure and should _not_ change the meaning of the data. +In particular, it should not try to update the state data to capture any +changes made to the corresponding remote object outside of OpenTofu. + +This function then returns the **Upgraded State**, which captures the same +information as the **Previous Run State** but does so in a way that conforms +to the current version of the resource type schema, which therefore allows +OpenTofu Core to interact with the data fully for subsequent steps. + +### ReadResource + +Although OpenTofu typically expects to have exclusive control over any remote +object that is bound to a resource instance, in practice users may make changes +to those objects outside of OpenTofu, causing OpenTofu's records of the +object to become stale. + +The `ReadResource` function asks the provider to make a best effort to detect +any such external changes and describe them so that OpenTofu Core can use +an up-to-date **Prior State** as the input to the next `PlanResourceChange` +call. + +This is always a best effort operation because there are various reasons why +a provider might not be able to detect certain changes. For example: +* Some remote objects have write-only attributes, which means that there is + no way to determine what value is currently stored in the remote system. +* There may be new features of the underlying API which the current provider + version doesn't know how to ask about. + +OpenTofu Core expects a provider to carefully distinguish between the +following two situations for each attribute: +* **Normalization**: the remote API has returned some data in a different form + than was recorded in the **Previous Run State**, but the meaning is unchanged. + + In this case, the provider should return the exact value from the + **Previous Run State**, thereby preserving the value as it was written by + the user in the configuration and thus avoiding unwanted cascading changes to + elsewhere in the configuration. +* **Drift**: the remote API returned data that is materially different from + what was recorded in the **Previous Run State**, meaning that the remote + system's behavior no longer matches what the configuration previously + requested. + + In this case, the provider should return the value from the remote system, + thereby discarding the value from the **Previous Run State**. When a + provider does this, OpenTofu _may_ report it to the user as a change + made outside of OpenTofu, if OpenTofu Core determined that the detected + change was a possible cause of another planned action for a downstream + resource instance. + +This operation returns the **Prior State** to use for the next call to +`PlanResourceChange`, thus completing the circle and beginning this process +over again. + +## Handling of Nested Blocks in Configuration + +Nested blocks are a configuration-only construct and so the number of blocks +cannot be changed on the fly during planning or during apply: each block +represented in the configuration must have a corresponding nested object in +the planned new state and new state, or OpenTofu Core will raise an error. + +If a provider wishes to report about new instances of the sub-object type +represented by nested blocks that are created implicitly during the apply +operation -- for example, if a compute instance gets a default network +interface created when none are explicitly specified -- this must be done via +separate "computed" attributes alongside the nested blocks. This could be list +or map of objects that includes a mixture of the objects described by the +nested blocks in the configuration and any additional objects created implicitly +by the remote system. + +Provider protocol version 6 introduced the new idea of structural-typed +attributes, which are a hybrid of attribute-style syntax but nested-block-style +interpretation. For providers that use structural-typed attributes, they must +follow the same rules as for a nested block type of the same nesting mode. + +## Import Behavior + +The main resource instance change lifecycle is concerned with objects whose +entire lifecycle is driven through OpenTofu, including the initial creation +of the object. + +As an aid to those who are adopting OpenTofu as a replacement for existing +processes or software, OpenTofu also supports adopting pre-existing objects +to bring them under OpenTofu's management without needing to recreate them +first. + +When using this facility, the user provides the address of the resource +instance they wish to bind the existing object to, and a string representation +of the identifier of the existing object to be imported in a syntax defined +by the provider on a per-resource-type basis, which we'll call the +**Import ID**. + +The import process trades the user's **Import ID** for a special +**Import Stub State**, which behaves as a placeholder for the +**Previous Run State** pretending as if a previous OpenTofu run is what had +created the object. + +### ImportResourceState + +The `ImportResourceState` operation takes the user's given **Import ID** and +uses it to verify that the given object exists and, if so, to retrieve enough +data about it to produce the **Import Stub State**. + +OpenTofu Core will always pass the returned **Import Stub State** to the +normal `ReadResource` operation after `ImportResourceState` returns it, so +in practice the provider may populate only the minimal subset of attributes +that `ReadResource` will need to do its work, letting the normal function +deal with populating the rest of the data to match what is currently set in +the remote system. + +For the same reasons that `ReadResource` is only a _best effort_ at detecting +changes outside of OpenTofu, a provider may not be able to fully support +importing for all resource types. In that case, the provider developer must +choose between the following options: + +* Perform only a partial import: the provider may choose to leave certain + attributes set to `null` in the **Prior State** after both + `ImportResourceState` and the subsequent `ReadResource` have completed. + + In this case, the user can provide the missing value in the configuration + and thus cause the next `PlanResourceChange` to plan to update that value + to match the configuration. The provider's `PlanResourceChange` function + must be ready to deal with the attribute being `null` in the + **Prior State** and handle that appropriately. +* Return an error explaining why importing isn't possible. + + This is a last resort because of course it will then leave the user unable + to bring the existing object under OpenTofu's management. However, if a + particular object's design doesn't suit importing then it can be a better + user experience to be clear and honest that the user must replace the object + as part of adopting OpenTofu, rather than to perform an import that will + leave the object in a situation where OpenTofu cannot meaningfully manage + it. diff --git a/network-poc/static/docs/state_encryption.md b/network-poc/static/docs/state_encryption.md new file mode 100644 index 0000000..e173971 --- /dev/null +++ b/network-poc/static/docs/state_encryption.md @@ -0,0 +1,309 @@ +# State encryption + +This document details our intended implementation of the state and plan encryption feature. + +## Notes + +This document mentions `HCL` as a short-form for OpenTofu code. Unless otherwise specified, everything written also applies to the [JSON-equivalent of the HCL code](https://opentofu.org/docs/language/syntax/json/). + +## Goals + +The goal of this feature is to allow OpenTofu users to fully encrypt state files when they are stored on the local disk or transferred to a remote backend. The feature should also allow reading from an encrypted remote backend using the `terraform_remote_state` data source. The encrypted version should still be a valid JSON file, but not necessarily a valid state file. + +Furthermore, this feature should allow users to encrypt plan files when they are stored. However, plan files are not JSON, they are undocumented binary files and should be treated as such. + +For the encryption key, users should be able to specify a key directly, use a remote key provider (such as AWS KMS, etc.), or create derivative keys from another key source. The primary encryption method should be AES-GCM, but the implementation should be open to different encryption methods. The user should also have the ability to decrypt a state or plan file with one (older) key and then re-encrypt data with a newer key. Multiple fallbacks should be avoided in the implementation. + +To enable use cases where multiple teams need to collaborate, the user should be able to specify separate encryption methods and keys for individual uses, especially for the `terraform_remote_state` data source. However, to simplify configuration, the user should be able to specify a default configuration for all remote state data sources. + +It is the goal of this feature to let users specify their encryption configuration both in (HCL) code and in environment variables. The latter is necessary to allow users the reuse of code for both encrypted and unencrypted state storage. + +Finally, it is the goal of the encryption feature to make available a library that third party tooling can use to encrypt and decrypt state. This may be implemented as a package within the OpenTofu repository, or as a standalone repository. + +## Possible future goals + +This section describes possible future goals. However, these goals are merely aspirations, and we may or may not implement them, or implement them differently based on community feedback. We describe these aspirations here to make clear which features we intentionally left out of scope for the current implementation. + +Users use CI/CD systems or security scanners that need to read the state or plan files, but may not fully trust these systems. In the future, the user should be able to specify partial encryption. This encryption type would only encrypt sensitive values instead of the whole state file. + +At this time, due to the limitations on passing providers through to modules, encryption configuration is global. However, in the future, the user should be able to create a module that carries along their own encryption method and how it relates to the `terraform_remote_state` data sources. This is important so individual teams can ship ready-to-use modules to other teams that access their state. However, due to the constraints on passing resources to modules this is currently out of scope for this proposal. + +Finally, it is a future goal to enable providers to provide their own key providers and encryption methods. Users may also want to create additional, encryption-related, such as merely signing plan files, which this functionality would enable. + +## Non-goals + +In this section we describe the features that are out of scope for state and plan encryption. We do not aspire to solve these problems with the same implementation, and they must be addressed separately if the community chooses to support these endeavours. + +The primary goal of this feature is to protect state and plan files **at rest**. It is not the goal of this feature to protect other channels secrets may be accessed through, such as the JSON output. As such, it is not a goal of this feature to encrypt any output on the standard output, or file output that is not a state or plan file. + +Furthermore, it is not a goal of this feature to *authenticate* that the user is running an up-to-date plan file. It does not protect against, among others, replay attacks where a malicious actor replaces a current plan or state file with an old one. + +It is also not a goal of this feature to protect the state file against the operator of the device running `tofu`. The operator already has access to the encryption key and can decrypt the data without the `tofu` binary being present if they so chose. + +## User-facing effects + +Unless the user explicitly specifies encryption options, no encryption will take place and OpenTofu will continue to function as before. No forced encryption will take place. Furthermore, regardless of the encryption status, other functionality, such as state management CLI functions, JSON output, etc. remain unaffected and will be readable in plain text if they were readable as plain text before. Only state and plan files will be affected by the encryption. + +Users will be able to specify their encryption configuration both in code and via environment variables. Both configurations are equivalent and will be merged at execution time. For more details, see the [environment configuration](#environment-configuration) section below. + +When a user wants to enable encryption, they must specify the following block: + +```hcl2 +terraform { + encryption { + // Encryption options + } +} +``` + +The mere presence of the `encryption` block alone should not enable encryption because the user should explicitly specify what key and method to use. The implementation should error and alert the user if the encryption block is present but has no configuration. + +The encryption relies on an encryption key, or a composite encryption key, which the user can provide directly or via a key management system. The user must provide at least one `key_provider` block with the settings described below. These key providers serve the purpose of creating or providing the encryption key. For example, the user could hard-code a static key named foo: + +```hcl2 +terraform { + encryption { + key_provider "static" "foo" { + key = "6f6f706830656f67686f6834616872756f3751756165686565796f6f72653169" + } + } +} +``` + +> [!NOTE] +> The user is responsible for keeping this key safe and follow disaster recovery best practices. OpenTofu is a read-only consumer for the key the user provided and will not perform tasks on the key management system like key rotation. + +The user also has to specify at least one encryption method referencing the key provider. This encryption method determines how the encryption takes place. It is the user's responsibility to make sure that they provided a key that is suitable for the encryption method. + +```hcl2 +terraform { + encryption { + //... + method "aes_gcm" "bar" { + key_provider = key_provider.static.foo + } + } +} +``` + +Finally, the user must reference the method for use in their state file, plan file, etc. This enables creating a different configuration for different purposes. + +```hcl2 +terraform { + encryption { + //... + state { + method = method.aes_gcm.abc + } + plan { + method = method.aes_gcm.cde + } + remote_state_data_sources { + default { + method = method.aes_gcm.ghi + } + remote_state_data_source "some_module.remote_data_source.foo" { + method = method.aes_gcm.ijk + } + } + } +} +``` + +To facilitate key and method rollover, the user can specify a fallback configuration for state and plan decryption. When the user specifies a `fallback` block, `tofu` will first attempt to decrypt any state or plan it reads with the primary method and then fall back to the `fallback` method. When `tofu` writes a state or plan, it will not use the `fallback` method and always writes with the primary method. + +```hcl2 +terraform { + encryption { + //... + state { + method = method.aes_gcm.bar + fallback { + method = method.aes_gcm.baz + } + } + } +} +``` + +> [!NOTE] +> The `fallback` is a block because the future goals may require adding additional options. + +> [!NOTE] +> Multiple `fallback` blocks should not be supported or should be discouraged because they would be detrimental to performance and encourage keeping old encryption keys in the configuration. + +In the situation where `enforce` is not set to true, and no `method` or `fallback` is specified, no encryption will take place. If the user does not specify a method, but specifies a fallback, the next apply command will disable the encryption given that `enforce` is not set to true. This is to allow the user to disable encryption without removing the encryption configuration from the code. + +### Composite keys + +When a user desires to create a composite key, such as for creating a passphrase-based derivative key or a shared custody key, they may avail themselves of a key provider that supports multiple inputs. The user can chain key providers together: + +```hcl2 +terraform { + encryption { + key_provider "static" "my_passphrase" { + key = "this is my encryption key" + } + key_provider "some_derivative_key_provider" "my_derivative_key" { + key_providers = [key_provider.static.my_passphrase] + } + method "aes_gcm" "foo" { + key_provider = key_provider.some_derivative_key_provider.my_derivative_key + } + //... + } +} +``` + +> [!NOTE] +> The specific implementation of the derivative key must pay attention to combine the keys securely if it supports multiple key providers as inputs, such as using HMAC to combine keys. + +### Environment configuration + +As mentioned above, users can configure encryption in environment variables, either as HCL or JSON. To do this, the user has to specify the encryption configuration fragment in either of the two formats. The following two examples are equivalent: + +```hcl2 +key_provider "static" "my_key" { + key = "this is my encryption key" +} +method "aes_gcm" "foo" { + key_provider = key_provider.static.my_key +} +state { + method = method.aes_gcm.foo +} +``` + +```json +{ + "key_provider" : { + "static": { + "my_key": { + "key": "this is my encryption key" + } + } + }, + "method": { + "aes_gcm": { + "foo": { + "key_provider": "${key_provider.static.my_key}" + } + } + }, + "state": { + "method": "${method.aes_gcm.foo}" + } +} +``` + +The user can set either of these structures in the `TF_ENCRYPTION` environment variable: + +```bash +export TF_ENCRYPTION='{"key_provider":{...},"method":{...},"state":{...}}' +``` + +When the user specifies both an environment and a code configuration, `tofu` merges the two configurations. If two values conflict, the environment configuration takes precedence. + +To ensure that the encryption cannot be accidentally forgotten or disabled and the data stored unencrypted, the user can specify the `enforced` option in the HCL configuration: + +```hcl2 +terraform { + encryption { + //... + state { + enforced = true + } + plan { + enforced = true + } + } +} +``` + +> [!NOTE] +> The `enforced` option is also available in the environment configuration and works as intended, but doesn't make much sense because its primary purpose is to guard against environment variable omission. + +## Encrypted state format + +When `tofu` encrypts a state file, the encrypted state is still a JSON file. Any implementations can distinguish encrypted files by the `encryption` key being present in the JSON structure. However, there may be other keys in the state file depending on the encryption method and type. + +For example (not final): + +```json +{ + "encryption": { + "method": "aes_gcm", + "key_provider": "static.my_key" + }, + // ... Additional keys here +} +``` + +> [!WARNING] +> Tools working with state files should not make assumptions about the type or structure of the `encryption` field as it may vary from implementation to implementation. + +## Encrypted plan format + +An unencrypted plan file in OpenTofu is an opaque binary. This specification makes no rules for how the encrypted format should look like and all non-encryption routines should treat the value as opaque. + +## Implementation + +When implementing the encryption tooling, the implementation should be split in two parts: the library and the OpenTofu implementation. The library should rely on the cty types and hcl as a means to specify schema, but should not be otherwise tied to the OpenTofu codebase. This is necessary to enable encryption capabilities for third party tooling that may need to work with state and plan files. + +### Library implementation + +The encryption library should create an interface that other projects and OpenTofu itself can use to encrypt and decrypt state. The library should express its schema needs (e.g. for key provider config) using [cty](https://github.com/zclconf/go-cty) and [hcl](https://github.com/hashicorp/hcl), but be otherwise independent of the OpenTofu codebase. Ideally, the OpenTofu project should provide this library as a standalone dependency that does not pull in the entire OpenTofu dependency tree. + +#### Encryption interface + +The main component of the library should be the `Encryption` interface. This interface should provide methods to request an encryption tool for each individual purpose, such as: + +```go +type Encryption interface { + State() StateEncryption + Plan() PlanEncryption + RemoteState(string) StateEncryption +} +``` + +Each of the returned encryption tools should provide methods to encrypt the data of the specified purpose, such as: + +```go +type StateEncryption interface { + DecryptState([]byte) ([]byte, error) + EncryptState([]byte) ([]byte, error) +} +``` + +The encryption routines should assume that they get passed a valid state or plan file and encrypt it as described in this document. Conversely, the decryption routines should assume that their input will be an encrypted state or plan file and should attempt to decrypt. The state decryption function should follow the fallback process described in this document. + +#### Key providers + +The main responsibility of a key provider is providing a key in a `[]byte`. It may consume structured configuration, which may also include references to other key providers. However, an implementation of a key provider should never have to deal with resolving these dependencies. Instead, the library should correctly resolve the key provider order and look up the keys in the right order and pass the already-resolved data in as [configuration](#configuration). + +In addition to the encryption key, key providers may also emit additional metadata. The library must store this metadata alongside the encrypted data and pass it to the key provider when initializing the key provider for decryption in a subsequent run. The key provider is responsible for ensuring that no sensitive data is stored in the metadata. + +> [!NOTE] +> Since a user can chain key providers, the library must make sure to store metadata from all key providers in the encrypted form. However, when the user renames the key provider the library may fail to decrypt the state or plan files if the user fails to provide an adequate fallback with the correct naming. The documentation for this feature should encourage users to create new key providers if they change the parameters in a backwards-incompatible manner, and they want to decrypt older state or plan files. + +#### Methods + +The responsibility of a method is to encrypt and decrypt an opaque block of data. The method is not responsible for understanding the structure of the data. Instead, the library core should take care of traversing the state or plan files and deciding specifically what to encrypt. A method must implement the encrypted format in such a way that it can determine if a subsequent decryption failed or not. Methods that cannot decide on decryption success without validating the underlying data, such as rot13, are not supported. + +Similar to [key providers](#key-providers), the method may need configuration but should not have to deal with lookup up key providers itself. + +#### Registering key providers and methods + +The library should be modular. Anyone using the library, including OpenTofu, should be able to add new key providers and methods and read the configuration for these without modifying the library code. To that end, the library should provide a registry for key providers and methods. + +The library should also not force any included key providers or methods onto its user, so the registry should not be global. Instead, every library user should configure their own registry. However, the library should provide a way to obtain a preconfigured registry with built-in key providers and methods. + +#### Configuration + +In order to ensure consistency between OpenTofu and other library users, the library should provide a method to parse an HCL or JSON block and turn it into configuration structures. In parallel, the library should also make it as simple as possible for implementers to safely provide new key providers and methods, which is why the library should also use struct tags in Go to convert the incoming configuration. + +```go +type Config struct { + Key string `hcl:"key"` +} +``` diff --git a/network-poc/static/docs/tofu-cheatsheet.md b/network-poc/static/docs/tofu-cheatsheet.md new file mode 100644 index 0000000..8446095 --- /dev/null +++ b/network-poc/static/docs/tofu-cheatsheet.md @@ -0,0 +1,102 @@ +# OpenTofu Quick Reference + +## Core Architecture +- Graph-based execution: resources form a DAG, parallel where possible +- Provider plugins communicate via gRPC (plugin protocol v5/v6) +- State tracks resource → real-world mapping (JSON format) +- Plan → Apply workflow: always preview before changing + +## HCL Essentials +```hcl +terraform { + required_providers { + aws = { source = "hashicorp/aws", version = "~> 5.0" } + } +} + +provider "aws" { region = "eu-north-1" } + +resource "aws_instance" "web" { + ami = "ami-0c55b159cbfafe1f0" + instance_type = "t3.micro" + tags = { Name = "web-server" } +} + +variable "env" { + type = string + default = "dev" +} + +output "ip" { value = aws_instance.web.public_ip } + +data "aws_ami" "latest" { + most_recent = true + owners = ["amazon"] + filter { + name = "name" + values = ["al2023-ami-*-x86_64"] + } +} +``` + +## Resource Lifecycle +- create_before_destroy: new resource before destroying old +- prevent_destroy: block accidental deletion +- ignore_changes: skip drift on specified attributes +- replace_triggered_by: force replacement when dependency changes + +## Destroy Order +- Destroy runs in reverse dependency order +- ForceDestroy needed for resources with dependencies +- Deposed instances cleaned up automatically + +## State Encryption (OpenTofu-specific) +```hcl +terraform { + encryption { + key_provider "pbkdf2" "main" { + passphrase = var.state_passphrase + } + method "aes_gcm" "main" { + keys = key_provider.pbkdf2.main + } + state { + method = method.aes_gcm.main + enforced = true + } + } +} +``` + +## Module Structure +``` +modules/ + vpc/ + main.tf + variables.tf + outputs.tf + app/ + main.tf + variables.tf + outputs.tf +main.tf # root module +variables.tf +outputs.tf +terraform.tfvars +``` + +## Key Commands +- tofu init: initialize providers and modules +- tofu plan: preview changes +- tofu apply: execute changes +- tofu destroy: remove all resources +- tofu state list/show/mv/rm: state management +- tofu import: bring existing resource under management + +## Best Practices +- Always use required_providers with version constraints +- Use variables for environment-specific values +- State encryption for sensitive data (OpenTofu feature) +- Modules for reusable infrastructure patterns +- Remote state backend for team collaboration +- Plan file for CI/CD: tofu plan -out=plan.bin && tofu apply plan.bin diff --git a/network-poc/static/docs/tracing.md b/network-poc/static/docs/tracing.md new file mode 100644 index 0000000..16e118b --- /dev/null +++ b/network-poc/static/docs/tracing.md @@ -0,0 +1,147 @@ +# OpenTofu Tracing Guide + +This document describes how to use and implement tracing in OpenTofu Core using OpenTelemetry. + +There's background information on OpenTofu's tracing implementation in [the OpenTelemetry Tracing RFC](https://github.com/opentofu/opentofu/blob/main/rfc/20250129-Tracing-For-Extra-Context.md) + +> [!WARNING] +> If you change which version of the `go.opentelemetry.io/otel/sdk` we have selected in our `go.mod`, you **must** make sure that `internal/tracing/traceattrs/semconv.go` imports the same subpackage of `go.opentelemetry.io/otel/semconv/*` that is used by the selected version of `go.opentelemetry.io/otel/sdk`. +> +> This is important because our tracing setup uses a blend of directly-constructed `semconv` attributes and attributes chosen indirectly through the `resource` package, and they must all be using the same version of the semantic conventions schema or there will be a "conflicting Schema URL" error at runtime. +> +> (Problems of this sort should be detected both by a unit test in `internal/tracing/traceattrs` and an end-to-end test that executes OpenTofu with tracing enabled.) + +## Overview + +OpenTofu provides distributed tracing capabilities via OpenTelemetry to help end users understand the execution flow and performance characteristics of OpenTofu operations. Tracing is particularly useful for: + +- Debugging performance issues (e.g., "Why is my plan taking so long?") +- Understanding time spent in different operations +- Visualizing the execution flow across providers and modules +- Diagnosing issues in CI/CD pipelines + +Tracing in OpenTofu is **strictly opt-in** and disabled by default. It's designed to have minimal overhead when disabled and to provide valuable insights when enabled. + +> [!IMPORTANT] +> OpenTofu's tracing functionality refers only to OpenTelemetry traces for local debugging and analysis. +> No telemetry or usage data is sent to external servers, and no data leaves your environment unless you explicitly configure an external collector. + +## Enabling Tracing + +To enable tracing in OpenTofu: + +1. Set the environment variable `OTEL_TRACES_EXPORTER=otlp` +2. Configure the OpenTelemetry exporter using standard OpenTelemetry environment variables + +Example configuration for a local Jaeger collector: + +```bash +export OTEL_TRACES_EXPORTER=otlp +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_INSECURE=true +``` + +For a complete list of configuration options, refer to the [OpenTelemetry Documentation](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). + +## Quick Start with Jaeger + +To quickly spin up a local Jaeger instance with OTLP support: + +```bash +docker run -d --rm --name jaeger \ + -p 16686:16686 \ + -p 4317:4317 \ + -p 4318:4318 \ + -p 5778:5778 \ + -p 9411:9411 \ + jaegertracing/jaeger:2.5.0 +``` + +Then configure OpenTofu as shown above and access the Jaeger UI at http://localhost:16686. + +## Adding Tracing to OpenTofu Code + +> [!NOTE] +> **For Contributors**: When adding tracing to OpenTofu, remember that the primary audience is **end users** who need to understand performance, not OpenTofu developers. Add spans sparingly to avoid polluting traces with too much detail. + +### Basic Span Creation + +```go +import ( + "github.com/opentofu/opentofu/internal/tracing" + "github.com/opentofu/opentofu/internal/tracing/traceattrs" +) + +func SomeFunction(ctx context.Context) error { + // Create a new span + ctx, span := tracing.Tracer().Start(ctx, "Human readable operation name", + tracing.SpanAttributes( + traceattrs.String("opentofu.some_attribute", "value") + ), + ) + defer span.End() + + // Optionally add additional attributes after the span is created, if + // they only need to appear in certain cases. + span.SetAttributes(traceattrs.String("opentofu.some_other_attribute", "value")) + + // Use the more specific attribute-construction helpers from package + // traceattrs where they are relevant, to ensure we follow consistent + // semantic conventions for cross-cutting concerns. + span.SetAttributes(traceattrs.OpenTofuProviderAddress("hashicorp/aws")) + + // Your function logic here... + + // If an error occurs + if err != nil { + tracing.SetSpanError(span, err) + return err + } + + return nil +} +``` + +OpenTelemetry has many different packages spread across a variety of different Go modules, and those different modules often need to be upgraded together to ensure consistent behavior and avoid errors at runtime. + +Therefore we prefer to directly import `go.opentelemetry.io/otel/*` packages only from our packages under `internal/tracing`, and then reexport certain functions from our own packages so that we can manage all of the OpenTelemetry dependencies in a centralized place to minimize "dependency hell" problems when upgrading. Packages under `go.opentelemetry.io/contrib/instrumentation/*` are an exception because they tend to be more tightly-coupled to whatever they are instrumenting than to the other OpenTelemetry packages, and so it's better to import those from the same file that's importing whatever other package the instrumentation is being applied to. + +> [!WARNING] +> Don't import `go.opentelemetry.io/otel/semconv/*` packages from anywhere except `internal/tracing/traceattrs/semconv.go`! +> +> If you want to use standard OpenTelemetry semantic conventions from other packages, use them indirectly through reexports in `package traceattrs` instead, so we can make sure there's only one file in OpenTofu deciding which version of semconv we are currently depending on. + +### Tracing Conventions + +#### Span Naming + +- Use human-readable, action-oriented names that describe operations from a user perspective +- Prefer names like "Provider installation" over internal function names like "InstallProvider" +- Use consistent terminology from the OpenTofu CLI and documentation +- Span names should represent UX-level concepts, not internal code structure + +#### Attributes + +- Prefer standard [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) where applicable, using helper functions from [`internal/tracing/traceattrs`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tracing/traceattrs). +- Use `OpenTofu`-prefixed functions in [`internal/tracing/traceattrs`](https://pkg.go.dev/github.com/opentofu/opentofu/internal/tracing/traceattrs) for OpenTofu-specific cross-cutting concerns. +- It's okay to use one-off inline strings for attribute names specific to a single span, but make sure to still follow the [OpenTelemetry attribute naming conventions](https://opentelemetry.io/docs/specs/semconv/general/naming/) and use the `opentofu.` prefix for anything that is not a standardized semantic convention. +- If a particular subsystem of OpenTofu has some repeated conventions for attribute names, consider creating unexported string constants or attribute construction helper functions in the same package to centralize those naming conventions. + +#### Error Handling + +Use the `tracing.SetSpanError` helper to consistently record errors: + +```go +if err != nil { + tracing.SetSpanError(span, err) + return err +} +``` + +This helper supports various error types including standard errors, strings, and OpenTofu diagnostics. + +### Instrumentation Guidelines + +1. **Focus on Key Operations**: Instrument high-level operations that are meaningful to end users rather than every internal function. +2. **Include Valuable Context**: Add attributes that help identify resources, modules, or operations. +3. **Respect Performance**: Avoid expensive computations solely for tracing. diff --git a/network-poc/static/docs/unicode.md b/network-poc/static/docs/unicode.md new file mode 100644 index 0000000..1660d4c --- /dev/null +++ b/network-poc/static/docs/unicode.md @@ -0,0 +1,142 @@ +# How OpenTofu Uses Unicode + +The OpenTofu language uses the Unicode standards as the basis of various +different features. The Unicode Consortium publishes new versions of those +standards periodically, and we aim to adopt those new versions in new +minor releases of OpenTofu in order to support additional characters added +in those new versions. + +Unfortunately due to those features being implemented by relying on a number +of external libraries, adopting a new version of Unicode is not as simple as +just updating a version number somewhere. This document aims to describe the +various steps required to adopt a new version of Unicode in OpenTofu. + +We typically aim to be consistent across all of these dependencies as to which +major version of Unicode we currently conform to. The usual initial driver +for a Unicode upgrade is switching to new version of the Go runtime library +which itself uses a new version of Unicode, because Go itself does not provide +any way to select Unicode versions independently from Go versions. Therefore +we typically upgrade to a new Unicode version only in conjunction with +upgrading to a new Go version. + +## Unicode tables in the Go standard library + +Several OpenTofu language features are implemented in terms of functions in +[the Go `strings` package](https://pkg.go.dev/strings), +[the Go `unicode` package](https://pkg.go.dev/unicode), and other supporting +packages in the Go standard library. + +The Go team maintains the Go standard library features to support a particular +Unicode version for each Go version. The specific Unicode version for a +particular Go version is available in +[`unicode.Version`](https://pkg.go.dev/unicode#Version). + +We adopt a new version of Go by editing the `go.mod` file in the root +of this repository. Although it's typically possible to build OpenTofu with +other versions of Go, that file documents the version we intend to use for +official releases and thus the primary version we use for development and +testing. Adopting a new Go version typically also implies other behavior +changes inherited from the Go standard library, so it's important to review the +relevant version changelog(s) to note any behavior changes we'll need to pass +on to our own users via the OpenTofu changelog. + +The other subsystems described below should always be set up to match +`unicode.Version`. In some cases those libraries automatically try to align +themselves with `unicode.Version` and generate an error if they cannot, but +that isn't true of all of them. + +## Unicode Identifier Rules in HCL + +_Identifier and Pattern Syntax_ (TF31) is a Unicode standards annex which +describe a set of rules for tokenizing "identifiers", such as variable names +in a programming language. + +HCL uses a superset of that specification for its own identifier tokenization +rules, and so it includes some code derived from the TF31 data tables that +describe which characters belong to the "ID_Start" and "ID_Continue" classes. + +Since OpenTofu is the primary user of HCL, it's typically OpenTofu's adoption +of a new Unicode version which drives HCL to adopt one. To update the Unicode +tables to a new version: +* Edit `hclsyntax/generate.go`'s line which runs `unicode2ragel.rb` to specify + the URL of the `DerivedCoreProperties.txt` data file for the intended Unicode + version. +* Run `go generate ./hclsyntax` to run the generation code to update both + `unicode_derived.rl` and, indirectly, `scan_tokens.go`. (You will need both + a Ruby interpreter and the Ragel state machine compiler on your system in + order to complete this step.) +* Run all the tests to check for regressions: `go test ./...` +* If all looks good, commit all of the changes and open a PR to HCL. +* Once that PR is merged and released, update OpenTofu to use the new version + of HCL. + +## Unicode Text Segmentation + +_Text Segmentation_ (TR29) is a Unicode standards annex which describes +algorithms for breaking strings into smaller units such as sentences, words, +and grapheme clusters. + +Several OpenTofu language features make use of the _grapheme cluster_ +algorithm in particular, because it provides a practical definition of +individual visible characters, taking into account combining sequences such +as Latin letters with separate diacritics or Emoji characters with gender +presentation and skin tone modifiers. + +The text segmentation algorithms rely on supplementary data tables that are +not part of the core set encoded in the Go standard library's `unicode` +packages, and so instead we rely on the third-party module +[`github.com/apparentlymart/go-textseg`](http://pkg.go.dev/github.com/apparentlymart/go-textseg) +to provide those tables and a Go implementation of the grapheme cluster +segmentation algorithm in terms of the tables. + +The `go-textseg` library is designed to allow calling programs to potentially +support multiple Unicode versions at once, by offering a separate module major +version for each Unicode major version. For example, the full module path for +the Unicode 13 implementation is `github.com/apparentlymart/go-textseg/v13`. + +If that external library doesn't yet have support for the Unicode version we +intend to adopt then we'll first need to open a pull request to contribute +new language support. The details of how to do this will unfortunately vary +depending on how significantly the Text Segmentation annex has changed since +the most recently-supported Unicode version, but in many cases it can be +just a matter of editing that library's `make_tables.go`, `make_test_tables.go`, +and `generate.go` files to point to the URLs where the Unicode consortium +published new tables and then run `go generate` to rebuild the files derived +from those data sources. As long as the new Unicode version has only changed +the data tables and not also changed the algorithm, often no further changes +are needed. + +Once a new Unicode version is included, the maintainer of that library will +typically publish a new major version that we can depend on. Two different +codebases included in OpenTofu all depend directly on the `go-textseg` module +for parts of their functionality: + +* [`hashicorp/hcl`](https://github.com/hashicorp/hcl) uses text + segmentation as part of producing visual column offsets in source ranges + returned by the tokenizer and parser. OpenTofu in turn uses that library + for the underlying syntax of the OpenTofu language, and so it passes on + those source ranges to the end-user as part of diagnostic messages. +* The third-party module [`github.com/zclconf/go-cty`](https://github.com/zclconf/go-cty) + provides several of the OpenTofu language built in functions, including + functions like `substr` and `length` which need to count grapheme clusters + as part of their implementation. + +As part of upgrading OpenTofu's Unicode support we therefore typically also +open pull requests against these other codebases, and then adopt the new +versions that produces. OpenTofu work often drives the adoption of new Unicode +versions in those codebases, with other dependencies following along when they +next upgrade. + +At the time of writing OpenTofu itself doesn't _directly_ depend on +`go-textseg`, and so there are no specific changes required in this OpenTofu +codebase aside from the `go.sum` file update that always follows from +changes to transitive dependencies. + +The `go-textseg` library does have a different "auto-version" mechanism which +selects an appropriate module version based on the current Go language version, +but neither HCL nor cty use that because the auto-version package will not +compile for any Go version that doesn't have a corresponding Unicode version +explicitly recorded in that repository, and so that would be too harsh a +constraint for libraries like HCL which have many callers, many of which don't +care strongly about Unicode support, that may wish to upgrade Go before the +text segmentation library has been updated. diff --git a/network-poc/static/index.html b/network-poc/static/index.html index 15bca38..2191d1a 100644 --- a/network-poc/static/index.html +++ b/network-poc/static/index.html @@ -1057,6 +1057,10 @@ DevOps
DevOps
+
+ Tofuist +
Tofuist
+
Tarkkailija
Tarkkailija
@@ -1091,6 +1095,7 @@ +
@@ -1159,6 +1164,7 @@ data: { name: 'Data-Agentti — System Prompt', model: 'qwen-coder', default: 'Olet tietokanta-asiantuntija. Vastaat skeemojen suunnittelusta, SQL-kyselyiden optimoinnista ja datamalleista.' }, qa: { name: 'QA — System Prompt', model: 'qwen-coder', default: 'Olet laadunvarmistaja (QA). Kirjoitat testejä, etsit virheitä ja varmistat, että kaikki reunatapaukset on huomioitu.' }, tester: { name: 'DevOps — System Prompt', model: 'qwen-coder', default: 'Olet DevOps-insinööri. Kirjoitat Dockerfile- ja docker-compose.yml-tiedostot, README:t ja käynnistysohjeet. Käytä aina multi-stage Docker buildia ja docker compose -orkestrointia.' }, + tofuist: { name: 'Tofuist — System Prompt', model: 'qwen-coder', docs: '/docs/tofu-cheatsheet.md', default: 'You are an OpenTofu/Terraform IaC specialist. You write HCL infrastructure code: providers, resources, modules, variables, outputs, state management, and encryption. You follow OpenTofu best practices: use planning behaviors before apply, handle resource lifecycle (create_before_destroy, prevent_destroy), configure state encryption for sensitive data, and structure code with clear module boundaries. Always output valid HCL code. Use provider references correctly (required_providers block). Prefer data sources over hardcoded values.' }, }; const selectedAgents = new Set(); let sharedPrompt = localStorage.getItem('kpn-shared-prompt') || ''; @@ -1386,7 +1392,7 @@ const title = document.getElementById('prompt-modal-title'); const fields = document.getElementById('prompt-modal-fields'); - const agentNames = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data' }; + const agentNames = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data', tofuist: 'Tofuist' }; title.textContent = `${agentNames[agent] || agent} — ${label}`; fields.innerHTML = modalPromptParts.map((f, i) => ` @@ -2054,6 +2060,14 @@ IMPORTANT: Include get_db() dependency for FastAPI` }, const parts = []; if (sharedPrompt) parts.push(sharedPrompt); if (agent && agent.prompt) parts.push(agent.prompt); + // Ladataan agentin docs-referenssi (esim. OpenTofu cheatsheet) + if (agent && agent.docs && !agent._docsCache) { + try { + const r = await fetch(agent.docs); + if (r.ok) agent._docsCache = await r.text(); + } catch(e) { /* docs ei saatavilla */ } + } + if (agent && agent._docsCache) parts.push('Reference:\n' + agent._docsCache); parts.push(prompt); const fullPrompt = parts.join('\n\n'); @@ -2140,7 +2154,7 @@ IMPORTANT: Include get_db() dependency for FastAPI` }, } renderPipelineSteps(); // Päivitetään agentin avatar tooltip + vilahdus - const avatarMap = { manager: 'avatar-kpn', coder: 'avatar-coder', tester: 'avatar-tester', qa: 'avatar-qa', data: 'avatar-data' }; + const avatarMap = { manager: 'avatar-kpn', coder: 'avatar-coder', tester: 'avatar-tester', qa: 'avatar-qa', data: 'avatar-data', tofuist: 'avatar-tofuist' }; const avatarId = avatarMap[agent]; if (avatarId) { const el = document.getElementById(avatarId); @@ -2170,7 +2184,7 @@ IMPORTANT: Include get_db() dependency for FastAPI` }, if (pipelineSteps.length === 0) { container.style.display = 'none'; return; } container.style.display = 'flex'; container.innerHTML = pipelineSteps.map((s, i) => { - const colors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff' }; + const colors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff', tofuist: '#e3a336' }; const color = colors[s.agent] || '#8b949e'; const icon = s.status === 'done' ? '✓' : s.status === 'active' ? '◷' : '◯'; const iconColor = s.status === 'done' ? '#3fb950' : s.status === 'active' ? '#d29922' : '#8b949e'; @@ -2837,8 +2851,8 @@ ${fixableFiles}`; function generateProjectReport(task, files, steps, staticIssues) { const fileEntries = Object.entries(files); - const agentNames = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data' }; - const agentColors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff' }; + const agentNames = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data', tofuist: 'Tofuist' }; + const agentColors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff', tofuist: '#e3a336' }; // Syntaksikorostus: kevyt regex-pohjainen highlighter function highlightCode(code, filename) { @@ -2948,9 +2962,9 @@ ${filesHtml} } function generateWorkflowSwimlane(steps) { - const agentLabels = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data' }; - const agentColors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff' }; - const agentBgs = { manager: '#1c1206', coder: '#0d1a0d', tester: '#0d1520', qa: '#170d22', data: '#1a0d22' }; + const agentLabels = { manager: 'Manageri', coder: 'Koodari', tester: 'DevOps', qa: 'QA', data: 'Data', tofuist: 'Tofuist' }; + const agentColors = { manager: '#d29922', coder: '#3fb950', tester: '#58a6ff', qa: '#a371f7', data: '#d2a8ff', tofuist: '#e3a336' }; + const agentBgs = { manager: '#1c1206', coder: '#0d1a0d', tester: '#0d1520', qa: '#170d22', data: '#1a0d22', tofuist: '#1a1506' }; const stepDescs = { 'Suunnittelu': 'Jakaa projektin tiedostoiksi', 'Review': 'Tarkistaa koodin laadun', 'Testit': 'Kirjoittaa pytest-testit', 'Dockerfile': 'Generoi Docker-imagen', 'Compose': 'Palvelumääritys', 'README': 'Käyttöohjeet', 'Validointi': 'Tarkistaa yhteensopivuuden', 'Korjaukset': 'Korjaa löydetyt ongelmat' }; var agents = [];