Forem: JHipster

Micro Frontends for Java Microservices

Matt Raible — Fri, 20 Jan 2023 15:47:47 +0000

Microservices have been quite popular in the Java ecosystem ever since Spring Boot and Spring Cloud made them easy to build and deploy. Things have gotten even easier in recent years with the proliferation of new Java frameworks built specifically for microservices: MicroProfile, Micronaut, Quarkus, and Helidon. Not only do these frameworks provide an excellent developer experience, but they also tend to have built-in Docker support. They even work with GraalVM, so you can compile your apps to native code!

To be fair, MicroProfile isn't a framework; it's a spec with many implementations. In fact, both Quarkus and Helidon have MicroProfile flavors you can use.

Today, I'll show you how to build a Java microservices architecture that leverages micro frontends for the UI. The backend will use Spring Boot and Spring Cloud, while the frontend will use React. You can also use Angular or Vue if you'd like.

This tutorial is also available as a screencast.

NOTE: This video uses JHipster 7.9.3. All the steps will still work with JHipster 8.1.0, but you have to use Java 17 and Node 18.

Prerequisites:

You can install JHipster with npm:

npm i -g generator-jhipster@8

Java microservices with Spring Boot and JHipster

JHipster is an application generator that creates a Spring Boot backend. You can configure it to use SQL or NoSQL databases, plain ol' Spring MVC, or reactive with WebFlux. It also generates a UI for your REST API and offers you the choice of Angular, React, or Vue. Last year, I showed you how to build reactive Java microservices with Spring Boot and JHipster. In this tutorial, you'll build a gateway with Spring Cloud Gateway. Then, you create a blog microservice and a store microservice, each with its own database.

This microservices architecture had one major flaw: the UI for it is a monolith, with all its files on the gateway. This isn't good from a loose-coupling point of view because changes in a microservice might require changes in the UI. Instead of being able to deploy the microservice independently, you have to deploy the gateway too.

Today, I'm proud to show you how you can solve this problem with micro frontends. JHipster recently added support for micro-frontends. Microfrontends provide a way for you to remotely load and execute code at runtime so your microservice's UI can live in the same artifact without being coupled to the gateway!

In the previous paragraph, you might notice I spelled micro frontends three different ways. The current literature is all over the place on this one!

// Detect dark theme var iframe = document.getElementById('tweet-1499098253920460802-810'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1499098253920460802&theme=dark" }

I'm going to use "micro frontends" for the remainder of this post since that's what Cam Jackson used in his Micro Frontends article on Martin Fowler's blog.

A quick introduction to Module Federation

Webpack's Module Federation is one of the best-known implementations for micro frontends. Its ModuleFederationPlugin allows a build to provide or consume modules with other independent builds at runtime. It even allows you to share libraries between frontends to reduce the size of remote bundles.

Zack Jackson is the creator of Module Federation and recently collaborated with Manfred Steyer to create Native Federation. This means you can use micro frontend concepts with any build tool, not just webpack.

// Detect dark theme var iframe = document.getElementById('tweet-1564312149580582912-428'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1564312149580582912&theme=dark" }

Why should Java developers care?

I think micro frontends are a fascinating architectural concept. Microservices weave everything together on the backend with protocols like HTTP and gRPC. With micro frontends, it's all HTTP. You can see your app get stitched together by watching your browser's network console and seeing remote modules load.

I've encountered quite a few monolith UIs in my time as a consultant. The backend was a beautiful microservice architecture, but it was all tightly coupled on the frontend. There's a good chance many Java developers don't care about the UI because they just work on the beautiful backends. However, if you consider yourself a Java web developer, micro frontends are as revolutionary as HTML5!

And that's the beauty of this tutorial; you don't have to write any micro frontends. JHipster can create them for you!

Micro frontends in action with JHipster

I used a JDL (JHipster Domain Language) file named reactive-ms.jdl to create the reactive Java microservices tutorial I mentioned earlier. You can see this file online in the JDL samples repository.

I copied this file to reactive-mf.jdl and changed a few things for this tutorial:

Enabled micro frontends by adding microfrontends [blog, store] to the gateway's definition.
Changed the client framework from Vue to React.
Added clientFramework react and Cypress to each microservice.
Changed the service discovery to Consul, since this is the default in JHipster 8.
Added a deployment section for Kubernetes.

CAUTION: JHipster's JDL allows you to specify different client frameworks, but micro frontends will only work if you set the same one for all your apps.

Run the following command to create a new directory for your micro frontends project:

take micro-frontends-jhipster
# mkdir micro-frontends-jhipster && cd micro-frontends-jhipster if you don't have take installed

Download both the -ms and -mf JDLs and compare them in IntelliJ IDEA. You'll need IDEA's Command-line Launcher for the idea command to work.

jhipster download reactive-ms.jdl
jhipster download reactive-mf.jdl
idea diff reactive-ms.jdl reactive-mf.jdl

TIP: The JHipster JDL Plugin is a handy tool for working with JDL files.

Micro frontend options: Angular, React, and Vue

JHipster has support for the big three JavaScript frameworks: Angular, React, and Vue. All are implemented using TypeScript, and a newly generated app should have around 70% code coverage, both on the backend and frontend.

There is also a Svelte blueprint, but it does not support micro frontends at the time of this writing.

Build Java microservices with Spring Boot and WebFlux

To generate a microservices architecture with micro frontend support, run the following command:

jhipster jdl reactive-mf.jdl --monorepository --workspaces

The last two arguments are optional, but I expect you to use them for this tutorial. Without the monorepository flag, the gateway and microservices would have their own Git repos. The workspaces flag enables npm workspaces, which are kinda like having an aggregator pom.xml that allows you to execute commands across projects. It also makes it so there's only one node_modules in the root directory. To learn more, I recommend egghead's Introduction to Monorepos with NPM Workspaces.

If you want to use Angular, append --client-framework angular to the command above to override the JDL value:

--client-framework angular

If you'd rather try out Vue, use the following:

--client-framework vue

Run your reactive Spring Boot microservices

When the process is complete, cd into the gateway directory and start Consul, Keycloak, and PostgreSQL using Docker Compose.

cd gateway
docker compose -f src/main/docker/consul.yml up -d
docker compose -f src/main/docker/keycloak.yml up -d
docker compose -f src/main/docker/postgresql.yml up -d

Then, run ./gradlew (or npm run app:start if you prefer npm commands). When the startup process completes, open your favorite browser to http://localhost:8080, and log in with the credentials displayed on the page.

You'll be redirected back to the gateway, but the Entities menu won't have any links because the micro frontends it tries to load are unavailable.

Start the blog by opening a terminal and navigating to its directory. Then, start its database with Docker and the app with Gradle.

npm run docker:db:up
./gradlew

Open a new terminal and do the same for the store microservice.

You can verify everything is started using Consul at http://localhost:8500.

Refresh the gateway app; you should see menu items to navigate to the microservices now.

Zero turnaround development that sparks joy

At this point, I've only shown you how to run the Spring Boot backends with their packaged React apps. What if you want to work on the UI and have zero turnaround that sparks joy? ✨🤗

In the gateway app, run npm start. This command will run the UI on a web server, open a browser window to http://localhost:9000, and use Browsersync to keep your browser in sync with your code.

Modify the code in gateway/src/main/webapp/app/modules/home/home.tsx to make a quick change. For example, add the following HTML below the <h1>.

<h2 className="text-primary">
  Hi, I'm a quick edit!
</h2>

You'll see this change immediately appear within your browser.

Remove it, and it'll disappear right away too.

Now, open another terminal and navigate into the store directory. Run npm start, and you'll have a similar zero-turnaround experience when modifying files in the store app. The app will start a webserver on http://localhost:9002, and there will only be one menu item for product. Modify files in the store/src/main/webapp/app/entities/store/product directory, and you'll see the changes in your browser immediately. For example, change the wrapper <div> in product.tsx to have a background color:

<div className="bg-info">

The UI will change before you can Command+Tab back to your browser.

The backend has quick turnaround abilities too, thanks to Spring Boot devtools. If you modify a backend class, recompiling it will cause Spring Boot to reload your component lickety-split. It's pretty slick!

A look under the hood of micro frontends

When you're learning concepts like micro frontends, it's often helpful to look at the code that makes things work.

The gateway's webpack.microfrontend.js handles specifying the shared dependencies and components between apps. The src/main/webapp/app/shared/layout/menus/entities.tsx file contains the menu items for each micro frontend.

const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

const packageJson = require('../package.json');
// Microfrontend api, should match across gateway and microservices.
const apiVersion = '0.0.1';

const sharedDefaults = { singleton: true, strictVersion: true, requiredVersion: apiVersion };
const shareMappings = (...mappings) => Object.fromEntries(mappings.map(map => [map, { ...sharedDefaults, version: apiVersion }]));

const shareDependencies = ({ skipList = [] } = {}) =>
  Object.fromEntries(
    Object.entries(packageJson.dependencies)
      .filter(([dependency]) => !skipList.includes(dependency))
      .map(([dependency, version]) => [dependency, { ...sharedDefaults, version, requiredVersion: version }]),
  );

module.exports = ({ serve }) => {
  return {
    optimization: {
      moduleIds: 'named',
      chunkIds: 'named',
      runtimeChunk: false,
    },

    plugins: [
      new ModuleFederationPlugin({
        shareScope: 'default',
        shared: {
          ...shareDependencies(),
          ...shareMappings(
            'app/config/constants',
            'app/config/store',
            'app/shared/error/error-boundary-routes',
            'app/shared/layout/menus/menu-components',
            'app/shared/layout/menus/menu-item',
            'app/shared/reducers',
            'app/shared/reducers/locale',
            'app/shared/reducers/reducer.utils',
            'app/shared/util/date-utils',
            'app/shared/util/entity-utils',
          ),
        },
      }),
    ],
    output: {
      publicPath: 'auto',
    },
  };
};

The blog's webpack.microfrontend.js looks similar, except that it exposes its remoteEntry.js, menu items, and routes.

const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
const { DefinePlugin } = require('webpack');

const packageJson = require('../package.json');
// Microfrontend api, should match across gateway and microservices.
const apiVersion = '0.0.1';

const sharedDefaults = { singleton: true, strictVersion: true, requiredVersion: apiVersion };
const shareMappings = (...mappings) => Object.fromEntries(mappings.map(map => [map, { ...sharedDefaults, version: apiVersion }]));

const shareDependencies = ({ skipList = [] } = {}) =>
  Object.fromEntries(
    Object.entries(packageJson.dependencies)
      .filter(([dependency]) => !skipList.includes(dependency))
      .map(([dependency, version]) => [dependency, { ...sharedDefaults, version, requiredVersion: version }]),
  );

module.exports = ({ serve }) => {
  return {
    optimization: {
      moduleIds: 'named',
      chunkIds: 'named',
      runtimeChunk: false,
    },

    plugins: [
      new ModuleFederationPlugin({
        name: 'blog',
        filename: 'remoteEntry.js',
        shareScope: 'default',
        exposes: {
          './entities-menu': './src/main/webapp/app/entities/menu',
          './entities-routes': './src/main/webapp/app/entities/routes',
        },
        shared: {
          ...shareDependencies(),
          ...shareMappings(
            'app/config/constants',
            'app/config/store',
            'app/shared/error/error-boundary-routes',
            'app/shared/layout/menus/menu-components',
            'app/shared/layout/menus/menu-item',
            'app/shared/reducers',
            'app/shared/reducers/locale',
            'app/shared/reducers/reducer.utils',
            'app/shared/util/date-utils',
            'app/shared/util/entity-utils',
          ),
        },
      }),
      new DefinePlugin({
        BLOG_I18N_RESOURCES_PREFIX: JSON.stringify(''),
      }),
    ],
    output: {
      publicPath: 'auto',
    },
  };
};

Build and run with Docker

To build Docker images for each application, run the following command from the root directory.

npm run java:docker

The command is slightly different if you're using a Mac with Apple Silicon.

npm run java:docker:arm64

TIP: You can see all npm scripts with npm run.

Then, navigate to the docker-compose directory, stop the existing containers, and start all the containers.

cd docker-compose
docker stop $(docker ps -a -q);
docker compose up

This command will start and run all the apps, their databases, Consul, and Keycloak. To make Keycloak work, you must add the following line to your hosts file (/etc/hosts on Mac/Linux, c:\Windows\System32\Drivers\etc\hosts on Windows).

127.0.0.1  keycloak

This is because you will access your application with a browser on your machine (where the name is localhost, or 127.0.0.1), but inside Docker it will run in its own container, where the name is keycloak.

If you want to prove everything works, ensure everything is started at http://localhost:8500, then run npm run e2e -ws from the root project directory. This command will run the Cypress tests that JHipster generates in your browser.

Switch identity providers

JHipster ships with Keycloak when you choose OAuth 2.0 / OIDC as the authentication type. However, you can easily change it to another identity provider, like Auth0!

First, you'll need to register a regular web application. Log in to your Auth0 account (or sign up if you don't have an account). You should have a unique domain like dev-xxx.us.auth0.com.

Select Create Application in the Applications section. Use a name like Micro Frontends, select Regular Web Applications, and click Create.

Switch to the Settings tab and configure your application settings:

Allowed Callback URLs: http://localhost:8080/login/oauth2/code/oidc
Allowed Logout URLs: http://localhost:8080/

Scroll to the bottom and click Save Changes.

In the roles section, create new roles named ROLE_ADMIN and ROLE_USER.

Create a new user account in the users section. Click the Role tab to assign the roles you just created to the new account.

Make sure your new user's email is verified before attempting to log in!

Next, head to Actions > Flows and select Login. Create a new action named Add Roles and use the default trigger and runtime. Change the onExecutePostLogin handler to be as follows:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://www.jhipster.tech';
  if (event.authorization) {
    api.idToken.setCustomClaim('preferred_username', event.user.email);
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}

This code adds the user's roles to a custom claim (prefixed with https://www.jhipster.tech/roles). This claim is mapped to Spring Security authorities in SecurityUtils.java in the gateway app.

Select Deploy and drag the Add Roles action to your Login flow.

Edit docker-compose/central-server-config/application.yml and append the following YAML block to add your Auth0 settings.

jhipster:
  security:
    oauth2:
      audience: https://<your-auth0-domain>/api/v2/

spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://<your-auth0-domain>/ # make sure to include the trailing slash!
        registration:
          oidc:
            client-id: <your-client-id>
            client-secret: <your-client-secret>

NOTE: Want to have all these steps automated for you? Vote for issue #351 in the Auth0 CLI project.

Stop all your Docker containers with Ctrl+C and start them again.

docker compose up

Now, Spring Security will be configured to use Auth0, and Consul will distribute these settings to all your microservices. When everything is started, navigate to http://localhost:8080 and click sign in. You will be prompted for your Auth0 credentials.

After entering your credentials, you'll be redirected back to the gateway, and your username will be displayed.

You should be able to add, edit, and delete blogs, posts, tags, and products, proving that your microservices and micro frontends can talk to each other.

If you'd like to use Okta for your identity provider, see JHipster's documentation.

TIP: You can configure JHipster quickly with the Okta CLI:

okta apps create jhipster

Deploy with Kubernetes

The JDL you used to generate this microservices stack has a section at the bottom for deploying to Kubernetes.

deployment {
  deploymentType kubernetes
  appsFolders [gateway, blog, store]
  clusteredDbApps [store]
  kubernetesNamespace demo
  kubernetesUseDynamicStorage true
  kubernetesStorageClassName ""
  serviceDiscoveryType consul
  dockerRepositoryName "mraible"
}

The jhipster jdl command generates a kubernetes directory with this information and configures all your apps, databases, and Consul to be Kubernetes-ready. If you have a Kubernetes cluster created, you can deploy to its demo namespace using the following command.

./kubectl-apply.sh -f

It also generates files for Kustomize and Skaffold if you'd prefer to use those tools. See the kubernetes/K8S-README.md file for more information.

I won't go into the nitty-gritty details of deploying a JHipster microservices stack to cloud providers with K8s, mainly because it's covered in previous blog posts. The first post below shows how to run Minikube locally, encrypt your secrets, and deploy to Google Cloud.

The JHipster team also has a blog you can follow at dev.to/jhipster.

Learn more about micro frontends and microservices

I hope you enjoyed this overview of how to use micro frontends within a Java microservices architecture. I like how micro frontends allow each microservice application to be self-contained and deployable, independent of the other microservices. It's also pretty neat how JHipster generates Docker and Kubernetes configuration for you. Cloud-native FTW!

You can find the source code for this example on GitHub, in the @oktadev/auth0-micro-frontends-jhipster-example repository.

If you'd like to learn more about micro frontends and microservices, I recommend these posts:

Please follow @auth0 and @oktadev on Twitter. We also have YouTube channels that you might enjoy at youtube.com/auth0 and youtube.com/oktadev. If you have any questions, please leave a comment below!

CI/CD Java Microservices with CircleCI and Spinnaker

Jimena Garbarino — Tue, 23 Aug 2022 23:37:28 +0000

Continuous integration and delivery (CI/CD) are essential practices for modern software development. In this post we cover the basics of how to add CI/CD for a JHipster microservices architecture and Kubernetes as the target cloud deployment environment.

Briefly, continuous integration is the practice of integrating code into the main branch of a shared repository early and often. Instead of integrating features at the end of a development cycle, code is integrated with the shared repository multiple times throughout the day. Each commit triggers automated tests, so issues are detected and fixed earlier and faster, improving team confidence and productivity. The chosen continuous integration platform is from CircleCI, a company founded in 2011 and headquartered in San Francisco. They offer a free cloud to test their services.

Continuous delivery is the practice of releasing to production often in a fast, safe, and automated way, allowing faster innovation and feedback loops. Its adoption requires the implementation of techniques and tools like Spinnaker, an open-source, multi-cloud, continuous delivery platform that provides application management and deployment features. The intersection between CI and CD is not always clear, but for this example, we assume CI produces and validates the artifacts and CD deploys them. The CI/CD workflow for the exploration of the proposed tools is illustrated below.

This tutorial was created with the following frameworks and tools:

Create a Java microservices architecture
- Configure Okta for OIDC authentication
Set up CI for JHipster with CircleCI
Install Spinnaker on Google Kubernetes Engine
- Understand Spinnaker artifacts and accounts
- Install Halyard
- Choose GKE for Spinnaker deployment
- Choose the installation environment
- Choose a storage service
- Deploy Spinnaker
Set up CD for a JHipster microservices architecture
- Use GKE for Kubernetes deployment
- Add a Docker registry account
- Add a GitHub artifact account
- Create the store microservice pipeline
- Configure the Docker image triggers
- Configure the deployment stages
- Trigger the CI/CD pipeline with a GitHub push
- Inspect Spinnaker logs
Spinnaker features and best practices
Learn more about JHipster, microservices, and Kubernetes

Create a Java microservices architecture

If you haven't tried JHipster yet, you can do the classical local installation with npm.

npm install -g generator-jhipster@7.9.2

If you'd rather use Yarn or Docker, follow the instructions at jhipster.tech.

You can also use the example reactive-jhipster from GitHub, a reactive microservices architecture with Spring Cloud Gateway and Spring WebFlux, Vue as the client framework, and Gradle as the build tool. You can find the complete instructions for building the architecture in a previous post: Reactive Java Microservices with Spring Boot and JHipster.
Create a project folder jhipster-ci-cd.

cd jhipster-ci-cd
http -d https://raw.githubusercontent.com/oktadev/java-microservices-examples/bc7cbeeb1296bd0fcc6a09f4e39f4e6e472a076a/reactive-jhipster/reactive-ms.jdl
jhipster jdl reactive-ms.jdl

After the generation, you will find sub-folders were created for the gateway, store, and blog services. The gateway will act as the front-end application and as a secure router to the store and blog microservices.

The next step is to generate the Kubernetes deployment descriptors. In the project root folder, create a kubernetes directory and run the k8s JHipster sub-generator:

mkdir kubernetes
cd kubernetes
jhipster k8s

NOTE: You must set up the Docker repository name for the cloud deployment, so go ahead and create a Docker Hub personal account, if you don't have one, before running the k8s sub-generator.

Choose the following options when prompted:

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-dockerhub-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)

Configure Okta for OIDC authentication

One more configuration step before building the applications, let's configure Okta for authentication. You must run the commands at the root folder of the project.

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create jhipster. Select the default app name, or change it as you see fit. Accept the default Redirect URI values provided for you.

What does the Okta CLI do?

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:
- login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
- logout: http://localhost:8080 and http://localhost:8761
Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

You will see output like the following when it’s finished:

Okta application configuration has been written to: /path/to/app/.okta.env

Run cat .okta.env (or type .okta.env on Windows) to see the issuer and credentials for your app. It will look like this (except the placeholder values will be populated):

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="https://{yourOktaDomain}/oauth2/default"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="{clientId}"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="{clientSecret}"

NOTE: You can also use the Okta Admin Console to create your app. See Create a JHipster App on Okta for more information.

Add the settings from the generated .okta.env to kubernetes/registry-k8s/application-configmap.yml:

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>

Enable the OIDC authentication in the jhipster-registry service by adding the oauth2 profile in the kubernetes/registry-k8s/jhipster-registry.yml file:

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

We are going to build the gateway and store in a continuous integration workflow with CircleCI.

Set up CI for JHipster with CircleCI

First, create the CircleCI configuration for the store microservice and the gateway. "What about the blog app?", you might ask. I'm not including it in this example to streamline this tutorial. You should be able to configure it similar to the store if you want to deploy everything.

cd store
jhipster ci-cd

cd gateway
jhipster ci-cd

For both applications, choose the following options:

What CI/CD pipeline do you want to generate? CircleCI
What tasks/integrations do you want to include? (none)

You must tweak the generated configuration at store/.circleci/config.yml, as the following changes are required for successful execution:

Change the execution environment of the workflow to a dedicated VM, as that is required by the TestContainers dependency in tests. The chosen environment is LinuxVM, a standalone Ubuntu 20.04 virtual machine.
As the dedicated VM includes Docker, the Docker installation step in the configuration must be removed.
Add a conditional step for building and pushing the image to Docker Hub, only if the branch name is main.

Note: You can also configure the job to only build specific branches.

The final config.yml must look like this:

version: 2.1
jobs:
  build:
    environment:
      DOCKERHUB_USER: your-dockerhub-username
      IMAGE_NAME: your-dockerhub-username/store
    machine:
      image: ubuntu-2004:current
    resource_class: large
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "build.gradle" }}-{{ checksum "package-lock.json" }}
            # Perform a Partial Cache Restore (https://circleci.com/docs/2.0/caching/#restoring-cache)
            - v1-dependencies-
      - run:
          name: Print Java Version
          command: 'java -version'
      - run:
          name: Print Node Version
          command: 'node -v'
      - run:
          name: Print NPM Version
          command: 'npm -v'
      - run:
          name: Install Node Modules
          command: 'npm install'
      - save_cache:
          paths:
            - node
            - node_modules
            - ~/.gradle
          key: v1-dependencies-{{ checksum "build.gradle" }}-{{ checksum "package-lock.json" }}
      - run:
          name: Give Executable Power
          command: 'chmod +x gradlew'
      - run:
          name: Backend tests
          command: npm run ci:backend:test
      - when:
          condition:
            equal: [ main, << pipeline.git.branch >> ]
          steps:
            - run:
                name: Build and Publish Docker Image
                command: |
                  ./gradlew -Pprod bootJar jib \
                    -Djib.to.image=$IMAGE_NAME \
                    -Djib.to.auth.username=$DOCKERHUB_USER \
                    -Djib.to.auth.password=$DOCKERHUB_PASS

Do the same updates to the gateway/.circleci/config.yml file. Additionally, the following change is required:

Add ~/.cache/Cypress as a cache path

Be sure to replace your-dockerhub-username and set the correct IMAGE_NAME.
The final config.yml for the gateway must look like this:

