@pulumi/command 0.0.4-alpha.1646714993 → 0.1.0-alpha.1779516124

package/README.md

@@ -1,4 +1,12 @@
-# Pulumi Command Provider (preview)
+[![Actions Status](https://github.com/pulumi/pulumi-command/workflows/master/badge.svg)](https://github.com/pulumi/pulumi-command/actions)
+[![Slack](http://www.pulumi.com/images/docs/badges/slack.svg)](https://slack.pulumi.com)
+[![NPM version](https://badge.fury.io/js/%40pulumi%2Fcommand.svg)](https://www.npmjs.com/package/@pulumi/command)
+[![Python version](https://badge.fury.io/py/pulumi-command.svg)](https://pypi.org/project/pulumi-command)
+[![NuGet version](https://badge.fury.io/nu/pulumi.command.svg)](https://badge.fury.io/nu/pulumi.command)
+[![PkgGoDev](https://pkg.go.dev/badge/github.com/pulumi/pulumi-command/sdk/go)](https://pkg.go.dev/github.com/pulumi/pulumi-command/sdk/go)
+[![License](https://img.shields.io/npm/l/%40pulumi%2Fpulumi.svg)](https://github.com/pulumi/pulumi-command/blob/master/LICENSE)
+
+# Pulumi Command Provider
 
 The Pulumi Command Provider enables you to execute commands and scripts either locally or remotely as part of the Pulumi resource model.  Resources in the command package support running scripts on `create` and `destroy` operations, supporting stateful local and remote command execution.
 
@@ -12,12 +20,10 @@ There are many scenarios where the Command package can be useful:
 
 Some users may have experience with Terraform "provisioners", and the Command package offers support for similar scenarios.  However, the Command package is provided as independent resources which can be combined with other resources in many interesting ways. This has many strengths, but also some differences, such as the fact that a Command resource failing does not cause a resource it is operating on to fail.
 
-You can use the Command package from a Pulumi program written in any Pulumi language: C#, Go, JavaScript/TypeScript, and Python.
+You can use the Command package from a Pulumi program written in any Pulumi language: C#, Go, JavaScript/TypeScript, Python, and YAML.
 You'll need to [install and configure the Pulumi CLI](https://pulumi.com/docs/get-started/install) if you haven't already.
 
 
-> **NOTE**: The Command package is in preview.  The API design may change ahead of general availability based on [user feedback](https://github.com/pulumi/pulumi-command/issues). 
-
 ## Examples
 
 ### A simple local resource (random)
@@ -45,7 +51,7 @@ import (
 func main() {
 	pulumi.Run(func(ctx *pulumi.Context) error {
 
-		random, err := local.NewCommand(ctx, "my-bucket", &local.CommandArgs{
+		random, err := local.NewCommand(ctx, "my-bucket", &local.CommandInput{
 			Create: pulumi.String("openssl rand -hex 16"),
 		})
 		if err != nil {
@@ -108,7 +114,7 @@ const server = new aws.ec2.Instance("server", {
 
 // Now set up a connection to the instance and run some provisioning operations on the instance.
 
-const connection: types.input.remote.ConnectionArgs = {
+const connection: types.input.remote.ConnectionInput = {
     host: server.publicIp,
     user: "ec2-user",
     privateKey: privateKey,
@@ -181,7 +187,7 @@ export const output = rand.stdout;
 
 ### Using `local.Command `with CURL to manage external REST API
 
-This example uses `local.Command` to create a simple resource provider for managing GitHub labels, by invoking `curl` commands on `create` and `delete` commands against the GitHub REST API.  A similar approach could be applied to build other simple providers against any REST API directly from within Pulumi programs in any language.  This approach is somewhat limited by the fact that `local.Command` does not yet support `diff`/`update`/`read`.  Support for those may be [added in the future](https://github.com/pulumi/pulumi-command/issues/20).
+This example uses `local.Command` to create a simple resource provider for managing GitHub labels, by invoking `curl` commands on `create` and `delete` commands against the GitHub REST API. A similar approach could be applied to build other simple providers against any REST API directly from within Pulumi programs in any language. This approach is somewhat limited by the fact that `local.Command` does not yet support `diff`/`read`. Support for [Read](https://github.com/pulumi/pulumi-command/issues/432) and [Diff](https://github.com/pulumi/pulumi-command/issues/433) may be added in the future.
 
 This example also shows how `local.Command` can be used as an implementation detail inside a nicer abstraction, like the `GitHubLabel` component defined below.
 
@@ -255,32 +261,111 @@ curl \
 
 ### Graceful cleanup of workloads in a Kubernetes cluster
 
-There are cases where it's important to run some cleanup operation before destroying a resource, in case destroying the resource does not properly handle orderly cleanup.  For example, destroying an EKS Cluster will not ensure that all Kubernetes object finalizers are run, which may lead to leaking external resources managed by those Kubernetes resources.  This example shows how we can use a `delete`-only `Command` to ensure some cleanup is run within a cluster before destroying it.
+There are cases where it's important to run some cleanup operation before destroying a resource such as when destroying the resource does not properly handle orderly cleanup.  For example, destroying an EKS Cluster will not ensure that all Kubernetes object finalizers are run, which may lead to leaking external resources managed by those Kubernetes resources.  This example shows how we can use a `delete`-only `Command` to ensure some cleanup is run within a cluster before destroying it.
+
+```yaml
+resources:
+  cluster:
+    type: eks:Cluster
+
+  cleanupKubernetesNamespaces:
+    # We could also use `RemoteCommand` to run this from
+    # within a node in the cluster.
+    type: command:local:Command
+    properties:
+      # This will run before the cluster is destroyed.
+      # Everything else will need to depend on this resource
+      # to ensure this cleanup doesn't happen too early.
+      delete: |
+        kubectl --kubeconfig <(echo "$KUBECONFIG_DATA") delete namespace nginx
+      # Process substitution "<()" doesn't work in the default interpreter sh.
+      interpreter: ["/bin/bash", "-c"]
+      environment:
+        KUBECONFIG_DATA: "${cluster.kubeconfigJson}"
+```
 
 ```ts
-import { local } from "@pulumi/command";
+import * as pulumi from "@pulumi/pulumi";
+import * as command from "@pulumi/command";
 import * as eks from "@pulumi/eks";
-import * as random from "@pulumi/random";
-import { interpolate } from "@pulumi/pulumi";
 
 const cluster = new eks.Cluster("cluster", {});
 
 // We could also use `RemoteCommand` to run this from within a node in the cluster
-const cleanupKubernetesNamespaces = new local.Command("cleanupKubernetesNamespaces", {
+const cleanupKubernetesNamespaces = new command.local.Command("cleanupKubernetesNamespaces", {
     // This will run before the cluster is destroyed.  Everything else will need to 
     // depend on this resource to ensure this cleanup doesn't happen too early.
-    delete: "kubectl delete --all namespaces",
+    "delete": "kubectl --kubeconfig <(echo \"$KUBECONFIG_DATA\") delete namespace nginx\n",
+    // Process substitution "<()" doesn't work in the default interpreter sh.
+    interpreter: [
+        "/bin/bash",
+        "-c",
+    ],
     environment: {
-        KUBECONFIG: cluster.kubeconfig,
+        KUBECONFIG_DATA: cluster.kubeconfigJson,
     },
 });
 ```
 
+### Working with Assets and Paths
+
+When a local command creates assets as part of its execution, these can be captured by specifying `assetPaths` or `archivePaths`.
+
+```typescript
+const lambdaBuild = local.runOutput({
+    dir: "../my-function",
+    command: `yarn && yarn build`,
+    archivePaths: ["dist/**"],
+});
+
+new aws.lambda.Function("my-function", {
+    code: lambdaBuild.archive,
+   // ...
+});
+```
+
+When using the `assetPaths` and `archivePaths`, they take a list of 'globs'.
+- We only include files not directories for assets and archives.
+- Path separators are `/` on all platforms - including Windows.
+- Patterns starting with `!` are 'exclude' rules.
+- Rules are evaluated in order, so exclude rules should be after inclusion rules.
+- `*` matches anything except `/`
+- `**` matches anything, _including_ `/`
+- All returned paths are relative to the working directory (without leading `./`) e.g. `file.text` or `subfolder/file.txt`.
+- For full details of the globbing syntax, see [github.com/gobwas/glob](https://github.com/gobwas/glob)
+
+#### Asset Paths Example
+
+Given the rules:
+```yaml
+- "assets/**"
+- "src/**.js"
+- "!**secret.*"
+```
+
+When evaluating against this folder:
+
+```yaml
+- assets/
+  - logos/
+    - logo.svg
+- src/
+  - index.js
+  - secret.js
+```
+
+The following paths will be returned:
+
+```yaml
+- assets/logos/logo.svg
+- src/index.js
+```
+
 ## Building
 
 ### Dependencies
 
-- Go 1.16
+- Go 1.17
 - NodeJS 10.X.X or later
 - Python 3.6 or later
 - .NET Core 3.1
@@ -298,7 +383,7 @@ $ make build
 $ make install
 ```
 
-Add the `bin` folder to your `$PATH` or copy the `bin/pulumi-resource-aws-native` file to another location in your `$PATH`.
+Add the `bin` folder to your `$PATH` or copy the `bin/pulumi-resource-command` file to another location in your `$PATH`.
 
 ### Running an example
 

package/index.d.ts

@@ -1,5 +1,8 @@
-export * from "./provider";
+export { ProviderArgs } from "./provider";
+export type Provider = import("./provider").Provider;
+export declare const Provider: typeof import("./provider").Provider;
 import * as local from "./local";
 import * as remote from "./remote";
 import * as types from "./types";
 export { local, remote, types, };
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,MAAM,MAAM,QAAQ,GAAG,OAAO,YAAY,EAAE,QAAQ,CAAC;AACrD,eAAO,MAAM,QAAQ,EAAE,cAAc,YAAY,EAAE,QAAsB,CAAC;AAK1E,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,OAAO,EACH,KAAK,EACL,MAAM,EACN,KAAK,GACR,CAAC"}

package/index.js

@@ -1,5 +1,5 @@
 "use strict";
-// *** WARNING: this file was generated by pulumigen. ***
+// *** WARNING: this file was generated by pulumi-language-nodejs. ***
 // *** Do not edit by hand unless you're certain you know what you are doing! ***
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -12,30 +12,38 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.types = exports.remote = exports.local = void 0;
-const pulumi = require("@pulumi/pulumi");
-const utilities = require("./utilities");
-// Export members:
-__exportStar(require("./provider"), exports);
+exports.types = exports.remote = exports.local = exports.Provider = void 0;
+const pulumi = __importStar(require("@pulumi/pulumi"));
+const utilities = __importStar(require("./utilities"));
+exports.Provider = null;
+utilities.lazyLoad(exports, ["Provider"], () => require("./provider"));
 // Export sub-modules:
-const local = require("./local");
+const local = __importStar(require("./local"));
 exports.local = local;
-const remote = require("./remote");
+const remote = __importStar(require("./remote"));
 exports.remote = remote;
-const types = require("./types");
+const types = __importStar(require("./types"));
 exports.types = types;
-const provider_1 = require("./provider");
 pulumi.runtime.registerResourcePackage("command", {
     version: utilities.getVersion(),
     constructProvider: (name, type, urn) => {
         if (type !== "pulumi:providers:command") {
             throw new Error(`unknown provider type ${type}`);
         }
-        return new provider_1.Provider(name, undefined, { urn });
+        return new exports.Provider(name, undefined, { urn });
     },
 });
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";AAAA,yDAAyD;AACzD,iFAAiF;;;;;;;;;;;;;;;;;AAEjF,yCAAyC;AACzC,yCAAyC;AAEzC,kBAAkB;AAClB,6CAA2B;AAE3B,sBAAsB;AACtB,iCAAiC;AAK7B,sBAAK;AAJT,mCAAmC;AAK/B,wBAAM;AAJV,iCAAiC;AAK7B,sBAAK;AAGT,yCAAsC;AAEtC,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE;IAC9C,OAAO,EAAE,SAAS,CAAC,UAAU,EAAE;IAC/B,iBAAiB,EAAE,CAAC,IAAY,EAAE,IAAY,EAAE,GAAW,EAA2B,EAAE;QACpF,IAAI,IAAI,KAAK,0BAA0B,EAAE;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;SACpD;QACD,OAAO,IAAI,mBAAQ,CAAC,IAAI,EAAO,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;CACJ,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,iFAAiF;;;;;;;;;;;;;;;;;;;;;;;;;;AAEjF,uDAAyC;AACzC,uDAAyC;AAK5B,QAAA,QAAQ,GAAyC,IAAW,CAAC;AAC1E,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAGvE,sBAAsB;AACtB,+CAAiC;AAK7B,sBAAK;AAJT,iDAAmC;AAK/B,wBAAM;AAJV,+CAAiC;AAK7B,sBAAK;AAET,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE;IAC9C,OAAO,EAAE,SAAS,CAAC,UAAU,EAAE;IAC/B,iBAAiB,EAAE,CAAC,IAAY,EAAE,IAAY,EAAE,GAAW,EAA2B,EAAE;QACpF,IAAI,IAAI,KAAK,0BAA0B,EAAE;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;SACpD;QACD,OAAO,IAAI,gBAAQ,CAAC,IAAI,EAAO,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;CACJ,CAAC,CAAC"}