Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs/packer seo templates batch1 #13282

Merged
merged 5 commits into from
Jan 29, 2025
Merged

Docs/packer seo templates batch1 #13282

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba3c07b
legacy json template ref
trujillo-adam Jan 24, 2025
a9ada1d
hcl template blocks
trujillo-adam Jan 27, 2025
54da4b0
hcl templates content except functions
trujillo-adam Jan 28, 2025
f86801a
Apply suggestions from code review
trujillo-adam Jan 29, 2025
f46a435
Apply suggestions from code review
trujillo-adam Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
---
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 HCP Packer.
page_title: hcp_packer_registry - build - Blocks
The `hcp_packer_registry` block configures details new or updated images in the HCP Packer registry. Learn how to configure the `hcp_packer_registry` block.
trujillo-adam marked this conversation as resolved.
Show resolved Hide resolved
page_title: hcp_packer_registry block reference
---

# The `hcp_packer_registry` block
# `hcp_packer_registry` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should match the page_title, right? So this would be:

Suggested change
# `hcp_packer_registry` block
# `hcp_packer_registry` block reference


The `hcp_packer_registry` block lets you customize the metadata Packer sends to HCP Packer Registry. It configures the details of an image that is created or updated within the HCP Packer registry.
This topic provides reference information about the `hcp_packer_registry` block.

## Description

The `hcp_packer_registry` block configures details about an image Packer creates or updates in the HCP Packer registry. Use the `hcp_packer_registry` block to customize the metadata Packer sends to HCP Packer Registry.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually really like the second sentence here — how would you feel about adding that to the description instead of "Learn how to configure the hcp_packer_registry block." which I don't feel like tells you as much?


To get started with HCP Packer, refer to the [HCP Packer documentation](/hcp/docs/packer) or try the [Get Started with HCP Packer tutorials](/packer/tutorials/hcp-get-started).

Expand Down
15 changes: 9 additions & 6 deletions website/content/docs/templates/hcl_templates/blocks/build/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
---
description: |
The source block defines what builders are started.
page_title: build - Blocks
The `build` block contains instructions for Packer to follow during a build. Learn how to configure the `build` block in your Packer templates.
page_title: build block reference
---

# The `build` block
# `build` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `build` block
# `build` block reference


`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `build` block.

The `build` block defines what builders are started, how to `provision` them
and if necessary what to do with their artifacts using `post-process`.

## Description

The `build` block specifies which builders Packer should run, how to provision them,
and any post-processing actions Packer should perform on the resulting artifacts.

To use builders in a `build` block you can either:

Expand Down
10 changes: 6 additions & 4 deletions website/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
---
description: |
The post-processor block defines how a post-processor is configured.
page_title: post-processor - build - Blocks
The `post-processor` block defines post-processor behavior after a `packer build` command. Learn how to configure `post-processor` blocks in your Packer templates.
page_title: post-processor block reference
---

# The `post-processor` block
# `post-processor` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `post-processor` block
# `post-processor` block reference


`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `post-processor` block.

## Description

The `post-processor` block defines how a post-processor is configured.

Expand Down
15 changes: 7 additions & 8 deletions website/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
---
description: >
The post-processors block allows to define lists of post-processors to apply
to an artifact.
page_title: post-processors - build - Blocks
Add the `post-processors` block to a `build` block to define a list of post-processors to apply to an artifact. Learn how to configure nested `post-processors` blocks.
page_title: post-processors block reference
---

# The `post-processors` block
# `post-processors` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `post-processors` block
# `post-processors` block reference


`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `post-processors` block.

The `post-processors` block allows to define lists of
[`post-processors`](/packer/docs/templates/hcl_templates/blocks/build/post-processor), that will run
from the artifact of each build.
## Description

Add a `post-processors` block to your `build` block to include a list of [post-processor](/packer/docs/templates/hcl_templates/blocks/build/post-processor) configurations. Packer runs the post-processors for the artifact of each build.
trujillo-adam marked this conversation as resolved.
Show resolved Hide resolved

```hcl
# builds.pkr.hcl
Expand Down
22 changes: 11 additions & 11 deletions website/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
---
description: |
The provisioner block defines how a provisioner is configured.
page_title: provisioner - build - Blocks
The `provisioner` block defines how to configure a provisioner. Learn how to configure `provisioner` blocks in your templates.
page_title: provisioner block reference
---

# The `provisioner` block
# `provisioner` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `provisioner` block
# `provisioner` block reference


