|
|
| (7 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | {{outdated}}
| + | 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. |
| − | | |
| − | 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.
| |
| − | | |
| − | Below we assume that the following environment variables are set:
| |
| − | | |
| − | * <tt>$EC2_CERT</tt>: path to your AWS X.509 certificate (PEM file).
| |
| − | * <tt>$EC2_PRIVATE_KEY</tt>: path to the corresponding private key (PEM file).
| |
| − | * <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 == | | == Public NixOS AMIs == |
| | | | |
| − | The list of current NixOS AMI's are available at https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix
| + | 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]). |
| − | | |
| − | == Running NixOS instances ==
| |
| − | | |
| − | <ol>
| |
| − | | |
| − | <li>To create instances from the command line, you need to install the EC2 API tools:
| |
| − | | |
| − | <syntaxhighlight lang="console">$ nix-env -i ec2-api-tools</syntaxhighlight>
| |
| − | | |
| − | Alternatively, you can create NixOS instances using the [http://aws.amazon.com/console/ AWS Management Console].
| |
| − | | |
| − | <li>Start a small instance running NixOS:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ec2-run-instances -k gsg-keypair ami-c9f2d8bd
| |
| − | RESERVATION r-10ca4167 516444698777 default
| |
| − | INSTANCE i-f6d3b781 ami-c9f2d8bd pending gsg-keypair 0 m1.small ...</syntaxhighlight>
| |
| − | | |
| − | <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:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ec2-request-spot-instances -t m1.large -k gsg-keypair -p 0.3 ami-ecb49e98</syntaxhighlight>
| |
| − | | |
| − | <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>:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ssh -i id_rsa-gsg-keypair root@ec2-79-125-97-89.eu-west-1.compute.amazonaws.com</syntaxhighlight>
| |
| − | | |
| − | 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):
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ec2-authorize default -p 22 -s 0.0.0.0/0</syntaxhighlight>
| |
| − | | |
| − | <li>To start working with the instance, you may want to do the following to obtain the Nixpkgs and NixOS sources:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ nixos-checkout
| |
| − | $ nixos-rebuild pull</syntaxhighlight>
| |
| − | | |
| − | You should now be able to install software, e.g.
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ nix-env -i emacs</syntaxhighlight>
| |
| − | | |
| − | or reconfigure the instance:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ nano /etc/nixos/configuration.nix
| |
| − | $ nixos-rebuild switch</syntaxhighlight>
| |
| − | | |
| − | 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.
| + | 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. |
| − | | |
| − | </ol>
| |
| | | | |
| | == Creating a NixOS AMI == | | == 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. | + | 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>
| |
| − | | |
| − | <li>Install the EC2 AMI tools:
| |
| − | | |
| − | <syntaxhighlight lang="console">$ nix-env -i ec2-ami-tools</syntaxhighlight>
| |
| − | | |
| − | <li>The easy way to build NixOS AMIs is to run the following command:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ NIXOS=/path/to/nixos NIXPKGS=/path/to/nixpkgs /path/to/nixos/maintainers/scripts/ec2/create-amis.sh</syntaxhighlight>
| |
| − | | |
| − | You may need to edit the regions and stateDir variables in the create-amis.sh script.
| |
| − | 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:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ 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</syntaxhighlight>
| |
| − | | |
| − | (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>:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ls -l ./result/nixos.img
| |
| − | -r--r--r-- 1 root nixbld 4294967296 Jan 1 1970 ./result/nixos.img</syntaxhighlight>
| |
| − | | |
| − | <li>Bundle the image:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ 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.</syntaxhighlight>
| |
| − | | |
| − | 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:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ 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.
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | (Of course you can use any other bucket location as well.)
| |
| − | | |
| − | <li>Register the image as a private AMI:
| |
| − | | |
| − | <syntaxhighlight lang="console">
| |
| − | $ ec2-register nixos-img/nixos.img.manifest.xml -n nixos-img -d '...description...'
| |
| − | IMAGE ami-efffd59b</syntaxhighlight>
| |
| − | | |
| − | To make it public:
| |
| | | | |
| − | <syntaxhighlight lang="console">
| + | == Additional Resources == |
| − | $ ec2-modify-image-attribute ami-efffd59b -l -a all</syntaxhighlight>
| + | [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 |
| | | | |
| − | </ol> | + | == 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 <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. |
| | | | |
| | [[Category:Deployment]] | | [[Category:Deployment]] |
| | [[Category:Server]] | | [[Category:Server]] |