Skip to content

Commit 51983bd

Browse files
lbajolet-hashicorplbajolet-hashicorp
committed
docs: add docs on project bundles
In HCL2, it is possible to split the different components of a build over several files, and to build them by invoking `packer build' on the directory containing those partial templates. This was not documented, nor was there any example in Packer to highlight such a workflow, so we add those with this commit.
1 parent 1a1fada commit 51983bd

File tree

8 files changed

+382
-0
lines changed

8 files changed

+382
-0
lines changed

‎examples/hcl/bundle/app/common_vars.pkr.hcl

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
variable "region" {
2+
type = string
3+
default = "us-east-1"
4+
}
5+
6+
variable "aws_access_key" {
7+
type = string
8+
}
9+
10+
variable "aws_secret_key" {
11+
type = string
12+
}

‎examples/hcl/bundle/app/defaults.auto.pkrvars.hcl

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
windows_user = "Administrator"
2+
windows_password = "p455WorD!"
3+
ssh-username = "ec2-user"

‎examples/hcl/bundle/app/linux_build.pkr.hcl

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
variable "ssh-username" {
2+
type = string
3+
}
4+
5+
source "amazon-ebs" "linux" {
6+
region = var.region
7+
access_key = var.aws_access_key
8+
secret_key = var.aws_secret_key
9+
10+
ami_name = "linux-app"
11+
source_ami = "ami-06e46074ae430fba6" # Amazon Linux 2023 x86-64
12+
instance_type = "t2.micro"
13+
communicator = "ssh"
14+
ssh_username = var.ssh-username
15+
ssh_timeout = "45s"
16+
}
17+
18+
build {
19+
sources = ["amazon-ebs.linux"]
20+
21+
// Other provisioners/post-processors
22+
}

‎examples/hcl/bundle/app/scripts/enable_winrm.ps

1.98 KB
Binary file not shown.

‎examples/hcl/bundle/app/windows_build.pkr.hcl

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
variable "windows_user" {
2+
type = string
3+
}
4+
5+
variable "windows_password" {
6+
type = string
7+
}
8+
9+
data "file" "user_data_file" {
10+
contents = templatefile("scripts/enable_winrm.ps", {
11+
"winrm_user" = var.windows_user,
12+
"winrm_password" = var.windows_password,
13+
})
14+
destination = "enable_winrm"
15+
force = true
16+
}
17+
18+
source "amazon-ebs" "windows" {
19+
region = var.region
20+
access_key = var.aws_access_key
21+
secret_key = var.aws_secret_key
22+
23+
ami_name = "windows-app"
24+
source_ami = "ami-00b2c40b15619f518" # Windows server 2016 base x86_64
25+
instance_type = "m3.medium"
26+
communicator = "winrm"
27+
winrm_username = var.windows_user
28+
winrm_password = var.windows_password
29+
user_data_file = data.file.user_data_file.path
30+
}
31+
32+
build {
33+
sources = ["amazon-ebs.windows"]
34+
35+
provisioner "powershell" {
36+
inline = [
37+
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/InitializeInstance.ps1 -Schedule",
38+
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/SysprepInstance.ps1 -NoShutdown"
39+
]
40+
}
41+
42+
// Other provisioners/post-processors
43+
}

‎examples/hcl/bundle/enable_winrm

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<powershell>
2+
# Set administrator password
3+
net user Administrator p455WorD!
4+
wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE
5+
6+
# First, make sure WinRM can't be connected to
7+
netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new enable=yes action=block
8+
9+
# Delete any existing WinRM listeners
10+
winrm delete winrm/config/listener?Address=*+Transport=HTTP 2>$Null
11+
winrm delete winrm/config/listener?Address=*+Transport=HTTPS 2>$Null
12+
13+
# Disable group policies which block basic authentication and unencrypted login
14+
15+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Client -Name AllowBasic -Value 1
16+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Client -Name AllowUnencryptedTraffic -Value 1
17+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Service -Name AllowBasic -Value 1
18+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Service -Name AllowUnencryptedTraffic -Value 1
19+
20+
21+
# Create a new WinRM listener and configure
22+
winrm create winrm/config/listener?Address=*+Transport=HTTP
23+
winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="0"}'
24+
winrm set winrm/config '@{MaxTimeoutms="7200000"}'
25+
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
26+
winrm set winrm/config/service '@{MaxConcurrentOperationsPerUser="12000"}'
27+
winrm set winrm/config/service/auth '@{Basic="true"}'
28+
winrm set winrm/config/client/auth '@{Basic="true"}'
29+
30+
# Configure UAC to allow privilege elevation in remote shells
31+
$Key = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'
32+
$Setting = 'LocalAccountTokenFilterPolicy'
33+
Set-ItemProperty -Path $Key -Name $Setting -Value 1 -Force
34+
35+
# Configure and restart the WinRM Service; Enable the required firewall exception
36+
Stop-Service -Name WinRM
37+
Set-Service -Name WinRM -StartupType Automatic
38+
netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new action=allow localip=any remoteip=any
39+
Start-Service -Name WinRM
40+
</powershell>

‎website/content/docs/templates/hcl_templates/project-bundles.mdx

+258
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
page_title: HCL2 Project Bundles
3+
description: |-
4+
Packer templates written in HCL2 may be defined under a single file, or
5+
as a series of template partials stored in a single directory.
6+
This document aims to explain how Packer works in such cases, and how
7+
users may define their templates as a series of partials rather than a
8+
single HCL2 template.
9+
---
10+
11+
# HCL2 Project Bundles
12+
13+
`@include 'from-1.5/beta-hcl2-note.mdx'`
14+
15+
Packer users coming from the Legacy JSON templates may be used to define a series of
16+
builds from a single template.
17+
While HCL2 also supports workflows like these, due to the way Packer parses templates
18+
in HCL2 mode, it also supports splitting the template in multiple files, and
19+
using them to trigger concurrent builds.
20+
21+
## Project Bundle
22+
23+
A project bundle is a directory containing multiple `.pkr.hcl` or `.pkrvars.hcl` files
24+
which can be loaded by Packer for building a bundle of images from these partially
25+
defined templates.
26+
27+
-> **Note:** You cannot mix-in HCL2 and JSON templates, loading templates from a directory is
28+
only supported on HCL2 templates.
29+
30+
Any supported HCL2 template component may be defined in partial templates.
31+
For example, you may want to define the variables you are going to use in a file,
32+
and use them directly from the other partial templates defined in the directory you
33+
want to build.
34+
35+
To make reasoning about separate builds easier, you may also split your templates into
36+
multiple files, one per family of builds.
37+
38+
For example, assume we are building multiple images for a specific environment,
39+
and we want to segregate those builds by OS familiy.
40+
41+
You could partition the bundle like so:
42+
43+
```shell
44+
.
45+
└── app
46+
├── common_vars.pkr.hcl
47+
├── defaults.auto.pkrvars.hcl
48+
├── linux_build.pkr.hcl
49+
├── scripts
50+
│   └── enable_winrm.ps
51+
└── windows_build.pkr.hcl
52+
```
53+
54+
<Tabs>
55+
<Tab heading="common_vars.pkr.hcl">
56+
57+
```hcl
58+
variable "region" {
59+
type = string
60+
default = "us-east-1"
61+
}
62+
63+
variable "aws_access_key" {
64+
type = string
65+
}
66+
67+
variable "aws_secret_key" {
68+
type = string
69+
}
70+
```
71+
72+
</Tab>
73+
74+
<Tab heading="windows_build.pkr.hcl">
75+
76+
```hcl
77+
variable "windows_user" {
78+
type = string
79+
}
80+
81+
variable "windows_password" {
82+
type = string
83+
}
84+
85+
data "file" "user_data_file" {
86+
contents = templatefile("scripts/enable_winrm.ps", {
87+
"winrm_user" = var.windows_user,
88+
"winrm_password" = var.windows_password,
89+
})
90+
destination = "enable_winrm"
91+
force = true
92+
}
93+
94+
source "amazon-ebs" "windows" {
95+
region = var.region
96+
access_key = var.aws_access_key
97+
secret_key = var.aws_secret_key
98+
99+
ami_name = "windows-app"
100+
source_ami = "ami-00b2c40b15619f518" # Windows server 2016 base x86_64
101+
instance_type = "m3.medium"
102+
communicator = "winrm"
103+
winrm_username = var.windows_user
104+
winrm_password = var.windows_password
105+
user_data_file = data.file.user_data_file.path
106+
}
107+
108+
build {
109+
sources = ["amazon-ebs.windows"]
110+
111+
provisioner "powershell" {
112+
inline = [
113+
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/InitializeInstance.ps1 -Schedule",
114+
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/SysprepInstance.ps1 -NoShutdown"
115+
]
116+
}
117+
118+
// Other provisioners/post-processors
119+
}
120+
```
121+
122+
</Tab>
123+
<Tab heading="linux_build.pkr.hcl">
124+
125+
```hcl
126+
variable "ssh-username" {
127+
type = string
128+
}
129+
130+
source "amazon-ebs" "linux" {
131+
region = var.region
132+
access_key = var.aws_access_key
133+
secret_key = var.aws_secret_key
134+
135+
ami_name = "linux-app"
136+
source_ami = "ami-06e46074ae430fba6" # Amazon Linux 2023 x86-64
137+
instance_type = "t2.micro"
138+
communicator = "ssh"
139+
ssh_username = var.ssh-username
140+
ssh_timeout = "45s"
141+
}
142+
143+
build {
144+
sources = ["amazon-ebs.linux"]
145+
146+
// Other provisioners/post-processors
147+
}
148+
```
149+
150+
</Tab>
151+
<Tab heading="default.auto.pkrvars.hcl">
152+
153+
```hcl
154+
windows_user = "Administrator"
155+
windows_password = "p455WorD!"
156+
ssh-username = "ec2-user"
157+
```
158+
159+
</Tab>
160+
161+
<Tab heading="enable_winrm.ps">
162+
163+
```powershell
164+
<powershell>
165+
# Set administrator password
166+
net user ${winrm_user} ${winrm_password}
167+
wmic useraccount where "name='${winrm_user}'" set PasswordExpires=FALSE
168+
169+
# First, make sure WinRM can't be connected to
170+
netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new enable=yes action=block
171+
172+
# Delete any existing WinRM listeners
173+
winrm delete winrm/config/listener?Address=*+Transport=HTTP 2>$Null
174+
winrm delete winrm/config/listener?Address=*+Transport=HTTPS 2>$Null
175+
176+
# Disable group policies which block basic authentication and unencrypted login
177+
178+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Client -Name AllowBasic -Value 1
179+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Client -Name AllowUnencryptedTraffic -Value 1
180+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Service -Name AllowBasic -Value 1
181+
Set-ItemProperty -Path HKLM:\Software\Policies\Microsoft\Windows\WinRM\Service -Name AllowUnencryptedTraffic -Value 1
182+
183+
184+
# Create a new WinRM listener and configure
185+
winrm create winrm/config/listener?Address=*+Transport=HTTP
186+
winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="0"}'
187+
winrm set winrm/config '@{MaxTimeoutms="7200000"}'
188+
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
189+
winrm set winrm/config/service '@{MaxConcurrentOperationsPerUser="12000"}'
190+
winrm set winrm/config/service/auth '@{Basic="true"}'
191+
winrm set winrm/config/client/auth '@{Basic="true"}'
192+
193+
# Configure UAC to allow privilege elevation in remote shells
194+
$Key = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'
195+
$Setting = 'LocalAccountTokenFilterPolicy'
196+
Set-ItemProperty -Path $Key -Name $Setting -Value 1 -Force
197+
198+
# Configure and restart the WinRM Service; Enable the required firewall exception
199+
Stop-Service -Name WinRM
200+
Set-Service -Name WinRM -StartupType Automatic
201+
netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new action=allow localip=any remoteip=any
202+
Start-Service -Name WinRM
203+
</powershell>
204+
```
205+
206+
</Tab>
207+
</Tabs>
208+
209+
In this example hierarchy, each file describes the following:
210+
211+
* `windows_build.pkr.hcl`: the build blocks and sources related to Windows, having a separate build block and provisioners/post-processors may make sense since Windows behaves very differently from *NIX OSes
212+
* `linux_build.pkr.hcl`: the build blocks and sources related to Linux
213+
* `variables.pkr.hcl`: the variables required to build the images. For example if you are building images on AWS, you can specify variables used in both templates here, along with their default values if relevant.
214+
* `defaults.pkrvars.hcl`: the default values for the variables defined in `variables.pkr.hcl`.
215+
* `scripts/enable_winrm.ps`: a simple script to enable winrm and create an Administrator user and password for winrm authentication.
216+
217+
Building the whole bundle at once is done by invoking `packer build` on the whole directory: `packer build app`.
218+
219+
If you want to build the windows or linux builds separately, you can do so by using the `--only` or `--except` flags:
220+
221+
<Tabs>
222+
223+
<Tab heading="build_all">
224+
225+
```shell
226+
$ packer build \
227+
--variable "aws_access_key=AKIAIOSFODNN7EXAMPLE" \
228+
--variable "aws_secret_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
229+
app
230+
```
231+
232+
</Tab>
233+
234+
<Tab heading="build_linux_only">
235+
236+
```shell
237+
$ packer build \
238+
--variable "aws_access_key=AKIAIOSFODNN7EXAMPLE" \
239+
--variable "aws_secret_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
240+
--only 'amazon-ebs.linux' \
241+
app
242+
```
243+
244+
</Tab>
245+
246+
<Tab heading="build_windows_only">
247+
248+
```shell
249+
$ packer build \
250+
--variable "aws_access_key=AKIAIOSFODNN7EXAMPLE" \
251+
--variable "aws_secret_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
252+
--only 'amazon-ebs.windows' \
253+
app
254+
```
255+
256+
</Tab>
257+
258+
</Tabs>

‎website/data/docs-nav-data.json

+4
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,10 @@
111111
"title": "Overview",
112112
"path": "templates/hcl_templates"
113113
},
114+
{
115+
"title": "Project Bundles",
116+
"path": "templates/hcl_templates/project-bundles"
117+
},
114118
{
115119
"title": "Blocks",
116120
"routes": [

0 commit comments

Comments
 (0)