From 9daabf3b12de6b4eb679f60d183c485ac113c003 Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 12:27:28 +0100 Subject: [PATCH 01/13] Fix some typo's; Fix markdown and formatting --- .../intro/getting-started/build-image.html.md | 98 ++++++++++--------- 1 file changed, 51 insertions(+), 47 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 23f60252d..b7101dc82 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -12,7 +12,7 @@ description: |- # Build an Image With Packer installed, let's just dive right into it and build our first image. -Our first image will be an [Amazon EC2 AMI](https://aws.amazon.com/ec2/) +Our first image will be an [Amazon EC2 AMI](https://aws.amazon.com/ec2/). This is just an example. Packer can create images for [many platforms][platforms]. If you don't have an AWS account, [create one now](https://aws.amazon.com/free/). @@ -160,7 +160,7 @@ typically represent an ID (such as in the case of an AMI) or a set of files (such as for a VMware virtual machine). In this example, we only have a single artifact: the AMI in us-east-1 that was created. -This AMI is ready to use. If you wanted you could go and launch this AMI right +This AMI is ready to use. If you wanted you could go and launch this AMI right now and it would work great. -> **Note:** Your AMI ID will surely be different than the one above. If you @@ -203,18 +203,21 @@ how to validate and build templates into machine images. ### Another Linux Example, with provisioners: Create a file named `welcome.txt` and add the following: + ``` WELCOME TO PACKER! ``` Create a file named `example.sh` and add the following: -``` + +```bash #!/bin/bash -echo "hello +echo "hello" ``` -Set your access key and id as environment variables, so we don't need to pass +Set your access key and id as environment variables, so we don't need to pass them in through the command line: + ``` export AWS_ACCESS_KEY_ID=MYACCESSKEYID export AWS_SECRET_ACCESS_KEY=MYSECRETACCESSKEY @@ -222,7 +225,7 @@ export AWS_SECRET_ACCESS_KEY=MYSECRETACCESSKEY Now save the following text in a file named `firstrun.json`: -``` +```json { "variables": { "aws_access_key": "{{env `AWS_ACCESS_KEY_ID`}}", @@ -272,10 +275,10 @@ Now save the following text in a file named `firstrun.json`: and to build, run `packer build firstrun.json` -Note that if you wanted to use a `source_ami` instead of a `source_ami_filter` +Note that if you wanted to use a `source_ami` instead of a `source_ami_filter` it might look something like this: `"source_ami": "ami-fce3c696",` -Your output will look like this: +Your output will look like this: ``` amazon-ebs output will be in this color. @@ -314,16 +317,16 @@ amazon-ebs output will be in this color. ==> amazon-ebs: Waiting for AMI to become ready... ``` -### A windows example +### A Windows Example -Note that this uses a larger instance. You will be charged for it. Also keep -in mind that using windows AMIs incurs a fee that you don't get when you use +Note that this uses a larger instance. You will be charged for it. Also keep +in mind that using windows AMIs incurs a fee that you don't get when you use linux AMIs. -You'll need to have a boostrapping file to enable ssh or winrm; here's a basic +You'll need to have a boostrapping file to enable ssh or winrm; here's a basic example of that file. -``` +```powershell # set administrator password net user Administrator SuperS3cr3t! wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE @@ -353,16 +356,16 @@ net start winrm ``` -Save the above code in a file named `bootstrap_win.txt`. +Save the above code in a file named `bootstrap_win.txt`. -The example config below shows the two different ways of using the powershell -provisioner: `inline` and `script`. -The first example, `inline`, allows you to provide short snippets of code, and -will create the script file for you. The second example allows you to run more -complex code by providing the path to a script to run on the guest vm. +The example config below shows the two different ways of using the powershell +provisioner: `inline` and `script`. +The first example, `inline`, allows you to provide short snippets of code, and +will create the script file for you. The second example allows you to run more +complex code by providing the path to a script to run on the guest vm. -Here's an example of a `sample_script.ps1` that will work with the environment -variables we will set in our packer config; copy the contents into your own +Here's an example of a `sample_script.ps1` that will work with the environment +variables we will set in our packer config; copy the contents into your own `sample_script.ps1` and provide the path to it in your packer config: ``` @@ -375,39 +378,40 @@ Write-Output("Likewise, VAR2 is " + $Env:VAR2 ) Write-Output("and VAR3 is " + $Env:VAR3 ) ``` -Next you need to create a packer config that will use this bootstrap file. See -the example below, which contains examples of using source_ami_filter for +Next you need to create a packer config that will use this bootstrap file. See +the example below, which contains examples of using source_ami_filter for windows in addition to the powershell and windows-restart provisioners: -``` +```json { "variables": { - "aws_access_key": "{{env `AWS_ACCESS_KEY_ID`}}", - "aws_secret_key": "{{env `AWS_SECRET_ACCESS_KEY`}}", - "region": "us-east-1" + "aws_access_key": "{{env `AWS_ACCESS_KEY_ID`}}", + "aws_secret_key": "{{env `AWS_SECRET_ACCESS_KEY`}}", + "region": "us-east-1" }, "builders": [ - { - "type": "amazon-ebs", - "access_key": "{{ user `aws_access_key` }}", - "secret_key": "{{ user `aws_secret_key` }}", - "region": "us-east-1", - "instance_type": "m3.medium", - "source_ami_filter": { - "filters": { - "virtualization-type": "hvm", - "name": "*WindowsServer2012R2*", - "root-device-type": "ebs" + { + "type": "amazon-ebs", + "access_key": "{{ user `aws_access_key` }}", + "secret_key": "{{ user `aws_secret_key` }}", + "region": "us-east-1", + "instance_type": "m3.medium", + "source_ami_filter": { + "filters": { + "virtualization-type": "hvm", + "name": "*WindowsServer2012R2*", + "root-device-type": "ebs" + }, + "most_recent": true, + "owners": "amazon" }, - "most_recent": true, - "owners": "amazon" - }, - "ami_name": "packer-demo-{{timestamp}}", - "user_data_file": "./bootstrap_win.txt", - "communicator": "winrm", - "winrm_username": "Administrator", - "winrm_password": "SuperS3cr3t!" - }], + "ami_name": "packer-demo-{{timestamp}}", + "user_data_file": "./bootstrap_win.txt", + "communicator": "winrm", + "winrm_username": "Administrator", + "winrm_password": "SuperS3cr3t!" + } + ], "provisioners": [ { "type": "powershell", From 1b8238e35fbaffbadd623b7f5376e1cf931eb052 Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 13:29:50 +0100 Subject: [PATCH 02/13] Fix missing powershell tags around User Data script --- website/source/intro/getting-started/build-image.html.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index b7101dc82..f0ce6f200 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -327,6 +327,7 @@ You'll need to have a boostrapping file to enable ssh or winrm; here's a basic example of that file. ```powershell + # set administrator password net user Administrator SuperS3cr3t! wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE @@ -353,6 +354,7 @@ set-service winrm -startupType automatic # Finally, allow WinRM connections and start the service netsh advfirewall firewall set rule name="WinRM" new action=allow net start winrm + ``` From ed0a60bd61531c1c83ec778de32482522cea91f7 Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 14:02:59 +0100 Subject: [PATCH 03/13] Fix quotes. Use Write-Host in preference to Write-Output --- .../intro/getting-started/build-image.html.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index f0ce6f200..738dd907d 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -370,14 +370,15 @@ Here's an example of a `sample_script.ps1` that will work with the environment variables we will set in our packer config; copy the contents into your own `sample_script.ps1` and provide the path to it in your packer config: -``` -Write-Output("PACKER_BUILD_NAME is automatically set for you,) -Write-Output("or you can set it in your builder variables; ) -Write-Output("the default for this builder is: " + $Env:PACKER_BUILD_NAME ) -Write-Output("Remember that escaping variables in powershell requires backticks: ) -Write-Output("for example, VAR1 from our config is " + $Env:VAR1 ) -Write-Output("Likewise, VAR2 is " + $Env:VAR2 ) -Write-Output("and VAR3 is " + $Env:VAR3 ) +```powershell +Write-Host "PACKER_BUILD_NAME is automatically set for you, " -NoNewline +Write-Host "or you can set it in your builder variables; " -NoNewline +Write-Host "The default for this builder is:" $Env:PACKER_BUILD_NAME + +Write-Host "Use backticks as the escape character when required in powershell:" +Write-Host "For example, VAR1 from our config is:" $Env:VAR1 +Write-Host "Likewise, VAR2 is:" $Env:VAR2 +Write-Host "Finally, VAR3 is:" $Env:VAR3 ``` Next you need to create a packer config that will use this bootstrap file. See @@ -418,7 +419,7 @@ windows in addition to the powershell and windows-restart provisioners: { "type": "powershell", "environment_vars": ["DEVOPS_LIFE_IMPROVER=PACKER"], - "inline": "Write-Output(\"HELLO NEW USER; WELCOME TO $Env:DEVOPS_LIFE_IMPROVER\")" + "inline": "Write-Host \"HELLO NEW USER; WELCOME TO $Env:DEVOPS_LIFE_IMPROVER\"" }, { "type": "windows-restart" From e4985ae6f6b3c4e801e957332f99382909a5947b Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 20:55:12 +0100 Subject: [PATCH 04/13] Set to use a basic Windows source AMI that qualifies for free tier usage --- .../intro/getting-started/build-image.html.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 738dd907d..943f81572 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -319,11 +319,17 @@ amazon-ebs output will be in this color. ### A Windows Example -Note that this uses a larger instance. You will be charged for it. Also keep -in mind that using windows AMIs incurs a fee that you don't get when you use -linux AMIs. +As with the Linux example above, should you decide to follow along and +build an AMI from the example template, provided you qualify for free tier +usage, you should not be charged for actually building the AMI. +However, please note that you will be charged for storage of the snapshot +associated with any AMI that you create. +If you wish to avoid further charges, follow the steps in the [Managing the +Image](/intro/getting-started/build-image.html#managing-the-image) section +above to deregister the created AMI and delete the associated snapshot once +you're done. -You'll need to have a boostrapping file to enable ssh or winrm; here's a basic +You'll need to have a bootstrapping file to enable ssh or winrm; here's a basic example of that file. ```powershell @@ -398,11 +404,11 @@ windows in addition to the powershell and windows-restart provisioners: "access_key": "{{ user `aws_access_key` }}", "secret_key": "{{ user `aws_secret_key` }}", "region": "us-east-1", - "instance_type": "m3.medium", + "instance_type": "t2.micro", "source_ami_filter": { "filters": { "virtualization-type": "hvm", - "name": "*WindowsServer2012R2*", + "name": "*Windows_Server-2012-R2*English-64Bit-Base*", "root-device-type": "ebs" }, "most_recent": true, From dc45bd381c3b7a8d05f8a9f560d80c7c10d96ead Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 21:07:33 +0100 Subject: [PATCH 05/13] Manually set up all required for remote management. Use in-built FW rules Use of 'winrm quickconfig' can sometimes cause the Packer build to fail shortly after the WinRM connection is established. * When executed the 'winrm quickconfig -q' command configures the firewall to allow management messages to be sent over HTTP (port 5985) * This undoes the previous command in the script that configured the firewall to prevent this access. * The upshot is that the system is configured and ready to accept WinRM connections earlier than intended. * If Packer establishes its WinRM connection immediately after execution of the 'winrm quickconfig -q' command, the later commands within the script that restart the WinRM service cause the established connection, and consequently, the overall build to fail. --- .../intro/getting-started/build-image.html.md | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 943f81572..6caf355cd 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -334,19 +334,22 @@ example of that file. ```powershell -# set administrator password +# Set administrator password net user Administrator SuperS3cr3t! wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE -# First, make sure WinRM doesn't run and can't be connected to -netsh advfirewall firewall add rule name="WinRM" protocol=TCP dir=in localport=5985 action=block -net stop winrm - -# turn off PowerShell execution policy restrictions +# Turn off PowerShell execution policy restrictions Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope LocalMachine -# configure WinRM -winrm quickconfig -q +# First, make sure WinRM can't be connected to +netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new enable=yes action=block + +# Delete any existing WinRM listeners +winrm delete winrm/config/listener?Address=*+Transport=HTTP 2>$Null +winrm delete winrm/config/listener?Address=*+Transport=HTTPS 2>$Null + +# Create a new WinRM listener and configure +winrm create winrm/config/listener?Address=*+Transport=HTTP winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="0"}' winrm set winrm/config '@{MaxTimeoutms="7200000"}' winrm set winrm/config/service '@{AllowUnencrypted="true"}' @@ -354,12 +357,16 @@ winrm set winrm/config/service '@{MaxConcurrentOperationsPerUser="12000"}' winrm set winrm/config/service/auth '@{Basic="true"}' winrm set winrm/config/client/auth '@{Basic="true"}' -net stop winrm -set-service winrm -startupType automatic +# Configure UAC to allow privilege elevation in remote shells +$Key = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' +$Setting = 'LocalAccountTokenFilterPolicy' +Set-ItemProperty -Path $Key -Name $Setting -Value 1 -Force -# Finally, allow WinRM connections and start the service -netsh advfirewall firewall set rule name="WinRM" new action=allow -net start winrm +# Configure and restart the WinRM Service; Enable the required firewall exception +Stop-Service -Name WinRM +Set-Service -Name WinRM -StartupType Automatic +netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new action=allow localip=any remoteip=any +Start-Service -Name WinRM ``` From 5eb68e0573b88f186d17ab1533725a970e404be1 Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 21:48:48 +0100 Subject: [PATCH 06/13] GNU to make a happy RMS --- website/source/intro/getting-started/build-image.html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 6caf355cd..25aa7a577 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -201,7 +201,7 @@ how to validate and build templates into machine images. ## Some more examples: -### Another Linux Example, with provisioners: +### Another GNU/Linux Example, with provisioners: Create a file named `welcome.txt` and add the following: ``` @@ -319,7 +319,7 @@ amazon-ebs output will be in this color. ### A Windows Example -As with the Linux example above, should you decide to follow along and +As with the GNU/Linux example above, should you decide to follow along and build an AMI from the example template, provided you qualify for free tier usage, you should not be charged for actually building the AMI. However, please note that you will be charged for storage of the snapshot From 10af3770c756a2a6f6bd6ca0af28e2449f09d27f Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 23:42:52 +0100 Subject: [PATCH 07/13] New sample output to match changes --- .../intro/getting-started/build-image.html.md | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 25aa7a577..bf8a70637 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -457,38 +457,39 @@ You should see output like this: ``` amazon-ebs output will be in this color. -==> amazon-ebs: Prevalidating AMI Name: packer-demo-1507234504 - amazon-ebs: Found Image ID: ami-d79776ad -==> amazon-ebs: Creating temporary keypair: packer_59d692c8-81f9-6a15-2502-0ca730980bed -==> amazon-ebs: Creating temporary security group for this instance: packer_59d692f0-dd01-6879-d8f8-7765327f5365 -==> amazon-ebs: Authorizing access to port 5985 on the temporary security group... +==> amazon-ebs: Prevalidating AMI Name: packer-demo-1507933843 + amazon-ebs: Found Image ID: ami-23d93c59 +==> amazon-ebs: Creating temporary keypair: packer_59e13e94-203a-1bca-5327-bebf0d5ad15a +==> amazon-ebs: Creating temporary security group for this instance: packer_59e13ea9-3220-8dab-29c0-ed7f71e221a1 +==> amazon-ebs: Authorizing access to port 5985 from 0.0.0.0/0 in the temporary security group... ==> amazon-ebs: Launching a source AWS instance... ==> amazon-ebs: Adding tags to source instance amazon-ebs: Adding tag: "Name": "Packer Builder" - amazon-ebs: Instance ID: i-04467596029d0a2ff -==> amazon-ebs: Waiting for instance (i-04467596029d0a2ff) to become ready... + amazon-ebs: Instance ID: i-0349406ac85f02166 +==> amazon-ebs: Waiting for instance (i-0349406ac85f02166) to become ready... ==> amazon-ebs: Skipping waiting for password since WinRM password set... ==> amazon-ebs: Waiting for WinRM to become available... amazon-ebs: WinRM connected. ==> amazon-ebs: Connected to WinRM! ==> amazon-ebs: Provisioning with Powershell... -==> amazon-ebs: Provisioning with powershell script: /var/folders/8t/0yb5q0_x6mb2jldqq_vjn3lr0000gn/T/packer-powershell-provisioner079851514 +==> amazon-ebs: Provisioning with powershell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner175214995 amazon-ebs: HELLO NEW USER; WELCOME TO PACKER ==> amazon-ebs: Restarting Machine ==> amazon-ebs: Waiting for machine to restart... - amazon-ebs: WIN-164614OO21O restarted. + amazon-ebs: WIN-TEM0TDL751M restarted. ==> amazon-ebs: Machine successfully restarted, moving on ==> amazon-ebs: Provisioning with Powershell... -==> amazon-ebs: Provisioning with powershell script: ./scripts/sample_script.ps1 - amazon-ebs: PACKER_BUILD_NAME is automatically set for you, or you can set it in your builder variables; the default for this builder is: amazon-ebs - amazon-ebs: Remember that escaping variables in powershell requires backticks; for example VAR1 from our config is A$Dollar - amazon-ebs: Likewise, VAR2 is A`Backtick - amazon-ebs: and VAR3 is A'SingleQuote +==> amazon-ebs: Provisioning with powershell script: ./sample_script.ps1 + amazon-ebs: PACKER_BUILD_NAME is automatically set for you, or you can set it in your builder variables; The default for this builder is: amazon-ebs + amazon-ebs: Use backticks as the escape character when required in powershell: + amazon-ebs: For example, VAR1 from our config is: A$Dollar + amazon-ebs: Likewise, VAR2 is: A`Backtick + amazon-ebs: Finally, VAR3 is: A'SingleQuote ==> amazon-ebs: Stopping the source instance... amazon-ebs: Stopping instance, attempt 1 ==> amazon-ebs: Waiting for the instance to stop... -==> amazon-ebs: Creating the AMI: packer-demo-1507234504 - amazon-ebs: AMI: ami-2970b753 +==> amazon-ebs: Creating the AMI: packer-demo-1507933843 + amazon-ebs: AMI: ami-100fc56a ==> amazon-ebs: Waiting for AMI to become ready... ==> amazon-ebs: Terminating the source AWS instance... ==> amazon-ebs: Cleaning up any extra volumes... @@ -499,7 +500,7 @@ Build 'amazon-ebs' finished. ==> Builds finished. The artifacts of successful builds are: --> amazon-ebs: AMIs were created: -us-east-1: ami-2970b753 +us-east-1: ami-100fc56a ``` And if you navigate to your EC2 dashboard you should see your shiny new AMI. From e1d88ffaabda2fb2df3a4748f4326b41a3348964 Mon Sep 17 00:00:00 2001 From: DanHam Date: Fri, 13 Oct 2017 23:48:39 +0100 Subject: [PATCH 08/13] Export of AWS creds for users who skipped over the GNU/Linux example --- website/source/intro/getting-started/build-image.html.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index bf8a70637..550dbefe7 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -450,6 +450,14 @@ windows in addition to the powershell and windows-restart provisioners: } ``` +Set your access key and id as environment variables, so we don't need to pass +them in through the command line: + +``` +export AWS_ACCESS_KEY_ID=MYACCESSKEYID +export AWS_SECRET_ACCESS_KEY=MYSECRETACCESSKEY +``` + Then `packer build firstrun.json` You should see output like this: From 6d4e8ab583acf96cd05610ccf52282601fef0cbd Mon Sep 17 00:00:00 2001 From: DanHam Date: Sat, 14 Oct 2017 01:29:49 +0100 Subject: [PATCH 09/13] Suggest Windows 2008 and 2016 and add name filter --- .../intro/getting-started/build-image.html.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 550dbefe7..7d897d05d 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -513,5 +513,25 @@ us-east-1: ami-100fc56a And if you navigate to your EC2 dashboard you should see your shiny new AMI. +Why stop there though? + +As you'll see, with one simple change to the template above, it's +just as easy to create your own Windows 2008 or Windows 2016 AMIs. Just +set the value for the name field within `source_ami_filter` as required: + +For Windows 2008 SP2: + +``` + "name": "*Windows_Server-2008-SP2*English-64Bit-Base*", +``` + +For Windows 2016: + +``` + "name": "*Windows_Server-2016-English-Full-Base*", +``` + +The bootstrapping and sample provisioning should work the same across all +Windows server versions. [platforms]: /docs/builders/index.html From 69393ef9bba2aa751c8e31ff2946a27fa3bdc3b0 Mon Sep 17 00:00:00 2001 From: DanHam Date: Sat, 14 Oct 2017 01:49:50 +0100 Subject: [PATCH 10/13] No need to set execution policy. AWS default is unrestricted --- website/source/intro/getting-started/build-image.html.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 7d897d05d..38c3bf301 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -338,9 +338,6 @@ example of that file. net user Administrator SuperS3cr3t! wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE -# Turn off PowerShell execution policy restrictions -Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope LocalMachine - # First, make sure WinRM can't be connected to netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new enable=yes action=block From 400f210dc2d94083414845291dd6d2a6a2150fba Mon Sep 17 00:00:00 2001 From: DanHam Date: Sat, 14 Oct 2017 02:07:58 +0100 Subject: [PATCH 11/13] Set region to use user configured variable --- website/source/intro/getting-started/build-image.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 38c3bf301..647946c6b 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -407,7 +407,7 @@ windows in addition to the powershell and windows-restart provisioners: "type": "amazon-ebs", "access_key": "{{ user `aws_access_key` }}", "secret_key": "{{ user `aws_secret_key` }}", - "region": "us-east-1", + "region": "{{ user `region` }}", "instance_type": "t2.micro", "source_ami_filter": { "filters": { From 26319ee74be61361a76d5a7680854c7faacaf247 Mon Sep 17 00:00:00 2001 From: DanHam Date: Sun, 15 Oct 2017 23:50:59 +0100 Subject: [PATCH 12/13] Additional explanations possibly needed by a user new to Packer or AWS --- .../intro/getting-started/build-image.html.md | 95 ++++++++++++++++--- 1 file changed, 80 insertions(+), 15 deletions(-) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 647946c6b..2cdddf544 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -329,8 +329,47 @@ Image](/intro/getting-started/build-image.html#managing-the-image) section above to deregister the created AMI and delete the associated snapshot once you're done. -You'll need to have a bootstrapping file to enable ssh or winrm; here's a basic -example of that file. +Again, in this example, we are making use of an existing AMI available from +the Amazon marketplace as the *source* or starting point for building our +own AMI. In brief, Packer will spin up the source AMI, connect to it and then +run whatever commands or scripts we've configured in our build template to +customize the image. Finally, when all is done, Packer will wrap the whole +customized package up into a brand new AMI that will be available from the +[AWS AMI management page]( +https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Images). Any +instances we subsequently create from this AMI will have our all of our +customizations baked in. This is the core benefit we are looking to +achieve from using the [Amazon EBS builder](/docs/builders/amazon-ebs.html) +in this example. + +Now, all this sounds simple enough right? Well, actually it turns out we +need to put in just a *bit* more effort to get things working as we'd like... + +Here's the issue: Out of the box, the instance created from our source AMI +is not configured to allow Packer to connect to it. So how do we fix it so +that Packer can connect in and customize our instance? + +Well, it turns out that Amazon provides a mechanism that allows us to run a +set of *pre-supplied* commands within the instance shortly after the instance +starts. Even better, Packer is aware of this mechanism. This gives us the +ability to supply Packer with the commands required to configure the instance +for a remote connection *in advance*. Once the commands are run, Packer +will be able to connect directly in to the instance and make the +customizations we need. + +Here's a basic example of a file that will configure the instance to allow +Packer to connect in over WinRM. As you will see, we will tell Packer about +our intentions by referencing this file and the commands within it from +within the `"builders"` section of our +[build template](/docs/templates/index.html) that we will create later. + +Note the `` and `` tags at the top and bottom of +the file. These tags tell Amazon we'd like to run the enclosed code with +PowerShell. You can also use `` tags to enclose any commands +that you would normally run in a Command Prompt window. See +[Running Commands on Your Windows Instance at Launch]( +http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-windows-user-data.html) +for more info about what's going on behind the scenes here. ```powershell @@ -367,18 +406,22 @@ Start-Service -Name WinRM ``` - Save the above code in a file named `bootstrap_win.txt`. -The example config below shows the two different ways of using the powershell -provisioner: `inline` and `script`. +Now we've got the business of getting Packer connected to our instance +taken care of, let's get on with the *real* reason we're doing all this, +which is actually configuring and customizing the instance. Again, we do this +with [Provisioners](/docs/provisioners/index.html). + +The example config below shows the two different ways of using the [PowerShell +provisioner](/docs/provisioners/powershell.html): `inline` and `script`. The first example, `inline`, allows you to provide short snippets of code, and will create the script file for you. The second example allows you to run more -complex code by providing the path to a script to run on the guest vm. +complex code by providing the path to a script to run on the guest VM. Here's an example of a `sample_script.ps1` that will work with the environment -variables we will set in our packer config; copy the contents into your own -`sample_script.ps1` and provide the path to it in your packer config: +variables we will set in our build template; copy the contents into your own +`sample_script.ps1` and provide the path to it in your build template: ```powershell Write-Host "PACKER_BUILD_NAME is automatically set for you, " -NoNewline @@ -391,9 +434,27 @@ Write-Host "Likewise, VAR2 is:" $Env:VAR2 Write-Host "Finally, VAR3 is:" $Env:VAR3 ``` -Next you need to create a packer config that will use this bootstrap file. See -the example below, which contains examples of using source_ami_filter for -windows in addition to the powershell and windows-restart provisioners: +Finally, we need to create the actual [build template]( +/docs/templates/index.html). +Remember, this template is the core configuration file that Packer uses to +understand what you want to build, and how you want to build it. + +As mentioned earlier, the specific builder we are using in this example +is the [Amazon EBS builder](/docs/builders/amazon-ebs.html). +The template below demonstrates use of the [`source_ami_filter`]( +/docs/builders/amazon-ebs.html#source_ami_filter) configuration option +available within the builder for automatically selecting the *latest* +suitable source Windows AMI provided by Amazon. +We also use the `user_data_file` configuration option provided by the builder +to reference the bootstrap file we created earlier. As you will recall, our +bootstrap file contained all the commands we needed to supply in advance of +actually spinning up the instance, so that later on, our instance is +configured to allow Packer to connect in to it. + +The `"provisioners"` section of the template demonstrates use of the +[powershell](/docs/provisioners/powershell.html) and +[windows-restart](/docs/provisioners/windows-restart.html) provisioners to +customize and control the build process: ```json { @@ -447,15 +508,18 @@ windows in addition to the powershell and windows-restart provisioners: } ``` -Set your access key and id as environment variables, so we don't need to pass -them in through the command line: +Save the build template as `firstrun.json`. + +Next we need to set things up so that Packer is able to access and use our +AWS account. Set your access key and id as environment variables, so we +don't need to pass them in through the command line: ``` export AWS_ACCESS_KEY_ID=MYACCESSKEYID export AWS_SECRET_ACCESS_KEY=MYSECRETACCESSKEY ``` -Then `packer build firstrun.json` +Finally, we can create our new AMI by running `packer build firstrun.json` You should see output like this: @@ -508,7 +572,8 @@ Build 'amazon-ebs' finished. us-east-1: ami-100fc56a ``` -And if you navigate to your EC2 dashboard you should see your shiny new AMI. +And if you navigate to your EC2 dashboard you should see your shiny new AMI +listed in the main window of the Images -> AMIs section. Why stop there though? From c9e6ffa91c459587e47f16e03bb13bfcab6b23a6 Mon Sep 17 00:00:00 2001 From: DanHam Date: Mon, 16 Oct 2017 02:45:56 +0100 Subject: [PATCH 13/13] Add warning note about using the 'winrm quickconfig -q' command A lot of examples out there on the web make use of this command to configure the instance to allow connections over WinRM. Since the danger is not immediately obvious and the failure because of its use intermittent, we should do our best to advise against its use here. --- .../intro/getting-started/build-image.html.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 2cdddf544..c66b04d04 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -408,6 +408,29 @@ Start-Service -Name WinRM Save the above code in a file named `bootstrap_win.txt`. +-> **A quick aside/warning:** +Windows administrators in the know might be wondering why we haven't simply +used a `winrm quickconfig -q` command in the script above, as this would +*automatically* set up all of the required elements necessary for connecting +over WinRM. Why all the extra effort to configure things manually? +Well, long and short, use of the `winrm quickconfig -q` command can sometimes +cause the Packer build to fail shortly after the WinRM connection is +established. How? +1. Among other things, as well as setting up the listener for WinRM, the +quickconfig command also configures the firewall to allow management messages +to be sent over HTTP. +2. This undoes the previous command in the script that configured the +firewall to prevent this access. +3. The upshot is that the system is configured and ready to accept WinRM +connections earlier than intended. +4. If Packer establishes its WinRM connection immediately after execution of +the 'winrm quickconfig -q' command, the later commands within the script that +restart the WinRM service will unceremoniously pull the rug out from under +the connection. +5. While Packer does *a lot* to ensure the stability of its connection in to +your instance, this sort of abuse can prove to be too much and *may* cause +your Packer build to stall irrecoverably or fail! + Now we've got the business of getting Packer connected to our instance taken care of, let's get on with the *real* reason we're doing all this, which is actually configuring and customizing the instance. Again, we do this