version: 2.1
jobs:
  build:
    environment:
      DOCKERHUB_USER: your-dockerhub-username
      IMAGE_NAME: your-dockerhub-username/gateway
    machine:
      image: ubuntu-2004:current
    resource_class: large
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "build.gradle" }}-{{ checksum "package-lock.json" }}
            # Perform a Partial Cache Restore (https://circleci.com/docs/2.0/caching/#restoring-cache)
            - v1-dependencies-
      - run:
          name: Print Java Version
          command: 'java -version'
      - run:
          name: Print Node Version
          command: 'node -v'
      - run:
          name: Print NPM Version
          command: 'npm -v'
      - run:
          name: Install Node Modules
          command: 'npm install'
      - save_cache:
          paths:
            - node
            - node_modules
            - ~/.gradle
            - ~/.cache/Cypress
          key: v1-dependencies-{{ checksum "build.gradle" }}-{{ checksum "package-lock.json" }}
      - run:
          name: Give Executable Power
          command: 'chmod +x gradlew'
      - run:
          name: Backend tests
          command: npm run ci:backend:test
      - run:
          name: Run Front End Tests
          command: npm run ci:frontend:test
      - when:
          condition:
            equal: [ main, << pipeline.git.branch >> ]
          steps:
            - run:
                name: Build and Publish Docker Image
                command: |
                  ./gradlew -Pprod bootJar jib \
                    -Djib.to.image=$IMAGE_NAME \
                    -Djib.to.auth.username=$DOCKERHUB_USER \
                    -Djib.to.auth.password=$DOCKERHUB_PASS

To take advantage of the one-step GitHub integration of CircleCI, you need a GitHub account. After signing in to GitHub, create a new public repository store. Follow the instructions to push the existing repository from your local machine to GitHub using the command line. Do the same with the gateway project.

Sign up at CircleCI with your GitHub account, and on the left menu choose Projects. Find the store project and click Set Up Project. Configure the project to use the Fastest option (Use the .circleci/config.yml in my repo) and type main for the branch. Click Set Up Project to continue.

Do the same for the gateway project. The configuration triggers an initial pipeline execution that will fail, because you still must set up Docker Hub credentials for both projects, allowing CircleCI to push the container images. At the store project page, on the top right, choose Project Settings. Then choose Environment Variables. Click Add Environment Variable. and set the following values:

Name: DOCKERHUB_PASS
Value: your Docker Hub password, or better, a Docker Hub access token if you have 2FA enabled.

NOTE: For creating a Docker Hub access token, sign in to Docker Hub, and choose Account Settings in the top right user menu. Then, on the left menu, choose Security. Click New Access Token and set a description for the token, for example, circleci. Then click Generate and copy the new token. You can use the same token for both projects store and gateway.

Once a project is set up in CircleCI, a pipeline is triggered each time a commit is pushed to the configured branch. The pipeline in execution appears on the Dashboard page. You can also manually trigger the pipeline from the Dashboard if you choose the project and branch from the pipeline filters, and then click Trigger Pipeline. Before moving on to the next section, manually execute the store pipeline and the gateway pipeline once, to push the first image of each to DockerHub.

NOTE: If you modify the configuration, and encounter CircleCI cache errors, the only way I found to recreate the cache is to update the version prefix, for example:

v2-dependencies-{{ checksum "build.gradle" }}-{{ checksum "package-lock.json" }}

Install Spinnaker on Google Kubernetes Engine

Although CircleCI supports deployment for common targets, Spinnaker is a deployment manager that supports multiple cloud providers, promoting artifacts through stages (dev, staging, UAT, production), and creating continuous delivery workflows. Spinnaker does not support CI, but it can listen to events and collect artifacts produced by external CI systems.

You can choose among the following installation environments for Spinnaker:

Distributed installation on Kubernetes
Local installation of Debian packages
Local git installation from GitHub

For this example, the distributed alternative was selected. But before the installation, learn about some key concepts in Spinnaker configuration.

Understand Spinnaker artifacts and accounts

A Spinnaker artifact is a named JSON object that refers to an external resource, for example, a Docker image or a file stored in GitHub. In a pipeline trigger, you can specify an expected artifact, and Spinnaker will compare the incoming artifact from the trigger and bind it to be used by the trigger or another stage in the pipeline.
Also in Kubernetes, the deployed manifests can be provided statically or as an artifact. In this example, manifests are provided as artifacts stored in GitHub.

For Spinnaker to access and act on resources, like Docker registries, cloud providers, and code repositories, different types of accounts must be enabled in the Spinnaker configuration, along with the credentials. In addition, the configuration has the optional step of associating Spinnaker with a Kubernetes service account, allowing you to restrict permissions over the cluster resources granted to Spinnaker.

Install Halyard

As described in Spinnaker docs, the first step is to install Halyard. For a local install in MacOS:

curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/macos/InstallHalyard.sh
sudo bash InstallHalyard.sh

Verify the installation with:

hal -v

You must also install kubectl, the Kubernetes command line tool, to run commands against the clusters.

Choose GKE for Spinnaker deployment

The second step is to choose a cloud provider for the environment in which you will install Spinnaker. For Kubernetes, Spinnaker needs a kubeconfig file, to access and manage the cluster. For creating a kubeconfig for a GKE cluster, you must first create the cluster. Google Cloud provides a free tier of their services that grants you $300 in free credits if you are a new user.

After you sign up, install gcloud CLI. When you reach the end of the process, the last step is to run gcloud init and set up authorization for the tool. Also install the Kubectl authentication plugin.

Create the cluster for the Spinnaker deployment with the following line:

gcloud container clusters create spinnaker-cluster \
--zone southamerica-east1-a \
--machine-type n1-standard-4 \
--enable-autorepair \
--enable-autoupgrade

Then fetch the cluster credentials with:

gcloud container clusters get-credentials spinnaker-cluster --zone southamerica-east1-a

get-credentials will update a kubeconfig file with appropriate credentials and endpoint information to point kubectl at a specific cluster in Google Kubernetes Engine.

Create a namespace for the Spinnaker cluster:

kubectl create namespace spinnaker

The Spinnaker documentation recommends creating a Kubernetes service account, using Kubernetes role definitions that restrict the permissions granted to the Spinnaker account. Create a spinnaker folder in the root folder or any other location. Add the file spinnaker-service-account.yml with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: spinnaker-role
rules:
  - apiGroups: ['']
    resources:
      [
        'namespaces',
        'configmaps',
        'events',
        'replicationcontrollers',
        'serviceaccounts',
        'pods/log',
      ]
    verbs: ['get', 'list']
  - apiGroups: ['']
    resources: ['pods', 'services', 'secrets']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
  - apiGroups: ['autoscaling']
    resources: ['horizontalpodautoscalers']
    verbs: ['list', 'get']
  - apiGroups: ['apps']
    resources: ['controllerrevisions']
    verbs: ['list']
  - apiGroups: ['extensions', 'apps']
    resources: ['daemonsets', 'deployments', 'deployments/scale', 'ingresses', 'replicasets', 'statefulsets']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
  # These permissions are necessary for Halyard to operate. We use this role also to deploy Spinnaker itself.
  - apiGroups: ['']
    resources: ['services/proxy', 'pods/portforward']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: spinnaker-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: spinnaker-role
subjects:
  - namespace: spinnaker
    kind: ServiceAccount
    name: spinnaker-service-account
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: spinnaker-service-account
  namespace: spinnaker

Then execute the following commands to create the service account in the current context:

CONTEXT=$(kubectl config current-context)

kubectl apply --context $CONTEXT \
    -f ./spinnaker-service-account.yml

TOKEN=$(kubectl get secret --context $CONTEXT \
   $(kubectl get serviceaccount spinnaker-service-account \
       --context $CONTEXT \
       -n spinnaker \
       -o jsonpath='{.secrets[0].name}') \
   -n spinnaker \
   -o jsonpath='{.data.token}' | base64 --decode)

kubectl config set-credentials ${CONTEXT}-token-user --token $TOKEN

kubectl config set-context $CONTEXT --user ${CONTEXT}-token-user

Enable the Kubernetes provider in Halyard:

hal config provider kubernetes enable

NOTE: You will see warnings related to missing configuration. Be patient, in the following steps all will be solved.

Add the service account to the Halyard configuration:

CONTEXT=$(kubectl config current-context)

hal config provider kubernetes account add spinnaker-gke-account \
    --context $CONTEXT

Choose the installation environment

The Distributed installation on Kubernetes deploys each Spinnaker's microservice separately to a remote cloud, and it is the recommended environment for zero-downtime updates of Spinnaker.

Select the distributed deployment with:

hal config deploy edit --type distributed --account-name spinnaker-gke-account

Choose a storage service

Spinnaker requires an external storage provider for persisting application settings and configured pipelines. To avoid losing this data, using a hosted storage solution is recommended. For this example, we use Google Cloud Storage. Hosting the data externally allows us to delete clusters in between sessions, and keep the pipelines once the clusters have been recreated.

In the spinnaker folder, run the following code:

SERVICE_ACCOUNT_NAME=spinnaker-gcs-account
SERVICE_ACCOUNT_DEST=~/.gcp/gcs-account.json

gcloud iam service-accounts create \
    $SERVICE_ACCOUNT_NAME \
    --display-name $SERVICE_ACCOUNT_NAME

SA_EMAIL=$(gcloud iam service-accounts list \
    --filter="displayName:$SERVICE_ACCOUNT_NAME" \
    --format='value(email)')

PROJECT=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT \
    --role roles/storage.admin --member serviceAccount:$SA_EMAIL

mkdir -p $(dirname $SERVICE_ACCOUNT_DEST)

gcloud iam service-accounts keys create $SERVICE_ACCOUNT_DEST \
    --iam-account $SA_EMAIL

BUCKET_LOCATION=us

hal config storage gcs edit --project $PROJECT \
    --bucket-location $BUCKET_LOCATION \
    --json-path $SERVICE_ACCOUNT_DEST

hal config storage edit --type gcs

The last hal commands edit the storage settings and set the storage source to GCS.

Deploy Spinnaker

You can verify the deployment configuration with:

hal config deploy

And the storage configuration with:

hal config storage

List the available Spinnaker versions:

hal version list

Set the version for the deployment with:

hal config version edit --version 1.27.0

Deploy Spinnaker to GKE:

hal deploy apply

Even if hal deploy apply returns successfully, the installation may not be complete yet. Check if the pods are ready with k9s:

k9s -n spinnaker

A healthy Spinnaker deployment will look like this:

You can connect to the Spinnaker UI using the following command:

hal deploy connect

Navigate to http://localhost:9000 and the UI should load. The Projects tab should look like the screenshot below.

Set up CD for a JHipster microservices architecture

Spinnaker is multi-cloud because it can manage delivery to multiple cloud providers. Some companies use different platforms for production and test environments. In this example, the same cloud provider (GKE) was chosen both for Spinnaker deployment and for the application test deployment.

Use GKE for Kubernetes deployment

Now I'll show you how to add a new Kubernetes account for a different cluster, which will be used for application deployment.

Create a cluster for the JHipster microservices architecture:

gcloud container clusters create jhipster-cluster \
--zone southamerica-east1-a \
--machine-type n1-standard-4 \
--enable-autorepair \
--enable-autoupgrade

Fetch the cluster credentials:

gcloud container clusters get-credentials jhipster-cluster --zone southamerica-east1-a

Create the namespace demo for your microservices:

kubectl create namespace demo

In the spinnaker directory, create the file jhipster-service-account.yml:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: jhipster-role
rules:
  - apiGroups: ['']
    resources:
      [
        'namespaces',
        'events',
        'replicationcontrollers',
        'serviceaccounts',
        'pods/log',
      ]
    verbs: ['get', 'list']
  - apiGroups: ['']
    resources: ['pods', 'services', 'secrets', 'configmaps', 'persistentvolumeclaims']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
  - apiGroups: ['autoscaling']
    resources: ['horizontalpodautoscalers']
    verbs: ['list', 'get']
  - apiGroups: ['apps']
    resources: ['controllerrevisions']
    verbs: ['list']
  - apiGroups: ['extensions', 'apps']
    resources: ['daemonsets', 'deployments', 'deployments/scale', 'ingresses', 'replicasets', 'statefulsets']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
  # These permissions are necessary for Halyard to operate. We use this role also to deploy Spinnaker itself.
  - apiGroups: ['']
    resources: ['services/proxy', 'pods/portforward']
    verbs:
      [
        'create',
        'delete',
        'deletecollection',
        'get',
        'list',
        'patch',
        'update',
        'watch',
      ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: jhipster-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: jhipster-role
subjects:
  - namespace: demo
    kind: ServiceAccount
    name: jhipster-service-account
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: jhipster-service-account
  namespace: demo

Notice there are some differences with the Spinnaker service account. The k8s manifests generated by JHipster include the creation of secrets, configmaps, and persistentvolumeclaims. The management of those Kubernetes resources must be granted to the service account used for deploying the JHipster k8s manifests.

Create the Kubernetes jhipster-service-account:

CONTEXT=$(kubectl config current-context)

kubectl apply --context $CONTEXT \
    -f ./jhipster-service-account.yml
TOKEN=$(kubectl get secret --context $CONTEXT \
   $(kubectl get serviceaccount jhipster-service-account \
       --context $CONTEXT \
       -n demo \
       -o jsonpath='{.secrets[0].name}') \
   -n demo \
   -o jsonpath='{.data.token}' | base64 --decode)

kubectl config set-credentials ${CONTEXT}-token-user --token $TOKEN

kubectl config set-context $CONTEXT --user ${CONTEXT}-token-user

Add the account to the Halyard configuration:

CONTEXT=$(kubectl config current-context)

hal config provider kubernetes account add jhipster-gke-account \
    --context $CONTEXT

Add a Docker registry account

As the goal is to trigger the pipeline execution when a new image is pushed to Docker Hub, you need to configure a Docker Registry provider with Halyard.

First, enable the Docker Registry provider:

hal config provider docker-registry enable

The following hal config line will prompt for your password (or access token if you have 2FA enabled). Make sure to replace your-dockerhub-username.

ADDRESS=index.docker.io
USERNAME=your-dockerhub-username

hal config provider docker-registry account add docker-account \
    --address $ADDRESS \
    --repositories $USERNAME/store $USERNAME/gateway \
    --username $USERNAME \
    --password

Add a GitHub artifact account

The pipeline will deploy k8s manifests from a GitHub repository, so you must also configure a GitHub artifact account. First, enable the feature:

hal config artifact github enable

Generate an access token on GitHub. Sign in, and in the user menu choose Settings. Then on the left menu choose Developer settings. On the left menu choose Personal access tokens. Click Generate new token and copy the token.

Then add your GitHub username and set the new token when prompted:

ARTIFACT_ACCOUNT_NAME=your-github-username

hal config artifact github account add $ARTIFACT_ACCOUNT_NAME \
    --token

The new GKE, Docker, and GitHub account configurations must be applied to the deployment before starting the pipeline design:

hal deploy apply

Create the store microservice pipeline

The pipeline is the central concept in deployment management with Spinnaker. It is compounded by a sequence of actions, named stages. A pipeline can be triggered manually or automatically, and have an execution history. Connect to the Spinnaker UI again to create the first pipeline.

hal deploy connect

Navigate to https://localhost:9000 > Applications. Click Create Application and just set the application name and owner email. The repository type and additional fields are not mandatory and you can leave all blank for this test.

Then, on the left menu, choose Pipelines and click Configure a new pipeline. Set a name for the pipeline, for example, store-cd.

Configure the Docker image triggers

In the pipeline configuration, click Add Trigger. Set the following configuration for the trigger:

Type: Docker Registry
Registry Name: docker-account
Organization: your-dockerhub-username
Image: your-dockerhub-username/store
Artifact Constraints: Choose Define new artifact

In the Expected Artifact form, set the following values:

Display Name: store-image
Account: docker-registry
Docker image: Fully qualified index.docker.io/your-dockerhub-username/store
Use prior execution: yes
Use default artifact: yes (set the same account and object path as before)

Click Save Artifact.

IMPORTANT NOTE: Spinnaker provides a mechanism to override the version of Docker images, Kubernetes ConfigMaps, and Secrets in manifests, injecting new versions when one of these objects exists in the pipeline context. However, Spinnaker documentation does not have a clear example of the trigger configuration for the Docker image to be available in the pipeline context. To make it happen, you must set it as an artifact constraint in the trigger. If the artifact constraint is not defined, the original image version in the manifests will be deployed, instead of the new image that triggered the pipeline. If no version is in the manifests, latest will be the default.

Add a second Docker registry trigger for the gateway image pushes and click Save Changes.

Configure the deployment stages

The store pipeline will execute the following stages:

Deploy the application ConfigMap
Deploy the JHipster Registry
Deploy the gateway database PostgreSQL
Deploy the store clustered database MongoDB
Deploy the gateway microservice
Deploy the store microservice
Enable the gateway service
Enable the store service

The Kubernetes configuration created in the folder jhipster-ci-cd/kubernetes must be pushed to a GitHub repository, so Spinnaker can access it using the GitHub artifact account created earlier. But before you push, edit kubernetes/store-k8s/store-deployment.yml and set the image name with the fully qualified address:

- name: store-app
  image: index.docker.io/indiepopart/store

Do the same for kubernetes/gateway-k8s/gateway-deployment.yml. This is also required for the artifact substitution to work.

Sign in to GitHub and create a public repository jhipster-k8s. Follow the instructions to push the existing kubernetes folder from your local using the command line.

IMPORTANT NOTE: At this point, you will be pushing plain secrets contained in the application and Kubernetes configuration. To avoid this insecure anti-pattern, you can run the JHipster registry locally to encrypt application configuration, and also set up kubeseal for Kubernetes secrets encryption. The process is described in a previous post: Kubernetes to the Cloud with Spring Boot and JHipster.

Go back to Spinnaker UI, and in the pipeline configuration choose Add Stage and set the following values:

Type: Deploy (Manifest)
Stage Name: deploy application-configmap
Account: jhipster-gke-account
Override Namespace: yes
Namespace: demo
Manifest Source: Artifact
Manifest Artifact: Define a new artifact

In the artifact fields, set the following values:

Account: your-github-username
Content URL: https://api.github.com/repos/your-github-username/jhipster-k8s/contents/registry-k8s/application-configmap.yml
Commit/Branch: main

Click Save Changes.
Repeat the process for adding stages to deploy jhipster-registry.yml, which must depend on the previous manifest. Also repeat for gateway-postgresql.yml, store-mongodb.yml manifests, which both should depend on the jhipster-registry stage. Make sure to set the correct Content URL for the GitHub artifact. It must have the form https://api.github.com/repos/<your-github-username>/<repo-name>/contents/<path>. If you open the URL in a browser, it should render a JSON response.

Add a stage for the store-deployment.yml manifest, it must depend on the store-mongodb stage. For this manifest, you must bind the Docker image from the context. In the deploy manifest configuration, in Required Artifacts to Bind, choose store-image. The option must be available, as the image was set as an artifact constraint in the trigger configuration, making the artifact available in the pipeline context.

Also add a stage for the gateway-deployment.yml, binding the gateway Docker image. It must depend on the gateway-postgresql stage.

Finally, add a stage for store-service.yml, which must depend on the store-deployment stage, and a stage for gateway-service.yml, which must depend on the gateway-postgresql stage. Notice that Docker images have to be bound only for the manifests that contain a reference to the image.
The complete pipeline must look like this:

Test the pipeline manually once. Go to Pipelines and select Start Manual Execution for the store-cd pipeline. Set the following options:

Trigger: leave docker-account: your-dockerhub-username/store
Type: Tag
Tag: latest

Successful execution will show all stages in a green state:

Get the external IP of the gateway:

kubectl get svc gateway -n demo

Update the redirect URIs in Okta to allow the gateway address as a valid redirect. Run okta login, open the returned URL in your browser, and sign in to the Okta Admin Console. Go to the Applications section, find your application, edit, and add:

Sign-in redirect URIs: http://<external-ip>:8080/login/oauth2/code/oidc
Sign-out redirect URIs: http://<external-ip>:8080

Navigate to http://<external-ip>:8080 and sign in to the application with your Okta credentials. Then try creating a Product:

Trigger the CI/CD pipeline with a GitHub push

For testing the workflow, make a code change in the gateway. Edit src/main/webapp/content/scss/_bootstrap-variables.scss and update the following variable:

$body-bg: steelblue;

Also, the pipeline under test will only trigger if a new image tag is detected. So edit .circleci/confg.yml and update the image name:

IMAGE_NAME: indiepopart/gateway:v1

Commit and push the change to the main branch, and watch the CircleCI CI pipeline triggers. After the new gateway image is pushed to Docker Hub, watch the Spinnaker CD pipeline trigger and deploy the updated gateway. On the left menu choose Clusters, and verify the active gateway deployment now has a V002. If you click over the V002 box, you can also verify the image tag that was deployed.

You can delete clusters in between sessions to save costs with the following gcloud commands:

gcloud container clusters delete <cluster-name> \
  --zone <cluster-zone>

The cloud storage used by Spinnaker for pipeline persistence generates some costs, you can also delete it with the CLI or using the web console.

Inspect Spinnaker logs

For pipeline and trigger debugging, the Spinnaker services spin-echo and spin-igor inform Docker monitoring events and indicate the reasons why an execution was skipped.

kubectl get pods -n spinnaker
kubectl logs spin-igor-7c8bdd94f5-lx5dl -n spinnaker | grep v1

Found 1 new images for docker-account. Images: [{imageId=igor:dockerRegistry:v2:docker-account:indiepopart/gateway:v1, sendEvent=true}]
New tagged image: account=docker-account, image=igor:dockerRegistry:v2:docker-account:indiepopart/gateway:v1. Digest is now [null].
Sending tagged image info to echo: account=docker-account: image=igor:dockerRegistry:v2:docker-account:indiepopart/gateway:v1

Spinnaker features and best practices

When implementing continuous delivery, here are some best practices and key features to be aware of:

Deploy Docker images by digest: Spinnaker documentation recommends deploying images by digest instead of tag, because the tag might reference different content each time. The digest is a content-based hash of the image and it uniquely identifies it. Spinnaker's artifact substitution allows deploying the same manifest, with the image digest supplied by the pipeline trigger. Using the proposed trigger and a free Docker Hub account as the registry, the digest data seems not to be available. It is also recommended to trigger a CD pipeline off of a push to a Docker registry instead of a GitHub push or Jenkins job, allowing development teams to choose their delivery process without more constraints.
Rollbacks: Just as there is a stage for deploying manifests, there are also stages for deleting, scaling, and rolling back manifests. Spinnaker also supports automated rollbacks, as it exposes the Undo Rollout functionality as a stage, which can be configured to run when other stages fail, and to roll back by a number of revisions of the deployed object. ConfigMaps and Secrets must be versioned for the automated rollback to actually roll back code or configuration.
Manual judgments: The pipeline can include a manual judgment stage, that will make the execution interrupt, asking for user input to continue or cancel. This can be used to ask for confirmation before promoting a staging deployment to production.
Pipeline management: Spinnaker represents pipelines as JSON behind the scenes, and maintains a revision history of the changes made to the pipeline. It also supports pipeline templates, that can be managed through the spin CLI, and help with pipeline sharing and distribution.
Canary: You can automate Canary analysis by creating canary stages for your pipeline. Canary must be enabled in the Spinnaker installation using hal commands. The Canary analysis consists of the evaluation of metrics chosen during configuration, comparing a partial rollout with the current deployment. The stage will fail based on the deviation criteria configured for the metric.
Secrets management: Spinnaker does not directly support secrets management. Secrets should be encrypted at rest and in transit. Credentials encryption for application secrets and Kubernetes secrets was covered in a recent post: Kubernetes to the Cloud with Spring Boot and JHipster.
Rollout strategies: The Spinnaker Kubernetes provider supports running dark, highlander, and red/black rollouts. In the Deploy Manifest stage, there is a strategy option that allows associating workload to a service, sending traffic to it, and choosing how to handle any previous versions of the workload in the same cluster and namespace.

Learn more about JHipster, microservices, and Kubernetes

This article looks at the nuts and bolts of JHipster deployments. CI and CD propose several organizational and technical practices aimed at improving team confidence, efficiency, and productivity. Spinnaker is a powerful tool for continuous deployment, with more than 200 companies around the world contributing to its growth.

As each architecture and organization is different, your pipeline design must be customized to your particular use case. I hope this brief introduction will help you get the most out of these wonderful tools.

To learn more about JHipster and its microservices support, check out the following links:

Be sure to follow us on Twitter and subscribe to our YouTube Channel so that you never miss any of our excellent content!

How to Deploy JHipster Microservices on Amazon EKS Using Terraform and Kubernetes

Deepu K Sasidharan — Tue, 05 Jul 2022 13:50:34 +0000

When it comes to infrastructure, public clouds are the most popular choice these days, especially Amazon Web Services (AWS). If you are in one of those lucky or unlucky (depending on how you see it) teams running microservices, then you need a way to orchestrate their deployments. When it comes to orchestrating microservices, Kubernetes is the de-facto choice. Most public cloud providers also provide managed Kubernetes as a service; for example, Google provides Google Kubernetes Engine (GKE), Microsoft provides Azure Kubernetes Service (AKS), and Amazon provides Amazon Elastic Kubernetes Service (EKS).

This doesn't mean that deploying and managing microservices on the public cloud is easy; each cloud service comes with its own challenges and pain. This is especially true for Amazon EKS, which, in my opinion, is the most difficult Kubernetes service to use, but also one of the most flexible. This is because EKS consists of some clever orchestrations doing a complex dance on top of other AWS services like EC2, EBS, etc.

If you want to run a microservice stack on EKS, you will need to spend some extra time and effort setting it up and managing it. This is where infrastructure as code (IaC) tools like Terraform come in handy.

So here is what you will learn to do today:

Scaffold a Java microservice stack using JHipster, Spring Boot, and Spring Cloud
Create an EKS cluster, Virtual Private Cloud (VPC), subnets, and required Kubernetes add-ons using Terraform on AWS
Set up OIDC authentication for the microservice stack using Okta
Build and deploy the microservice stack to the cluster

Prerequisites

AWS account with the IAM permissions to create EKS clusters
AWS CLI installed and configured
AWS IAM Authenticator installed
kubectl installed
Docker installed and configured
Terraform installed
Java 11+ installed
Okta CLI installed
JHipster CLI installed
[Optional] KDash

Why Terraform, why not CloudFormation?

At this point, the first question that might pop up in your mind would be, "Why not use CloudFormation?". It's a good question; after all, CloudFormation is built by AWS and hence sounds like an excellent solution to manage AWS resources. But anyone who has tried both CloudFormation and Terraform will probably tell you to forget that CloudFormation even exists. I think CloudFormation is far more complex and less developer-friendly than Terraform. You also need to write a lot more boilerplate with CloudFormation in YAML or JSON. Yikes! And most importantly, Terraform is far more powerful and flexible than CloudFormation. It's cross-platform, which means you can take care of all your infrastructure management needs on any platform with one tool.

Scaffold a Java microservice stack using JHipster

You need a microservice stack to deploy to the cluster. I'm using a microservice stack scaffolded for demo purposes using JHipster. You can use another microservice stack if you want. If you prefer using the same application as in this demo, then you can either scaffold it using JHipster JDL or clone the sample repository from GitHub.

Option 1: Scaffold the microservice stack using JHipster



mkdir jhipster-microservice-stack
cd jhipster-microservice-stack
# download the JDL file.
jhipster download https://raw.githubusercontent.com/oktadev/okta-jhipster-k8s-eks-microservices-example/main/apps.jdl
# Update the `dockerRepositoryName` property to use your Docker Repository URI/Name.
# scaffold the apps.
jhipster jdl apps.jdl

Option 2: Clone the sample repository



git clone https://github.com/oktadev/okta-jhipster-k8s-eks-microservices-example

In either case, remember to change the Docker repository name to match your Docker repository.

The JHipster scaffolded sample application has a gateway application, two microservices, and uses JHipster Registry for service discovery and centralized configuration.

Create an EKS cluster using Terraform

Now let us move on to the important part of the tutorial. Creating an EKS cluster in AWS is not as straightforward as in Google Cloud Platform (GCP). You need to also create a lot more resources for everything to work correctly without surprises. You will be using a bunch of Terraform providers to help with this, and you will also use some prebuilt Terraform modules like AWS VPC Terraform module and Amazon EKS Blueprints for Terraform to reduce the amount of boilerplate you need to write.

These are the AWS resources and VPC architecture you will create:

Build the Terraform configuration

First, make sure you use a specific version of the providers as different versions might use different attributes and features. Create a versions.tf file:



mkdir terraform
cd terraform
touch versions.tf

Add the following to the file:



terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 3.72"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = ">= 2.10"
    }
    helm = {
      source  = "hashicorp/helm"
      version = ">= 2.4.1"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.2.0"
    }
    nullres = {
      source  = "hashicorp/null"
      version = ">= 3.1"
    }
  }
}

