Installation on Amazon Elastic Kubernetes Service (EKS)

To install Akka Cloud Platform on Amazon Elastic Kubernetes Service (EKS), you must have an Amazon account and a subscription to the Akka Cloud Platform new tab.

Expected Time to Install

A new installation will take approximately 40 minutes.

  • Provision Amazon EKS cluster - 30 minutes - Depends on how many nodes are provisioned and what instance types are chosen. It is also variable based on day-to-day AWS region conditions. This estimate is for the cluster parameters described in this guide.

  • Install pre-requisities into Amazon EKS - 5 minutes - Subscribe to product, install a Kubernetes metrics-server, and set up a service account.

  • Install Akka Cloud Platform - 5 minutes - Installation of the Akka Cloud Platform helm chart with minimal configuration.

Akka Cloud Platform supports metrics-server up to 0.4.4. Installing newer versions will result in an error when using Akka Cloud Platform operator.

Pre-requisite Skills

A familiarity with the following services and skillsets is recommended before installation.

1. Verify Prerequisites

To install and use the Akka Cloud Platform, you must have the following tools installed. We recommend using the latest versions of these tools. If you do not have them yet or need to update, we provide links to installation instructions:

  • The Kubernetes command-line tool, kubectl, allows you to run commands against Kubernetes clusters. Follow the instructions in the Kubernetes documentation new tab to install kubectl.

  • Helm is required to install the Akka Operator in the Kubernetes cluster. Follow the instructions in the Helm documentation new tab to install helm.

  • The AWS Command Line Interface (AWS CLI) enables you to interact with AWS services using commands in your command-line shell. Follow the instructions in the AWS documentation new tab to install aws.

  • The eksctl command line utility provides the ability to create and manage Kubernetes clusters on Amazon EKS. Follow the instructions in the AWS documentation new tab to install eksctl.

2. Login to your AWS account

If you are a first time AWS user, please register your account at https://aws.amazon.com/ new tab.

  1. Navigate to AWS Identity and Access Management (IAM) console new tab to create a user and create access keys under Security Credential tab.

  2. Open a terminal and from a command prompt use the aws tool to install the credentials:

aws configure

3. Create a Kubernetes cluster

A typical cluster takes up to 30 minutes to create.

When following the instructions below, replace:

  • eks-akka-demo with your own EKS cluster name

  • eu-central-1 with your preferred AWS region

You can create a Kubernetes cluster with the eksctl command line tool. For example:

eksctl create cluster \
  --name eks-akka-demo \
  --version 1.17 \
  --region eu-central-1 \
  --nodegroup-name linux-nodes \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 4 \
  --with-oidc \
  --managed

An alternative is to create it from the Amazon EKS console new tab.

  • We recommend using EKS with EC2 nodes, and not the Fargate option that is available in the EKS console.

  • You should create the cluster with IAM roles for service accounts enabled.

After the cluster is available, configure kubectl to connect to the cluster

aws eks update-kubeconfig --region eu-central-1 --name eks-akka-demo

4. Install the Kubernetes Metrics Server

The Akka Operator depends on the Kubernetes Metrics Server new tab being installed. It is used for usage metering and billing.

You can install version 0.4.4 with:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.4.4/components.yaml

5. AWS Marketplace

If you have not already done it, subscribe to the Akka Cloud Platform new tab by clicking the Subscribe button on the product page and accepting the terms and conditions.

6. Create a service account for the Akka Operator

The Akka Operator requires a service account with IAM roles new tab in order to access the Amazon Marketplace usage metering API.

  1. If your Amazon EKS cluster has not been created with IAM OIDC provider new tab (e.g. with the --with-oidc option with eksctl), enable it with:

    eksctl utils associate-iam-oidc-provider \
        --cluster eks-akka-demo \
        --region eu-central-1 \
        --approve
  2. Create an IAM policy for the service account:

    1. Create a policy.json file with content:

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "aws-marketplace:MeterUsage"
                  ],
                  "Resource": "*"
              }
          ]
      }
    2. Create the AkkaPlatformOperator policy:

      aws iam create-policy \
          --policy-name AkkaPlatformOperator \
          --policy-document file://policy.json

      Make a note of the policy ARN for the next step.

      If the AkkaPlatformOperator policy already exists you can retrieve the policy ARN with:

      aws iam list-policies
  3. Create the iamserviceaccount:

    eksctl create iamserviceaccount \
        --name akka-operator \
        --namespace lightbend \
        --cluster eks-akka-demo \
        --region eu-central-1 \
        --attach-policy-arn <policy_arn> \
        --approve \
        --override-existing-serviceaccounts

