Skip to content
A tutorial for how to use the Eclipse MicroProfile Kabanero Collection and Appsody CLI to create, run, update, deploy, and deliver cloud native microservices.
Branch: master
Clone or download
Pull request Compare This branch is 13 commits behind kabanero-io:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
README.adoc

README.adoc

Developing cloud native microservices with the Eclipse MicroProfile Collection and Appsody CLI

Note
This repository contains the guide documentation source. To view the guide in published form, view it on the website.

Explore how to use the Eclipse MicroProfile Kabanero Collection and Appsody CLI to create, run, update, deploy, and deliver cloud native microservices.

What you’ll learn

You will learn how to create and run a simple cloud native microservice. Then, you’ll update the microservice that you created and deploy it to Kubernetes or Knative. This will all be done by using the Eclipse MicroProfile Kabanero Collection with the Appsody CLI.

Kabanero’s Eclipse MicroProfile Collection provides a stack that enables the development and optimization of microservices. Applications are written based on the Eclipse MicroProfile API specifications, and built and run with the Open Liberty runtime.

Prerequisites

  1. Docker must be installed.

  2. You must have access to a Kubernetes cluster. If you are using Docker for Desktop, you can enable Kubernetes from the menu by selecting Preferences → Kubernetes → Enable Kubernetes.

  3. Appsody must be installed.

  4. (Optional) If you have an enterprise-specific Kabanero Collection Hub, you need the URL to your index file.

Getting started

Configuring Appsody

Add your Kabanero index to the Appsody CLI. The following example uses the public index for Kabanero Version 0.1.2.

To check the repositories that Appsody can already access, run the following command:

appsody repo list

You see an output similar to the following example:

appsody repo list
NAME        URL
*appsodyhub https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml

Next, run the following command to add the Kabanero index:

appsody repo add kabanero https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml

Check the existing repositories to see that it was added:

appsody repo list
NAME        URL
*appsodyhub https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml
kabanero    https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml

In this example, the asterisk (*) shows that appsodyhub is the default repository. Run the following command to set the Kabanero index as the default repository:

appsody repo set-default kabanero

Check the existing repositories to see that it was updated:

appsody repo list
NAME        URL
appsodyhub  https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml
*kabanero   https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml

Your Appsody CLI is now configured to use the Kabanero Collections. Next, you need to initialize your project.

Initializing your project

First, create a directory that will contain the project:

mkdir -p ~/projects/simple-microprofile
cd ~/projects/simple-microprofile

Run the following command to initialize the project with the Appsody CLI:

appsody init java-microprofile

The output from the command varies depending on whether you have an installation of Java and Maven on your system. If Java and Maven are installed on your system, you see an output similar to the following example:

[InitScript] [INFO] -------------------< dev.appsody:java-microprofile >--------------------
[InitScript] [INFO] Building java-microprofile 0.2.11
[InitScript] [INFO] --------------------------------[ pom ]---------------------------------
[InitScript] [INFO]
[InitScript] [INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-versions) @ java-microprofile ---
[InitScript] [INFO] Skipping Rule Enforcement.
[InitScript] [INFO]
[InitScript] [INFO] --- maven-install-plugin:2.4:install (default-install) @ java-microprofile ---
[InitScript] [INFO] Installing /Users/myuser/projects/simple-microprofile/.appsody_init/pom.xml to /Users/myuser/.m2/repository/dev/appsody/java-microprofile/0.2.11/java-microprofile-0.2.11.pom
[InitScript] [INFO] ------------------------------------------------------------------------
[InitScript] [INFO] BUILD SUCCESS
[InitScript] [INFO] ------------------------------------------------------------------------
[InitScript] [INFO] Total time:  0.648 s
[InitScript] [INFO] Finished at: 2019-09-13T10:17:55+01:00
[InitScript] [INFO] ------------------------------------------------------------------------
Successfully initialized Appsody project

If Java and Maven are not installed on your system, you see an output similar to the following example:

[InitScript] Unable to find any JVMs matching version "(null)".
[InitScript] No Java runtime present, try --request to install.
[InitScript] Unable to find a $JAVA_HOME at "/usr", continuing with system-provided Java...
[InitScript] No Java runtime present, requesting install.
[Warning] The stack init script failed: exit status 1
[Warning] Your local IDE may not build properly, but the Appsody container should still work.
[Warning] To try again, resolve the issue then run `appsody init` with no arguments.

Your project is now initialized.

Understanding the project layout

For context, the following image displays the structure of the project that you’re working on:

Project structure


It contains the following artifacts:

  • StarterApplication.java, a JAX-RS Application class

  • server.xml, an Open Liberty server configuration file

  • index.html, a static HTML file

  • pom.xml, a project build file