`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic providers reference information about the `provisioner` block.

The `provisioner` block defines how a provisioner is configured.
## Description

The `provisioner` block defines how to configure a provisioner. Provisioners use builtin and third-party software to install and configure the
machine image after booting. Provisioners prepare the system for use.

The list of available provisioners can be found in the
[Provisioners](/packer/docs/provisioners) section.

```hcl
# builds.pkr.hcl
Expand All @@ -23,12 +29,6 @@ build {
}
```

Provisioners use builtin and third-party software to install and configure the
machine image after booting. Provisioners prepare the system for use.

The list of available provisioners can be found in the
[provisioners](/packer/docs/provisioners) section.

## Run on Specific Sources

You can use the `only` or `except` configurations to run a provisioner only
Expand Down
26 changes: 13 additions & 13 deletions website/content/docs/templates/hcl_templates/blocks/build/source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
---
description: >
A source block nested in a build block allows you to use an already defined
source and to set specific fields which aren't already set in the top-level
source block.
page_title: source - build - Blocks
A `source` block nested in a `build` block reuses a builder defined
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would you feel about using the sentence you have below instead? It feels more descriptive:

Suggested change
A `source` block nested in a `build` block reuses a builder defined
Add a nested `source` block to your `build` block to reuse a builder defined elsewhere in your configuration.

elsewhere in the configuration. Learn how to configure a nested `source` block.
page_title: source block reference
---

# The `source` block
# `source` block
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# `source` block
# `source` block reference

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll stop leaving this because I figure it'll be easier for you to do in your IDE than apply a bunch of suggestions 😅


`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about `source` blocks nested in a `build` block.

A `source` block nested in a `build` block allows you to use an already defined
source and to "fill in" those fields _which aren't already set in the top-level
source block_.
## Description

Add a `source` block to your `build` block to reuse a builder defined elsewhere in the configuration. Packer fills in the source fields that are not already set in the top-level `source` block.

Build-level source blocks are implemented by merging their contents with the
corresponding top-level source block, and a packer build will fail when it
corresponding top-level source block, and a `packer build` command fails when it
encounters the ambiguity that arises when a source parameter is defined twice.
For example, in the below example, if the top-level "lxd.arch" source block
also defined an `output_image` field (or if one of the build-level source blocks
redefined and image field), Packer would error.

For example, in the below example, if the top-level `lxd.arch` source block
also defined an `output_image` field or if one of the build-level source blocks
redefined and image field, Packer would error.

```hcl
# file: builds.pkr.hcl
Expand Down
13 changes: 5 additions & 8 deletions website/content/docs/templates/hcl_templates/blocks/data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,13 @@
---
description: >
The data block defines data sources within your Packer configuration.
page_title: data - Blocks
The `data` block defines data sources within your Packer configuration. Learn how to configure `data` blocks.
page_title: data block referenece
---

# The `data` block
# `data` block

The `data` block defines data sources within your Packer configuration.
The `data` block defines data sources within your Packer configuration. The following example instructs Packer to query the `amazon-ami` data source for information to use in the template.

`@include 'from-1.5/datasources/example-block.mdx'`

# More on data sources

- Read the [full Data Sources](/packer/docs/templates/hcl_templates/datasources) description for a more
thorough read.
Refer to [Data Sources](/packer/docs/templates/hcl_templates/datasources) for instructions about using the `data` block in your configuration.
19 changes: 9 additions & 10 deletions website/content/docs/templates/hcl_templates/blocks/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
---
page_title: Blocks - Configuration Language
description: The HCL language has a number of blocks that can be used to configure builds.
page_title: Built-in blocks overview
description: A block is a container for configuration in a Packer template. Learn about the types of configration blocks built into HCL for Packer.
---

# Built-in Blocks
# Built-in blocks overview

`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides an overview of the configuration blocks built into the Packer language that you can use to write Packer templates in HCL2.

The Packer - HCL2 language includes a number of built-in blocks that you can
use to configure builds. A block is a container for configuration.
## Introduction

The most important blocks can be broken into a couple of major types:
A block is a container for configuration. You can use the following types of blocks in your Packer templates:

- `build` blocks contain configuration for a specific combination of builders,
provisioners, and post-processors used to create a specific image artifact.
Expand All @@ -29,8 +28,8 @@ The most important blocks can be broken into a couple of major types:

The documentation contains information for each block type.

Other blocks, such as the "packer" block, provide information to the Packer core
about what version it is allowed to run. The "required_plugins" block helps the
Other blocks, such as the `packer` block, provide information to the Packer core
about what version it is allowed to run. The `required_plugins` block helps the
Packer core

