From 614e35f6ff355824d0fbc11bb8dd24f7430a58b7 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 23 Jan 2025 19:41:57 -0800 Subject: [PATCH] updated provisioners reference topics --- .../content/docs/provisioners/breakpoint.mdx | 20 +++++------------ .../docs/provisioners/community-supported.mdx | 19 +++++++++++----- website/content/docs/provisioners/custom.mdx | 16 -------------- website/content/docs/provisioners/file.mdx | 19 ++++++---------- .../content/docs/provisioners/hcp-sbom.mdx | 8 +++---- website/content/docs/provisioners/index.mdx | 22 +++++++++---------- .../content/docs/provisioners/powershell.mdx | 17 +++++--------- .../content/docs/provisioners/shell-local.mdx | 18 +++++---------- website/content/docs/provisioners/shell.mdx | 16 +++++--------- .../docs/provisioners/windows-restart.mdx | 12 +++++----- .../docs/provisioners/windows-shell.mdx | 14 +++++------- .../provisioners/community_provisioners.mdx | 12 ---------- website/data/docs-nav-data.json | 18 +++++++-------- website/redirects.js | 5 +++++ 14 files changed, 83 insertions(+), 133 deletions(-) delete mode 100644 website/content/docs/provisioners/custom.mdx delete mode 100644 website/content/partials/provisioners/community_provisioners.mdx diff --git a/website/content/docs/provisioners/breakpoint.mdx b/website/content/docs/provisioners/breakpoint.mdx index 97e9ffd6b..2cde93863 100644 --- a/website/content/docs/provisioners/breakpoint.mdx +++ b/website/content/docs/provisioners/breakpoint.mdx @@ -1,28 +1,18 @@ --- description: > - The breakpoint provisioner will pause until the user presses "enter" to resume - - the build. This is intended for debugging purposes, and allows you to halt at - a - - particular part of the provisioning process. -page_title: breakpoint - Provisioners + The `breakpoint` provisioner pauses a build until you press the Enter key. Use the `breakpoint` provisioner to help you debug errors. +page_title: breakpoint provisioner reference --- -# Breakpoint Provisioner - -Type: `breakpoint` +# `breakpoint` provisioner -The breakpoint provisioner will pause until the user presses "enter" to resume -the build. This is intended for debugging purposes, and allows you to halt at a -particular part of the provisioning process. +The `breakpoint` provisioner pauses the build operation until you press the Enter key to resume the build. Use the `breakpoint` provisioner to help you debug errors. -This is independent of the `-debug` flag, which will instead halt at every step -and between every provisioner. +Alternatively, you can add the [`-debug` flag](/packer/docs/commands/build#debug) when running your build to halt the operation at every step and between every provisioner. ## Basic Example diff --git a/website/content/docs/provisioners/community-supported.mdx b/website/content/docs/provisioners/community-supported.mdx index 1cb14aa97..f2bdf70e9 100644 --- a/website/content/docs/provisioners/community-supported.mdx +++ b/website/content/docs/provisioners/community-supported.mdx @@ -1,14 +1,23 @@ --- description: | - Community-maintained provisioners are not part of the core Packer binary, but - can run alongside Packer with minimal extra effort. -page_title: Community - Provisioners + You can use provisioners built and maintained by the Packer developer community to extend Packer functionality. Learn about community-supported provisioners. +page_title: Community provisioners reference --- # Community Provisioners The following provisioners are developed and maintained by various members of the Packer community, not by HashiCorp. For more information on how to use community -provisioners, see our docs on [extending Packer](/packer/docs/plugins/creation). +provisioners, refer to [Developing Plugins](/packer/docs/plugins/creation). + +- [Comment Provisioner](https://github.com/SwampDragons/packer-provisioner-comment) - + Example provisioner that allows you to annotate your build with bubble-text + comments. + +- [Windows Update provisioner](https://github.com/rgl/packer-plugin-windows-update) - + A provisioner for gracefully handling Windows updates and the reboots they + cause. + +- [S3 Provisioner](https://github.com/spacechunks/packer-plugin-s3) - + A provisioner that retrieves objects from S3 and stores them at a given destination. -@include 'provisioners/community_provisioners.mdx' diff --git a/website/content/docs/provisioners/custom.mdx b/website/content/docs/provisioners/custom.mdx deleted file mode 100644 index 560684434..000000000 --- a/website/content/docs/provisioners/custom.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: | - Packer is extensible, allowing you to write new provisioners without having to - modify the core source code of Packer itself. Documentation for creating new - provisioners is covered in the custom provisioners page of the Packer plugin - section. -page_title: Custom - Provisioners ---- - -# Custom Provisioner - -Packer is extensible, allowing you to write new provisioners without having to -modify the core source code of Packer itself. Documentation for creating new -provisioners is covered in the [custom -provisioners](/packer/docs/plugins/creation/custom-provisioners) page of the Packer -plugin section. diff --git a/website/content/docs/provisioners/file.mdx b/website/content/docs/provisioners/file.mdx index 987b7de3b..4e9d96e68 100644 --- a/website/content/docs/provisioners/file.mdx +++ b/website/content/docs/provisioners/file.mdx @@ -1,26 +1,21 @@ --- description: | - The file Packer provisioner uploads files to machines built by Packer. The - recommended usage of the file provisioner is to use it to upload files, and - then use shell provisioner to move them to the proper place, set permissions, - etc. -page_title: File - Provisioners + The `file` Packer provisioner uploads files to machines built by Packer. Learn how to use the `file` provisioner and about the Packer provisioner workflow. +page_title: file provisioner reference --- -# File Provisioner +# `file` provisioner -Type: `file` +The `file` Packer provisioner uploads files to machines built by Packer. We recommend implementing the following workflow: -The file Packer provisioner uploads files to machines built by Packer. The -recommended usage of the file provisioner is to use it to upload files, and -then use [shell provisioner](/packer/docs/provisioners/shell) to move them to the -proper place, set permissions, etc. +1. Use the `file` provisionerto upload files +1. Use the [`shell` provisioner](/packer/docs/provisioners/shell) to move the files imto the proper place, set permissions, and perform other tasks. -Warning: You can only upload files to locations that the provisioning user +You can only upload files to locations that the provisioning user (generally not root) has permission to access. Creating files in /tmp and using a shell provisioner to move them into the final location is the only way to upload files to root owned locations. diff --git a/website/content/docs/provisioners/hcp-sbom.mdx b/website/content/docs/provisioners/hcp-sbom.mdx index f0bd15cca..a165c5d24 100644 --- a/website/content/docs/provisioners/hcp-sbom.mdx +++ b/website/content/docs/provisioners/hcp-sbom.mdx @@ -1,16 +1,14 @@ --- description: | - The hcp-sbom Packer provisioner uploads a CycloneDX or SPDX JSON-formatted software bill of materials record to HCP Packer. -page_title: HCP SBOM - Provisioners + The `hcp-sbom` Packer provisioner uploads a CycloneDX- or SPDX JSON-formatted software bill of materials record to HCP Packer. Learn how to use the `hcp-sbom` provisioner. +page_title: hcp-sbom provisioner reference --- -# HCP SBOM Provisioner - -Type: `hcp-sbom` +# `hcp-sbom` provisioner The `hcp-sbom` provisioner uploads software bill of materials (SBOM) files from artifacts built by Packer to HCP Packer. You must format SBOM files you want to upload as JSON and follow either the [SPDX](https://spdx.github.io/spdx-spec/latest) or [CycloneDX](https://cyclonedx.org/) specification. HCP Packer ties these SBOM files to the version of the artifact that Packer builds. diff --git a/website/content/docs/provisioners/index.mdx b/website/content/docs/provisioners/index.mdx index da2603e80..f64e25f46 100644 --- a/website/content/docs/provisioners/index.mdx +++ b/website/content/docs/provisioners/index.mdx @@ -1,11 +1,11 @@ --- description: | Provisioners use builtin and third-party software to install and configure the - machine image after booting. -page_title: Provisioners + machine image after booting. Learn about Packer provisioners. +page_title: Provisioners overview --- -# Provisioners +# Provisioners overview Provisioners use built-in and third-party software to install and configure the machine image after booting. Provisioners prepare the system, so you may want to use them for the following use cases: @@ -17,19 +17,19 @@ booting. Provisioners prepare the system, so you may want to use them for the fo The following provisioners are included with Packer: -- [Breakpoint](/packer/docs/provisioners/breakpoint) - pause until the user presses `Enter` to resume +- [`breakpoint`](/packer/docs/provisioners/breakpoint) - pause until the user presses `Enter` to resume a build. -- [File](/packer/docs/provisioners/file) - upload files to machines image during a build. -- [HCP SBOM](/packer/docs/provisioners/hcp-sbom) - upload an SBOM and associate it with an artifact +- [`file`](/packer/docs/provisioners/file) - upload files to machines image during a build. +- [`hcp-sbom`](/packer/docs/provisioners/hcp-sbom) - upload an SBOM and associate it with an artifact version in the HCP Packer registry. -- [Shell](/packer/docs/provisioners/shell) - run shell scripts on the machines image during a build. -- [Local Shell](/packer/docs/provisioners/shell-local) - run shell scripts on the host running Packer +- [`shell`](/packer/docs/provisioners/shell) - run shell scripts on the machines image during a build. +- [`shell-local`](/packer/docs/provisioners/shell-local) - run shell scripts on the host running Packer during a build. -- [PowerShell](/packer/docs/provisioners/powershell) - run PowerShell scripts on Windows machine +- [`powershell`](/packer/docs/provisioners/powershell) - run PowerShell scripts on Windows machine images during a build. -- [Windows Shell](/packer/docs/provisioners/windows-shell) - run commands using `cmd` on Windows +- [`windows-shell`](/packer/docs/provisioners/windows-shell) - run commands using `cmd` on Windows machine images during a build. -- [Windows Restart](/packer/docs/provisioners/windows-restart) - initiate a reboot on a Windows +- [`windows-restart`](/packer/docs/provisioners/windows-restart) - initiate a reboot on a Windows machine images during a build. Additional [Community Supported](/packer/docs/provisioners/community-supported) provisioners are diff --git a/website/content/docs/provisioners/powershell.mdx b/website/content/docs/provisioners/powershell.mdx index c50b8515c..d0cffb890 100644 --- a/website/content/docs/provisioners/powershell.mdx +++ b/website/content/docs/provisioners/powershell.mdx @@ -1,23 +1,18 @@ --- description: | - The PowerShell Packer provisioner runs PowerShell scripts on Windows machines. - It assumes that the communicator in use is WinRM. -page_title: PowerShell - Provisioners + The `powershell` Packer provisioner runs PowerShell scripts on Windows machines. + Learn how to use the provisioner with WinRM and SSH communicators. +page_title: powershell provisioner reference --- -# PowerShell Provisioner +# `powershell` provisioner -Type: `powershell` - -The PowerShell Packer provisioner runs PowerShell scripts on Windows machines. -It assumes that the communicator in use is WinRM. However, the provisioner can -work equally well (with a few caveats) when combined with the SSH communicator. -See the [section -below](#combining-the-powershell-provisioner-with-the-ssh-communicator) for +The `powershell` Packer provisioner runs PowerShell scripts on Windows machines. +The provisioner is designed for machines using WinRM as the communicator, but you can also use the provisioner with the SSH communicator. Refer to the [Combining the PowerShell Provisioner with the SSH Communicator](#combining-the-powershell-provisioner-with-the-ssh-communicator) for details. `@include 'path/separator-note.mdx'` diff --git a/website/content/docs/provisioners/shell-local.mdx b/website/content/docs/provisioners/shell-local.mdx index a8bbea413..578fc46e8 100644 --- a/website/content/docs/provisioners/shell-local.mdx +++ b/website/content/docs/provisioners/shell-local.mdx @@ -1,24 +1,18 @@ --- description: | - shell-local will run a shell script of your choosing on the machine where - Packer is being run - in other words, shell-local will run the shell script on - your build server, or your desktop, etc., rather than the remote/guest machine - being provisioned by Packer. -page_title: Shell (Local) - Provisioners + The `shell-local` Packer provisioner runs shell scripts on the machine where Packer is running. Learn how to use the `shell-local` provisioner to run a shell script on your build server, desktop, or other local machine. +page_title: shell-local provisioner reference --- -# Local Shell Provisioner +# `shell-local` provisioner -Type: `shell-local` - -shell-local will run a shell script of your choosing on the machine where -Packer is being run - in other words, shell-local will run the shell script on -your build server, or your desktop, etc., rather than the remote/guest machine -being provisioned by Packer. +The `shell-local` provisioner runs shell scripts on the machine where +Packer is running. Use the provisioner to run a shell script on your build server, desktop, or other local machine instead of the remote or guest machine you are +using Packer to provision. The [remote shell](/packer/docs/provisioners/shell) provisioner executes shell scripts on a remote machine. diff --git a/website/content/docs/provisioners/shell.mdx b/website/content/docs/provisioners/shell.mdx index ca10852cf..6049c9ef9 100644 --- a/website/content/docs/provisioners/shell.mdx +++ b/website/content/docs/provisioners/shell.mdx @@ -1,22 +1,18 @@ --- description: | - The shell Packer provisioner provisions machines built by Packer using shell - scripts. Shell provisioning is the easiest way to get software installed and - configured on a machine. -page_title: Shell - Provisioners + The `shell` Packer provisioner provisions machines built by Packer using shell + scripts. Use the `shell` provisioner install and configure software on a machine. +page_title: shell provisioner reference --- -# Shell Provisioner +# `shell` provisioner -Type: `shell` - -The shell Packer provisioner provisions machines built by Packer using shell -scripts. Shell provisioning is the easiest way to get software installed and -configured on a machine. +The `shell` Packer provisioner provisions machines built by Packer using shell +scripts. Use the `shell` provisioner install and configure software on a machine. -> **Building Windows images?** You probably want to use the [PowerShell](/packer/docs/provisioners/powershell) or [Windows diff --git a/website/content/docs/provisioners/windows-restart.mdx b/website/content/docs/provisioners/windows-restart.mdx index 9c78bced5..8a45636fd 100644 --- a/website/content/docs/provisioners/windows-restart.mdx +++ b/website/content/docs/provisioners/windows-restart.mdx @@ -1,19 +1,17 @@ --- description: | - The Windows restart provisioner restarts a Windows machine and waits for it to - come back up. -page_title: Windows Restart - Provisioners + The `windows-restart` provisioner restarts a Windows machine and waits for it to + come back up. Learn how to use the `windows-restart` provisioner. +page_title: windows-restart provisioner reference --- -# Windows Restart Provisioner +# `windows-restart` provisioner -Type: `windows-restart` - -The Windows restart provisioner initiates a reboot on a Windows machine and +The `windows-restart` provisioner initiates a reboot on a Windows machine and waits for the machine to come back online. The Windows provisioning process often requires multiple reboots, and this diff --git a/website/content/docs/provisioners/windows-shell.mdx b/website/content/docs/provisioners/windows-shell.mdx index 2663aedf7..60ada7244 100644 --- a/website/content/docs/provisioners/windows-shell.mdx +++ b/website/content/docs/provisioners/windows-shell.mdx @@ -1,20 +1,18 @@ --- description: | - The windows-shell Packer provisioner runs commands on Windows using the cmd - shell. -page_title: Windows Shell - Provisioners + The `windows-shell` provisioner runs commands on Windows using the `cmd` + shell. Learn how to use the `windows-shell` provisioner. +page_title: windows-shell provisioner reference --- -# Windows Shell Provisioner +# `windows-shell` provisioner -Type: `windows-shell` - -The windows-shell Packer provisioner runs commands on a Windows machine using -`cmd`. It assumes it is running over WinRM. +The `windows-shell` Packer provisioner runs commands on a Windows machine using +`cmd`. The provisioner is designed to communicate with machines running WinRM. ## Basic Example diff --git a/website/content/partials/provisioners/community_provisioners.mdx b/website/content/partials/provisioners/community_provisioners.mdx deleted file mode 100644 index 172938d71..000000000 --- a/website/content/partials/provisioners/community_provisioners.mdx +++ /dev/null @@ -1,12 +0,0 @@ -### Community Provisioners - -- [Comment Provisioner](https://github.com/SwampDragons/packer-provisioner-comment) - - Example provisioner that allows you to annotate your build with bubble-text - comments. - -- [Windows Update provisioner](https://github.com/rgl/packer-plugin-windows-update) - - A provisioner for gracefully handling Windows updates and the reboots they - cause. - -- [S3 Provisioner](https://github.com/spacechunks/packer-plugin-s3) - - A provisioner that retrieves objects from S3 and stores them at a given destination. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a601d5f01..d6d453a46 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -785,40 +785,40 @@ "path": "provisioners" }, { - "title": "Breakpoint", + "title": "breakpoint", "path": "provisioners/breakpoint" }, { - "title": "File", + "title": "file", "path": "provisioners/file" }, { - "title": "HCP SBOM", + "title": "hcp-sbom", "path": "provisioners/hcp-sbom" }, { - "title": "PowerShell", + "title": "powershell", "path": "provisioners/powershell" }, { - "title": "Shell", + "title": "shell", "path": "provisioners/shell" }, { - "title": "Shell (Local)", + "title": "shell-Local", "path": "provisioners/shell-local" }, { - "title": "Windows Shell", + "title": "windows-shell", "path": "provisioners/windows-shell" }, { - "title": "Windows Restart", + "title": "windows-restart", "path": "provisioners/windows-restart" }, { "title": "Custom", - "path": "provisioners/custom" + "href": "/packer/docs/plugins/creation/custom-provisioners" }, { "title": "Community-Supported", diff --git a/website/redirects.js b/website/redirects.js index 05458574d..190a54245 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -91,6 +91,11 @@ module.exports = [ destination: '/packer/docs/plugins/install', permanent: true, }, + { + source: '/packer/docs/provisioners/custom', + destination: '/packer/docs/plugins/creation/custom-provisioners', + permanent: true, + } /** * END EMPTY PAGE REDIRECTS */