jprdonnelly/opentf
1
0
Fork 0
mirror of https://github.com/opentffoundation/opentf.git synced 2025-12-25 01:00:16 -05:00
Code Issues Packages Projects Releases Wiki Activity

Rename website to OpenTofu (#516)

Browse Source 
Co-authored-by: Damian Stasik <920747+damianstasik@users.noreply.github.com>
Co-authored-by: Roman Grinovski <roman.grinovski@gmail.com>
This commit is contained in:
Julien Levasseur
2023-09-21 05:57:47 -04:00
committed by GitHub
parent e5878055b6
commit 4c0bda5386
221 changed files with 2497 additions and 2497 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
website/docs/internals/machine-readable-ui.mdx
View File

@@ -1,12 +1,12 @@
---
description: >-
OpenTF provides a machine-readable streaming JSON UI output for plan,
OpenTofu provides a machine-readable streaming JSON UI output for plan,
apply, and refresh operations.
---
# Machine-Readable UI
By default, many OpenTF commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface.
By default, many OpenTofu commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface.
For long-running commands such as `plan`, `apply`, and `refresh`, the `-json` flag outputs a stream of JSON UI messages, one per line. These can be processed one message at a time, with integrating software filtering, combining, or modifying the output as desired.
@@ -21,33 +21,33 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
## Sample JSON Output
Below is sample output from running `opentf apply -json`:
Below is sample output from running `tofu apply -json`:
```javascript
{"@level":"info","@message":"OpenTF 1.6.0","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.275359-04:00","opentf":"0.15.4","type":"version","ui":"0.1.0"}
{"@level":"info","@message":"random_pet.animal: Plan to create","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.705503-04:00","change":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"Plan: 1 to add, 0 to change, 0 to destroy.","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.705638-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"plan"},"type":"change_summary"}
{"@level":"info","@message":"random_pet.animal: Creating...","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.825308-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"apply_start"}
{"@level":"info","@message":"random_pet.animal: Creation complete after 0s [id=smart-lizard]","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.826179-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create","id_key":"id","id_value":"smart-lizard","elapsed_seconds":0},"type":"apply_complete"}
{"@level":"info","@message":"Apply complete! Resources: 1 added, 0 changed, 0 destroyed.","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.869168-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"apply"},"type":"change_summary"}
{"@level":"info","@message":"Outputs: 1","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.869280-04:00","outputs":{"pets":{"sensitive":false,"type":"string","value":"smart-lizard"}},"type":"outputs"}
{"@level":"info","@message":"OpenTofu 1.6.0","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.275359-04:00","tofu":"0.15.4","type":"version","ui":"0.1.0"}
{"@level":"info","@message":"random_pet.animal: Plan to create","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.705503-04:00","change":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"Plan: 1 to add, 0 to change, 0 to destroy.","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.705638-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"plan"},"type":"change_summary"}
{"@level":"info","@message":"random_pet.animal: Creating...","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.825308-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"apply_start"}
{"@level":"info","@message":"random_pet.animal: Creation complete after 0s [id=smart-lizard]","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.826179-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create","id_key":"id","id_value":"smart-lizard","elapsed_seconds":0},"type":"apply_complete"}
{"@level":"info","@message":"Apply complete! Resources: 1 added, 0 changed, 0 destroyed.","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.869168-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"apply"},"type":"change_summary"}
{"@level":"info","@message":"Outputs: 1","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.869280-04:00","outputs":{"pets":{"sensitive":false,"type":"string","value":"smart-lizard"}},"type":"outputs"}
```
Each line consists of a JSON object with several keys common to all messages. These are:
- `@level`: this is normally "info", but can be "error" or "warn" when showing diagnostics
- `@message`: a human-readable summary of the contents of this message
- `@module`: always "opentf.ui" when rendering UI output
- `@module`: always "tofu.ui" when rendering UI output
- `@timestamp`: an RFC3339 timestamp of when the message was output
- `type`: defines which kind of message this is and determines how to interpret other keys which may be present
Clients presenting the logs as a user interface should handle unexpected message types by presenting at least the `@message` field to the user.
Messages will be emitted as events occur to trigger them. This means that messages related to several resources may be interleaved (if OpenTF is running with concurrency above 1). The [`resource` object value](#resource-object) can be used to link multiple messages about a single resource.
Messages will be emitted as events occur to trigger them. This means that messages related to several resources may be interleaved (if OpenTofu is running with concurrency above 1). The [`resource` object value](#resource-object) can be used to link multiple messages about a single resource.
## Message Types
@@ -55,13 +55,13 @@ The following message types are supported:
### Generic Messages
- `version`: information about the OpenTF version and the version of the schema used for the following messages
- `version`: information about the OpenTofu version and the version of the schema used for the following messages
- `log`: unstructured human-readable log lines
- `diagnostic`: diagnostic warning or error messages; [see the `opentf validate` docs for more details on the format](/docs/cli/commands/validate#json)
- `diagnostic`: diagnostic warning or error messages; [see the `tofu validate` docs for more details on the format](/docs/cli/commands/validate#json)
### Operation Results
- `resource_drift`: describes a detected change to a single resource made outside of OpenTF
- `resource_drift`: describes a detected change to a single resource made outside of OpenTofu
- `planned_change`: describes a planned change to a single resource
- `change_summary`: summary of all planned or applied changes
- `outputs`: list of all root module outputs
@@ -76,7 +76,7 @@ The following message types are supported:
A machine-readable UI command output will always begin with a `version` message. The following message-specific keys are defined:
- `opentf`: the OpenTF version which emitted this message
- `tofu`: the OpenTofu version which emitted this message
- `ui`: the machine-readable UI schema version defining the meaning of the following messages
### Example
@@ -84,10 +84,10 @@ A machine-readable UI command output will always begin with a `version` message.
```json
{
"@level": "info",
"@message": "OpenTF 0.15.4",
"@module": "opentf.ui",
"@message": "OpenTofu 0.15.4",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.275359-04:00",
"opentf": "0.15.4",
"tofu": "0.15.4",
"type": "version",
"ui": "0.1.0"
}
@@ -95,7 +95,7 @@ A machine-readable UI command output will always begin with a `version` message.
## Resource Drift
If drift is detected during planning, OpenTF will emit a `resource_drift` message for each resource which has changed outside of OpenTF. This message has an embedded `change` object with the following keys:
If drift is detected during planning, OpenTofu will emit a `resource_drift` message for each resource which has changed outside of OpenTofu. This message has an embedded `change` object with the following keys:
- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
- `action`: the action planned to be taken for the resource. Values: `update`, `delete`.
@@ -108,7 +108,7 @@ This message does not include details about the exact changes which caused the c
{
"@level": "info",
"@message": "random_pet.animal: Drift detected (update)",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.705503-04:00",
"change": {
"resource": {
@@ -128,7 +128,7 @@ This message does not include details about the exact changes which caused the c
## Planned Change
At the end of a plan or before an apply, OpenTF will emit a `planned_change` message for each resource which has changes to apply. This message has an embedded `change` object with the following keys:
At the end of a plan or before an apply, OpenTofu will emit a `planned_change` message for each resource which has changes to apply. This message has an embedded `change` object with the following keys:
- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
- `previous_resource`: object describing the previous address of the resource, if this change includes a configuration-driven move
@@ -151,7 +151,7 @@ This message does not include details about the exact changes which caused the c
{
"@level": "info",
"@message": "random_pet.animal: Plan to create",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.705503-04:00",
"change": {
"resource": {
@@ -171,7 +171,7 @@ This message does not include details about the exact changes which caused the c
## Change Summary
OpenTF outputs a change summary when a plan or apply operation completes. Both message types include a `changes` object, which has the following keys:
OpenTofu outputs a change summary when a plan or apply operation completes. Both message types include a `changes` object, which has the following keys:
- `add`: count of resources to be created (including as part of replacement)
- `change`: count of resources to be changed in-place
@@ -184,7 +184,7 @@ OpenTF outputs a change summary when a plan or apply operation completes. Both m
{
"@level": "info",
"@message": "Apply complete! Resources: 1 added, 0 changed, 0 destroyed.",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.869168-04:00",
"changes": {
"add": 1,
@@ -213,7 +213,7 @@ Note that `sensitive` outputs still include the `value` field, and integrating s
{
"@level": "info",
"@message": "Outputs: 1",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.869280-04:00",
"outputs": {
"pets": {
@@ -228,7 +228,7 @@ Note that `sensitive` outputs still include the `value` field, and integrating s
## Operation Messages
Performing OpenTF operations to a resource will often result in several messages being emitted. The message types include:
Performing OpenTofu operations to a resource will often result in several messages being emitted. The message types include:
- `apply_start`: when starting to apply changes for a resource
- `apply_progress`: periodically, showing elapsed time output
@@ -257,7 +257,7 @@ The `apply_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "random_pet.animal: Creating...",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.825308-04:00",
"hook": {
"resource": {
@@ -289,7 +289,7 @@ The `apply_progress` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[4]: Still creating... [30s elapsed]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-17T09:34:26.222465-04:00",
"hook": {
"resource": {
@@ -323,7 +323,7 @@ The `apply_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "random_pet.animal: Creation complete after 0s [id=smart-lizard]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.826179-04:00",
"hook": {
"resource": {
@@ -360,7 +360,7 @@ The exact detail of the error will be rendered as a separate `diagnostic` messag
{
"@level": "info",
"@message": "null_resource.none[0]: Creation errored after 10s",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:54.013910-04:00",
"hook": {
"resource": {
@@ -392,7 +392,7 @@ The `provision_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Provisioning with 'local-exec'...",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:43.997431-04:00",
"hook": {
"resource": {
@@ -426,7 +426,7 @@ One `provision_progress` message is output for each log line received from the p
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec): Executing: [\"/bin/sh\" \"-c\" \"sleep 10 && exit 1\"]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:43.997869-04:00",
"hook": {
"resource": {
@@ -458,7 +458,7 @@ The `provision_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec) Provisioning complete",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-17T09:34:06.239043-04:00",
"hook": {
"resource": {
@@ -489,7 +489,7 @@ The `provision_errored` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec) Provisioning errored",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:54.013572-04:00",
"hook": {
"resource": {
@@ -520,7 +520,7 @@ The `refresh_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Refreshing state... [id=1971614370559474622]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T14:18:06.508915-04:00",
"hook": {
"resource": {
@@ -552,7 +552,7 @@ The `refresh_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Refresh complete [id=1971614370559474622]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T14:18:06.509371-04:00",
"hook": {
"resource": {