From da8ec952492a863030e683ae628c04430d3fda98 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 14 Oct 2021 15:26:19 -0400 Subject: [PATCH] Updates for HCP Packer docs Enable HCP Packer docs and add note about public beta (#11339) format markdown and mention that registry block is available in v1.7.7 --- .../{ => hcp}/hcp-packer-image.mdx | 10 ++-- .../{ => hcp}/hcp-packer-iteration.mdx | 8 ++-- .../content/docs/datasources/hcp/index.mdx | 42 +++++++++++++++++ .../{ => hcp}/packer-image-iteration.mdx | 8 ++-- website/content/docs/index.mdx | 22 +++++---- .../blocks/build/hcp_packer_registry.mdx | 47 ++++++++++++++----- website/data/docs-nav-data.json | 25 ++++++++++ 7 files changed, 128 insertions(+), 34 deletions(-) rename website/content/docs/datasources/{ => hcp}/hcp-packer-image.mdx (82%) rename website/content/docs/datasources/{ => hcp}/hcp-packer-iteration.mdx (81%) create mode 100644 website/content/docs/datasources/hcp/index.mdx rename website/content/docs/datasources/{ => hcp}/packer-image-iteration.mdx (67%) diff --git a/website/content/docs/datasources/hcp-packer-image.mdx b/website/content/docs/datasources/hcp/hcp-packer-image.mdx similarity index 82% rename from website/content/docs/datasources/hcp-packer-image.mdx rename to website/content/docs/datasources/hcp/hcp-packer-image.mdx index ba90a00eb..8c13afe96 100644 --- a/website/content/docs/datasources/hcp-packer-image.mdx +++ b/website/content/docs/datasources/hcp/hcp-packer-image.mdx @@ -14,8 +14,8 @@ The `HCP Packer Image` Data Source retrieves information about an image from the HCP Packer registry. This information can be used to provide a source image to various Packer builders. -Please note: The HCP Packer registry is in development, and is not yet available -for public use. For more information about HCP Packer, see https://www.hashicorp.com/blog/announcing-hcp-packer +~> **Note:** HCP Packer is under active development, and we are currently offering a [public beta version](https://portal.cloud.hashicorp.com) to collect feedback and continue improving the product. +To get started, visit the [HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the [Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) collection on HashiCorp Learn. ## Basic Example @@ -63,7 +63,7 @@ data "hcp-packer-image" "foo" { # a single base image can be customized in multiple secondary layers. source "amazon-ebs" "packer-secondary" { source_ami = data.hcp-packer-image.foo.id - ... + # ... } ``` @@ -75,11 +75,11 @@ described. ### Required: -@include 'datasource/hcp-packer-image/RunConfig-required.mdx' +@include 'datasource/hcp-packer-image/Config-required.mdx' There are currently no optional fields for this datasource, though we intend to add filtering fields in the future. ### Output Fields: -@include 'datasource/hcp-packer-image/DatasourceOutput.mdx' \ No newline at end of file +@include 'datasource/hcp-packer-image/DatasourceOutput.mdx' diff --git a/website/content/docs/datasources/hcp-packer-iteration.mdx b/website/content/docs/datasources/hcp/hcp-packer-iteration.mdx similarity index 81% rename from website/content/docs/datasources/hcp-packer-iteration.mdx rename to website/content/docs/datasources/hcp/hcp-packer-iteration.mdx index 388542b81..a169bb982 100644 --- a/website/content/docs/datasources/hcp-packer-iteration.mdx +++ b/website/content/docs/datasources/hcp/hcp-packer-iteration.mdx @@ -14,8 +14,8 @@ The `HCP Packer Iteration` Data Source retrieves information about an iteration from the HCP Packer registry. This information can be used to query HCP for a source image for various Packer builders. -Please note: The HCP Packer registry is in development, and is not yet available -for public use. For more information about HCP Packer, see https://www.hashicorp.com/blog/announcing-hcp-packer +~> **Note:** HCP Packer is under active development, and we are currently offering a [public beta version](https://portal.cloud.hashicorp.com) to collect feedback and continue improving the product. +To get started, visit the [HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the [Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) collection on HashiCorp Learn. ## Basic Example @@ -73,11 +73,11 @@ described. ### Required: -@include 'datasource/hcp-packer-iteration/RunConfig-required.mdx' +@include 'datasource/hcp-packer-iteration/Config-required.mdx' There are currently no optional fields for this datasource, though we intend to add filtering fields in the future. ### Output Fields: -@include 'datasource/hcp-packer-iteration/DatasourceOutput.mdx' \ No newline at end of file +@include 'datasource/hcp-packer-iteration/DatasourceOutput.mdx' diff --git a/website/content/docs/datasources/hcp/index.mdx b/website/content/docs/datasources/hcp/index.mdx new file mode 100644 index 000000000..5dddf1b86 --- /dev/null +++ b/website/content/docs/datasources/hcp/index.mdx @@ -0,0 +1,42 @@ +--- +description: | + Data sources used to data from the HCP Packer registry. +page_title: HCP - Data sources +sidebar_title: Overview +--- + + +# HCP Packer Registry Data sources + +The HCP Packer registry bridges the gap between image factories and image +deployments, allowing development and security teams to work together to create, +manage, and consume golden images in a centralized way. + +The HCP Packer registry stores metadata about your images, including when they +were created, where the image exists in the cloud, and what (if any) git commit +is associated with your image build. You can use the registry to track +information about the golden images your Packer builds produce, clearly +designate which images are appropriate for test and production environments, +and query for the right golden images to use in both Packer and Terraform +configurations. + +HCP Packer is under active development, and we are currently offering a public +beta version to collect feedback and continue improving the product. We +encourage you to try HCP Packer and submit your feedback. + +Packer has two data sources that work together to retrieve information from the +HCP Packer registry: + + * [hcp-packer-iteration](/docs/datasources/hcp/hcp-packer-iteration) - + retrieves information about an iteration in HCP Packer registry + * [hcp-packer-image](/docs/datasources/hcp/hcp-packer-image) - retrieves + information about a specific image created in the HCP Packer registry + +These data sources are intended to be used together to determine source images +for pipelined Packer builds. + +## How to use this plugin + +This plugin comes bundled with the Packer core, so you do not need to install +it separately. Please install Packer v1.7.7 or above to use the latest version +of the HCP Packer registry datasources. \ No newline at end of file diff --git a/website/content/docs/datasources/packer-image-iteration.mdx b/website/content/docs/datasources/hcp/packer-image-iteration.mdx similarity index 67% rename from website/content/docs/datasources/packer-image-iteration.mdx rename to website/content/docs/datasources/hcp/packer-image-iteration.mdx index 7e7edbdda..9176c58d1 100644 --- a/website/content/docs/datasources/packer-image-iteration.mdx +++ b/website/content/docs/datasources/hcp/packer-image-iteration.mdx @@ -14,8 +14,8 @@ The `Packer Image Iteration` Data Source retrieves information about an iteration from the HCP Packer registry. This information can be parsed to provide a source image to various Packer builders. -Please note: The HCP Packer registry is in development, and is not yet available -for public use. For more information about HCP Packer, see https://www.hashicorp.com/blog/announcing-hcp-packer +~> **Note:** HCP Packer is under active development, and we are currently offering a [public beta version](https://portal.cloud.hashicorp.com) to collect feedback and continue improving the product. +To get started, visit the [HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the [Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) collection on HashiCorp Learn. ## Basic Example @@ -37,7 +37,7 @@ described. ### Required: -@include 'datasource/packer-image-iteration/RunConfig-required.mdx' +@include 'datasource/packer-image-iteration/Config-required.mdx' There are currently no optional fields for this datasource, though we intend -to add filtering fields in the future. \ No newline at end of file +to add filtering fields in the future. diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx index d1f92a760..186ad6e51 100644 --- a/website/content/docs/index.mdx +++ b/website/content/docs/index.mdx @@ -1,15 +1,21 @@ --- description: | - Welcome to the Packer documentation! This documentation is more of a reference - guide for all available features and options in Packer. If you're just getting - started with Packer, please start with the introduction and getting started - guide instead. + Packer allows you to create identical machine images for multiple platforms from a single source template. page_title: Documentation --- # Packer Documentation -Welcome to the Packer documentation! This documentation is more of a reference -guide for all available features and options in Packer. If you're just getting -started with Packer, please start with the [introduction and getting started -guide](/intro) instead. +[Packer](https://www.packer.io/) is an open source tool that enables you to create identical machine images for multiple platforms from a single source template. A common use case is creating "golden images" that teams across an organization can use in cloud infrastructure. + +To install Packer and learn the standard Packer workflow, try the [Get Started tutorials](https://learn.hashicorp.com/packer) on Hashicorp Learn. + +## HCP Packer + +The HCP Packer registry bridges the gap between image factories and image deployments, allowing development and security teams to work together to create, manage, and consume golden images in a centralized way. + +The HCP Packer registry stores metadata about your images, including when they were created, where the image exists in the cloud, and what (if any) git commit is associated with your image build. You can use the registry to track information about the golden images your Packer builds produce, clearly designate which images are appropriate for test and production environments, and query for the right golden images to use in both Packer and Terraform configurations. + +HCP Packer is under active development, and we are currently offering a [public beta version](https://portal.cloud.hashicorp.com) to collect feedback and continue improving the product. We encourage you to try HCP Packer and submit your feedback. + +To get started, visit the [HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the [Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) collection on HashiCorp Learn. diff --git a/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx b/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx index 67caf425d..646a2ab71 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx @@ -1,17 +1,33 @@ --- description: > The hcp_packer_registry allows operators the ability to customize the metadata sent to HCP Packer Registry. - It configures the base details of an image that is created or updated within the HCP Packer registry. + It configures the base details of an image that is created or updated within HCP Packer. page_title: hcp_packer_registry - build - Blocks --- # The `hcp_packer_registry` block -The `hcp_packer_registry` block allows operators the ability to customize the metadata sent to -HCP Packer Registry. It configures the details of an image that is created or updated within the HCP Packer registry. +~> **Note:** HCP Packer is under active development, and we are currently +offering a [public beta version](https://portal.cloud.hashicorp.com) to collect +feedback and continue improving the product. +To get started, visit the +[HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the +[Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) +collection on HashiCorp Learn. -The presence of a `hcp_packer_registry` block will enable the HCP Packer registry mode and all the builds within that build block -will be pushed to the remote registry if the appropriate HCP credentials are set (`HCP_CLIENT_ID` and `HCP_CLIENT_SECRET`). If no HCP credentials are set Packer will fail the build and exit immediately to avoid any potential artifact drift between the build providers and the HCP Packer registry. + +The `hcp_packer_registry` block allows operators the ability to customize the +metadata sent to HCP Packer Registry. It configures the details of an image +that is created or updated within the HCP Packer registry. + +This block is available from version 1.7.7 of Packer. + +The presence of a `hcp_packer_registry` block in a build block will enable HCP +Packer mode. Packer will push all builds within that build block to the remote +registry if the appropriate HCP credentials are set (`HCP_CLIENT_ID` and +`HCP_CLIENT_SECRET`). If no HCP credentials are set, Packer will fail the build +and exit immediately to avoid any potential artifact drift between the defined +builders (source blocks) and the HCP Packer registry. ```hcl # file: builds.pkr.hcl @@ -38,13 +54,18 @@ Some nice description about the image which artifact is being published to HCP P } ``` -- `bucket_name` (string) - The image name when published to the HCP Packer registry. Should always be the same, otherwise a new image will be created. - Defaults to `build.name` if not set. Will be overwritten if `HCP_PACKER_BUCKET_NAME` is set. +- `bucket_name` (string) - The image name when published to the HCP Packer + registry. Should always be the same, otherwise a new image will be created. + Defaults to `build.name` if not set. Will be overwritten if + `HCP_PACKER_BUCKET_NAME` is set. -- `description` (string) - The image description. Useful to provide a summary about the image. The description will appear - at the image's main page and will be updated whenever it is changed and a new build is pushed to the HCP Packer registry. Should contain - a maximum of 255 characters. Defaults to `build.description` if not set. +- `description` (string) - The image description. Useful to provide a summary + about the image. The description will appear at the image's main page and + will be updated whenever it is changed and a new build is pushed to the HCP + Packer registry. Should contain a maximum of 255 characters. Defaults to + `build.description` if not set. -- `labels` (map[string]string) - Map of labels. Can provide any information, such as tools versions - (e.g. go 1.17, python 3.5, etc...). The labels will appear at the image's main page and will be updated - whenever it is changed and a new build is pushed to the HCP Packer registry. +- `labels` (map[string]string) - Map of labels. Can provide any information, + such as tools versions (e.g. go 1.17, python 3.5, etc...). The labels will + appear at the image's main page and will be updated whenever it is changed + and a new build is pushed to the HCP Packer registry. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e1c77825a..718042f34 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -75,6 +75,10 @@ "title": "Overview", "path": "templates/hcl_templates/blocks/build" }, + { + "title": "hcp_packer_registry", + "path": "templates/hcl_templates/blocks/build/hcp_packer_registry" + }, { "title": "source", "path": "templates/hcl_templates/blocks/build/source" @@ -707,6 +711,23 @@ { "title": "Overview", "path": "datasources" + }, + { + "title": "HCP Packer", + "routes": [ + { + "title": "Overview", + "path": "datasources/hcp" + }, + { + "title": "Iteration", + "path": "datasources/hcp/hcp-packer-iteration" + }, + { + "title": "Image", + "path": "datasources/hcp/hcp-packer-image" + } + ] } ] }, @@ -846,5 +867,9 @@ { "title": "Debugging", "path": "debugging" + }, + { + "title": "HCP Packer", + "href": "https://cloud.hashicorp.com/docs/packer" } ]