Next, you need to define variables and configure the providers. Create a config.tf file:



touch config.tf

Add the following to the file:



# ##  To save state in s3. Update to suit your needs
# backend "s3" {
#   bucket = "create-an-s3-bucket-and-provide-name-here"
#   region = local.region
#   key    = "eks-cluster-with-new-vpc/terraform.tfstate"
# }

variable "region" {
  default     = "eu-west-1"
  description = "AWS region"
}

resource "random_string" "suffix" {
  length  = 8
  special = false
}

data "aws_availability_zones" "available" {}

locals {
  name            = "okta-jhipster-eks-${random_string.suffix.result}"
  region          = var.region
  cluster_version = "1.22"
  instance_types  = ["t2.large"] # can be multiple, comma separated

  vpc_cidr = "10.0.0.0/16"
  azs      = slice(data.aws_availability_zones.available.names, 0, 3)

  tags = {
    Blueprint  = local.name
    GitHubRepo = "github.com/aws-ia/terraform-aws-eks-blueprints"
  }
}

provider "aws" {
  region = local.region
}

# Kubernetes provider
# You should **not** schedule deployments and services in this workspace.
# This keeps workspaces modular (one for provision EKS, another for scheduling
# Kubernetes resources) as per best practices.
provider "kubernetes" {
  host                   = module.eks_blueprints.eks_cluster_endpoint
  cluster_ca_certificate = base64decode(module.eks_blueprints.eks_cluster_certificate_authority_data)

  exec {
    api_version = "client.authentication.k8s.io/v1alpha1"
    command     = "aws"
    # This requires the awscli to be installed locally where Terraform is executed
    args = ["eks", "get-token", "--cluster-name", module.eks_blueprints.eks_cluster_id]
  }
}

provider "helm" {
  kubernetes {
    host                   = module.eks_blueprints.eks_cluster_endpoint
    cluster_ca_certificate = base64decode(module.eks_blueprints.eks_cluster_certificate_authority_data)

    exec {
      api_version = "client.authentication.k8s.io/v1alpha1"
      command     = "aws"
      # This requires the awscli to be installed locally where Terraform is executed
      args = ["eks", "get-token", "--cluster-name", module.eks_blueprints.eks_cluster_id]
    }
  }
}

You can uncomment the backend section above to save state in S3 instead of your local filesystem. This is recommended for production setup so that everyone in a team has the same state. This file defines configurable and local variables used across the workspace and configures some of the providers used. The Kubernetes provider is included in this file so the EKS module can complete successfully. Otherwise, it throws an error when creating kubernetes_config_map.aws_auth. The helm provider is used to install Kubernetes add-ons to the cluster.

Build the VPC

Next up, you need a VPC, subnets, route tables, and other networking bits. You will use the vpc module from the terraform-aws-modules repository. This module is a wrapper around the AWS VPC module. It makes it easier to configure VPCs and all the other required networking resources. Create a vpc.tf file:



touch vpc.tf

Add the following to the file:



#---------------------------------------------------------------
# VPC, Subnets, Internet gateway, Route tables, etc.
#---------------------------------------------------------------
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 3.0"

  name = local.name
  cidr = local.vpc_cidr

  azs             = local.azs
  public_subnets  = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 8, k)]
  private_subnets = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 8, k + 10)]

  enable_nat_gateway   = true
  single_nat_gateway   = true
  enable_dns_hostnames = true

  # Manage so we can name
  manage_default_network_acl    = true
  default_network_acl_tags      = { Name = "${local.name}-default" }
  manage_default_route_table    = true
  default_route_table_tags      = { Name = "${local.name}-default" }
  manage_default_security_group = true
  default_security_group_tags   = { Name = "${local.name}-default" }

  public_subnet_tags = {
    "kubernetes.io/cluster/${local.name}" = "shared"
    "kubernetes.io/role/elb"              = 1
  }

  private_subnet_tags = {
    "kubernetes.io/cluster/${local.name}" = "shared"
    "kubernetes.io/role/internal-elb"     = 1
  }

  tags = local.tags
}

This will create:

A new VPC, three private subnets, and three public subnets,
Internet gateway and NAT gateway for the public subnets,
and AWS routes for the gateways, public/private route tables, and route table associations.

Build the EKS cluster

Now that you have the networking part done, you can build configurations for the EKS cluster and its add-ons. You will use the eks_blueprints module from terraform-aws-eks-blueprints, which is a wrapper around the terraform-aws-modules and provides additional modules to configure EKS add-ons.

Create a eks-cluster.tf file:



touch eks-cluster.tf

Add the following to the file:



#---------------------------------------------------------------
# EKS cluster, worker nodes, security groups, IAM roles, K8s add-ons, etc.
#---------------------------------------------------------------
module "eks_blueprints" {
  source = "github.com/aws-ia/terraform-aws-eks-blueprints?ref=v4.0.9"

  cluster_name    = local.name
  cluster_version = local.cluster_version

  vpc_id             = module.vpc.vpc_id
  private_subnet_ids = module.vpc.private_subnets

  managed_node_groups = {
    node = {
      node_group_name = "managed-ondemand"
      instance_types  = local.instance_types
      min_size        = 2
      subnet_ids      = module.vpc.private_subnets
    }
  }

  tags = local.tags
}

module "eks_blueprints_kubernetes_addons" {
  source = "github.com/aws-ia/terraform-aws-eks-blueprints//modules/kubernetes-addons?ref=v4.0.9"

  eks_cluster_id       = module.eks_blueprints.eks_cluster_id
  eks_cluster_endpoint = module.eks_blueprints.eks_cluster_endpoint
  eks_oidc_provider    = module.eks_blueprints.oidc_provider
  eks_cluster_version  = module.eks_blueprints.eks_cluster_version

  # EKS Managed Add-ons
  enable_amazon_eks_vpc_cni    = true
  enable_amazon_eks_coredns    = true
  enable_amazon_eks_kube_proxy = true

  # K8S Add-ons
  enable_aws_load_balancer_controller = true
  enable_metrics_server               = true
  enable_cluster_autoscaler           = true
  enable_aws_cloudwatch_metrics       = false

  tags = local.tags

}

# To update local kubeconfig with new cluster details
resource "null_resource" "kubeconfig" {
  depends_on = [module.eks_blueprints_kubernetes_addons]
  provisioner "local-exec" {
    command = "aws eks --region ${local.region}  update-kubeconfig --name $AWS_CLUSTER_NAME"
    environment = {
      AWS_CLUSTER_NAME = local.name
    }
  }
}

The eks_blueprints module definition creates:

EKS Cluster Control plane with one managed node group and fargate profile,
Cluster and node security groups and rules, IAM roles and policies required,
and AWS Key Management Service (KMS) configuration.

The eks_blueprints_kubernetes_addons module definition creates:

Amazon EKS add-ons vpc-cni, CoreDNS, and kube-proxy,
AWS Load Balancer Controller that provisions an AWS Network Load Balancer for distributing traffic,
and Metrics Server, and Cluster Autoscaler for scaling your workloads.

The null_resource configuration updates your local kubeconfig with the new cluster details. It's not a required step for provisioning but just a handy hack.

Finally, you can also define some outputs to be captured. Create a outputs.tf file:



touch outputs.tf

Add the following to the file:



output "vpc_private_subnet_cidr" {
  description = "VPC private subnet CIDR"
  value       = module.vpc.private_subnets_cidr_blocks
}

output "vpc_public_subnet_cidr" {
  description = "VPC public subnet CIDR"
  value       = module.vpc.public_subnets_cidr_blocks
}

output "vpc_cidr" {
  description = "VPC CIDR"
  value       = module.vpc.vpc_cidr_block
}

output "eks_cluster_id" {
  description = "EKS cluster ID"
  value       = module.eks_blueprints.eks_cluster_id
}

output "eks_managed_nodegroups" {
  description = "EKS managed node groups"
  value       = module.eks_blueprints.managed_node_groups
}

output "eks_managed_nodegroup_ids" {
  description = "EKS managed node group ids"
  value       = module.eks_blueprints.managed_node_groups_id
}

output "eks_managed_nodegroup_arns" {
  description = "EKS managed node group arns"
  value       = module.eks_blueprints.managed_node_group_arn
}

output "eks_managed_nodegroup_role_name" {
  description = "EKS managed node group role name"
  value       = module.eks_blueprints.managed_node_group_iam_role_names
}

output "eks_managed_nodegroup_status" {
  description = "EKS managed node group status"
  value       = module.eks_blueprints.managed_node_groups_status
}

output "configure_kubectl" {
  description = "Configure kubectl: make sure you're logged in with the correct AWS profile and run the following command to update your kubeconfig"
  value       = module.eks_blueprints.configure_kubectl
}

Provision the cluster

Our Terraform definitions are ready. Now you can provision the cluster. First, initialize Terraform workspace and plan the changes:



# download modules and providers. Initialize state.
terraform init
# see a preview of what will be done
terraform plan

Review the plan and make sure everything is correct. Ensure you have configured your AWS CLI and IAM Authenticator to use the correct AWS account. If not, run the following:



# Visit https://console.aws.amazon.com/iam/home?#/security_credentials for creating access keys
aws configure

Now you can apply the changes:



terraform apply

Confirm by typing yes when prompted. This will take a while (15-20 minutes), so sit back and have a coffee or contemplate what led you to this point in life. 😉

Once the EKS cluster is ready, you will see the output variables printed to the console.



configure_kubectl = "aws eks --region eu-west-1 update-kubeconfig --name okta-tf-demo"
eks_cluster_id = "okta-tf-demo"
eks_managed_nodegroup_arns = tolist([
  "arn:aws:eks:eu-west-1:216713166862:nodegroup/okta-tf-demo/managed-ondemand-20220610125341399700000010/f0c0a6d6-b8e1-cf91-3d21-522552d6bc2e",
])
eks_managed_nodegroup_ids = tolist([
  "okta-tf-demo:managed-ondemand-20220610125341399700000010",
])
eks_managed_nodegroup_role_name = tolist([
  "okta-tf-demo-managed-ondemand",
])
eks_managed_nodegroup_status = tolist([
  "ACTIVE",
])
eks_managed_nodegroups = tolist([
  {
    "node" = {
      "managed_nodegroup_arn" = [
        "arn:aws:eks:eu-west-1:216713166862:nodegroup/okta-tf-demo/managed-ondemand-20220610125341399700000010/f0c0a6d6-b8e1-cf91-3d21-522552d6bc2e",
      ]
      "managed_nodegroup_iam_instance_profile_arn" = [
        "arn:aws:iam::216713166862:instance-profile/okta-tf-demo-managed-ondemand",
      ]
      "managed_nodegroup_iam_instance_profile_id" = [
        "okta-tf-demo-managed-ondemand",
      ]
      "managed_nodegroup_iam_role_arn" = [
        "arn:aws:iam::216713166862:role/okta-tf-demo-managed-ondemand",
      ]
      "managed_nodegroup_iam_role_name" = [
        "okta-tf-demo-managed-ondemand",
      ]
      "managed_nodegroup_id" = [
        "okta-tf-demo:managed-ondemand-20220610125341399700000010",
      ]
      "managed_nodegroup_launch_template_arn" = []
      "managed_nodegroup_launch_template_id" = []
      "managed_nodegroup_launch_template_latest_version" = []
      "managed_nodegroup_status" = [
        "ACTIVE",
      ]
    }
  },
])
region = "eu-west-1"
vpc_cidr = "10.0.0.0/16"
vpc_private_subnet_cidr = [
  "10.0.10.0/24",
  "10.0.11.0/24",
  "10.0.12.0/24",
]
vpc_public_subnet_cidr = [
  "10.0.0.0/24",
  "10.0.1.0/24",
  "10.0.2.0/24",
]

You should see the cluster details if you run kdash or kubectl get nodes commands.

Note: The EKS cluster defined here will not come under AWS free tier; hence, running this will cost money, so delete the cluster as soon as you finish the tutorial to keep the cost within a few dollars.

Set up OIDC authentication using Okta

You can proceed to deploy the sample application. You could skip this step if you used a sample that does not use Okta or OIDC for authentication.

First, navigate to the store application folder.

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:

login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
logout: http://localhost:8080 and http://localhost:8761

Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761\* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

The OIDC app configuration will be written to .okta.env file in the folder where you ran the command.

Note: Make sure to add the newly created .okta.env file to your .gitignore file so that you don't accidentally expose your credentials to the public.

Update kubernetes/registry-k8s/application-configmap.yml with the OIDC configuration from the .okta.env file. 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>

Next, configure the JHipster Registry to use OIDC for authentication. Modify kubernetes/registry-k8s/jhipster-registry.yml to enable the oauth2 profile, which is preconfigured in the JHipster Registry application.



- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

The application is now ready.

Secure secrets

If you have noticed, you are setting secrets in plain text on the application-configmap.yml file, which is not ideal and is not a best practice for security. For the specific JHipster application, you can use the encrypt functionality provided by the JHipster Registry to encrypt the secrets. See Encrypt Your Secrets with Spring Cloud Config to learn how to do this. But that would also rely on a base64 encoded encryption key added as a Kubernetes Secret, which still can be decoded. The best way to do this would be to use AWS Secrets Manager, an external service like HashiCorp Vault, or Sealed Secrets. To learn more about these methods see Encrypt Your Kubernetes Secrets.

Deploy the microservice stack

You are ready to deploy to our shiny new EKS cluster, but first, you need to build and push the Docker images to a container registry. You can use Amazon Elastic Container Registry (ECR) or any other container registry.

Build the Docker images

You need to build Docker images for each app. This is specific to the JHipster application used in this tutorial which uses Jib to build the images. Make sure you are logged into Docker using docker login. Navigate to each app folder (store, invoice, product) and run the following command:



./gradlew bootJar -Pprod jib -Djib.to.image=<docker-repo-uri-or-name>/<image-name>

Image names should be store, invoice, and product.

Deploy the applications to EKS

Start the deployment using the handy script provided by JHipster. You could also manually apply deployments using kubectl apply -f <file> commands.



cd kubernetes
./kubectl-apply.sh -f

You can also run the following command to see the status of the deployments:



kubectl get pods -n jhipster

View the registry using port-forwarding as follows, and you will be able to access the application at http://localhost:8761.



kubectl port-forward svc/jhipster-registry -n jhipster 8761

You can access the gateway application using port-forwarding as follows, and you will be able to access the application at http://localhost:8080.



kubectl port-forward svc/store -n jhipster 8080

Or, you can access the application via the load balancer exposed. Find the external IP of the store service by navigating to the service tab in KDash or by running the following:



kubectl get svc store -n jhipster

Navigate to the Okta Admin Console and go to Applications > Applications from left-hand navigation. Find the application you created earlier with okta apps create jhipster and add the external IP from kubectl get svc command to the Sign-in redirect URIs and Sign-out redirect URIs. Make sure to use the same paths as the current localhost entries.

Now you should be able to visit the external IP of the store service on port 8080 and see the application, and you should be able to log in using your Okta credentials.

Tear down the cluster with Terraform

Once you are done with the tutorial, you can delete the cluster and all the resources created using Terraform by running the following commands:



cd terraform

# The commands below might take a while to finish.

terraform destroy -target="module.eks_blueprints_kubernetes_addons" -auto-approve

# If deleting VPC fails, then manually delete the load balancers and security groups

# for the load balancer associated with the VPC from AWS EC2 console and try again.

terraform destroy -target="module.eks_blueprints" -auto-approve

terraform destroy -target="module.vpc" -auto-approve

# cleanup anything left over.

terraform destroy -auto-approve

Learn more about Java Microservices, EKS, Kubernetes, and JHipster

If you want to learn more about Kubernetes, OIDC, or using OIDC with Kubernetes, and security in general, check out these additional resources.

You can find all the code from this example on GitHub.

If you liked this tutorial, chances are you'll enjoy the others we publish. Please follow @oktadev on Twitter and subscribe to our YouTube channel to get notified when we publish new developer tutorials.

Cloud Native Java Microservices with JHipster and Istio

Deepu K Sasidharan — Tue, 28 Jun 2022 10:24:09 +0000

Microservices are not everyone's cup of tea, and they shouldn't be. Not every problem can or should be solved by microservices. Sometimes building a simple monolith is a far better option. Microservices are solutions for use cases where scale and scalability are important. A few years ago, microservices were all the rage, made popular, especially by companies like Netflix, Spotify, Google, etc. While the hype has died down a bit, genuine use cases still exist. With ongoing advances in cloud computing technologies, building microservices as cloud-native services is the way to go due to many benefits.

Today we will look at building a cloud-native Java microservice stack that utilizes a service mesh to provide most of the distributed system needs and we'll deploy it to the cloud using Kubernetes.

So here is what we will do today:

Build a Java microservice stack using JHipster, Spring Boot, and Spring Cloud
Create a Google Kubernetes Engine (GKE) cluster
Deploy Istio service mesh to the cluster
Set up monitoring and observability
Deploy and monitor the microservices to the cluster

Let's get started!

Prerequisites

A Google Cloud Platform account
Docker installed on your machine
Node.js installed on your machine
JHipster installed on your machine
Google Cloud SDK installed and configured on your machine
kubectl or KDash
Basic understanding of Java, Spring, Containers, and Kubernetes

If you prefer to follow along by watching a video, see [How to Build Low-Code Microservices on the Cloud Using Istio, JHipster, and Kubernetes] on the OktaDev YouTube channel.

Why build cloud-native microservices using a service mesh?

Before we dive into building a cloud-native microservice stack, let's look at what a service mesh is and the benefits of using one.

A service mesh provides features to help with common distributed microservice challenges. Like service discovery, routing, load balancing, and so on. Today we will be using Istio, one of the most popular service mesh solutions available. Istio is tailored for distributed application architectures, especially those you might run in Kubernetes. Istio plays nicely with Kubernetes, so nicely that you might think that it's part of the Kubernetes platform itself. Istio isn't the only service mesh around; we also have platforms like Linkerd and Consul, which are also quite popular.

Istio specifically provides the following features.

Secure service-to-service communication over TLS. Of course, with support for identity-based authentication and authorization.
Service discovery, so that your microservices can discover each other.
Automatic load balancing for the services
Traffic control features like routing, circuit breaking, retries, fail-overs, and fault injection.
A pluggable policy layer that can enforce stuff like access control, rate limiting, A/B testing, traffic splits, quotas, etc.
It also provides automatic metrics, logs, and traces for all traffic within the cluster from Ingress to Egress and between pods.

What is Istio Service Mesh?

Let's take a quick look at Istio internals. The Istio architecture can be classified into two distinct planes.

Control plane: It consists of the istiod demon, and it manages and configures the envoy proxies to route traffic. The control plane also enforces policies and collects telemetry, and includes components like Pilot for traffic management, Citadel to manage security, and Galley to manage configurations.

Data plane: It's made of Envoy proxies deployed as sidecars to our application containers. Envoy is a high-performance, lightweight distributed proxy. It controls all the incoming and outgoing traffic to the container it is attached to.

We can use tools like Grafana, Prometheus, Kiali and Zipkin for monitoring and observability as they work well with the telemetry provided by Istio. You can use these or use your existing monitoring stack as well.

Build a Java Microservices Stack using JHipster

Before you proceed, ensure you have installed JHipster. If not, install it using the command npm -g install generator-jhipster. At the moment of writing, I'm using JHipster version 7.8.1.

We will be using the JHipster Domain Language (JDL) to define our microservices, entities, and deployment options. But first, let's take a look at the architecture we will be building today.

We have the Istio control plane taking care of policy, load balancing, etc. We also have the Istio Ingress gateway to route all external traffic to our applications. We have four microservices. First is a gateway application created by JHipster that acts as our React GUI and authentication layer. The remaining are services that provide APIs. Each of our containers will have an envoy proxy as an auto-injected sidecar. We hook up Grafana, Prometheus, Zipkin, and Kiali to the telemetry provided by Istio so that we have monitoring and observability for our cluster. Each microservice also has its own database.

If you would prefer not to build the application yourself, clone the example from GitHub.

git clone https://github.com/oktadev/okta-java-spring-k8s-istio-microservices-example.git

It's not an overly complex architecture, but it's also not that simple. First, let us define our microservice using JDL. Create a file called app.jdl and paste the following content into it.

application {
  config {
    baseName store
    applicationType gateway
    packageName com.okta.developer.store
    serviceDiscoveryType no
    authenticationType jwt
    prodDatabaseType postgresql
    cacheProvider hazelcast
    buildTool gradle
    clientFramework react
  }
  entities *
}

application {
  config {
    baseName product
    applicationType microservice
    packageName com.okta.developer.product
    serviceDiscoveryType no
    authenticationType jwt
    prodDatabaseType postgresql
    cacheProvider hazelcast
    buildTool gradle
    serverPort 8081
  }
  entities Product, ProductCategory, ProductOrder, OrderItem
}

