Step 1: Set up for this tutorial Step 2: Create the project Step 3: Write the code Step 4: Build and run the application Next steps

Get started with the SDK for Kotlin

The AWS SDK for Kotlin provides Kotlin APIs for each AWS service. Using the SDK, you can build Kotlin applications that work with Amazon S3, Amazon EC2, Amazon DynamoDB, and more.

This tutorial shows you how to use Gradle to define dependencies for the AWS SDK for Kotlin. Then, you create code that writes data to a DynamoDB table. Although you might want to use the features of an IDE, all you need for this tutorial is a terminal window and a text editor.

Follow these steps to complete this tutorial:

Step 1: Set up for this tutorial
Step 2: Create the project
Step 3: Write the code
Step 4: Build and run the application

Step 1: Set up for this tutorial

Before you begin this tutorial, you need an active AWS account, an AWS Identity and Access Management (IAM) user with a programmatic access key and permissions to access DynamoDB. You also need a Java development environment that is configured to use the access key as credentials for AWS services.

Follow these steps to set up for this tutorial:

Create an AWS account
Create an IAM user
Install Java and Gradle
Configure credentials

Create an AWS account and an administrator IAM user

If you do not have an AWS account, visit the Amazon Web Services signup page and follow the on-screen prompts to create and activate a new account. For detailed instructions, see How do I create and activate a new AWS account?. After the account is active, sign in to your account using the root user credentials .

Next, create an administrator IAM user. The following procedure shows you how to do so. These instructions are also detailed in Creating an administrator IAM user and user group in the AWS Identity and Access Management User Guide.

Sign in to your account in the AWS Management Console as the administrator, not the root user. For more information, see Security best practices in IAM in the AWS Identity and Access Management User Guide.

Create an IAM user

For this tutorial, create another IAM user that has restricted, programmatic access. Give the user read and write access to DynamoDB. Programmatic access uses access keys for credentials.

To create an IAM user with restricted access

Sign in to the IAM console.
In the navigation pane on the left, choose Users. Then choose Add user.
Enter TestSDK as the User name and select the Access key - Programmatic access check box. Choose Next: Permissions.
Under Set permissions, select Attach existing policies directly.
In the list of policies, select the check box for the AmazonS3FullAccess policy. Choose Next: Tags.
Choose Next: Review. Then choose Create user.
On the Success screen, choose Download .csv.

The downloaded file contains the access key ID and the secret access key for this tutorial. Treat your secret access key as a password. Save it in a secure location and do not share it.

Note
You do not have another opportunity to download or copy the secret access key.

Install Java and Gradle

In your development environment, install Java 8 or later and Gradle.

For Java, use Oracle Java SE Development Kit, Amazon Corretto, Red Hat OpenJDK, or AdoptOpenJDK.
For Gradle, see https://gradle.org/install/.

Configure credentials

Configure your development environment with the TestSDK user access key ID and the secret access key. The AWS SDK for Kotlin uses this access key as credentials when your application makes requests to AWS services.

In a text editor, create a new file named credentials with the following code:


[default]
aws_access_key_id = TestSDK_AWS_ACCESS_KEY_ID
aws_secret_access_key = TestSDK_AWS_SECRET_ACCESS_KEY

In the new text file, replace Test_AWS_ACCESS_KEY with the TestSDK AWS access key ID, and replace TestSDK_AWS_SECRET_ACCESS_KEY with the TestSDK AWS secret access key. These are the values that you downloaded in step 7 of the procedure in the Create an IAM user section.

Save the file without a file extension (name it credentials). Refer to the following table for the correct location and file name based on your operating system.

Operating system	File name
Windows	`C:\Users\USERNAME\.aws\credentials`
Linux, macOS, or Unix	`~/.aws/credentials`

Step 2: Create the project

To create the project for this tutorial, first use Gradle to create a Kotlin project. Then, update the gradle.build.kts file with the required settings and dependencies for the AWS SDK for Kotlin.

To create a new project using Gradle

Create a new directory called get-started in a location of your choice, such as your desktop or home folder.
Open a terminal or command prompt window and navigate to the get-started directory you created.
Use the following command to create a new Gradle project configuration file (build.gradle.kts) and a basic Kotlin class.
```
gradle init --type kotlin-application --dsl kotlin
```
- When prompted with Generate build using new APIs and behavior, press the Enter key.
- When prompted with Project name, press Enter.
- When prompted for Source package, enter example.aws.getstarted.

