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.
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, for that 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.
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 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.
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.
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 various other client and server config.
Let's deploy our first Acorn 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
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" ]
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"
}
}
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 that the rest of the steps can refer to it. If you omit -n, a random two-word name will be generated.
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.
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 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
In the below command, replace the AWS_ACCOUNT_ID and REGION with your details from above ECR repository create 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
For all the below commands, switch the URLs to your own 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 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.
You can stop and remove Acorn app using
acorn stop go-acorn
acorn rm go-acorn
acorn uninstall --all
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
Before deleting the repository, you will need to remove the images
aws ecr delete-repository --repository-name go-acorn
eksctl delete cluster acorn-eks -r us-east-2