Switch branches/tags
Nothing to show
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src/main changed etcd URL Sep 11, 2017
Dockerfile renamed discovery sample to kumuluzee-discovery-etcd, added service n… Jul 13, 2017
README.md fixed readme files for discovery etcd samples Nov 20, 2017
pom.xml Upped KumuluzEE version of the samples Oct 12, 2018

README.md

KumuluzEE Discovery — register service with etcd

Develop a REST KumuluzEE microservice and register it with etcd.

The objective of this sample is to show how to register a REST service with etcd using KumuluzEE Discovery extension. This tutorial will guide you through all the necessary steps. You will add KumuluzEE dependencies into pom.xml. You will use existing JAX-RS sample, described here. Required knowledge: basic familiarity with JAX-RS and basic concepts of REST and JSON; basic familiarity with etcd.

Requirements

In order to run this example you will need the following:

  1. Java 8 (or newer), you can use any implementation:

    • If you have installed Java, you can check the version by typing the following in a command line:

      java -version
      
  2. Maven 3.2.1 (or newer):

    • If you have installed Maven, you can check the version by typing the following in a command line:

      mvn -version
      
  3. Git:

    • If you have installed Git, you can check the version by typing the following in a command line:

      git --version
      

Prerequisites

To run this sample you will need an etcd instance. Note that such setup with only one etcd node is not viable for production environments, but only for developing purposes. Here is an example on how to quickly run an etcd instance with docker:

 $ docker run -d -p 2379:2379 \
   --name etcd \
   --volume=/tmp/etcd-data:/etcd-data \
   quay.io/coreos/etcd:latest \
   /usr/local/bin/etcd \
   --name my-etcd-1 \
   --data-dir /etcd-data \
   --listen-client-urls http://0.0.0.0:2379 \
   --advertise-client-urls http://0.0.0.0:2379 \
   --listen-peer-urls http://0.0.0.0:2380 \
   --initial-advertise-peer-urls http://0.0.0.0:2380 \
   --initial-cluster my-etcd-1=http://0.0.0.0:2380 \
   --initial-cluster-token my-etcd-token \
   --initial-cluster-state new \
   --auto-compaction-retention 1 \
   -cors="*"

Usage

The example uses maven to build and run the microservice.

  1. Build the sample using maven:

    $ cd discovery-samples/discovery-register
    $ mvn clean package
  2. Start local etcd instance in another terminal:

    $ etcd
  3. Run the sample:

  • Uber-jar:

    $ java -jar target/${project.build.finalName}.jar

    in Windows environemnt use the command

    java -jar target/${project.build.finalName}.jar
  • Exploded:

    $ java -cp target/classes:target/dependency/* com.kumuluz.ee.EeApplication

    in Windows environment use the command

    java -cp target/classes;target/dependency/* com.kumuluz.ee.EeApplication

The application/service can be accessed on the following URL:

The application is registered with etcd. You can discover it using one of the discover samples:

To shut down the example simply stop the processes in the foreground.

Tutorial

This tutorial will guide you through the steps required to register KumuluzEE microservice with etcd. We will use existing sample Customer REST service with the following resources:

We will follow these steps:

  • Import a Maven sample, mentioned above, in the IDE of your choice (Eclipse, IntelliJ, etc.)
  • Add Maven dependency to KumuluzEE Discovery extension
  • Annotate JAX-RS Application class with @RegisterService annotation
  • Build the microservice
  • Run it

Add Maven dependencies

Add the kumuluzee-discovery-etcd dependency to the sample:

<dependencies>
    ...
    
    <dependency>
        <groupId>com.kumuluz.ee.discovery</groupId>
        <artifactId>kumuluzee-discovery-etcd</artifactId>
        <version>${kumuluzee-discovery.version}</version>
    </dependency>
</dependencies>

Add the kumuluzee-maven-plugin build plugin to package microservice as uber-jar:

<build>
    <plugins>
        <plugin>
            <groupId>com.kumuluz.ee</groupId>
            <artifactId>kumuluzee-maven-plugin</artifactId>
            <version>${kumuluzee.version}</version>
            <executions>
                <execution>
                    <id>package</id>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

or exploded:

<build>
    <plugins>
        <plugin>
            <groupId>com.kumuluz.ee</groupId>
            <artifactId>kumuluzee-maven-plugin</artifactId>
            <version>${kumuluzee.version}</version>
            <executions>
                <execution>
                    <id>package</id>
                    <goals>
                        <goal>copy-dependencies</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Annotate JAX-RS Application

Add the @RegisterService annotation to JAX-RS Application class (CustomerApplication.java):

@RegisterService
@ApplicationPath("v1")
public class CustomerApplication extends Application {
}

Add required configuration for the service discovery

You can add configuration using any KumuluzEE configuration source.

For example, you can use config.yml file, placed in resources folder:

kumuluzee:
  name: customer-service
  env:
    name: dev
  version: 1.0.0
  server:
    base-url: http://localhost:8081
    http:
      port: 8081
  discovery:
    etcd:
      hosts: http://192.168.99.100:2379
    ttl: 20
    ping-interval: 15

Port 8081 is used because we want to run another microservice on default port, which discovers this service on port 8080.

Build the microservice and run it

To build the microservice and run the example, use the commands as described in previous sections.