From f9b5a7cad1ea032c85b234b7d1dcd735aeee1c2f Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Tue, 21 Nov 2023 20:19:45 +0000 Subject: [PATCH] Update README for integration framework --- ...notify-integration-release-via-manual.yaml | 18 ++-- .../notify-integration-release-via-tag.yaml | 30 ++++-- .web-docs/README.md | 47 +++------ .../components/builder/digitalocean/README.md | 51 ++++++---- .../data-source/digitalocen-image/README.md | 7 ++ .../digitalocean-import/README.md | 99 ++++++++----------- docs/README.md | 47 +++------ docs/builders/digitalocean.mdx | 19 ---- docs/post-processors/digitalocean-import.mdx | 19 ---- 9 files changed, 137 insertions(+), 200 deletions(-) diff --git a/.github/workflows/notify-integration-release-via-manual.yaml b/.github/workflows/notify-integration-release-via-manual.yaml index 7126bfc..d2c0ff0 100644 --- a/.github/workflows/notify-integration-release-via-manual.yaml +++ b/.github/workflows/notify-integration-release-via-manual.yaml @@ -1,10 +1,12 @@ +# 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: 0.0.1 + default: 1.0.0 required: false branch: description: "A branch or SHA" @@ -15,32 +17,34 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout this repo - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 with: ref: ${{ github.event.inputs.branch }} # Ensure that Docs are Compiled - - uses: actions/setup-go@v4 + - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0 - shell: bash - run: make build-docs + 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 build-docs', and commit the result to resolve this error." + 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@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + 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: - integration_identifier: 'packer/BrandonRomano/digitalocean' + # The integration identifier will be used by the Packer team to register the integration + # the expected format is packer// + integration_identifier: "packer/hashicorp/scaffolding" release_version: ${{ github.event.inputs.version }} release_sha: ${{ github.event.inputs.branch }} github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/notify-integration-release-via-tag.yaml b/.github/workflows/notify-integration-release-via-tag.yaml index 4ac5df4..7318c02 100644 --- a/.github/workflows/notify-integration-release-via-tag.yaml +++ b/.github/workflows/notify-integration-release-via-tag.yaml @@ -3,38 +3,52 @@ on: push: tags: - '*.*.*' # Proper releases - - '*.*.*-*' # Pre 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@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 with: ref: ${{ github.ref }} # Ensure that Docs are Compiled - - uses: actions/setup-go@v4 + - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0 - shell: bash - run: make build-docs + 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 build-docs', and commit the result to resolve this error." + 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@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + 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: - integration_identifier: 'packer/BrandonRomano/digitalocean' - release_version: ${{ github.ref_name }} + # The integration identifier will be used by the Packer team to register the integration + # the expected format is packer// + integration_identifier: "packer/hashicorp/scaffolding" + release_version: ${{ needs.strip-version.outputs.packer-version }} release_sha: ${{ github.ref }} github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.web-docs/README.md b/.web-docs/README.md index e1a7290..af9de93 100644 --- a/.web-docs/README.md +++ b/.web-docs/README.md @@ -1,21 +1,11 @@ -# DigitalOcean Plugins - The [DigitalOcean](https://www.digitalocean.com/) Packer plugin provides a builder for building images in DigitalOcean, and a post-processor for importing already-existing images into DigitalOcean. -## Installation - -### Using pre-built releases -#### Using the `packer init` command +### Installation -Starting from version 1.7, Packer supports a new `packer init` command allowing -automatic installation of Packer plugins. Read the -[Packer documentation](https://www.packer.io/docs/commands/init) for more information. - -To install this plugin, copy and paste this code into your Packer configuration . -Then, run [`packer init`](https://www.packer.io/docs/commands/init). +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 { @@ -28,33 +18,22 @@ packer { } ``` -#### Manual installation - -You can find pre-built binary releases of the plugin [here](https://github.com/digitalocean/packer-plugin-digitalocean/releases). -Once you have downloaded the latest archive corresponding to your target OS, -uncompress it to retrieve the plugin binary file corresponding to your platform. -To install the plugin, please follow the Packer documentation on -[installing a plugin](https://www.packer.io/docs/extending/plugins/#installing-plugins). +Alternatively, you can use `packer plugins install` to manage installation of this plugin. +```sh +$ packer plugins install github.com/digitalocean/digitalocean +``` -#### From Source - -If you prefer to build the plugin from its source code, clone the GitHub -repository locally and run the command `go build` from the root -directory. Upon successful compilation, a `packer-plugin-digitalocean` plugin -binary file can be found in the root directory. -To install the compiled plugin, please follow the official Packer documentation -on [installing a plugin](https://www.packer.io/docs/extending/plugins/#installing-plugins). - +### Components -## Plugin Contents +#### Builders -The DigitalOcean plugin is intended as a starting point for creating Packer plugins, containing: +- [digitalocean](/packer/integrations/digitalocean/latest/components/builder/digitalocean) - The builder takes a source image, runs any provisioning necessary on the image after launching it, then snapshots it into a reusable image. This reusable image can then be used as the foundation of new servers that are launched within DigitalOcean. -### Builders +#### Data Sources -- [builder](/docs/builders/digitalocean.mdx) - The builder takes a source image, runs any provisioning necessary on the image after launching it, then snapshots it into a reusable image. This reusable image can then be used as the foundation of new servers that are launched within DigitalOcean. +- [digitalocean-image](/packer/integrations/digitalocean/latest/components/datasource/image) - The DigitalOcean image data source is used look up the ID of an existing DigitalOcean image for use as a builder source. -### Post-processors +#### Post-processors -- [post-processor](/docs/post-processors/digitalocean-import.mdx) - The digitalocean-import post-processor is used to import images to DigitalOcean +- [digitalocean-import](/packer/integrations/digitalocean/latest/components/post-processor/import) -processor](/docs/post-processors/digitalocean-import.mdx) - The digitalocean-import post-processor is used to import images to DigitalOcean diff --git a/.web-docs/components/builder/digitalocean/README.md b/.web-docs/components/builder/digitalocean/README.md index 8d2d186..0039c87 100644 --- a/.web-docs/components/builder/digitalocean/README.md +++ b/.web-docs/components/builder/digitalocean/README.md @@ -10,25 +10,6 @@ foundation of new servers that are launched within DigitalOcean. The builder does _not_ manage images. Once it creates an image, it is up to you to use it or delete it. -## Installation - -To install this plugin using Packer v1.7.0 or later, copy and paste this code -into your Packer configuration. - -Then, run [`packer init`](https://www.packer.io/docs/commands/init). - - -```hcl -packer { - required_plugins { - digitalocean = { - version = ">= 1.0.4" - source = "github.com/digitalocean/digitalocean" - } - } -} -``` - ## Configuration Reference There are many configuration options available for the builder. They are @@ -69,6 +50,13 @@ each category, the available configuration keys are alphabetized. using a DigitalOcean API compatible service. It can also be specified via environment variable DIGITALOCEAN_API_URL. +- `http_retry_max` (\*int) - The maximum number of retries for requests that fail with a 429 or 500-level error. + The default value is 5. Set to 0 to disable reties. + +- `http_retry_wait_max` (\*float64) - The maximum wait time (in seconds) between failed API requests. Default: 30.0 + +- `http_retry_wait_min` (\*float64) - The minimum wait time (in seconds) between failed API requests. Default: 1.0 + - `private_networking` (bool) - Set to true to enable private networking for the droplet being created. This defaults to false, or not enabled. @@ -201,6 +189,31 @@ In addition to the builder options, a + + +- `temporary_key_pair_type` (string) - `dsa` | `ecdsa` | `ed25519` | `rsa` ( the default ) + + Specifies the type of key to create. The possible values are 'dsa', + 'ecdsa', 'ed25519', or 'rsa'. + + NOTE: DSA is deprecated and no longer recognized as secure, please + consider other alternatives like RSA or ED25519. + +- `temporary_key_pair_bits` (int) - Specifies the number of bits in the key to create. For RSA keys, the + minimum size is 1024 bits and the default is 4096 bits. Generally, 3072 + bits is considered sufficient. DSA keys must be exactly 1024 bits as + specified by FIPS 186-2. For ECDSA keys, bits determines the key length + by selecting from one of three elliptic curve sizes: 256, 384 or 521 + bits. Attempting to use bit lengths other than these three values for + ECDSA keys will fail. Ed25519 keys have a fixed length and bits will be + ignored. + + NOTE: DSA is deprecated and no longer recognized as secure as specified + by FIPS 186-5, please consider other alternatives like RSA or ED25519. + + + + - `ssh_host` (string) - The address to SSH to. This usually is automatically configured by the diff --git a/.web-docs/components/data-source/digitalocen-image/README.md b/.web-docs/components/data-source/digitalocen-image/README.md index ca65e57..23939ed 100644 --- a/.web-docs/components/data-source/digitalocen-image/README.md +++ b/.web-docs/components/data-source/digitalocen-image/README.md @@ -20,6 +20,13 @@ for use as a builder source. - `api_url` (string) - A non-standard API endpoint URL. Set this if you are using a DigitalOcean API compatible service. It can also be specified via environment variable DIGITALOCEAN_API_URL. +- `http_retry_max` (\*int) - The maximum number of retries for requests that fail with a 429 or 500-level error. + The default value is 5. Set to 0 to disable reties. + +- `http_retry_wait_max` (\*float64) - The maximum wait time (in seconds) between failed API requests. Default: 30.0 + +- `http_retry_wait_min` (\*float64) - The minimum wait time (in seconds) between failed API requests. Default: 1.0 + - `name` (string) - The name of the image to return. Only one of `name` or `name_regex` may be provided. - `name_regex` (string) - A regex matching the name of the image to return. Only one of `name` or `name_regex` may be provided. diff --git a/.web-docs/components/post-processor/digitalocean-import/README.md b/.web-docs/components/post-processor/digitalocean-import/README.md index 184dc44..3aed683 100644 --- a/.web-docs/components/post-processor/digitalocean-import/README.md +++ b/.web-docs/components/post-processor/digitalocean-import/README.md @@ -16,88 +16,67 @@ import is complete. For information about the requirements to use an image for a DigitalOcean Droplet, see DigitalOcean's [Custom Images documentation](https://www.digitalocean.com/docs/images/custom-images). -### Installation +## Configuration -To install this plugin using Packer v1.7.0 or later, copy and paste this code -into your Packer configuration. +There are some configuration options available for the post-processor. -Then, run [`packer init`](https://www.packer.io/docs/commands/init). +Required: + -```hcl -packer { - required_plugins { - digitalocean = { - version = ">= 1.0.4" - source = "github.com/digitalocean/digitalocean" - } - } -} -``` +- `api_token` (string) - A personal access token used to communicate with the DigitalOcean v2 API. + This may also be set using the `DIGITALOCEAN_TOKEN` or + `DIGITALOCEAN_ACCESS_TOKEN` environmental variables. -## Configuration +- `spaces_key` (string) - The access key used to communicate with Spaces. This may also be set using + the `DIGITALOCEAN_SPACES_ACCESS_KEY` environmental variable. -There are some configuration options available for the post-processor. +- `spaces_secret` (string) - The secret key used to communicate with Spaces. This may also be set using + the `DIGITALOCEAN_SPACES_SECRET_KEY` environmental variable. -Required: +- `spaces_region` (string) - The name of the region, such as `nyc3`, in which to upload the image to Spaces. -- `api_token` (string) - A personal access token used to communicate with - the DigitalOcean v2 API. This may also be set using the - `DIGITALOCEAN_TOKEN` or `DIGITALOCEAN_ACCESS_TOKEN` environmental variables. - `DIGITALOCEAN_API_TOKEN` is acceptable but will be deprecated in a future release. +- `space_name` (string) - The name of the specific Space where the image file will be copied to for + import. This Space must exist when the post-processor is run. -- `spaces_key` (string) - The access key used to communicate with Spaces. - This may also be set using the `DIGITALOCEAN_SPACES_ACCESS_KEY` - environmental variable. +- `image_name` (string) - The name to be used for the resulting DigitalOcean custom image. -- `spaces_secret` (string) - The secret key used to communicate with Spaces. - This may also be set using the `DIGITALOCEAN_SPACES_SECRET_KEY` - environmental variable. +- `image_regions` ([]string) - A list of DigitalOcean regions, such as `nyc3`, where the resulting image + will be available for use in creating Droplets. -- `spaces_region` (string) - The name of the region, such as `nyc3`, in which - to upload the image to Spaces. + -- `space_name` (string) - The name of the specific Space where the image file - will be copied to for import. This Space must exist when the - post-processor is run. -- `image_name` (string) - The name to be used for the resulting DigitalOcean - custom image. +Optional: -- `image_regions` (array of string) - A list of DigitalOcean regions, such - as `nyc3`, where the resulting image will be available for use in creating - Droplets. + -Optional: +- `api_token` (string) - A personal access token used to communicate with the DigitalOcean v2 API. + This may also be set using the `DIGITALOCEAN_TOKEN` or + `DIGITALOCEAN_ACCESS_TOKEN` environmental variables. + +- `spaces_key` (string) - The access key used to communicate with Spaces. This may also be set using + the `DIGITALOCEAN_SPACES_ACCESS_KEY` environmental variable. + +- `spaces_secret` (string) - The secret key used to communicate with Spaces. This may also be set using + the `DIGITALOCEAN_SPACES_SECRET_KEY` environmental variable. -- `image_description` (string) - The description to set for the resulting - imported image. +- `spaces_region` (string) - The name of the region, such as `nyc3`, in which to upload the image to Spaces. -- `image_distribution` (string) - The name of the distribution to set for - the resulting imported image. +- `space_name` (string) - The name of the specific Space where the image file will be copied to for + import. This Space must exist when the post-processor is run. + +- `image_name` (string) - The name to be used for the resulting DigitalOcean custom image. + +- `image_regions` ([]string) - A list of DigitalOcean regions, such as `nyc3`, where the resulting image + will be available for use in creating Droplets. + + -- `image_tags` (array of strings) - A list of tags to apply to the resulting - imported image. - `keep_input_artifact` (boolean) - if true, do not delete the source virtual machine image after importing it to the cloud. Defaults to false. -- `skip_clean` (boolean) - Whether we should skip removing the image file - uploaded to Spaces after the import process has completed. "true" means - that we should leave it in the Space, "false" means to clean it out. - Defaults to `false`. - -- `space_object_name` (string) - The name of the key used in the Space where - the image file will be copied to for import. This is treated as a - [template engine](/docs/templates/legacy_json_templates/engine). Therefore, you - may use user variables and template functions in this field. - If not specified, this will default to `packer-import-{{timestamp}}`. - -- `timeout` (number) - The length of time in minutes to wait for individual - steps in the process to successfully complete. This includes both importing - the image from Spaces as well as distributing the resulting image to - additional regions. If not specified, this will default to 20. - ## Basic Example Here is a basic example: diff --git a/docs/README.md b/docs/README.md index e1a7290..af9de93 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,21 +1,11 @@ -# DigitalOcean Plugins - The [DigitalOcean](https://www.digitalocean.com/) Packer plugin provides a builder for building images in DigitalOcean, and a post-processor for importing already-existing images into DigitalOcean. -## Installation - -### Using pre-built releases -#### Using the `packer init` command +### Installation -Starting from version 1.7, Packer supports a new `packer init` command allowing -automatic installation of Packer plugins. Read the -[Packer documentation](https://www.packer.io/docs/commands/init) for more information. - -To install this plugin, copy and paste this code into your Packer configuration . -Then, run [`packer init`](https://www.packer.io/docs/commands/init). +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 { @@ -28,33 +18,22 @@ packer { } ``` -#### Manual installation - -You can find pre-built binary releases of the plugin [here](https://github.com/digitalocean/packer-plugin-digitalocean/releases). -Once you have downloaded the latest archive corresponding to your target OS, -uncompress it to retrieve the plugin binary file corresponding to your platform. -To install the plugin, please follow the Packer documentation on -[installing a plugin](https://www.packer.io/docs/extending/plugins/#installing-plugins). +Alternatively, you can use `packer plugins install` to manage installation of this plugin. +```sh +$ packer plugins install github.com/digitalocean/digitalocean +``` -#### From Source - -If you prefer to build the plugin from its source code, clone the GitHub -repository locally and run the command `go build` from the root -directory. Upon successful compilation, a `packer-plugin-digitalocean` plugin -binary file can be found in the root directory. -To install the compiled plugin, please follow the official Packer documentation -on [installing a plugin](https://www.packer.io/docs/extending/plugins/#installing-plugins). - +### Components -## Plugin Contents +#### Builders -The DigitalOcean plugin is intended as a starting point for creating Packer plugins, containing: +- [digitalocean](/packer/integrations/digitalocean/latest/components/builder/digitalocean) - The builder takes a source image, runs any provisioning necessary on the image after launching it, then snapshots it into a reusable image. This reusable image can then be used as the foundation of new servers that are launched within DigitalOcean. -### Builders +#### Data Sources -- [builder](/docs/builders/digitalocean.mdx) - The builder takes a source image, runs any provisioning necessary on the image after launching it, then snapshots it into a reusable image. This reusable image can then be used as the foundation of new servers that are launched within DigitalOcean. +- [digitalocean-image](/packer/integrations/digitalocean/latest/components/datasource/image) - The DigitalOcean image data source is used look up the ID of an existing DigitalOcean image for use as a builder source. -### Post-processors +#### Post-processors -- [post-processor](/docs/post-processors/digitalocean-import.mdx) - The digitalocean-import post-processor is used to import images to DigitalOcean +- [digitalocean-import](/packer/integrations/digitalocean/latest/components/post-processor/import) -processor](/docs/post-processors/digitalocean-import.mdx) - The digitalocean-import post-processor is used to import images to DigitalOcean diff --git a/docs/builders/digitalocean.mdx b/docs/builders/digitalocean.mdx index 20e08e2..7693f89 100644 --- a/docs/builders/digitalocean.mdx +++ b/docs/builders/digitalocean.mdx @@ -27,25 +27,6 @@ foundation of new servers that are launched within DigitalOcean. The builder does _not_ manage images. Once it creates an image, it is up to you to use it or delete it. -## Installation - -To install this plugin using Packer v1.7.0 or later, copy and paste this code -into your Packer configuration. - -Then, run [`packer init`](https://www.packer.io/docs/commands/init). - - -```hcl -packer { - required_plugins { - digitalocean = { - version = ">= 1.0.4" - source = "github.com/digitalocean/digitalocean" - } - } -} -``` - ## Configuration Reference There are many configuration options available for the builder. They are diff --git a/docs/post-processors/digitalocean-import.mdx b/docs/post-processors/digitalocean-import.mdx index ef67267..c6aba06 100644 --- a/docs/post-processors/digitalocean-import.mdx +++ b/docs/post-processors/digitalocean-import.mdx @@ -25,25 +25,6 @@ import is complete. For information about the requirements to use an image for a DigitalOcean Droplet, see DigitalOcean's [Custom Images documentation](https://www.digitalocean.com/docs/images/custom-images). -### Installation - -To install this plugin using Packer v1.7.0 or later, copy and paste this code -into your Packer configuration. - -Then, run [`packer init`](https://www.packer.io/docs/commands/init). - - -```hcl -packer { - required_plugins { - digitalocean = { - version = ">= 1.0.4" - source = "github.com/digitalocean/digitalocean" - } - } -} -``` - ## Configuration There are some configuration options available for the post-processor.