* updates to READMEs
This commit is contained in:
parent
1cce13e722
commit
e65b2d7720
@ -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.
|
||||||
|
@ -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.
|
|
||||||
|
@ -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 `#!`)
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user