DEV Community: BjornvdLaan

Green Software is Event Driven and Carbon Aware, with Kubernetes and KEDA

BjornvdLaan — Thu, 07 Sep 2023 15:41:17 +0000

Did you know that data centres emit more carbon than aviation or shipping? And it is not slowing down, with some research forecasting that computing will contribute 14% of global emissions by 2040. Even worse, a significant portion of these emissions is wasted on non-production resources running outside office hours, always having your application scaled out for peak hours. This is not only bad for the planet but also for your cloud bill.

How can we do better? Instead of having a fixed number of application replicas, we should match the scale of our applications to:

Current events, for example, in terms of incoming web requests or messages in a Kafka topic. Sizing your application based on how much work it has alleviates overprovisioning and always-on resources.
The availability of clean energy. The electricity on the data centre's power grid comes from different sources, such as coal, nuclear, and solar. We should do more when the energy is cleaner, i.e., the carbon intensity is lower to reduce emissions further.

This article shows how we can make our applications greener by
making them event-driven and carbon-aware. We'll introduce these properties at the level of the Kubernetes cluster using KEDA (Kubernetes Event-Driven Autoscaler) and Microsoft's Carbon Aware KEDA Operator, so all applications in the cluster can benefit without becoming more complex themselves. All code examples are found in my GitHub repo.

The webshop that wants to become greener

Consider a simple webshop with only two applications: a webserver that serves the website to customers and an ordering system that takes care of all other things. When a customer places an order, the webserver puts a message with all necessary information on a queue and immediately thanks the customer for its purchase. The ordering system consumes these messages asynchronously, checks the warehouse, dispatches the delivery, and then sends a confirmation email to the customer.

Even though the number of customers varies throughout the day, both applications are currently deployed with a fixed number of replica pods appropriate for busy moments. Below is a graph with the number of messages in the queue and the ordering system replicas in the cluster. The red line indicates the number of messages on the queue, and blue shows the number of pods.

For simplicity, we assume that the replicas and messages at a specific y-coordinate would be exactly in balance, i.e., precisely enough replicas for that number of messages. In that case, the area under the blue and red lines relates to the total and useful resource consumption, respectively. The difference is wasted resources.

The webshop takes pride in its sustainable reputation and also wants to cut back on cloud costs. The webshop owner spoke with customers and learned that while the webserver should always be available and fast, it's okay if the asynchronous email confirmation arrives a bit later.

The webshop owner wants to scale the ordering system based on the queue size and whether clean energy is available. In other words, when carbon intensity is low, and many messages are waiting in the queue, the ordering system can go full speed:

If, on the other hand, either the carbon intensity is high or the number of messages is low, we should balance the number of replicas:

Let's explore how we can achieve this with KEDA.

Event-driven scaling of pods

We want to move away from an always-on ordering system with too many replicas. To dynamically scale the ordering system based on the number of messages in the queue, we use KEDA (Kubernetes Event-Driven Autoscaler), a Kubernetes operator that can scale our application based on 'events'. In our case, 'events' refer to the messages on the queue, but many more events are supported. With the KEDA Controller installed in the cluster, we can dynamically scale the ordering system by creating a ScaledObject:

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: ordering-system-scaler
spec:
  scaleTargetRef:
    name: ordering-system

  pollingInterval: 5
  cooldownPeriod: 5
  idleReplicaCount: 0
  minReplicaCount: 1
  maxReplicaCount: 10
  fallback:
    failureThreshold: 4
    replicas: 5

  triggers:
    - type: aws-sqs-queue
      authenticationRef:
        name: ordering-system-triggerauth
      metadata:
        queueURL: <AWS-DOMAIN>/000000000000/ordering-queue
        awsEndpoint: <AWS-DOMAIN>
        queueLength: "50"
        awsRegion: "eu-west-1"
        identityOwner: pod

The YAML above consists of roughly three parts:

We must tell the ScaledObject which application we want to scale. This is done through the scaleTargetRef key. In this case, the target ordering-system is the Deployment that manages the ordering system replicas.
Then, we configure how we want to scale the application. minReplicaCount and maxReplicaCount determine the range of scaling, and we can configure many other properties as well.
Finally, we tell which event(s) to scale on in triggers. Here, we defined the AWS SQS Queue trigger and told it to strive for 50 messages in the queue.

The graph from earlier changes as follows:

The difference in area under both lines is much smaller now, indicating more efficient resource usage.

What I really like about KEDA is that it does not try to reinvent the wheel. Instead, it reuses Kubernetes' built-in HPA (Horizontal Pod Autoscaler). Since Kubernetes 1.10, the HPA can use external metrics based on External Metrics Servers. KEDA 'simply' implements an External Metrics Server that exposes data about the triggers we define in our ScaledObject.

Carbon-aware limits to scaling

With KEDA's event-driven scaling, our resource consumption already changed drastically. Still, the ordering system does not take into account the current availability of clean energy. If the webshop is busier on moments with less clean energy, we can still emit much more than we would like. Let's see how we can add carbon-awareness using the Carbon Aware KEDA Operator. This Kubernetes operator limits how far KEDA can scale our consumer based on the carbon-intensity. This operator essentially sets a ceiling for allowed maxReplicas in KEDA's ScaledObject based on the carbon intensity of the current time, allowing more scaling when carbon intensity is lower. Once the operator is installed, we can configure the scaling limits through a custom resource definition:

apiVersion: carbonaware.kubernetes.azure.com/v1alpha1
kind: CarbonAwareKedaScaler
metadata:
  name: carbon-aware-ordering-system-scaler
spec:
  maxReplicasByCarbonIntensity:            
    - carbonIntensityThreshold: 237
      maxReplicas: 10
    - carbonIntensityThreshold: 459
      maxReplicas: 6
    - carbonIntensityThreshold: 570
      maxReplicas: 3

  kedaTarget: scaledobjects.keda.sh
  kedaTargetRef:
    name: ordering-system-scaler
    namespace: default

  carbonIntensityForecastDataSource:       
    mockCarbonForecast: true               
    localConfigMap:                        
      name: carbon-intensity
      namespace: kube-system
      key: data

Similar to how the ScaledObject targeted a Deployment through its scaleTargetRef, this CarbonAwareKedaScaler targets a ScaledObject defined in kedaTargetRef. This makes for a neat layered approach where each layer is unaware of the layer above.

The essential part of the YAML definition above is the maxReplicasByCarbonIntensity key, which lets us configure increasingly strict scaling limits based on the availability of clean energy.

The operator retrieves the current carbon intensity from the ConfigMap we define under the carbonIntensityForecastDataSource key, but actually filling the ConfigMap is not something it can do for you. Fortunately, Microsoft created a companion operator called the Carbon Intensity Exporter, which builds on the Green Software Foundations's CarbonAwareSDK to provide carbon intensity data in the Kubernetes cluster. However, if you just want to play around then you can also set the mockCarbonForecast key to true. The operator will then create a ConfigMap with fake carbon intensity data for testing purposes.

With the Carbon Aware KEDA Operator configured in our cluster, we further decrease our webshop's carbon emissions by doing more when energy is cleaner:

In the second peak, the messages are consumed at a slightly slower pace because carbon intensity is too high at that moment. The customer might need to wait a few more seconds for the confirmation email but likely won't even notice.

