7.9 KiB
Profiles
Profiles are collections of related build definitions, which are used to
generate the vars.json files that Packer consumes
when building AMIs.
Profiles use HOCON (Human-Optimized Config Object Notation) which allows importing common configs from other files, simple variable interpolation, and easy merging of objects. This flexibility helps keep configuration for related build targets DRY.
Core Profiles
Core profile configurations are found in the base, version, and arch
subdirectories. Core profiles do not have a .conf suffix because they're not
meant to be directly used like target profiles with the builder.py script.
Base core profiles define all build vars with default values -- those left empty or null are usually set in version, arch, or target profile configs. Base profiles are included in version profiles, and do not need to be included in target profiles.
Version core profiles expand on the base profile they include, and set the
version, release, end_of_life (if known), and the associated Alpine Linux
repos.
Arch core profiles further define architecture-specific variables, such as
which apk-tools and alpine-keys to use (and their SHA256 checksums).
Target Profiles
Target profiles, defined in this directory, are the top-level configuration
used with ./scripts/builder.py; they must have a .conf suffix. Several
configuration objects are defined and later merged within the BUILDS object,
ultimately defining each individual build.
Simple profiles have an object that loads a "version" core profile and another that loads an "arch" core profile. A more complicated version-arch matrix profile would have an object for each version and arch.
Additionally, there are one or more objects that define profile-specific settings.
The BUILDS object's elements merge core and profile configs (with optional
inline build settings) into named build definitions; these build names can be
used to specify a subset of a profile's builds, for example:
./scripts/builder.py amis <profile> <build1> <build2> ...
Please note that merge order matters! The merge sequence is version --> architecture --> profile --> build.
Customization
If the AWS configuration you're using does not specify a default region, your
custom profile will need to specify build_region. If the build region does
not have a default VPC, you'll need to specify build_subnet.
version and release are meant to match Alpine; however, revision is used
used to track changes to the profile, additions of new
alpine-ec2-ami features,
or other situations where the AMIs needs to be rebuilt. The "edge" core
version profile sets revision to null, which translates into the current
datetime. Otherwise, the default set in the base profile is r0.
You will probably want to personalize the name and description of your AMI.
Set ami_name_prefix and ami_name_suffix; setting ami_desc_suffix and
ami_desc_suffix is optional.
Set build_instance_type if you want/need to use a different instance type to
build the image; the default is t3.nano.
If 1 GiB is not enough to install the packages in your base AMI, you can set
the ami_volume_size to the number of GiB you need. Note, however, that the
tiny-ec2-bootstrap init script
will expand the root partition to use the instance's entire EBS root volume
during the first boot, so you shouldn't need to make space for anything other
than installed packages.
Set ami_encrypt to "true" to create an encrypted AMI image. Launching images
from an encrypted AMI results in an encrypted EBS root volume. Please note
that if your AMI is encrypted, only the owning account will be able to use it.
NOTE: The following funcitonality that is currently not operational -- it is pending completion and integration of a new release tool. In the meantime, you will have to manually copy AMIs from the build region to other regions.
To copy newly built AMIs to regions other than the build_region region, set
ami_regions. This variable is a hash, which allows for finer control over
inherited values when merging configs. Region identifiers are the keys, a
value of true means the AMI should be copied to that region; null or
false indicate that it shouldn't be copied to that region. If you want to
ensure that the ami_regions hash does not inherit any values, set it to
null before configuring your regions. For example:
ami_regions = null # don't inherit any previous values
ami_regions {
us-west-2 = true
eu-north-1 = true
}
By default, the AMIs built are accessible only by the owning account. To
make your AMIs publicly available, set the ami_access hash variable:
ami_access {
all = true
}
Controlling what packages are installed and enabled in the AMI is the number
one reason for creating custom profile. The repos, pkgs, and svcs hash
variables serve precisely that purpose. With some exceptions (noted below),
they work the same as the ami_regions hash: true values enable, false
and null values disable, and inherited values can be cleared by first setting
the variable itself to null.
With repos, the keys are double-quoted URLs to the apk repos that you want
set up; these are initially set in the "version" core profiles. In addition
to the true, false, and null values, you can also use a "repo alias"
string value, allowing you to pin packages to be sourced from that particular
repo. For example, with a profile based from a non-edge core profile, you may
want to be able to pull packages from the edge testing repo:
repos {
"http://dl-cdn.alpinelinux.org/alpine/edge/testing" = "edge-testing"
}
The pkgs hash's default is set in the base core profile; its keys are
simply the Alpine package to install (or not install, if the value is false
or null). A true value installs the package from the default repos; if the
value is a repo alias string, the package will be pinned to explicitly install
from that repo. For example:
pkgs {
# install docker-compose from edge-testing repo
docker-compose = "edge-testing"
}
To control when (or whether) a system service starts, use the svcs hash
variable. Its first-level keys are names of runlevels (sysinit, boot,
default, and shutown), and the second-level keys are the services, as they
appear in /etc/init.d. Like the other profile hash variables, setting
false or null disable the service in the runlevel, true will enable the
service.
Further customization can be done by specifying your own setup script with the
setup_script profile variable. This will be copied to the build instance at
/tmp/setup-ami.d/setup_script, and executed by the setup-ami script just
before the final cleanup phase.
If there are additional data or scripts that your setup script uses, use the
setup_copy hash variable -- the key is the destination path under the build
instance's /tmp/setup-ami.d directory, and the value is the local path to
the source file or directory. No data is automatically installed in the AMI,
and no additional scripts are executed -- you must explicitly install/execute
via the setup_script script.
The AMI's default login user is alpine. If you want to specify a alternate
login, set it with the ami_user profile variable. This setting is saved in
/etc/conf.d/tiny-ec2-bootstrap as EC2_USER and
tiny-ec2-bootstrap
will use that valie instead of alpine.
Limitations and Caveats
- Hash variables that are reset to clear inherited values must be
re-defined as a hash, even if it is to remain empty:
hash_var = null # drops inherited values hash_var {} # re-defines as an empty hash