add documentation and example

Author: austinvalle

docs/actions/command.md

@@ -0,0 +1,79 @@
+page_title: "local_command Action - terraform-provider-local"
+subcategory: ""
+description: |-
+  Invokes an executable on the local machine. All environment variables visible to the Terraform process are passed through to the child process. After the child process successfully executes, the stdout will be returned for Terraform to display to the user.
+  Any non-zero exit code will be treated as an error and will return a diagnostic to Terraform containing the stderr message if available.
+---
+
+# local_command (Action)
+
+Invokes an executable on the local machine. All environment variables visible to the Terraform process are passed through to the child process. After the child process successfully executes, the `stdout` will be returned for Terraform to display to the user.
+
+Any non-zero exit code will be treated as an error and will return a diagnostic to Terraform containing the `stderr` message if available.
+
+## Example Usage
+
+For the following bash script (`example_script.sh`):
+```bash
+#!/bin/bash
+
+DATA=$(</dev/stdin)
+echo "stdin: $DATA, args: $@"
+```
+
+Here is an example configuration that will run the script after a resource is created:
+
+```terraform
+resource "terraform_data" "test" {
+  lifecycle {
+    action_trigger {
+      events  = [after_create]
+      actions = [action.local_command.bash_example]
+    }
+  }
+}
+
+action "local_command" "bash_example" {
+  config {
+    command   = "bash"
+    arguments = ["example_script.sh", "arg1", "arg2"]
+    stdin = jsonencode({
+      "key1" : "value1"
+      "key2" : "value2"
+    })
+  }
+}
+```
+
+The `stdout` will be displayed when the action is invoked:
+```bash
+ $ terraform apply -auto-approve
+
+# .. Terraform CLI output truncated for example purposes
+
+Plan: 1 to add, 0 to change, 0 to destroy. Actions: 1 to invoke.
+terraform_data.test: Creating...
+terraform_data.test: Creation complete after 0s [id=4b41b541-5550-590a-9949-657e91baa346]
+Action started: action.local_command.bash_example (triggered by terraform_data.test)
+Action action.local_command.bash_example (triggered by terraform_data.test): 
+
+stdin: {"key1":"value1","key2":"value2"}, args: arg1 arg2
+
+
+Action complete: action.local_command.bash_example (triggered by terraform_data.test)
+
+Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
+```
+
+<!-- action schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `command` (String) Executable name to be discovered on the PATH or absolute path to executable.
+
+### Optional
+
+- `arguments` (List of String) Arguments to be passed to the given command. Any `null` arguments will be removed from the list.
+- `stdin` (String) Data to be passed to the given command's standard input.
+- `working_directory` (String) The directory where the command should be executed. Defaults to the Terraform working directory.

examples/actions/local_command/action.tf

@@ -0,0 +1,19 @@
+resource "terraform_data" "test" {
+  lifecycle {
+    action_trigger {
+      events  = [after_create]
+      actions = [action.local_command.bash_example]
+    }
+  }
+}
+
+action "local_command" "bash_example" {
+  config {
+    command   = "bash"
+    arguments = ["example_script.sh", "arg1", "arg2"]
+    stdin = jsonencode({
+      "key1" : "value1"
+      "key2" : "value2"
+    })
+  }
+}

examples/actions/local_command/example_script.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+DATA=$(</dev/stdin)
+echo "stdin: $DATA, args: $@"

internal/provider/action_local_command.go

@@ -35,24 +35,26 @@ func (a *localCommandAction) Metadata(ctx context.Context, req action.MetadataRe
 
 func (a *localCommandAction) Schema(ctx context.Context, req action.SchemaRequest, resp *action.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description: "", // TODO: Describe action, mention that actions don't have output, this is meant to execute local commands, they can be non-idempotent as they are only executed during apply.
-		// If the external command is idempotent/you need the output, use data source (coming soon).
+		// TODO: Once we have a local_command data source, reference that to be used if the user needs to the consume the output of the command (and it's idempotent)
+		MarkdownDescription: "Invokes an executable on the local machine. All environment variables visible to the Terraform process are passed through " +
+			"to the child process. After the child process successfully executes, the `stdout` will be returned for Terraform to display to the user.\n\n" +
+			"Any non-zero exit code will be treated as an error and will return a diagnostic to Terraform containing the `stderr` message if available.",
 		Attributes: map[string]schema.Attribute{
 			"command": schema.StringAttribute{
 				Description: "Executable name to be discovered on the PATH or absolute path to executable.",
 				Required:    true,
 			},
 			"arguments": schema.ListAttribute{
-				Description: "Arguments to be passed to the given command.",
-				ElementType: types.StringType,
-				Optional:    true,
+				MarkdownDescription: "Arguments to be passed to the given command. Any `null` arguments will be removed from the list.",
+				ElementType:         types.StringType,
+				Optional:            true,
 			},
 			"stdin": schema.StringAttribute{
 				Description: "Data to be passed to the given command's standard input.",
 				Optional:    true,
 			},
 			"working_directory": schema.StringAttribute{
-				Description: "The directory where the command should be executed. Defaults to the current working directory.",
+				Description: "The directory where the command should be executed. Defaults to the Terraform working directory.",
 				Optional:    true,
 			},
 		},

templates/actions/command.md.tmpl

@@ -0,0 +1,45 @@
+page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+## Example Usage
+
+For the following bash script (`example_script.sh`):
+```bash
+#!/bin/bash
+
+DATA=$(</dev/stdin)
+echo "stdin: $DATA, args: $@"
+```
+
+Here is an example configuration that will run the script after a resource is created:
+
+{{ tffile (index .ExampleFiles 0) }}
+
+The `stdout` will be displayed when the action is invoked:
+```bash
+ $ terraform apply -auto-approve
+
+# .. Terraform CLI output truncated for example purposes
+
+Plan: 1 to add, 0 to change, 0 to destroy. Actions: 1 to invoke.
+terraform_data.test: Creating...
+terraform_data.test: Creation complete after 0s [id=4b41b541-5550-590a-9949-657e91baa346]
+Action started: action.local_command.bash_example (triggered by terraform_data.test)
+Action action.local_command.bash_example (triggered by terraform_data.test): 
+
+stdin: {"key1":"value1","key2":"value2"}, args: arg1 arg2
+
+
+Action complete: action.local_command.bash_example (triggered by terraform_data.test)
+
+Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
+```
+
+{{ .SchemaMarkdown | trimspace }}