application {
  config {
    baseName invoice
    applicationType microservice
    packageName com.okta.developer.invoice
    serviceDiscoveryType no
    authenticationType jwt
    prodDatabaseType postgresql
    buildTool gradle
    serverPort 8082
  }
  entities Invoice, Shipment
}

application {
  config {
    baseName notification
    applicationType microservice
    packageName com.okta.developer.notification
    serviceDiscoveryType no
    authenticationType jwt
    databaseType mongodb
    cacheProvider no
    enableHibernateCache false
    buildTool gradle
    serverPort 8083
  }
  entities Notification
}

Each application defines its name, package name, authentication type, database, etc. For all supported options and configurations, please refer to the JDL applications documentation. Each application also defines the applicationType and the entities it serves. Next, add the entity definitions to the app.jdl you just created.

/**
 * Entities for Store Gateway
 */
// Customer for the store
entity Customer {
  firstName String required
  lastName String required
  gender Gender required
  email String required pattern(/^[^@\s]+@[^@\s]+\.[^@\s]+$/)
  phone String required
  addressLine1 String required
  addressLine2 String
  city String required
  country String required
}

enum Gender {
  MALE, FEMALE, OTHER
}

relationship OneToOne {
  Customer{user(login) required} to User
}

service Customer with serviceClass
paginate Customer with pagination

/**
 * Entities for product microservice
 */
// Product sold by the Online store
entity Product {
  name String required
  description String
  price BigDecimal required min(0)
  itemSize Size required
  image ImageBlob
}

enum Size {
  S, M, L, XL, XXL
}

entity ProductCategory {
  name String required
  description String
}

entity ProductOrder {
  placedDate Instant required
  status OrderStatus required
  code String required
  invoiceId Long
  customer String required
}

enum OrderStatus {
  COMPLETED, PENDING, CANCELLED
}

entity OrderItem {
  quantity Integer required min(0)
  totalPrice BigDecimal required min(0)
  status OrderItemStatus required
}

enum OrderItemStatus {
  AVAILABLE, OUT_OF_STOCK, BACK_ORDER
}

relationship ManyToOne {
  OrderItem{product(name) required} to Product
}

relationship OneToMany {
  ProductOrder{orderItem} to OrderItem{order(code) required}
  ProductCategory{product} to Product{productCategory(name)}
}

service Product, ProductCategory, ProductOrder, OrderItem with serviceClass
paginate Product, ProductOrder, OrderItem with pagination
microservice Product, ProductOrder, ProductCategory, OrderItem with product

/**
 * Entities for Invoice microservice
 */
// Invoice for sales
entity Invoice {
  code String required
  date Instant required
  details String
  status InvoiceStatus required
  paymentMethod PaymentMethod required
  paymentDate Instant required
  paymentAmount BigDecimal required
}

enum InvoiceStatus {
  PAID, ISSUED, CANCELLED
}

entity Shipment {
  trackingCode String
  date Instant required
  details String
}

enum PaymentMethod {
  CREDIT_CARD, CASH_ON_DELIVERY, PAYPAL
}

relationship OneToMany {
  Invoice{shipment} to Shipment{invoice(code) required}
}

service Invoice, Shipment with serviceClass
paginate Invoice, Shipment with pagination
microservice Invoice, Shipment with invoice

/**
 * Entities for notification microservice
 */
entity Notification {
  date Instant required
  details String
  sentDate Instant required
  format NotificationType required
  userId Long required
  productId Long required
}

enum NotificationType {
  EMAIL, SMS, PARCEL
}

microservice Notification with notification

We define entities for each service and mark the entities as microservice entities. We also define relationships between entities, enums, and other options like pagination, service layer, etc. Please refer to JDL Entities and relationships documentation for more possibilities.

Now, we are ready to run JHipster. Open a terminal window on the folder where you saved the JDL and run the following command.

mkdir jhipster-istio
cd jhipster-istio

jhipster jdl app.jdl --fork

This will create the applications with all their entities and specified configurations. You should be able to see the gateway application in action by running the following command on the store folder.

./gradlew # starts the Spring Boot application

You can see everything that's generated in the example application on GitHub.

Create a GKE cluster and install Istio

To deploy the stack to Google Kubernetes Engine, we need to create a cluster and install Istio. So let's begin by creating a cluster using Google Cloud SDK.

Create a cluster

Ensure you are logged into the gcloud CLI from the command-line and run the following command to create a GKE cluster.

# set region and zone
gcloud config set compute/region europe-west1
gcloud config set compute/zone europe-west1-b
# Create a project and enable container APIs
gcloud projects create jhipster-demo-okta # You need to also enable billing via GUI
gcloud config set project jhipster-demo-okta
gcloud services enable container.googleapis.com

# Create GKE Cluster
gcloud container clusters create hello-hipster \
   --num-nodes 4 \
   --machine-type n1-standard-2

This could take anywhere from 5 to 15 minutes. --machine-type is important as we need more CPU than available in the default setup. Once the cluster is created, it should be set automatically as the current Kubernetes context. You can verify that by running kubectl config current-context. If the new cluster is not set as the current context, you can set it by running gcloud container clusters get-credentials hello-hipster.

Note: I'm using KDash to monitor the cluster; you can try it or use kubectl, k9s, and so on as you prefer.

Install Istio to cluster

As of writing this, I'm using Istio version 1.13.4. You can install istioctl by running the following command, preferably from your home directory.

export ISTIO_VERSION=1.13.4
curl -L https://istio.io/downloadIstio | sh -
cd istio-$ISTIO_VERSION
export PATH=$PWD/bin:$PATH

You should now be able to run istioctl from the command line. Now, we can use the CLI to Install Istio to the GKE cluster. Istio provides a few Helm profiles out of the box. We will use the demo profile for demo purposes. You can choose the production or dev profile as well. The command should install Istio and set up everything required on our cluster.

istioctl install --set profile=demo -y

Note: If you run into any trouble with firewall or user privilege issues, please refer to GKE setup guide from Istio.

Once the installation is complete, we need to fetch the External IP of the Istio Ingress Gateway. If you are using KDash, you can see it on the services tab, or you can run the following command to get it using kubectl.

kubectl get svc istio-ingressgateway -n istio-system

Install observability tools

Istio also provides addons for most of the popular monitoring and observability tools. Let's install Grafana, Prometheus, Kiali and Zipkin on our cluster. These are preconfigured to work with the telemetry data provided by Istio. Ensure you are in the folder where you installed Istio, like istio-1.13.4.

cd istio-$ISTIO_VERSION
kubectl apply -f samples/addons/grafana.yaml
kubectl apply -f samples/addons/prometheus.yaml
kubectl apply -f samples/addons/kiali.yaml
kubectl apply -f samples/addons/extras/zipkin.yaml

If we look at the istio-system namespace, we can see all the Istio components along with Grafana, Prometheus, Kiali, and Zipkin running. You can also see this by running the following command .

kubectl get pods -n istio-system

Deploy the microservice stack to GKE

Our cluster is ready, and we have Istio installed. Now, we can deploy our microservice stack to the cluster. First, we need to create Kubernetes manifests for our deployments and services and configurations for Istio. And once again, JHipster comes to the rescue. We can use the JDL deployment configurations to generate Kubernetes setup for our stack with one command easily.

Create Kubernetes manifests

Create a new JDL file, say deployment.jdl, and add the following content.

// will be created under 'kubernetes' folder
deployment {
  deploymentType kubernetes
  appsFolders [store, invoice, notification, product]
  dockerRepositoryName "<your-docker-repository-name>"
  serviceDiscoveryType no
  istio true
  kubernetesServiceType Ingress
  kubernetesNamespace jhipster
  ingressDomain "<istio-ingress-gateway-external-ip>.nip.io"
  ingressType gke
}

I hope it's self-explanatory. You can refer to the JDL deployment documentation for all the available options. We have enabled Istio and set the ingress domain to the Istio Ingress Gateway's external IP that we noted earlier. Now we need a DNS for our IP. For real use-cases, you should map a DNS for the IP using a service provided by your cloud vendor like Google Cloud DNS, but for testing and demo purposes, we can use a wildcard DNS service like nip.io to resolve our IP. Just append nip.io to our IP and use that as the ingressDomain. Make sure to use a docker repo where you have push rights.

Now run the following command from the root folder where you ran the previous jhipster jdl command.

jhipster jdl deployment.jdl

This will create a new folder, kubernetes, with all the required Kubernetes manifests like deployments, services, Istio virtual services, gateways, and so on, for all the applications, databases, and monitoring.

Each of the services will also have an Istio virtual service and destination rule. For example, the invoice service will have the following destination rule defining traffic policies.

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: invoice-destinationrule
  namespace: jhipster
spec:
  host: invoice
  trafficPolicy:
    loadBalancer:
      simple: RANDOM
    connectionPool:
      tcp:
        maxConnections: 30
        connectTimeout: 100ms
      http:
        http1MaxPendingRequests: 10
        http2MaxRequests: 100
        maxRequestsPerConnection: 10
        maxRetries: 5
    outlierDetection:
      consecutive5xxErrors: 5
      interval: 30s
      baseEjectionTime: 60s
  subsets:
    - name: v1
      labels:
        version: "v1"

It also includes the following virtual service that defines the route. You could also use virtual services to do traffic split between two versions of the same app, among other things.

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: invoice-virtualservice
  namespace: jhipster
spec:
  hosts:
    - invoice
  http:
    - route:
        - destination:
            host: invoice
            subset: "v1"
          weight: 100
      retries:
        attempts: 3
        perTryTimeout: 2s

The gateway is defined for the store application as it is our GUI as well.

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: store-gateway
  namespace: jhipster
  labels:
    gateway: store-gateway
    istio: ingressgateway
spec:
  selector:
    istio: ingressgateway
  servers:
    - port:
        number: 80
        name: http
        protocol: HTTP
      hosts:
        - store.jhipster.34.76.233.160.nip.io
    - port:
        number: 80
        name: http2
        protocol: HTTP2
      hosts:
        - store.jhipster.34.76.233.160.nip.io
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: store-gw-virtualservice
  namespace: jhipster
  labels:
    service: store-gw-virtualservice
spec:
  hosts:
    - store.jhipster.34.76.233.160.nip.io
  gateways:
    - store-gateway
  http:
    - match:
        - uri:
            prefix: /services/invoice/
      rewrite:
        uri: /
      route:
        - destination:
            host: invoice
    - match:
        - uri:
            prefix: /services/notification/
      rewrite:
        uri: /
      route:
        - destination:
            host: notification
    - match:
        - uri:
            prefix: /services/product/
      rewrite:
        uri: /
      route:
        - destination:
            host: product
    - route:
        - destination:
            host: store

As you can see, there are also many useful commands printed on the console that you can use to do the deployment.

Deploy to GKE

We are ready to deploy now. First, we need to build and push the images to the registry. We can use the handy Jib commands provided by JHipster. Navigate to each of the microservice folders and run the commands below.

cd store && ./gradlew bootJar -Pprod jib -Djib.to.image=yourDockerRepository/store
cd invoice && ./gradlew bootJar -Pprod jib -Djib.to.image=yourDockerRepository/invoice
cd notification && ./gradlew bootJar -Pprod jib -Djib.to.image=yourDockerRepository/notification
cd product && ./gradlew bootJar -Pprod jib -Djib.to.image=yourDockerRepository/product

Once the images are pushed to the Docker registry, we can deploy the stack using the handy script provided by JHipster. Navigate to the kubernetes folder created by JHipster and run the following command.

cd kubernetes
./kubectl-apply.sh -f

Once the deployments are done, we must wait for the pods to be in RUNNING status. Useful links will be printed on the terminal; make a note of them.

You can now access the application at the given http://store.jhipster.<istio-ingress-gateway-external-ip>.nip.io URI and log in with the default credentials.

Note: Currently, the JHipster OIDC setup does not work with Istio and there is an open issue in JHipster issue tracker for this. Alternative solutions would be to use an external authorization server with something like Open Policy Agent. We will cover this in a later blog post.

Monitoring and observability

Since we deployed tools for observability, let's see what we have.

Grafana

First up are Grafana and Prometheus for metrics and dashboards. Click the URI for Grafana from the previous deployment step. Click General at the top left corner and click the istio folder. You should see multiple preconfigured dashboards. You can monitor the performance of the workloads and the istio system itself here. You can also create your own dashboards if you like. Prometheus provides the data visualized on Grafana.

Kiali

Kiali is a management console for Istio service mesh, and it provides a web interface for visualizing the network topology of your service mesh. You can use it to explore the network topology of your cluster and see the network traffic flowing through it. Click Graph on the left side menu to see the network topology.

Zipkin

Zipkin is a distributed tracing solution for distributed systems. It is a tool for capturing distributed traces and providing a centralized view of the traces. This is essential for a microservice setup where a request could span multiple services, and debugging would require tracing them. Click RUN QUERY on the home screen to fetch recent traces, and click SHOW on one of them.

Cleanup the GCP cluster

Once you are done with experiments, make sure to delete the cluster you created so that you don't end up with a big bill from Google. You can delete the cluster from the Google Cloud Console GUI or via the command line using the following command.

gcloud container clusters delete hello-hipster

Learn more about Java Microservices, Istio, Kubernetes, and JHipster

If you want to learn more about Kubernetes, OIDC, or using OIDC with Kubernetes, and security in general, check out these additional resources.

You can find all the code from this example on GitHub.

Run Microservices on DigitalOcean with Kubernetes

Jimena Garbarino — Fri, 17 Jun 2022 21:50:28 +0000

Cloud adoption continues to increase rapidly worldwide, and not only in the software industry. Every year more and more companies move their applications to the cloud. In the last JHipster community survey, from December 2021, participants valued JHipster's ability to get them to production faster, and requested more tutorials on deployment to cloud platforms. DigitalOcean is among the most popular "other" cloud vendors, according to some surveys. This post is a quick walk-through of the deployment of a JHipster microservices architecture to a Kubernetes cluster in DigitalOcean's cloud.

This tutorial was created with the following frameworks and tools:

About DigitalOcean

DigitalOcean is a cloud services company founded in 2011 by brothers Ben and Moisey Uretsky. Their headquarters are in New York City in the United States, and they also have offices in Massachusetts and Bangalore. Last March 2022, DigitalOcean reached its IPO (Initial Public Offering), and some press articles describe it as the cloud services provider for small businesses: "Cloud services for the Little Guy".

DigitalOcean Kubernetes (DOKS) is a managed Kubernetes service that lets you deploy Kubernetes clusters without the complexities of handling the control pane and containerized infrastructure. Clusters are compatible with standard Kubernetes toolchains and integrate natively with DigitalOcean load balancers and block storage volumes. DOKS offers fast provisioning and deployment, and provides a free high-availability control pane, for reliability management. It can also provide a Cluster Autoscaler that automatically adjusts the size of the cluster by adding or removing nodes based on the cluster's capacity to schedule pods. Pricing for Kubernetes workloads is based on resources required by the cluster, droplets, block storage, and load balancers.

The company publishes its data center certification reports on its website, and all the data centers have approved two or more of the following certifications: SOC (System and Organization Controls) 1 Type II, SOC 2 Type II, SOC 3 Type II, and ISO/IEC 27001:2013 (Security techniques - Information security management systems). PCI-DSS (Payment Card Industry - Data Security Standard) has been certified in all data centers.

Set up a microservices architecture for Kubernetes

Before working on the application, you need to install JHipster. The classical way of working with JHipster is to do a local installation with NPM.

npm install -g generator-jhipster@7

If you'd rather use Yarn or Docker, follow the instructions at jhipster.tech.

For this test, start from the reactive-jhipster example in the java-microservices-examples repository on GitHub. The example is a JHipster reactive microservices architecture with Spring Cloud Gateway and Spring WebFlux, Vue as the client framework, and Gradle as the build tool. You can read about how it was built in Reactive Java Microservices with Spring Boot and JHipster.

git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/reactive-jhipster

If you inspect the project folder, you will find sub-folders for the gateway service, which will act as the front-end application, and a gateway to the store and blog microservices, which also have their subfolders. A docker-compose sub-folder contains the service definitions for running the application containers.

The next step is to generate the Kubernetes deployment descriptors. In the project root folder, create a kubernetes directory and run the k8s JHipster sub-generator:

mkdir kubernetes
cd kubernetes
jhipster k8s

Choose the following options when prompted:

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)

NOTE: You can leave the Docker repository name blank for running Kubernetes locally, but a repository will be required for the cloud deployment, so go ahead and create a DockerHub personal account, and the image pull configuration will be ready for both local and cloud deployments.

Build the gateway, store, and blog services container images with Jib. As Jib will push the images to DockerHub, you first need to do a docker login.

docker login

If you have two-factor authentication enabled, you must generate a token and use it as the password for the login. In the Docker web, go to the user menu and choose Account Settings. Then in the left menu choose Security and New Access Token.

For example, for building the gateway service image:

cd ../gateway
./gradlew bootJar -Pprod jib -Djib.to.image=<docker-repo-name>/gateway

IMPORTANT NOTE: Unfortunately the application example does not build with Java 17 at the moment of writing this post. As specified in the introduction, this example was built with Java 11.

Check that the images were uploaded to DockerHub, and navigate to the project root folder in the terminal for the next step.

Configure authentication with OpenID Connect

One more configuration step before running the architecture locally, let's configure Okta for authentication.

What does the Okta CLI do?

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:
- login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
- logout: http://localhost:8080 and http://localhost:8761
Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

You will see output like the following when it’s finished:

Okta application configuration has been written to: /path/to/app/.okta.env

Run cat .okta.env (or type .okta.env on Windows) to see the issuer and credentials for your app. It will look like this (except the placeholder values will be populated):

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="https://{yourOktaDomain}/oauth2/default"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="{clientId}"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="{clientSecret}"

NOTE: You can also use the Okta Admin Console to create your app. See Create a JHipster App on Okta for more information.

Add the settings from the generated .okta.env to kubernetes/registry-k8s/application-configmap.yml:

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>

Enable the OIDC authentication in the jhipster-registry service by adding the oauth2 profile in the kubernetes/registry-k8s/jhipster-registry.yml file:

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

Run locally with minikube

Install minikube and kubectl.

For minikube, you will need at least 2 CPUs. Start minikube with your number of CPUs:

cd kubernetes
minikube --cpus <ncpu> start

minikube will log the Kubernetes and Docker versions on start:

Preparing Kubernetes v1.23.3 on Docker 20.10.12 ...

For the store-mongodb deployment to work, the property Service.spec.publishNotReadyAddresses was required, instead of the annotation service.alpha.kubernetes.io/tolerate-unready-endpoints, as the latter was deprecated in Kubernetes release 1.11.

Edit kubernetes/store-k8s/store-mongodb.yml and add the publishNotReadyAddresses: true property to the spec key near the bottom of the file:

...
# Headless service for DNS record
apiVersion: v1
kind: Service
metadata:
  name: store-mongodb
  namespace: demo
spec:
  type: ClusterIP
  clusterIP: None
  publishNotReadyAddresses: true
  ports:
    - name: peer
      port: 27017
  selector:
    app: store-mongodb

Then deploy the application to minikube. In the kubernetes directory, run:

./kubectl-apply.sh -f

Now is a good time to install k9s, a terminal-based UI to interact with Kubernetes clusters. Then run k9s with:

k9s -n demo

Check out the commands list, some useful ones are:

:namespace: show all available namespaces
:pods: show all available pods

You can navigate the pods with ENTER and go back with ESC keys.

Set up port-forwarding for the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 8761

Navigate to http://localhost:8761 and sign in with your Okta credentials. When the registry shows all services in green, Set up port-forwarding for the gateway as well.

kubectl port-forward svc/gateway -n demo 8080

Navigate to http://localhost:8080, sign in, and create some entities to verify everything is working fine.

After looking around, stop minikube before the cloud deployment:

minikube stop

Also delete the minikube cluster to have a clean slate for future tests:

minikube delete

Deploy to DigitalOcean Kubernetes

Now that the architecture works locally, let's proceed to the cloud deployment. First, create a DigitalOcean account. The registration requires a $5 PayPal payment, or providing a credit card.

Most of the cluster tasks, if not all, can be accomplished using doctl, the command-line interface (CLI) for the DigitalOcean API. Install the tool, and perform the authentication with DigitalOcean:

doctl auth init

You will be prompted to enter the DigitalOcean access token that you can generate in the DigitalOcean control panel. Sign in, and then in the left menu go to API, click Generate New Token. Enter a token name, and click Generate Token. Copy the new token from the Tokens/Keys table.

You can find a detailed list of pricing for cluster resources at DigitalOcean, and with doctl you can quickly retrieve a list of node size options available for your account:

doctl k options sizes

Create the cluster with the following command line:

doctl k cluster create do1 -v --size s-4vcpu-8gb-intel

After creating a cluster, doctl adds a configuration context to kubectl and makes it active, so you can start monitoring your cluster right away with k9s. First, apply the resources configuration to the DigitalOcean cluster:

./kubectl-apply.sh -f

Monitor the deployment with k9s:

k9s -n demo

Once you see the jhipster-registry pods are up, set up port forwarding again so you can also monitor the status of the services in the registry UI.

Notes on DigitalOcean's node sizes and volumes

Deploying to a Kubernetes cluster on DigitalOcean's cloud can be tricky if you don't specify enough capacity from the start.

At first, I tested the cluster with the highest size Intel nodes available for my account, s-2vcpu-4gb-intel. I attempted to run the application in the default cluster configuration, a three-node cluster with a single node pool in the nyc1 region, using the latest Kubernetes version. As I started to see pods not running due to insufficient CPU, I increased the number of nodes and got everything working. DigitalOcean's latest and default Kubernetes version at the moment of writing this post was 1.22.8.

If you need to find out the reason why a pod is not running, you can get the pod events with kubectl describe, for example, for the jhipster-registry-0 pod:

kubectl describe pod jhipster-registry-0 -n demo

The output of the command, in the events section, for a pod that has failed due to insufficient cpu, looks like the following:

Events:
  Type     Reason                  Age                   From                     Message
  ----     ------                  ----                  ----                     -------
  Normal   NotTriggerScaleUp       4m30s                 cluster-autoscaler       pod didn't trigger scale-up:
  Warning  FailedScheduling        69s (x3 over 95s)     default-scheduler        0/3 nodes are available: 3 Insufficient cpu.

If you see a pod failing in k9s, check the events for that pod with kubectl describe pod as in the example above.

To add CPU, increase the number of nodes with doctl:

doctl k cluster node-pool update do1 do1-default-pool --count 4

You don't need to restart pods when adding nodes.

After I increased CPU (adding one more node to the cluster), some of the pods, in the store-mongodb stateful set with 3 replicas, did not run due to unbound immediate PersistentVolumeClaims. This was reported in the pod events, in the output of kubectl describe pod, for the failing pods. I then inspected persistent volume claims with the following commands:

kubectl get pvc -n demo
kubectl describe pvc datadir-store-mongodb-2 -n demo

The kubectl describe pvc command output was showing provisioning errors, and instructed to contact support:

Events:
  Type     Reason                Age                  From                                                                       Message
  ----     ------                ----                 ----                                                                       -------
  Normal   Provisioning          3m6s (x10 over 11m)  dobs.csi.digitalocean.com_master-do3_cebb3451-5eba-4805-956c-753ec148e2ea  External provisioner is provisioning volume for claim "demo/datadir-store-mongodb-2"
  Warning  ProvisioningFailed    3m5s (x10 over 11m)  dobs.csi.digitalocean.com_master-do3_cebb3451-5eba-4805-956c-753ec148e2ea  failed to provision volume with StorageClass "do-block-storage": rpc error: code = ResourceExhausted desc = volume limit (10) has been reached. Current number of volumes: 10. Please contact support.
  Normal   ExternalProvisioning  103s (x43 over 11m)  persistentvolume-controller                                                waiting for a volume to be created, either by external provisioner "dobs.csi.digitalocean.com" or manually created by system administrator

As instructed by the event message, I contacted DigitalOcean support and they fixed it.

Finally, as I first registered for the free trial account, I had to open a second support ticket requesting higher node sizes, so I could use the size s-4vcpu-8gb-intel. Not all the size options were available after signing up for the trial, but that is not the case for a standard account. Billing should be under $10 USD for a short Kubernetes service test.

Find your gateway's external IP and update redirect URIs

Once all the pods are running, find the gateway external IP with the kubectl describe command:

kubectl describe service gateway -n demo

The output will look like this:

