|
|
| (14 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| This article has some notes on installing NixOS on Amazon's [http://aws.amazon.com/ec2/ Elastic Compute Cloud (EC2)]. EC2 support is work in progress.
| | <languages /> |
| | <translate> |
| | <!--T:1--> |
| | Amazon EC2 is a widely used cloud deployment platform that is part of Amazon Web Services (AWS). NixOS largely supports the platform through AMIs and the [https://github.com/nix-community/nixos-generators nixos-generators] project. |
|
| |
|
| Below we assume that the following environment variables are set:
| | == Public NixOS AMIs == <!--T:2--> |
|
| |
|
| * <tt>$EC2_CERT</tt>: path to your AWS X.509 certificate (PEM file).
| | <!--T:3--> |
| * <tt>$EC2_PRIVATE_KEY</tt>: path to the corresponding private key (PEM file).
| | A list of NixOS AMI's available on AWS is located [https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/amazon-ec2-amis.nix here] and for a more up to date list: [https://nixos.github.io/amis/ here] (cf. [https://discourse.nixos.org/t/ami-for-nixos-23-11/36860/7 this discourse thread]). |
| * <tt>$AWS_ACCOUNT</tt>: AWS account number (e.g. <tt>1234-5678-9012</tt>).
| |
| * <tt>$AWS_ACCESS_KEY_ID</tt>: AWS access key ID (e.g. <tt>AKIAJM...</tt>).
| |
| * <tt>$AWS_SECRET_ACCESS_KEY</tt>: corresponding secret access key (e.g. <tt>klG5...</tt>).
| |
| * <tt>$AWS_CALLING_FORMAT</tt> may need to be set to <tt>SUBDOMAIN</tt>.
| |
| * <tt>$EC2_URL</tt> should be set to the desired region, e.g. <tt>https://ec2.eu-west-1.amazonaws.com/</tt>.
| |
|
| |
|
| == Public NixOS AMIs ==
| | <!--T:4--> |
| | The default user for these AMI's is <code>root</code>. There isn't a default password, instead authentication is done by using the SSH key selected during the EC2 creation process. |
|
| |
|
| The list of current NixOS AMI's are available at https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix
| | == Creating a NixOS AMI == <!--T:5--> |
|
| |
|
| == Running NixOS instances ==
| | <!--T:6--> |
| | The [https://github.com/nix-community/nixos-generators nixos-generators] project is currently the best method to create your own NixOS AMI. Follow the directions provided by <code>nixos-generators</code> & then follow the [https://docs.aws.amazon.com/vm-import/latest/userguide/what-is-vmimport.html instructions provided by AWS]. |
|
| |
|
| <ol> | | == Additional Resources == <!--T:7--> |
|
| |
|
| <li>To create instances from the command line, you need to install the EC2 API tools: | | <!--T:8--> |
| | [http://jackkelly.name/blog/archives/2020/08/30/building_and_importing_nixos_amis_on_ec2/ Building and Importing NixOS AMIs on EC2] by Jack Kelly |
|
| |
|
| <pre>$ nix-env -i ec2-api-tools</pre> | | == Troubleshooting == <!--T:9--> |
|
| |
|
| Alternatively, you can create NixOS instances using the [http://aws.amazon.com/console/ AWS Management Console].
| | == SSH Asks For Password == <!--T:10--> |
|
| |
|
| <li>Start a small instance running NixOS: | | <!--T:11--> |
| | | When connecting to a newly launched EC2 instance via SSH, it may ask for a password. This seems to be because the <code>amazon-init</code> systemd service is still reading user data. Back out of the current SSH attempt and try again in a few minutes. |
| <pre>
| | </translate> |
| $ ec2-run-instances -k gsg-keypair ami-c9f2d8bd
| |
| RESERVATION r-10ca4167 516444698777 default
| |
| INSTANCE i-f6d3b781 ami-c9f2d8bd pending gsg-keypair 0 m1.small ...</pre>
| |
| | |
| <tt>gsg-keypair</tt> denotes an SSH key pair created with <tt>ec2-add-keypair</tt>. To run a 64-bit instance, you must specify a 64-bit-capable instance type, e.g., <tt>-t m1.large</tt>. If your requirements allow it, you may prefer using a cheap spot instance:
| |
| | |
| <pre>
| |
| $ ec2-request-spot-instances -t m1.large -k gsg-keypair -p 0.3 ami-ecb49e98</pre>
| |
| | |
| <li>After a while the instance should be running, and you can log in using the SSH key generated by <tt>ec2-add-keypair</tt>:
| |
| | |
| <pre>
| |
| $ ssh -i id_rsa-gsg-keypair root@ec2-79-125-97-89.eu-west-1.compute.amazonaws.com</pre>
| |
| | |
| To get the IP address / hostname of the instance, use <tt>ec2-describe-instances</tt>. You may need to allow traffic to port 22 (ssh):
| |
| | |
| <pre>
| |
| $ ec2-authorize default -p 22 -s 0.0.0.0/0</pre>
| |
| | |
| <li>To start working with the instance, you may want to do the following to obtain the Nixpkgs and NixOS sources:
| |
| | |
| <pre>
| |
| $ nixos-checkout
| |
| $ nixos-rebuild pull</pre>
| |
| | |
| You should now be able to install software, e.g.
| |
| | |
| <pre>
| |
| $ nix-env -i emacs</pre>
| |
| | |
| or reconfigure the instance:
| |
| | |
| <pre>
| |
| $ nano /etc/nixos/configuration.nix
| |
| $ nixos-rebuild switch</pre>
| |
| | |
| Note: if you're using an ec2 instance based on the HVM virtualization type, you will need to set the
| |
| ec2.hvm = true;
| |
| | |
| setting in configuration.nix; otherwise GRUB won't pick up changes to your configuration across reboots.
| |
| | |
| </ol>
| |
| | |
| == Creating a NixOS AMI ==
| |
| | |
| The following steps show how to build your own NixOS Amazon Image (AMI), upload it to S3, and start an instance.
| |
| | |
| <ol>
| |
| | |
| <li>Install the EC2 AMI tools:
| |
| | |
| <pre>$ nix-env -i ec2-ami-tools</pre>
| |
| | |
| <li>The easy way to build NixOS AMIs is to run the following command:
| |
| | |
| <pre>
| |
| $ NIXOS=/path/to/nixos NIXPKGS=/path/to/nixpkgs /path/to/nixos/maintainers/scripts/create-amis.sh</pre>
| |
| | |
| This will build, bundle and upload AMIs to several EC2 regions. Note that the resulting AMIs will be public. | |
| | |
| Alternatively, you can perform the steps below to create the AMI manually.
| |
| | |
| <li>Build the raw disk image: | |
| | |
| <pre>
| |
| $ NIXPKGS=/path/to/nixpkgs NIXOS_CONFIG=/path/to/nixos/modules/virtualisation/amazon-config.nix \
| |
| nix-build /path/to/nixos -A config.system.build.amazonImage \
| |
| --argstr system i686-linux</pre>
| |
| | |
| (Use <tt>--argstr system x86_64-linux</tt> to build a 64-bit image.) This will produce an <tt>ext3</tt> disk image in <tt>./result/nixos.img</tt>:
| |
| | |
| <pre>
| |
| $ ls -l ./result/nixos.img
| |
| -r--r--r-- 1 root nixbld 4294967296 Jan 1 1970 ./result/nixos.img</pre>
| |
| | |
| <li>Bundle the image:
| |
| | |
| <pre>
| |
| $ ec2-bundle-image -i ./result/nixos.img --user $AWS_ACCOUNT --arch i386 \
| |
| -c $EC2_CERT -k $EC2_PRIVATE_KEY \
| |
| --kernel aki-c34d67b7
| |
| Bundling image file...
| |
| Splitting /tmp/nixos.img.tar.gz.enc...
| |
| Created nixos.img.part.00
| |
| ...
| |
| Created nixos.img.part.19
| |
| Generating digests for each part...
| |
| Digests generated.
| |
| Creating bundle manifest...
| |
| ec2-bundle-image complete.</pre>
| |
| | |
| The resulting bundle is stored in <tt>/tmp/nixos.img.manifest.xml</tt> and <tt>/tmp/nixos.img.part.*</tt>. Use <tt>--arch x86_64</tt> for 64-bit images. For the kernel, you should use <tt>pv-grub-hd0_1.02-<em>arch</em></tt> (use <tt>ec2-describe-images -a</tt> to find the AMI ID). This is the PV-GRUB "kernel" that boots the native NixOS kernel in the image.
| |
| | |
| <li>Upload the bundle:
| |
| | |
| <pre>
| |
| $ ec2-upload-bundle -b nixos-img -m /tmp/nixos.img.manifest.xml \
| |
| -a $AWS_ACCESS_KEY_ID -s $AWS_SECRET_ACCESS_KEY --location EU
| |
| Creating bucket...
| |
| Uploading bundled image parts to the S3 bucket nixos-img ...
| |
| Uploaded nixos.img.part.00
| |
| Uploaded nixos.img.part.01
| |
| ...
| |
| Uploaded nixos.img.part.19
| |
| Uploading manifest ...
| |
| Uploaded manifest.
| |
| Bundle upload completed.
| |
| </pre>
| |
| | |
| (Of course you can use any other bucket location as well.)
| |
| | |
| <li>Register the image as a private AMI:
| |
| | |
| <pre>
| |
| $ ec2-register nixos-img/nixos.img.manifest.xml -n nixos-img -d '...description...'
| |
| IMAGE ami-efffd59b</pre>
| |
| | |
| To make it public:
| |
| | |
| <pre>
| |
| $ ec2-modify-image-attribute ami-efffd59b -l -a all</pre>
| |
| | |
| </ol> | |
|
| |
|
| [[Category:Deployment]] | | [[Category:Deployment]] |
| | [[Category:Server]] |
Amazon EC2 is a widely used cloud deployment platform that is part of Amazon Web Services (AWS). NixOS largely supports the platform through AMIs and the nixos-generators project.
Public NixOS AMIs
A list of NixOS AMI's available on AWS is located here and for a more up to date list: here (cf. this discourse thread).
The default user for these AMI's is root. There isn't a default password, instead authentication is done by using the SSH key selected during the EC2 creation process.
Creating a NixOS AMI
The nixos-generators project is currently the best method to create your own NixOS AMI. Follow the directions provided by nixos-generators & then follow the instructions provided by AWS.
Additional Resources
Building and Importing NixOS AMIs on EC2 by Jack Kelly
Troubleshooting
SSH Asks For Password
When connecting to a newly launched EC2 instance via SSH, it may ask for a password. This seems to be because the amazon-init systemd service is still reading user data. Back out of the current SSH attempt and try again in a few minutes.
