packer-cn/website/source/docs/builders/oracle-classic.html.md

309 lines
13 KiB
Markdown
Raw Normal View History

2018-01-25 17:00:26 -05:00
---
description: |
2018-10-26 20:02:19 -04:00
The oracle-classic builder is able to create new custom images for use with
Oracle Cloud Infrastructure Classic Compute.
2018-01-25 17:00:26 -05:00
layout: docs
2018-02-01 19:35:10 -05:00
page_title: 'Oracle Cloud Infrastructure Classic - Builders'
2018-01-25 17:00:26 -05:00
sidebar_current: 'docs-builders-oracle-classic'
---
2018-02-01 19:35:10 -05:00
# Oracle Cloud Infrastructure Classic Compute Builder
2018-01-25 17:00:26 -05:00
Type: `oracle-classic`
The `oracle-classic` Packer builder is able to create custom images for use
2018-10-26 20:02:19 -04:00
with [Oracle Cloud Infrastructure Classic
Compute](https://cloud.oracle.com/compute-classic). The builder takes a base
image, runs any provisioning necessary on the base image after launching it,
and finally snapshots it creating a reusable custom image.
2018-01-25 17:00:26 -05:00
2018-10-26 20:02:19 -04:00
It is recommended that you familiarise yourself with the [Key Concepts and
Terminology](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsg/terminology.html)
2018-01-25 17:00:26 -05:00
prior to using this builder if you have not done so already.
2018-10-26 20:02:19 -04:00
The builder *does not* manage images. Once it creates an image, it is up to you
2018-01-25 17:00:26 -05:00
to use it or delete it.
## Authorization
2018-10-26 20:02:19 -04:00
This builder authenticates API calls to Oracle Cloud Infrastructure Classic
Compute using basic authentication (user name and password). To read more, see
the [authentication
documentation](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsa/Authentication.html)
2018-01-25 17:00:26 -05:00
## Configuration Reference
2018-10-26 20:02:19 -04:00
There are many configuration options available for the `oracle-classic`
builder. This builder currently only works with the SSH communicator.
2018-01-25 17:00:26 -05:00
### Required
2018-10-26 20:02:19 -04:00
- `api_endpoint` (string) - This is your custom API endpoint for sending
requests. Instructions for determining your API endpoint can be found
2018-01-25 17:00:26 -05:00
[here](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsa/SendRequests.html)
2018-10-26 20:02:19 -04:00
- `dest_image_list` (string) - Where to save the machine image to once you've
provisioned it. If the provided image list does not exist, Packer will
create it.
2018-01-31 13:47:19 -05:00
2018-10-26 20:02:19 -04:00
- `identity_domain` (string) - This is your customer-specific identity domain
2018-01-25 17:00:26 -05:00
as generated by Oracle. If you don't know what your identity domain is, ask
your account administrator. For a little more information, see the Oracle
[documentation](https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/ocuid/identity-domain-overview.html#GUID-7969F881-5F4D-443E-B86C-9044C8085B8A).
2018-10-26 20:02:19 -04:00
- `source_image_list` (string) - This is what image you want to use as your
base image. See the
[documentation](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsg/listing-machine-images.html)
for more details. You may use either a public image list, or a private
image list. To see what public image lists are available, you can use the
CLI, as described
[here](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stopc/image-lists-stclr-and-nmcli.html#GUID-DB7E75FE-F752-4FF7-AB70-3C8DCDFCA0FA)
2018-01-25 17:00:26 -05:00
- `source_image_list_entry` (string) - The entry identifying the machine
image to use in the image list. Defaults to the latest available entry.
2018-10-26 20:02:19 -04:00
- `password` (string) - Your account password.
2018-01-25 17:00:26 -05:00
2018-10-26 20:02:19 -04:00
- `shape` (string) - The template that determines the number of CPUs, amount
of memory, and other resources allocated to a newly created instance. For
more information about shapes, see the documentation
[here](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsg/machine-images-and-shapes.html).
2018-01-25 17:00:26 -05:00
2018-10-26 20:02:19 -04:00
- `username` (string) - Your account username.
2018-01-25 17:00:26 -05:00
### Optional
2018-10-26 20:02:19 -04:00
- `attributes` (string) - (string) - Attributes to apply when launching the
2018-10-26 04:09:20 -04:00
instance. Note that you need to be careful about escaping characters due to
the templates being JSON. It is often more convenient to use
`attributes_file`, instead. You may only define either `attributes` or
`attributes_file`, not both.
2018-10-26 20:02:19 -04:00
- `attributes_file` (string) - Path to a json file that will be used for the
2018-10-26 04:09:20 -04:00
attributes when launching the instance. You may only define either
`attributes` or `attributes_file`, not both.
2018-10-26 20:02:19 -04:00
- `image_description` (string) - a description for your destination image
list. If you don't provide one, Packer will provide a generic description.
2018-01-31 13:47:19 -05:00
2018-10-26 20:02:19 -04:00
- `ssh_username` (string) - The username that Packer will use to SSH into the
instance; required if using SSH. The default oracle user with sudo
privileges is `opc`, so you may set `ssh_username` to `opc` if you have not
yet configured users on your machine. If you have already configured users
on your machine, you may prompt Packer to use one of those instead. For
more detail, see the
2018-01-25 17:00:26 -05:00
[documentation](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsg/accessing-oracle-linux-instance-using-ssh.html).
2018-10-26 20:02:19 -04:00
- `image_name` (string) - The name to assign to the resulting custom image.
2018-01-25 17:00:26 -05:00
2018-10-26 23:54:38 -04:00
- `persistent_volume_size` (int) - Size in gigabytes of the persistent boot
storage volume to build the image on. Use this if you want a bigger volume
than what instance storage provides. Note that using this option puts the
builder into a "persistent volume" mode, which is substantially different
than the default snapshot mode. Please see the configuration section below
for additional configuration options.
2018-10-26 20:02:19 -04:00
- `snapshot_timeout` (string) - How long to wait for a snapshot to be
created. Expects a positive golang Time.Duration string, which is a
sequence of decimal numbers and a unit suffix; valid suffixes are `ns`
(nanoseconds), `us` (microseconds), `ms` (milliseconds), `s` (seconds), `m`
2018-10-26 20:02:19 -04:00
(minutes), and `h` (hours). Examples of valid inputs: `100ms`, `250ms`,
`1s`, `2.5s`, `2.5m`, `1m30s`. Example: `"snapshot_timeout": "15m"`.
Default: `20m`.
2018-10-26 23:54:38 -04:00
### Persistent Volume Build
You will use this type of build if you've set the `persistent_volume_size`
option. If you need a bigger disk than what you normally get with instance
storage, you'll want to set this.
In the *persistent volume* mode, things are built a little differently.
Normally, we launch an instance, then provision it and take a snapshot, which
becomes your machine image. This relies on the disk of the created instance
being large enough to perform your entire provisioning process. If that disk
size isn't sufficient, we can build with a persistent volume of arbitrary size.
First, we create a persistent volume of the requested size. This volume is
bootable and initialized with your image list. We start an instance with this
volume as the boot volume. After this instance launches, we provision and
terminate it, leaving the persistent volume around.
2018-10-26 23:54:38 -04:00
Next, we create a second instance, the "builder", this time booting from
instance storage. We also attach a new persistent volume, making it twice the
size of the original. We connect to this instance and copy the contents of the
first volume into a tarball file on the second volume. We then upload this file
to Object Storage Classic, and create a new machine image with it.
For more details, see this [blog
post](https://blogs.oracle.com/cloudmarketplace/creating-an-oracle-compute-machine-image-from-an-instance-with-persistent-boot-storage),
which discusses the strategy used here.
2018-10-26 23:54:38 -04:00
If this is set, a few more options become available.
- `builder_communicator` (communicator) - This represents an
[`ssh communicator`](/docs/templates/communicator.html#ssh-communicator),
and can be configured as such. If you use a different builder image, you
2019-01-11 17:06:15 -05:00
may need to change the `ssh_username`, for example. That might look like
this:
2018-10-26 23:54:38 -04:00
2019-01-11 17:06:15 -05:00
``` json
2018-10-26 23:54:38 -04:00
{
"builders": [
{
"builder_communicator": {
"ssh_username": "soandso"
},
"type": "oracle-classic"
}
]
}
```
- `builder_image_list` (string) - This is the image to use for the builder
2018-10-30 15:05:14 -04:00
instance. This *must* be a linux image, and Oracle Linux is recommended.
2018-10-26 23:54:38 -04:00
Default: `/oracle/public/OL_7.2_UEKR4_x86_64`.
- `builder_image_list_entry` (string) - The entry identifying the machine
image to use in the image list. If `builder_image_list` is unset, this
defaults to `5`, which is a working image as of this time. Otherwise, it
defaults to the latest entry. Set this to `0` to force it to use the latest
entry when using the default `builder_image_list`.
2018-10-26 23:54:38 -04:00
- `builder_shape` (string) - The template that determines the number of CPUs,
amount of memory, and other resources allocated to the builder instance.
Default: `oc3`.
2019-01-11 17:06:15 -05:00
- `builder_upload_image_command` (string) - The command to run to upload the
2018-10-26 23:54:38 -04:00
image to Object Storage Classic. This is for advanced users only, and you
should consult the default in code to decide on the changes to make. For
most users the default should suffice.
2018-01-25 17:00:26 -05:00
## Basic Example
Here is a basic example. Note that account specific configuration has been
obfuscated; you will need to add a working `username`, `password`,
2018-01-25 17:00:26 -05:00
`identity_domain`, and `api_endpoint` in order for the example to work.
``` json
2018-01-25 17:00:26 -05:00
{
"builders": [
{
"type": "oracle-classic",
"username": "myuser@myaccount.com",
"password": "supersecretpasswordhere",
"identity_domain": "#######",
"api_endpoint": "https://api-###.compute.###.oraclecloud.com/",
"source_image_list": "/oracle/public/OL_7.2_UEKR4_x86_64",
"shape": "oc3",
"image_name": "Packer_Builder_Test_{{timestamp}}",
"attributes": "{\"userdata\": {\"pre-bootstrap\": {\"script\": [\"...\"]}}}",
"dest_image_list": "Packer_Builder_Test_List"
2018-01-25 17:00:26 -05:00
}
],
"provisioners": [
{
"type": "shell",
"inline": ["echo hello"]
}
]
}
```
## Basic Example -- Windows
Attributes file is optional for connecting via ssh, but required for winrm.
The following file contains the bare minimum necessary to get winRM working;
2018-10-26 04:09:20 -04:00
you have to give it the password to give to the "Administrator" user, which
2018-10-26 20:02:19 -04:00
will be the one winrm connects to. You must also whitelist your computer to
connect via winRM -- the empty braces below whitelist any computer to access
2018-10-26 04:09:20 -04:00
winRM but you can make it more secure by only allowing your build machine
2018-10-26 20:02:19 -04:00
access. See the
[docs](https://docs.oracle.com/en/cloud/iaas/compute-iaas-cloud/stcsg/automating-instance-initialization-using-opc-init.html#GUID-A0A107D6-3B38-47F4-8FC8-96D50D99379B)
for more details on how to define a trusted host.
Save this file as `windows_attributes.json`:
2018-10-26 20:02:19 -04:00
``` json
{
"userdata": {
"administrator_password": "password",
"winrm": {}
}
}
```
2018-10-26 20:02:19 -04:00
Following is a minimal but working Packer config that references this
attributes file:
2018-03-28 12:04:06 -04:00
2018-10-26 20:02:19 -04:00
``` json
{
"variables": {
"opc_username": "{{ env `OPC_USERNAME`}}",
"opc_password": "{{ env `OPC_PASSWORD`}}",
"opc_identity_domain": "{{env `OPC_IDENTITY_DOMAIN`}}",
"opc_api_endpoint": "{{ env `OPC_ENDPOINT`}}"
},
"builders": [
{
"type": "oracle-classic",
"username": "{{ user `opc_username`}}",
"password": "{{ user `opc_password`}}",
"identity_domain": "{{ user `opc_identity_domain`}}",
"api_endpoint": "{{ user `opc_api_endpoint`}}",
2018-03-28 12:04:06 -04:00
"source_image_list": "/Compute-{{ user `opc_identity_domain` }}/{{ user `opc_username`}}/Microsoft_Windows_Server_2012_R2-17.3.6-20170930-124649",
"attributes_file": "./windows_attributes.json",
"shape": "oc3",
"image_name": "Packer_Windows_Demo_{{timestamp}}",
"dest_image_list": "Packer_Windows_Demo",
"communicator": "winrm",
"winrm_username": "Administrator",
"winrm_password": "password"
}
],
"provisioners": [
{
"type": "powershell",
"inline": "Write-Output(\"HELLO WORLD\")"
}
]
}
```
2018-10-26 23:54:38 -04:00
## Persistent Volume Example
Here is an example using a persistent volume. Note the `persistent_volume_size`
setting.
2019-01-11 17:06:15 -05:00
``` json
2018-10-26 23:54:38 -04:00
{
"variables": {
"opc_username": "{{ env `OPC_USERNAME`}}",
"opc_password": "{{ env `OPC_PASSWORD`}}",
"opc_identity_domain": "{{env `OPC_IDENTITY_DOMAIN`}}",
"opc_api_endpoint": "{{ env `OPC_ENDPOINT`}}"
},
"builders": [
{
"type": "oracle-classic",
"username": "{{ user `opc_username`}}",
"password": "{{ user `opc_password`}}",
"identity_domain": "{{ user `opc_identity_domain`}}",
"api_endpoint": "{{ user `opc_api_endpoint`}}",
"source_image_list": "/oracle/public/OL_7.2_UEKR4_x86_64",
"persistent_volume_size": 15,
"image_name": "Packer_Builder_Test_{{timestamp}}",
2018-10-27 05:04:36 -04:00
"dest_image_list": "Packer_Builder_Test_List",
2018-10-27 00:59:26 -04:00
"ssh_username": "opc",
2018-10-26 23:54:38 -04:00
"shape": "oc3"
}
],
"provisioners": [
{
"type": "shell",
"inline": ["echo hello"]
}
]
}
```