To configure your project with dependencies for the AWS SDK for Kotlin and Amazon S3

In the folder get-started that you created in the previous procedure, open the build.gradle.kts file.

Replace its contents with the following Gradle code, and then save your changes.

Note

For the latest version of the Amazon S3 module of the SDK for Kotlin, see the Maven central repository and use that value in the following code.


import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    kotlin("jvm") version "1.7.10"
    application
}

group = "example.aws"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation("aws.sdk.kotlin:s3:0.17.5-beta")
    testImplementation(kotlin("test"))
}

tasks.withType<Test> {
    useJUnitPlatform()
}

tasks.withType<KotlinCompile>() {
    kotlinOptions.jvmTarget = "1.8"
}

application.mainClass.set("example.aws.getstarted.AppKt")

The dependencies section contains an entry for the Amazon S3 module of the AWS SDK for Kotlin. The Gradle compiler is configured to use Java 1.8 in the tasks.withType<KotlinCompile>() section.

Step 3: Write the code

After the project has been created and configured, edit the project’s default class App to use the following example code.

In your project folder app, navigate to the directory src/main/kotlin/com/example/getstarted. Open the App.kt file.

Replace its contents with the following code and save the file.


package example.aws.getstarted

import aws.sdk.kotlin.services.s3.*
import aws.sdk.kotlin.services.s3.model.BucketLocationConstraint
import aws.smithy.kotlin.runtime.content.ByteStream
import kotlinx.coroutines.runBlocking
import java.util.UUID

val REGION = "us-west-2"
val BUCKET = "bucket-${UUID.randomUUID()}"
val KEY = "key"

fun main(): Unit = runBlocking {
    S3Client
        .fromEnvironment { region = REGION }
        .use { s3 ->
            setupTutorial(s3)

            println("Creating object $BUCKET/$KEY...")

            s3.putObject {
                bucket = BUCKET
                key = KEY
                body = ByteStream.fromString("Testing with the Kotlin SDK")
            }

            println("Object $BUCKET/$KEY created successfully!")

            cleanUp(s3)
        }
}

suspend fun setupTutorial(s3: S3Client) {
    println("Creating bucket $BUCKET...")
    s3.createBucket {
        bucket = BUCKET
        createBucketConfiguration {
            locationConstraint = BucketLocationConstraint.fromValue(REGION)
        }
    }
    println("Bucket $BUCKET created successfully!")
}

suspend fun cleanUp(s3: S3Client) {
    println("Deleting object $BUCKET/$KEY...")
    s3.deleteObject {
        bucket = BUCKET
        key = KEY
    }
    println("Object $BUCKET/$KEY deleted successfully!")

    println("Deleting bucket $BUCKET...")
    s3.deleteBucket {
        bucket = BUCKET
    }
    println("Bucket $BUCKET deleted successfully!")
}

Step 4: Build and run the application

After the project is created and contains the example class, build and run the application.

Open a terminal or command prompt window and navigate to your project directory get-started.
Use the following command to build and run your application:
```
gradle run
```

The application calls the createBucket API operation to create a new S3 bucket and then calls putObject to put a new object into the new S3 bucket.

In the cleanUp() function at the end, the application deletes the object and then deletes the S3 bucket.

To see the results in the Amazon S3 console

In App.kt, comment out the line cleanUp(s3) in the runBlocking section and save the file.
Rebuild the project and put a new object into a new S3 bucket by running gradle run.
Sign in to the Amazon S3 console to view the new object in the new S3 bucket.

After you view the object, delete the S3 bucket.

Success

If your Gradle project built and ran without error, then congratulations. You have successfully built your first Kotlin application using the AWS SDK for Kotlin.

Cleanup

When you are done developing your new application, delete any AWS resources that you created during this tutorial to avoid incurring any charges. You might also want to delete or archive the project folder (get-started) that you created in Step 2.

Follow these steps to clean up resources:

If you commented out the call to the cleanUp() function, delete the S3 bucket in the Amazon S3 console.

In the IAM console, delete the TestSDK user.

If you delete this user, also remove the contents of the credentials file that you created during setup.

Next steps

Now that you have the basics down, you can learn about the following:

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

What is the AWS SDK for Kotlin?

Set up