iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve Documentation for Build-level Source Block 

The docs for top-level and build-level source blocks did not make it clear enough, early enough in the page, how packer merges their contents and fails when ambiguities  arise from redefinition. I know the info it there, but it's at the end and I feel that my modification shortens the page overall while putting the most useful info front and center. 

Also, there is simply an error in the note at the end of this page, which further confuses the situation for new readers trying to use HCL and reuse source blocks. It's referring to a non-existent amazon source which is probably a past copy/paste error. 

It took me a day to get re-usable source blocks working, bc I skimmed the page at first (I know slap my wrist), but didn't really grasp what it was saying in the Note at the end, and found it confusing. It wasn't until I found the Issues and PRs related to this feature getting added last April/May that I realized how it was implemented that I started to grasp what this was saying.
This commit is contained in:
Tim Black 2021-01-27 11:12:42 -08:00 committed by GitHub
parent f36554fa0e
commit 300604675b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
website/content/docs/templates/hcl_templates/blocks/build/source.mdx vendored
View File

@ -1,7 +1,8 @@
---
description: >
A source block nested in a build block allows you to use an already defined
source and to set specific fields.
source and to set specific fields which aren't already set in the top-level
source block.
page_title: source - build - Blocks
sidebar_title: <tt>source</tt>
---
@ -10,8 +11,16 @@ sidebar_title: <tt>source</tt>
`@include 'from-1.5/beta-hcl2-note.mdx'`
A `source` block nested in a `build` block allows to use an already defined
source and to set specific fields.
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_.
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
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.
```hcl
# builds.pkr.hcl
@ -43,11 +52,3 @@ build {
}
}
```
This allows to have commonly defined source settings with specific parts of it
defined inside the specific build block.
-> **Note:** It is **not allowed** to set the same field in a top-level source
block and in a used source block. For example, if in the above example, the
top-level "amazon-ebs.example" source block also had an `output` field;
Packer would error.