> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/dragen/dragen-v4.6/reference/dragen-multi-cloud/dragen-on-aws.md). # DRAGEN on AWS You can run DRAGEN analysis on Amazon Web Services (AWS). For information on using DRAGEN, see the [DRAGEN User Guide Section](/dragen/dragen-v4.6/product-guides/dragen-v4.6.md). For information on using AWS, see the AMI documentation available on the Amazon Web Services site. ### Getting Access to the DRAGEN AMI (Amazon Machine Image) There are two options available for using the AMI: a Marketplace AMI (Pay-As-You-Go) and a Private AMI (Bring-Your-Own-License). To use the Marketplace AMI, visit the AWS Marketplace and subscribe to the DRAGEN Complete Suite. For access to the Private AMI, please contact our [sales team](https://www.illumina.com/company/contact-us.html#/sales) to obtain licensing and deployment instructions. Private AMI runs are licensed with an Illumina BioInsight Platform API key, see [BioInsight Platform Licensing](/dragen/dragen-v4.6/reference/licensing/api_key_licensing.md). Existing deployments that use legacy license credentials are covered in [Legacy DRAGEN Cloud Licensing](/dragen/dragen-v4.6/reference/licensing/cloud_licensing.md). ### Building your own DRAGEN AMI 1. Choose a base AMI. We recommend [Rocky Linux](https://rockylinux.org) 8.x. 1. At the [download page](https://rockylinux.org/download), under Cloud Images, click Rocky Linux 8, and then under Cloud Providers, click AWS AMI. 2. In the popup, filter by your AWS region. For example, "us-east-1". From the results, choose an 8.10 x86\_64 image. 3. Click deploy and launch an instance. 2. Once the instance is ready, log into it as user: rocky 3. Install dragen. 1. For hardware accelerated mode using F2 instances: 1. Download the Illumina DRAGEN GPG public key to the instance 2. Import the key: `rpm --import /path/to/key` 3. Download and install the following DRAGEN RPMs from the **DRAGEN - Getting Started** app, which you can open from the Illumina BioInsight Platform home page or at [dragen.illumina.com](https://dragen.illumina.com). The app can provide a download link so you can fetch the RPMs directly on the instance. * edico\_driver * dragen-aws 2. For software only mode on other instance types: 1. Follow the [Obtain and Install](/dragen/dragen-v4.6/reference/software-mode.md#obtain-and-install) instructions 2. [Update ulimits](/dragen/dragen-v4.6/reference/software-mode.md#file-handles-and-user-processes) 4. Create an AMI from your instance. Follow the [Create an Amazon EBC-backed AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami-ebs.html) guide. ### Launch an Instance To launch an EC2 instance, refer to the [AWS EC2 Launch Guide documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html) - making sure you select the desired DRAGEN AMI and instance type. * For instance type, an [EC2 FPGA-powered instance](https://aws.amazon.com/ec2/instance-types/f2/) is required. `f2.6xlarge` is recommended. * For configure storage, we recommend attaching 2TB of EBS storage using 4x 500GB GP3 volumes configured as RAID0, if local instance storage is insufficient ### Connect to and Configure Your Instance 1. Navigate to the Instances page and select the instance to connect to. 2. Click **Connect**, then choose **SSH client**. 3. instanceUse appropriate username: ec2-user for EL8 images, or centos for EL7 images. 4. Mount the disks to `/staging` on the instance using the following commands as needed. ``` sudo yum -y install mdadm sudo mdadm --create --verbose /dev/md0 --level=0 --name=MY_RAID0 --raid-devices= sudo mkfs.ext4 -L MY_RAID0 /dev/md0 sudo mkdir -p /staging sudo sh -c "echo 'LABEL=MY_RAID0 /staging ext4 defaults,noatime 0 0' >> /etc/fstab" sudo mount -a ``` For example, the following command mounts four volumes attached at `/dev/nvme1n1`, `/dev/nvme2n1`, `/dev/nvme3n1`, and `/dev/nvme4n1` to a RAID 0 on `/staging`. ``` sudo yum -y install mdadm sudo mdadm --create --verbose /dev/md0 --level=0 --name=MY_RAID0 --raid-devices=4 /dev/nvme1n1 /dev/nvme2n1 /dev/nvme3n1 /dev/nvme4n1 sudo mkfs.ext4 -L MY_RAID0 /dev/md0 sudo mkdir -p /staging sudo sh -c "echo 'LABEL=MY_RAID0 /staging ext4 defaults,noatime 0 0' >> /etc/fstab" sudo mount -a ``` ### Data Flow Input files, including the [hash table](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html), must be downloaded to the instance. DRAGEN can also process large input files (e.g., FASTQ, BAM) directly from s3 or a pre-signed URL. Ensure the instance has access to the s3 bucket via local credentials or an IAM role. ### Simple Run Example ``` cd /staging/ wget https://webdata.illumina.com/downloads/software/dragen/resource-files/hg38-alt_masked.cnv.graph.hla.rna-10-r4.0-1.tar.gz mkdir /staging/hg38-alt_masked.cnv.graph.hla.rna-10-r4.0-1 tar xvfz hg38-alt_masked.cnv.graph.hla.rna-10-r4.0-1.tar.gz -C hg38-alt_masked.cnv.graph.hla.rna-10-r4.0-1 wget https://ilmn-dragen-giab-samples.s3.amazonaws.com/WES/HG002/NA24385-AJ-Son-R1-NS_S33_L001_R2_001.fastq.gz wget https://ilmn-dragen-giab-samples.s3.amazonaws.com/WES/HG002/NA24385-AJ-Son-R1-NS_S33_L001_R1_001.fastq.gz dragen \ -r /staging/hg38-alt_masked.cnv.graph.hla.rna-10-r4.0-1 \ --fastq-file1 /staging/NA24385-AJ-Son-R1-NS_S33_L001_R2_001.fastq.gz \ --fastq-file2 /staging/NA24385-AJ-Son-R1-NS_S33_L001_R2_001.fastq.gz \ --RGID NA24385_RGID \ --RGSM NA24385 \ --enable-map-align true \ --enable-map-align-output true \ --enable-duplicate-marking true \ --enable-variant-caller true \ --output-file-prefix NA24385 \ --output-directory /staging/ \ --api-key-file /path/to/api_key.txt # needed for private AMI users ``` You can use DRAGEN command-line options. For more information on DRAGEN analysis and command line options, see the [Command Line Options Section](/dragen/dragen-v4.6/product-guides/dragen-v4.6/command-line-options.md) of the user guide. For information on using AWS, see the AMI documentation available on the Amazon Web Services site. ### Instance Identity DRAGEN FPGA Mode BYOL runs on AWS read the local instance identity document from the instance metadata service and use it to authenticate the run. DRAGEN uses the IPv4 local address, so licensing fails if access to that address is blocked. If you would rather not let applications reach the metadata service, save the instance identity documents yourself and point DRAGEN at the folder that holds them, using either `--lic-instance-id-location ` or the `DRAGEN_INSTANCE_IDENTITY` environment variable. The documents only need to be saved once per account and region, and the saved files can be reused after that. DRAGEN supports both AWS IMDSv1 and the more secure AWS IMDSv2, and detects which version is in use. IMDSv2 must be enabled on the instance, otherwise IMDSv1 is used by default. See [AWS Instance Metadata Service Information](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html). {% hint style="warning" %} **Version requirement**: IMDSv2 is only supported in **DRAGEN 4.3 and above**. Earlier versions only support IMDSv1. For input streaming from an S3 bucket, DRAGEN 4.4 and earlier support IMDSv1 only. {% endhint %} If you use IMDSv2 and run DRAGEN in a container, you may need to [increase the default](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-existing-instances.html#modify-PUT-response-hop-limit) hop count to at least 2. The instance identity folder must contain three files, named `pkcs7`, `signature`, and `document`. {% tabs %} {% tab title="IMDSv1" %} ```bash curl -v -H Metadata:true --noproxy "*" "http://169.254.169.254/latest/dynamic/instance-identity/pkcs7" -o /opt/instance-identity/pkcs7 curl -v -H Metadata:true --noproxy "*" "http://169.254.169.254/latest/dynamic/instance-identity/document" -o /opt/instance-identity/document cp /opt/instance-identity/pkcs7 /opt/instance-identity/signature ``` {% endtab %} {% tab title="IMDSv2" %} ```bash curl -X PUT -H "X-aws-ec2-metadata-token-ttl-seconds: 300" -H "X-aws-ec2-metadata-token: required" --noproxy "*" "http://169.254.169.254/latest/api/token" curl -H "X-aws-ec2-metadata-token: " --noproxy "*" "http://169.254.169.254/latest/dynamic/instance-identity/document" curl -H "X-aws-ec2-metadata-token: " --noproxy "*" "http://169.254.169.254/latest/dynamic/instance-identity/signature" curl -H "X-aws-ec2-metadata-token: " --noproxy "*" "http://169.254.169.254/latest/dynamic/instance-identity/pkcs7" ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.connected.illumina.com/dragen/dragen-v4.6/reference/dragen-multi-cloud/dragen-on-aws.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.