Install NixOS on Amazon EC2: Difference between revisions

From NixOS Wiki
imported>Tamiyo
No edit summary
imported>Tamiyo
remove outdated information & replace it with some updated info
Line 1: Line 1:
{{outdated}}
{{outdated}}


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.
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:
 
* <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 ==
Line 18: Line 8:


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 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.
== 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.
</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">
$ ec2-modify-image-attribute ami-efffd59b -l -a all</syntaxhighlight>
 
</ol>


[[Category:Deployment]]
[[Category:Deployment]]
[[Category:Server]]
[[Category:Server]]

Revision as of 21:09, 2 January 2024

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.

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.