From de292e2134cba36fcc1c61723b994528e6f605d2 Mon Sep 17 00:00:00 2001 From: BrandonRomano Date: Thu, 15 Jun 2023 11:02:30 -0700 Subject: [PATCH] docs: Upgrade plugin to integrations framework --- .github/workflows/ensure-docs-compiled.yaml | 22 ++ ...notify-integration-release-via-manual.yaml | 46 +++ .../notify-integration-release-via-tag.yaml | 40 +++ .web-docs/README.md | 33 ++ .web-docs/components/builder/uhost/README.md | 331 ++++++++++++++++++ .../post-processor/import/README.md | 108 ++++++ .web-docs/metadata.hcl | 17 + .web-docs/scripts/compile-to-webdocs.sh | 129 +++++++ GNUmakefile | 6 + docs/README.md | 70 ++-- docs/builders/uhost.mdx | 16 +- 11 files changed, 757 insertions(+), 61 deletions(-) create mode 100644 .github/workflows/ensure-docs-compiled.yaml create mode 100644 .github/workflows/notify-integration-release-via-manual.yaml create mode 100644 .github/workflows/notify-integration-release-via-tag.yaml create mode 100644 .web-docs/README.md create mode 100644 .web-docs/components/builder/uhost/README.md create mode 100644 .web-docs/components/post-processor/import/README.md create mode 100644 .web-docs/metadata.hcl create mode 100755 .web-docs/scripts/compile-to-webdocs.sh diff --git a/.github/workflows/ensure-docs-compiled.yaml b/.github/workflows/ensure-docs-compiled.yaml new file mode 100644 index 0000000..74a174d --- /dev/null +++ b/.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@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 + - uses: actions/setup-go@fac708d6674e30b6ba41289acaab6d4b75aa0753 # v4.0.1 + - shell: bash + run: make build-docs + - 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." + exit 1 + fi + diff --git a/.github/workflows/notify-integration-release-via-manual.yaml b/.github/workflows/notify-integration-release-via-manual.yaml new file mode 100644 index 0000000..1013921 --- /dev/null +++ b/.github/workflows/notify-integration-release-via-manual.yaml @@ -0,0 +1,46 @@ +name: Notify Integration Release (Manual) +on: + workflow_dispatch: + inputs: + version: + description: "The release version (semver)" + default: 0.0.1 + 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@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + with: + ref: ${{ github.event.inputs.branch }} + # Ensure that Docs are Compiled + - uses: actions/setup-go@v4 + - shell: bash + run: make build-docs + - 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." + exit 1 + fi + # Perform the Release + - name: Checkout integration-release-action + uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + with: + repository: hashicorp/integration-release-action + path: ./integration-release-action + - name: Notify Release + uses: ./integration-release-action + with: + integration_identifier: 'packer/hashicorp/ucloud' + 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 new file mode 100644 index 0000000..68e684f --- /dev/null +++ b/.github/workflows/notify-integration-release-via-tag.yaml @@ -0,0 +1,40 @@ +name: Notify Integration Release (Tag) +on: + push: + tags: + - '*.*.*' # Proper releases + - '*.*.*-*' # Pre releases +jobs: + notify-release: + runs-on: ubuntu-latest + steps: + - name: Checkout this repo + uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + with: + ref: ${{ github.ref }} + # Ensure that Docs are Compiled + - uses: actions/setup-go@v4 + - shell: bash + run: make build-docs + - 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." + exit 1 + fi + # Perform the Release + - name: Checkout integration-release-action + uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + with: + repository: hashicorp/integration-release-action + path: ./integration-release-action + - name: Notify Release + uses: ./integration-release-action + with: + integration_identifier: 'packer/hashicorp/ucloud' + release_version: ${{ github.ref_name }} + release_sha: ${{ github.ref }} + github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.web-docs/README.md b/.web-docs/README.md new file mode 100644 index 0000000..05517fb --- /dev/null +++ b/.web-docs/README.md @@ -0,0 +1,33 @@ +The UCloud plugin is able to build customized images based on an existing base image for use in UHost Instance. + +### Installation +To install this plugin add this code into your Packer configuration and run [packer init](/packer/docs/commands/init) + +```hcl +packer { + required_plugins { + ucloud = { + version = "~> 1" + source = "github.com/hashicorp/ucloud" + } + } +} +``` + +Alternatively, you can use `packer plugins install` to manage installation of this plugin. + +```sh +packer plugins install github.com/hashicorp/ucloud +``` +### Components + +#### Builders + +- [ucloud-uhost](/packer/integrations/hashicorp/ucloud/latest/components/builder/uhost) - The `ucloud-uhost` builder provides the capability to build + customized images based on an existing base image for use in UHost Instance. + +#### Post-processors + +- [ucloud-import](/packer/integrations/hashicorp/uhost/latest/components/post-processor/import) - The UCloud Import post-processor takes the RAW, VHD, VMDK, or qcow2 + artifact from various builders and imports it to UCloud customized image list + for UHost Instance. diff --git a/.web-docs/components/builder/uhost/README.md b/.web-docs/components/builder/uhost/README.md new file mode 100644 index 0000000..0eddc68 --- /dev/null +++ b/.web-docs/components/builder/uhost/README.md @@ -0,0 +1,331 @@ +Type: `ucloud-uhost` +Artifact BuilderId: `ucloud.uhost` + +The `ucloud-uhost` Packer builder plugin provides the capability to build +customized images based on an existing base image for use in UHost Instance. + +This builder builds an UCloud image by launching an UHost instance from a source image, +provisioning that running machine, and then creating an image from that machine. + +## Configuration Reference + +The following configuration options are available for building UCloud images. They are +segmented below into two categories: required and optional parameters. + +In addition to the options listed here, a +[communicator](/packer/docs/templates/legacy_json_templates/communicator) can be configured for this +builder. + +~> **Note:** The builder doesn't support Windows images for now and only supports CentOS and Ubuntu images via SSH authentication with `ssh_username` (Required) and `ssh_password` (Optional). The `ssh_username` must be `root` for CentOS images and `ubuntu` for Ubuntu images. The `ssh_password` may contain 8-30 characters, and must consist of at least 2 items out of the capital letters, lower case letters, numbers and special characters. The special characters include `()~!@#\$%^&\*-+=\_|{}\[]:;'<>,.?/`. + +### Required: + + + +- `public_key` (string) - This is the UCloud public key. It must be provided unless `profile` is set, + but it can also be sourced from the `UCLOUD_PUBLIC_KEY` environment variable. + +- `private_key` (string) - This is the UCloud private key. It must be provided unless `profile` is set, + but it can also be sourced from the `UCLOUD_PRIVATE_KEY` environment variable. + +- `region` (string) - This is the UCloud region. It must be provided, but it can also be sourced from + the `UCLOUD_REGION` environment variables. + +- `project_id` (string) - This is the UCloud project id. It must be provided, but it can also be sourced + from the `UCLOUD_PROJECT_ID` environment variables. + + + + + + +- `availability_zone` (string) - This is the UCloud availability zone where UHost instance is located. such as: `cn-bj2-02`. + You may refer to [list of availability_zone](https://docs.ucloud.cn/api/summary/regionlist) + +- `source_image_id` (string) - This is the ID of base image which you want to create your customized images with. + +- `instance_type` (string) - The type of UHost instance. + You may refer to [list of instance type](https://docs.ucloud.cn/compute/terraform/specification/instance) + + + + + + +- `image_name` (string) - The name of the user-defined image, which contains 1-63 characters and only + support Chinese, English, numbers, '-\_,.:[]'. + + + + +### Optional: + + + +- `base_url` (string) - This is the base url. (Default: `https://api.ucloud.cn`). + +- `profile` (string) - This is the UCloud profile name as set in the shared credentials file, it can + also be sourced from the `UCLOUD_PROFILE` environment variables. + +- `shared_credentials_file` (string) - This is the path to the shared credentials file, it can also be sourced from + the `UCLOUD_SHARED_CREDENTIAL_FILE` environment variables. If this is not set + and a profile is specified, `~/.ucloud/credential.json` will be used. + + + + + + +- `instance_name` (string) - The name of instance, which contains 1-63 characters and only support Chinese, + English, numbers, '-', '\_', '.'. + +- `boot_disk_type` (string) - The type of boot disk associated to UHost instance. + Possible values are: `cloud_ssd` and `cloud_rssd` for cloud boot disk, `local_normal` and `local_ssd` + for local boot disk. (Default: `cloud_ssd`). The `cloud_ssd` and `local_ssd` are not fully supported + by all regions as boot disk type, please proceed to UCloud console for more details. + + ~> **Note:** It takes around 10 mins for boot disk initialization when `boot_disk_type` is `local_normal` or `local_ssd`. + +- `boot_disk_size` (int) - The size of boot disk associated to UHost instance, which cannot be smaller than the size of source image. + The unit is `GB`. Default value is the size of source image. + +- `vpc_id` (string) - The ID of VPC linked to the UHost instance. If not defined `vpc_id`, the instance will use the default VPC in the current region. + +- `subnet_id` (string) - The ID of subnet under the VPC. If `vpc_id` is defined, the `subnet_id` is mandatory required. + If `vpc_id` and `subnet_id` are not defined, the instance will use the default subnet in the current region. + +- `security_group_id` (string) - The ID of the fire wall associated to UHost instance. If `security_group_id` is not defined, + the instance will use the non-recommended web fire wall, and open port include 22, 3389 by default. + It is supported by ICMP fire wall protocols. + You may refer to [security group_id](https://docs.ucloud.cn/network/firewall/firewall). + +- `eip_bandwidth` (int) - Maximum bandwidth to the elastic public network, measured in Mbps (Mega bit per second). (Default: `10`). + +- `eip_charge_mode` (string) - Elastic IP charge mode. Possible values are: `traffic` as pay by traffic, `bandwidth` as pay by bandwidth, + `post_accurate_bandwidth` as post pay mode. (Default: `traffic`). + Note currently default `traffic` eip charge mode not not fully support by all `availability_zone` + in the `region`, please proceed to [UCloud console](https://console.ucloud.cn/unet/eip/create) for more details. + You may refer to [eip introduction](https://docs.ucloud.cn/unet/eip/introduction). + +- `user_data` (string) - User data to apply when launching the instance. + Note that you need to be careful about escaping characters due to the templates + being JSON. It is often more convenient to use user_data_file, instead. + Packer will not automatically wait for a user script to finish before + shutting down the instance this must be handled in a provisioner. + You may refer to [user_data_document](https://docs.ucloud.cn/uhost/guide/metadata/userdata) + +- `user_data_file` (string) - Path to a file that will be used for the user data when launching the instance. + +- `min_cpu_platform` (string) - Specifies a minimum CPU platform for the the VM instance. (Default: `Intel/Auto`). + You may refer to [min_cpu_platform](https://docs.ucloud.cn/uhost/introduction/uhost/type_new) + - The Intel CPU platform: + - `Intel/Auto` as the Intel CPU platform version will be selected randomly by system; + - `Intel/IvyBridge` as Intel V2, the version of Intel CPU platform selected by system will be `Intel/IvyBridge` and above; + - `Intel/Haswell` as Intel V3, the version of Intel CPU platform selected by system will be `Intel/Haswell` and above; + - `Intel/Broadwell` as Intel V4, the version of Intel CPU platform selected by system will be `Intel/Broadwell` and above; + - `Intel/Skylake` as Intel V5, the version of Intel CPU platform selected by system will be `Intel/Skylake` and above; + - `Intel/Cascadelake` as Intel V6, the version of Intel CPU platform selected by system will be `Intel/Cascadelake`; + - The AMD CPU platform: + - `Amd/Auto` as the Amd CPU platform version will be selected randomly by system; + - `Amd/Epyc2` as the version of Amd CPU platform selected by system will be `Amd/Epyc2` and above; + +- `use_ssh_private_ip` (bool) - If this value is true, packer will connect to the created UHost instance via a private ip + instead of allocating an EIP (elastic public ip).(Default: `false`). + + + + + + +- `image_description` (string) - The description of the image. + +- `image_copy_to_mappings` ([]ImageDestination) - The array of mappings regarding the copied images to the destination regions and projects. + + - `project_id` (string) - The destination project id, where copying image in. + + - `region` (string) - The destination region, where copying image in. + + - `name` (string) - The copied image name. If not defined, builder will use `image_name` as default name. + + - `description` (string) - The copied image description. + + ```json + { + "image_copy_to_mappings": [ + { + "project_id": "{{user `ucloud_project_id`}}", + "region": "cn-sh2", + "description": "test", + "name": "packer-test-basic-sh" + } + ] + } + ``` + +- `wait_image_ready_timeout` (int) - Timeout of creating image or copying image. The default timeout is 3600 seconds if this option + is not set or is set to 0. + + + + +## Examples + +Here is a basic example for build UCloud CentOS image: + +**JSON** + +```json +{ + "variables": { + "ucloud_public_key": "{{env `UCLOUD_PUBLIC_KEY`}}", + "ucloud_private_key": "{{env `UCLOUD_PRIVATE_KEY`}}", + "ucloud_project_id": "{{env `UCLOUD_PROJECT_ID`}}" + }, + + "builders": [ + { + "type": "ucloud-uhost", + "public_key": "{{user `ucloud_public_key`}}", + "private_key": "{{user `ucloud_private_key`}}", + "project_id": "{{user `ucloud_project_id`}}", + "region": "cn-bj2", + "availability_zone": "cn-bj2-02", + "instance_type": "n-basic-2", + "source_image_id": "uimage-f1chxn", + "ssh_username": "root", + "image_name": "packer-test{{timestamp}}" + } + ] +} +``` + +**HCL2** + +```hcl +// .pkr.hcl file +variable "ucloud_public_key" { + type = string + default = "xxx" +} + +variable "ucloud_private_key" { + type = string + default = "xxx" +} + +variable "ucloud_project_id" { + type = string + default = "xxx" +} + +source "ucloud-uhost" "basic-example" { + public_key = var.ucloud_public_key + private_key = var.ucloud_private_key + project_id = var.ucloud_project_id + region = "cn-bj2" + availability_zone = "cn-bj2-02" + instance_type = "n-basic-2" + source_image_id = "uimage-f1chxn" + ssh_username = "root" +} + +build { + source "sources.ucloud-uhost.basic-example" { + image_name = "packer-test-${timestamp()}" + } +} +``` + + +Here is a example for build UCloud Ubuntu image: + +**JSON** + +```json +{ + "variables": { + "ucloud_public_key": "{{env `UCLOUD_PUBLIC_KEY`}}", + "ucloud_private_key": "{{env `UCLOUD_PRIVATE_KEY`}}", + "ucloud_project_id": "{{env `UCLOUD_PROJECT_ID`}}", + "password": "ucloud_2020" + }, + + "builders": [ + { + "type": "ucloud-uhost", + "public_key": "{{user `ucloud_public_key`}}", + "private_key": "{{user `ucloud_private_key`}}", + "project_id": "{{user `ucloud_project_id`}}", + "region": "cn-bj2", + "availability_zone": "cn-bj2-02", + "instance_type": "n-basic-2", + "source_image_id": "uimage-irofn4", + "ssh_password": "{{user `password`}}", + "ssh_username": "ubuntu", + "image_name": "packer-test-ubuntu{{timestamp}}" + } + ], + + "provisioners": [ + { + "type": "shell", + "execute_command": "echo '{{user `password`}}' | sudo -S '{{.Path}}'", + "inline": ["sleep 30", "sudo apt update", "sudo apt install nginx -y"] + } + ] +} +``` + +**HCL2** + +```hcl +// .pkr.hcl file +variable "ucloud_public_key" { + type = string + default = "xxx" +} + +variable "ucloud_private_key" { + type = string + default = "xxx" +} + +variable "ucloud_project_id" { + type = string + default = "xxx" +} + +variable "password" { + type = string + default = "ucloud_2020" +} + +source "ucloud-uhost" "basic-example" { + public_key = var.ucloud_public_key + private_key = var.ucloud_private_key + project_id = var.ucloud_project_id + region = "cn-bj2" + availability_zone = "cn-bj2-02" + instance_type = "n-basic-2" + ssh_password = var.password + source_image_id = "uimage-irofn4" + ssh_username = "ubuntu" +} + +build { + source "sources.ucloud-uhost.basic-example" { + image_name = "packer-test-ubuntu-${timestamp()}" + } + provisioner "shell" { + execute_command = "echo '${var.password}' | sudo -S '{{.Path}}'" + inline = ["sleep 30", "sudo apt update", "sudo apt install nginx -y"] + } +} +``` + + +-> **Note:** Packer can also read the public key and private key from +environmental variables. See the configuration reference in the section above +for more information on what environmental variables Packer will look for. + +~> **Note:** Source image may be deprecated after a while, you can use the tools like [UCloud CLI](https://docs.ucloud.cn/cli/intro) to run `ucloud image list` to find one that exists. diff --git a/.web-docs/components/post-processor/import/README.md b/.web-docs/components/post-processor/import/README.md new file mode 100644 index 0000000..ad98e18 --- /dev/null +++ b/.web-docs/components/post-processor/import/README.md @@ -0,0 +1,108 @@ +Type: `ucloud-import` +Artifact BuilderId: `packer.post-processor.ucloud-import` + +The Packer UCloud Import post-processor takes the RAW, VHD, VMDK, or qcow2 artifact from various builders and imports it to UCloud customized image list for UHost Instance. + +~> **Note** Some regions don't support image import. You may refer to [ucloud console](https://console.ucloud.cn/uhost/uimage) for more detail. If you want to import to unsupported regions, please import the image in `cn-bj2` first, and then copy the image to the target region. + +## How Does it Work? + +The import process operates by making a temporary copy of the RAW, VHD, VMDK, or qcow2 to an UFile bucket, and calling an import task in UHost on the RAW, VHD, VMDK, or qcow2 file. Once completed, an UCloud UHost Image is returned. The temporary RAW, VHD, VMDK, or qcow2 copy in UFile can be discarded after the import is complete. + +## Configuration + +There are some configuration options available for the post-processor. There +are two categories: required and optional parameters. + +### Required: + + + +- `public_key` (string) - This is the UCloud public key. It must be provided unless `profile` is set, + but it can also be sourced from the `UCLOUD_PUBLIC_KEY` environment variable. + +- `private_key` (string) - This is the UCloud private key. It must be provided unless `profile` is set, + but it can also be sourced from the `UCLOUD_PRIVATE_KEY` environment variable. + +- `region` (string) - This is the UCloud region. It must be provided, but it can also be sourced from + the `UCLOUD_REGION` environment variables. + +- `project_id` (string) - This is the UCloud project id. It must be provided, but it can also be sourced + from the `UCLOUD_PROJECT_ID` environment variables. + + + + + + +- `ufile_bucket_name` (string) - The name of the UFile bucket where the RAW, VHD, VMDK, or qcow2 file will be copied to for import. + This bucket must exist when the post-processor is run. + +- `image_name` (string) - The name of the user-defined image, which contains 1-63 characters and only + supports Chinese, English, numbers, '-\_,.:[]'. + +- `image_os_type` (string) - Type of the OS. Possible values are: `CentOS`, `Ubuntu`, `Windows`, `RedHat`, `Debian`, `Other`. + You may refer to [ucloud_api_docs](https://docs.ucloud.cn/api/uhost-api/import_custom_image) for detail. + +- `image_os_name` (string) - The name of OS. Such as: `CentOS 7.2 64位`, set `Other` When `image_os_type` is `Other`. + You may refer to [ucloud_api_docs](https://docs.ucloud.cn/api/uhost-api/import_custom_image) for detail. + +- `format` (string) - The format of the import image , Possible values are: `raw`, `vhd`, `vmdk`, or `qcow2`. + + + + +### Optional: + + + +- `base_url` (string) - This is the base url. (Default: `https://api.ucloud.cn`). + +- `profile` (string) - This is the UCloud profile name as set in the shared credentials file, it can + also be sourced from the `UCLOUD_PROFILE` environment variables. + +- `shared_credentials_file` (string) - This is the path to the shared credentials file, it can also be sourced from + the `UCLOUD_SHARED_CREDENTIAL_FILE` environment variables. If this is not set + and a profile is specified, `~/.ucloud/credential.json` will be used. + + + + + + +- `ufile_key_name` (string) - The name of the object key in + `ufile_bucket_name` where the RAW, VHD, VMDK, or qcow2 file will be copied + to import. This is a [template engine](/packer/docs/templates/legacy_json_templates/engine). + Therefore, you may use user variables and template functions in this field. + +- `skip_clean` (bool) - Whether we should skip removing the RAW, VHD, VMDK, or qcow2 file uploaded to + UFile after the import process has completed. Possible values are: `true` to + leave it in the UFile bucket, `false` to remove it. (Default: `false`). + +- `image_description` (string) - The description of the image. + +- `wait_image_ready_timeout` (int) - Timeout of importing image. The default timeout is 3600 seconds if this option is not set or is set. + + + + +## Basic Example + +Here is a basic example. This assumes that the builder has produced a RAW artifact for us to work with. This will take the RAW image generated by a builder and upload it to UFile. Once uploaded, the import process will start, creating an UCloud UHost image to the region `cn-bj2`. + +```json +"post-processors":[ + { + "type":"ucloud-import", + "public_key": "{{user `ucloud_public_key`}}", + "private_key": "{{user `ucloud_private_key`}}", + "project_id": "{{user `ucloud_project_id`}}", + "region":"cn-bj2", + "ufile_bucket_name": "packer-import", + "image_name": "packer_import", + "image_os_type": "CentOS", + "image_os_name": "CentOS 6.10 64位", + "format": "raw" + } + ] +``` diff --git a/.web-docs/metadata.hcl b/.web-docs/metadata.hcl new file mode 100644 index 0000000..3152e91 --- /dev/null +++ b/.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 = "UCloud" + description = "The UCloud plugin is able to build customized images for use in UHost Instance." + identifier = "packer/hashicorp/ucloud" + component { + type = "builder" + name = "UCloud Uhost" + slug = "uhost" + } + component { + type = "post-processor" + name = "UCloud Import" + slug = "import" + } +} diff --git a/.web-docs/scripts/compile-to-webdocs.sh b/.web-docs/scripts/compile-to-webdocs.sh new file mode 100755 index 0000000..51a7238 --- /dev/null +++ b/.web-docs/scripts/compile-to-webdocs.sh @@ -0,0 +1,129 @@ +#!/usr/bin/env bash + +# Converts the folder name that the component documentation file +# is stored in into the integration slug of the component. +componentTypeFromFolderName() { + if [[ "$1" = "builders" ]]; then + echo "builder" + elif [[ "$1" = "provisioners" ]]; then + echo "provisioner" + elif [[ "$1" = "post-processors" ]]; then + echo "post-processor" + elif [[ "$1" = "datasources" ]]; then + echo "data-source" + else + echo "" + fi +} + +# $1: The content to adjust links +# $2: The organization of the integration +rewriteLinks() { + local result="$1" + local organization="$2" + + urlSegment="([^/]+)" + urlAnchor="(#[^/]+)" + + # Rewrite Component Index Page links to the Integration root page. + # + # (\1) (\2) (\3) + # /packer/plugins/datasources/amazon#anchor-tag--> + # /packer/integrations/hashicorp/amazon#anchor-tag + local find="\(\/packer\/plugins\/$urlSegment\/$urlSegment$urlAnchor?\)" + local replace="\(\/packer\/integrations\/$organization\/\2\3\)" + result="$(echo "$result" | sed -E "s/$find/$replace/g")" + + + # Rewrite Component links to the Integration component page + # + # (\1) (\2) (\3) (\4) + # /packer/plugins/datasources/amazon/parameterstore#anchor-tag --> + # /packer/integrations/{organization}/amazon/latest/components/datasources/parameterstore + local find="\(\/packer\/plugins\/$urlSegment\/$urlSegment\/$urlSegment$urlAnchor?\)" + local replace="\(\/packer\/integrations\/$organization\/\2\/latest\/components\/\1\/\3\4\)" + result="$(echo "$result" | sed -E "s/$find/$replace/g")" + + # Rewrite the Component URL segment from the Packer Plugin format + # to the Integrations format + result="$(echo "$result" \ + | sed "s/\/datasources\//\/data-source\//g" \ + | sed "s/\/builders\//\/builder\//g" \ + | sed "s/\/post-processors\//\/post-processor\//g" \ + | sed "s/\/provisioners\//\/provisioner\//g" \ + )" + + echo "$result" +} + +# $1: Docs Dir +# $2: Web Docs Dir +# $3: Component File +# $4: The org of the integration +processComponentFile() { + local docsDir="$1" + local webDocsDir="$2" + local componentFile="$3" + + local escapedDocsDir="$(echo "$docsDir" | sed 's/\//\\\//g' | sed 's/\./\\\./g')" + local componentTypeAndSlug="$(echo "$componentFile" | sed "s/$escapedDocsDir\///g" | sed 's/\.mdx//g')" + + # Parse out the Component Slug & Component Type + local componentSlug="$(echo "$componentTypeAndSlug" | cut -d'/' -f 2)" + local componentType="$(componentTypeFromFolderName "$(echo "$componentTypeAndSlug" | cut -d'/' -f 1)")" + if [[ "$componentType" = "" ]]; then + echo "Failed to process '$componentFile', unexpected folder name." + echo "Documentation for components must be stored in one of:" + echo "builders, provisioners, post-processors, datasources" + exit 1 + fi + + + # Calculate the location of where this file will ultimately go + local webDocsFolder="$webDocsDir/components/$componentType/$componentSlug" + mkdir -p "$webDocsFolder" + local webDocsFile="$webDocsFolder/README.md" + local webDocsFileTmp="$webDocsFolder/README.md.tmp" + + # Copy over the file to its webDocsFile location + cp "$componentFile" "$webDocsFile" + + # Remove the Header + local lastMetadataLine="$(grep -n -m 2 '^\-\-\-' "$componentFile" | tail -n1 | cut -d':' -f1)" + cat "$webDocsFile" | tail -n +"$(($lastMetadataLine+2))" > "$webDocsFileTmp" + mv "$webDocsFileTmp" "$webDocsFile" + + # Remove the top H1, as this will be added automatically on the web + cat "$webDocsFile" | tail -n +3 > "$webDocsFileTmp" + mv "$webDocsFileTmp" "$webDocsFile" + + # Rewrite Links + rewriteLinks "$(cat "$webDocsFile")" "$4" > "$webDocsFileTmp" + mv "$webDocsFileTmp" "$webDocsFile" +} + +# Compiles the Packer SDC compiled docs folder down +# to a integrations-compliant folder (web docs) +# +# $1: The directory of the plugin +# $2: The directory of the SDC compiled docs files +# $3: The output directory to place the web-docs files +# $4: The org of the integration +compileWebDocs() { + local docsDir="$1/$2" + local webDocsDir="$1/$3" + + echo "Compiling MDX docs in '$2' to Markdown in '$3'..." + # Create the web-docs directory if it hasn't already been created + mkdir -p "$webDocsDir" + + # Copy the README over + cp "$docsDir/README.md" "$webDocsDir/README.md" + + # Process all MDX component files (exclude index files, which are unsupported) + for file in $(find "$docsDir" | grep "$docsDir/.*/.*\.mdx" | grep --invert-match "index.mdx"); do + processComponentFile "$docsDir" "$webDocsDir" "$file" "$4" + done +} + +compileWebDocs "$1" "$2" "$3" "$4" diff --git a/GNUmakefile b/GNUmakefile index b9bec13..c11e7b7 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -32,3 +32,9 @@ testacc: dev generate: install-packer-sdc @go generate ./... # checkout the .docs folder for a preview of the docs + +build-docs: install-packer-sdc + @if [ -d ".docs" ]; then rm -r ".docs"; fi + @packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/" + @./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp" + @rm -r ".docs" diff --git a/docs/README.md b/docs/README.md index c7d380c..05517fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,61 +1,33 @@ -# UCloud Plugins +The UCloud plugin is able to build customized images based on an existing base image for use in UHost Instance. -The UCloud plugin is able to build -customized images based on an existing base image for use in UHost Instance. - -## Components - -The Scaffolding plugin is intended as a starting point for creating Packer plugins, containing: - -### Builders - -- [ucloud-uhost](/docs/builders/uhost.mdx) - The `ucloud-uhost` builder provides the capability to build - customized images based on an existing base image for use in UHost Instance. - -### Post-processors - -- [ucloud-import](/docs/post-processors/import.mdx) - The UCloud Import post-processor takes the RAW, VHD, VMDK, or qcow2 - artifact from various builders and imports it to UCloud customized image list - for UHost Instance. - -## Installation - -### Using pre-built releases - -#### Using the `packer init` command - -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). +### Installation +To install this plugin add this code into your Packer configuration and run [packer init](/packer/docs/commands/init) ```hcl packer { - required_plugins { - ucloud = { - version = ">= 1.0.9" - source = "github.com/hashicorp/ucloud" + required_plugins { + ucloud = { + version = "~> 1" + source = "github.com/hashicorp/ucloud" + } } - } } ``` -#### Manual installation +Alternatively, you can use `packer plugins install` to manage installation of this plugin. -You can find pre-built binary releases of the plugin [here](https://github.com/hashicorp/packer-plugin-name/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). +```sh +packer plugins install github.com/hashicorp/ucloud +``` +### Components +#### Builders -#### From Source +- [ucloud-uhost](/packer/integrations/hashicorp/ucloud/latest/components/builder/uhost) - The `ucloud-uhost` builder provides the capability to build + customized images based on an existing base image for use in UHost Instance. + +#### Post-processors -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-ucloud` 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). +- [ucloud-import](/packer/integrations/hashicorp/uhost/latest/components/post-processor/import) - The UCloud Import post-processor takes the RAW, VHD, VMDK, or qcow2 + artifact from various builders and imports it to UCloud customized image list + for UHost Instance. diff --git a/docs/builders/uhost.mdx b/docs/builders/uhost.mdx index ac117f3..ae63b5a 100644 --- a/docs/builders/uhost.mdx +++ b/docs/builders/uhost.mdx @@ -48,8 +48,7 @@ builder. Here is a basic example for build UCloud CentOS image: - - +**JSON** ```json { @@ -76,8 +75,7 @@ Here is a basic example for build UCloud CentOS image: } ``` - - +**HCL2** ```hcl // .pkr.hcl file @@ -114,13 +112,10 @@ build { } ``` - - Here is a example for build UCloud Ubuntu image: - - +**JSON** ```json { @@ -157,8 +152,7 @@ Here is a example for build UCloud Ubuntu image: } ``` - - +**HCL2** ```hcl // .pkr.hcl file @@ -205,8 +199,6 @@ build { } ``` - - -> **Note:** Packer can also read the public key and private key from environmental variables. See the configuration reference in the section above