Live-coding a Rust crate for short EC2 jobs (part 1)

Introduction

This tutorial provides a step-by-step guide for building a Rust crate designed to run short-lived jobs on EC2 spot block instances. Aimed at users familiar with Rust, this guide will help you gain practical experience in a larger project. By following these steps, you will learn how to interface with EC2, manage VM connections, and improve your client API.

Step 1: Setting Up Your Rust Environment

To begin, ensure that you have a Rust development environment configured on your machine.

1. Install Rust:

   • Use rustup to install Rust. This will also install cargo, the Rust package manager.

2. Create a New Project:

   • Open a terminal and create a new Rust crate:

     cargo new tsunami
     cd tsunami
     

3. Add Dependencies:

   • Open Cargo.toml and add any necessary dependencies for AWS SDK or other libraries you might need:

     [dependencies]
     aws-sdk-ec2 = "0.0.26" # Check for the latest version
     tokio = { version = "1", features = ["full"] }
     

Step 2: Interfacing with EC2

Now that your environment is set up, you will learn how to interface with EC2.

1. Configure AWS Credentials:

   • Set up your AWS credentials by creating a file at ~/.aws/credentials with the following format:

     [default]
     aws_access_key_id = YOUR_ACCESS_KEY
     aws_secret_access_key = YOUR_SECRET_KEY
     

2. Implement EC2 Client:

   • In src/main.rs, create an EC2 client to interact with AWS services:

     use aws_sdk_ec2::{Client, Config, Region};
     use aws_types::credentials::Credentials;
     
     async fn create_ec2_client() -> Client {
         let shared_config = aws_config::load_from_env().await;
         Client::new(&shared_config)
     }
     

Step 3: Establishing VM Connections

In this step, you will learn how to connect to EC2 instances and manage SSH connections.

1. Launch an EC2 Instance:

   • Use the EC2 client to launch an instance:

     let run_response = ec2_client.run_instances()
         .instance_type("t2.micro")
         .image_id("ami-0c55b159cbfafe1f0") // Update with a valid AMI ID
         .max_count(1)
         .min_count(1)
         .send()
         .await?;
     

2. Connect via SSH:

   • Implement a method to handle SSH connections to the instance once it is running. You can use the tokio-ssh crate for this.

Step 4: Tidying Up the Client API

As your project grows, it's important to keep your code organized.

1. Refactor Your Code:

   • Break down large functions into smaller, reusable ones.
   • Create a module for EC2 interactions to keep your main.rs clean.

2. Implement Error Handling:

   • Use the failure crate to manage errors gracefully:

     #[derive(Debug, Fail)]
     pub enum MyError {
         #[fail(display = "Error occurred: {}", _0)]
         CustomError(String),
     }
     

Conclusion

In this first part of the tutorial, you set up a Rust environment, interfaced with EC2, and learned how to manage VM connections. Key takeaways include setting up AWS credentials, launching EC2 instances, and organizing your Rust code effectively. For further learning, consider exploring the second part of this series to continue building your Rust crate. You can find the code for this project on GitHub.