From bdee8868bed48a894a36a7864348232fc9bb26d2 Mon Sep 17 00:00:00 2001 From: Thomas Kappler Date: Thu, 20 Jun 2024 20:10:57 +0200 Subject: [PATCH] Document Command in its own Markdown file, with `triggers` examples (#472) Resolves #40 Part of #196 Issue #40 showed that the `triggers` property could be confusing to users. This PR adds more docs, including sample code. The actual changes are all in inputs.go and command.md. --- .../cmd/pulumi-resource-command/schema.json | 12 +- provider/pkg/provider/common/inputs.go | 5 +- provider/pkg/provider/local/command.go | 13 +- provider/pkg/provider/local/command.md | 215 ++++++++++++++++ provider/pkg/provider/remote/command.go | 8 +- provider/pkg/provider/remote/command.md | 234 ++++++++++++++++++ sdk/dotnet/Local/Command.cs | 62 ++++- sdk/dotnet/Remote/Command.cs | 63 ++++- sdk/go/command/local/command.go | 84 ++++++- sdk/go/command/remote/command.go | 85 ++++++- .../com/pulumi/command/local/Command.java | 54 +++- .../com/pulumi/command/local/CommandArgs.java | 25 +- .../com/pulumi/command/remote/Command.java | 54 +++- .../pulumi/command/remote/CommandArgs.java | 25 +- sdk/nodejs/local/command.ts | 46 +++- sdk/nodejs/remote/command.ts | 46 +++- sdk/python/pulumi_command/local/command.py | 88 ++++++- sdk/python/pulumi_command/remote/command.py | 88 ++++++- 18 files changed, 1117 insertions(+), 90 deletions(-) create mode 100644 provider/pkg/provider/local/command.md create mode 100644 provider/pkg/provider/remote/command.md diff --git a/provider/cmd/pulumi-resource-command/schema.json b/provider/cmd/pulumi-resource-command/schema.json index 280fc911..ed67c42d 100644 --- a/provider/cmd/pulumi-resource-command/schema.json +++ b/provider/cmd/pulumi-resource-command/schema.json @@ -205,7 +205,7 @@ }, "resources": { "command:local:Command": { - "description": "A local command to be executed.\nThis command can be inserted into the life cycles of other resources using the\n`dependsOn` or `parent` resource options. A command is considered to have\nfailed when it finished with a non-zero exit code. This will fail the CRUD step\nof the `Command` resource.", + "description": "A local command to be executed.\n\nThis command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource.\n\n{{% examples %}}\n## Example Usage\n\n{{% example %}}\n### Triggers\n\nThis example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run.\n\n```typescript\nimport * as pulumi from \"@pulumi/pulumi\";\nimport * as command from \"@pulumi/command\";\nimport * as random from \"@pulumi/random\";\n\nconst str = \"foo\";\nconst fileAsset = new pulumi.asset.FileAsset(\"Pulumi.yaml\");\nconst rand = new random.RandomString(\"rand\", {length: 5});\nconst localFile = new command.local.Command(\"localFile\", {\n create: \"touch foo.txt\",\n archivePaths: [\"*.txt\"],\n});\n\nconst cmd = new command.local.Command(\"cmd\", {\n create: \"echo create > op.txt\",\n delete: \"echo delete >> op.txt\",\n triggers: [\n str,\n rand.result,\n fileAsset,\n localFile.archive,\n ],\n});\n```\n\n```python\nimport pulumi\nimport pulumi_command as command\nimport pulumi_random as random\n\nfoo = \"foo\"\nfile_asset_var = pulumi.FileAsset(\"Pulumi.yaml\")\nrand = random.RandomString(\"rand\", length=5)\nlocal_file = command.local.Command(\"localFile\",\n create=\"touch foo.txt\",\n archive_paths=[\"*.txt\"])\n\ncmd = command.local.Command(\"cmd\",\n create=\"echo create > op.txt\",\n delete=\"echo delete >> op.txt\",\n triggers=[\n foo,\n rand.result,\n file_asset_var,\n local_file.archive,\n ])\n```\n\n```go\npackage main\n\nimport (\n\t\"github.com/pulumi/pulumi-command/sdk/go/command/local\"\n\t\"github.com/pulumi/pulumi-random/sdk/v4/go/random\"\n\t\"github.com/pulumi/pulumi/sdk/v3/go/pulumi\"\n)\n\nfunc main() {\n\tpulumi.Run(func(ctx *pulumi.Context) error {\n\t\tstr := pulumi.String(\"foo\")\n\n\t\tfileAsset := pulumi.NewFileAsset(\"Pulumi.yaml\")\n\n\t\trand, err := random.NewRandomString(ctx, \"rand\", &random.RandomStringArgs{\n\t\t\tLength: pulumi.Int(5),\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tlocalFile, err := local.NewCommand(ctx, \"localFile\", &local.CommandArgs{\n\t\t\tCreate: pulumi.String(\"touch foo.txt\"),\n\t\t\tArchivePaths: pulumi.StringArray{\n\t\t\t\tpulumi.String(\"*.txt\"),\n\t\t\t},\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\t_, err = local.NewCommand(ctx, \"cmd\", &local.CommandArgs{\n\t\t\tCreate: pulumi.String(\"echo create > op.txt\"),\n\t\t\tDelete: pulumi.String(\"echo delete >> op.txt\"),\n\t\t\tTriggers: pulumi.Array{\n\t\t\t\tstr,\n\t\t\t\trand.Result,\n\t\t\t\tfileAsset,\n\t\t\t\tlocalFile.Archive,\n\t\t\t},\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn nil\n\t})\n}\n```\n\n```csharp\nusing Pulumi;\nusing Command = Pulumi.Command;\nusing Random = Pulumi.Random;\n\nreturn await Deployment.RunAsync(() =>\n{\n var str = \"foo\";\n\n var fileAssetVar = new FileAsset(\"Pulumi.yaml\");\n\n var rand = new Random.RandomString(\"rand\", new()\n {\n Length = 5,\n });\n\n var localFile = new Command.Local.Command(\"localFile\", new()\n {\n Create = \"touch foo.txt\",\n ArchivePaths = new[]\n {\n \"*.txt\",\n },\n });\n\n var cmd = new Command.Local.Command(\"cmd\", new()\n {\n Create = \"echo create > op.txt\",\n Delete = \"echo delete >> op.txt\",\n Triggers = new object[]\n {\n str,\n rand.Result,\n fileAssetVar,\n localFile.Archive,\n },\n });\n\n});\n```\n\n```java\npublic class App {\n public static void main(String[] args) {\n Pulumi.run(App::stack);\n }\n\n public static void stack(Context ctx) {\n final var fileAssetVar = new FileAsset(\"Pulumi.yaml\");\n\n var rand = new RandomString(\"rand\", RandomStringArgs.builder()\n .length(5)\n .build());\n\n var localFile = new Command(\"localFile\", CommandArgs.builder()\n .create(\"touch foo.txt\")\n .archivePaths(\"*.txt\")\n .build());\n\n var cmd = new Command(\"cmd\", CommandArgs.builder()\n .create(\"echo create > op.txt\")\n .delete(\"echo delete >> op.txt\")\n .triggers(\n rand.result(),\n fileAssetVar,\n localFile.archive())\n .build());\n\n }\n}\n```\n\n```yaml\nconfig: {}\noutputs: {}\nresources:\n rand:\n type: random:index/randomString:RandomString\n properties:\n length: 5\n\n localFile:\n type: command:local:Command\n properties:\n create: touch foo.txt\n archivePaths:\n - \"*.txt\"\n\n cmd:\n type: command:local:Command\n properties:\n create: echo create > op.txt\n delete: echo delete >> op.txt\n triggers:\n - ${rand.result}\n - ${fileAsset}\n - ${localFile.archive}\n\nvariables:\n fileAsset:\n fn::fileAsset: \"Pulumi.yaml\"\n```\n{{% /example %}}\n\n{{% /examples %}}", "properties": { "addPreviousOutputInEnv": { "type": "boolean", @@ -284,7 +284,7 @@ "items": { "$ref": "pulumi.json#/Any" }, - "description": "Trigger replacements on changes to this input.", + "description": "Trigger a resource replacement on changes to any of these values. The\ntrigger values can be of any type. If a value is different in the current update compared to the\nprevious update, the resource will be replaced, i.e., the \"create\" command will be re-run.\nPlease see the resource documentation for examples.", "replaceOnChanges": true }, "update": { @@ -356,7 +356,7 @@ "items": { "$ref": "pulumi.json#/Any" }, - "description": "Trigger replacements on changes to this input.", + "description": "Trigger a resource replacement on changes to any of these values. The\ntrigger values can be of any type. If a value is different in the current update compared to the\nprevious update, the resource will be replaced, i.e., the \"create\" command will be re-run.\nPlease see the resource documentation for examples.", "replaceOnChanges": true }, "update": { @@ -366,7 +366,7 @@ } }, "command:remote:Command": { - "description": "A command to run on a remote host.\nThe connection is established via ssh.", + "description": "A command to run on a remote host. The connection is established via ssh.\n\n{{% examples %}}\n## Example Usage\n\n{{% example %}}\n### Triggers\n\nThis example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run.\n\n```typescript\nimport * as pulumi from \"@pulumi/pulumi\";\nimport * as command from \"@pulumi/command\";\nimport * as random from \"@pulumi/random\";\n\nconst str = \"foo\";\nconst fileAsset = new pulumi.asset.FileAsset(\"Pulumi.yaml\");\nconst rand = new random.RandomString(\"rand\", {length: 5});\nconst localFile = new command.local.Command(\"localFile\", {\n create: \"touch foo.txt\",\n archivePaths: [\"*.txt\"],\n});\nconst cmd = new command.remote.Command(\"cmd\", {\n connection: {\n host: \"insert host here\",\n },\n create: \"echo create > op.txt\",\n delete: \"echo delete >> op.txt\",\n triggers: [\n str,\n rand.result,\n fileAsset,\n localFile.archive,\n ],\n});\n\n```\n\n```python\nimport pulumi\nimport pulumi_command as command\nimport pulumi_random as random\n\nfoo = \"foo\"\nfile_asset_var = pulumi.FileAsset(\"Pulumi.yaml\")\nrand = random.RandomString(\"rand\", length=5)\nlocal_file = command.local.Command(\"localFile\",\n create=\"touch foo.txt\",\n archive_paths=[\"*.txt\"])\n\ncmd = command.remote.Command(\"cmd\",\n connection=command.remote.ConnectionArgs(\n host=\"insert host here\",\n ),\n create=\"echo create > op.txt\",\n delete=\"echo delete >> op.txt\",\n triggers=[\n foo,\n rand.result,\n file_asset_var,\n local_file.archive,\n ])\n```\n\n```go\npackage main\n\nimport (\n\t\"github.com/pulumi/pulumi-command/sdk/go/command/local\"\n\t\"github.com/pulumi/pulumi-command/sdk/go/command/remote\"\n\t\"github.com/pulumi/pulumi-random/sdk/v4/go/random\"\n\t\"github.com/pulumi/pulumi/sdk/v3/go/pulumi\"\n)\n\nfunc main() {\n\tpulumi.Run(func(ctx *pulumi.Context) error {\n\t\tstr := pulumi.String(\"foo\")\n\n\t\tfileAsset := pulumi.NewFileAsset(\"Pulumi.yaml\")\n\n\t\trand, err := random.NewRandomString(ctx, \"rand\", &random.RandomStringArgs{\n\t\t\tLength: pulumi.Int(5),\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tlocalFile, err := local.NewCommand(ctx, \"localFile\", &local.CommandArgs{\n\t\t\tCreate: pulumi.String(\"touch foo.txt\"),\n\t\t\tArchivePaths: pulumi.StringArray{\n\t\t\t\tpulumi.String(\"*.txt\"),\n\t\t\t},\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\t_, err = remote.NewCommand(ctx, \"cmd\", &remote.CommandArgs{\n\t\t\tConnection: &remote.ConnectionArgs{\n\t\t\t\tHost: pulumi.String(\"insert host here\"),\n\t\t\t},\n\t\t\tCreate: pulumi.String(\"echo create > op.txt\"),\n\t\t\tDelete: pulumi.String(\"echo delete >> op.txt\"),\n\t\t\tTriggers: pulumi.Array{\n\t\t\t\tstr,\n\t\t\t\trand.Result,\n\t\t\t\tfileAsset,\n\t\t\t\tlocalFile.Archive,\n\t\t\t},\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn nil\n\t})\n}\n```\n\n```csharp\nusing Pulumi;\nusing Command = Pulumi.Command;\nusing Random = Pulumi.Random;\n\nreturn await Deployment.RunAsync(() => \n{\n var str = \"foo\";\n\n var fileAssetVar = new FileAsset(\"Pulumi.yaml\");\n\n var rand = new Random.RandomString(\"rand\", new()\n {\n Length = 5,\n });\n\n var localFile = new Command.Local.Command(\"localFile\", new()\n {\n Create = \"touch foo.txt\",\n ArchivePaths = new[]\n {\n \"*.txt\",\n },\n });\n\n var cmd = new Command.Remote.Command(\"cmd\", new()\n {\n Connection = new Command.Remote.Inputs.ConnectionArgs\n {\n Host = \"insert host here\",\n },\n Create = \"echo create > op.txt\",\n Delete = \"echo delete >> op.txt\",\n Triggers = new object[]\n {\n str,\n rand.Result,\n fileAssetVar,\n localFile.Archive,\n },\n });\n\n});\n```\n\n```java\npublic class App {\n public static void main(String[] args) {\n Pulumi.run(App::stack);\n }\n\n public static void stack(Context ctx) {\n final var fileAssetVar = new FileAsset(\"Pulumi.yaml\");\n\n var rand = new RandomString(\"rand\", RandomStringArgs.builder()\n .length(5)\n .build());\n\n var localFile = new Command(\"localFile\", CommandArgs.builder()\n .create(\"touch foo.txt\")\n .archivePaths(\"*.txt\")\n .build());\n\n var cmd = new Command(\"cmd\", CommandArgs.builder()\n .connection(ConnectionArgs.builder()\n .host(\"insert host here\")\n .build())\n .create(\"echo create > op.txt\")\n .delete(\"echo delete >> op.txt\")\n .triggers( \n rand.result(),\n fileAssetVar,\n localFile.archive())\n .build());\n\n }\n}\n```\n\n```yaml\nconfig: {}\noutputs: {}\n\nresources:\n rand:\n type: random:index/randomString:RandomString\n properties:\n length: 5\n\n localFile:\n type: command:local:Command\n properties:\n create: touch foo.txt\n archivePaths:\n - \"*.txt\"\n\n cmd:\n type: command:remote:Command\n properties:\n connection:\n host: \"insert host here\"\n create: echo create > op.txt\n delete: echo delete >> op.txt\n triggers:\n - ${rand.result}\n - ${fileAsset}\n - ${localFile.archive}\n\nvariables:\n fileAsset:\n fn::fileAsset: \"Pulumi.yaml\"\n```\n\n{{% /example %}}\n\n{{% /examples %}}", "properties": { "addPreviousOutputInEnv": { "type": "boolean", @@ -414,7 +414,7 @@ "items": { "$ref": "pulumi.json#/Any" }, - "description": "Trigger replacements on changes to this input.", + "description": "Trigger a resource replacement on changes to any of these values. The\ntrigger values can be of any type. If a value is different in the current update compared to the\nprevious update, the resource will be replaced, i.e., the \"create\" command will be re-run.\nPlease see the resource documentation for examples.", "replaceOnChanges": true }, "update": { @@ -467,7 +467,7 @@ "items": { "$ref": "pulumi.json#/Any" }, - "description": "Trigger replacements on changes to this input.", + "description": "Trigger a resource replacement on changes to any of these values. The\ntrigger values can be of any type. If a value is different in the current update compared to the\nprevious update, the resource will be replaced, i.e., the \"create\" command will be re-run.\nPlease see the resource documentation for examples.", "replaceOnChanges": true }, "update": { diff --git a/provider/pkg/provider/common/inputs.go b/provider/pkg/provider/common/inputs.go index 10b69c6a..0d5fb957 100644 --- a/provider/pkg/provider/common/inputs.go +++ b/provider/pkg/provider/common/inputs.go @@ -17,7 +17,10 @@ type ResourceInputs struct { // Annotate lets you provide descriptions and default values for fields and they will // be visible in the provider's schema and the generated SDKs. func (c *ResourceInputs) Annotate(a infer.Annotator) { - a.Describe(&c.Triggers, "Trigger replacements on changes to this input.") + a.Describe(&c.Triggers, `Trigger a resource replacement on changes to any of these values. The +trigger values can be of any type. If a value is different in the current update compared to the +previous update, the resource will be replaced, i.e., the "create" command will be re-run. +Please see the resource documentation for examples.`) a.Describe(&c.Create, "The command to run on create.") a.Describe(&c.Delete, `The command to run on delete. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR are set to the stdout and stderr properties of the diff --git a/provider/pkg/provider/local/command.go b/provider/pkg/provider/local/command.go index 2015fae0..a734bdaa 100644 --- a/provider/pkg/provider/local/command.go +++ b/provider/pkg/provider/local/command.go @@ -12,15 +12,18 @@ // See the License for the specific language governing permissions and // limitations under the License. -// This file contains metadata around the types for - package local import ( + _ "embed" + "github.com/pulumi/pulumi-command/provider/pkg/provider/common" "github.com/pulumi/pulumi-go-provider/infer" ) +//go:embed command.md +var resourceDoc string + // This is the type that implements the Command resource methods. // The methods are declared in the commandController.go file. type Command struct{} @@ -34,11 +37,7 @@ var _ = (infer.Annotated)((*Command)(nil)) // Implementing Annotate lets you provide descriptions and default values for resources and they will // be visible in the provider's schema and the generated SDKs. func (c *Command) Annotate(a infer.Annotator) { - a.Describe(&c, "A local command to be executed.\n"+ - "This command can be inserted into the life cycles of other resources using the\n"+ - "`dependsOn` or `parent` resource options. A command is considered to have\n"+ - "failed when it finished with a non-zero exit code. This will fail the CRUD step\n"+ - "of the `Command` resource.") + a.Describe(&c, resourceDoc) } // These are the inputs (or arguments) to a Command resource. diff --git a/provider/pkg/provider/local/command.md b/provider/pkg/provider/local/command.md new file mode 100644 index 00000000..2d633453 --- /dev/null +++ b/provider/pkg/provider/local/command.md @@ -0,0 +1,215 @@ +A local command to be executed. + +This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + +{{% examples %}} +## Example Usage + +{{% example %}} +### Triggers + +This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + +```typescript +import * as pulumi from "@pulumi/pulumi"; +import * as command from "@pulumi/command"; +import * as random from "@pulumi/random"; + +const str = "foo"; +const fileAsset = new pulumi.asset.FileAsset("Pulumi.yaml"); +const rand = new random.RandomString("rand", {length: 5}); +const localFile = new command.local.Command("localFile", { + create: "touch foo.txt", + archivePaths: ["*.txt"], +}); + +const cmd = new command.local.Command("cmd", { + create: "echo create > op.txt", + delete: "echo delete >> op.txt", + triggers: [ + str, + rand.result, + fileAsset, + localFile.archive, + ], +}); +``` + +```python +import pulumi +import pulumi_command as command +import pulumi_random as random + +foo = "foo" +file_asset_var = pulumi.FileAsset("Pulumi.yaml") +rand = random.RandomString("rand", length=5) +local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + +cmd = command.local.Command("cmd", + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) +``` + +```go +package main + +import ( + "github.com/pulumi/pulumi-command/sdk/go/command/local" + "github.com/pulumi/pulumi-random/sdk/v4/go/random" + "github.com/pulumi/pulumi/sdk/v3/go/pulumi" +) + +func main() { + pulumi.Run(func(ctx *pulumi.Context) error { + str := pulumi.String("foo") + + fileAsset := pulumi.NewFileAsset("Pulumi.yaml") + + rand, err := random.NewRandomString(ctx, "rand", &random.RandomStringArgs{ + Length: pulumi.Int(5), + }) + if err != nil { + return err + } + + localFile, err := local.NewCommand(ctx, "localFile", &local.CommandArgs{ + Create: pulumi.String("touch foo.txt"), + ArchivePaths: pulumi.StringArray{ + pulumi.String("*.txt"), + }, + }) + if err != nil { + return err + } + + _, err = local.NewCommand(ctx, "cmd", &local.CommandArgs{ + Create: pulumi.String("echo create > op.txt"), + Delete: pulumi.String("echo delete >> op.txt"), + Triggers: pulumi.Array{ + str, + rand.Result, + fileAsset, + localFile.Archive, + }, + }) + if err != nil { + return err + } + return nil + }) +} +``` + +```csharp +using Pulumi; +using Command = Pulumi.Command; +using Random = Pulumi.Random; + +return await Deployment.RunAsync(() => +{ + var str = "foo"; + + var fileAssetVar = new FileAsset("Pulumi.yaml"); + + var rand = new Random.RandomString("rand", new() + { + Length = 5, + }); + + var localFile = new Command.Local.Command("localFile", new() + { + Create = "touch foo.txt", + ArchivePaths = new[] + { + "*.txt", + }, + }); + + var cmd = new Command.Local.Command("cmd", new() + { + Create = "echo create > op.txt", + Delete = "echo delete >> op.txt", + Triggers = new object[] + { + str, + rand.Result, + fileAssetVar, + localFile.Archive, + }, + }); + +}); +``` + +```java +public class App { + public static void main(String[] args) { + Pulumi.run(App::stack); + } + + public static void stack(Context ctx) { + final var fileAssetVar = new FileAsset("Pulumi.yaml"); + + var rand = new RandomString("rand", RandomStringArgs.builder() + .length(5) + .build()); + + var localFile = new Command("localFile", CommandArgs.builder() + .create("touch foo.txt") + .archivePaths("*.txt") + .build()); + + var cmd = new Command("cmd", CommandArgs.builder() + .create("echo create > op.txt") + .delete("echo delete >> op.txt") + .triggers( + rand.result(), + fileAssetVar, + localFile.archive()) + .build()); + + } +} +``` + +```yaml +config: {} +outputs: {} +resources: + rand: + type: random:index/randomString:RandomString + properties: + length: 5 + + localFile: + type: command:local:Command + properties: + create: touch foo.txt + archivePaths: + - "*.txt" + + cmd: + type: command:local:Command + properties: + create: echo create > op.txt + delete: echo delete >> op.txt + triggers: + - ${rand.result} + - ${fileAsset} + - ${localFile.archive} + +variables: + fileAsset: + fn::fileAsset: "Pulumi.yaml" +``` +{{% /example %}} + +{{% /examples %}} \ No newline at end of file diff --git a/provider/pkg/provider/remote/command.go b/provider/pkg/provider/remote/command.go index 833136e8..85efd747 100644 --- a/provider/pkg/provider/remote/command.go +++ b/provider/pkg/provider/remote/command.go @@ -15,18 +15,22 @@ package remote import ( + _ "embed" + "github.com/pulumi/pulumi-go-provider/infer" "github.com/pulumi/pulumi-command/provider/pkg/provider/common" ) +//go:embed command.md +var resourceDoc string + type Command struct{} // Implementing Annotate lets you provide descriptions for resources and they will // be visible in the provider's schema and the generated SDKs. func (c *Command) Annotate(a infer.Annotator) { - a.Describe(&c, `A command to run on a remote host. -The connection is established via ssh.`) + a.Describe(&c, resourceDoc) } // The arguments for a remote Command resource. diff --git a/provider/pkg/provider/remote/command.md b/provider/pkg/provider/remote/command.md new file mode 100644 index 00000000..9002f4f7 --- /dev/null +++ b/provider/pkg/provider/remote/command.md @@ -0,0 +1,234 @@ +A command to run on a remote host. The connection is established via ssh. + +{{% examples %}} +## Example Usage + +{{% example %}} +### Triggers + +This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + +```typescript +import * as pulumi from "@pulumi/pulumi"; +import * as command from "@pulumi/command"; +import * as random from "@pulumi/random"; + +const str = "foo"; +const fileAsset = new pulumi.asset.FileAsset("Pulumi.yaml"); +const rand = new random.RandomString("rand", {length: 5}); +const localFile = new command.local.Command("localFile", { + create: "touch foo.txt", + archivePaths: ["*.txt"], +}); +const cmd = new command.remote.Command("cmd", { + connection: { + host: "insert host here", + }, + create: "echo create > op.txt", + delete: "echo delete >> op.txt", + triggers: [ + str, + rand.result, + fileAsset, + localFile.archive, + ], +}); + +``` + +```python +import pulumi +import pulumi_command as command +import pulumi_random as random + +foo = "foo" +file_asset_var = pulumi.FileAsset("Pulumi.yaml") +rand = random.RandomString("rand", length=5) +local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + +cmd = command.remote.Command("cmd", + connection=command.remote.ConnectionArgs( + host="insert host here", + ), + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) +``` + +```go +package main + +import ( + "github.com/pulumi/pulumi-command/sdk/go/command/local" + "github.com/pulumi/pulumi-command/sdk/go/command/remote" + "github.com/pulumi/pulumi-random/sdk/v4/go/random" + "github.com/pulumi/pulumi/sdk/v3/go/pulumi" +) + +func main() { + pulumi.Run(func(ctx *pulumi.Context) error { + str := pulumi.String("foo") + + fileAsset := pulumi.NewFileAsset("Pulumi.yaml") + + rand, err := random.NewRandomString(ctx, "rand", &random.RandomStringArgs{ + Length: pulumi.Int(5), + }) + if err != nil { + return err + } + + localFile, err := local.NewCommand(ctx, "localFile", &local.CommandArgs{ + Create: pulumi.String("touch foo.txt"), + ArchivePaths: pulumi.StringArray{ + pulumi.String("*.txt"), + }, + }) + if err != nil { + return err + } + + _, err = remote.NewCommand(ctx, "cmd", &remote.CommandArgs{ + Connection: &remote.ConnectionArgs{ + Host: pulumi.String("insert host here"), + }, + Create: pulumi.String("echo create > op.txt"), + Delete: pulumi.String("echo delete >> op.txt"), + Triggers: pulumi.Array{ + str, + rand.Result, + fileAsset, + localFile.Archive, + }, + }) + if err != nil { + return err + } + return nil + }) +} +``` + +```csharp +using Pulumi; +using Command = Pulumi.Command; +using Random = Pulumi.Random; + +return await Deployment.RunAsync(() => +{ + var str = "foo"; + + var fileAssetVar = new FileAsset("Pulumi.yaml"); + + var rand = new Random.RandomString("rand", new() + { + Length = 5, + }); + + var localFile = new Command.Local.Command("localFile", new() + { + Create = "touch foo.txt", + ArchivePaths = new[] + { + "*.txt", + }, + }); + + var cmd = new Command.Remote.Command("cmd", new() + { + Connection = new Command.Remote.Inputs.ConnectionArgs + { + Host = "insert host here", + }, + Create = "echo create > op.txt", + Delete = "echo delete >> op.txt", + Triggers = new object[] + { + str, + rand.Result, + fileAssetVar, + localFile.Archive, + }, + }); + +}); +``` + +```java +public class App { + public static void main(String[] args) { + Pulumi.run(App::stack); + } + + public static void stack(Context ctx) { + final var fileAssetVar = new FileAsset("Pulumi.yaml"); + + var rand = new RandomString("rand", RandomStringArgs.builder() + .length(5) + .build()); + + var localFile = new Command("localFile", CommandArgs.builder() + .create("touch foo.txt") + .archivePaths("*.txt") + .build()); + + var cmd = new Command("cmd", CommandArgs.builder() + .connection(ConnectionArgs.builder() + .host("insert host here") + .build()) + .create("echo create > op.txt") + .delete("echo delete >> op.txt") + .triggers( + rand.result(), + fileAssetVar, + localFile.archive()) + .build()); + + } +} +``` + +```yaml +config: {} +outputs: {} + +resources: + rand: + type: random:index/randomString:RandomString + properties: + length: 5 + + localFile: + type: command:local:Command + properties: + create: touch foo.txt + archivePaths: + - "*.txt" + + cmd: + type: command:remote:Command + properties: + connection: + host: "insert host here" + create: echo create > op.txt + delete: echo delete >> op.txt + triggers: + - ${rand.result} + - ${fileAsset} + - ${localFile.archive} + +variables: + fileAsset: + fn::fileAsset: "Pulumi.yaml" +``` + +{{% /example %}} + +{{% /examples %}} \ No newline at end of file diff --git a/sdk/dotnet/Local/Command.cs b/sdk/dotnet/Local/Command.cs index f8065ccf..aca5604b 100644 --- a/sdk/dotnet/Local/Command.cs +++ b/sdk/dotnet/Local/Command.cs @@ -11,10 +11,54 @@ namespace Pulumi.Command.Local { /// /// A local command to be executed. - /// This command can be inserted into the life cycles of other resources using the - /// `dependsOn` or `parent` resource options. A command is considered to have - /// failed when it finished with a non-zero exit code. This will fail the CRUD step - /// of the `Command` resource. + /// + /// This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + /// + /// ## Example Usage + /// ### Triggers + /// + /// This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + /// + /// ```csharp + /// using Pulumi; + /// using Command = Pulumi.Command; + /// using Random = Pulumi.Random; + /// + /// return await Deployment.RunAsync(() => + /// { + /// var str = "foo"; + /// + /// var fileAssetVar = new FileAsset("Pulumi.yaml"); + /// + /// var rand = new Random.RandomString("rand", new() + /// { + /// Length = 5, + /// }); + /// + /// var localFile = new Command.Local.Command("localFile", new() + /// { + /// Create = "touch foo.txt", + /// ArchivePaths = new[] + /// { + /// "*.txt", + /// }, + /// }); + /// + /// var cmd = new Command.Local.Command("cmd", new() + /// { + /// Create = "echo create > op.txt", + /// Delete = "echo delete >> op.txt", + /// Triggers = new object[] + /// { + /// str, + /// rand.Result, + /// fileAssetVar, + /// localFile.Archive, + /// }, + /// }); + /// + /// }); + /// ``` /// [CommandResourceType("command:local:Command")] public partial class Command : global::Pulumi.CustomResource @@ -187,7 +231,10 @@ public partial class Command : global::Pulumi.CustomResource public Output Stdout { get; private set; } = null!; /// - /// Trigger replacements on changes to this input. + /// Trigger a resource replacement on changes to any of these values. The + /// trigger values can be of any type. If a value is different in the current update compared to the + /// previous update, the resource will be replaced, i.e., the "create" command will be re-run. + /// Please see the resource documentation for examples. /// [Output("triggers")] public Output> Triggers { get; private set; } = null!; @@ -420,7 +467,10 @@ public InputList Interpreter private InputList? _triggers; /// - /// Trigger replacements on changes to this input. + /// Trigger a resource replacement on changes to any of these values. The + /// trigger values can be of any type. If a value is different in the current update compared to the + /// previous update, the resource will be replaced, i.e., the "create" command will be re-run. + /// Please see the resource documentation for examples. /// public InputList Triggers { diff --git a/sdk/dotnet/Remote/Command.cs b/sdk/dotnet/Remote/Command.cs index fb0dc7b6..32274e2e 100644 --- a/sdk/dotnet/Remote/Command.cs +++ b/sdk/dotnet/Remote/Command.cs @@ -10,8 +10,57 @@ namespace Pulumi.Command.Remote { /// - /// A command to run on a remote host. - /// The connection is established via ssh. + /// A command to run on a remote host. The connection is established via ssh. + /// + /// ## Example Usage + /// ### Triggers + /// + /// This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + /// + /// ```csharp + /// using Pulumi; + /// using Command = Pulumi.Command; + /// using Random = Pulumi.Random; + /// + /// return await Deployment.RunAsync(() => + /// { + /// var str = "foo"; + /// + /// var fileAssetVar = new FileAsset("Pulumi.yaml"); + /// + /// var rand = new Random.RandomString("rand", new() + /// { + /// Length = 5, + /// }); + /// + /// var localFile = new Command.Local.Command("localFile", new() + /// { + /// Create = "touch foo.txt", + /// ArchivePaths = new[] + /// { + /// "*.txt", + /// }, + /// }); + /// + /// var cmd = new Command.Remote.Command("cmd", new() + /// { + /// Connection = new Command.Remote.Inputs.ConnectionArgs + /// { + /// Host = "insert host here", + /// }, + /// Create = "echo create > op.txt", + /// Delete = "echo delete >> op.txt", + /// Triggers = new object[] + /// { + /// str, + /// rand.Result, + /// fileAssetVar, + /// localFile.Archive, + /// }, + /// }); + /// + /// }); + /// ``` /// [CommandResourceType("command:remote:Command")] public partial class Command : global::Pulumi.CustomResource @@ -80,7 +129,10 @@ public partial class Command : global::Pulumi.CustomResource public Output Stdout { get; private set; } = null!; /// - /// Trigger replacements on changes to this input. + /// Trigger a resource replacement on changes to any of these values. The + /// trigger values can be of any type. If a value is different in the current update compared to the + /// previous update, the resource will be replaced, i.e., the "create" command will be re-run. + /// Please see the resource documentation for examples. /// [Output("triggers")] public Output> Triggers { get; private set; } = null!; @@ -218,7 +270,10 @@ public InputMap Environment private InputList? _triggers; /// - /// Trigger replacements on changes to this input. + /// Trigger a resource replacement on changes to any of these values. The + /// trigger values can be of any type. If a value is different in the current update compared to the + /// previous update, the resource will be replaced, i.e., the "create" command will be re-run. + /// Please see the resource documentation for examples. /// public InputList Triggers { diff --git a/sdk/go/command/local/command.go b/sdk/go/command/local/command.go index 047a57a1..0318988a 100644 --- a/sdk/go/command/local/command.go +++ b/sdk/go/command/local/command.go @@ -12,10 +12,66 @@ import ( ) // A local command to be executed. -// This command can be inserted into the life cycles of other resources using the -// `dependsOn` or `parent` resource options. A command is considered to have -// failed when it finished with a non-zero exit code. This will fail the CRUD step -// of the `Command` resource. +// +// This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. +// +// ## Example Usage +// ### Triggers +// +// This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. +// +// ```go +// package main +// +// import ( +// +// "github.com/pulumi/pulumi-command/sdk/go/command/local" +// "github.com/pulumi/pulumi-random/sdk/v4/go/random" +// "github.com/pulumi/pulumi/sdk/v3/go/pulumi" +// +// ) +// +// func main() { +// pulumi.Run(func(ctx *pulumi.Context) error { +// str := pulumi.String("foo") +// +// fileAsset := pulumi.NewFileAsset("Pulumi.yaml") +// +// rand, err := random.NewRandomString(ctx, "rand", &random.RandomStringArgs{ +// Length: pulumi.Int(5), +// }) +// if err != nil { +// return err +// } +// +// localFile, err := local.NewCommand(ctx, "localFile", &local.CommandArgs{ +// Create: pulumi.String("touch foo.txt"), +// ArchivePaths: pulumi.StringArray{ +// pulumi.String("*.txt"), +// }, +// }) +// if err != nil { +// return err +// } +// +// _, err = local.NewCommand(ctx, "cmd", &local.CommandArgs{ +// Create: pulumi.String("echo create > op.txt"), +// Delete: pulumi.String("echo delete >> op.txt"), +// Triggers: pulumi.Array{ +// str, +// rand.Result, +// fileAsset, +// localFile.Archive, +// }, +// }) +// if err != nil { +// return err +// } +// return nil +// }) +// } +// +// ``` type Command struct { pulumi.CustomResourceState @@ -92,7 +148,10 @@ type Command struct { Stdin pulumi.StringPtrOutput `pulumi:"stdin"` // The standard output of the command's process Stdout pulumi.StringOutput `pulumi:"stdout"` - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers pulumi.ArrayOutput `pulumi:"triggers"` // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -212,7 +271,10 @@ type commandArgs struct { Logging *Logging `pulumi:"logging"` // Pass a string to the command's process as standard in Stdin *string `pulumi:"stdin"` - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers []interface{} `pulumi:"triggers"` // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -287,7 +349,10 @@ type CommandArgs struct { Logging LoggingPtrInput // Pass a string to the command's process as standard in Stdin pulumi.StringPtrInput - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers pulumi.ArrayInput // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -498,7 +563,10 @@ func (o CommandOutput) Stdout() pulumi.StringOutput { return o.ApplyT(func(v *Command) pulumi.StringOutput { return v.Stdout }).(pulumi.StringOutput) } -// Trigger replacements on changes to this input. +// Trigger a resource replacement on changes to any of these values. The +// trigger values can be of any type. If a value is different in the current update compared to the +// previous update, the resource will be replaced, i.e., the "create" command will be re-run. +// Please see the resource documentation for examples. func (o CommandOutput) Triggers() pulumi.ArrayOutput { return o.ApplyT(func(v *Command) pulumi.ArrayOutput { return v.Triggers }).(pulumi.ArrayOutput) } diff --git a/sdk/go/command/remote/command.go b/sdk/go/command/remote/command.go index 435e9d4b..b784ee6e 100644 --- a/sdk/go/command/remote/command.go +++ b/sdk/go/command/remote/command.go @@ -12,8 +12,69 @@ import ( "github.com/pulumi/pulumi/sdk/v3/go/pulumi" ) -// A command to run on a remote host. -// The connection is established via ssh. +// A command to run on a remote host. The connection is established via ssh. +// +// ## Example Usage +// ### Triggers +// +// This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. +// +// ```go +// package main +// +// import ( +// +// "github.com/pulumi/pulumi-command/sdk/go/command/local" +// "github.com/pulumi/pulumi-command/sdk/go/command/remote" +// "github.com/pulumi/pulumi-random/sdk/v4/go/random" +// "github.com/pulumi/pulumi/sdk/v3/go/pulumi" +// +// ) +// +// func main() { +// pulumi.Run(func(ctx *pulumi.Context) error { +// str := pulumi.String("foo") +// +// fileAsset := pulumi.NewFileAsset("Pulumi.yaml") +// +// rand, err := random.NewRandomString(ctx, "rand", &random.RandomStringArgs{ +// Length: pulumi.Int(5), +// }) +// if err != nil { +// return err +// } +// +// localFile, err := local.NewCommand(ctx, "localFile", &local.CommandArgs{ +// Create: pulumi.String("touch foo.txt"), +// ArchivePaths: pulumi.StringArray{ +// pulumi.String("*.txt"), +// }, +// }) +// if err != nil { +// return err +// } +// +// _, err = remote.NewCommand(ctx, "cmd", &remote.CommandArgs{ +// Connection: &remote.ConnectionArgs{ +// Host: pulumi.String("insert host here"), +// }, +// Create: pulumi.String("echo create > op.txt"), +// Delete: pulumi.String("echo delete >> op.txt"), +// Triggers: pulumi.Array{ +// str, +// rand.Result, +// fileAsset, +// localFile.Archive, +// }, +// }) +// if err != nil { +// return err +// } +// return nil +// }) +// } +// +// ``` type Command struct { pulumi.CustomResourceState @@ -44,7 +105,10 @@ type Command struct { Stdin pulumi.StringPtrOutput `pulumi:"stdin"` // The standard output of the command's process Stdout pulumi.StringOutput `pulumi:"stdout"` - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers pulumi.ArrayOutput `pulumi:"triggers"` // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -134,7 +198,10 @@ type commandArgs struct { Logging *Logging `pulumi:"logging"` // Pass a string to the command's process as standard in Stdin *string `pulumi:"stdin"` - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers []interface{} `pulumi:"triggers"` // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -168,7 +235,10 @@ type CommandArgs struct { Logging LoggingPtrInput // Pass a string to the command's process as standard in Stdin pulumi.StringPtrInput - // Trigger replacements on changes to this input. + // Trigger a resource replacement on changes to any of these values. The + // trigger values can be of any type. If a value is different in the current update compared to the + // previous update, the resource will be replaced, i.e., the "create" command will be re-run. + // Please see the resource documentation for examples. Triggers pulumi.ArrayInput // The command to run on update, if empty, create will // run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR @@ -318,7 +388,10 @@ func (o CommandOutput) Stdout() pulumi.StringOutput { return o.ApplyT(func(v *Command) pulumi.StringOutput { return v.Stdout }).(pulumi.StringOutput) } -// Trigger replacements on changes to this input. +// Trigger a resource replacement on changes to any of these values. The +// trigger values can be of any type. If a value is different in the current update compared to the +// previous update, the resource will be replaced, i.e., the "create" command will be re-run. +// Please see the resource documentation for examples. func (o CommandOutput) Triggers() pulumi.ArrayOutput { return o.ApplyT(func(v *Command) pulumi.ArrayOutput { return v.Triggers }).(pulumi.ArrayOutput) } diff --git a/sdk/java/src/main/java/com/pulumi/command/local/Command.java b/sdk/java/src/main/java/com/pulumi/command/local/Command.java index 0b572dc3..792cf165 100644 --- a/sdk/java/src/main/java/com/pulumi/command/local/Command.java +++ b/sdk/java/src/main/java/com/pulumi/command/local/Command.java @@ -22,10 +22,46 @@ /** * A local command to be executed. - * This command can be inserted into the life cycles of other resources using the - * `dependsOn` or `parent` resource options. A command is considered to have - * failed when it finished with a non-zero exit code. This will fail the CRUD step - * of the `Command` resource. + * + * This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + * + * ## Example Usage + * ### Triggers + * + * This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + * + * 
+ * {@code
+ * public class App {
+ *     public static void main(String[] args) {
+ *         Pulumi.run(App::stack);
+ *     }
+ * 
+ *     public static void stack(Context ctx) {
+ *         final var fileAssetVar = new FileAsset("Pulumi.yaml");
+ * 
+ *         var rand = new RandomString("rand", RandomStringArgs.builder()
+ *             .length(5)
+ *             .build());
+ * 
+ *         var localFile = new Command("localFile", CommandArgs.builder()
+ *             .create("touch foo.txt")
+ *             .archivePaths("*.txt")
+ *             .build());
+ * 
+ *         var cmd = new Command("cmd", CommandArgs.builder()
+ *             .create("echo create > op.txt")
+ *             .delete("echo delete >> op.txt")
+ *             .triggers(
+ *                 rand.result(),
+ *                 fileAssetVar,
+ *                 localFile.archive())
+ *             .build());
+ * 
+ *     }
+ * }
+ * }
+ *
* */ @ResourceType(type="command:local:Command") @@ -317,14 +353,20 @@ public Output stdout() { return this.stdout; } /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ @Export(name="triggers", refs={List.class,Object.class}, tree="[0,1]") private Output> triggers; /** - * @return Trigger replacements on changes to this input. + * @return Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ public Output>> triggers() { diff --git a/sdk/java/src/main/java/com/pulumi/command/local/CommandArgs.java b/sdk/java/src/main/java/com/pulumi/command/local/CommandArgs.java index 3fa6e71c..744f8139 100644 --- a/sdk/java/src/main/java/com/pulumi/command/local/CommandArgs.java +++ b/sdk/java/src/main/java/com/pulumi/command/local/CommandArgs.java @@ -260,14 +260,20 @@ public Optional> stdin() { } /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ @Import(name="triggers") private @Nullable Output> triggers; /** - * @return Trigger replacements on changes to this input. + * @return Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ public Optional>> triggers() { @@ -696,7 +702,10 @@ public Builder stdin(String stdin) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * @@ -707,7 +716,10 @@ public Builder triggers(@Nullable Output> triggers) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * @@ -717,7 +729,10 @@ public Builder triggers(List triggers) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * diff --git a/sdk/java/src/main/java/com/pulumi/command/remote/Command.java b/sdk/java/src/main/java/com/pulumi/command/remote/Command.java index 1799da63..3c58d4dd 100644 --- a/sdk/java/src/main/java/com/pulumi/command/remote/Command.java +++ b/sdk/java/src/main/java/com/pulumi/command/remote/Command.java @@ -20,8 +20,48 @@ import javax.annotation.Nullable; /** - * A command to run on a remote host. - * The connection is established via ssh. + * A command to run on a remote host. The connection is established via ssh. + * + * ## Example Usage + * ### Triggers + * + * This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + * + * 
+ * {@code
+ * public class App {
+ *     public static void main(String[] args) {
+ *         Pulumi.run(App::stack);
+ *     }
+ * 
+ *     public static void stack(Context ctx) {
+ *         final var fileAssetVar = new FileAsset("Pulumi.yaml");
+ * 
+ *         var rand = new RandomString("rand", RandomStringArgs.builder()
+ *             .length(5)
+ *             .build());
+ * 
+ *         var localFile = new Command("localFile", CommandArgs.builder()
+ *             .create("touch foo.txt")
+ *             .archivePaths("*.txt")
+ *             .build());
+ * 
+ *         var cmd = new Command("cmd", CommandArgs.builder()
+ *             .connection(ConnectionArgs.builder()
+ *                 .host("insert host here")
+ *                 .build())
+ *             .create("echo create > op.txt")
+ *             .delete("echo delete >> op.txt")
+ *             .triggers(            
+ *                 rand.result(),
+ *                 fileAssetVar,
+ *                 localFile.archive())
+ *             .build());
+ * 
+ *     }
+ * }
+ * }
+ *
* */ @ResourceType(type="command:remote:Command") @@ -171,14 +211,20 @@ public Output stdout() { return this.stdout; } /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ @Export(name="triggers", refs={List.class,Object.class}, tree="[0,1]") private Output> triggers; /** - * @return Trigger replacements on changes to this input. + * @return Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ public Output>> triggers() { diff --git a/sdk/java/src/main/java/com/pulumi/command/remote/CommandArgs.java b/sdk/java/src/main/java/com/pulumi/command/remote/CommandArgs.java index 08036ab3..1ca9bbdb 100644 --- a/sdk/java/src/main/java/com/pulumi/command/remote/CommandArgs.java +++ b/sdk/java/src/main/java/com/pulumi/command/remote/CommandArgs.java @@ -147,14 +147,20 @@ public Optional> stdin() { } /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ @Import(name="triggers") private @Nullable Output> triggers; /** - * @return Trigger replacements on changes to this input. + * @return Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * */ public Optional>> triggers() { @@ -380,7 +386,10 @@ public Builder stdin(String stdin) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * @@ -391,7 +400,10 @@ public Builder triggers(@Nullable Output> triggers) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * @@ -401,7 +413,10 @@ public Builder triggers(List triggers) { } /** - * @param triggers Trigger replacements on changes to this input. + * @param triggers Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. * * @return builder * diff --git a/sdk/nodejs/local/command.ts b/sdk/nodejs/local/command.ts index e2ecdff4..c55daec4 100644 --- a/sdk/nodejs/local/command.ts +++ b/sdk/nodejs/local/command.ts @@ -9,10 +9,38 @@ import * as utilities from "../utilities"; /** * A local command to be executed. - * This command can be inserted into the life cycles of other resources using the - * `dependsOn` or `parent` resource options. A command is considered to have - * failed when it finished with a non-zero exit code. This will fail the CRUD step - * of the `Command` resource. + * + * This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + * + * ## Example Usage + * ### Triggers + * + * This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + * + * ```typescript + * import * as pulumi from "@pulumi/pulumi"; + * import * as command from "@pulumi/command"; + * import * as random from "@pulumi/random"; + * + * const str = "foo"; + * const fileAsset = new pulumi.asset.FileAsset("Pulumi.yaml"); + * const rand = new random.RandomString("rand", {length: 5}); + * const localFile = new command.local.Command("localFile", { + * create: "touch foo.txt", + * archivePaths: ["*.txt"], + * }); + * + * const cmd = new command.local.Command("cmd", { + * create: "echo create > op.txt", + * delete: "echo delete >> op.txt", + * triggers: [ + * str, + * rand.result, + * fileAsset, + * localFile.archive, + * ], + * }); + * ``` */ export class Command extends pulumi.CustomResource { /** @@ -181,7 +209,10 @@ export class Command extends pulumi.CustomResource { */ public /*out*/ readonly stdout!: pulumi.Output; /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. */ public readonly triggers!: pulumi.Output; /** @@ -371,7 +402,10 @@ export interface CommandArgs { */ stdin?: pulumi.Input; /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. */ triggers?: pulumi.Input; /** diff --git a/sdk/nodejs/remote/command.ts b/sdk/nodejs/remote/command.ts index 193da79f..07fb5859 100644 --- a/sdk/nodejs/remote/command.ts +++ b/sdk/nodejs/remote/command.ts @@ -8,8 +8,40 @@ import * as enums from "../types/enums"; import * as utilities from "../utilities"; /** - * A command to run on a remote host. - * The connection is established via ssh. + * A command to run on a remote host. The connection is established via ssh. + * + * ## Example Usage + * ### Triggers + * + * This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + * + * ```typescript + * import * as pulumi from "@pulumi/pulumi"; + * import * as command from "@pulumi/command"; + * import * as random from "@pulumi/random"; + * + * const str = "foo"; + * const fileAsset = new pulumi.asset.FileAsset("Pulumi.yaml"); + * const rand = new random.RandomString("rand", {length: 5}); + * const localFile = new command.local.Command("localFile", { + * create: "touch foo.txt", + * archivePaths: ["*.txt"], + * }); + * const cmd = new command.remote.Command("cmd", { + * connection: { + * host: "insert host here", + * }, + * create: "echo create > op.txt", + * delete: "echo delete >> op.txt", + * triggers: [ + * str, + * rand.result, + * fileAsset, + * localFile.archive, + * ], + * }); + * + * ``` */ export class Command extends pulumi.CustomResource { /** @@ -84,7 +116,10 @@ export class Command extends pulumi.CustomResource { */ public /*out*/ readonly stdout!: pulumi.Output; /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. */ public readonly triggers!: pulumi.Output; /** @@ -184,7 +219,10 @@ export interface CommandArgs { */ stdin?: pulumi.Input; /** - * Trigger replacements on changes to this input. + * Trigger a resource replacement on changes to any of these values. The + * trigger values can be of any type. If a value is different in the current update compared to the + * previous update, the resource will be replaced, i.e., the "create" command will be re-run. + * Please see the resource documentation for examples. */ triggers?: pulumi.Input; /** diff --git a/sdk/python/pulumi_command/local/command.py b/sdk/python/pulumi_command/local/command.py index 291814ce..dc9f7b86 100644 --- a/sdk/python/pulumi_command/local/command.py +++ b/sdk/python/pulumi_command/local/command.py @@ -121,7 +121,10 @@ def __init__(__self__, *, stdout and stderr as outputs. If there might be secrets in the output, you can disable logging here and mark the outputs as secret via 'additionalSecretOutputs'. Defaults to logging both stdout and stderr. :param pulumi.Input[str] stdin: Pass a string to the command's process as standard in - :param pulumi.Input[Sequence[Any]] triggers: Trigger replacements on changes to this input. + :param pulumi.Input[Sequence[Any]] triggers: Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. :param pulumi.Input[str] update: The command to run on update, if empty, create will run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR are set to the stdout and stderr properties of the Command resource from previous @@ -360,7 +363,10 @@ def stdin(self, value: Optional[pulumi.Input[str]]): @pulumi.getter def triggers(self) -> Optional[pulumi.Input[Sequence[Any]]]: """ - Trigger replacements on changes to this input. + Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. """ return pulumi.get(self, "triggers") @@ -404,10 +410,36 @@ def __init__(__self__, __props__=None): """ A local command to be executed. - This command can be inserted into the life cycles of other resources using the - `dependsOn` or `parent` resource options. A command is considered to have - failed when it finished with a non-zero exit code. This will fail the CRUD step - of the `Command` resource. + + This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + + ## Example Usage + ### Triggers + + This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + + ```python + import pulumi + import pulumi_command as command + import pulumi_random as random + + foo = "foo" + file_asset_var = pulumi.FileAsset("Pulumi.yaml") + rand = random.RandomString("rand", length=5) + local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + + cmd = command.local.Command("cmd", + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) + ``` :param str resource_name: The name of the resource. :param pulumi.ResourceOptions opts: Options for the resource. @@ -503,7 +535,10 @@ def __init__(__self__, stdout and stderr as outputs. If there might be secrets in the output, you can disable logging here and mark the outputs as secret via 'additionalSecretOutputs'. Defaults to logging both stdout and stderr. :param pulumi.Input[str] stdin: Pass a string to the command's process as standard in - :param pulumi.Input[Sequence[Any]] triggers: Trigger replacements on changes to this input. + :param pulumi.Input[Sequence[Any]] triggers: Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. :param pulumi.Input[str] update: The command to run on update, if empty, create will run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR are set to the stdout and stderr properties of the Command resource from previous @@ -517,10 +552,36 @@ def __init__(__self__, opts: Optional[pulumi.ResourceOptions] = None): """ A local command to be executed. - This command can be inserted into the life cycles of other resources using the - `dependsOn` or `parent` resource options. A command is considered to have - failed when it finished with a non-zero exit code. This will fail the CRUD step - of the `Command` resource. + + This command can be inserted into the life cycles of other resources using the `dependsOn` or `parent` resource options. A command is considered to have failed when it finished with a non-zero exit code. This will fail the CRUD step of the `Command` resource. + + ## Example Usage + ### Triggers + + This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + + ```python + import pulumi + import pulumi_command as command + import pulumi_random as random + + foo = "foo" + file_asset_var = pulumi.FileAsset("Pulumi.yaml") + rand = random.RandomString("rand", length=5) + local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + + cmd = command.local.Command("cmd", + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) + ``` :param str resource_name: The name of the resource. :param CommandArgs args: The arguments to use to populate this resource's properties. @@ -817,7 +878,10 @@ def stdout(self) -> pulumi.Output[str]: @pulumi.getter def triggers(self) -> pulumi.Output[Optional[Sequence[Any]]]: """ - Trigger replacements on changes to this input. + Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. """ return pulumi.get(self, "triggers") diff --git a/sdk/python/pulumi_command/remote/command.py b/sdk/python/pulumi_command/remote/command.py index 5a33d156..b5b90403 100644 --- a/sdk/python/pulumi_command/remote/command.py +++ b/sdk/python/pulumi_command/remote/command.py @@ -44,7 +44,10 @@ def __init__(__self__, *, stdout and stderr as outputs. If there might be secrets in the output, you can disable logging here and mark the outputs as secret via 'additionalSecretOutputs'. Defaults to logging both stdout and stderr. :param pulumi.Input[str] stdin: Pass a string to the command's process as standard in - :param pulumi.Input[Sequence[Any]] triggers: Trigger replacements on changes to this input. + :param pulumi.Input[Sequence[Any]] triggers: Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. :param pulumi.Input[str] update: The command to run on update, if empty, create will run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR are set to the stdout and stderr properties of the Command resource from previous @@ -167,7 +170,10 @@ def stdin(self, value: Optional[pulumi.Input[str]]): @pulumi.getter def triggers(self) -> Optional[pulumi.Input[Sequence[Any]]]: """ - Trigger replacements on changes to this input. + Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. """ return pulumi.get(self, "triggers") @@ -207,8 +213,38 @@ def __init__(__self__, update: Optional[pulumi.Input[str]] = None, __props__=None): """ - A command to run on a remote host. - The connection is established via ssh. + A command to run on a remote host. The connection is established via ssh. + + ## Example Usage + ### Triggers + + This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + + ```python + import pulumi + import pulumi_command as command + import pulumi_random as random + + foo = "foo" + file_asset_var = pulumi.FileAsset("Pulumi.yaml") + rand = random.RandomString("rand", length=5) + local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + + cmd = command.remote.Command("cmd", + connection=command.remote.ConnectionArgs( + host="insert host here", + ), + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) + ``` :param str resource_name: The name of the resource. :param pulumi.ResourceOptions opts: Options for the resource. @@ -228,7 +264,10 @@ def __init__(__self__, stdout and stderr as outputs. If there might be secrets in the output, you can disable logging here and mark the outputs as secret via 'additionalSecretOutputs'. Defaults to logging both stdout and stderr. :param pulumi.Input[str] stdin: Pass a string to the command's process as standard in - :param pulumi.Input[Sequence[Any]] triggers: Trigger replacements on changes to this input. + :param pulumi.Input[Sequence[Any]] triggers: Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. :param pulumi.Input[str] update: The command to run on update, if empty, create will run again. The environment variables PULUMI_COMMAND_STDOUT and PULUMI_COMMAND_STDERR are set to the stdout and stderr properties of the Command resource from previous @@ -241,8 +280,38 @@ def __init__(__self__, args: CommandArgs, opts: Optional[pulumi.ResourceOptions] = None): """ - A command to run on a remote host. - The connection is established via ssh. + A command to run on a remote host. The connection is established via ssh. + + ## Example Usage + ### Triggers + + This example defines several trigger values of various kinds. Changes to any of them will cause `cmd` to be re-run. + + ```python + import pulumi + import pulumi_command as command + import pulumi_random as random + + foo = "foo" + file_asset_var = pulumi.FileAsset("Pulumi.yaml") + rand = random.RandomString("rand", length=5) + local_file = command.local.Command("localFile", + create="touch foo.txt", + archive_paths=["*.txt"]) + + cmd = command.remote.Command("cmd", + connection=command.remote.ConnectionArgs( + host="insert host here", + ), + create="echo create > op.txt", + delete="echo delete >> op.txt", + triggers=[ + foo, + rand.result, + file_asset_var, + local_file.archive, + ]) + ``` :param str resource_name: The name of the resource. :param CommandArgs args: The arguments to use to populate this resource's properties. @@ -416,7 +485,10 @@ def stdout(self) -> pulumi.Output[str]: @pulumi.getter def triggers(self) -> pulumi.Output[Optional[Sequence[Any]]]: """ - Trigger replacements on changes to this input. + Trigger a resource replacement on changes to any of these values. The + trigger values can be of any type. If a value is different in the current update compared to the + previous update, the resource will be replaced, i.e., the "create" command will be re-run. + Please see the resource documentation for examples. """ return pulumi.get(self, "triggers")