Run the Example Akka App

To make sure that your environment is set up correctly, install the example app and use Lightbend Orchestration reactive-cli to deploy it to Minikube. The main steps include:

  1. Install reactive-cli
  2. Download and configure the project
  3. Publish the app
  4. Set up RBAC
  5. Deploy with reactive-cli

Install reactive-cli

If you don’t have it already, install Lightbend Orchestration’s command line interface:

Using a command window, install reactive-cli:

OS X
brew install lightbend/tools/reactive-cli
Ubuntu
wget -qO - https://downloads.lightbend.com/rp/keys/bintray-debian | \
    sudo apt-key add - && \
    echo "deb https://dl.bintray.com/lightbend/deb $(lsb_release -cs) main" | \
    sudo tee /etc/apt/sources.list.d/lightbend.list && \
    sudo apt-get install apt-transport-https -y && \
    sudo apt-get update && \
    sudo apt-get install reactive-cli

Download and configure the project

Clone the example and configure it to use the sbt-reactive-app plugin, which will enable you to deploy to the Minikube cluster:

  1. Using a command window, clone the tutorial project:

    git clone -b tutorial https://github.com/lightbend/akka-cluster-orchestration-example.git

  2. Change into the example directory:

    cd akka-cluster-orchestration-example

  3. Using any editor, open the project/plugins.sbt file and add a dependency on the sbt-reactive-app plugin: addSbtPlugin("com.lightbend.rp" % "sbt-reactive-app" % "1.5.0")

  4. In the top level project directory, open build.sbt and add the following lines:

// Enable plugin.
enablePlugins(SbtReactiveAppPlugin)

// Enable akka-cluster bootstrapping inside of k8s.
// Allows easy building of an akka cluster by just adding more pods.
enableAkkaClusterBootstrap := true

// Expose http endpoint.
endpoints += HttpEndpoint("http", 8080, HttpIngress(Seq(80), Seq("tutorial.io"), Seq("/")))

Publish the app

Check to make sure that Minikube is running and you have access to the Lightbend Console. (See the Installation Guide if you have any issues.) Then, build a docker image for your application and publish it using the following commands:

eval $(minikube docker-env)
sbt docker:publishLocal

Set up RBAC

The Akka cluster needs to query the Kubernetes apiserver for pod information. Recent Kubernetes versions enable RBAC by default, which prevents default access to the apiserver. You need to set up an RBAC role to assign a role to the default system account that every pod inherits. This grants access to the Akka cluster.

First, create the file rbac.yaml in the top level project directory with the following contents:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
  resources: ["pods"]
  verbs: ["get", "watch", "list"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: read-pods
subjects:
- kind: User
  name: system:serviceaccount:default:default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Next, apply the file to the cluster:

kubectl apply -f rbac.yaml

A message should confirm that pod-reader and read-pods were created. Note that if you had previously used a pod-reader, it will remain unchanged.

Deploy with reactive-cli

First, deploy your application using the reactive-cli tool:

# Create deployment and service resources.
rp generate-kubernetes-resources "akka-cluster-orchestration-example:0.1.0" \
  --generate-pod-controllers --generate-services \
  --pod-controller-replicas 4 | kubectl apply -f -

A message should confirm that the application was created.

Next, create an ingress resource:

# Creates ingress resource.
rp generate-kubernetes-resources \
  --generate-ingress --ingress-name tutorial \
  "akka-cluster-orchestration-example:0.1.0" | kubectl apply -f -

A message should confirm that the Ingress extension for the tutorial was created.

Check the app

After a minute, your application should be up with four cluster members. You can check the status of the application with kubectl:

kubectl get pod

If there are any errors, you can investigate further with kubectl commands such as kubectl describe pod <pod-name>.

You should now be able to see the app as a Workload in the Minikube dashboard and as a Pod in the Lightbend Console. As a reminder, if you don’t have the Console open, find the minikube IP:

$ minikube ip

Using the IP, view the Lightbend console at minikube-ip:30080. The default will be http://192.168.99.100:30080.

Now that you are sure that your environment is configured correctly, instrument the app with Telemetry.