DEV Community: Michael Weidmann

Remote debugging of Java apps in Kubernetes

Michael Weidmann — Thu, 15 Sep 2022 09:36:17 +0000

"It works on my machine ¯_(ツ)_/¯" - the older generation of developers often used this phrase in daily life. With Docker and Kubernetes there are platforms that solve such problems today.

But don’t be too happy about it: sometimes your application does not do what was implemented and tested locally. An experienced developer would turn on the debugger in such a case, but is that so easy on a Kubernetes cluster? Yes, and we'll show you exactly how in this blog post!

For the sake of simplicity, we will use the IntelliJ development environment throughout this post, but that should not be a big limitation - other development environments offer similar features.

Concept

The underlying idea is to enable debugging on a port in the Kubernetes pod (in which the Java app is running). This port must be exposed by the Pod.

Afterwards, a local port must be forwarded to the open debugging port of the pod using Port Forwarding. Last but not least, JVM Remote Debugging must be started in the development environment with the forwarded local port. The following diagram shows the structure of remote debugging in a Kubernetes cluster:

Figure 1: The concept of remote debugging in a Kubernetes cluster

Step 0: Setting up JVM remote debugging in IntelliJ

The first step is to set up remote debugging in IntelliJ. To do this, open please the configuration window for Run Configurations:

Figure 2: New "Remote JVM Debug" Run Configuration

Create a new Run Configuration by clicking on the plus symbol in the upper left corner and selecting Remote JVM Debug from the list.
Then you can give the configuration any name you like.
The standard configuration usually does not need to be adjusted. If the default port 5005 is used elsewhere in your application, you can change it in the configuration.
Now copy the command line arguments, they will be needed in the next step.
Finally, save the configuration, because you will need it later.

Step 1: Enable debugging in the remote JVM

We usually package our applications in Docker Images, which we build with such a Dockerfile:

FROM eclipse-temurin:17-alpine

ARG ARTIFACT
COPY $ARTIFACT app.jar

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar /app.jar"]

Important is the variable $JAVA_OPTS in the ENTRYPOINT. We use this to insert the previously copied command line arguments. We do this by adapting the deployment resource in Kubernetes. With kubectl get deployments you can display a list of your deployments and with kubectl edit deployment <DEPLOYMENT_NAME> you can adjust the deployment as follows:

spec:
  containers:
    - ...
      env:
        - name: JAVA_OPTS
          value: <COPIED_JAVA_OPTS>
      ports:
        - name: remotedebugging
          containerPort: <PORT>
          protocol: TCP
      ...

Replace <COPIED_JAVA_OPTS> with the copied command line arguments from IntelliJ.
Replace <PORT> with the port you use for debugging, in our case 5005.

Once you have done this, you can close the editor and Kubernetes starts a new deployment for you. You can check this with the command kubectl get pods. A new pod should have been created. Important for the next step: Copy the name of the pod!

Step 2: Port Forwarding

After the Pod has been restarted, the debugging port of the Pod must be forwarded to your local machine. This can be done with the following command: kubectl port-forward <POD_NAME> <LOCAL_PORT>:<POD_PORT>

<POD_NAME> is the name of the pod you should have copied in the previous step.
<LOCAL_PORT> must be replaced with the port used locally for forwarding and to which the development environment connects for debugging.
<POD_PORT> is the port you opened in the deployment configuration in the previous step.

Step 3: Happy Debugging!

Finally, the debugging configuration created in Step 0 must be started and the following message should appear: Listening for transport dt_socket at address: 5005. 🎉

Now you can set breakpoints and find some bugs!

Resources

Michael Weidmann is writing for the devlix Blog at https://www.devlix.de/blog
This article was published first here (german): https://www.devlix.de/remote-debugging-von-java-apps-in-kubernetes/

devlix GmbH: quality, consulting, development

The four C’s of software architecture

Michael Weidmann — Mon, 01 Feb 2021 17:36:40 +0000

It’s the little details that are vital. Little things make big things happen.
- John Wooden

