From f1ee5ec8775aad2fa8007f11aac3926897181098 Mon Sep 17 00:00:00 2001 From: Yacine Fodil <105779815+yfodil@users.noreply.github.com> Date: Thu, 18 Aug 2022 15:58:27 +0200 Subject: [PATCH] docs: update install process, adding example (#58) --- README.md | 17 ++++++++-- docs/README.md | 62 +++++++++++++++------------------- docs/builders/scaleway.mdx | 55 ++++++++++++++++++++---------- example/README.md | 36 +++++++++++--------- example/build.pkr.hcl | 40 ---------------------- example/build_scaleway.pkr.hcl | 23 +++++++++++++ version/version.go | 2 +- 7 files changed, 122 insertions(+), 113 deletions(-) delete mode 100644 example/build.pkr.hcl create mode 100644 example/build_scaleway.pkr.hcl diff --git a/README.md b/README.md index ef42264..e9ffa6e 100644 --- a/README.md +++ b/README.md @@ -12,21 +12,32 @@ 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 . +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 { scaleway = { - version = ">= 1.0.0" - source = "github.com/hashicorp/scaleway" + version = ">= 1.0.5" + source = "github.com/scaleway/scaleway" } } } ``` +#### Using the `packer plugins install` command + +```sh +$ packer plugins install github.com/scaleway/scaleway v1.0.x +``` + +This command will install the most recent compatible Scaleway Packer plugin matching +version constraint. If the version constraint is omitted, the most recent +version of the plugin will be installed. + + #### Manual installation You can find pre-built binary releases of the plugin [here](https://github.com/scaleway/packer-plugin-scaleway/releases). diff --git a/docs/README.md b/docs/README.md index cb92f62..6fe11b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,7 @@ -# Scaffolding Plugins +# Scaleway Plugin - +The [Scaleway](https://www.scaleway.com) Packer plugin provides a builder for building images in +Scaleway. ## Installation @@ -19,23 +13,35 @@ 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 . +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 { - name = { - version = ">= 1.0.0" - source = "github.com/hashicorp/name" + scaleway = { + version = ">= 1.0.5" + source = "github.com/scaleway/scaleway" } } } ``` + +#### Using the `packer plugins install` command + +```sh +$ packer plugins install github.com/scaleway/scaleway v1.0.x +``` + +This command will install the most recent compatible Scaleway Packer plugin matching +version constraint. If the version constraint is omitted, the most recent +version of the plugin will be installed. + + #### Manual installation -You can find pre-built binary releases of the plugin [here](https://github.com/hashicorp/packer-plugin-name/releases). +You can find pre-built binary releases of the plugin [here](https://github.com/scaleway/packer-plugin-scaleway/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 @@ -44,9 +50,9 @@ To install the plugin, please follow the Packer documentation on #### 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-name` plugin +If you prefer to build the plugin from sources, clone the GitHub repository +locally and run the command `go build` from the root +directory. Upon successful compilation, a `packer-plugin-scaleway` 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). @@ -54,25 +60,11 @@ on [installing a plugin](https://www.packer.io/docs/extending/plugins/#installin ## Plugin Contents -The Scaffolding plugin is intended as a starting point for creating Packer plugins, containing: +The Scaleway plugin is intended as a starting point for creating Packer plugins, containing: ### Builders -- [builder](/docs/builders/builder-name.mdx) - The scaffolding builder is used to create endless Packer - plugins using a consistent plugin structure. - -### Provisioners - -- [provisioner](/docs/provisioners/provisioner-name.mdx) - The scaffolding provisioner is used to provisioner - Packer builds. - -### Post-processors - -- [post-processor](/docs/post-processors/postprocessor-name.mdx) - The scaffolding post-processor is used to - export scaffolding builds. - -### Data Sources - -- [data source](/docs/datasources/datasource-name.mdx) - The scaffolding data source is used to - export scaffolding data. +- [builder](/docs/builders/scaleway.mdx) - The Scaleway Packer builder is able to create new images for use with Scaleway BareMetal and Virtual cloud server. +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 Scaleway. diff --git a/docs/builders/scaleway.mdx b/docs/builders/scaleway.mdx index 575dc43..8692324 100644 --- a/docs/builders/scaleway.mdx +++ b/docs/builders/scaleway.mdx @@ -28,6 +28,25 @@ of new servers that are launched within Scaleway. The builder does _not_ manage snapshots. 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 { + scaleway = { + version = ">= 1.0.5" + source = "github.com/scaleway/scaleway" + } + } +} +``` + ## Configuration Reference There are many configuration options available for the builder. They are @@ -55,24 +74,6 @@ Here is a basic example. It is completely valid as soon as you enter your own access tokens: - - -```json -{ - "type": "scaleway", - "project_id": "YOUR PROJECT ID", - "access_key": "YOUR ACCESS KEY", - "secret_key": "YOUR SECRET KEY", - "image": "UUID OF THE BASE IMAGE", - "zone": "fr-par-1", - "commercial_type": "DEV1-S", - "ssh_username": "root", - "ssh_private_key_file": "~/.ssh/id_rsa" -} -``` - - - ```hcl @@ -92,6 +93,24 @@ build { } ``` + + + + + ```json + { + "type": "scaleway", + "project_id": "YOUR PROJECT ID", + "access_key": "YOUR ACCESS KEY", + "secret_key": "YOUR SECRET KEY", + "image": "UUID OF THE BASE IMAGE", + "zone": "fr-par-1", + "commercial_type": "DEV1-S", + "ssh_username": "root", + "ssh_private_key_file": "~/.ssh/id_rsa" + } + ``` + diff --git a/example/README.md b/example/README.md index ced3cc8..dea616e 100644 --- a/example/README.md +++ b/example/README.md @@ -1,20 +1,24 @@ -## The Example Folder +# Example -This folder must contain a fully working example of the plugin usage. The example must define the `required_plugins` -block. A pre-defined GitHub Action will run `packer init`, `packer validate`, and `packer build` to test your plugin -with the latest version available of Packer. +## Simple Packer Build -The folder can contain multiple HCL2 compatible files. The action will execute Packer at this folder level -running `packer init -upgrade .` and `packer build .`. +After cloning this repo, move to the `example` directory by running: -If the plugin requires authentication, the configuration should be provided via GitHub Secrets and set as environment -variables in the [test-plugin-example.yml](/.github/workflows/test-plugin-example.yml) file. Example: +```sh +$ cd packer-plugin-scaleway/example +``` -```yml - - name: Build - working-directory: ${{ github.event.inputs.folder }} - run: PACKER_LOG=${{ github.event.inputs.logs }} packer build . - env: - AUTH_KEY: ${{ secrets.AUTH_KEY }} - AUTH_PASSWORD: ${{ secrets.AUTH_PASSWORD }} -``` \ No newline at end of file +Either modify `basic_scaleway.pkr.hcl` to reflect your Scaleway keys and project id, or comment that out and set the environment variables by running: + +```sh +$ export SCW_DEFAULT_PROJECT_ID= +$ export SCW_ACCESS_KEY= +$ export SCW_SECRET_KEY= +``` + +Then run the following commands to build a simple Scaleway image via Packer: + +```sh +$ packer init basic_scaleway.pkr.hcl +$ packer build basic_scaleway.pkr.hcl +``` diff --git a/example/build.pkr.hcl b/example/build.pkr.hcl deleted file mode 100644 index 76d6a28..0000000 --- a/example/build.pkr.hcl +++ /dev/null @@ -1,40 +0,0 @@ -packer { - required_plugins { - scaffolding = { - version = ">=v0.1.0" - source = "github.com/hashicorp/scaffolding" - } - } -} - -source "scaffolding-my-builder" "foo-example" { - mock = local.foo -} - -source "scaffolding-my-builder" "bar-example" { - mock = local.bar -} - -build { - sources = [ - "source.scaffolding-my-builder.foo-example", - ] - - source "source.scaffolding-my-builder.bar-example" { - name = "bar" - } - - provisioner "scaffolding-my-provisioner" { - only = ["scaffolding-my-builder.foo-example"] - mock = "foo: ${local.foo}" - } - - provisioner "scaffolding-my-provisioner" { - only = ["scaffolding-my-builder.bar"] - mock = "bar: ${local.bar}" - } - - post-processor "scaffolding-my-post-processor" { - mock = "post-processor mock-config" - } -} diff --git a/example/build_scaleway.pkr.hcl b/example/build_scaleway.pkr.hcl new file mode 100644 index 0000000..61a452f --- /dev/null +++ b/example/build_scaleway.pkr.hcl @@ -0,0 +1,23 @@ +packer { + required_plugins { + scaleway = { + version = ">= 1.0.5" + source = "github.com/scaleway/scaleway" + } + } +} + +source "scaleway" "basic" { + project_id = "YOUR PROJECT ID" + access_key = "YOUR ACCESS KEY" + secret_key = "YOUR SECRET KEY" + commercial_type = "DEV1-S" + image = "ubuntu_focal" + image_name = "basic build" + ssh_username = "root" + zone = "fr-par-1" +} + +build { + sources = ["source.scaleway.basic"] +} diff --git a/version/version.go b/version/version.go index a9cf652..9ee8fb3 100644 --- a/version/version.go +++ b/version/version.go @@ -4,7 +4,7 @@ import "github.com/hashicorp/packer-plugin-sdk/version" var ( // Version is the main version number that is being run at the moment. - Version = "1.0.2" + Version = "1.0.6" // VersionPrerelease is A pre-release marker for the Version. If this is "" // (empty string) then it means that it is a final release. Otherwise, this