Name:                     gateway
Namespace:                demo
Labels:                   app=gateway
Annotations:              kubernetes.digitalocean.com/load-balancer-id: e81d2b8c-6c28-430d-8ba8-6dab29a1ba76
                          service.beta.kubernetes.io/do-loadbalancer-certificate-id: bd0b1d03-0f90-449d-abbe-ac6a4026c133
Selector:                 app=gateway
Type:                     LoadBalancer
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.245.47.51
IPs:                      10.245.47.51
LoadBalancer Ingress:     157.230.200.181
Port:                     http  8080/TCP
TargetPort:               8080/TCP
NodePort:                 http  31048/TCP
Endpoints:                10.244.1.42:8080
Session Affinity:         None
External Traffic Policy:  Cluster

Sign-in redirect URIs: http://<load-balancer-ingress-ip>:8080/login/oauth2/code/oidc
Sign-out redirect URIs: http://<load-balancer-ingress-ip>:8080

Navigate to http://<load-balancer-ingress-ip>:8080 and rejoice when everything works!

Secure web traffic with HTTPS

Since the gateway service acts as the application front-end, in the k8s descriptors it is defined as a LoadBalancer service type. This exposes the service externally using the cloud provider's load balancer. DigitalOcean load balancers are a fully-managed, highly available network load-balancing service. Load balancers distribute traffic to groups of droplets, which decouples the overall health of a backend service from the health of a single server to ensure that your services stay online.

The standard practice is to secure web traffic to your application with HTTPS. For traffic encryption, you need a TLS (SSL) certificate. DigitalOcean also provides automatic certificate creation and renewal if you manage your domain with DigitalOcean's DNS, which is free. But domain registration is not provided. To use DigitalOcean's DNS, you need to register a domain name with a registrar and update your domain's NS records to point to DigitalOcean's name servers.

Then, for using DigitalOcean's managed domain and certificate, you must delegate the domain, updating NS records in the registrar. Because of this requirement, you cannot use free DNS services where you cannot set up NS records, like nip.io.

IMPORTANT NOTE: Before changing the registrar NS records (the nameservers), add your domain to DigitalOcean, to minimize service disruptions.

You can create the certificate and the domain at the same time in the DigitalOcean control panel, when you set up the load balancer HTTPS forwarding.

DigitalOcean load balancers support two main configurations for encrypted web traffic:

SSL termination: decrypts SSL requests at the load balancer and sends them unencrypted to the backend at the Droplets' private IP address. The slower and CPU-intensive work of decryption is performed at the load balancer, and certificate management is simplified. The traffic between the load balancer and the backend is secured by routing over the VPC network, but data is readable inside the private network.
SSL passthrough: sends the encrypted SSL requests directly to the backend at the Droplets' private IP address, traffic between the load balancer and the backend is secured. Every backend server must have the certificate, and client information contained in X-forwarded-* headers might be lost.

Taking advantage of the simplified certificate management, SSL termination will be configured in the following steps through the DigitalOcean control panel.

Log in to your DigitalOcean account, and in the left menu choose Kubernetes. Then choose your cluster, and on the cluster page, choose Resources. In the LOAD BALANCERS list, choose the single load balancer that must have been created. On the load balancer page, choose the Settings tab. Click Edit in the Forwarding Rules. Add a forwarding rule for HTTPS in port 443, and in the certificate drop-down, choose New certificate.

In the New Certificate form, choose the Use Let's Encrypt tab, and then in the domain box, choose Add new domain. Then enter your domain name, and list other subdomains to include. Add a name for the certificate and click Generate Certificate.

Back in the Forwarding rules page, check that the generated certificate is selected, and forward the traffic to the droplet HTTP port where the gateway is running. Tick the checkbox Create DNS records for all the new Let's Encrypt certificates and then Save the forwarding settings.

Finally, in the SSL section of the settings, tick the checkbox Redirect HTTP to HTTPS.

Once again, update the redirect URIs in Okta to allow the newly configured domain. Add the following redirect URIs:

Sign-in redirect URIs: https://<your-domain>/login/oauth2/code/oidc
Sign-out redirect URIs: https://<your-domain>

Test the configuration by navigating to http://<your-domain>. First, the load balancer should redirect to HTTPs, and then the gateway should redirect to the Okta sign-in page.

Inspect and manage cluster resources

You can retrieve the cluster associated resources with the following doctl command:

doctl k cluster list-associated-resources do1

The output will list the volumes and load balancers created for the cluster, which generate billing charges besides the cost of the nodes:

Volumes                                                                                                                                                                                       Volume Snapshots    Load Balancers
[a33dbaba-cb22-11ec-9383-0a58ac145375 a6e18809-cb22-11ec-8723-0a58ac14468c 65fb3778-cb23-11ec-9383-0a58ac145375 ac106c49-cb22-11ec-9383-0a58ac145375 c7122288-cb22-11ec-bd08-0a58ac14467d]    []                  [8ebbcbf2-1e67-46f5-b38a-eddae17f00f3]

Unfortunately, there is no way to pause the cluster. According to DigitalOcean, you can power a droplet off, but this does not halt the billing. Billing costs can be reduced by taking a snapshot of the droplet and then destroying it. The snapshot cost is less expensive.

While testing the platform, you can delete the cluster in between sessions, to avoid spending the trial credit while not actively working on it.

doctl k cluster delete do1

Volumes provisioned to the cluster are not deleted with the cluster, and charges are generated hourly. You can delete volumes using the control panel or with the following commands:

doctl compute volume list
doctl compute volume delete <volume-id>

The load balancers are not deleted with the cluster either:

doctl compute load-balancer list
doctl compute load-balancer delete <load-balancer-id>

During registration, a project must have been created, allowing you to organize resources. You can list all the resources associated with a project with the following command:

doctl projects list
doctl projects resources list <project-id>

Learn more about JHipster and Kubernetes

This has been a brief walkthrough for deploying JHipster to a DigitalOcean's managed Kubernetes cluster. Some important topics for production deployment were not covered in this post, to focus in particular on DigitalOcean resource requirements. Some key topics we did not cover in this post include external configuration storage with Spring Cloud Config and Git as well as secrets encryption both for the cloud configuration and Kubernetes configuration. You can learn about these good practices in the first post of this cloud deployment series: Kubernetes to the Cloud with Spring Boot and JHipster.

Keep learning, and for more content on JHipster, check out the following links:

Be sure to follow us on Twitter and subscribe to our YouTube Channel so that you never miss any of our excellent content!

Create Kubernetes Microservices on Azure with Cosmos DB

Andrew Hughes — Fri, 17 Jun 2022 03:45:43 +0000

In this tutorial, you'll learn how to deploy a JHipster-based reactive microservice to Azure Kubernetes Service (AKS). You'll use Azure's Cosmos DB as a persistent store for one of the services. For security, you'll use Okta as an OAuth 2.0 and OpenID Connect (OIDC) provider. You'll also securely encrypt all secrets in the project configuration files using Kubernetes secrets and kubeseal. This tutorial focuses on deploying an already generated project to Azure AKS. It does not go into great detail about generating the project. To see how the project was generated using JHipster, take a look at Reactive Java Microservices with Spring Boot and JHipster.

The project has a few different pieces:

JHipster Registry: a Eureka server for service discovery and a Spring Cloud Config server for centralized configuration management
Gateway: public Spring Cloud Gateway application using Vue
Store: Spring Boot microservice using Azure's Cosmo DB API for MongoDB
Blog: Spring Boot microservice using a Neo4J database

This tutorial has a lot of different technologies in it. I've tried to make it as simple and as explicit as possible, but it's probably helpful to have some basic knowledge of Docker and Kubernetes before you start.

If you're already familiar with all the tech in this tutorial, you can skip ahead to the prerequisites section. If not, I'm going to explain them a little before we move on.

JHipster microservices architecture overview

JHipster is a development platform that streamlines the generation, development, and deployment of both monolithic and microservice applications. It supports a dizzying array of frontend (Angular, React, and Vue) and backend (Spring Boot, Micronaut, Quarkus, Node.js, and .NET) technologies. It's designed to be deployed using Docker and Kubernetes, and can easily deploy to all the major cloud platforms, such as AWS, Azure, Heroku, Cloud Foundry, Google Cloud Platform, and OpenShift.

The project in this tutorial uses Spring Boot with Java resource servers and a Vue frontend. It was built with the JHipster generator that quickly scaffolds a new application based on either an interactive shell or a DSL file. You can read more about generating microservices with JHipster in their docs. One of the slick features of the JHipster generator is that you can generate data entities along with applications.

The JHipster Registry that is generated with the microservice includes two important functions: a Eureka server and a Spring Cloud Config server. The Eureka server allows the microservices to dynamically find each other without having to use hard-coded URIs. This means that the microservice can scale and services can be replaced without causing problems. It's a bit like a phonebook or a DNS service for the microservice. The Spring Cloud Config server allows project configuration to be centralized and distributed to all of the different services. In this tutorial you'll use this feature to configure all of the services for Okta OAuth in one place.

The JHipster API Gateway is the public face of your microservice. All public traffic comes through this service, which also includes the Vue frontend. The gateway is one of three application types that can be created by the JHipster generator DSL. The other two are monolith and microservice. A monolith is a non-microservice application with a single service.

The store service and blog service are both examples of the microservice application type. This means that each service is a Spring Boot resources server with some type of SQL or NoSQL backend.

The generator creates four applications. They are designed to be built and run as docker containers, which makes it easy for them to be packaged in Kubernetes pods. Kubernetes is a container orchestrator specifically designed for managing microservice networks. It's something like Docker Compose but designed for microservices with a lot of great features like service discovery, load balancing, automatic rollouts and restarts, resource management, and storage mounting.

Prerequisites

This tutorial has a lot of pieces. Install the required software below and sign up for an Azure Cloud account. You'll need a free Okta account, but you can use the Okta CLI to sign up for it later in the tutorial.

Docker: you'll need to have both Docker Engine and Docker Compose installed (If you install the Docker desktop, this will automatically install both. On Linux, if you install Docker Engine individually, you will have to also install Docker Compose) separately.
Docker Hub: you'll need a Docker Hub to host the docker images so that Azure can pull them.
Java 11: this tutorial requires Java 11. If you need to manage multiple Java versions, SDKMAN! is a good solution. Check out their docs to install it.
Okta CLI: you'll use Okta to add security to the microservice network. You can register for a free account from the CLI.
Azure Cloud account: they offer a free-tier account with a $200 credit to start.
Azure CLI: you'll use the Azure CLI to manage the Kubernetes cluster.
kubectl: CLI to manage Kubernetes clusters.

If you have never had an Azure account before, you can create a new one that will allow free-tier access and has $200 credit allocated to it. This is more than enough to finish this tutorial. However, the credit does expire after 30 days. If you do not have credit left or your credit has expired, this tutorial should only cost a few dollars if you stop and start the AKS cluster when you are not working on it. You can keep an eye on your costs using the cost explorer in the Azure portal and set alerts if you are concerned about it. Upgrading to pay-as-you-go may also alleviate some resource throttling issues around testing the AKS clusters.

Spring Boot microservices for Azure and Cosmos DB

This project is based on two of Matt Raible's tutorials: Reactive Java Microservices with Spring Boot and JHipster and Kubernetes to the Cloud with Spring Boot and JHipster. In these tutorials, he builds a reactive Java microservice architecture and shows how to deploy it to Google Cloud (GCP). I have modified the project to work with Azure and Cosmos DB.

You will first run the project using Docker Compose. Once you have this working, you will run the project as a Kubernetes cluster on Azure. My modifications were relatively minor and involved removing the unnecessary MongoDB instances (from both the docker-compose.yml file and from the Kubernetes descriptors) as well as updating environment values to point the store service to the Cosmos DB instance instead of a MongoDB instance.

Listed briefly, the changes I made from Matt Raible's posts to make this work with Azure and Cosmos DB are as follows. You can skip this list (and the next section) and go right to cloning the Git repository if you want, but since this documents how to update a JHipster-generated project to use Cosmos DB, I thought it was worth including.

In the docker-compose/docker-compose.yml file:

removed the MongoDB service
updated the store service property SPRING_DATA_MONGODB_URI to point to the Cosmos DB instance via a .env file
removed the Keycloak service and the environment variables that configured auth to use Keycloak from the remaining services (not strictly necessary but cleaned things up)

In the k8s/store-k8s directory:

removed the store-mongodb.yml file (This creates the MongoDB Kubernetes service that our project does not need.)
in store-deployment.yml:
- removed the initContainers (The init container waits for the MongoDB instance, which is removed.)
- updated SPRING_DATA_MONGODB_URI env value of the store-app container to the Cosmos DB URI (This points the store to the Cosmos DB instance.)
- properly secured the Cosmos DB connection string using Kubernetes secrets and kubeseal

Setting the store app's initial status for Eureka

Creating this tutorial, I ran into a problem with the store app getting stuck as OUT_OF_SERVICE. When I inspected the logs, I found that the service started as UP, quickly went to DOWN, and then OUT_OF_SERVICE. Later, it would go back to UP but the Eureka server never registered this change.

There's an open issue documenting this problem on Spring Cloud Netflix and Netflix Eureka.

A temporary fix taken from the issue on GitHub is to override the health reporting implementation so that it returns DOWN instead of OUT_OF_SERVICE while the program is still starting. This blocks it from ever reporting OUT_OF_SERVICE. You can see the fix in the EurekaFix.java file in the store app.

Clone the microservices project from GitHub

Clone the modified JHipster reactive microservice project from GitHub and checkout the start tag.

git clone https://github.com/oktadev/okta-azure-kubernetes-cosmosdb-example.git \
  azure-k8s-cosmosdb
cd azure-k8s-cosmosdb
git fetch --all --tags
git checkout tags/start -b working

Create the Azure Cosmos DB with API for MongoDB

You need to create an Azure Cosmos DB instance. You can either use the Azure Portal or the CLI to create a new Cosmos DB instance. Make sure you create a one that is Azure Cosmos DB API for MongoDB (Cosmos DB supports various database types). If you use the portal, it's pretty self-explanatory but don't forget to enable the free tier and enable a public network.

Here are the instructions for using the CLI.

Log into the Azure CLI using a Bash shell. This will redirect you to a browser to log into the Azure portal.

az login

This should show you the subscriptions for your account.

[
  {
    "cloudName": "AzureCloud",
    "homeTenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "id": "90eb9f51-b4be-4a9f-a69f-11b7668a874d",
    "isDefault": true,
    "managedByTenants": [],
    "name": "Azure subscription 1",
    "state": "Enabled",
    "tenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "user": {
      "name": "andrewcarterhughes@outlook.com",
      "type": "user"
    }
  }
]

Set the subscription in the shell. Your subscription is probably Azure subscription 1, as that is the default. Make sure you use the subscription that was created when you registered for a free account (or whatever subscription you want if you already have an account).

az account set --subscription <you-subscription-name>

Open a Bash shell. Create a resource group with the following command.

az group create --name australia-east --location australiaeast

Create the Cosmos DB account in the resource group. Substitute your Azure subscription name in the command below (it's probably Azure subscription 1, which is what mine defaulted to).

az cosmosdb create --name jhipster-cosmosdb --resource-group australia-east \
  --kind MongoDB --subscription <you-subscription-name> --enable-free-tier true \
  --enable-public-network true

Once that command returns (it may take a few minutes), it should list a lot of JSON showing properties of the created Cosmos DB account.

If you get an error that says:

(BadRequest) DNS record for cosmosdb under zone Document is already taken.

Then you need to change the --name parameter to something else. Since this is used to generate the public URI for the database it needs to be unique across Azure. Try adding your name or a few random numbers.

I'm using the Australia East location because that was the location that had free tier AKS nodes available when I wrote this tutorial. You can use any resource group you want as long as it allows you to create the AKS cluster later in the tutorial. Even if you can't use the free tier or the free credits, if you stop and start the AKS cluster between working on the tutorial, the cost should be very small (mine was less than a few dollars). The application should still work if the Cosmos DB database is in a different resource group and region since the database URI is configured to be publicly accessible.

List the connection string for the Cosmos DB API for MongoDB endpoint using the following command. If you changed the database name above, you will need to update it in the command below.

az cosmosdb keys list --type connection-strings --name jhipster-cosmosdb \
  --resource-group australia-east

This will list four connection strings. You need to save (copy and paste somewhere) the first, the primary connection string. (Ellipses have been used for brevity below.)

{
  "connectionStrings": [
    {
      "connectionString": "mongodb://jhipster-cosmosdb:XBq5KZ81V8hM63KjCOezi1arq...",
      "description": "Primary MongoDB Connection String"
    },
    ...
  ]
}

Edit the .env file in the docker-compose subdirectory. Add the following variables to it, substituting your connection string for the placeholder. Make sure the connection string is enclosed in quotes. This value is referenced by the docker-compose.yml file and passed to the store service, pointing it to the Cosmos DB MongoDB database.

The ENCRYPT_KEY will be used as the key for encrypting sensitive values stored in the Spring Cloud Config and used by the JHipster registry. You can put whatever value you want in there. A UUID works well, but any string value will work. The longer, the better.

docker-compose/.env

SPRING_DATA_MONGO_URI=<your-connection-string>
ENCRYPT_KEY=<your-encryption-key>

Configure identity with Okta

What does the Okta CLI do?

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:
- login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
- logout: http://localhost:8080 and http://localhost:8761
Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

Run cat .okta.env (or type .okta.env on Windows) to see the issuer and credentials for your app.

NOTE: You can also use the Okta Admin Console to create your app. See Create a JHipster App on Okta for more information.

Take note of the name because you will need to find the app in the Okta Admin Console and update the redirect URIs a little later. The okta apps command creates a config file named .okta.env. It will look something like the following. It helpfully lists the values you will need in the next step.

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="https://dev-13337.okta.com/oauth2/default"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="2989u928u383..."
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="09328uu098u4..."

Both the Docker Compose project and the Kubernetes project use Spring Cloud Config to centralize configuration. The JHipster registry service makes these config values available to all of the other services in the cluster.

Open docker-compose/central-server-config/application.yml and add the following to the end, filling in the issuer-uri, client-id, and client-secret taken from the .okta.env file. This is the Spring Cloud Config file for the Docker Compose project.

docker-compose/central-server-config/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>

Build the Docker images and run the app with Docker Compose

You're all set to run the app locally using Docker and Docker Compose. You need to build the docker image for each of the projects: gateway, store, and blog (you don't have to build the registry because it uses an image).

In the three different app directories, run the following Gradle command.

./gradlew -Pprod bootJar jibDockerBuild

The default Docker resource settings may not be enough to run this project. You may need to bump them. These settings worked for me.

CPUs: 8
Memory: 25 GB
Swap: 2 GB
Disk image size: 120 GB

Navigate to the docker-compose directory and run the app. You can use the -d param to run it as a daemon but for the moment I like seeing the logs. You're just running this in Docker Compose as a warm-up for the Azure deployment anyway.

docker-compose up

Give that a minute or two to finish running all the services.

Open the gateway service at http://localhost:8080.

Go to Account and Sign in. You should be directed to the Okta sign-in form.

You should be able to authenticate with your Okta credentials.

Make sure all parts of the application are working. First, test the store (which is using the Cosmos DB Mongo database) by going to Entities and Product. Make sure you can add a new product and see it in the list of products. Next, create a blog (Entities and Blog).

If that works, you can take a look at the Administration menu. There's a lot of helpful info there.

You can also check the JHipster Registry at http://localhost:8761.

Encrypt the client secret

Leaving secrets in plain text in repositories is a security risk. There are two values in this app that are sensitive: the Cosmos DB connection string that includes the username and password and the Okta OIDC app client secret. You were able to avoid exposing the database credentials by using a .env file. However, the Okta client secret is exposed as plain text in the Spring Cloud Config file (docker-compose/central-server-config/application.yml). This can be encrypted using the JHipster registry.