Conclusion

Computing significantly contributes to global carbon emissions, and digitalisation shows no signs of slowing down. We should, therefore, become more efficient in our resource usage. This article shows how we can use KEDA to become more event-driven and carbon-aware and reduce overprovisioning of our applications.

Carbon Aware Software: Three Demand Shaping Strategies, implemented in Kotlin

BjornvdLaan — Mon, 10 Jul 2023 08:22:31 +0000

Software engineers have a largely untapped opportunity to contribute to a greener world. In this article, I discuss how we can schedule asynchronous tasks to minimise carbon emissions.

Electricity comes from various sources, each with different carbon emissions. Depending on the source, a certain amount of carbon is emitted for each generated kilowatt hour (kwh). Clean and renewable sources like wind, solar, and hydroelectric power emit minimal carbon, while fossil fuel sources emit quite a bit more. The amount of carbon emitted by an energy source is called its carbon intensity, measured in grams of carbon per kwh.

Ideally, you would plug your computer or data center directly into a wind farm so that your software is powered with zero carbon intensity. However, it is not feasible for most individuals to directly connect to wind farms; instead, they rely on power grids that receive electricity from a mix of sources. Once connected to a grid, you cannot control the specific sources supplying your electricity. You simply receive a blend of all the current power sources within the grid, including both lower- and higher-carbon sources. Therefore, the carbon intensity of the electricity you consume reflects a combination of all the sources on the grid at that moment.

Carbon awareness is the idea of doing more when more energy comes from low-carbon sources and doing less when more energy comes from high-carbon sources. One approach to building carbon-aware software is called demand shaping: we shape our computation to match the existing supply. When the carbon cost of running your application becomes high, shape the demand to match the supply of carbon.

