Merge pull request #9 from BrandonRomano/main

Register plug-in as Packer integration

.github/workflows/ensure-docs-compiled.yaml

@@ -0,0 +1,22 @@
+name: Ensure Docs are Compiled
+on:
+  push:
+jobs:
+  ensure-docs-compiled:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v2
+      - uses: actions/setup-go@v4
+      - shell: bash
+        run: make generate
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make generate', and commit the result to resolve this error."
+            exit 1
+          fi
+

.github/workflows/notify-integration-release-via-manual.yaml

@@ -0,0 +1,50 @@
+# Manual release workflow is used for deploying documentation updates
+# on the specified branch without making an official plugin release. 
+name: Notify Integration Release (Manual)
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "The release version (semver)"
+        default: 1.0.0
+        required: false
+      branch:
+        description: "A branch or SHA"
+        default: 'main'
+        required: false
+jobs:
+  notify-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          ref: ${{ github.event.inputs.branch }}
+      # Ensure that Docs are Compiled
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+      - shell: bash
+        run: make generate
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make generate', and commit the result to resolve this error."
+            exit 1
+          fi
+      # Perform the Release
+      - name: Checkout integration-release-action
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          repository: hashicorp/integration-release-action
+          path: ./integration-release-action
+      - name: Notify Release
+        uses: ./integration-release-action
+        with:
+          # The integration identifier will be used by the Packer team to register the integration
+          # the expected format is packer/<GitHub Org Name>/<plugin-name>
+          integration_identifier: "packer/joomcode/external"
+          release_version: ${{ github.event.inputs.version }}
+          release_sha: ${{ github.event.inputs.branch }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/notify-integration-release-via-tag.yaml

@@ -0,0 +1,54 @@
+name: Notify Integration Release (Tag)
+on:
+  push:
+    tags:
+      - '*.*.*'   # Proper releases
+jobs:
+  strip-version:
+    runs-on: ubuntu-latest
+    outputs:
+      packer-version: ${{ steps.strip.outputs.packer-version }}
+    steps:
+      - name: Strip leading v from version tag
+        id: strip
+        env:
+          REF: ${{ github.ref_name }}
+        run: |
+          echo "packer-version=$(echo "$REF" | sed -E 's/v?([0-9]+\.[0-9]+\.[0-9]+)/\1/')" >> "$GITHUB_OUTPUT"
+  notify-release:
+    needs:
+      - strip-version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          ref: ${{ github.ref }}
+      # Ensure that Docs are Compiled
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+      - shell: bash
+        run: make generate
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make generate', and commit the result to resolve this error."
+            exit 1
+          fi
+      # Perform the Release
+      - name: Checkout integration-release-action
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          repository: hashicorp/integration-release-action
+          path: ./integration-release-action
+      - name: Notify Release
+        uses: ./integration-release-action
+        with:
+          # The integration identifier will be used by the Packer team to register the integration
+          # the expected format is packer/<GitHub Org Name>/<plugin-name>
+          integration_identifier: "packer/joomcode/external"
+          release_version: ${{ needs.strip-version.outputs.packer-version }}
+          release_sha: ${{ github.ref }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.web-docs/README.md

@@ -0,0 +1,31 @@
+The External plugin is able to communicate with external commands.
+
+### Installation
+
+To install this plugin, copy and paste this code into your Packer configuration, then run [`packer init`](https://www.packer.io/docs/commands/init).
+
+```hcl
+packer {
+  required_plugins {
+    external = {
+      version = "> 0.0.2"
+      source  = "github.com/joomcode/external"
+    }
+  }
+}
+```
+
+Alternatively, you can use `packer plugins install` to manage installation of this plugin.
+
+```sh
+$ packer plugins install github.com/joomcode/external
+```
+
+### Components
+
+#### Data Sources
+- [external](/packer/integrations/joomcode/external/latest/components/data-source/external) - Communicate with external commands
+  using JSON protocol.
+- [external-raw](/packer/integrations/joomcode/external/latest/components/data-source/raw) - Communicate with external commands
+  using plaintext protocol.
+

.web-docs/components/data-source/external/README.md

@@ -0,0 +1,113 @@
+Type: `external`
+
+The `external` data source allows an external program implementing a specific
+protocol (defined below) to act as a data source, exposing arbitrary
+data for use elsewhere in the Packer configuration.
+
+~> **Warning** This mechanism is provided as an "escape hatch" for exceptional
+situations where a first-class Packer provider is not more appropriate.
+Its capabilities are limited in comparison to a true data source, and
+implementing a data source via an external program is likely to hurt the
+portability of your Packer configuration by creating dependencies on
+external programs and libraries that may not be available (or may need to
+be used differently) on different operating systems.
+
+## Example Usage
+```hcl
+data "external" "example" {
+  program = ["jq", "{ \"foo\": .key1 }"]
+  query = {
+    key1 = "val1"
+  }
+}
+
+locals {
+  result = data.external.example.result
+}
+
+source "null" "example" {
+  communicator = "none"
+}
+
+build {
+  sources = ["source.null.example"]
+
+  provisioner "shell-local" {
+    inline = [
+      "echo ${local.result["foo"]} == val1",
+    ]
+  }
+}
+```
+
+## External Program Protocol
+
+The external program described by the `program` attribute must implement a
+specific protocol for interacting with Packer, as follows.
+
+The program must read all the data passed to it on `stdin`, and parse
+it as a JSON object. The JSON object contains the contents of the `query`
+argument and its values will always be strings.
+
+The program must then produce a valid JSON object on `stdout`, which will
+be used to populate the `result` attribute exported to the rest of the
+Packer configuration. This JSON object must again have all of its
+values as strings. On successful completion it must exit with status zero.
+
+If the program encounters an error and is unable to produce a result, it
+must print a human-readable error message (ideally a single line) to `stderr`
+and exit with a non-zero status. Any data on `stdout` is ignored if the
+program returns a non-zero status.
+
+All environment variables visible to the Packer process are passed through
+to the child program.
+
+## Argument Reference
+
+### Required
+
+- `command` ([]string) - A list of strings, whose first element is the program
+  to run and whose subsequent elements are optional command line arguments
+  to the program. Packer does not execute the program through a shell, so
+  it is not necessary to escape shell metacharacters nor add quotes around
+  arguments containing spaces.
+
+### Optional
+
+- `working_dir` (string) - Working directory of the program.
+  If not supplied, the program will run in the current directory.
+- `query` (map[string]string) - A map of string values to pass to the external program
+  as the query arguments. If not supplied, the program will receive an empty
+  object as its input.
+
+### Output
+
+- `result` (map[string]string) - A map of string values returned from the external program.
+
+
+## Processing JSON in shell scripts
+
+Since the external data source protocol uses JSON, it is recommended to use
+the utility [`jq`](https://stedolan.github.io/jq/) to translate to and from
+JSON in a robust way when implementing a data source in a shell scripting
+language.
+
+The following example shows some input/output boilerplate code for a
+data source implemented in bash:
+
+```bash
+#!/bin/bash
+# Exit if any of the intermediate steps fail
+set -e
+# Extract "foo" and "baz" arguments from the input into
+# FOO and BAZ shell variables.
+# jq will ensure that the values are properly quoted
+# and escaped for consumption by the shell.
+eval "$(jq -r '@sh "FOO=\(.foo) BAZ=\(.baz)"')"
+# Placeholder for whatever data-fetching logic your script implements
+FOOBAZ="$FOO $BAZ"
+# Safely produce a JSON object containing the result value.
+# jq will ensure that the value is properly quoted
+# and escaped to produce a valid JSON string.
+jq -n --arg foobaz "$FOOBAZ" '{"foobaz":$foobaz}'
+```

.web-docs/components/data-source/raw/README.md

@@ -0,0 +1,70 @@
+Type: `external-raw`
+
+The `external-raw` data source allows an external program to act as a data source,
+exposing arbitrary data for use elsewhere in the Packer configuration.
+
+~> **Warning** This mechanism is provided as an "escape hatch" for exceptional
+situations where a first-class Packer provider is not more appropriate.
+Its capabilities are limited in comparison to a true data source, and
+implementing a data source via an external program is likely to hurt the
+portability of your Packer configuration by creating dependencies on
+external programs and libraries that may not be available (or may need to
+be used differently) on different operating systems.
+
+## Example Usage
+```hcl
+data "external-raw" "example" {
+  program = ["rev"]
+  query = "hello"
+}
+
+locals {
+  result = data.external-raw.example.result
+}
+
+source "null" "example" {
+  communicator = "none"
+}
+
+build {
+  sources = ["source.null.example"]
+
+  provisioner "shell-local" {
+    inline = [
+      "echo ${trimspace(local.result)} == olleh",
+    ]
+  }
+}
+```
+
+## External Program Protocol
+
+The protocol is similar to the one used by the
+[external](/packer/integrations/joomcode/external/latest/components/data-source/external) data source.
+However, query and result are plaintext strings instead of JSON objects.
+Refer to the [external](/packer/integrations/joomcode/external/latest/components/data-source/external) doc
+for more details.
+
+`external-raw` should be used over `external` in cases where the external program
+does not support JSON input and/or output.
+
+## Argument Reference
+
+### Required
+
+- `command` ([]string) - A list of strings, whose first element is the program
+  to run and whose subsequent elements are optional command line arguments
+  to the program. Packer does not execute the program through a shell, so
+  it is not necessary to escape shell metacharacters nor add quotes around
+  arguments containing spaces.
+
+### Optional
+
+- `working_dir` (string) - Working directory of the program.
+  If not supplied, the program will run in the current directory.
+- `query` (string) - An input to pass to the external program.
+  If not supplied, the program will not receive anything on standard input.
+
+### Output
+
+- `result` (string) - The output returned from the external program.

.web-docs/metadata.hcl

@@ -0,0 +1,17 @@
+# For full specification on the configuration of this file visit:
+# https://github.com/hashicorp/integration-template#metadata-configuration
+integration {
+  name = "External"
+  description = "The External plugin is able to communicate with external commands."
+  identifier = "packer/joomcode/external"
+  component {
+    type = "data-source"
+    name = "External Raw"
+    slug = "raw"
+  }
+  component {
+    type = "data-source"
+    name = "External"
+    slug = "external"
+  }
+}