The Egyptian pyramids: Seen in the big picture, they are a masterpiece of architecture; seen in detail, they are only small stones placed one on top of the other. Software is typically also composed of small units. To create a good overall picture, the small components must harmonize well with each other.

Many people in the software industry are familiar with the following situation: Ideas for a software architecture are collected, discussed, various approaches are visualized on a whiteboard or flipchart, and an architecture is agreed together. As a protocol of the meetings, the visualized architecture is photographed and saved in a wiki tool for the future.

Figure 1: Result of the architecture sessions (© Simon Brown, 2021, https://c4model.com/)

A few weeks later, a new employee joins the project and wants to get a rough overview of what the software is about and how it is actually structured (or an employee returning after vacation 😉). This task is not easy, because sometimes labels on arrows are missing and same symbols are used for different elements of the architecture. For this reason, the employee asks the responsible software architect, who, however, does not really remember the individual details either.

Conclusion 1: The architecture diagram does not by itself provide the information needed for a basic understanding (in the best case more than just that). There is simply no general standard for modeling software architectures.

In a different situation an existing software requires a new feature, which is associated with architectural changes. Due to the non-uniform and unclear way of documentation, the concrete changes are difficult to represent. Thus, valuable time can be lost by first having to reconstruct the architecture.

Conclusion 2: Changes to the architecture are always time-consuming with such a documentation style.

A short excursion into other industries

In other industries, such as building architecture or electronics, such modeling activities are largely standardized. Standards exist for the individual circuit symbols in electrical circuits, such as IEC 60617. In addition, abstract models exist for different views of a circuit diagram, which can be viewed here. It is important to mention that these models are actually used in practice!

It would be nice if standards of this kind existed for software architectures. A few important requirements for this would be:

Outsiders should understand the architecture as simply as possible by looking at the diagram
Use of uniform and simple terminology and symbols
Different views of the software so that each stakeholder has a suitable overview over the software

The last point can be compared to a map that you zoom into (see figure 2). This allows to map different levels of detail of the architecture. This is required for different stakeholders of the software.

For example, a software developer needs a much deeper insight into the architecture than a colleague from sales.

Figure 2: Different levels of abstraction of a place on a map (Base map and data from OpenStreetMap and OpenStreetMap Foundation, © OpenStreetMap contributors, 2021, https://www.openstreetmap.org/copyright/en)

But UML is a standard, isn’t it?

Absolutely correct. UML (Unified Modeling Language) is a standardized modeling language whose goal is to specify, design and document software systems. UML is known to many people and some of them in the software industry have already had to deal with it. Various diagrams can be mapped with UML. Here is a small and incomplete list (taken from here)

Behavioral diagrams:
- Activity diagram
- Use Case diagram
- Sequence diagram
- State machine diagram
- …
Structural diagrams:
- Class diagram
- Object diagram
- Deployment diagram

A good survey of the different types of UML diagrams can be found here.

UML is very interesting and some diagrams are wonderful for modeling ideas graphically! Small class diagrams representing a design pattern is a good use case for a UML diagram, because classes, interfaces, inheritances, data and behavior can be easily represented in UML.

However, to visualize the whole application architecture with UML, different diagrams would have to be drawn and brought together. This costs time and can be very confusing under certain circumstances with large architectures. In addition, the diagrams may cause confusion for people without a technical background, as they are not familiar with the notation. We can and should use UML, but for the situations it should be used for: to describe design patterns and small parts of an application in detail.

But how can we then describe software architectures?

The solution: The C4 model

In 2006, Simon Brown developed a simple and comparatively easy way to describe software architectures. In principle, this works analogously as shown in figure 2 with the map. There are four different “zoom levels” of the architecture (this also explains the name 😉):

System Context
Container
Components
Code

Before looking at the individual levels in a little more detail, it is important to agree on a common abstraction. This is also used again afterwards in the charts. The following list provides a brief overview:

Person: A human or group of humans interacting with a system.
Software System: A software system is the highest level of abstraction and describes something that provides value to its users (both human and technical). The software being modeled and other systems on which the software system depends are included.
Container: Not Docker! In the C4 model, this means individual applications or data stores. Typically, they are individually deployable/executable units. (Examples: a Spring Boot application, a PostgreSQL database, …).
Component: Just like container, this term can have many meanings. In the C4 context, a component is a grouping of related functionalities behind a defined interface. Unlike containers, components cannot be executed individually. Example: A REST controller from Spring Boot is a component.

Deeper explanations and explanations can be read on the official site.

It is important to mention that the C4 model merely describes how an architecture should be described in an understandable way. The model does not describe a process or a notation. However, there is an official proposal for the notation, which is used in the following subchapters.

The following subchapters provide a brief insight into the different abstraction levels, which can be read in more detail here. This is accompanied by an example from the official site, in which an online banking system is modeled graphically.

Level 1: System Context

This diagram shows the overview of a software system with all interactions. Not only user interactions are meant, but also external software systems. The target audience of the diagram is not only the developer of the software, but also outsiders.

Figure 3 shows an example of a System Context diagram. In the center you can see the software system, which is describes. Around the outside the people and external software systems involved are shown and how the components relate to each other.

Level 2: Container

At this level, a view is taken into the system which is described in this example. The individual elements of the system are described at a high level with containers. If relevant, external persons and systems can also be mapped.

Figure 4 shows a container diagram. Each container is an autonomously executable unit. Rough technological decisions can be documented at this level.

Level 3: Component

The penultimate level considers the individual containers from the second level separately and divides them into components. This view is comparable to a package diagram from UML. The banking example can be viewed here.

Level 4: Code

The last level considers the components defined from level 3 individually. Usually class diagrams or Entity-Relationship-Diagrams are located at this level. Often this level is considered optional, since such a deep level is not necessary for a rough understanding of an architecture.

C4-Model vs. UML

In our view, the C4 model and UML must not be contrasted; both pursue different goals and have their reason for existence. While the C4 model describes how a concrete system architecture can be documented in a way that is easy to understand, UML focuses on a uniform notation and a wide range of diagrams. In fact, we find that the diagrams resulting from the C4 model should be supplemented with UML diagrams if necessary, because the four diagrams do not represent a complete architecture documentation under any circumstances! If you are a fan of UML, the C4 diagrams can be mapped with modified UML notation.

Closing words

The C4 model has definitely convinced us and we will use it again — if it fits. In one of our projects, a colleague was able to familiarize himself with the architecture we had changed without much effort after taking parental leave.
We like using the standardized and lightweight model to design architectures efficiently and to document them in a way that is understandable for all target groups. A big advantage is the integration of the C4 model with arc42, ArchiMate and other tools. We have used draw.io with an extension so far and have been satisfied with it.

DEV Community: Michael Weidmann

Remote debugging of Java apps in Kubernetes

Concept

Step 0: Setting up JVM remote debugging in IntelliJ

Step 1: Enable debugging in the remote JVM

Step 2: Port Forwarding

Step 3: Happy Debugging!

Resources

The four C’s of software architecture

A short excursion into other industries

But UML is a standard, isn’t it?

The solution: The C4 model

Level 1: System Context

Level 2: Container

Level 3: Component

Level 4: Code

C4-Model vs. UML

Closing words

Related articles/videos

Modeling Software Architecture With C4 | by Jakub Kapuscik | Better Programming

Jakub Kapuscik ・ Jan 31, 2025 ・
Medium

DEV Community: Michael Weidmann

Remote debugging of Java apps in Kubernetes

Concept

Step 0: Setting up JVM remote debugging in IntelliJ

Step 1: Enable debugging in the remote JVM

Step 2: Port Forwarding

Step 3: Happy Debugging!

Resources

The four C’s of software architecture

A short excursion into other industries

But UML is a standard, isn’t it?

The solution: The C4 model

Level 1: System Context

Level 2: Container

Level 3: Component

Level 4: Code

C4-Model vs. UML

Closing words

Related articles/videos

Modeling Software Architecture With C4 | by Jakub Kapuscik | Better Programming

Jakub Kapuscik ・ Jan 31, 2025 ・ Medium

Jakub Kapuscik ・ Jan 31, 2025 ・
Medium