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