Open the registry (http://localhost:8761) and click on Configuration and Encryption.

Paste your client secret in the text box. Click Encrypt.

This, incidentally, is why you needed the ENCRYPT_KEY property in the .env file. That's the key that JHipster registry uses to encrypt these values (so keep it secret!).

You can now copy the encrypted value and paste it back into the application.yml file. Make sure you include the {cipher} part. It should look similar to below. Don't forget the quotes!

docker-compose/central-server-config/application.yml

...
spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://dev-123456.okta.com/oauth2/default
        registration:
          oidc:
            client-id: 0oa6ycm987987uy98
            client-secret: "{cipher}88acb434dd088acb434dd088acb434dd0..."

Stop the app if you have not already using control-c. Restart it.

docker-compose up

Make sure you can still sign into the gateway at http://localhost:8080.

You may be wondering (like I did initially), why can't I just put the client secret in the .env file? This doesn't work because the .env file is processed by Spring Cloud Config and JHipster registry after the container is composed, not by Docker Compose during the container creation, which is when the .env file is processed.

You're done with the Docker Compose implementation. To clean up, you can run the following command. This will stop and remove the containers, networks, volumes, and images created by docker-compose up.

docker-compose down --remove-orphans

Create the Azure Kubernetes cluster

The app works locally. Now it's time to deploy it to an Azure Kubernetes Cluster (AKS). The first step is to create an AKS cluster.

It's super easy to use the CLI to create a cluster. I'll show you the command below. However, there's a wrinkle. The free tier cannot create a cluster in many of the regions because of resource quotas. At least, this was the case when I was working on this tutorial. Nor is there an easy way to quickly see what regions will allow you to create a free-tier cluster. This is why I used Australia East as the region--it allowed me to create a free cluster.

If the command below does not work, I suggest going to the Azure portal and creating a Kubernetes cluster there. Select Create a service and Kubernetes Service. You'll have to select different regions and see what sizes are available (under Node size and Change size) until you find a region that will allow you to create something in the free tier. But hopefully the command will work and you won't have to worry about it.

The size I'm using for this tutorial is Standard B4ms with two nodes. I found that I needed two nodes for the cluster to start properly.

Run the following command to create the AKS cluster.

az aks create --resource-group australia-east --name jhipster-demo \
  --node-count 2 --enable-addons monitoring --generate-ssh-keys --node-vm-size standard_b4ms

This will probably take a few minutes.

As a side note, you can stop the cluster at any point. This will pause billing on the cluster.

az aks stop --resource-group australia-east --name jhipster-demo

And you can start it again.

az aks start --resource-group australia-east --name jhipster-demo

You can stop and start the cluster from the Azure portal as well.

The next step is to get the credentials for the cluster and merge them into .kube/config so that kubectl can use them. Use the following command.

az aks get-credentials --resource-group australia-east --name jhipster-demo

You should see output that ends like the following.

Merged "jhipster-demo" as current context in /home/andrewcarterhughes/.kube/config

You should be able to use kubectl to get the node on Azure.

kubectl get nodes

NAME                                STATUS   ROLES   AGE    VERSION
aks-nodepool1-21657131-vmss000000   Ready    agent   105s   v1.22.6
aks-nodepool1-21657131-vmss000001   Ready    agent   108s   v1.22.6

You can also list a lot of information about the cluster in JSON format using:

az aks list --resource-group australia-east

Configure Kubernetes for Okta and Cosmos DB

The Kubernetes files in the k8s directory were created with the JHipster Kubernetes sub-generator (see the docs for info). To see how the original project was generated, take a look at Matt Raible's JHipster and Kubernetes tutorial. As outlined above, these files were modified to work with Azure Cosmos DB instead of MongoDB in a Kubernetes pod (which is what the sub-generator assumes).

Configure Spring OAuth in the Kubernetes pod by updating k8s/registry-k8s/application-configmap.yml. You can use the same values you used above in the Docker Compose section, in docker-compose/central-server-config/application.yml.

Make sure you use the encrypted client secret enclosed in quotes with the {cipher} prefix. You're going to copy both the encryption key and the encrypted client secret from the Docker Compose configuration to avoid having to re-encrypt the client secret with a new key.

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: "{cipher}<encrypted-client-secret>"

To configure the JHipster Registry to use OIDC for authentication, you have to modify k8s/registry-k8s/jhipster-registry.yml to enable the oauth2 profile. This has already been done for you in the example app in the project Git repository.

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

Also in k8s/registry-k8s/jhipster-registry.yml, update the ENCRYPT_KEY value to use the same encryption key you used above in the Docker Compose section in the .env file.

- name: ENCRYPT_KEY
  value: <your-encryption-key>

To configure the store service to use the Cosmo database, you need to put your connection string in k8s/store-k8s/store-deployment.yml.

- name: SPRING_DATA_MONGODB_URI
  value: "<your-connection-string>"

Both the encryption key and the database connection string are sensitive values that need to be encrypted. You'll see how to do that just a little later in this tutorial.

Build Docker images and push to Docker Hub

Previously you built the docker images, but you left them in the local repository. Now you need to upload them to Docker Hub so that Azure AKS can find them. If you haven't already signed up for a Docker Hub account, please do so now.

In each of the three directories (blog, store, and gateway), run the following command. Save your Docker Hub username in a Bash variable as shown below and you can copy and paste the commands and run them in each service directory.

DOCKER_HUB_USERNAME=<docker-hub-username>
# in blog
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/blog
# in store
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/store
# in gateway
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/gateway

To briefly explain what's happening here, take a look at the blog service's Kubernetes descriptor file. It defines a container named blog-app that uses the docker image andrewcarterhughes/blog, which is my Docker Hub username and the blog image.

k8s/blog-k8s/blog-deployment.yml

containers:
  - name: blog-app
    image: andrewcarterhughes/blog

Thus in the k8s directory, each service (store, blog, gateway, and registry) defines a container and a docker image to be run in that container, along with a whole lot of configuration (which is really a lot of what JHipster is bootstrapping for you). The registry does not have a project folder because it uses a stock image that can be pulled directly from the JHipster Docker repository.

To use the images you just created with Kubernetes, do a find and replace in the k8s directory. Replace all instances of andrewcarterhughes with your Docker Hub username (<docker-hub-username>).

One nice feature of Kubernetes is the ability to define init containers. These are containers that run before the main container and can be used to create or wait for necessary resources like databases. I noticed while I was debugging things in this app that a lot of the errors happened in the init containers. It's helpful to know this because if you try and inspect the main container log nothing will be there because the container hasn't even started yet. You have to check the log for the init container that failed. The Kubernetes management tools that I mention below really come in handy for this.

Deploy your microservices to Azure AKS

You can manage a Kubernetes service purely with kubectl. However, there are some pretty helpful tools for monitoring and logging. Both k9s and Kubernetes Lens are great. I recommend installing one or both of these and using them to inspect and monitor your Kubernetes services. They are especially helpful when things go wrong (not that things ever go wrong, I wouldn't know anything about that, I just heard about it from friends, I swear). Kubernetes Lens is a full-on desktop app that describes itself as a Kubernetes IDE. In comparison, k9s is a lighter-weight, text-based tool.

Open a Bash shell and navigate to the k8s subdirectory of the project.

Deploy your microservice architecture to Azure with:

./kubectl-apply.sh -f

If you open this file, you'll see that it creates the namespace and applies the project files. If you do this manually, it's important that the namespace is created first and that the registry is run before the other services.

...
suffix=k8s
kubectl apply -f namespace.yml
kubectl apply -f registry-${suffix}/
kubectl apply -f blog-${suffix}/
kubectl apply -f gateway-${suffix}/
kubectl apply -f store-${suffix}/
...

You can check on your pods with the following command. If you're on the free tier, this may take a few minutes. Using the pay-as-you-go plan, everything was up and running almost immediately for me.

kubectl get pods -n demo

NAME                                  READY   STATUS    RESTARTS   AGE
blog-6896f6dd58-mbjkn                 1/1     Running   0          3m51s
blog-neo4j-0                          1/1     Running   0          3m48s
gateway-7f6d57765f-2fhfb              1/1     Running   0          3m46s
gateway-postgresql-647476b4d5-jdp5c   1/1     Running   0          3m44s
jhipster-registry-0                   1/1     Running   0          3m52s
store-7889695569-k4wkv                1/1     Running   0          3m41s

Here's an example of what this looks like with Kubernetes Lens (the containers were still booting).

Another useful command is describe. I won't replicate the output here, but if you want more detailed information for debugging, you can also run the following.

kubectl describe pods -n demo

To tail logs, you can use the name of the pod.

kubectl logs <pod-name> --tail=-1 -n demo

Although, like I said, k9s and Lens are really the way to go for more detailed inspection.

Here's a screenshot from k9s. You can dig down into the different pods to get more detailed information and inspect logs.

You can use port-forwarding to see the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 8761

Open a browser and navigate to http://localhost:8761. You will be redirected to the Okta login screen, after which you will be taken to the registry.

Make sure everything is green. If you have an error, check the logs for the pod that caused the error. You can restart a specific deployment by deleting it and re-applying it. For example, to restart the store, you can use the commands below from the k8s directory.

kubectl delete -f store-k8s/
kubectl apply -f store-k8s/

Once all is good, control-c to stop forwarding the registry. Expose the gateway and open it.

kubectl port-forward svc/gateway -n demo 8080

Go to http://localhost:8080.

Authenticate with Okta. Make sure you can add blogs, posts, tags, and products. Because the store service uses the same Cosmos DB instance that you were using with Docker Compose locally, any test products you created earlier will still be there.

In preparation for the next step, delete everything you just deployed to AKS in the demo namespace.

kubectl delete all --all -n demo

The first all refers to all resource types. The second --all refers to every object in the resource types (as opposed to specifying an object name or ID). Thus by specifying the namespace you are deleting every object of every resource type in that namespace.

This is one of the benefits of using a namespace. You can do a delete like this. If you do this from the default namespace, you'll risk deleting things you didn't mean to delete or pods added by Kubernetes and Azure for infrastructure administration.

You can also just delete the entire namespace. It will be recreated if you use the Bash script to apply the deployments. This deletes absolutely everything from the namespace but is a little slower. If you do this, you need to make sure that you recreate the namespace later (I'll remind you).

kubectl delete namespace demo

Encrypt the sensitive configuration parameters

There are two really important config values that need to be encrypted: (1) the Cosmos DB connection string (which contains the database credentials) and (2) the OIDC client secret. Because these two values are processed differently, you're going to use two slightly different methods for encrypting them.

There are three different layers of encryption happening here. I found this a little confusing so I'm going to explain it briefy.

JHipster registry encryption for Spring Cloud Config values (values in k8s/registry-k8s/application-configmap.yml)
Kubernetes "encryption" (obfuscation, really) that moves secrets found in Kubernetes deployment files to base64-encoded secrets files
kubeseal which hardens Kubernetes secrets to properly encrypted values

The first above is only for Spring Cloud Config values. The latter two are used to encrypt values in the Kubernetes descriptor files (the other yml files in the k8s directory).

When you use JHipster registry encryption, you have to define an ENCRYPT_KEY value that is used by JHipster to encrypt the secrets. However, because this value is stored in yml files that are going to be committed to a repository, this value must be properly encrypted to ensure the security of the Spring Cloud Config values.

The Cosmos DB connection string (the SPRING_DATA_MONGODB_URI env var) is a Kubernetes deployment value, same as the ENCRYPT_KEY, not a Spring Cloud Config value.

Thus, to harden the OIDC client secret, you must (1) define an ENCRYPT_KEY to enable JHipster registry encryption, (2) use JHipster registry to encrypt the client ID and place the encrypted value in the application-configmap.yml, and (3) use Kubernetes secrets and kubeseal to properly encrypt the ENCRYPT_KEY.

Securing the Cosmos DB connection string is the same as the ENCRYPT_KEY: use Kubernetes secrets and kubeseal to properly encrypt it.

Matt Raible did a great job of explaining secrets management in Kubernetes in his post, Kubernetes to the Cloud with Spring Boot and JHipster. He also linked to a lot of great resources. I'm not going to go into much more detail explaining it here. Check his post out for more info.

The first thing you need to do is install kubeseal into the AKS cluster. You can take a look at the kubeseal GitHub page for more info.

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.17.5/controller.yaml

Retrieve the certificate keypair that this controller generates.

kubectl get secret -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml

Copy the raw value of tls.crt and decode it. You can use the command line, or learn more about base64 encoding/decoding in our documentation.

echo -n <paste-value-here> | base64 --decode

Put the raw value in a tls.crt file.

Next, install Kubeseal. On macOS, you can use Homebrew. For other platforms, see the release notes.

brew install kubeseal

Encrypt ENCRYPT_KEY and SPRING_DATA_MONGODB_URI (the Cosmos DB connect string). Run the following command to do this, replacing the two values with your encryption key and your connection string.

kubectl create secret generic project-secrets \
  --from-literal=ENCRYPT_KEY='<your-encryption-key>' \
  --from-literal=SPRING_DATA_MONGODB_URI='<your-connection-string>' \
  --dry-run=client -o yaml > secrets.yml

If you deleted the namespace earlier, you need to create it again (it won't hurt to run this if you didn't delete the namespace).

kubectl apply -f namespace.yml

Now, use kubeseal to convert the secrets to encrypted secrets.

kubeseal --cert tls.crt --format=yaml -n demo < secrets.yml > sealed-secrets.yml

Remove the original secrets file and deploy your sealed secrets.

rm secrets.yml
kubectl apply -n demo -f sealed-secrets.yml && kubectl get -n demo sealedsecret project-secrets

You need to update the yml files to refer to the encrypted values. Add the following env variable to the jhister-registry container in k8s/registry-k8s/jhipster-registry.yml (if an ENCRYPT_KEY already exists, replace it).

env:
  ...
  - name: ENCRYPT_KEY
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: ENCRYPT_KEY

In k8s/store-k8s/store-deployment.yml, change the SPRING_DATA_MONGODB_URI env variable to use the sealed secret.

env:
  ...
  - name: SPRING_DATA_MONGODB_URI
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: SPRING_DATA_MONGODB_URI

Deploy the cluster.

./kubectl-apply.sh -f

Give the cluster a bit to start. Check it with one of the tools I mentioned or the following:

kubectl get pods -n demo

Once everything is ready, port forward the registry to check the services.

kubectl port-forward svc/jhipster-registry -n demo 8761

Make sure you can log in and that all the services are green. You should either be automatically logged in and redirected back to the home page or directed to log in with the Okta login screen.

This is the happy dance.

Forward the gateway and test the app.

kubectl port-forward svc/gateway -n demo 8080

Log in. Make sure everything works. Kick the tires. Start a blog. Create some products. Influence some people. Restore democracy. Take over the world. Whatever you want.

Once you're done with everything, you can delete the resource group. This will also delete all the resources in the resource group, including the Cosmos database and the AKS cluster. If you have multiple subscriptions, you may need to add a --subscription param.

az group delete --name australia-east

Wait for this to finish. Once it is done, it's probably a good idea to log into the Azure Portal and make sure that the AKS cluster, the Cosmos DB instance, and the resource group have been deleted.

Azure AKS, Kubernetes, and Spring Boot microservices deployed!

Thanks to Julien Dubois for help getting this tutorial finished!

In this project you saw how to deploy a JHipster microservice to Azure AKS. You saw how you can use a managed Cosmos DB instance in place of a MongoDB pod in Kubernetes. You saw how to deploy the app first with Docker Compose and then later with kubectl and the Azure CLI. Finally, you properly encrypted all of the sensitive configuration values using a combination of JHipster registry encryption, Kubernetes secrets, and kubeseal.

As I mentioned at the top, this project is based on two of Matt Raible's tutorials:

Deepu Sasidharan wrote a tutorial, Deploying JHipster Microservices on Azure Kubernetes Service (AKS), that was also a big help.

If you liked this post, there's a good chance you'll like similar ones:

If you have questions, please ask them in the comments below! If you're into social media, follow us: @oktadev on Twitter, Okta for Developers on LinkedIn, and OktaDev on Facebook. If you like learning via video, subscribe to our YouTube channel.

Build Secure Ionic Apps with Angular and JHipster

Matt Raible — Thu, 16 Jun 2022 23:43:08 +0000

Ionic is a framework for building mobile apps with web technologies that look and act like native apps. Because they're built with web technologies (HTML, JavaScript, and CSS), you can also deploy your Ionic apps as single-page applications. Or, even better, as progressive web apps (PWAs) that work offline.

Ionic supports the big three web frameworks: Angular, React, and Vue. Once you've written your app, you can deploy it to a simulator or device with Capacitor. Capacitor (pictured as the blue layer) provides the runtime for your app to communicate with the native operating system and vice versa.

Ionic's main competitors are native apps built with Swift or Objective-C (for iOS) and Java or Kotlin (for Android). Ionic also competes with React Native, which uses web technologies and translates them to native components.

The Ionic blog has a recent post that does a performance comparison between Ionic and React Native. TL;DR: Both options will give you a high-performance app with a truly native look and feel.

Prerequisites:

What the heck is JHipster?

This tutorial will show you how to use Ionic, Angular, and Capacitor to build a mobile app that talks to a Spring Boot backend. It won't take but a few minutes, thanks to JHipster!

JHipster is an application generator that creates an Angular frontend and a Spring Boot backend based on the options you choose. It has the ability for you, as a developer, to customize what it generates with blueprints. The blueprints feature has resulted in many additional options for an app: Kotlin, Spring Native, Micronaut, Quarkus, .NET Core, NestJS, and Svelte.

Below is a diagram of the app you'll create in this tutorial and its authentication flow.

✨ Introducing the JHipster Ionic blueprint!

The JHipster project has supported generating an Ionic app using a generator-jhipster-ionic module for the past several years.
As the primary maintainer of this module, I'm proud to announce that it has been re-written as a blueprint, and it's much easier to understand now. The previous module relied on the Ionic CLI, the base Angular starter, the Ionic JHipster starter, and custom code to glue it all together.
Now, the source code is all contained in one project.

Marcelo Shima volunteered to do the conversion, and after a couple of months, I'm proud to say the JHipster Ionic blueprint is now available!

// Detect dark theme var iframe = document.getElementById('tweet-1523893356744609792-214'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1523893356744609792&theme=dark" }

Here's how to use it:

Create an ionic-app directory alongside your JHipster app.

- backend
- ionic-app

Navigate into ionic-app using your terminal. Install Ionic for JHipster and create a new app using jhipster-ionic.

npm install -g generator-jhipster-ionic
jhipster-ionic

You'll be prompted for the location of your JHipster app, a name for your Ionic app, and then you'll be off to the races!

You can also create a JHipster app and an Ionic app simultaneously by using the bundled JHipster.

mkdir bug-tracker && cd bug-tracker
jhipster-ionic jdl bug-tracker.jh
cd ../ionic4j

This process will follow the same convention where the generated backend and frontend apps are side-by-side on your hard drive.

Then you can run both apps from your Ionic app using easy-to-remember commands.

npm run backend:start
# open a new terminal window
npm start

NOTE: The JHipster Ionic blueprint currently only supports Angular. Now that it's a blueprint, it will be much easier to add support for Vue and React. If you're interested in helping out, please let me know! Okta is a platinum sponsor of the JHipster project and enjoys assigning bug bounties for feature development.

Build a mobile app with Ionic and Angular

To see Ionic + JHipster in action, let's start with a Full Stack Java + React app I created for the Auth0 blog. I updated the app to the latest version of JHipster (v7.8.1) and created an Ionic app with JHipster Ionic, so everything is guaranteed to work. This Flickr clone allows you to upload photos, tag them, and organize them into albums. First, clone the example:

git clone https://github.com/oktadev/okta-jhipster-ionic-example.git \
  jhipster-ionic --depth 1
cd jhipster-ionic/backend

Start the app:

npm run ci:e2e:prepare # starts Keycloak and PostgreSQL in Docker
./mvnw

Then, navigate to http://localhost:8080 in your favorite browser.
Sign in with admin/admin credentials and rejoice when it all works.

Open a new terminal window and enter the jhipster-ionic/ionic-app directory. Install its dependencies and run npm start to test the Ionic client.

npm install
npm start

You should be able to sign in and add a new photo.

Please keep reading to learn how JHipster made all of this possible. Or, skip ahead to run your Ionic app on iOS using Capacitor.

How to integrate Ionic and Spring Boot

JHipster makes it easy to create a Spring Boot API that Spring Security protects. The JHipster Ionic blueprint generates an Ionic client that talks to your Spring Boot API and understands its auth mechanism. I created the jhipster-ionic project using the following steps:

Install the JHipster Ionic blueprint:

npm i -g generator-jhipster-ionic@8.0.0

Create a parent directory to hold everything:

# take is a shortcut for mdkir && cd
take jhipster-ionic

Clone an existing JHipster Flickr example:

git clone https://github.com/oktadev/auth0-full-stack-java-example.git backend --depth 1

Create a new directory to hold your Ionic project, then run jhipster-ionic in it:

take ionic-app
jhipster-ionic

Provide the path to your backend JHipster app and name your app flickr2.

That's it! The blueprint will generate an Ionic client, complete with screens for editing entities, unit tests, and end-to-end tests with Cypress.

Pretty slick, don't you think?! 😎

Run your Spring Boot API

You'll need to start your backend first, so your Ionic app can talk to its API. First, start Keycloak and PostgreSQL in Docker containers:

cd backend
npm run ci:e2e:prepare # starts Keycloak and PostgreSQL in Docker

Next, update backend/src/main/resources/config/application-prod.yml to allow CORS from http://localhost:8100.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100'
    allowed-methods: '*'
    allowed-headers: '*'
    exposed-headers: 'Authorization,Link,X-Total-Count,X-${jhipster.clientApp.name}-alert,X-${jhipster.clientApp.name}-error,X-${jhipster.clientApp.name}-params'
    allow-credentials: true
    max-age: 1800

Then, start the backend app using ./mvnw -Pprod. You should be able to log in at http://localhost:8080 (with admin/admin) and add new photos using Entities > Photos. Add a few photos so you have some data to work with.

Run your Ionic app

Open another terminal and navigate to the ionic-app folder. Launch your Ionic client using npm start. In your default browser, the app will be opened at http://localhost:8100.

You should be able to log in with Keycloak and see all the listed entities in your app.

In the JHipster app's tutorial, there's a section where you're instructed to remove photo fields that can be calculated. Specifically, height, width, date taken, and date uploaded. These values are calculated when the photos are uploaded, so there's no reason to display them when adding a photo.

To add this same functionality to your Ionic app, modify src/app/pages/entities/photo/photo-update.html and wrap these fields with <div *ngIf="!isNew">.

<div *ngIf="!isNew">
  <ion-item>
    <ion-label position="floating">Height</ion-label>
    <ion-input type="number" name="height" formControlName="height"></ion-input>
  </ion-item>
  ...
  <ion-item>
    <ion-label>Uploaded</ion-label>
    <ion-datetime displayFormat="MM/DD/YYYY HH:mm" formControlName="uploaded" id="field_uploaded"></ion-datetime>
  </ion-item>
</div>

The Ionic CLI will auto-compile and reload the app in your browser when you save this file. You can prove everything works as expected by stopping your app (with Ctrl + C) and running all the end-to-end tests with Cypress.

npm run e2e

Run your Ionic app on iOS using Capacitor

Generate a native iOS project with the following commands:

npx ionic build
npx ionic capacitor add ios

Add your custom scheme (dev.localhost.ionic) to ios/App/App/Info.plist. This scheme is configured in src/environments/environment.ts; you can easily change it to something else if you like.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.getcapacitor.capacitor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>capacitor</string>
      <string>dev.localhost.ionic</string>
    </array>
  </dict>
</array>

Modify the JHipster app's CORS settings (in backend/src/main/resources/config/application-prod.yml) to allow capacitor://localhost as an origin.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100,capacitor://localhost'

Restart your backend app. Deploy your Ionic app to iOS Simulator and run it.

npx cap run ios

Confirm you can log in and rejoice in your success!

Run your Ionic app on Android

Generate an Android project with Capacitor.

npx ionic capacitor add android

Enable clear text traffic and add dev.localhost.ionic as a scheme in android/app/src/main/AndroidManifest.xml:

<activity ... android:usesCleartextTraffic="true">
  <!-- You'll need to add this intent filter so redirects work -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="dev.localhost.ionic" />
    <!--data android:scheme="com.okta.dev-133337" /-->
  </intent-filter>

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

Modify the JHipster app's CORS settings to allow http://localhost as an origin.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100,capacitor://localhost,http://localhost'

Restart your backend app and run your Ionic app on Android using the Capacitor CLI:

npx cap run android

CAUTION: If you get an error when running this command, make sure to use Java 11.

You'll need to run a couple of commands to allow the emulator to communicate with JHipster and Keycloak.

adb reverse tcp:8080 tcp:8080
adb reverse tcp:9080 tcp:9080

You should be able to log in and edit entities, just like you can in a browser and on iOS!

Why use OpenID Connect for mobile apps?

Storing API keys and secrets in mobile apps is not safe. OAuth 2.0 solves this problem by not shipping any secrets in mobile apps and instead involving the user in the process of getting an access token into the app. These access tokens are unique per user, and they're updated every time the user logs in. The PKCE extension provides a solution for securely doing the OAuth flow on a mobile app even when there is no pre-provisioned secret.

If you need to access an API from a mobile app, hopefully, it supports OAuth and PKCE! Thankfully most of the hard work of PKCE is handled by SDKs like AppAuth, so you don't have to write all that code yourself. If you're working with an API like Okta, then Okta's SDKs do PKCE automatically, so you don't have to worry about it. The JHipster Ionic blueprint uses Ionic AppAuth.

The previous sections showed you how to use Keycloak as your identity provider. If you're deploying to production, you might not want to manage your users and authentication system. That's where Okta and Auth0 can help!

Switch your identity provider to Okta

If you don't have an Okta developer account, you can sign up for one or run okta register after installing the Okta CLI.

If you want to change your JHipster app to use Okta, the Okta CLI makes this as easy as okta apps create jhipster. This command creates a .okta.env file you can source to override the default Keycloak settings.

source .okta.env
./mvnw -Pprod

With Keycloak, you don't need a separate OIDC app for Ionic. With Okta, you do. See JHipster's documentation to learn how to create a native app for Ionic on Okta.

After you've changed the client ID in your Ionic app, run it using npm start. You'll be prompted to log in using your Okta credentials at http://localhost:8100.

Switch your identity provider to Auth0

To switch your identity provider to Auth0, you first need an Auth0 account. Then, create a .auth0.env file and see JHipster's Auth0 docs for how to populate it.

Next, configure a native app for Ionic on Auth0. Once you're finished updating your Ionic app with a new client ID and audience, you should be able to run your backend and new frontend client using the following commands:

source .auth0.env
npm run backend:start
# open a new terminal
npm start

To see it in action on your mobile emulators, use the following commands:

npm run build

# iOS
npx cap run ios

# Android
npx cap run android

Learn more about Ionic, Spring Boot, and JHipster

I hope you've enjoyed learning about Ionic and the new Ionic blueprint for JHipster. In my opinion, it's pretty neat that you can rapidly prototype a mobile client for your JHipster. It's even better that you can use a leading-edge mobile application framework to do it.

You can find the source code for this example on GitHub, in the @oktadev/okta-jhipster-ionic-example repository.

If you liked this post, you might like these others too.

If you have any questions, please leave a comment below.
You can follow @oktadev on Twitter and subscribe to our YouTube channel for more leading-edge content. We're also on LinkedIn and Facebook.

Introducing Spring Native for JHipster: Serverless Full-Stack Made Easy

Matt Raible — Thu, 24 Mar 2022 16:49:18 +0000

Over the years, I've developed a lot of Java applications. I started writing Java code in the late 90s and spent several years doing Java before I tried another server-side language. I was impressed when I first tried building apps in Ruby on Rails, Python, and Node.js - they all started super-fast!

Starting fast is cool, but we in the Java community have often asked, does it perform over time? The Java Virtual Machine is famous for performance and optimization over time.

I scoffed at serverless when it first came out. Mostly because I was a Java developer and my apps didn't start in milliseconds. They also used a whole lotta memory and there was no hope in sight.

Then, along came GraalVM. It's gained support from many Java frameworks in the last few years and has made their apps start in milliseconds!

Today, I'm proud to announce that this same capability is now available for your JHipster 7+ apps!

Prerequisites:

If you'd rather learn visually, you can watch a video of this tutorial.

Why should you care about serverless?

From IBM's What is Serverless computing?

Serverless is a cloud execution model that enables a simpler, more cost-effective way to build and operate cloud-native applications.

That's it!

For companies with high traffic and large cloud bills, serverless makes sense. They can save millions of dollars a month.

GraalVM allows serverless Java for everyone!

I've been playing with GraalVM and the Java frameworks that support it for around 18 months. After doing a lot of research, I blogged about building native Java apps with Micronaut, Quarkus, and Spring Boot.

In September 2021, I did a talk with Josh Long about Spring Native with JHipster at the San Francisco JUG.

// Detect dark theme var iframe = document.getElementById('tweet-1442698739563446276-977'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1442698739563446276&theme=dark" }

I flew out on a Monday, we got everything working by Wednesday afternoon, and then spoke about our experience on Wednesday night. I wrote about it in JHipster Works with Spring Native! on LinkedIn and created a JHipster issue to automate our learnings.

What is Spring Native?

Spring Native provides an API to configure Spring Boot and GraalVM so classes that are not easily discoverable become recognizable. For example, those that are instantiated using reflection. It's a really slick extension to Spring Boot and will likely disappear with Spring Boot 3 because it'll be native by default.

As a result of our successful presentation at the SF JUG, Josh and I were invited to speak at the Garden State JUG in December. We laid low for a few months and rekindled our research in December. I wrote about it in JHipster works with Spring Native, Part 2!

🔥 Announcing the JHipster Native blueprint!

In late January 2022, we (the JHipster team) upgraded JHipster to use Spring Boot 2.6 and released version 7.6.0.

In early February, I updated the Spring Native with JHipster examples that Josh and I'd been using for research. I was ready to start automating the Spring Native integration using a JHipster module. When I asked the JHipster team about the best way to implement it, Marcelo Shima volunteered to create the initial blueprint.

This was on a Friday afternoon (Mountain Time or MT). By the next morning, Marcelo had the MVP finished and provided steps to reproduce our examples. 😳

I was amazed! I remember telling (my partner) Trish that he'd done a week's worth of (my estimated) work in a matter of hours.

Today, I'm proud to announce the JHipster Native blueprint is available! Here's how to use it:

npm install -g generator-jhipster-native
jhipster-native

This will generate a JHipster app and integrate GraalVM automatically. You can build and run a native image with the following commands:

./mvnw package -Pnative,prod -DskipTests
npm run ci:e2e:prepare # start docker dependencies
./target/native-executable

NOTE: Gradle is not currently an option. Follow generator-jhipster-native#24 to see when it's supported.

Go native with Spring Native and GraalVM

To see Spring Native + JHipster in action, let's look at a previous JHipster app I created for the Auth0 blog. First, clone the example:

git clone https://github.com/oktadev/auth0-full-stack-java-example.git jhipster-native
cd jhipster-native

TIP: Want results right away? Clone the spring-native branch with the changes below already made:
git clone -b spring-native https://github.com/oktadev/auth0-full-stack-java-example.git jhipster-native
Then, skip to the Configure your OpenID Connect identity provider section to continue.

Install JHipster 7.8.1 and the JHipster Native blueprint:

npm i -g generator-jhipster@7.8.1
npm i -g generator-jhipster-native@1.1.2

Then, remove all the existing project files and regenerate them. The jhipster-native command includes parameters to disable caching because it's not supported by Spring Native, yet.

rm -rf *
jhipster-native --with-entities --cache-provider no --no-enable-hibernate-cache
# When prompted to overwrite .gitignore, type "a" to overwrite all files

If you open the project in IntelliJ IDEA, you can use the Commit Tools Window (Cmd + 0 on macOS or Ctrl + 0 on Linux/Windows) to view files that changed.

Next, run the following git checkout commands to restore the files that were modified in the original example.

git checkout .gitignore
git checkout README.md
git checkout demo.adoc
git checkout flickr2.jdl
git checkout screenshots
git checkout src/main/webapp/app/entities/photo/photo.tsx
git checkout src/main/webapp/app/entities/photo/photo-update.tsx
git checkout src/main/java/com/auth0/flickr2/config/SecurityConfiguration.java
git checkout src/main/resources/config/application-heroku.yml
git checkout src/main/resources/config/bootstrap-heroku.yml
git checkout Procfile
git checkout system.properties

If you'd rather not use the command line, you can right-click on each file and select Rollback.

If you ran the git checkout commands, there are several changes I made in the first tutorial that'll need to be re-applied:

In src/main/resources/config/application-dev.yml, remove the faker profile for Liquibase.

In pom.xml, re-add Drew Noake's metadata-extractor library:

<dependency>
    <groupId>com.drewnoakes</groupId>
    <artifactId>metadata-extractor</artifactId>
    <version>2.16.0</version>
</dependency>

Next, modify the createPhoto() method in src/main/java/com/auth0/flickr2/web/rest/PhotoResource.java to set the metadata when an image is uploaded.

import com.drew.imaging.ImageMetadataReader;
import com.drew.imaging.ImageProcessingException;
import com.drew.metadata.Metadata;
import com.drew.metadata.MetadataException;
import com.drew.metadata.exif.ExifSubIFDDirectory;
import com.drew.metadata.jpeg.JpegDirectory;

import javax.xml.bind.DatatypeConverter;
import java.io.BufferedInputStream;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;

import java.time.Instant;
import java.util.Date;

public class PhotoResource {
    ...

    public ResponseEntity<Photo> createPhoto(@Valid @RequestBody Photo photo) throws URISyntaxException {
        log.debug("REST request to save Photo : {}", photo);
        if (photo.getId() != null) { ... }

        try {
            photo = setMetadata(photo);
        } catch (ImageProcessingException | IOException | MetadataException ipe) {
            log.error(ipe.getMessage());
        }

        Photo result = photoRepository.save(photo);
        ...
    }

    private Photo setMetadata(Photo photo) throws ImageProcessingException, IOException, MetadataException {
        String str = DatatypeConverter.printBase64Binary(photo.getImage());
        byte[] data2 = DatatypeConverter.parseBase64Binary(str);
        InputStream inputStream = new ByteArrayInputStream(data2);
        BufferedInputStream bis = new BufferedInputStream(inputStream);
        Metadata metadata = ImageMetadataReader.readMetadata(bis);
        ExifSubIFDDirectory directory = metadata.getFirstDirectoryOfType(ExifSubIFDDirectory.class);

        if (directory != null) {
            Date date = directory.getDateDigitized();
            if (date != null) {
                photo.setTaken(date.toInstant());
            }
        }

        if (photo.getTaken() == null) {
            log.debug("Photo EXIF date digitized not available, setting taken on date to now...");
            photo.setTaken(Instant.now());
        }

        photo.setUploaded(Instant.now());

        JpegDirectory jpgDirectory = metadata.getFirstDirectoryOfType(JpegDirectory.class);
        if (jpgDirectory != null) {
            photo.setHeight(jpgDirectory.getImageHeight());
            photo.setWidth(jpgDirectory.getImageWidth());
        }

        return photo;
    }
    ...
}

Install the React libraries needed:
```
npm i react-photo-album react-images
```
IMPORTANT: In the previous tutorial, I used react-photo-gallery. I switched to react-photo-album because it supports React 17. Because of this, you'll also need to update src/main/webapp/app/entities/photo/photo.tsx.
1. Change import Gallery from 'react-photo-gallery' to import PhotoAlbum from 'react-photo-album'.
2. Change <Gallery photos={photoSet} onClick={openLightbox} /> to <PhotoAlbum photos={photoSet} layout="rows" onClick={openLightbox} />.

In src/test/javascript/cypress/integration/entity/photo.spec.ts, remove the code that sets the calculated data in the should create an instance of Photo test:

cy.get(`[data-cy="height"]`).type('99459').should('have.value', '99459');
cy.get(`[data-cy="width"]`).type('61514').should('have.value', '61514');
cy.get(`[data-cy="taken"]`).type('2021-10-11T16:46').should('have.value', '2021-10-11T16:46');
cy.get(`[data-cy="uploaded"]`).type('2021-10-11T15:23').should('have.value', '2021-10-11T15:23');

Then, you'll need to add type hints for Drew Noake's EXIF processing library in src/main/java/com/auth0/flickr2/Flickr2App.java:

@org.springframework.nativex.hint.TypeHint(
    types = {
        ...
        com.drew.metadata.exif.ExifIFD0Directory.class,
        com.drew.metadata.exif.ExifSubIFDDirectory.class,
        com.drew.metadata.exif.ExifThumbnailDirectory.class,
        com.drew.metadata.exif.makernotes.AppleMakernoteDirectory.class,
        com.drew.metadata.exif.GpsDirectory.class,
})
@org.springframework.nativex.hint.NativeHint(options = "-H:+AddAllCharsets")

The @NativeHint(options = "-H:+AddAllCharsets") solves the following exception that happens when you upload a photo:

Caused by: java.nio.charset.UnsupportedCharsetException: Cp1252
    at java.nio.charset.Charset.forName(Charset.java:528) ~[native-executable:na]
    at com.drew.lang.Charsets.<clinit>(Charsets.java:40) ~[na:na]

Once you've made all the changes (or cloned the spring-native branch), you can build your hip native binary.

Build a native JHipster app

You will need a JDK with GraalVM and its native-image compiler. Using SDKMAN, run the following command and set it as the default:

sdk install java 22.0.0.2.r17-grl

Then, use Maven to build the project. Skip tests since there's no support for Mockito at this time.

./mvnw package -Pnative,prod -DskipTests

This process will take a few minutes to complete.

Configure your OpenID Connect identity provider

When you generate a JHipster app with OAuth 2.0 / OIDC for authentication, it defaults to using Keycloak. It creates a src/main/docker/keycloak.yml file for Docker Compose, as well as a src/main/docker/realm-config directory with files to auto-create users and OIDC clients.

If you want to use Keycloak for your running app, start it with the following command:

docker-compose -f src/main/docker/keycloak.yml up -d

If you'd rather use Okta or Auth0, that's possible too!

Use Okta as your identity provider

You'll need to source the .okta.env file the Okta CLI creates to override the default Spring Security settings.

source .okta.env

If you're on Windows, you can modify this file to use set instead of export and rename it to okta.bat. Then, run it with okta.bat from the command line.

CAUTION: Modify your existing .gitignore file to have *.env so you don't accidentally check in your secrets!

Skip to Run your native JHipster app if you've configured your app for Okta and just want to see it running.

Use Auth0 as your identity provider

To switch from Keycloak to Auth0, override the Spring Security OAuth properties. You don't even need to write any code!

To see how it works, create a .auth0.env file in the root of your project, and fill it with the code below to override the default OIDC settings:

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI=https://<your-auth0-domain>/
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID=<your-client-id>
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET=<your-client-secret>
export JHIPSTER_SECURITY_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

You'll need to create a new web application in Auth0 and fill in the <...> placeholders before this works.

Create an OpenID Connect app on Auth0

Log in to your Auth0 account (or sign up if you don't have an account). You should have a unique domain like dev-xxx.eu.auth0.com.

Press the Create Application button in the Applications section. Use a name like JHipster Native!, select Regular Web Applications, and click Create.

Switch to the Settings tab and configure your application settings:

Allowed Callback URLs: http://localhost:8080/login/oauth2/code/oidc
Allowed Logout URLs: http://localhost:8080/

Scroll to the bottom and click Save Changes.

Copy your Auth0 domain, client ID, and client secret into the .auth0.env file you created earlier. Then, run source .auth0.env.

In the roles section, create new roles named ROLE_ADMIN and ROLE_USER.

Create a new user account in the users section. Click on the Role tab to assign the roles you just created to the new account.

Make sure your new user's email is verified before attempting to log in!

Next, head to Auth Pipeline > Rules > Create. Select the Empty rule template. Provide a meaningful name like Group claims and replace the Script content with the following.

function(user, context, callback) {
  user.preferred_username = user.email;
  const roles = (context.authorization || {}).roles;

  function prepareCustomClaimKey(claim) {
    return `https://www.jhipster.tech/${claim}`;
  }

  const rolesClaim = prepareCustomClaimKey('roles');

  if (context.idToken) {
    context.idToken[rolesClaim] = roles;
  }

  if (context.accessToken) {
    context.accessToken[rolesClaim] = roles;
  }

  callback(null, user, context);
}

This code is adding the user's roles to a custom claim (prefixed with https://www.jhipster.tech/roles). Click Save changes to continue.

TIP: Want to have all these steps automated for you? Add a 👍 to issue #351 in the Auth0 CLI project.

Run your native JHipster app

After you've built your app, it will be available in target/native-executable. Start Keycloak or source your Okta/Auth0 settings. Then, run the following commands:

npm run ci:e2e:prepare # start docker dependencies
./target/native-executable

It should start in under a second!

What does the JHipster Native blueprint do?

The JHipster Native blueprint integrates Spring Native into a JHipster project based on findings from the research by Josh Long and me. I documented our findings in September and December 2021.

Sep 30, 2021: JHipster Works with Spring Native!
Dec 14, 2021: JHipster works with Spring Native, Part 2!

The unexpected thing is, one of the hardest problems we had to solve was with JPA and relationships. In JVM mode, everything worked fine. When running in native mode, there was an exception. The solution took days to figure out, but was quite simple to fix: I just had to add a type hint for java.util.HashSet.class. 🤯

During this experience, I was surprised to find that Spring Native doesn't support caching yet. I believe this support will be added by the community soon. In the meantime, if you're looking to start/stop your infra as fast as possible, you probably don't care about caching. Caching is made for long-lived, JVM-strong, JVM-loving apps.

What's the performance like?

The native binary starts in just over 500ms (577ms) on my 2019 MacBook Pro with a 2.4 GHz 8-Core Intel Core i9 processor and 64 GB of RAM.

If I start it in JVM mode with Maven, it takes a little over four seconds.

As far as build time goes, Spring Native says:

Finished generating 'native-executable' in 3m 15s.

If I build a Docker image with the native binary:

mvn spring-boot:build-image -Pprod

It takes a while the first time:

Total time:  07:24 min

And it's slightly faster the second time:

Total time:  06:43 min

The amount of memory used after starting: 178 MB.

The amount of memory used after running npm run e2e: 211 MB.

In the interest of full disclosure, here's the command I used to measure the amount of memory used:

ps -o pid,rss,command | grep --color native | awk '{$2=int($2/1024)" MB";}{ print;}'

What about the M1 Max? That's not an option yet, but could be in the next release of GraalVM.

Learn more about GraalVM and Spring Native

I hope you've enjoyed learning how to make JHipster work with Spring Native and GraalVM. It's still a work-in-progress. Startup time isn't the end-all-be-all metric, but it is important in a serverless environment.

You can find the source code for this example on GitHub in the @oktadev/auth0-full-stack-java-example repository. The source for the JHipster Native blueprint is in the @jhipster/generator-jhipster-native repository.

JHipster also has Micronaut and Quarkus blueprints. However, their native support is currently a work-in-progress. I hope to help improve them in the next few months.

If you liked this post, there's a good chance you'll like similar ones:

Deploy JHipster Microservices to GCP with Kubernetes

Matt Raible — Wed, 09 Mar 2022 02:03:04 +0000

When your business or application is successful, it needs to scale. Not just technology-wise, but human-wise. When you're growing rapidly, it can be difficult to hire developers fast enough. Using a microservices architecture for your apps can allow you to divide up ownership and responsibilities, and scale teams along with your code.

Kubernetes is an open-source platform for managing containerized workloads and services. Kubernetes traces its lineage directly from Borg, Google's long-rumored internal container-oriented cluster-management system.

Spring Boot and Spring Cloud were some of the pioneering frameworks in Javaland. However, even they stood on the shoulders of giants when they leveraged Netflix's open-source projects to embrace and extend. In 2018, Netflix OSS announced they'd come full circle, and adopted Spring Boot.

Today, I'd like to show you how to build and deploy (with Kubernetes) a reactive microservice architecture with Spring Boot, Spring Cloud, and JHipster. Why reactive? Because Spring Cloud Gateway is now the default for JHipster 7 gateways, even if you choose to build your microservices with Spring MVC.

Spring Cloud Gateway is a library for building an API Gateway on top of Spring WebFlux. It easily integrates with OAuth to communicate between microservices. You just need to add a TokenRelay filter.

spring:
  cloud:
    gateway:
      default-filters:
        - TokenRelay

CAUTION: Spring Cloud no longer supports Netflix Zuul. An open issue adds Spring MVC/Servlet support to Spring Cloud Gateway. It's scheduled for implementation before the end of 2021.

Prerequisites:

You can also watch this tutorial as a screencast.

A Brief Intro to Kubernetes (K8s)

Kubernetes is an open-source project from Google that provides an API for deploying your apps and making them talk with each other. It helps automate deployments and updates, and manages your apps and services with limited downtime. You use Docker containers and YAML to make it all work.

The YAML can be burdensome, but that's where JHipster comes in. It can generate the YAML for you!

Create a Kubernetes-Ready Microservices Architecture

I showed you how to build Reactive Java microservices with Spring Boot and JHipster in a previous post. Today, I'll show you how to generate K8s deployment descriptors, use Spring Cloud Config with Git, encrypt your secrets, and make it all work on Google Cloud (GKE to be specific).

Start by cloning the JHipster 7 { Vue, Spring Boot, WebFlux } reactive microservices project from GitHub:

git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/reactive-jhipster

TIP: If you just want to see the completed project, just cd into the project's jhipster-k8s directory.
cd ../jhipster-k8s

This project has four directories:

gateway: a Spring Boot + Spring Cloud Gateway project configured for OpenID Connect (OIDC) login. It's also configured as an OAuth 2.0 resource server. It contains a front-end application built with Vue.
blog: a Spring Boot + WebFlux microservice that talks to a Neo4j database.
store: a Spring Boot + WebFlux microservice that uses MongoDB.
docker-compose: a set of Docker files that describe how to run all containers together.

NOTE: The SPA app on the gateway is currently a monolith. The JHipster team is still working on micro frontends support.

If you don't have JHipster installed, install it.

npm i -g generator-jhipster@7

Generate Kubernetes Deployment Descriptors

Navigate to the reactive-jhipster directory. Next, create a k8s directory, cd into it, and run JHipster's Kubernetes sub-generator.

mkdir k8s
cd k8s
jhipster k8s

You'll be prompted with several questions. Answer them as I did below:

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:
Kubernetes namespace: demo
Docker repository name:
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>

NOTE: If you don't want to publish your images on Docker Hub, leave the Docker repository name blank.

After I answered these questions, my k8s/.yo-rc.json file had the following contents:

{
  "generator-jhipster": {
    "appsFolders": ["blog", "gateway", "store"],
    "directoryPath": "../",
    "clusteredDbApps": ["store"],
    "serviceDiscoveryType": "eureka",
    "jwtSecretKey": "NDFhMGY4NjF...",
    "dockerRepositoryName": "mraible",
    "dockerPushCommand": "docker push",
    "kubernetesNamespace": "demo",
    "kubernetesServiceType": "LoadBalancer",
    "kubernetesUseDynamicStorage": true,
    "kubernetesStorageClassName": "",
    "ingressDomain": "",
    "monitoring": "no",
    "istio": false
  }
}

I already showed you how to get everything working with Docker Compose in the previous tutorial. So today, I'd like to show you how to run things locally with Minikube.

Install Minikube to Run Kubernetes Locally

If you have Docker installed, you can run Kubernetes locally with Minikube. Run minikube start to begin.

minikube --cpus 8 start

CAUTION: If this doesn't work, use brew install minikube, or see Minikube's installation instructions.

This command will start Minikube with 16 GB of RAM and 8 CPUs. Unfortunately, the default, which is 16 GB RAM and two CPUs, did not work for me.

You can skip ahead to creating your Docker images while you wait for this to complete.

After this command executes, it'll print out a message and notify you which cluster and namespace are being used.

🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

TIP: You can stop Minikube with minikube stop and start over with minikube delete.

Create Docker Images with Jib

Now, you need to 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).

This command should also be in the window where you ran jhipster k8s, so you can copy them from there.

./gradlew bootJar -Pprod jib -Djib.to.image=<docker-repo-name>/<image-name>

Create Private Docker Images

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 jibDockerBuild

Because 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: IfNotPresent

Make 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

You've now built Docker images for your microservices, but you haven't seen them running. First, you'll need to configure Okta for authentication and authorization.

JHipster ships with JHipster Registry. It acts as a Eureka service for service discovery and contains a Spring Cloud Config server for distributing your configuration settings.

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

Now that you've configured everything, it's time to see it in action.

Start Your Spring Boot Microservices with K8s

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 demo

You can use the name of a pod with kubectl logs to tail its logs.

kubectl logs <pod-name> --tail=-1 -n demo

You can use port-forwarding to see the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 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 demo 8080

Then, go to http://localhost:8080, and you should be able to add blogs, posts, tags, and products.

You can also automate testing to ensure that everything works. Set your Okta credentials as environment variables and run end-to-end tests using Cypress (from the gateway directory).

export CYPRESS_E2E_USERNAME=<your-username>
export CYPRESS_E2E_PASSWORD=<your-password>
npm run e2e

Proof it worked for me:

Plain Text Secrets? Uggh!

You may notice that I used a secret in plain text in the application-configmap.yml file. Secrets in plain text are a bad practice! I hope you didn't check everything into source control yet!!

Encrypt Your Secrets with Spring Cloud Config

The JHipster Registry has an encryption mechanism you can use to encrypt your secrets. That way, it's safe to store them in public repositories.

Add an ENCRYPT_KEY to the environment variables in k8s/registry-k8s/jhipster-registry.yml.

- name: ENCRYPT_KEY
  value: really-long-string-of-random-charters-that-you-can-keep-safe

TIP: You can use JShell to generate a UUID you can use for your encrypt key.
jshell

UUID.randomUUID()
You can quit by typing /exit.

Restart your JHipster Registry containers from the k8s directory.

./kubectl-apply.sh -f

Encrypt Your OIDC Client Secret

You can encrypt your client secret by logging into http://localhost:8761 and going to Configuration > Encryption. If this address doesn't resolve, you'll need to port-forward again.

kubectl port-forward svc/jhipster-registry -n demo 8761

Copy and paste your client secret from application-configmap.yml (or .okta.env) and click Encrypt.

Then, copy the encrypted value back into application-configmap.yml. Make sure to wrap it in quotes!

You can also use curl:

curl -X POST http://admin:<password-you-set-earlier>@localhost:8761/config/encrypt -d your-client-secret

If you use curl, make sure to add {cipher} to the beginning of the string. For example:

client-secret: "{cipher}1b12934716c32d360c85f651a0793df2777090c..."

Apply these changes and restart all deployments.

./kubectl-apply.sh -f
kubectl rollout restart deploy -n demo

Verify everything still works at http://localhost:8080.

TIP: If you don't want to restart the Spring Cloud Config server when you update its configuration, see Refresh the Configuration in Your Spring Cloud Config Server.

Change Spring Cloud Config to use Git

You might want to store your app's configuration externally. That way, you don't have to redeploy everything to change values. Good news! Spring Cloud Config makes it easy to switch to Git instead of the filesystem to store your configuration.

In k8s/registry-k8s/jhipster-registry.yml, find the following variables:

- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_TYPE
  value: native
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_SEARCH_LOCATIONS
  value: file:./central-config

Below these values, add a second lookup location.

- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_TYPE
  value: git
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_URI
  value: https://github.com/mraible/reactive-java-ms-config/
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_SEARCH_PATHS
  value: config
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_LABEL
  value: main

Create a GitHub repo that matches the URI, path, and branch you entered.

In my case, I created reactive-java-ms-config and added a config/application.yml file in the main branch. Then, I added my spring.security.* values to it and removed them from k8s/registry-k8s/application-configmap.yml.

See Spring Cloud Config's Git Backend docs for more information.

Deploy Spring Boot Microservices to Google Cloud (aka GCP)

It's nice to see things running locally on your machine, but it's even better to get to production! In this section, I'll show you how to deploy your containers to Google Cloud.

First, stop Minikube if you were running it previously.

minikube stop

You can also use kubectl commands to switch clusters.

kubectl config get-contexts
kubectl config use-context XXX

The cool kids use kubectx and kubens to set the default context and namespace. You can learn how to install and use them via the kubectx GitHub project.

Create a Container Registry on Google Cloud

Before the JHipster 7.0.0 release, I tested this microservice example with Kubernetes and Google Cloud. I found many solutions in Ray Tsang's Spring Boot on GCP Guides. Thanks, Ray!

To start with Google Cloud, you'll need an account and a project. Sign up for Google Cloud Platform (GCP), log in, and create a project. Open a console in your browser. A GCP project contains all cloud services and resources--such as virtual machines, network, load balancers--that you might use.

TIP: You can also download and install the gcloud CLI if you want to run things locally.

Enable the Google Kubernetes Engine API and Container Registry:

gcloud services enable container.googleapis.com containerregistry.googleapis.com

Create a Kubernetes Cluster

Run the following command to create a cluster for your apps.

gcloud container clusters create CLUSTER_NAME \
--zone us-central1-a \
--machine-type n1-standard-4 \
--enable-autorepair \
--enable-autoupgrade

I called my cluster reactive-ms. See GCP's zones and machine-types for other options. I found the n1-standard-4 to be the minimum for JHipster.

You created Docker images earlier to run with Minikube. Then, those images were deployed to Docker Hub or your local Docker registry. If you deployed to Docker Hub, you can use your deployment files as-is.

For Google Cloud and its Kubernetes engine (GKE), you can also publish your images to your project's registry. Thankfully, this is easy to do with Jib.

Navigate to the gateway directory and run:

./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/gateway

You can get your project ID by running gcloud projects list.

Repeat the process for blog and store. You can run these processes in parallel to speed things up.

cd ../blog
./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/blog
cd ../store
./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/store

TIP: You might have to run gcloud auth configure-docker for Jib to publish to your GCP container registry.

Then, in your k8s/**/*-deployment.yml files, add gcr.io/<your-project-id> as a prefix. Remove the imagePullPolicy if you specified it earlier. For example:

containers:
  - name: gateway-app
    image: gcr.io/jhipster7/gateway
    env:

In the k8s directory, apply all the deployment descriptors to run all your images.

./kubectl-apply.sh -f

You can monitor the progress of your deployments with kubectl get pods -n demo.

TIP: If you make a mistake configuring JHipster Registry and need to deploy it, you can do so with the following command:
kubectl apply -f registry-k8s/jhipster-registry.yml -n demo
kubectl rollout restart statefulset/jhipster-registry -n demo
You'll need to restart all your deployments if you changed any configuration settings that services need to retrieve.
kubectl rollout restart deploy -n demo

Access Your Gateway on Google Cloud

Once everything is up and running, get the external IP of your gateway.

kubectl get svc gateway -n demo

You'll need to add the external IP address as a valid redirect to your Okta OIDC app. Run okta login, open the returned URL in your browser, and sign in to the Okta Admin Console. Go to the Applications section, find your application, and edit it.

Add the standard JHipster redirect URIs using the IP address. For example, http://34.71.48.244:8080/login/oauth2/code/oidc for the login redirect URI, and http://34.71.48.244:8080 for the logout redirect URI.

You can use the following command to set your gateway's IP address as a variable you can curl.

EXTERNAL_IP=$(kubectl get svc gateway -ojsonpath="{.status.loadBalancer.ingress[0].ip}" -n demo)
curl $EXTERNAL_IP:8080

Run open http://$EXTERNAL_IP:8080, and you should be able to sign in.

Great! Now that you know things work, let's integrate better security, starting with HTTPS.

Add HTTPS to Your Reactive Gateway

You should always use HTTPS. It's one of the easiest ways to secure things, especially with the free certificates offered these days. Ray Tsang's External Load Balancing docs was a big help in figuring out all these steps.

You'll need a static IP to assign your TLS (the official name for HTTPS) certificate.

gcloud compute addresses create gateway-ingress-ip --global

You can run the following command to make sure it worked.

gcloud compute addresses describe gateway-ingress-ip --global --format='value(address)'

Then, create a k8s/ingress.yml file:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: gateway
  annotations:
    kubernetes.io/ingress.global-static-ip-name: "gateway-ingress-ip"
spec:
  rules:
    - http:
        paths:
          - path: /*
            pathType: ImplementationSpecific
            backend:
              service:
                name: gateway
                port:
                  number: 8080

Deploy it and make sure it worked.

kubectl apply -f ingress.yml -n demo

# keep running this command displays an IP address
# (hint: up arrow recalls the last command)
kubectl get ingress gateway -n demo

To use a TLS certificate, you must have a fully qualified domain name and configure it to point to the IP address. If you don't have a real domain, you can use nip.io.

Set the IP in a variable, as well as the domain.

EXTERNAL_IP=$(kubectl get ingress gateway -ojsonpath="{.status.loadBalancer.ingress[0].ip}" -n demo)
DOMAIN="${EXTERNAL_IP}.nip.io"

# Prove it works
echo $DOMAIN
curl $DOMAIN

To create a certificate, create a k8s/certificate.yml file.

cat << EOF > certificate.yml
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: gateway-certificate
spec:
  domains:
  # Replace the value with your domain name
  - ${DOMAIN}
EOF

Add the certificate to ingress.yml:

...
metadata:
  name: gateway
  annotations:
    kubernetes.io/ingress.global-static-ip-name: "gateway-ingress-ip"
    networking.gke.io/managed-certificates: "gateway-certificate"
...

Deploy both files:

kubectl apply -f certificate.yml -f ingress.yml -n demo

Check your certificate's status until it prints Status: ACTIVE:

kubectl describe managedcertificate gateway-certificate -n demo

While you're waiting, you can proceed to forcing HTTPS in the next step.

Force HTTPS with Spring Security

Spring Security's WebFlux support makes it easy to redirect to HTTPS. However, if you redirect all HTTPS requests, the Kubernetes health checks will fail because they receive a 302 instead of a 200.

Crack open SecurityConfiguration.java in the gateway project and add the following code to the springSecurityFilterChain() method.

http.redirectToHttps(redirect -> redirect
    .httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto"))
);

Rebuild the Docker image for the gateway project.

./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/gateway

Run the following commands to start a rolling restart of gateway instances:

kubectl rollout restart deployment gateway -n demo

TIP: Run kubectl get deployments to see your deployment names.

Now you should get a 302 when you access your domain. HTTPie is a useful alternative to curl.

Update your Okta OIDC app to have https://${DOMAIN}/login/oauth2/code/oidc as a valid redirect URI. Add https://${DOMAIN} to the sign-out redirect URIs too.

Encrypt Your Kubernetes Secrets

Congratulations! Now you have everything running on GKE, using HTTPS! However, you have a lot of plain-text secrets in your K8s YAML files.

"But, wait!" you might say. Doesn't Kubernetes Secrets solve everything?

In my opinion, no. They're just unencrypted base64-encoded strings stored in YAML files. There's a good chance you'll want to check in the k8s directory you created.

Having secrets in your source code is a bad idea! The good news is most people (where most people = my followers) manage secrets externally.

// Detect dark theme var iframe = document.getElementById('tweet-1387439868444397568-901'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1387439868444397568&theme=dark" }

NOTE: Watch Kubernetes Secrets in 5 Minutes if you want to learn more about Kubernetes Secrets.

The Current State of Secret Management in Kubernetes

I recently noticed a tweet from Daniel Jacob Bilar that links to a talk from FOSDEM 2021 on the current state of secret management within Kubernetes. It's an excellent overview of the various options.

Store Secrets in Git with Sealed Secrets and Kubeseal

Bitnami has a Sealed Secrets Apache-licensed open source project. Its README explains how it works.

Problem: "I can manage all my K8s config in git, except Secrets."

Solution: Encrypt your Secret into a SealedSecret, which is safe to store - even to a public repository. The SealedSecret can be decrypted only by the controller running in the target cluster, and nobody else (not even the original author) is able to obtain the original Secret from the SealedSecret.

Store your Kubernetes Secrets in Git thanks to Kubeseal. Hello SealedSecret! by Aurélie Vache provides an excellent overview of how to use it.

First, you'll need to install the Sealed Secrets CRD (Custom Resource Definition).

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.16.0/controller.yaml

Retrieve the certificate keypair that this controller generates.

kubectl get secret -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml

Copy the raw value of tls.crt and decode it. You can use the command line, or learn more about base64 encoding/decoding in our documentation.

echo -n <paste-value-here> | base64 --decode

Put the raw value in a tls.crt file.

Next, install Kubeseal. On macOS, you can use Homebrew. For other platforms, see the release notes.

brew install kubeseal

The major item you need to encrypt in this example is the ENCRYPT_KEY you used to encrypt the OIDC client secret. Run the following command to do this, where the value comes from your k8s/registry-k8s/jhipster-registry.yml file.

kubectl create secret generic encrypt-key \
  --from-literal=ENCRYPT_KEY='your-value-here' \
  --dry-run=client -o yaml > secrets.yml

Next, use kubeseal to convert the secrets to encrypted secrets.

kubeseal --cert tls.crt --format=yaml -n demo < secrets.yml > sealed-secrets.yml

Remove the original secrets file and deploy your sealed secrets.

rm secrets.yml
kubectl apply -n demo -f sealed-secrets.yml && kubectl get -n demo sealedsecret encrypt-key

Configure JHipster Registry to use the Sealed Secret

In k8s/registry-k8s/jhipster-registry.yml, change the ENCRYPT_KEY to use your new secret.

...
- name: ENCRYPT_KEY
  valueFrom:
    secretKeyRef:
      name: encrypt-key
      key: ENCRYPT_KEY

TIP: You should be able to encrypt other secrets, like your database passwords, using a similar technique.

Now, redeploy JHipster Registry and restart all your deployments.

./kubectl-apply.sh -f
kubectl rollout restart deployment -n demo

You can use port-forwarding to see the JHipster Registry locally.

kubectl port-forward svc/jhipster-registry -n demo 8761

Google Cloud Secret Manager

Google Cloud has a Secret Manager you can use to store your secrets. There's even a Spring Boot starter to make it convenient to retrieve these values in your app.

For example, you could store your database password in a properties file.

spring.datasource.password=${sm://my-db-password}

This is pretty slick, but I like to remain cloud-agnostic. Also, I like how the JHipster Registry allows me to store encrypted secrets in Git.

Use Spring Vault for External Secrets

Using an external key management solution like HashiCorp Vault is also recommended. The JHipster Registry will have Vault support in its next release.

In the meantime, I recommend reading Secure Secrets With Spring Cloud Config and Vault.

Scale Your Reactive Java Microservices

You can scale your instances using the kubectl scale command.

kubectl scale deployments/store --replicas=2 -n demo

Scaling will work just fine for the microservice apps because they're set up as OAuth 2.0 resource servers and are therefore stateless.

However, the gateway uses Spring Security's OIDC login feature and stores the access tokens in the session. So if you scale it, sessions won't be shared. Single sign-on should still work; you'll just have to do the OAuth dance to get tokens if you hit a different instance.

To synchronize sessions, you can use Spring Session and Redis with JHipster.

CAUTION: If you leave everything running on Google Cloud, you will be charged for usage. Therefore, I recommend removing your cluster or deleting your namespace (kubectl delete ns demo) to reduce your cost.
gcloud container clusters delete <cluster-name> --zone=us-central1-a
You can delete your Ingress IP address too:
gcloud compute addresses delete gateway-ingress-ip --global

Monitor Your Kubernetes Cluster with K9s

Using kubectl to monitor your Kubernetes cluster can get tiresome. That's where K9s can be helpful. It provides a terminal UI to interact with your Kubernetes clusters. K9s was created by my good friend Fernand Galiana. He's also created a commercial version called K9sAlpha.

To install it on macOS, run brew install k9s. Then run k9s -n demo to start it. You can navigate to your pods, select them with Return, and navigate back up with Esc.

There's also KDash, from JHipster co-lead, Deepu K Sasidharan. It's a simple K8s terminal dashboard built with Rust. Deepu recently released an MVP of the project.

If for some reason you don't like CLI's, you can try Kubernetic.

Continuous Integration and Delivery of JHipster Microservices

This tutorial doesn't mention continuous integration and delivery of your reactive microservice architecture. I plan to cover that in a future post. If you have a solution you like, please leave a comment.

Spring on Google Cloud Platform

JHipster uses Docker containers to run all its databases in this example. However, there are a number of Google Cloud services you can use as alternatives. See the Spring Cloud GCP project on GitHub for more information.

I didn't mention Testcontainers in this post. However, JHipster does support using them. Testcontainers also has a GCloud Module.

Why Not Istio?

I didn't use Istio in this example because I didn't want to complicate things. Learning Kubernetes is hard enough without learning another system on top of it. Istio acts as a network between your containers that can do networky things like authentication, authorization, monitoring, and retries. I like to think of it as AOP for containers.

If you'd like to see how to use JHipster with Istio, see How to set up Java microservices with Istio service mesh on Kubernetes by JHipster co-lead Deepu K Sasidharan.

Fernand Galiana recommends checking out BPF (Berkeley Packet Filter) and Cilium. Cilium is open source software for transparently providing and securing the network and API connectivity between application services deployed using Linux container management platforms such as Kubernetes.

Learn More About Kubernetes, Spring Boot, and JHipster

This blog post showed you how to deploy your reactive Java microservices to production using Kubernetes. JHipster did much of the heavy lifting for you since it generated all the YAML-based deployment descriptors. Since no one really likes writing YAML, I'm calling that a win!

You learned how to use JHipster Registry to encrypt your secrets and configure Git as a configuration source for Spring Cloud Config. Bitnami's Sealed Secrets is a nice companion to encrypt the secrets in your Kubernetes deployment descriptors.

For more information about storing your secrets externally, these additional resources might help.

You can find the source code for this example on GitHub in our Java microservices examples repository.

git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/jhipster-k8s

See JHipster's documentation on Kubernetes and GCP if you'd like more concise instructions.

If you enjoyed this post, I think you'll like these others as well:

If you have any questions, please ask them in the comments below.

To be notified when we publish new blog posts, follow us on Twitter or LinkedIn. We frequently publish videos to our YouTube channel too. Subscribe today!

A huge thanks goes to Fernand Galiana for his review and detailed feedback.

We analyze the JHipster Community Survey on YouTube

Anthony Viard — Thu, 03 Mar 2022 17:12:06 +0000

Hi there,
You probably did not miss our Community Survey and the results shared by Alina on this blog post.

During my weekly "Compose with Anthony" Live stream session with the ModSquad on YouTube, I tried to understand and analyze the results of the survey and how we can imagine the future of the project.

Thanks to all participants! Please find the replay below and share your thoughts with us ;)

JHipster Community Survey Results

Аlina Yurenko — Thu, 10 Feb 2022 15:04:27 +0000

Several weeks ago, we launched the JHipster Community Survey. The goal was to get feedback from the community about the most useful features and components, things that are missing, and where we should focus our attention to make the project even better for everyone.

We got over 500 responses; thank you all for taking the time to contribute and share the survey with your community! Now let’s take a look at the results!

How do you use JHipster?

The first section of questions was dedicated to understanding the most common scenarios in which JHipster is used, and how exactly, so we can focus our efforts accordingly.

Which client-side frameworks do you use with JHipster?

The most commonly used framework in the JHipster community is Angular, with 68.3% of respondents making it their #1 choice. React is in second place with 35.3% votes, and the rest of the votes are distributed between Vue.js, Svelte, and using none:

What kind of applications do you create with JHipster?

It was very interesting to understand what kind of applications developers are building with JHipster. SPA/Monolith is a clear winner (78.3%), with Microservices being a close second (60.8%). Gateways and Server-only projects were equally popular:

Outside Java/Spring Boot, do you use other languages/frameworks supported by JHipster?

Many developers use JHipster for Java and Spring Boot projects, but do they use it for other platforms and frameworks? Yes; Node.js, Kotlin, and Flutter are quite popular, as well as such frameworks as Quarkus, Ionic, React Native, and Micronaut.

What is one thing you love about JHipster?

This was an open question, where everyone could share what they like about JHipster in any form. Some of the most popular answers were the following:

Easy bootstrapping of web applications
Use of best practices and standards
Eliminating routine work and getting to production fast
Enabling unit and integration tests
Using latest technologies and open source stack
Flexibility and customizations out of the box
Continuous support and community

…and many other things.

Thanks everyone for this great feedback!

What can be improved?

We also asked to identify one thing people hate about JHipster, so we can improve it. Many users said there is no such thing! :) Others pointed out that improving some of the documentation, the upgrade process, entities update, and adding more tutorials, in particular for various cloud platforms, would be great.

How would you rate the quality of generated code?

78.3% of users rated the quality of the code, generated by JHipster, as 8 out of 10 or higher!

JHipster's Roadmap

Some of the most interesting and at the same time challenging questions to answer for each project are about the roadmap. Which features should we prioritize? What is missing? Are our current plans and assumptions right, or do our users feel differently? To get night into that, we asked our users several questions about the roadmap.

What features would you like to see in JHipster?

All of the options that we put up for voting - micro frontends, GraphQL support and GraalVM Native Image support, are highly anticipated by the community. Some of the features suggested by the community, were support for TypeScript, DynamoDB, Flyway, Redis and Vert.x, extended Neo4J support, and Python support, along with introducing app templates and entity-based application dashboards, and others.

If you could improve the getting started experience for JHipster, what would you change?

A few users suggested having a minimalistic version of Jhipster, which is already addressed with the recent announcement of JHipster Lite — go and give it a try, if you haven’t yet!

Other suggestions were to have more project samples, a simple JDL sample (like “Book” and “Author”), outlining best practices for upgrading, creating sample projects with various integrations, and adding more short explainer videos and step-by-step tutorials for beginners.

JHipster User Profile

We also asked a few questions to better understand who our users are, and in what context they are using JHipster.

First, a few short facts:

Most of JHipster users define their programming level experience as “Experienced” (50.7%) or “Expert” (27.7%). Only 5% of them are beginners;
Most of them also learned about JHipster from a colleague or via GitHub;
For the majority of users (65%), JHipster is an integral part of their workflow;
42% of respondents' companies approve using JHipster.

And a few more details about developers using JHipster.

Which programming languages do you regularly use?

Another question we asked was about programming languages. Almost all our respondents use Java (96.1%), which is not surprising since a lot of JHipster’s backend options are Java-based. JavaScript is also popular (61.9%), probably primarily for the front-end part. Python and Kotlin are next, which also corresponds to feature request data we've seen before. 9% of the users also chose C# and Golang:

Have you ever made contributions to the project?

JHipster is lucky to have a very active and engaged community. Every third community member helped the project by providing feedback via GitHub, and every fourth created content about it, such as blog posts, event talks, etc. Other contributions, such as sending code PRs, contributing to docs, and helping other developers, are extremely valuable and improve the project for everyone.

Conclusion

Thanks again to everyone for taking the time to provide this feedback. We will go through the suggestions with the core team, and will use the results to adjust the project plans.

Some of the most requested features are already on our roadmap, with ongoing work happening and bounties on them — feel to contribute or share your thoughts in corresponding GitHub tickets!

[#10189] Implement a micro frontends prototype with JHipster

[#214] GraphQL support

[#13733] Add native image support with GraalVM and Spring Native

If you didn’t have a chance to participate in the survey, or have other suggestions, your feedback is always welcome on GitHub and Twitter.

Add a CLI to your JHipster blueprint

Anthony Viard — Fri, 13 Aug 2021 10:53:37 +0000

Hello my fellow hipsters. Who has never dreamt to have his own CLI for his blueprint? This is what I want to show you today.

JHipster versions and your blueprint

If like me, you like to play with many JHipster versions, switching between your fork and official JHipster releases you probably struggle with version management. How to be sure my JHipster command will launch the version I need? And how I’ll be sure my users will not have bad experiences when using my blueprint?

How a CLI can improve your blueprint experience

When you generate a project with the JHipster command line with your blueprint you type that:

jhipster --blueprint myBlueprint

This means you want to launch JHipster with a blueprint called “myBlueprint” using a global JHipster installation, or the local one. In both cases you can’t be sure the good version will be used and your blueprint as compatibility with a specific version.

Create your blueprint and its CLI

First, you need to start by creating your own blueprint, you can use the blueprint generator here : https://github.com/jhipster/generator-jhipster-blueprint

Then we need to add a cli folder that will contain the node.js code. I split it into two files, the app.js (which will launch JHipster for us) and the utils.js (which will contain some functions).

app.js

    #!/usr/bin/env node

    **const **fork = require('child_process').fork;
    **const **utils = require('./utils');

    **const **jhipsterPath = utils.generateJHipsterPath('../node_modules/generator-jhipster/cli/jhipster');
    **const **args = utils.initArguments('--blueprint', 'myBlueprint');

    utils.printBanner();
    fork(jhipsterPath, args);

utils.js

    #!/usr/bin/env node

    **const **p = require('path');
    **const **chalk = require('chalk');

    **function **generateJHipsterPath(relativePath) {
        **const **absolutePath = p.join(__dirname, relativePath);
        **return **p.normalize(absolutePath);
    }

    **function **initArguments(...args) {
        **const **inputArgs = _removeNodeArgsInProcessArgv();

        **return **args.concat(inputArgs);
    }

    **function **_removeNodeArgsInProcessArgv() {
        **return **process.argv ? process.argv.slice(2) : [];
    }

    **function **printBanner() {
        /* eslint-disable no-console */
        console.log('\n');
        console.log(`${chalk.yellow('Welcome to myBlueprint JHipster Generator')}\n`);

        console.log('This CLI will call JHipster with myBlueprint blueprint for you. You could use all JHipster CLI options.\n');

        console.log(`${chalk.redBright('Ready ?... ')}${chalk.blueBright("Let's go!")}\n`);

        console.log(
            chalk.green(' _______________________________________________________________________________________________________________\n')
        );
        /* eslint-enable no-console */
    }

    module.exports = {
        generateJHipsterPath,
        initArguments,
        printBanner
    };

This code will generate the right JHipster path (from our node_modules) and launch it with the follow argument (and print a personal header before the JHipster’s one):
-- blueprint myBlueprint

When this is done, we just need to register the node.js code as “bin” in our package.json :

    "bin": {
      "myBlueprint": "./cli/app.js"
    }

And add the cli folder in the “files” entry (to add it when doing a npm publish):

    "files": [
      "generators",
      "cli"
    ]

Link your blueprint

As long as your blueprint is not published in the npm registry you need to link it.
npm link

for yours final users a simple install is necessary
npm i -g generator-jhipster-myBlueprint

Use your CLI

In a terminal, create a new folder and type your blueprint command
myBlueprint

We can see that the JHipster version used is 5.4.0, same as our package.json

You can, of course, add options like we used to do with the original JHipster CLI:
myBlueprint --skip-client --skip-git --skip-checks

Conclusion

I hope this article will help you, you can find all the source code in my github repository here:
https://github.com/avdev4j/myBlueprint

Feel free to use it and contribute to jhipster.tech and https://github.com/jhipster

Forem: JHipster

Micro Frontends for Java Microservices

Java microservices with Spring Boot and JHipster

A quick introduction to Module Federation

Why should Java developers care?

Micro frontends in action with JHipster

Micro frontend options: Angular, React, and Vue

Build Java microservices with Spring Boot and WebFlux

Run your reactive Spring Boot microservices

Zero turnaround development that sparks joy

A look under the hood of micro frontends

Build and run with Docker

Switch identity providers

Deploy with Kubernetes

Learn more about micro frontends and microservices

CI/CD Java Microservices with CircleCI and Spinnaker

Table of Contents

Create a Java microservices architecture

Configure Okta for OIDC authentication

Set up CI for JHipster with CircleCI

Install Spinnaker on Google Kubernetes Engine

Understand Spinnaker artifacts and accounts

Install Halyard

Choose GKE for Spinnaker deployment

Choose the installation environment

Choose a storage service

Deploy Spinnaker

Set up CD for a JHipster microservices architecture

Use GKE for Kubernetes deployment

Add a Docker registry account

Add a GitHub artifact account

Create the store microservice pipeline

Configure the Docker image triggers

Configure the deployment stages

Trigger the CI/CD pipeline with a GitHub push

Inspect Spinnaker logs

Spinnaker features and best practices

Learn more about JHipster, microservices, and Kubernetes

How to Deploy JHipster Microservices on Amazon EKS Using Terraform and Kubernetes

Why Terraform, why not CloudFormation?

Scaffold a Java microservice stack using JHipster

Create an EKS cluster using Terraform

Build the Terraform configuration

Build the VPC

Build the EKS cluster

Provision the cluster

Set up OIDC authentication using Okta

Secure secrets

Deploy the microservice stack

Build the Docker images

Deploy the applications to EKS

Tear down the cluster with Terraform

Learn more about Java Microservices, EKS, Kubernetes, and JHipster

Cloud Native Java Microservices with JHipster and Istio

Why build cloud-native microservices using a service mesh?

What is Istio Service Mesh?

Build a Java Microservices Stack using JHipster

Create a GKE cluster and install Istio

Create a cluster

Install Istio to cluster

Install observability tools

Deploy the microservice stack to GKE

Create Kubernetes manifests

Deploy to GKE

Monitoring and observability

Grafana

Kiali

Zipkin

Cleanup the GCP cluster

Learn more about Java Microservices, Istio, Kubernetes, and JHipster

Run Microservices on DigitalOcean with Kubernetes

About DigitalOcean

Set up a microservices architecture for Kubernetes

Configure authentication with OpenID Connect

Run locally with minikube

Deploy to DigitalOcean Kubernetes

Notes on DigitalOcean's node sizes and volumes

Find your gateway's external IP and update redirect URIs

Secure web traffic with HTTPS

Inspect and manage cluster resources