Getting Started with Acorn and Amazon EKS

This guide will help you to deploy a sample application using Acorn on top of Amazon Elastic Kubernetes Service (Amazon EKS). At the end of this tutorial, you will have a running app that you can manage using Acorn CLI.

Prerequisites

Before starting this tutorial, you must install and configure the following tools

• acorn – CLI for Installing Acorn control plane on Kubernetes cluster and deploying your apps. You can install it using brew or see Installing Acorn CLI docs.brew install acorn-io/cli/acorn
• kubectl – Install CLI using instructions.
• eksctl – CLI for working with EKS clusters that automate many individual tasks. You can install it using brew or see Installing or updating eksctl.brew install weaveworks/tap/eksctl
• aws CLI – CLI for configuring AWS credentials and default region. You can install it using the command line installer or see Installing AWS CLI_.curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" sudo installer -pkg AWSCLIV2.pkg -target _

We won’t be covering how to configure AWS CLI in this guide, so you can follow the official Getting Started instructions.

Once you have configured your AWS CLI with credentials, let’s start by creating the EKS cluster.

Create an EKS cluster

The below command will create cloud formation templates, node groups, deploy the EKS cluster, and set the kubectl context.

eksctl create cluster --name acorn-eks --region us-east-2

Once the deployment is done, you verify the status of the cluster using:

kubectl cluster-info

In case of any deployment issues, you can check eksctl troubleshooting guide here.

Let’s deploy the Ingress controller for Application traffic. We will be deploying the Nginx Ingress controller in this guide.

Deploy Nginx Ingress Controller

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.3.0/deploy/static/provider/aws/deploy.yaml

This will give us the base Kubernetes deployment will all the essential features to deploy the Acorn control plane.

Deploy Acorn Control Plane

As Acorn provides a public DNS service to test applications, we will install Acorn with DNS enabled and Nginx as an ingress class for applications to test our apps quickly.

acorn install --acorn-dns enabled --ingress-class-name nginx

You can check the Install status using.

acorn info

The above command will give additional information like cluster domain and other client and server configs.

Let’s deploy our first Acorn application.

Create Application

let’s start by creating a folder structure and a few files for our application

mkdir go-acorn && cd go-acorn

Create a file main.go containing the code of our web server

package main

import (
    "fmt"
    "log"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hi there, I love %s!", r.URL.Path[1:])
}

func main() {
    http.HandleFunc("/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

create another file go.mod

module go-acorn

go 1.18

Dockerfile

Now we have all the code and want to bundle it up in a Docker container. Create the Dockerfile with the following content:

FROM golang:1.18-alpine
WORKDIR /app
COPY go.mod .
RUN go mod download
COPY *.go ./
RUN go build -o /go-acorn
EXPOSE 8080
CMD [ "/go-acorn" ]

Acornfile

Create a file named Acornfile, which will be used to package our application into an OCI-compatible image.

containers: {
    "go-acorn": {
        build: {
            context: "."
        }
        ports: publish: "8080/http"
    }
}

Run your Application

To run your Acorn application, simply run:

acorn run -n go-acorn .

The above command will use the existing Dockerfile to build your application package and store it on an internal registry hosted as part of the Acorn control plane.

The -n go-acorn gives this app a specific name so the rest of the steps can refer to it. If you omit -n, a random two-word name will be generated.

Access your Application

You can get the information about your deployed apps by running the command:

acorn apps

$ acorn apps
NAME           IMAGE          HEALTHY   UP-TO-DATE   CREATED          ENDPOINTS                                                                        MESSAGE
go-acorn      de20c54dd4cb        1         1        64s ago          http://go-acorn.go-acorn.wk77wk.alpha.on-acorn.io => go-acorn:8080                    OK

Under the endpoints section, we can see the URL created for this application on Acorn DNS. For more information on endpoint naming conventions, refer to docs.

Access the application using your custom endpoint:

curl http://go-acorn.go-acorn.wk77wk.alpha.on-acorn.io/acorn

Hi there, I love acorn!

Until now, we have deployed our application using Acorn’s internal registry. Let’s create an ECR registry to push images on the custom registry.

Push Acorn Image to ECR

You can create an ECR repository using:

aws ecr create-repository --repository-name go-acorn \

--no-cli-pager --image-scanning-configuration scanOnPush=true

The output of the above command will look something like this:

{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-2:12345411519:repository/go-acorn",
        "registryId": "12345411519",
        "repositoryName": "go-acorn",
        "repositoryUri": "12345411519.dkr.ecr.us-east-2.amazonaws.com/go-acorn",
        "createdAt": "2022-08-19T17:06:52+08:00",
        "imageTagMutability": "MUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": true
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}

Once the repository is created, let’s go ahead and configure the credentials for Acorn to push images to ECR

Add ECR login credentials to Acorn

In the below command, replace the AWS_ACCOUNT_ID and REGION with your details from the above ECR repository create command output.

aws ecr get-login-password --region REGION | acorn login --username AWS \

--password-stdin AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com

The above command will create registry credentials on Acorn, which you can verify using:

$ acorn credentials
SERVER                                              USERNAME   CREATED
12345411519.dkr.ecr.us-east-2.amazonaws.com           AWS        3s ago

Build and Push Container image

For all the below commands, switch the URLs to your repository.

acorn build -t 12345411519.dkr.ecr.us-east-2.amazonaws.com/go-acorn:v1 .  
    
acorn push 12345411519.dkr.ecr.us-east-2.amazonaws.com/go-acorn:v1

Now you can update your application to use the image from the ECR registry using:

acorn update --image 12345411519.dkr.ecr.us-east-2.amazonaws.com/go-acorn:v1 go-acorn

$ acorn apps
NAME           IMAGE                                                           HEALTHY   UP-TO-DATE   CREATED   ENDPOINTS                                                                        MESSAGE
go-acorn   12345411519.dkr.ecr.us-east-2.amazonaws.com/go-acorn:v1   1         1            37m ago   http://go-acorn.go-acorn.wk77wk.alpha.on-acorn.io => go-acorn:8080   OK

Now your application is running with a container image from a custom registry.

Cleanup

Stop and Remove the application

You can stop and remove Acorn app using

acorn stop go-acorn
acorn rm go-acorn

Uninstall Acorn from K8s cluster

acorn uninstall --all

Delete ECR repository images

IMAGES_TO_DELETE=$( aws ecr list-images --region us-east-2 --repository-name go-acorn --query 'imageIds[*]' --output json )

aws ecr batch-delete-image --region us-east-2 --repository-name go-acorn --image-ids "$IMAGES_TO_DELETE" || true

Delete ECR repository

Before deleting the repository, you will need to remove the images

aws ecr delete-repository --repository-name go-acorn

Delete EKS cluster

eksctl delete cluster acorn-eks -r us-east-2