🍃 ☁️
Java Microservices with Spring Boot & Spring Cloud This repository contains examples of how to build a Java microservices architecture with Spring Boot, Spring Cloud, and Netflix Eureka.
This repository has five examples in it:
- A bare-bones microservices architecture with Spring Boot, Spring Cloud, Eureka Server, and Zuul.
- A microservices architecture that's generated with JHipster and configured centrally with Spring Cloud Config.
- A microservices architecture that uses Spring Cloud Gateway and Spring WebFlux to show reactive microservices.
- A JHipster-generated reactive microservices architecture with Spring Cloud Gateway and Spring WebFlux.
- A JHipster 7 + Kubernetes example that deploys to Google Cloud with sealed secrets.
We think you'll enjoy them all!
- See Java Microservices with Spring Boot and Spring Cloud for an overview of the first example.
- Read Java Microservices with Spring Cloud Config and JHipster to learn about microservices with JHipster.
- Refer to Secure Reactive Microservices with Spring Cloud Gateway to learn about Spring Cloud Gateway and reactive microservices.
- Refer to Reactive Java Microservices with Spring Boot and JHipster to see how JHipster makes reactive microservices a breeze.
- Peruse Kubernetes to the Cloud with Spring Boot and JHipster to see how JHipster simplifies Kubernetes deployments.
Prerequisites: Java 11 and an internet connection.
- Spring Boot + Spring Cloud Example
- JHipster + Spring Cloud Config Example
- Spring Cloud Gateway Example
- Reactive Microservices with JHipster Example
- Kubernetes to the Cloud Example
- Links
- Help
- License
Spring Boot + Spring Cloud Example
To install this example, run the following commands:
git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/spring-boot+cloud
The api-gateway
and car-service
projects are already pre-configured to be locked down with OAuth 2.0 and Okta. That means if you try to run them, you won't be able to login until you create an account, and an application in it.
Create a Web Application in Okta
Log in to your Okta Developer account (or sign up if you don't have an account).
- From the Applications page, choose Add Application.
- On the Create New Application page, select Web.
- Give your app a memorable name, add
http://localhost:8080/login/oauth2/code/okta
as a Login redirect URI, select Refresh Token (in addition to Authorization Code), and click Done.
Copy the issuer (found under API > Authorization Servers), client ID, and client secret into the application.properties
of the api-gateway
and car-service
projects.
okta.oauth2.issuer=https://{yourOktaDomain}/oauth2/default
okta.oauth2.client-id=$clientId
okta.oauth2.client-secret=$clientSecret
Then, run all the projects with ./mvnw
in separate terminal windows. You should be able to navigate to http://localhost:8761
and see the apps have been registered with Eureka.
Then, navigate to http://localhost:8080/cool-cars
in your browser, log in with Okta, and see the resulting JSON.
JHipster + Spring Cloud Config Example
To install this example, run the following commands:
git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/jhipster
Create Docker containers for all gateway and microservice applications:
mvn -Pprod verify com.google.cloud.tools:jib-maven-plugin:dockerBuild
Create a Web Application in Okta
Log in to your Okta Developer account (or sign up if you don't have an account).
- From the Applications page, choose Add Application.
- On the Create New Application page, select Web.
- Give your app a memorable name, add
http://localhost:8080/login/oauth2/code/okta
as a Login redirect URI, select Refresh Token (in addition to Authorization Code), and click Done. - To configure Logout to work in JHipster, Edit your app, add
http://localhost:8080
as a Logout redirect URI, then click Save.
Rather than modifying each of your apps for Okta, you can use Spring Cloud Config in JHipster Registry to do it. Open docker-compose/central-server-config/application.yml
and add your Okta settings.
The client ID and secret are available on your app settings page. You can find the issuer under API > Authorization Servers.
spring:
security:
oauth2:
client:
provider:
oidc:
issuer-uri: https://{yourOktaDomain}/oauth2/default
registration:
oidc:
client-id: {yourClientId}
client-secret: {yourClientSecret}
The registry, gateway, blog, and store applications are all configured to read this configuration on startup.
Start all your containers from the docker-compose
directory:
docker-compose up -d
Before you can log in to the registry, you'll need to add redirect URIs for JHipster Registry, ensure your user is in a ROLE_ADMIN
group and that groups are included in the ID token.
Log in to your Okta dashboard, edit your OIDC app, and add the following Login redirect URI:
http://localhost:8761/login/oauth2/code/oidc
You'll also need to add a Logout redirect URI:
http://localhost:8761
Then, click Save.
Create Groups and Add Them as Claims to the ID Token
JHipster is configured by default to work with two types of users: administrators and users. Keycloak is configured with users and groups automatically, but you need to do some one-time configuration for your Okta organization.
Create a ROLE_ADMIN
group (Users > Groups > Add Group) and add your user to it. Navigate to API > Authorization Servers, and click on the the default
server. Click the Claims tab and Add Claim. Name it groups
, and include it in the ID Token. Set the value type to Groups
and set the filter to be a Regex of .*
. Click Create.
Now when you hit http://localhost:8761
or http://localhost:8080
, you should be able to log in with Okta!
Spring Cloud Gateway Example
To install this example, run the following commands:
git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/spring-cloud-gateway
The api-gateway
and car-service
projects are already pre-configured to be locked down with OAuth 2.0 and Okta. That means if you try to run them, you won't be able to login until you create an account, and an application in it.
If you already have an Okta account, see the Create a Web Application in Okta section below. Otherwise, we created a Maven plugin that configures a free Okta developer account + an OIDC app (in under a minute!).
To use it, run ./mvnw com.okta:okta-maven-plugin:setup
to create an account and configure the gateway to work with Okta.
Copy the okta.*
properties from the gateway's src/main/resources/application.properties
to the same file in the car-service
project.
Then, run all the projects with ./mvnw
in separate terminal windows. You should be able to navigate to http://localhost:8761
and see the apps have been registered with Eureka.
Then, navigate to http://localhost:8080/cars
in your browser, log in with Okta, and see the resulting JSON.
Create a Web Application in Okta
Log in to your Okta Developer account (or sign up if you don't have an account).
- From the Applications page, choose Add Application.
- On the Create New Application page, select Web.
- Give your app a memorable name, add
http://localhost:8080/login/oauth2/code/okta
as a Login redirect URI and click Done.
Copy the issuer (found under API > Authorization Servers), client ID, and client secret into the application.properties
of the api-gateway
and car-service
projects.
okta.oauth2.issuer=https://{yourOktaDomain}/oauth2/default
okta.oauth2.client-id=$clientId
okta.oauth2.client-secret=$clientSecret
Reactive Microservices with JHipster Example
To install this example, run the following commands:
git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/reactive-jhipster
The JHipster Registry and Spring Cloud Config are pre-configured to use Okta. That means if you try to run them, you won't be able to login until you create an account, and an application in it.
Install the Okta CLI using the instructions on cli.okta.com and come back here when you're done. If you don't have an Okta developer account, run okta register
.
NOTE: You can also use your browser and Okta's developer console to register an app. See JHipster's security documentation for those instructions.
From the gateway project's directory, run okta apps create jhipster
. Accept the default redirect URIs.
This process does several things:
- Registers an OIDC app in Okta with JHipster's configured redirect URIs.
- Creates
ROLE_ADMIN
andROLE_USER
groups and adds your user to both. - Creates a
groups
claim and adds it to ID tokens. - Creates a
.okta.env
file with the values you'll need to talk to Okta.
Spring Cloud Config allows you to distribute Spring's configuration between apps. Update gateway/src/main/docker/central-server-config/localhost-config/application.yml
to use your Okta app settings. You can find the values for each property in the .okta.env
file.
spring:
security:
oauth2:
client:
provider:
oidc:
issuer-uri: https://<your-okta-domain>/oauth2/default
registration:
oidc:
client-id: <client-id>
client-secret: <client-secret>
Save your changes. These values will be distributed to the JHipster Registry, gateway, blog, and store apps. Start all the services and apps using the following commands:
cd gateway
docker-compose -f src/main/docker/keycloak.yml up -d #jhkeycloakup
docker-compose -f src/main/docker/postgresql.yml up -d #jhpostgresqlup
docker-compose -f src/main/docker/jhipster-registery up -d #jhregistryup
./gradlew
Open a new terminal window, start the blog app's Neo4j database, and then the app itself.
cd ../blog
docker-compose -f src/main/docker/neo4j.yml up -d #jhneo4jup
./gradlew
Then, open another terminal window, start the store app's MongoDB database, and the microservice.
cd ../store
docker-compose -f src/main/docker/mongodb.yml up -d #jhmongoup
./gradlew
Now, open a new incognito browser window, go to http://localhost:8080
, and sign in. Rejoice that using Okta for authentication works!
TIP: You can also run everything using Docker Compose. See the blog post for how to do that.
Kubernetes + Reactive Java with JHipster Example
To install this example, run the following commands:
git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/jhipster-k8s/k8s
If you don't have JHipster installed, install it.
npm i -g generator-jhipster@7
Run JHipster's Kubernetes sub-generator.
jhipster k8s
You will be prompted with several questions. The answers will be pre-populated from choices I made when creating this app. Answer as follows, changing the Docker repository name to yours, or leaving it blank if you don't have one.
- Type of application: Microservice application
- Root directory: ../
- Which applications?
<select all>
- Set up monitoring? No
- Which applications with clustered databases? select store
- Admin password for JHipster Registry:
<generate one>
- Kubernetes namespace: demo
- Docker repository name:
<your docker hub username>
- Command to push Docker image:
docker push
- Enable Istio? No
- Kubernetes service type? LoadBalancer
- Use dynamic storage provisioning? Yes
- Use a specific storage class?
<leave empty>
Install Minikube to Run Kubernetes Locally
If you have Docker installed, you can run Kubernetes locally with Minikube. Run minikube start
to begin.
minikube --memory 8g --cpus 8 start
Build Docker images for each app. In the {gateway
, blog
, store
} directories, run the following Gradle command (where <image-name>
is gateway
, store
, or blog
).
./gradlew bootJar -Pprod jib -Djib.to.image=<docker-repo-name>/<image-name>
You can also build your images locally and publish them to your Docker daemon. This is the default if you didn't specify a base Docker repository name.
# this command exposes Docker images to minikube eval $(minikube docker-env) ./gradlew -Pprod bootJar jibDockerBuildBecause this publishes your images locally to Docker, you'll need to make modifications to your Kubernetes deployment files to use
imagePullPolicy: IfNotPresent
.- name: gateway-app image: gateway imagePullPolicy: IfNotPresentMake sure to add this
imagePullPolicy
to the following files:
k8s/gateway-k8s/gateway-deployment.yml
k8s/blog-k8s/blog-deployment.yml
k8s/store-k8s/store-deployment.yml
Register an OIDC App for Auth
Install the Okta CLI using the instructions on cli.okta.com and come back here when you're done. If you don't have an Okta developer account, run okta register
.
NOTE: You can also use your browser and Okta's developer console to register an app. See JHipster's security documentation for those instructions.
From the gateway project's directory, run okta apps create jhipster
. Accept the default redirect URIs.
This process does several things:
- Registers an OIDC app in Okta with JHipster's configured redirect URIs.
- Creates
ROLE_ADMIN
andROLE_USER
groups and adds your user to both. - Creates a
groups
claim and adds it to ID tokens. - Creates a
.okta.env
file with the values you'll need to talk to Okta.
Update k8s/registry-k8s/application-configmap.yml
to contain your OIDC settings from the .okta.env
file the Okta CLI just created. The Spring Cloud Config server reads from this file and shares the values with the gateway and microservices.
data:
application.yml: |-
...
spring:
security:
oauth2:
client:
provider:
oidc:
issuer-uri: https://<your-okta-domain>/oauth2/default
registration:
oidc:
client-id: <client-id>
client-secret: <client-secret>
To configure the JHipster Registry to use OIDC for authentication, modify k8s/registry-k8s/jhipster-registry.yml
to enable the oauth2
profile.
- name: SPRING_PROFILES_ACTIVE
value: prod,k8s,oauth2
Then, in the k8s
directory, start your engines!
./kubectl-apply.sh -f
You can see if everything starts up using the following command.
kubectl get pods -n default
You can use the name of a pod with kubectl logs
to tail its logs.
kubectl logs <pod-name> --tail=-1 -n default
You can use port-forwarding to see the JHipster Registry.
kubectl port-forward svc/jhipster-registry -n default 8761
Open a browser and navigate to http://localhost:8761
. You'll need to sign in with your Okta credentials.
Once all is green, use port-forwarding to see the gateway app.
kubectl port-forward svc/gateway -n default 8080
Then, go to http://localhost:8080
, and you should be able to add blogs, posts, tags, and products.
Please read the Kubernetes to the Cloud with Spring Boot and JHipster for more information.
Links
These examples use the following open source libraries:
- Okta Spring Boot Starter
- Spring Boot
- Spring Cloud
- Spring Cloud Gateway
- Spring Security
- JHipster
- OpenJDK
- K9s
Help
Please post any questions as comments on the example's blog post, or on the Okta Developer Forums.
License
Apache 2.0, see LICENSE.