Running the Appsody development environment

Run the following command to start the Appsody development environment:

appsody run

The Appsody CLI launches a local Docker image that contains an Open Liberty server that hosts the microservice. After some time, you see a message similar to the following example:

[Container] [INFO] [AUDIT   ] CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 20.235 seconds.

This message indicates that the server is started and you are ready to begin developing your application.

Creating and updating the application

Navigate to the JAX-RS application endpoint to confirm that there are no JAX-RS resources available. Go to the http://localhost:9080/starter URL. You see the following HTTP 500 error that states that there are no provider or resource classes that are associated with the application:

Error 500: javax.servlet.ServletException: At least one provider or resource class should be specified for application class "dev.appsody.starter.StarterApplication

In a new command-line window, go to the src/main/java/dev/appsody/starter directory that’s within your project folder. Create a file named StarterResource.java. Open the file, populate it with the following code, and save it:

package dev.appsody.starter;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
@Path("/resource")
public class StarterResource {
    @GET
    public String getRequest() {
        return "StarterResource response";
    }
}

After you save, the source compiles and the application updates. You see messages similar to the following example:

[Container] [INFO] [AUDIT   ] CWWKT0017I: Web application removed (default_host): http://85862d8696be:9080/
[Container] [INFO] [AUDIT   ] CWWKZ0009I: The application starter-app has stopped successfully.
[Container] [INFO] [AUDIT   ] CWWKT0016I: Web application available (default_host): http://85862d8696be:9080/
[Container] [INFO] [AUDIT   ] CWWKZ0003I: The application starter-app updated in 0.988 seconds.

Now if you browse to the http://localhost:9080/starter URL, you no longer see the HTTP 500 error. The resource that you just added is available at the starter/resource URL path. Go to the http://localhost:9080/starter/resource URL to see the following resource response:

StarterResource response

Try changing the message in the StarterResource.java file, saving, and refreshing the page. You’ll see that it takes only a few seconds for the change to take effect.

Deploying to Kubernetes

After you finish writing your application code, the Appsody CLI makes it easy to deploy to a Kubernetes cluster for further testing. Ensure that your kubectl command is configured with cluster details, and run the following command to deploy your application:

appsody deploy

This command builds a new Docker image that is optimized for production deployment and deploys the image to your Kubernetes cluster. After some time you see a message similar to the following example:

Deployed project running at http://localhost:30262

Run the following command to check the status of the application pods:

kubectl get pods

You see an output similar to the following example:

NAME                                  READY    STATUS   RESTARTS   AGE
appsody-operator-859b97bb98-htpgw      1/1     Running   0         3m2s
simple-microprofile-77d6868765-xkcpk   1/1     Running   0         31s

The pod that is related to your deployed application is similar to the following pod:

simple-microprofile-77d6868765-xkcpk   1/1     Running   0         31s

After the simple-microprofile pod starts, go to the URL that was returned after you ran the appsody deploy command, and you see the Appsody microservice splash screen. To see the response from your application, point your browser to <URL_STRING>/starter/resource, where <URL_STRING> is the URL that was returned. For example, the http://localhost:30262 URL was returned in the previous example. Go to the http://localhost:30262/starter/resource URL to see the deployed application response.

Use the following command to stop the deployed application:

appsody deploy delete

After you run this command, and the deployment is deleted, you see the following message:

Deployment deleted

Deploying to Knative

You can also choose to deploy the application with Knative Serving. To deploy the application with Knative Serving, you must first install Knative in your Kubernetes cluster. For information about installing Knative, see the Knative documentation. When Knative is installed, run the following command to generate an app-deploy.yaml file:

appsody deploy —generate-only

Open the app-deploy.yaml file that you generated and add the following information to the spec definition:

createKnativeService: true

Run the following command to deploy the application from your local image registry:

appsody deploy --tag dev.local/simple-microprofile --namespace <namespace>

Alternatively, run the following command to deploy the application from Docker Hub:

appsody deploy --push -—tag <my-account>/simple-microprofile --namespace <namespace>

After the application deploys, you see a message similar to the following example that details the serving URL:

Deployed project running at "http://simple-microprofile.knative-serving.192.168.1.10.nip.io"

To see the response from your application, point your browser to <URL_STRING>/starter/resource, where <URL_STRING> is the URL that was returned in the previous step.

Delivering to pipelines

After you develop and test your application, it’s time to deliver it to your enterprise’s Kabanero pipeline. Operations teams can configure the webhook on the Git repository that triggers the pipeline. To deliver it to the pipeline, push the project to the pre-configured Git repository. The pipeline then builds and deploys the application.

You can’t perform that action at this time.