Demand shaping (https://learn.greensoftware.foundation/carbon-awareness)

Demand shaping sounded a bit abstract to me when I first heard about it. Therefore, I decided to build carbon-aware software myself using Kotlin and Spring Boot. This article shows my plans and insights. You can find my code here at GitHub.

Our implementation

We'll simulate a scenario where a producer periodically puts task descriptions on a queue, describing a computationally intensive task that some consumer should execute asynchronously. Imagine this being some tasks that are not time-critical but should be performed somewhere in the future. Before executing a task, the consumers will first reach out to an API called the CarbonAwareSDK, which provides information about the carbon intensity at a certain time and place.

Each consumer implements a different strategy for processing events based on the retrieved carbon intensity:

Threshold consumer only consumes new tasks from the queue if the carbon intensity is lower than a certain threshold.
Adaptive velocity consumer, which takes longer breaks between tasks based on the carbon intensity.
Forecast-based consumer, which runs its daily task at the optimal time in the next 24 hours.

CarbonAwareSDK API

CarbonAwareSDK helps us retrieve information about the carbon intensity at a certain time and place. Documentation on the available endpoints is found here. For our purposes, we use two of its functionalities.

Current Carbon Intensity

We can request the current carbon intensity at a specific location through the following URL:

https://carbon-aware-api.azurewebsites.net/emissions/bylocation?location=eastus

The response contains a field rating: the carbon intensity, measured in grams of CO2 equivalent per kilowatt hour.

[
    {
        location: "PJM_ROANOKE",
        time: "2023-06-26T17:05:00+00:00",
        rating: 588.30930389,
        duration: "00:05:00"
    }
]

Forecasted carbon intensity

We can also ask the service to forecast carbon intensities between two timestamps, indicated by path variables dataStartAt and dataEndAt.

https://carbon-aware-api.azurewebsites.net/emissions/forecasts/current?location=northeurope&dataStartAt=2023-07-19T15:00:00Z&dataEndAt=2023-07-20T16:00:00Z&windowSize=10

One really cool feature is that it also gives us the most moment in that time frame where carbon intensity is lowest.

[
    {
        generatedAt: "2023-06-26T17:00:00+00:00",
        requestedAt: "2023-06-26T17:03:33.4552082+00:00",
        location: "eastus",
        dataStartAt: "2023-06-26T17:05:00+00:00",
        dataEndAt: "2023-06-27T17:00:00+00:00",
        windowSize: 0,
        optimalDataPoints: [
            {
                location: "PJM_ROANOKE",
                timestamp: "2023-06-27T07:45:00+00:00",
                duration: 5,
                value: 497.9432056032178
            }
        ],
        forecastData: [
            {
                location: "PJM_ROANOKE",
                timestamp: "2023-06-26T17:05:00+00:00",
                duration: 5,
                value: 607.0114067773352
            },
            {
                location: "PJM_ROANOKE",
                timestamp: "2023-06-26T17:10:00+00:00",
                duration: 5,
                value: 606.2321824825342
            },
            {
                location: "PJM_ROANOKE",
                timestamp: "2023-06-26T17:15:00+00:00",
                duration: 5,
                value: 605.3570016963745
            },
            ... and more ...
        ]
    }
]

Threshold consumer

This first consumer is called every 5 seconds using Spring Boot's @Scheduled annotation. Upon invocation, the current carbon intensity is retrieved. Tasks are only retrieved and executed if the carbon intensity is lower than the threshold MAXIMUM_CARBON_INTENSITY.

@Component
class ThresholdConsumer(
    val taskProcessor: TaskProcessor,
    val carbonIntensityService: CarbonIntensityService,
    val queueService: QueueService
) {
    @Scheduled(fixedDelay = 5, timeUnit = TimeUnit.SECONDS)
    fun consume() {
        val currentCarbonIntensity = carbonIntensityService.getIntensity().rating

        if (currentCarbonIntensity < MAXIMUM_CARBON_INTENSITY) {
            val task = queueService.receiveTask()
            task?.let {
                val result = taskProcessor.process(it)
                LOGGER.info("Task ${it.id} executed successfully with threshold strategy. Result = ${result}.")
            }
        } else {
            LOGGER.info("No task executed with threshold strategy because carbon intensity ${currentCarbonIntensity} is too high (threshold = ${MAXIMUM_CARBON_INTENSITY}).")
        }
    }

    companion object {
        private const val MAXIMUM_CARBON_INTENSITY = 400
        private val LOGGER = LoggerFactory.getLogger(ThresholdConsumer::class.java)
    }
}

Adaptive velocity consumer

The adaptive velocity consumer is different from our first consumer, who will always continue consuming messages. It just works harder when the carbon intensity is lower. After reading and executing a task, the consumer sleeps 10 milliseconds for each gram of CO2 emitted for a kwh at this moment. It will therefore sleep less if more clean energy is available.

@Component
class AdaptiveVelocityConsumer(
    val taskProcessor: TaskProcessor,
    val carbonIntensityService: CarbonIntensityService,
    val queueService: QueueService
) {
    @EventListener
    fun consume(event: ApplicationReadyEvent) {
        while (true) {
            val currentCarbonIntensity = carbonIntensityService.getIntensity()

            val delay = currentCarbonIntensity.rating * 10L
            Thread.sleep(delay.toLong())

            val task = queueService.receiveTask()
            task?.let {
                val result = taskProcessor.process(it)
                LOGGER.info("Task ${it.id} executed successfully with adapted speed strategy. Result = ${result}.")
            }
        }
    }

    companion object {
        private val LOGGER = LoggerFactory.getLogger(AdaptiveVelocityConsumer::class.java)
    }
}

Forecast consumer

The first two consumers make decisions based on the current carbon intensity, which is quite similar to a greedy algorithm. Our final consumer aims to be smarter than that. Instead of asking CarbonAwareSDK for the current carbon intensity, the consumer requests a forecast for the coming day. The response looks as below. The most important field is optimalDataPoints, which contains the best moment to perform our task.

We schedule the consumer to be run once per day. During invocation, it retrieves the best moment to execute a task that day and schedules it using Spring Boot's TaskScheduler.

@Component
class ForecastingConsumer(
    val taskScheduler: TaskScheduler,
    val taskProcessor: TaskProcessor,
    val carbonIntensityService: CarbonIntensityService,
    val queueService: QueueService
) {
    @Scheduled(fixedDelay = 1, timeUnit = TimeUnit.DAYS)
    fun consume() {
        val task = queueService.receiveTask()

        task?.let {
            val optimalIntensity = carbonIntensityService.getForecastedOptimalIntensity().optimalDataPoints.first()

            taskScheduler.schedule(Instant.from(DateTimeFormatter.ISO_INSTANT.parse(optimalIntensity.timestamp))) {
                val result = taskProcessor.process(it)
                LOGGER.info("Task ${it.id} executed successfully with forecasting strategy. Result = ${result}.")
            }
            LOGGER.info("Task ${it.id} scheduled successfully at ${optimalIntensity.timestamp} with forecasting strategy.")
        }
    }


    companion object {
        private val LOGGER = LoggerFactory.getLogger(ForecastingConsumer::class.java)
    }

    fun TaskScheduler.schedule(moment: Instant, task: Runnable) =
        this.schedule(task, moment)
}

Insights

These three consumers give us an initial idea of how we can build carbon-aware software. However, is the application level the right place to implement this logic? Yes, we manage to do more work when we emit less carbon, but we still have these applications running and methods being invoked. All these network requests between the consumers and the CarbonAwareSDK also costs electricity. In addition, the application becomes more complex with this shaping logic, degrading its carbon efficiency. The three consumers each also have specific downsides:

The threshold consumer cannot guarantee that tasks are ever executed. Some locations in the world are still very reliant on coal so that the threshold might be too low.
The adaptive velocity consumer reads faster when cleaner energy is available but could still process a lot of its tasks during very dirty times of the day. Even worse, it could slowly work through the whole queue during high carbon intensity hours and then have nothing left to do when it wants to speed up.
The forecasting consumer solves the downsides of the previous two, but scheduling a task at the application level is a risky move. At any moment, the application could be killed as part of a rolling update or some error unrelated to the task. The scheduling is then lost. The task description was already removed from the queue, so it won't be executed anymore altogether.

This all gets even messier if we have multiple replicas of the same application, which is not uncommon in production environments.

Shift down to the platform

I believe the forecasting consumer is the most promising of the three strategies. However, the application is not the right place to implement this functionality. Instead, I imagine having a custom resource in Kubernetes that allows us to schedule tasks based on the carbon intensity.

apiVersion: carbonaware/v1
kind: CarbonAwareDailyJob
metadata:
  name: my-day-job
spec:
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: consumer
            image: task-consumer:1.0
          restartPolicy: OnFailure

This CarbonAwareDailyJob custom resource and its associated custom controller, reach out to the CarbonAwareSDK (which you can also host on-premise!) for the forecast of the next 24 hours. The Job described by the jobTemplate is then executed at that optimal moment, very similar to the forecasting consumer we saw earlier. An added benefit is that our custom controller centralises all calls to the CarbonAwareSDK API, saving network traffic and carbon.

Conclusion

Implementing carbon-aware software with demand shaping techniques has the potential to reduce carbon emissions and promote sustainability in our digital landscape. In this article, we applied demand shaping at the application level. However, I learned that demand shaping might be better implemented at a lower level. Green software patterns like demand shaping are still under active development. Continued research, collaboration, and adoption of carbon-aware software solutions are vital to realising these benefits and creating a greener future.

3 steps towards a greener IT landscape

BjornvdLaan — Mon, 03 Jul 2023 08:12:00 +0000

Businesses all over the world are moving towards a greener future. Steel factories look at green steel, dairy companies offer plant-based alternatives, office roofs get solar panels, and cloud providers make sustainability pledges. However, even though every company nowadays uses software and hardware of some form, the IT landscape is often not considered in those sustainability plans, even though data centres have substantial carbon emissions (more than aviation and growing!). Sustainability is also not of mind when software and hardware developers talk about non-functional requirements; they think about performance and reliability but not so much about carbon efficiency.

I believe software engineers have a largely untapped opportunity to contribute to a greener world. And a big bonus: as we green our IT landscape, the applications in it also likely become cheaper to run, with better performance and resilience. Win-win!

In this article, we will take three steps into the world of green software engineering, with concrete examples along the way. The three steps are visualised below.

1. The Software Application

Running our applications causes carbon to be emitted. We will probably never be able to emit nothing at all, but we can work to minimise the amount of carbon emitted per unit of work. There are essentially two approaches to making applications more energy-efficient.

The first approach is to simply make our application consume less energy. How to achieve this exactly depends on your application. For web applications, we could look at the network communication between the frontend and the backend and identify three options:

Reduce the size of network packets by minifying the web assets or removing unused CSS definitions.
Reduce the distance those packets travel by introducing a CDN (Content Delivery Network).
Reduce the number of API calls needed to render the page.

We could even look at the programming language you pick. Five years ago, researchers in Portugal compared the energy consumption of several popular programming languages and showed how their execution time and memory usage influenced energy usage. They found that compiled languages (C, Go, Rust, Java) tend to be more energy efficient than interpreted languages (JavaScript, Python).

Alternatively, we can make our applications more intelligent. Our power grid is supplied with electricity from various sources. When the sun is shining and the wind is blowing, then more of the available energy comes from renewable sources. Based on that concept, we build our applications to be carbon-aware: do more when more energy comes from low-carbon sources and less when more energy comes from high-carbon sources. Imagine an application that reads a task description from Kafka and performs some CPU-intensive computation that adjusts its pace based on how clean the current energy supply is. This pattern is called demand shaping, as we shape the energy demand of our application based on the carbon intensity.

Instead of changing the pace (demand shaping), we can also shift to a different time and/or place. This is called demand shifting. Imagine that your company is in Australia, and you want to run computations during nighttime. You could run the workload in the Netherlands, where its daytime and where solar power is more readily available.

2. The Runtime Platform

Our software applications are often operated on runtime platforms such as Kubernetes, which makes them a great place to achieve more sustainability gains. Making improvements at the platform-level profits all applications running on it. The k8s community has some great initiatives to assist you. I'll give three examples here.

Suppose your company has separate Dev, Test, Acceptance and Production environments. In that case, you can already achieve significant emission reduction by turning off the Dev and Test clusters on weekends. You can automate this through kube-green, which automatically shuts down your deployments and cronjobs when you don't need them. An added benefit: you also promote a healthy working environment where developers take some rest outside business hours.

By default, Kubernetes scales workloads based on CPU and RAM utilisation. However, we can use components like KEDA to scale based on relevant demand metrics such as HTTP requests or queue length. This can help us reduce resource utilisation and, therefore, your carbon emissions. KEDA can even scale deployments down to zero.

Finally, we can adjust the Scheduler to assign pods to nodes based on the carbon intensity at that machine's location. Bill Johnson, Principal Software Engineering Manager, wrote an article about this topic here.

3. The Hardware

All software we build eventually runs on hardware, from servers in a datacenter to the phones and laptops of our end users. These devices need to be manufactured, and they also need to be dismantled eventually. The carbon that is emitted during the creation and disposal of a device is called embodied carbon. The bar chart below (credits: Green Software Foundation) shows that this embodied carbon is not a trivial factor.

Reducing the embodied carbon of servers requires embracing responsible lifecycle management, which involves implementing proper disposal and recycling methods for old servers. By refurbishing, reselling, or recycling them, we extend their useful life and prevent them from ending up in landfills.

Besides the embodied carbon, we should also consider how servers are used. Simply said: the more we utilise a server, the more efficient it can run our applications. We call this energy proportionality (more info here). Therefore, we can run our software using less electricity by running on as few servers as possible.

I believe that embodied carbon and energy proportionality are why cloud providers have an amazing opportunity to contribute to a better world. I am happy to see the first steps already being taken. Servers in data centres are often written off after four; all three big cloud vendors recently announced extending this lifespan in the light of sustainability. Also, as they manage the applications of multiple companies, they can intelligently allocate workloads in such a way that no servers are sitting idle, improving utilisation rates.

Besides making hardware more sustainable under the cloud-hood, cloud providers should also give tools to their customers to make greener choices. For example, AWS Lambda has a SnapStart option to decrease startup times. In the same way, we could have a CarbonAwareStart that applies demand shaping to Lambda executions. Moreover, cloud providers could inform customers about their emissions in the same way as they now give insight into the costs. What gets measured gets improved.

Conclusion

Green software invites us, software engineers, to make our IT landscape more sustainable. Engineers can play a vital role in protecting the environment by focusing on energy efficiency, reducing waste, and minimising carbon emissions. Joining the green software movement is an opportunity and a responsibility to build a better future together. Using sustainable practices, we can drive innovation, improve performance, and contribute to a resilient digital world across all industries. Let's work together to create a greener, more sustainable planet.

Interested? Check out the Green Software Foundation.

Image attributions

Cover photo by Matt Anderson on Unsplash.

The icons used in my visualisation are found on Flaticon.com.

Globe icons created by Uniconlabs - Flaticon
Lifespan icons created by Flowicon - Flaticon
Server icons created by Freepik - Flaticon
Development icons created by Design Circle - Flaticon
Application icons created by Smashicons - Flaticon

AWS announces AWS CarbonAwareBatch, the Future of Sustainable Cloud Computing

BjornvdLaan — Thu, 22 Jun 2023 08:24:49 +0000

Today, Amazon Web Services (AWS) announced the launch of AWS CarbonAwareBatch, a revolutionary new service that reimagines the way companies approach sustainable cloud computing. The solution not only prioritizes computing efficiency but also harnesses the power of environmental responsibility.

AWS CarbonAwareBatch, built on the robust framework of AWS Batch, is designed to enhance businesses' green credentials by intelligently scheduling batch jobs during periods of low-carbon intensity. It enables organizations to minimize the carbon footprint associated with their computing tasks, bringing a new level of environmental consciousness to the technology sector.

"Efficiency and innovation are key pillars at AWS. With CarbonAwareBatch, we're not only redefining these terms but also factoring in sustainability," said April McGreen, Tech Lead of AWS CarbonAwareBatch. "We are empowering our customers to make positive environmental choices, seamlessly aligning their technological needs with their environmental goals."

Key Features

In addition to harnessing low-carbon periods, AWS CarbonAwareBatch boasts a range of innovative features:

Carbon Footprint Dashboard: An interactive, user-friendly dashboard provides real-time data on the carbon emissions saved by utilizing the service. This provides businesses with tangible data to showcase their commitment to sustainability.
Carbon Credits: AWS CarbonAwareBatch calculates the carbon emissions saved and converts them into carbon credits, which businesses can use towards their sustainability goals or trade in carbon credit markets.
Sustainability Scorecard: This feature gives an in-depth analysis of a company's sustainable usage patterns and offers recommendations on how to optimize for further environmental impact reduction.
Machine Learning Optimizations: Leveraging machine learning, AWS CarbonAwareBatch forecasts power grid carbon intensity, allowing it to optimally schedule jobs to further minimize carbon emissions.

By leveraging AWS CarbonAwareBatch, businesses can now align their operations with the principles of a green economy, reducing their carbon footprint without compromising on efficiency or productivity.

The Future is Green

With AWS CarbonAwareBatch, Amazon Web Services continues to demonstrate its commitment to driving sustainable innovation. By integrating environmental consciousness into its core services, AWS is not just preparing for the future, but actively shaping it, ensuring that technology continues to serve as a force for good.

The future of cloud computing is not just about convenience and flexibility - it's also about stewardship of our planet. AWS CarbonAwareBatch is the vanguard of this new era, providing the tools businesses need to be at the forefront of the green revolution.

…

That would have been cool, right?

While this announcement and the service of AWS CarbonAwareBatch sounds like the perfect blend of technological innovation and environmental responsibility, this announcement is unfortunately not real. It's a projection of what could be possible in the future, generated by ChatGPT and myself.

As we continue to grapple with the realities of climate change, we hope to see companies like AWS pioneering more solutions like this - technologies that not only propel us forward but also protect and preserve our world.

We look forward to a day when AWS CarbonAwareBatch, or a service very much like it, moves from the realm of AI-generated possibilities into tangible reality. Until then, we encourage everyone - technologists, businesses, and consumers alike - to continue pushing for a more sustainable future.

Kotlin Multiplatform’s three levels of testing with Kotest

BjornvdLaan — Sat, 21 Jan 2023 15:48:19 +0000

Kotlin Multiplatform allows us to share common Kotlin code between various platforms, including JVM, JavaScript, iOS, Android, and native. This is useful when we have shared business logic relevant to all platforms. If functions in that common codebase require a platform-specific implementation, then Kotlin Multiplatform offers a mechanism of expected and actual declarations to essentially create placeholders that are implemented per platform. We examine this mechanism later in this article. A Kotlin Multiplatform project contains multiple modules called source sets to enable such code sharing. By default, each platform has two source sets, one for the code (jvmMain, jsMain) and one for the tests (jvmTest, jsTest) and additionally two source sets for common code (commonMain and commonTest) that are used in all main compilations of a project. These modules are structured in a hierarchy to provide any level of code sharing.

Source set hierarchy in Kotlin Multiplatform.

One use case is to share dependencies. Below we see an example where commonTest defines Kotest dependencies used for all platforms, and the JVM-specific dependencies are added to the jvmTest source set.

sourceSets {
    val `commonTest` by getting {
        dependencies {
            implementation(libs.kotest.assertions.core)
            implementation(libs.kotest.framework.engine)
            implementation(kotlin("test-common"))
            implementation(kotlin("test-annotations-common"))
        }
    }

    val jvmTest by getting {
        dependencies {
            implementation(libs.kotest.runner.junit5)
        }
    }
}

Each platform also has its own specific code so that, for instance, the JVM part of your application can implement a server, the front-end is built in JavaScript code, and the mobile apps are created based on the source sets for Android and iOS.

This article shows how we can test all three layers of code in a Kotlin Multiplatform project: common, expected / actual declaration, and platform-specific code. We use Kotest as our testing framework because it has built-in multiplatform support. The framework delegates testing to platform-specific engines, such as JUnit and Mocha. All code samples can be found on GitHub.

Common code

Code that is shared by all platforms by default resides in the commonMain source set. It wouldn’t make sense to write tests for it in every platform, so instead, we can use the commonTest source set to store the common test suite. Let’s say that we need a function that calculates the factorial of a number in source set commonMain:

package nl.bjornvanderlaan.factorial

fun factorial(number: Int): Int
    = (1..number).fold(1) { acc, i -> acc * i}

We can provide the test code in commonTest:

package nl.bjornvanderlaan.factorial

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.ints.shouldBeExactly

class FactorialTest : StringSpec({
    "Factorial of 5 is 120" {
        factorial(5) shouldBeExactly 120
    }
})

As we can see, testing common code works the same as in ‘normal’ Kotlin projects. The cool part however is that this function can now be used in all possible platforms, which can be a huge bonus if we write all the business logic here.

Expected / Actual declarations

Sometimes, there are functions that we want to use in our common code, but they can be implemented much more efficiently with platform-specific code. For instance, Kotlin’s multiplatform standard library does not provide a way to encode a string in base64. We could roll our own implementation or look for an open-source library, but some of our target platforms already provide this functionality out of the box. Kotlin provides a mechanism of expected and actual declarations to tackle this situation. With this mechanism, a common source set defines an expected declaration, and platform-specific source sets provide the actual declaration corresponding to the expected declaration and the actual implementation. Besides functions, this mechanism also works for other constructs such as classes, enums, and annotations. Below we see an example of this mechanism for the JVM. The code is based on a tutorial from JetBrains.

/**
 * Source set: commonMain
 */
package nl.bjornvanderlaan.base64

expect fun encodeBase64(input: String): String

fun encodeGreeting(name: String): String {
    return "Greetings $name, from Kotlin Multiplatform!"
}

/**
 * Source set: jvmMain
 */

package nl.bjornvanderlaan.base64

import java.util.Base64

actual fun encodeBase64(input: String): String {
    return Base64.getEncoder().encode(input.encodeToByteArray()).decodeToString()
}

As we can see, the expected function in commonMain can be used by other functions such as encodeGreeting. Through this mechanism, we can write common code where it makes sense and let leave placeholders where we expect the platforms to deliver an actual implementation. Similar to the common code, we can write our test in commonTest:

/**
 * Source set: commonTest
 */
class Base64Test: StringSpec({
    "String is properly encoded to Base64" {
        val input = "Kotlin is awesome"

        val encodedInput = encodeBase64(input)

        encodedInput shouldBe "S290bGluIGlzIGF3ZXNvbWU="
    }
})

When we let Gradle test our project, it automatically executes this test for all platform-specific variants of the expected function. So even though we have multiple actual implementations, we do not need to repeat our test suite.

Specific Function

Finally, there are parts of the application that we want to build for specific platforms only. Because source sets are organised hierarchically, we can choose which test source we want to put our tests in. When we make a web application, we want the server code to be written specifically for the JVM, and the JavaScript source set would contain the front-end code. The tests are then likely put in jvmTest and jsTest source sets, respectively. We can use Kotest to write tests like we would for single-platform Kotlin projects. The advantage of Kotest is that we have one unified testing framework, and we can also use all helper functions and custom assertions from parent source sets. Let’s say that we want to write a function for the JVM platform that calculates the factorial of a factorial of a number. Note that the value is already bigger than what Integer can handle if the number is 4. Luckily, as this function is specific to the JVM, we can use BigInteger for this purpose.

/**
 * Source set: jvmMain
 */
package nl.bjornvanderlaan.factorialoffactorial

import nl.bjornvanderlaan.factorial.factorial
import java.math.BigInteger

fun factorialOfFactorial(number: Int): BigInteger {
    val bigNumber = factorial(number).toBigInteger()

    var currentNumber = BigInteger.ONE
    var accumulator = BigInteger.ONE

    while(currentNumber <= bigNumber) {
        accumulator *= currentNumber
        currentNumber++
    }
    return accumulator
}

kotlin

The function above also shows how the jvmMain source set can use the factorial function from its parent commonMain in the same way it can use its own functions. The function above can be tested with Kotest in the same way as we have seen in the other examples:

/**
 * Source set: jvmTest
 */
package nl.bjornvanderlaan.factorialoffactorial

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe
import java.math.BigInteger

class FactorialOfFactorialTest: StringSpec({
    "Factorial of factorial of 4 is 620448401733239439360000" {
        factorialOfFactorial(4) shouldBe BigInteger("620448401733239439360000")
    }
})

This function and its tests are defined in the JVM-specific part of our application and can, therefore, benefits from classes like BigInteger.

Intermediate levels

The examples above assume only two levels of hierarchy: the common parent and its platform-specific children. In practice, we might introduce more levels. For instance, if we also build a mobile application for iOS and Android, we might have an intermediate source sets mobileMain that depends on the commonMain source set and acts as the parent for iosTest and androidMain. In that case, the mobileTest source set can contain tests for functions implemented in mobileMain or expected functions implemented in child source sets.

Conclusion

Kotlin Multiplatform helps us reduce the time spent on writing and maintaining the same code for different platforms, and Kotest helps us to unify our testing efforts by providing a multiplatform framework. Multiplatform projects are structured as a hierarchy of source sets. The rules for testing are the same at every node: Kotest executes our tests on either the implementation in the main source set itself or fetches the actual implementations from child source sets. As such, Kotlin Multiplatform offers us the flexibility to create a super DRY codebase and test suite, regardless of the number of platforms we want to support.

Property-based testing with Kotlin and Kotest: the Christmas edition

BjornvdLaan — Sat, 21 Jan 2023 15:38:16 +0000

This article was previously posted as part of the 2022 Java Advent calendar.

Christmas is coming, and Santa and the elves are working around the clock to build all toys. After a long day in the toy workshop, the elves want to spend their hard-earned NorthPoleCoins on jingle juice and sweets at the local pub. They always go in groups and often order collectively. They use a special application to keep track of payments so that every elf pays its fair share. We see the service that settles these payments below.

To preserve peace on the north pole, we want to add some tests to ensure that this service works as intended. One crucial property of the method above is that, at any point in time, the balances of all elves add up to zero. Otherwise, coins would be created or lost. A unit test for this method could look something like the one below.

First, the scenario is set up by initialising the objects with example values. Then, we invoke the method under test and write assertions to verify that the output is as expected. Of course, it doesn’t stop with this single test case. We generally write additional, similar tests to sufficiently cover all scenarios and edge cases. And when we see that all the test scenarios we came up with are passing, we can relievedly commit or deploy our code.

Downsides of example-based testing

If we take a step back, we see that many of these test cases are quite similar, except that each uses a slightly different example. There are a few downsides to this approach. First of all, developers need to spend more time developing and maintaining these test cases. This includes coming up with realistic examples, which requires a thorough understanding of the domain. New developers on the team might also have a hard time grasping the actual intent of the test. It takes time to see what angles are covered for each method and what is missing or redundant. And despite all this effort from the team, only a small portion of all possible examples are covered by the tests they wrote. Covering all combinations of inputs is just not feasible. And even worse, the scenarios covered are the same every run: essentially coupling between scenario and test suite.

When we implement our methods, we want the logic to be generic and not tied to specific cases. The code should have certain properties for all possible inputs. The tests we write for it are more the opposite: we write tests that are example-specific and not generic. The code and tests are designed on different levels of abstraction, where properties are more abstract than concrete examples.

Property-based testing to the rescue

But what if we could write tests like we write our code? Property-based testing (short: PBT) can help us out here. Instead of defining the concrete examples to test, you specify the domain (strings, positive integers, etc.) and let the framework generate many input values, including edge cases. Each test is executed multiple times with different possible inputs during a test run. Property-based testing allows us to write one test that tests all of the desired inputs, including typical edge cases, which allows for more efficient test writing and ensures that a test passes for all possible values within the domain.

Below we see how our test could look as a property-based test. The scenario function is replaced by Kotest’s checkAll, taking as its inputs a set of generators. The class containing all generators is called Arb, which is short for arbitrary. A predefined number of examples is generated for each test run, a thousand by default in Kotest. The rest of the test remains completely the same, except that we added some code to transform the generated values to the entities and values of our domain.

Our example-based tests previously all passed, which might lead us to believe that this property-based test will also be happy. Our test cases represented all possible paths, right? However, we are actually met with a failure this time. You might think that a property-based test is more difficult to debug because of its generated input values, but we did not talk about PBT’s superpower. Kotest not just mentions the failing example if the test fails, it starts ‘shrinking’ the input values. If the test fails with integer value 8 as input then this value is shrunk to value 7, and the test is retried. If the test failed when we tried to input a list of three strings integer then the list is shrunk to two strings. Shrinking continues until the test passes again, and the goal is to find the minimal reproducible example for which the test fails, which helps find the bug. Let’s have a look at the stack trace of our run.

The test failed when we tried to divide (a rounded) 77.93 NorthPoleCoins over four elves, and Kotest started shrinking both inputs. Interestingly, both shrinks uncovered a different bug for us. Dividing the coins led to a rounding error, while an empty list caused an exception to be thrown. We might not have thought of it when we created our examples, but now we can adapt our code based on these results.

When we make ourselves as developers responsible for coming up with realistic examples, we risk such bugs slipping through the cracks. Property-based tests make sure that all scenarios can be verified.

Custom generators

The property-based test we saw above is less readable than we would like because of the logic we added to transform the values from the built-in Arb generators to be suitable for our test. Kotest allows us to define custom Arb’s through the arbitrary builder, and we can use Kotlin’s extension functions to use these custom generators in the same way as their built-in counterparts.

Where Kotest knows how to shrink built-in generators, the shrinking behaviour for custom generators can be very dependent on your domain. Therefore, the arbitrary builder allows us to provide a shrink function that returns a list of values we deem to be a shrink result of the current generated value. Let’s have a look at what this could look like:

We ended up with a more concise test than the example-based test that we started with, but it covered many more examples than before.

Conclusion

In this article, we’ve seen what property-based testing is and how it differs from the more common example-based testing. Where defining representative examples in example-based testing is the programmer’s responsibility, property-based testing leaves this to generators so that the tests do not become partly dependent on the chosen examples. Property-based testing allows us to generalize concrete examples to focus on the characteristics of the code that underlie these examples, resulting in a cleaner and more compact test suite that is easy to maintain and better exposes subtle bugs. In this way, we bring what we test closer to what we claim to test. However, it is also important to note that property-based testing is not intended to replace example-based unit tests completely. It’s an addition to our testing arsenal that allows us to cover every possible input value with a single test to reveal bugs we might not come up with ourselves.

Generate class diagrams with a Kotlin DSL for PlantUML

BjornvdLaan — Sat, 18 Dec 2021 15:05:27 +0000

Technical documentation of the systems helps us and our (future) colleagues to understand how things are built and how they work. The importance of internal documentation was recently also proven by the State of DevOps 2021, which notes it as one of its key findings this year. However, while probably most of us understand the relevance of good documentation, it is still not trivial to always keep it in sync with reality. Deadlines are tight, people want value delivered asap, "we will update it next sprint", and more decisions to get short term gains.

In a recent project, we therefore wanted to automate the creation of certain parts of the documentation. The first automation candidate we identified were class diagrams. As part of our documentation-as-code approach, these diagrams were already manually made with PlantUML, an open-source tool allowing users to create diagrams from a plain text language. For example, with PlantUML, we can write the following text:

@startuml
class Person {
  + id : Int
  + name : String
  + getName() : String
  + getPets() : List<Pet>
}

class Pet {
  + id : Int
  + name : String
  + owner : Person
  + getName() : String
  + getOwner() : Person
}

Person - Pet : owns >
@enduml

The PlantUML tool can take this simple text document and generate a PNG with a cool retro-ish look:

With PlantUML, you can update the documentation in the same pull request as your code changes and benefit from git's version-control. Also, as its part of the pull requests, colleagues can actually review the diagrams and so each change to documentation is approved by someone else. I personally think this is already a big improvement compared to stashing your documentation somewhere far away from your code on a Confluence page or, even worse, a Sharepoint.

For the project that I worked on, we would have these PlantUML diagrams in the repository and a git push would trigger a pipeline that creates the PNG images and deploys everything to our Sphinx-based company documentation server. That works well, but we still needed to manually update these diagrams and that felt like applying our changes twice. Once to the code and once to the documentation. Could we not just generate the docs?

The plan

We want to create class diagrams automatically. A first thought would be to use StringBuilder. While that is perfectly possible, we preferably had a more structured way that also ensures a checked and standardised output. To this end, we explored creating a Kotlin DSL (Domain-Specific Language) for PlantUML diagrams. This article explains our approach and the decisions we took. Below you see a sneak-peak of the syntax. Do you like what you see? Then please read on!

fun main() {
    val myDiagram = classDiagram {
        clazz("Person") {
            public (
                Field("id", "Integer"),
                Method("getPets", "List<Pet>")
            )
        }

        clazz("Pet") {
            public (
                Field("id", "Integer"),
                Method("getName", "String"),
                Method("getOwner", "Person")
            )

            private {
                Field("name", "String")
            }
        }

        relationship("Person", "Pet", RelationshipType.ASSOCIATION, "is owned by")
    }
}

Lambda with receivers

The secret ingredient to create DSL's in Kotlin is its receiver types. Using these, a lambda with a receiver allows you to call methods of an object in the body of a lambda without any qualifiers. Much has already been written about receivers in other articles so, in this article, we will only look at the applying lambda's with receivers to our specific use case.

Diagram-as-a-constrained-tree

The key idea behind our PlantUML DSL is to see a class diagram as a very constrained tree structure. Each node has children of a very specific type. For example, a class can only have fields and methods.

DSL's are great to encode such constraints. Let's start by defining an abstract base class for all our elements. PlantUmlElement has a list to keep track of its children which are all subtypes of PlantUmlElement as well. A new child can be added through the addChild method, which has two implementations:

The first implementation accepts just the new child as parameter. This method will be used if that child is a leaf node and does not require further initialisation.
Otherwise, we also pass a lambda with receiver to initialise the grandchildren.

We also require subclasses to implement the toString() method to get the PlantUML String. I admit that this is a slight misuse of toString(), but it does make our syntax cleaner for our example.

abstract class PlantUmlElement {
    protected val children = mutableListOf<PlantUmlElement>()

    protected fun <T: PlantUmlElement> addChild(child: T) {
        children.add(child)
    }

    protected fun <T: PlantUmlElement> addChild(child: T, init: T.() -> Unit) {
        child.init()
        this.addChild(child)
    }

    abstract override fun toString(): String
}

Implementation of the elements

All elements essentially follow the same approach:

Extend the PlantUmlElement base class.
If the element is not a leaf, then expose a method for each possible child element type that calls addChild. If the child element type is also not a leaf, then the variant of addChild is called with a lambda with receiver.
Override toString() to return the PlantUML representation of this element. If the element is not a leaf, then call the toString() methods of the children as well.

The implementation then looks like this:

enum class AttributeVisibility { PUBLIC, PRIVATE, PROTECTED }

abstract class Attribute(private val first: String, private val second: String? = null): PlantUmlElement() {
    private var visibility: AttributeVisibility = AttributeVisibility.PUBLIC

    fun setVisibility(visibility: AttributeVisibility): Attribute {
        this.visibility = visibility
        return this
    }

    protected fun getModifier() =
        when(this.visibility) {
            AttributeVisibility.PUBLIC -> "+"
            AttributeVisibility.PRIVATE -> "-"
            AttributeVisibility.PROTECTED -> "*"
        }

    abstract override fun toString(): String
}

class Field(private val name: String, private val dataType: String? = null): Attribute(name, dataType) {
    override fun toString() = "${getModifier()} $name ${if(dataType != null) ": $dataType" else ""}"
}

class Method(private val name: String, private val returnType: String? = null): Attribute(name, returnType) {
    override fun toString() = "${getModifier()} $name() ${if(returnType != null) ": $returnType" else ""}"
}

enum class RelationshipType { EXTENSION, COMPOSITION, AGGREGATION, ASSOCIATION }

class Relationship(private val left: String, private val right: String, private val type: RelationshipType, private val label: String? = null): PlantUmlElement() {
    override fun toString() = "$left ${getArrow()} $right ${if (label != null) ": $label" else ""}"

    private fun getArrow() =
        when(this.type) {
            RelationshipType.EXTENSION -> "<|--"
            RelationshipType.COMPOSITION -> "*--"
            RelationshipType.AGGREGATION -> "o--"
            RelationshipType.ASSOCIATION -> "<--"
        }
}

class Class(private val name: String, private val identifier: String): PlantUmlElement() {
    private fun addAttributes(attributes: List<Attribute>, visibility: AttributeVisibility)
        = attributes.forEach { addChild(it.setVisibility(visibility)) }

    fun public(vararg attributes: Attribute) = addAttributes(attributes.toList(), AttributeVisibility.PUBLIC)
    fun private(vararg attributes: Attribute) = addAttributes(attributes.toList(), AttributeVisibility.PRIVATE)

    override fun toString() = "class \"${this.name}\" as ${this.identifier} {\n\t${children.joinToString("\n\t")}\n}"
}

class ClassDiagram: PlantUmlElement() {
    fun clazz(name: String, identifier: String = name.replace(" ", ""), init: Class.() -> Unit) =
        addChild(Class(name, identifier), init)

    fun relationship(left: String, right: String, type: RelationshipType, label: String? = null) =
        addChild(Relationship(left, right, type, label))

    override fun toString() = "@startuml ldm\n\t${children.joinToString("\n\n")}\n@enduml"
}

All that we now still require is a function to start with the root ClassDiagram. This function is not part of a class and accepts a lambda with receiver that is then applied to a freshly created ClassDiagram object.

fun classDiagram(init: ClassDiagram.() -> Unit) = ClassDiagram().apply(init)

A more complex example

Using the DSL we just created, we can make class diagrams that are slightly more complex than what we already saw in this article. For example, we can write the following diagram:

fun main() {
    val myDiagram = classDiagram {
        clazz("Person") {
            public (
                Field("id", "Integer"),
                Method("getName", "String")
            )
        }

        clazz("Customer") {
            public (
                Field("id", "Integer"),
                Field("emailAddress", "String"),
                Method("getName", "String"),
                Method("getAccountBalance", "Integer"),
                Method("verifyPassword", "Boolean")
            )

            private (
                Field("name", "String"),
                Field("password", "String")
            )
        }

        clazz("Wallet") {
            public (
                Field("id", "Integer"),
                Field("customerId", "Integer"),
                Method("getBalance", "Integer")
            )
        }

        clazz("Order") {
            public (
                Field("id", "Integer"),
                Field("customerId", "Integer"),
                Method("place", "Integer"),
                Method("getTotalPrice", "Float")
            )
        }

        clazz("OrderItem") {
            public (
                Field("id", "Integer"),
                Field("orderId", "Integer"),
                Method("getDescription", "String")
            )

            private (
                Field("description", "String"),
                Field("price", "Float")
            )
        }

        relationship("Person", "Customer", RelationshipType.EXTENSION, "extends")
        relationship("Customer", "Wallet", RelationshipType.AGGREGATION, "belongs to")

        relationship("Order", "OrderItem", RelationshipType.COMPOSITION, "is part of")

        relationship("Order", "Customer", RelationshipType.ASSOCIATION, "places")
    }

    println(myDiagram)
}

Which results in this image:

Et Voila!

That's all we need to create a simple class diagram. Obviously, PlantUML has a lot more features and these can be integrated into our DSL as well. To actually automate documentation generation, we would then use forEach, map and other language features to dynamically put such diagram together. At least, we now have an approach that is more robust that just building a string using StringBuilder or just appending Strings. We can enforce constraints and the generation code is also much more readable.

The full code and all examples in this article can be found on GitHub: BjornvdLaan/plantuml-dsl-kotlin.

Create your REST API using OpenAPI kotlin-spring generator

BjornvdLaan — Thu, 11 Nov 2021 12:04:09 +0000

When building an API, I like to start by first creating a formal definition before starting the actual development. One of the most established standards for such API definitions is OpenAPI (formerly Swagger). One pleasant aspect of starting with a definition is that, once the definition is created and agreed upon, we can generate part of our codebase using the OpenAPI Generator. As the name suggests, the OpenAPI Generator generates code from an OpenAPI specification. More specifically, the generator is able to create code for client libraries, server stubs, documentation, and configuration in many different languages and frameworks.

I know this generator from my Java projects and decided to use it with Kotlin as well. Lucky for me, there is actually a generator for Spring Boot-based Kotlin projects! I, however, could not find a tutorial dedicated to it and therefore I share my steps here in this tutorial.

TL;DR

You can find the full project (including target) at https://github.com/BjornvdLaan/kotlin-spring-boot-open-api-example.

What we want to achieve

We wish to generate the server stub using the OpenAPI Generator via its Maven plugin. An advantage of using the Maven (or Gradle) plugin is that the generation becomes part of our API’s build lifecycle and the generated code is always in sync with your OpenAPI definition when you clean compile your code.

For our example in this tutorial, we will use the PetStore OpenAPI specification from this tutorial on Baeldung. After running the Maven plugin, the generated code is found in the target/generated-sources/openapi directory (see below). After generation, we ‘only’ still need to implement the generated Delegate interfaces within our own src directory and, voila, the API is implemented. We will implement one of the routes in the PetStore specification and test it using curl.

Create your Spring Boot project

We start by creating a fresh Spring Boot project using the Spring Initializr. We tell it to be a Maven project using Kotlin and packaged as a jar. We also add the Spring Web dependency because the generated code depends on this dependency.

After downloading the project, we open it in our favorite IDE and we add the petstore.yml OpenAPI definition to src/main/resources to end up with the following project structure.

Before we can start, we need to add one more dependency to our pom.xml that the generated code depends on:



<dependency>             
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Add the Maven plugin

Now it's time to add the OpenAPI Generator's Maven plugin to pom.xml.



<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>
                    ${project.basedir}/src/main/resources/petstore.yml
                </inputSpec>
                <generatorName>kotlin-spring</generatorName>
                <configOptions>
                    <basePackage>nl.bjornvanderlaan.petstoreapi</basePackage>
                    <apiPackage>nl.bjornvanderlaan.petstoreapi.api</apiPackage>
                    <modelPackage>nl.bjornvanderlaan.petstoreapi.model</modelPackage>
                    <configPackage>nl.bjornvanderlaan.petstoreapi.config</configPackage>
                    <delegatePattern>true</delegatePattern>
                    <interfaceOnly>false</interfaceOnly>
                    <modelNameSuffix>Dto</modelNameSuffix>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

An overview of all configuration options is found here. I would like to highlight three options where I made a design decision:

[delegatePattern = true] - I asked the generator to use the Delegate pattern so the routes and their logic are separated. The Delegate implementations that we write ourselves can be injected in the generated code, without any need to manually touch the generated sources.
[interfaceOnly = false] - This option determines whether the controller implementation will also be generated. This controller implementation essentially just autowires the relevant Delegate to be used in the routes. I feel its good to let it be generated because then no engineer can be tempted to add other functionality to the controller, maintaining better separation of concerns. If you really want to do a lot more in your controller then it is worth considering to set this option to true.
[modelNameSuffix = Dto] - I prefer to use the Dto (Data Transfer Object) pattern to separate these objects from the entities that I will use in the service layer. As such, I add a suffix to make the pattern usage explicit.

Generate the code

We can generate the code by running mvn clean generate-sources and we then obtain the following project structure:

For IntelliJ users: the target/generated-sources/openapi/src/main/kotlin folder can be marked as an generated sources root. Right-click this folder, then go to 'Mark Directory as' and select Generated Sources Root.

The target/generated-sources/openapi/src/main/kotlin now contains two packages with a couple of classes each. Let's quickly go through them one by one.

api.PetsApi.kt

This interface class defines one method for each API route from our specification using Spring Web annotations like @RequestMapping, @GetMapping, and @PostMapping.
The methods are all one-liners as they simply delegate the work to the Delegate, exactly as we configured.
The interface also has an unimplemented getDelegate() which will be implemented by PetsApiController.

api.PetsApiDelegate

This interface defines the methods used by the PetsApi with a standard implementation that just returns status 501 Not Implemented. We will implement the interface in our src folder.

api.PetsApiController.kt

The Controller implements the PetsApi interface by autowiring the PetsApiDelegate implementation. As mentioned, I configured OpenAPI Generator to generate this class for me because I feel this is all the Controller should do.

api.Exceptions

This @ControllerAdvice class defines default exception handling for three exceptions that are commonly encountered.

api.ApiUtils

This object (singleton) defines a utility method used by a utility method for GET mappings.

model.ErrorDto

This Dto can be used to send back erroneous response to the requestor.

model.PetDto

The Dto that resembles our pets and is used to respond to, for instance, GET requests that want to retrieve data. Our generated code contains two examples of such routes: listPets and showPetById.

Implement the Delegate

Now it's finally time to start coding. We create a new class in nl.bjornvanderlaan.petstoreapi.api package (in src, not target!!) and we override the listPets method to let it return an hardcoded response with my three favorite cat names and status 200 (Ok).



package nl.bjornvanderlaan.petstoreapi.api

import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.stereotype.Component
import nl.bjornvanderlaan.petstoreapi.model.PetDto

@Component
class PetsApiDelegateImpl : PetsApiDelegate {
    override fun listPets(limit: Int?): ResponseEntity<List<PetDto>> {
        return ResponseEntity(
            listOf(
                PetDto(1L, "Charlie"),
                PetDto(2L, "Obi"),
                PetDto(3L, "Loki"),
            ),
            HttpStatus.OK
        )
    }
}

Verify the API

Great, so we have some generated classes in our target directory based on our OpenAPI specification and we also added some code of our own in src. Let's run this with IntelliJ and see what happens.

We learn that the Spring Boot application is now running on port 8080. But does it actually work?



$ curl -I http://localhost:8080/pets
HTTP/1.1 200 
Content-Type: application/json
Transfer-Encoding: chunked
Date: <redacted my author>

$ curl http://localhost:8080/pets
[{"id":1,"name":"Charlie","tag":null},{"id":2,"name":"Obi","tag":null},{"id":3,"name":"Loki","tag":null}]

Compile your code

We might suspect that this tutorial is finished as we have verified the API's response. However, when we try to compile our code using mvn clean compile we are met with some red text: compilation fails because the generated classes cannot be resolved.

Why does this happen? The problem is that the kotlin-maven-plugin does not see target/generated-sources/openapi as a source directory and so these files are not compiled after cleaning. We resolve this by explicitly adding the path to the plugin's configuration:



<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <configuration>
        <!-- omitted by author -->
    <executions>
        <execution>
            <id>compile</id>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <sourceDirs>
                    <sourceDir>${project.build.directory}/generated-sources/kotlin/src/main/kotlin</sourceDir>
                </sourceDirs>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <!-- omitted by author -->
    </dependencies>
</plugin>

Adding the above execution resolves our issue and Maven now tells us the build is successful.

Great! Now we are done, right? Not exactly. When we go a step further and run our Spring Boot application via mvn spring-boot:run then we are met with another error:

So now what? The issues is caused by our design choice to generate not only the interfaces but also the Controller classes as the generator then also gives us an Application.kt class. As we already also have a main class in our src project, Spring now cannot determine which to pick. There are essentially two ways to fix this. The first option is to delete our own PetStoreApplication.kt and use the generated class. This could be a reasonable choice if you are use that you do not want to do anything custom in the main class. Alternatively, we can configure spring-boot-maven-plugin to point out the correct main class:



<plugins>
    <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
            <mainClass>nl.bjornvanderlaan.petstoreapi.PetstoreApiApplicationKt</mainClass>
        </configuration>
    </plugin>
</plugins>

Regardless of which option you choose, we can run mvn spring-boot:run again and are then at last greeted with our beloved Spring banner and the message that our application can now be found at port 8080!

Conclusion

OpenApi allows us to create a specification for our API that we can share among teams and stakeholders to communicate our contracts. The OpenAPI Generator and its Maven plugin help us to generate code from our specification. We ourselves can then focus on the business logic. In this tutorial, we saw how we can generate a server stud from our specification for Spring Boot-based Kotlin projects.