Blocks can be defined in multiple files and `packer build folder` will build
Expand All @@ -39,7 +38,7 @@ using solely the files from a directory named `folder`.
Packer does not support user-defined blocks and so only the blocks built in to
the language are available for use. The documentation includes all of the available built-in HCL2 blocks.

## Config example:
## Configuration examples

`@include 'from-1.5/variables/foo-block.mdx'`

Expand Down
21 changes: 11 additions & 10 deletions website/content/docs/templates/hcl_templates/blocks/locals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
---
description: >
The locals block also called the local-variable block defines locals within
your Packer configuration.
page_title: locals - Blocks
The `locals` and `local-variable` blocks declare local variables in
your Packer configuration. Learn how to use these blocks to declare local variables in your template.
page_title: locals block reference
---

# The `locals` block
# `locals` block

`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `locals` block.

The `locals` block, also called the `local-variable` block, defines locals within
## Description

The `locals` and `local-variable` blocks declare local variables in
your Packer configuration.

`@include 'from-1.5/locals/example-block.mdx'`

# More on variables
Refer to the following topics for additional information about using the `locals` and `local-variable` blocks:

- Read the [full locals](/packer/docs/templates/hcl_templates/locals) description for a more
thorough read.
- Read the [variables guide](/packer/guides/hcl/variables) for more examples.
- [Local Variables](/packer/docs/templates/hcl_templates/locals)
- [Input Variables and local variables](/packer/guides/hcl/variables)
12 changes: 5 additions & 7 deletions website/content/docs/templates/hcl_templates/blocks/packer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
---
page_title: packer block reference
description: |-
Configuration reference for the `packer` block in Packer templates written in HCL.
The `packer` block configures Packer behavior. Learn how to configure the `packer` in Packer templates written in HCL.
---

# Packer Settings
# `packer` block

`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `packer` block.

-> **Note:** The `packer` block is only available in Packer v1.6.5 and later.
## Description

The `packer` configuration block type is used to configure some
behaviors of Packer itself, such as the minimum required Packer version needed to
apply your configuration.
The `packer` block configures Packer version requirements and specifies which plugins to install upon initialization.

## Packer Block Syntax

Expand Down
24 changes: 13 additions & 11 deletions website/content/docs/templates/hcl_templates/blocks/source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,26 @@
---
description: |
The top-level source block defines reusable builder configuration blocks
page_title: source - Blocks
The `source` block defines reusable builder configuration blocks. Learn how to define reusable builders using the `source` block.
page_title: source block reference
---

# The `source` block
# `source` block

`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic providers reference information about the `source` block.

The top-level `source` block defines reusable builder configuration blocks:
## Description

The `source` block defines reusable builder configuration blocks. Builders are commonly used in custom plugins.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `source` block defines reusable builder configuration blocks. Builders are commonly used in custom plugins.
The `source` block defines reusable builder configuration blocks, which are commonly used in custom plugins.


## Example

The following example defines a source for a builder type called `happycloud` with the name `foo`:

`@include 'from-1.5/sources/example-block.mdx'`

The first label — `happycloud` here — is the builder type. The second label is
the unique name or identifier you want to give to the source. There can be only one
`source.happycloud.foo` top-level source block; but it can be used more than
once. Builders are usually found in plugins, except for the `file` and the
`null` builders that will remain in Packer core.
There is only one `source.happycloud.foo` top-level source block, but it can be used more than once.

You can start builders by referring to those source blocks from a [`build`
You can start builders by referring to `source` blocks from a [`build`
block](/packer/docs/templates/hcl_templates/blocks/build) :

```hcl
Expand Down
16 changes: 8 additions & 8 deletions website/content/docs/templates/hcl_templates/blocks/variable.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
description: >
The variable block, also called the input-variable block, defines variables
within your Packer configuration.
page_title: variable - Blocks
The `variable` and `input-variable` blocks define variables in your Packer configuration. Learn how to use these blocks to declare variables in your template.
page_title: variable block reference
---

# The `variable` block
# `variable` block

`@include 'from-1.5/beta-hcl2-note.mdx'`
This topic provides reference information about the `variable` block.

The `variable` block, also called the `input-variable` block, defines variables
within your Packer configuration. An input-variable cannot be used in another
input variable: we recommend using [locals](/packer/docs/templates/hcl_templates/blocks/locals) for that instead.
## Description

The `variable` and `input-variable` blocks define variables
within your Packer configuration. You cannot use the `input-variable` block in another `input-variable` block. We recommend using the [`locals`](/packer/docs/templates/hcl_templates/blocks/locals) to nest variables instead.

`@include 'from-1.5/variables/foo-block.mdx'`

Expand Down
Loading