If creation of the service account fails for any reason, it is important to delete it before trying to re-create it. Otherwise, eksctl can skip creation of the service account. If this happens the output will contain:

[ℹ]  2 iamserviceaccounts (kube-system/aws-node, lightbend/akka-operator) were excluded (based on the include/exclude rules)

To delete the service account, run the following:

eksctl delete iamserviceaccount  \
    --name akka-operator \
    --namespace lightbend \
    --cluster eks-akka-demo \
    --region eu-central-1

7. Install Akka Operator

Install the Akka Operator with Helm:

  1. Add the Akka Operator Helm repository and update the local index:

    helm repo add akka-operator-helm https://lightbend.github.io/akka-operator-helm/
    helm repo update
  2. Install the latest version with:

    helm install akka-operator akka-operator-helm/akka-operator \
      --namespace lightbend \
      --create-namespace \
      --set serviceAccount.name=akka-operator
  3. Verify that the operator is running:

    kubectl get pods --namespace lightbend

The Akka Cloud Platform Helm chart adheres to the Principle of least privilege new tab with the Kubernetes cluster roles that are granted to the operator. For a complete list of Kubernetes cluster roles required by Akka Cloud Platform you may review the ClusterRole template found in the Helm Chart new tab.

With the Akka Operator running, you can deploy an Akka Microservice. The next page, Deployment workflow, provides general steps. The tutorial includes examples of build and template files.

Update Akka Operator

To update the Akka Operator version you have to update the Custom Resource Definition (CRD) separately because Helm will not perform that.

  1. Update the Akka Microservices CRD:

    kubectl apply -f  https://lightbend.github.io/akka-operator-helm/akka-operator/crds/v1/akka-microservices-crd.yml
  2. Update the Akka Operator with Helm.

    Add the Akka Operator Helm repository and update the local index:

    helm repo add akka-operator-helm https://lightbend.github.io/akka-operator-helm/
    helm repo update

    Pick a version upgrade to.

    helm search repo akka-operator-helm/akka-operator --versions

    Upgrade the chart.

    helm upgrade akka-operator akka-operator-helm/akka-operator \
      --version=<version> \
      --namespace lightbend \
      --set serviceAccount.name=akka-operator

Verify that the operator is running:

kubectl get pods --namespace lightbend

Uninstall Akka Operator

Delete the akka-operator with Helm:

helm delete akka-operator --namespace lightbend

Delete CRD:

kubectl delete customresourcedefinition akkamicroservices.akka.lightbend.com

Delete a Kubernetes cluster

eksctl delete cluster \
    --region eu-central-1 \
    --name eks-akka-demo
Deleting the cluster from the Amazon EKS console new tab requires several steps and therefore it’s easiest to use eksctl for this.

Troubleshooting

Cluster creation fails with "Cannot create cluster '<CLUSTER_NAME>' because <AWS_REGION>, the targeted availability zone does not currently have sufficient capacity

Creating an Amazon EKS cluster will provision many underlying AWS resources such as VPCs, Security Groups, EC2 instances, Elastic IPs, etc. All AWS accounts have default quotas for the number of resources that can be created per region. If you already have an EKS cluster or other AWS resources deployed in a region you may receive this error while creating an Amazon EKS cluster. To resolve you can pick a different region, clean up existing resources, or make a request to AWS for a higher resource quota new tab.

Akka Operator pod in ImagePullBackoff status

After the Akka Cloud Platform Helm chart is installed you observe an ImagePullBackOff status on a pod for the akka-operator Deployment. When you describe the pod you may find a Failed event, this will inckude a Docker pull error message that mentions "You are not entitled to pull this AWS Marketplace product image". This will occur when your AWS account is not subscribed to the Akka Cloud Platform on AWS Marketplace. To resolve you must subscribe to the product and then wait for the akka-operator pod to restart and attempt to pull the image again.