ZeroDownTime/alpine-zdt-images
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

* updates to READMEs

Browse Source
This commit is contained in:
Jake Buchholz 2020-09-14 19:50:15 -07:00 committed by Mike Crute
parent 1cce13e722
commit e65b2d7720
3 changed files with 61 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -50,7 +50,7 @@ for more details and information about how AMI profile configs work.
These scripts use the `boto3` library to interact with AWS, enabling you to These scripts use the `boto3` library to interact with AWS, enabling you to
provide your AWS account credentials in a number of different ways. see the provide your AWS account credentials in a number of different ways. see the
offical `boto3` documentation's section on offical `boto3` documentation's section on
[configuring credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials) [configuring credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#guide-credentials)
for more details. *Please note that these scripts do not implement the first for more details. *Please note that these scripts do not implement the first
two methods on the list.* two methods on the list.*
@ -63,7 +63,7 @@ To build all build targets in a target profile, simply...
You can also build specfic build targets within a profile: You can also build specfic build targets within a profile:
``` ```
./scripts/builder.py amis <profile> <build1> <build2> ./scripts/builder.py amis <profile> <build1> <build2> ...
``` ```
Before each build, new Alpine Linux *releases* are detected and the version's Before each build, new Alpine Linux *releases* are detected and the version's
@ -108,7 +108,7 @@ other target profiles.
### Cleaning up the Build Environment ### Cleaning up the Build Environment
The build process is careful to place all temporary files in teh `build` The build process is careful to place all temporary files in the `build`
subdirectory. Remove the temporary `build` subdirectory, which contains the subdirectory. Remove the temporary `build` subdirectory, which contains the
resolved profile and Packer configs, the Python virtual environment, and other resolved profile and Packer configs, the Python virtual environment, and other
temporary build-related artifacts. temporary build-related artifacts.

75
profiles/README.md
View File

@ -14,7 +14,7 @@ This flexibility helps keep configuration for related build targets
Core profile configurations are found in the `base`, `version`, and `arch` Core profile configurations are found in the `base`, `version`, and `arch`
subdirectories. Core profiles do not have a `.conf` suffix because they're not subdirectories. Core profiles do not have a `.conf` suffix because they're not
meant to be directly used like target profiles with `make`. 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 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. empty or null are usually set in version, arch, or target profile configs.
@ -31,7 +31,7 @@ which `apk-tools` and `alpine-keys` to use (and their SHA256 checksums).
## Target Profiles ## Target Profiles
Target profiles, defined in this directory, are the top-level configuration Target profiles, defined in this directory, are the top-level configuration
used with `make PROFILE=<profile>`; they must have a `.conf` suffix. Several used with `./scripts/builder.py`; they must have a `.conf` suffix. Several
configuration objects are defined and later merged within the `BUILDS` object, configuration objects are defined and later merged within the `BUILDS` object,
ultimately defining each individual build. ultimately defining each individual build.
@ -44,21 +44,23 @@ settings.
The `BUILDS` object's elements merge core and profile configs (with optional The `BUILDS` object's elements merge core and profile configs (with optional
inline build settings) into named build definitions; these build names can be inline build settings) into named build definitions; these build names can be
used to specify a subset of a profile's builds: used to specify a subset of a profile's builds, for example:
`make PROFILE=<profile> BUILDS="<build> ..."` `./scripts/builder.py amis <profile> <build1> <build2> ...`
**Please note that merge order matters!** The merge sequence is version --> **Please note that merge order matters!** The merge sequence is version -->
architecture --> profile --> build. architecture --> profile --> build.
## Customization ## Customization
The most important variables to set in your custom profile is `build_region` If the AWS configuration you're using does not specify a default region, your
and `build_subnet`. Without these, Packer will not know where to build. 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` can be `version` and `release` are meant to match Alpine; however, `revision` is used
used to track changes to profile or situations where the AMIs needed to be used to track changes to the profile, additions of new alpine-ec2-ami features,
rebuilt. The "edge" core version profile sets `revision` to the current or other situations where the AMIs needs to be rebuilt. The "edge" core
datetime, otherwise the default is `r0`. 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. 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 Set `ami_name_prefix` and `ami_name_suffix`; setting `ami_desc_suffix` and
@ -75,7 +77,12 @@ during the first boot, so you shouldn't need to make space for anything other
than installed packages. than installed packages.
Set `ami_encrypt` to "true" to create an encrypted AMI image. Launching images Set `ami_encrypt` to "true" to create an encrypted AMI image. Launching images
from an encrypted AMI results in an encrypted EBS root volume. 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 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 `ami_regions`. This variable is a *hash*, which allows for finer control over
@ -92,6 +99,14 @@ ami_regions {
} }
``` ```
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 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 one reason for creating custom profile. The `repos`, `pkgs`, and `svcs` hash
variables serve precisely that purpose. With some exceptions (noted below), variables serve precisely that purpose. With some exceptions (noted below),
@ -124,19 +139,29 @@ pkgs {
``` ```
To control when (or whether) a system service starts, use the `svcs` hash To control when (or whether) a system service starts, use the `svcs` hash
variable. Its keys are the service names, as they appear in `/etc/init.d`; variable. Its first-level keys are names of runlevels ('sysinit', 'boot',
default values are set in the base core profile. Like the other hash `default`, and `shutown`), and the second-level keys are the services, as they
variables, setting `false` or `null` disable the service, `true` will enable appear in `/etc/init.d`. Like the other profile hash variables, setting
the service at the "default" runlevel. The service can be enabled at a `false` or `null` disable the service in the runlevel, `true` will enable the
different runlevel by using that runlevel as the value. service.
By default, the AMIs built are accessible only by the owning account. To Further customization can be done by specifying your own setup script with the
make your AMIs publicly available, set the `ami_access` hash variable: `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
ami_access { before the final cleanup phase.
all = true
} If there are additional data or scripts that the 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](https://github.com/mcrute/tiny-ec2-bootstrap)
will use that valie instead of `alpine`.
## Limitations and Caveats ## Limitations and Caveats
@ -146,7 +171,3 @@ ami_access {
hash_var = null # drops inherited values hash_var = null # drops inherited values
hash_var {} # re-defines as an empty hash hash_var {} # re-defines as an empty hash
``` ```
* The AMI's login user is currently hard coded to be `alpine`. Changes to
[tiny-ec2-bootstrap](https://github.com/mcrute/tiny-ec2-bootstrap) are
required before we can truly make `ami_user` configurable.

15
releases/README.md
View File

@ -3,17 +3,22 @@
**These are not official AWS or Alpine images. They are community built and **These are not official AWS or Alpine images. They are community built and
supported.** supported.**
These AMIs should work with most EC2 features such as Elastic Network Adapters These AMIs should work with most EC2 features such as ENI's (Elastic Network
and NVMe EBS volumes. If you find any problems launching them on current Interfaces) and NVMe EBS (Elastic Block Storage) volumes. If you find any
generation instances, please open an [issue](https://github.com/mcrute/alpine-ec2-ami/issues) problems launching them on current generation instances, please open an
and include as much detailed information as possible. [issue](https://github.com/mcrute/alpine-ec2-ami/issues) and include as much
detailed information as possible.
AMIs built after 2020-09-15 include support for hot-pluggable ENI's and will
sync all private IPv4 and IPv6 address on those ENI's on `udhcpc` post-bound and
post-renew events.
During the *first boot* of instances created with these AMIs, the lightweight During the *first boot* of instances created with these AMIs, the lightweight
[tiny-ec2-bootstrap](https://github.com/mcrute/tiny-ec2-bootstrap) init [tiny-ec2-bootstrap](https://github.com/mcrute/tiny-ec2-bootstrap) init
script... script...
- sets the instance's hostname, - sets the instance's hostname,
- installs the SSH authorized_keys for the 'alpine' user, - installs the SSH authorized_keys for the 'alpine' user,
- disables 'root' and 'alpine' users' passwords, - disables 'root' and AMI user (default 'alpine') passwords,
- expands the root partition to use all available EBS volume space, - expands the root partition to use all available EBS volume space,
- and executes a "user data" script (must be a shell script that starts with `#!`) - and executes a "user data" script (must be a shell script that starts with `#!`)