diff --git a/README.md b/README.md index 0f15c07..90c514f 100644 --- a/README.md +++ b/README.md @@ -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 provide your AWS account credentials in a number of different ways. see the 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 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: ``` -./scripts/builder.py amis +./scripts/builder.py amis ... ``` 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 -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 resolved profile and Packer configs, the Python virtual environment, and other temporary build-related artifacts. diff --git a/profiles/README.md b/profiles/README.md index 2dfd50e..e1c34a4 100644 --- a/profiles/README.md +++ b/profiles/README.md @@ -14,7 +14,7 @@ This flexibility helps keep configuration for related build targets 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 `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 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, defined in this directory, are the top-level configuration -used with `make 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, ultimately defining each individual build. @@ -44,21 +44,23 @@ 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: -`make PROFILE= BUILDS=" ..."` +used to specify a subset of a profile's builds, for example: +`./scripts/builder.py amis ...` **Please note that merge order matters!** The merge sequence is version --> architecture --> profile --> build. ## Customization -The most important variables to set in your custom profile is `build_region` -and `build_subnet`. Without these, Packer will not know where to build. +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` can be -used to track changes to profile or situations where the AMIs needed to be -rebuilt. The "edge" core version profile sets `revision` to the current -datetime, otherwise the default is `r0`. +`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 @@ -75,7 +77,12 @@ 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. +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 @@ -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 one reason for creating custom profile. The `repos`, `pkgs`, and `svcs` hash 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 -variable. Its keys are the service names, as they appear in `/etc/init.d`; -default values are set in the base core profile. Like the other hash -variables, setting `false` or `null` disable the service, `true` will enable -the service at the "default" runlevel. The service can be enabled at a -different runlevel by using that runlevel as the value. +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. -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 -} -``` +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 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 @@ -146,7 +171,3 @@ ami_access { hash_var = null # drops inherited values 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. diff --git a/releases/README.md b/releases/README.md index 6af96d2..e8e3b21 100644 --- a/releases/README.md +++ b/releases/README.md @@ -3,17 +3,22 @@ **These are not official AWS or Alpine images. They are community built and supported.** -These AMIs should work with most EC2 features such as Elastic Network Adapters -and NVMe EBS volumes. If you find any problems launching them on current -generation instances, please open an [issue](https://github.com/mcrute/alpine-ec2-ami/issues) -and include as much detailed information as possible. +These AMIs should work with most EC2 features such as ENI's (Elastic Network +Interfaces) and NVMe EBS (Elastic Block Storage) volumes. If you find any +problems launching them on current generation instances, please open an +[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 [tiny-ec2-bootstrap](https://github.com/mcrute/tiny-ec2-bootstrap) init script... - sets the instance's hostname, - 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, - and executes a "user data" script (must be a shell script that starts with `#!`)