AI Assisted Coding

This is explicitly not about vibe coding. AI-assisted coding focuses on automating programming tasks and offloading work from the developer. The developer remains in the lead, precisely defining the expected outcome and the way it should be achieved.

Code Completion

A simple form of AI-assisted development is code completion. This goes far beyond the previously established variants of auto-completion limited to individual lines. Because the AI model has access to contextual information about the codebase, it can automatically generate entire blocks of code without difficulty. For repetitive tasks such as writing mapping methods or CRUD operations, this significantly reduces the amount of manual typing required. The more generic the requirement, the better the results tend to be, as large amounts of recurring code are well represented in the training data of AI models.

Implementing well-known algorithms also works very effectively due to the available training data. In many cases, it is sufficient to write a method signature and immediately receive a suitable auto-completion suggestion.

Repetitive tasks

Tasks that recur frequently within a codebase are well suited for AI-assisted development. For example, code for CRUD operations and database access can be generated with little effort. The initial implementation, however, should be done manually. This is where all technical details required for the specific use case are worked out. For subsequent tasks, this implementation can be provided to the LLM as a blueprint that it should follow as a reference.

Prompt: Implement a database repository “RolesRepository” for the entity “userrole”. Use the existing implementation of “UsersRepository” as a reference.

Class and method names can also be explicitly defined in the prompt. The more constraints and guidance you provide to an LLM, the lower the likelihood of hallucinations.

Refactorings

For refactorings that go beyond simple renaming, AI can take over many tasks. With clear instructions on what should be changed and what should remain untouched, and with a well-defined scope, the desired result can be achieved very quickly. A high level of test coverage ensures that functionality is not broken after the refactoring.

Approach

To successfully delegate work to an AI agent, requirements must be clearly formulated. In addition to the functional requirements often captured, for example, in a user story, technical details also need to be described. What may previously have been implicit knowledge shared among everyone involved in a software project now has to be made explicit, written down, and made accessible to the LLM.

Developers therefore need to invest more time in writing tasks in a way that allows them to be meaningfully executed by an AI. Here as well, it is advisable to proceed in very small, incremental steps. User stories are broken down into many small technical tasks with a very limited scope. These tasks can then be handed over to the AI for execution. Breaking work down into small tasks also reduces the blast radius an AI can create when it starts making changes across dozens of files. After the AI has implemented all tasks one by one and written dedicated tests for each task, it can open a pull request. The development team must then review the PRs and ensure the quality of the generated code. The requirement still applies that code must not only be correct, but also maintainable. Going forward, we will continue to read more source code than we write. Perhaps to an even greater extent than today.

In addition to individual tasks, technical and domain-specific information about a software system can be provided to an AI in an AGENTS.md file. This file is implicitly read with every prompt and taken into account when generating responses.

Limits of AI Coding

What does not work are one-shot attempts to implement entire features or even to generate complete systems. Even if such approaches produce results, they are usually far away from the desired outcome, the intended architecture, or even the coding guidelines followed by the team.

In some cases, using an AI is not even a time advantage. In agentic mode, an AI can easily spend an hour on a single task that an experienced developer with sufficient project knowledge could have implemented in just a few minutes. The time required to formulate high-quality prompts should also not be underestimated.

Coding is not the Bottleneck

Writing source code itself is not the limiting factor in software development. Even without AI, the actual coding time of senior developers typically accounts for only 30–40% of their work. For this reason, the use of artificial intelligence is not the silver bullet that some may see in it. However, it does shift developers’ work even further away from coding and more toward planning, preparation and review.

For experienced developers, AI tools can be a valuable way to automate simpler and repetitive tasks. For junior developers, this makes it even more important not to rely solely on prompting and vibe coding, but instead to build the experience and expertise required to develop software effectively with the help of AI.

Another useful tool in the testing toolbox is snapshot testing. Snapshot tests do exactly what the name suggests: they create a snapshot of a test result. This makes it possible to freeze the behavior of a system and protect it against unwanted changes and regressions.

The example code for this blog post is available on Github:

https://github.com/davull/demo-snapshot-testing-in-csharp

The examples shown here use the NuGet package Snapshooter. However, the approach can easily be applied to other libraries as well.

Why Snapshot Testing?

Snapshot tests freeze the behavior of a system at the moment the test is executed. When a snapshot test is run for the first time, the result of the functionality under test is written to a file and then serves as a reference for future test runs. If the result deviates from the content of the reference file, the test is considered to have failed.

The differences can be easily inspected visually in a diff tool, allowing you to quickly decide whether the changes are expected or unexpected. Once you have reviewed the changes and consider them valid, you can accept the updated file as the new reference.

{
  "Date": "2025-12-01",
  "TemperatureC": 18,
--  "TemperatureF": 59,
++  "TemperatureF": 64,
--  "Summary": ""
++  "Summary": "Mild"
}

Another advantage is that you can easily inspect the contents of large data objects visually. If you want to verify multiple properties of a return object, you would traditionally write several Assert statements:

[Test]
public void GetForecast_Should_ReturnCorrectValues()
{
    var tomorrow = new DateOnly(2025, 12, 02);
    const int temperatureC = 18;
    
    var forecast = WeatherForecastProvider.GetForecast(tomorrow , temperatureC);
    
    Assert.That(forecast.Date, Is.EqualTo(tomorrow));
    Assert.That(forecast.Summary, Is.EqualTo("Mild"));
    Assert.That(forecast.TemperatureC, Is.EqualTo(18));
    Assert.That(forecast.TemperatureF, Is.EqualTo(64));
}

In contrast, when using a snapshot test, a single call to MatchSnapshot() allows you to capture all properties of the object at once.

[Test]
public void GetForecast_Should_MatchSnapshot()
{
    var tomorrow = new DateOnly(2025, 12, 02);
    const int temperatureC = 18;
    
    var forecast = WeatherForecastProvider.GetForecast(tomorrow , temperatureC);
    forecast.MatchSnapshot();
}

In the corresponding snapshot file __snapshots__/WeatherForecastProviderTests.GetForecast_Should_MatchSnapshot.snap, you’ll find the JSON representation of the object and can immediately see whether the properties contain the expected values.

{
  "Date": "2025-12-02",
  "TemperatureC": 18,
  "TemperatureF": 64,
  "Summary": "Mild"
}

Snapshot Testing on the backend

In the world of JavaScript frontend frameworks, snapshot testing has been common for quite some time, for example to verify the HTML output of render functions.

But snapshot testing can also be used effectively to verify SSR-based websites or API endpoints.

private readonly CustomWebApplicationFactory _factory = new();

[Test]
public async Task GetWeatherForecast_Should_MatchSnapshot()
{
    var client = _factory.CreateClient();
    var response = await client.GetAsync("/WeatherForecast");
    var content = await response.Content.ReadAsStringAsync();

    content.MatchSnapshot();
}

If an API call is not a pure function, some return values may change independently of the given input. For example, the current date. If you cannot control such values in your test setup, for instance by using the FakeTimeProvider, you can filter them out of the snapshot result.

content.MatchSnapshot(o => o.ExcludeField("$[*].date"));

HTML Snapshots

HTML pages can be tested in the same way. It’s often useful to clean up the HTML output before performing the snapshot comparison so that changes of random values are ignored. This includes things like dynamic IDs, anti-forgery tokens, or automatically generated CSS classes.

public static string PrepareMarkup(string markup)
{
    var replacements = new Dictionary<string, string>
    {
        {
          """
          <input name="__RequestVerificationToken" type="hidden" value="[\d\w-]+" \/>
          """,
          """
          <input name="__RequestVerificationToken" type="hidden" value="<replaced>" />
          """
        },
        {
          @"\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b",
          "00000000-0000-0000-0000-000000000000"
        },
        // ...
    };

    foreach (var (pattern, replacement) in replacements)
    {
        markup = Regex.Replace(markup, pattern, replacement);
    }

    return markup;
}

By creating snapshots of entire web pages at this level, you can reliably detect unwanted changes in the generated output and gain effective regression tests.

Working with legacy code

It’s well known that code without tests is considered legacy code. To work quickly and effectively with a legacy codebase, snapshot tests are an excellent way. They allow you to capture the application’s existing behavior, providing a safety net that makes it possible to modify the codebase while detecting unexpected changes.

For web applications, testing HTTP and API endpoints is straightforward. For desktop applications or native mobile apps, you need to work one layer below the UI. For example, you can create a snapshot of a ViewModel before and after changing the code.

If you have the ability to create repeatable integration tests with external resources such as a database, then the contents of that database can also become the target of a snapshot test.

[Test]
public async Task Table_User_Should_MatchSnapshot()
{
    // Prepare database

    // Do testing operation

    var user = Repository.GetUsers();
    users.MatchSnapshot();
}

How to work with such a task board in an agile project environment in order to deliver not just output but outcome and to avoid falling into mere status reporting is what I’ll demonstrate in this blog post.

Most software teams that work in iterations use some form of task board. These boards consist of several columns representing the current status of a task. In the simplest case, three columns TODO, DOING, and DONE are sufficient. Depending on the project setup, additional columns may appear at the beginning for design and refinement phases. On the other end, columns for testing or approval by the product owner or other stakeholders can be added. Furthermore, it is possible to assign each item on the board to the person currently working on the corresponding task.

Shared Ownership

The entire team is responsible for completing the work items. Therefore, user stories (or bugs or issues) are not assigned to individual people. At the beginning of an iteration, the team commits to a workload it believes it can handle. When a new work item is started, it is broken down into concrete tasks that need to be completed. During implementation, additional tasks may be added as it becomes clear that further work is required. These sub-tasks are then handled by individual team members and assigned to them on the board. In this way, multiple people can work on the same user story in parallel, allowing the team to keep track of which tasks are in progress and how many people are involved in each.

This means that everyone on the team is responsible for completing the currently active work items. Throughout the entire process, there are no “my” or “your” stories. Once someone has finished their current task, they can join another story already in progress. Only when no further parallel work is reasonably possible does the team begin implementing a new story.

Prioritize

How do I decide which task to tackle next? Because of the shared ownership of the entire iteration scope, I don’t have “my own” stories to work through. To avoid starting the next story at random, it’s important to prioritize the work currently represented on the board. Stories located further to the right side on the board are more important than those on the left. They always have a higher priority. If a story is in the TESTING column, I pick it up and test it. Instead of having a dedicated TESTING column, you can also simply create a sub-task for testing on the board. If a story is in the DOING column, I contribute to that story. Only when there are no more stories remaining on the right side of the board and no parallel work on active stories is possible does the team begin working on a new task.

In the Kanban framework, this concept is known as the Work in Progress (WIP) Limit.

The reasoning behind this approach is simple: user stories that are not finished — that is, not in the DONE status — provide no value to the product. One completed story is more valuable than five that are only partially done. After all, “almost finished” is not “finished”.

Stop Starting, Start Finishing

Walk the Board

As we’ve seen above, we walk through our task board from the right to the left and the same principle applies to our daily sync meetings with the product owner. We go through the board from right to left, clarifying which items have been completed and can be accepted. It’s sufficient for one person to guide the discussion through the board; there’s no need for everyone to report on their individual activities. The purpose is not to justify how one spent the previous workday or to showcase progress on a personal story. When issues arise, the team discusses them collectively to find a solution.

By following this approach, teams can maintain focus even in stressful situations and ensure the continuous improvement and evolution of the product.

Since I personally enjoy using Mastodon as a news source and aggregator for various blogs, I developed an application that automatically publishes RSS feeds in the Fediverse.

The source code and instructions for use are available on GitHub: https://github.com/davull/FeedToMastodon

A running instance of the application publishes posts from several news feeds on https://feedmirror.social

Feed To Mastodon

Feed To Mastodon is a .NET application that automatically posts new feed entries to Mastodon. It supports RSS, Atom and RDF feeds. The application can be compiled and run locally or used as a pre-configured Docker image.

The application can handle any number of feeds. A separate Mastodon account can be used for each feed.

To prevent the respective Mastodon account from being flooded with old feed entries, previous entries are skipped during the first synchronization of a new feed, and only new entries are published.

Configuration

The configuration of the feeds to be monitored is done in a .ini file.

[heise.de]
feed_url = https://www.heise.de/rss/heise-atom.xml
summary_separator = [...]
mastodon_server = https://mastodon.social/
mastodon_access_token = AWWHkaIB_...

[wired.com]
feed_url = https://www.wired.com/feed/rss
mastodon_server =  https://mastodon.social/
mastodon_access_token = ABC...

...

In addition to the URLs for the feed and the Mastodon server where the target account is registered, an access token is required.

The summary_separator parameter is optional and can be specified to shorten feed entries. The entry will be truncated at the first occurrence of the separator.

For example, if a post contains […], the entry can be shortened here:

Earlier today, we reported that […]
To the post <a rel="nofollow" ...>http://news.com/123</a>

Configuring summary_separator = […] results in the shortened entry:

Earlier today, we reported that ...

Posted entries are stored in an SQLite database to prevent duplicate posts.

Mastodon access token

An access token can be generated via the Mastodon website under Preferences -> Development -> New application. In the Name field, you can enter any text, such as Feed to Mastodon. For the Redirect URI, the default value urn:ietf:wg:oauth:2.0:oob can be kept. Under Scopes, only write:statuses needs to be selected, and profile can be deselected.

After saving, you can click on the newly created application again and copy the access token under Your access token.

Parameters

The file paths for the configuration and database files are stored as environment variables.

Run Feed to Mastodon

To run Feed to Mastodon via Docker, run the following command:

docker run -it --rm \
  -v "${PWD}/ftm-feed-config.ini:/app/ftm-feed-config.ini" \
  -v "${PWD}/ftm.sqlite:/app/ftm.sqlite" \
  -e "FTM_CONFIG_FILE_NAME=/app/ftm-feed-config.ini" \
  -e "FTM_DATABASE_NAME=/app/ftm.sqlite" \
  davidullrich/feed-to-mastodon:latest

A Docker Compose configuration looks like this:

services:
  ftm:
    container_name: feed-to-mastodon
    image: davidullrich/feed-to-mastodon:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    environment:
      - FTM_DATABASE_NAME=/app/data/ftm.sqlite
      - FTM_CONFIG_FILE_NAME=/app/data/ftm.ini
      - TZ=Europe/Berlin

Statistics

For those interested, Feed to Mastodon outputs a daily statistic on the console. This shows the number of feeds posted in the last 24 hours and the last seven days.

Statistics[0] ============================================================
Statistics[0] Total Posts per feed:    2024-11-18 00:00 - 2024-11-25 00:00
Statistics[0] ============================================================
Statistics[0]   Mashable:                                              215
Statistics[0]   Caschys Blog:                                          183
Statistics[0]   Digital Trends:                                        299
Statistics[0]   Elektroauto-News.net:                                    8
Statistics[0]   TESLARATI:                                              48
Statistics[0]   WIRED:                                                 102
Statistics[0] ------------------------------------------------------------
Statistics[0] Total:                                                   855
Statistics[0] ============================================================

Live example

At https://feedmirror.social, Feed to Mastodon is running with a few configured feeds, bringing the latest articles into the Fediverse.

If you prefer not to manage Docker containers within the test code, it is advisable to start and stop the containers independently of the test execution. Docker Compose and the Azure DevOps feature Service Containers are good alternatives for this.

The example code for this blog post is available on Github: https://github.com/davull/demo-docker-compose-test

Docker Compose

Docker Compose allows the definition and management of multiple Docker containers in a single file. These can then be started and stopped with just one command. Additionally, it enables the definition of networks between containers, the creation of storage volumes, and the setting of environment variables. For the demo application used here, I utilize a MariaDB database and a phpMyAdmin container. A simplified version of the Docker Compose file looks like this (the full configuration can be found in the Github repository):

name: "orderapp"

services:
  order-mariadb:
    image: mariadb:11.3
    container_name: order-mariadb
    volumes:
      - order-mariadb:/var/lib/mysql
    networks:
      - order-net
    environment:
      MYSQL_ROOT_PASSWORD: "some-password"
      MYSQL_DATABASE: "orders"

  order-pma:
    image: phpmyadmin
    container_name: order-pma
    ports:
      - "9002:80"
    networks:
      - order-net

networks:
  order-net:

volumes:
  order-mariadb:

Using docker compose up and docker compose down, you can start and stop all containers respectively.

If you want to use a MariaDB container for the integration tests of your application, there are a few things to consider. You need to initialize the database and populate it with appropriate test data. This can be done using a Shared Context within your test suite for xUnit, for instance, performing a Seeding of the database before each test run. After the test run, the database is simply deleted.

public class DatabaseFixture : IAsyncLifetime
{
    private string _databaseName;
    
    public async Task InitializeAsync()
    {
        _databaseName = GetRandomTestDatabaseName();
        await Database.Seed(_databaseName);
    }

    public async Task DisposeAsync()
      => await Database.DeleteDatabase(_databaseName);
}

Alternatively, you can utilize a feature of the MariaDB container that allows the execution of arbitrary SQL scripts when the container starts. To do this, you mount a folder into the container at /docker-entrypoint-initdb.d. All SQL files in this folder will be executed when the container starts.

services:
  order-mariadb:
    image: mariadb:11.3
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d

Besides the initial filling of the database, it is necessary to be able to determine after the start of the container whether the database server is ready to receive requests. This is crucial for running integration tests in a CI/CD pipeline to ensure that the tests are only executed when the container is fully operational. For Docker containers, the option of healthchecks is suitable. MariaDB already includes an appropriate healthcheck.sh script for this purpose.

services:
  order-mariadb:
    image: mariadb:11.3
    healthcheck:
      interval: 3s
      retries: 3
      test:
        [
          "CMD",
          "healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized",
        ]
      timeout: 30s

Docker Compose in a Azure Pipeline

With the previously created Docker Compose file, you can run the integration tests locally and also in an Azure DevOps CI/CD pipeline. First, we start our containers using the DockerCompose@0 task:

- task: DockerCompose@0
  displayName: "Docker compose up"
  inputs:
    containerregistrytype: Container Registry
    dockerComposeFile: "./docker/docker-compose.yml"
    action: Run a Docker Compose command
    dockerComposeCommand: "up -d"
    projectName: "orderapp"

After starting the containers, you need to wait for the database container to be ready for operation using a healthcheck.

If you are running your Azure pipeline in a Container Job, you must connect the database container to the network of the pipeline container. The environment variable $(Agent.ContainerNetwork) contains the name of the network in which the pipeline container is running.

- task: CmdLine@2
  displayName: "Prepair containers"
  inputs:
    workingDirectory: "./docker"
    script: |
      echo -e "Connect database to network $(Agent.ContainerNetwork) ...\n"
      docker network connect $(Agent.ContainerNetwork) order-mariadb
      
      echo -e "Waiting for container to be healthy ...\n"
      until [ "$(docker inspect -f '{{.State.Health.Status}}' order-mariadb)" == "healthy" ]; do
        sleep 1
      done

Afterwards, the tests can be run. Since the configuration of the database connection in the CI pipeline is different from that on a local PC or in a production environment, you can set it accordingly using a .runsettings file. This file allows you to specify different settings for different environments, ensuring that your tests can connect to the correct database instance depending on where they are being run.

<RunSettings>
  <RunConfiguration>
      <EnvironmentVariables>
          <DB_SERVER>order-mariadb</DB_SERVER>
          <DB_PORT>3306</DB_PORT>
          <DB_NAME>orders</DB_NAME>
          <DB_USER>root</DB_USER>
          <DB_PASSWORD>some-password</DB_PASSWORD>
      </EnvironmentVariables>
  </RunConfiguration>
</RunSettings>

In the DotNetCoreCLI@2 task, you specify the file as an argument. This can be done by including the --settings option followed by the path to your .runsettings file, allowing the .NET Core CLI to apply the specified configurations during the test run.

- task: DotNetCoreCLI@2
  displayName: "Dotnet test"
  inputs:
    command: test
    arguments: "--settings ./src/ci-tests.runsettings"

After the test run, the containers are stopped again.

- task: DockerCompose@0
  displayName: "Docker compose down"
  condition: always()
  inputs:
    containerregistrytype: Container Registry
    dockerComposeFile: "./docker/docker-compose.yml"
    currentWorkingDirectory: "./docker"
    action: Run a Docker Compose command
    dockerComposeCommand: "down -v"
    projectName: "orderapp"

Azure DevOps service containers

As an alternative to setting up and starting Docker containers using the Docker@2 or DockerCompose@0 task, Microsoft offers the option to deploy container resources as Service Containers within a pipeline. These containers run parallel to the build and test jobs and can be accessed by them. Therefore, Service Containers are also suitable for providing resources such as databases for integration tests.

The configuration of Service Containers is done directly in the .yaml file of the pipeline definition; the feature is not available for classic Azure Pipelines. The syntax is very similar to that of Docker Compose, so those familiar with it will find it easy to adapt.

Containers are defined under the resources section and then exposed under services (container resources can also be used for Container Jobs).

resources:
  containers:
    - container: order-mariadb
      image: mariadb:11.3
      ports:
        - 3306:3306
      env:
        MYSQL_ROOT_PASSWORD: "some-password"
        MYSQL_DATABASE: "orders"

services:
  order-mariadb: order-mariadb

With this setup, the MariaDB server can be accessed at localhost:3306.

If you are not using Docker containers for local development that can reuse configurations for integration tests within the CI pipeline, Service Containers offer a simple way to provide the necessary resources.

To ensure that external systems are reproducibly and predictably available in integration tests, they can be run in Docker containers. A simple setup of such service containers is enabled by the library Testcontainers.

The example code for this blog post is available on GitHub: https://github.com/davull/demo-docker-testcontainers

In a subsequent blog post, I will show how to implement integration tests using Docker Compose and Azure Service Containers.

Integration Tests

Integration tests are designed to examine the interaction of multiple components of a software system. This can involve individual functional units but also a complete pass-through of the application. For example, for a web API, one might send an HTTP request to the application, manipulate data in a database, and then return the result stored in a Redis cache back to the client.

While the behavior of external systems can be emulated using mocks, integration tests truly add value when they interact with real systems. This moves us closer to a production environment, allowing for the discovery of problems that would not be visible with mocks.

Most systems can now be operated in a Docker container. If a pre-configured image is not available, it is usually straightforward to create one’s own.

This containerization of applications can be utilized in testing to start the required systems in a defined state before each test run, such as in a CI/CD pipeline. After the tests are executed, the containers are simply stopped and deleted.

Testcontainers

The Testcontainers project provides libraries for many programming languages to simplify the setup and execution of Docker containers in tests. For .NET, there is a corresponding NuGet package available: Testcontainers for .NET.

A Testcontainer is simply defined before executing the test methods, started, and then stopped and deleted afterwards. The ContainerBuilder class offers a Fluent API to configure the containers.

var container = new ContainerBuilder()
    .WithImage("mariadb:11.3")
    .WithHostname("mariadb-test-container")
    .Build();

await container.StartAsync();

// run integration tests

await container.StopAsync();

To be able to run the tests locally, Docker must be installed on the computer and the Docker service must be running.

Best practice is to map container ports to random host ports to avoid conflicts with other running services and containers.

var containerBuilder = new ContainerBuilder()
    .WithPortBinding(3306, assignRandomHostPort: true);

var port = container.GetMappedPublicPort(3306);

To wait for the availability of a service within the container after startup, Testcontainers provides a variety of Wait strategies. For example, you can wait for the container’s health status or check the availability of any TCP port. Waiting for an HTTP endpoint is also possible.

// Wait for MySQL to be ready
var containerBuilder = new ContainerBuilder()
    .WithImage("mariadb:11.3")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilPortIsAvailable(3306));

// Wait for HTTP service to be ready
var containerBuilder = new ContainerBuilder()
    .WithImage("productservice:latest")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilHttpRequestIsSucceeded(strategy => strategy
            .ForPort(443)
            .ForPath("/api/products")
            .WithBasicAuthentication("user", "password")));

Many container images can be configured via environment variables. These can easily be passed to a Testcontainer using the WithEnvironment(env) method.

var env = new Dictionary<string, string>
{
    { "MYSQL_ROOT_PASSWORD", "some-password" },
    { "MYSQL_DATABASE", "products" }
};

var containerBuilder = new ContainerBuilder()
    .WithEnvironment(env);

Pre-configured Containers

Testcontainers offers a range of pre-configured containers that simplify the use of various services. This eliminates the need for specifying the image or port mapping. A MySqlContainer provides the option to directly obtain the appropriate connection string for the database.

var container = new MySqlBuilder().Build();
var connectionString = container.GetConnectionString();

Test Fixtures

To centralize the configuration of Testcontainers and not generate and start a new container for each test method call, one can use the capabilities of various testing frameworks to create so-called test fixtures.

For xUnit, you can create a class called DatabaseFixture that handles initializing and starting the container. A class that implements the ICollectionFixture<DatabaseFixture> interface can then control which tests share a container instance.

public class DatabaseFixture : IAsyncLifetime
{
    public async Task InitializeAsync()
    {
        _container = BuildContainer();
        await _container.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await _container.StopAsync();
    }

    // ...
}

[CollectionDefinition(Name)]
public class DatabaseCollectionFixture : ICollectionFixture<DatabaseFixture>
{
    public const string Name = "DatabaseCollection";
}

The corresponding tests are annotated with the Collection attribute and the collection name that provides the fixture container.

[Collection(DatabaseCollectionFixture.Name)]
public class DatabaseTests
{
    // ...
}

The project in the GitHub repository for this post shows a complete example: https://github.com/davull/demo-docker-testcontainers

CI/CD Pipeline

Testcontainers can be run in a CI/CD pipeline in the same way as locally. The only requirement is that Docker and the Docker CLI are also installed on the build server. In the case of Azure DevOps, this is already the case for Microsoft-hosted build agents. If you are using your own build containers, the Docker CLI can be installed via the task DockerInstaller@0.

- task: DockerInstaller@0
  displayName: "Install docker cli"
  inputs:
    dockerVersion: 26.1.0

When executing the test step, the required images are downloaded, if not already present, and the containers are started.

A lightweight method for documenting architectural decisions is through Architectural Decision Records, ADRs.

Architecture Documentation

Every piece of software also has a software architecture. Whether it is actively designed or “emerges” during development depends on the circumstances and requirements. To be able to comprehend and potentially evaluate decisions made on the way to the current state of the software retrospectively, architecture documentation, or at least documentation of the most important decisions, is advisable. Such decisions are often recorded in a wiki, Confluence, or Word document. The documentation thus occurs outside the actual source code and in an unstructured manner, making maintenance and updates challenging.

With arc42 or Structurizr, frameworks exist to systematically document various aspects of software and its architecture. For projects that do not require such extensive documentation, ADRs offer a lightweight solution.

Architectural Decision Records

The goal of Architectural Decision Records is not to describe or reflect the entire architecture of software but to document decisions that have led to the current architecture.

ADRs record architectural decisions in plain text files and prescribe only the format. Each decision gets its own file and a consecutive number. Markdown is used for simple formatting. The files are part of the source code repository, thus being subject to version control. ADRs can be introduced and discussed through pull requests.

Even though the name sets the context to Architecture, ADRs can be utilized for a variety of technical and non-technical decision documentation.

Format

According to the inventor Michael Nygard, ADRs consist of the following fields:

Title: Brief description of the decision.

Context: Description of the context in which the decision was made, including technological, political, or social conditions. The wording is neutral and describes the factual circumstances.

Decision: Describes the decision made in the previously outlined context. The wording is active and describes what will be done: “We will…”.

Status: The status of the decision. Possible values are proposed, accepted, deprecated, or superseded.

Consequences: Describes the resulting state after the decision. Both positive and negative consequences are listed.

Such an ADR document has a length of one to two pages. It represents communication with future developers or ourselves. Therefore, it is important that the documentation is clear, comprehensible, and not just a bullet-point list. For the file name, Nygard suggests a format: doc/arch/adr-NNN.md. Through the unique identifier, individual ADRs can be referenced, such as when later decisions build upon or replace a previous one.

Whether you follow the format shown here or develop your own variation for your project is secondary. What matters is that the format is consistently adhered to throughout the project. Joel Parker Henderson has compiled a series of ADR templates in a GitHub repository.

Example

The ADR for the decision to use RabbitMQ as a message broker might look like the following:

# ADR-039: RabbitMQ Message Broker

## Context

We need a message broker to exchange asynchronous messages
between the individual components of our application. The
solution should be able to operate in a fault-tolerant manner
and persistently store messages. The solution should be hosted
in our own data center and operated by our service team.
RabbitMQ is already in use in other projects, and the service
team is familiar with its operation.

## Decision

We will be using RabbitMQ as the message broker. RabbitMQ
meets our requirements and is already established within the
company. The responsibility for operation will be assigned
to the service team. We will communicate the expected message
volume to the service team.

## Status

accepted

## Consequences

Due to the decision, knowledge for the use of RabbitMQ needs
to be developed within the software team. The service team
will support the software team in the integration process.
The intended use of asynchronous messages between the components
of the application can be implemented.

With such a document, it is also possible to understand retrospectively why RabbitMQ was chosen instead of, for example, Azure Service Bus.

Tools

As ADRs (Architectural Decision Records) represent a structured form of documentation, a variety of tools have been established for their implementation.

adr-tools

Nat Pryce has developed adr-tools, a command-line tool for working with ADRs. This tool allows for the creation of new ADRs in the format described by Michael Nygard.

$ adr init doc/adrs
doc/adrs/0001-record-architecture-decisions.md

$ cat doc/adrs/0001-record-architecture-decisions.md

# 1. Record architecture decisions

Date: 2023-12-28

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as [described by Michael Nygard]
(http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset,
see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

New ADRs can be created using the command adr new.

$ adr new Write Blog Post about ADRs
doc/adrs/0002-write-blog-post-about-adrs.md

Additional commands allow for linking ADRs, listing them, and generating table of contents for ADRs.

$ adr generate toc
# Architecture Decision Records

* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Write Blog Post about ADRs](0002-write-blog-post-about-adrs.md)

adr-viewer

adr-viewer generates an HTML page from ADR files. This allows you to integrate ADRs into your CI/CD pipeline and automatically update the documentation.

$ pip install adr-viewer

$ adr-viewer --adr-path doc/adrs --output doc/adrs.html

The generated page provides an overview of all ADRs and allows navigation between individual documents. Different statuses are highlighted with distinct colors, offering a visual indication.

Even when refactoring existing code, such architecture tests can prove to be meaningful.

With ArchUnitNET, architecture rules can be defined as code and tested automatically.

ArchUnitNET

ArchUnitNET is a .NET port of the well-established Java library ArchUnit. With ArchUnitNET, it is possible to define architecture rules as unit tests and continuously and automatically verify them. The rules are written in C# code and can be executed in any testing framework. To use ArchUnitNET, it is sufficient to add the corresponding NuGet package to your project. For easy integration with different test frameworks, packages are available for xUnit, NUnit, and MS-Test.

Architecture Rules

ArchUnitNET tests are structured similarly to other unit tests. There is a test class with a series of test methods. For better performance, one can create a static class property with the definition of the architecture.

To achieve this, you make the ArchLoader aware of a series of assemblies that contain the code related to your architecture. Marker classes, for example, can be used for this purpose. However, the ArchLoader also has a variety of other methods, such as loading assemblies from a directory.

private static readonly Assembly DataModuleAssembly = 
    typeof(DataModuleMarker).Assembly;
private static readonly Assembly BusinessModuleAssembly = 
    typeof(BusinessModuleMarker).Assembly;
private static readonly Assembly DesktopModuleAssembly = 
    typeof(DesktopModuleMarker).Assembly;

private static readonly Architecture Architecture = new ArchLoader()
    .LoadAssemblies(DataModuleAssembly, BusinessModuleAssembly, DesktopModuleAssembly)
    .Build();

Within the architecture, sets of classes, interfaces, or methods can be formed, for example, to group classes into layers. If you use a consistent naming scheme, you can also filter by name patterns and, for instance, aggregate all repository classes together.

The user-friendly Fluent API of ArchUnitNET helps defining these sets.

private readonly IObjectProvider<IType> DataLayer =
    Types().That().ResideInAssembly(DataModuleAssembly).As("Data layer");

private readonly IObjectProvider<IType> BusinessLayer =
    Types().That().ResideInAssembly(BusinessModuleAssembly).As("Business layer");

private readonly IObjectProvider<Class> RepositoryClasses =
    Classes().That().HaveNameEndingWith("Repository").As("Repository classes");

To test whether all repository classes are indeed located in the data layer, we write a test that defines a corresponding rule and checks our architecture against it. For ease of use, you can include ArchRuleDefinition as a static using.

using static ArchUnitNET.Fluent.ArchRuleDefinition;

[Fact]
public void RepositoryClassesShouldBeInDataLayer()
{
    var rule = Classes().That().Are(RepositoryClasses).Should().Be(DataLayer);
    rule.Check(Architecture);
}

Checking for intentional or unintentional dependencies between modules also requires only a few lines of code. The following test verifies whether any type from the desktop layer accesses a type from the data layer.

[Fact]
public void DesktopLayerShouldNotReferenceDataLayer()
{
    var rule = Types().That().Are(DesktopLayer).Should().NotDependOnAny(DataLayer);
    rule.Check(Architecture);
}

If ArchUnitNET detects a violation of our rules, the test fails and provides an appropriate error message.

FailedArchRuleException
"Types that are Desktop layer should not depend on Data layer" failed:
    DesktopModule.ViewModels.ProductListViewModel does depend on
    DataModule.ProductRepository

Preventing Code Usage

Not only can the organization of source code be enforced in this way, but the usage of specific classes or methods can also be regulated. To ensure that only the Data Layer has access to a database, we restrict access to classes from the Microsoft.Data.SqlClient assembly, which includes the SqlConnection class, among others. Access to the database classes is only allowed from our own assemblies (ProjectAssemblies), specifically from within the DataLayer. To make ArchUnitNET aware of the Microsoft.Data.SqlClient assembly, we need to explicitly include it in our architecture definition.

private static readonly Assembly[] ProjectAssemblies = {
    DataModuleAssembly,
    BusinessModuleAssembly,
    DesktopModuleAssembly
};

private static readonly Assembly SystemDataAssembly =
    typeof(SqlConnection).Assembly;

private static readonly Architecture Architecture = new ArchLoader()
    .LoadAssemblies(/* ... */ SystemDataAssembly)
    .Build();

[Fact]
public void OnlyDataLayerShouldUseDatabase()
{
    var types = Types()
        .That().ResideInAssembly(ProjectAssemblies[0], ProjectAssemblies[1..])
        .And()
        .AreNot(DataLayer);
    var typesNotToUse = Types().That().ResideInAssembly(SystemDataAssembly);

    var rule = types.Should().NotDependOnAny(typesNotToUse);
    rule.Check(Architecture);
}

Architecture Refactoring

When dealing with an existing codebase and intending to make changes to it, ArchUnitNET allows you to define the desired target state before implementing the corresponding changes. Subsequently, you have the option to gradually transform the existing architecture in the desired direction. At the beginning of the refactoring process, the tests that are still red indicate the areas that need attention. Rules that haven’t been implemented yet can be skipped for the time being. Once all tests are reactivated and green, the refactoring is complete.

[Fact(Skip = "Refactoring of DesktopLayer will be done in the next iteration")]
public void DesktopLayerShouldNotReferenceDataLayer()
{
    var rule = Types().That().Are(DesktopLayer).Should().NotDependOnAny(DataLayer);
    rule.Check(Architecture);
}

Finding System Resources

The use of non-deterministic system resources such as the current time can make writing tests challenging. If you don’t want to refactor directly towards Pure Functions, it can be helpful to use an abstraction like the TimeProvider introduced since .NET 8.

Here, too, a test can help us find all accesses to DateTime.Now or DateTime.UtcNow.

[Fact]
public void DateTimeNowShouldNotBeUsedInBusinessLayer()
{
    var types = Types().That().Are(BusinessLayer);

    var methodsNotToCall = MethodMembers()
        .That().AreDeclaredIn(typeof(DateTime))
        .And().AreStatic()
        .And().HaveNameEndingWith("get_UtcNow()")
        .Or().HaveNameEndingWith("get_Now()");

    var rule = types.Should().NotCallAny(methodsNotToCall);
    rule.Check(Architecture);
}

A failing test will once again indicate to us where we need to make adjustments in this case.

"Types that are Business layer should not call Method members that are declared
in "System.DateTime" and are static and have name ending with "get_UtcNow()"" failed:
    BusinessModule.ProductService does call System.DateTime
    System.DateTime::get_UtcNow()

Kudos to Andreas Lausen for his sample code from SEACON 2023.

Conclusion

ArchUnitNET provides a powerful way to define architecture and code usage rules in the form of unit tests and to automatically and continuously verify them. After a short learning curve, writing new rules becomes straightforward. Since these architecture rules behave like any other unit test, they can also be integrated into existing codebases. The best practice is, of course, to define and use them as early as possible.

The example code for this post can be found on GitHub: https://github.com/davull/demo-archunit

As it is also available as a ready-made Docker image, you can easily deploy it as an Azure App Service. For rolling it out using Terraform, a simple configuration is sufficient.

The Terraform code for this post can be found on Github: https://github.com/davull/uptime-kuma-azure-app-service

Azure App Service

To run a Docker container in Azure as a Web App for Container, we need an App Service that resides in an App Service Plan. Alternatively, containers can also be run in Azure Container App or Azure Kubernetes Service, an overview is provided by Microsoft here.

To ensure that the data collected by Uptime Kuma (an SQLite database) is not lost with each container restart, we persist it in a Storage Account.

Resource Group

To organize resources in Azure, we create a new Resource Group. To do this, we search for Resource Group in the Azure Marketplace and click Create.

We assign a name, choose a region, and click Review + Create. Afterward, we can create our services within the Resource Group.

Storage Account

When creating the Storage Account, we select the created Resource Group, set the name, region, and redundancy level. For non-critical applications, the most cost-effective option is typically Local-redundant storage (LRS). The remaining settings can be kept as default.

Once our Storage Account is provisioned, we can create a File share. For the tier, we choose Hot, and the backup option can be enabled or disabled based on our needs.

App Service Plan und Web App for Container

To create an App Service Plan, we follow a similar process. As the Operation System, we choose Linux, and the smallest non-free pricing plan Basic B1 is sufficient. This plan costs approximately €13 per month and provides 1.75 GB of memory and 1 vCPU. Depending on the number of services to be monitored, it might be advisable to choose a larger plan. However, scaling up can also be done at any time later.

Now that an App Service Plan and Storage are available, we can create the actual App Service. To start the wizard, we search for Web App for Containers or Web App in the Azure Portal. Although they are listed separately in the Marketplace, they represent the same service.

As the Publish method, we choose Docker, and for the Operating System, we select Linux. The name chosen here will also be the subdomain under which the service will be accessible later (<name>.azurewebsites.net).

In the next tab, Docker, we switch the Image Source to Docker Hub and enter the desired image with the tag, for example, louislam/uptime-kuma:latest.

After completing the wizard, Azure pulls the Docker image from the Hub and starts our container. During the first launch of Uptime Kuma, it takes some time for the service to be up and running and the website to be accessible. You can track the process under the Deployment Center entry in the Logs tab.

Mount Azure File Share

To ensure that the Uptime Kuma database is not lost with each container restart, we mount the previously created File Share into the container. To do this, select the Configuration section and go to the Path mappings tab. Add a new entry, choosing the previously created Storage Account and the Storage Container created for the File Share. Select Azure File as the Storage Type. The path under which the File Share is mounted in the container should be /app/data. This is where Uptime Kuma stores its application data. After saving, the container will be restarted, and the data will now be stored in our Storage Container.

When we now access the website of the Web App, Uptime Kuma greets us with the setup dialog, where we can create the admin user.

Terraform

As an alternative to the Azure Portal, managing the configuration of our application in a true Infrastructure as Code manner using Terraform is a great option. For this, we can utilize the azurerm Provider. The various authentication methods are described in the documentation. We create the same resources as we did in the portal using Terraform.

The configuration file looks like this:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.79"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "rg_kuma" {
  name     = var.resource_group_name
  location = var.location
}

resource "azurerm_storage_account" "sa_kuma" {
  name                     = var.storage_account_name
  resource_group_name      = azurerm_resource_group.rg_kuma.name
  location                 = azurerm_resource_group.rg_kuma.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
  min_tls_version          = "TLS1_2"
}

resource "azurerm_storage_share" "share_kuma" {
  name                 = "kumashare"
  storage_account_name = azurerm_storage_account.sa_kuma.name
  quota                = var.storage_quota
  access_tier          = "Hot"
}

resource "azurerm_service_plan" "service_plan_kuma" {
  name                = "service-plan-kuma"
  resource_group_name = azurerm_resource_group.rg_kuma.name
  location            = azurerm_resource_group.rg_kuma.location
  os_type             = "Linux"
  sku_name            = var.service_plan_sku
}

resource "azurerm_linux_web_app" "web_app_kuma" {
  name                = var.web_app_name
  resource_group_name = azurerm_resource_group.rg_kuma.name
  location            = azurerm_resource_group.rg_kuma.location
  service_plan_id     = azurerm_service_plan.service_plan_kuma.id
  https_only          = true

  site_config {
    http2_enabled       = true
    minimum_tls_version = "1.2"

    application_stack {
      docker_image_name   = var.docker_image
      docker_registry_url = "https://index.docker.io"
    }
  }

  app_settings = {
    "DOCKER_ENABLE_CI" = "true"
  }

  storage_account {
    access_key   = azurerm_storage_account.sa_kuma.primary_access_key
    account_name = azurerm_storage_account.sa_kuma.name
    name         = "webappstorage"
    type         = "AzureFiles"
    share_name   = azurerm_storage_share.share_kuma.name
    mount_path   = "/app/data"
  }
}

The variables are defined in a separate file.

variable "resource_group_name" {
  type = string
}

variable "storage_account_name" {
  type = string
}

variable "web_app_name" {
  type = string
}

variable "location" {
  type    = string
  default = "westeurope"
}

variable "storage_quota" {
  type    = number
  default = 50
}

variable "service_plan_sku" {
  type    = string
  default = "B1"
}

variable "docker_image" {
  type    = string
  default = "louislam/uptime-kuma:latest"
}

In a .tfvar file, the values for the variables are set.

resource_group_name  = "rg-kuma"
storage_account_name = "<your-storage-account-name>"
web_app_name         = "<your-web-app-name>"

Now, with a single command, we can create the entire environment and also delete it when needed.

terraform apply -var-file="terraform.tfvar"
terraform destroy -var-file="terraform.tfvar"

The following article will demonstrate how to transition from a codebase with many such indirections to a simpler version that removes a lot of unnecessary complexity.

Initial Situation

As a starting point for our refactoring, let’s consider a fictional example of an online shop. The source code is available on GitHub, and there’s a separate branch in the repository for each refactoring step.

Source code on GitHub, Branch steps/01-initial-state

The application consists of an application project and a project for associated tests. The structure doesn’t strictly adhere to an architectural style but is meant to illustrate the components you might expect in such a system. Additionally, we will focus on the backend side of our online shop here. The folder structure looks like this:

├───Refactor.Application
│   ├───Controllers
│   ├───CQRS
│   │   ├───Handlers
│   │   └───Requests
│   ├───Data
│   ├───Models
│   ├───Repositories
│   │   ├───Implementations
│   │   └───Interfaces
│   └───Services
└───Refactor.Application.Test
    ├───Controllers
    ├───CQRS
    │   └───Handlers
    ├───Repositories
    └───Services

The application is written in C# and uses ASP.NET controllers. Business logic is implemented in service classes, and domain models are located in the Models folder. Database access is done through the Repository pattern, and the POCO classes for the database are placed in the Data folder. For communication between controllers and services, the CQRS (Command Query Responsibility Segregation) pattern is employed.

All these individual components are managed and wired together using Dependency Injection.

Abstraction

In software development, abstraction is a commonly used concept. However, it often falls short of its primary goal, which is to reduce complexity and maintenance efforts. Additionally, abstraction layers are frequently introduced without providing concrete benefits but rather because “that’s how things are done.” This not only impacts code readability but also makes it challenging to understand the runtime behavior without a detailed analysis of dependencies. While the abstractions in our example might appear artificially enforced for a small demo, they are indeed encountered in real projects from time to time.

Base Classes and Marker Interfaces

All our model classes inherit from an abstract base class or record called ModelBase, which doesn’t provide any implementation. The database POCOs implement an interface called IData, which at least defines a property Id.

// ./Models
public abstract record ModelBase;

public record Customer(
    Guid Id,
    string FirstName,
    string LastName,
    string Email) : ModelBase;

// ./Data
public interface IData
{
    Guid Id { get; }
}

public record Customer(
    Guid Id,
    string FirstName,
    string LastName,
    string Email,
    bool Active) : IData;

Repository Interfaces

In the Repositories folder, you can find both a generic interface IRepository<T> and specific interfaces for each database table or POCO class, such as ICustomerRepository. Additionally, there’s an abstract base class called AbstractRepository<T>, which simply implements the methods of the generic interface one-to-one.

public interface IRepository<T> where T : IData
{
    T Get(Guid id);
    IEnumerable<T> GetAll();
    void Add(T entity);
    ...
}

public abstract class AbstractRepository<T> : IRepository<T> where T : IData
{
    protected readonly IDatabase _database;

    protected AbstractRepository(IDatabase database) => _database = database;

    public abstract T Get(Guid id);
    public abstract IEnumerable<T> GetAll();
    public abstract void Add(T entity);
    ...
}

Abstracting the concrete database access through an interface like IDatabase can be meaningful, as it allows you to replace external systems like a database with a mock object during testing. However, we will find a different solution to this problem as we proceed.

In most cases, the concrete implementations of the repositories typically consist of forwarding calls to the base class or an IDatabase object.

public class CustomerRepository : AbstractRepository<Customer>, ICustomerRepository
{
    public CustomerRepository(IDatabase database) : base(database) { }

    public override void Add(Customer entity) => _database.Add(entity);
    public override void Update(Customer entity) => _database.Update(entity);
    ...
}

Services and CQRS

All our services are defined as interfaces with precisely one implementation; there is no need for multiple implementations or runtime swapping.

The example of ITaxService illustrates the frequent use of interfaces. The interface defines only a single method, which has no dependencies apart from its direct method parameters.

public interface ITaxService
{
    (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate);
}

public class TaxService : ITaxService
{
    public (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate)
    {
        var taxAmount = netPrice * taxRate / 100m;
        var grossPrice = netPrice + taxAmount;

        return (taxAmount, grossPrice);
    }
}

Tests

Now, what does a (unit) test for such code look like? Testing the GetOrderItems() method of the OrderItemService illustrates how much setup code is already required to mock dependencies and feed them with data. In the case of the ITaxService interface, even the business logic is implemented in the mock object.

[Test]
public void Should_Return_OrderItems()
{
    // Arrange
    var orderId = Guid.NewGuid();

    var orderItem1 = new OrderItem(Guid.NewGuid(),
        orderId, Guid.NewGuid(), 2, 19.75m);
    var orderItem2 = new OrderItem(Guid.NewGuid(),
        orderId, Guid.NewGuid(), 3, 9.66m);
    var orderItemData = new List<OrderItem> { orderItem1, orderItem2 };

    var orderItemRepository = Substitute.For<IOrderItemRepository>();
    orderItemRepository.GetByOrderId(orderId).Returns(orderItemData);

    var taxService = Substitute.For<ITaxService>();

    taxService.CalculateTax(default, default)
        .ReturnsForAnyArgs(info =>
        {
            var netPrice = info.ArgAt<decimal>(0);
            var taxRate = info.ArgAt<decimal>(1);

            var taxAmount = netPrice * taxRate / 100m;
            var grossPrice = netPrice + taxAmount;

            return (taxAmount, grossPrice);
        });

    var sut = new OrderItemService(orderItemRepository, taxService);

    // Act
    var orderItems = sut.GetOrderItems(orderId);

    // Assert
    orderItems.Should().NotBeNullOrEmpty();
    orderItems.Should().HaveCount(2);

    var firstOrderItem = orderItems.First();
    firstOrderItem.Id.Should().Be(orderItem1.Id);
    firstOrderItem.TaxRate.Should().Be(19);
    firstOrderItem.GrossPrice.Should().Be(19.75m * 1.19m);
}

As shown in Step 1 of our refactoring process, you can significantly reduce the setup code for tests with minimal effort.

Code Analysis

Exploring our application using Sonargraph reveals the number of dependencies between the individual classes we are dealing with at this stage.

At this point, the codebase consists of 917 lines of code in 53 files and has an Average Component Dependency (ACD) of 5.3.

Step 1: Test Dummies

In the first step, we focus on the test classes. A robust test suite is the foundation of safe refactoring, which is why we start here.

Following the motto new is glue, we move the instantiation of test data out of the test methods and into Dummies. There’s a dedicated blog post on the topic of Dummy Factories Simple test setup with dummy factories, so we’ll only briefly touch on the changes to our example code here.

Source code on GitHub, Branch steps/02-introduce-dummies

We add a class called DataDummies that takes care of instantiating data objects for us. Additionally, we define some static instances of Customer objects that we can use in our tests.

internal static class DataDummies
{
    public static Customer JohnDoe => Customer(
        new Guid("bfbffb19-cdd4-42ac-b536-606a16d03eae"), "John",
        "Doe", "john.doe@example.com");

    public static Customer JaneDoe => Customer(
        new Guid("95a6db4a-4635-4fb3-b7f6-c206ff7272f1"), "Jane",
        "Doe", "Jane.doe@example.com", false);

    public static Customer Customer(
        Guid? id = null, string firstName = "Peter", string lastName = "Parker",
        string email = "peter.parker@example.com", bool active = true)
    {
        return new Customer(id ?? Guid.NewGuid(),
            firstName, lastName, email, active);
    }

    ...
}

We follow the same approach for our domain objects. Here, we can take advantage of the fact that POCO classes and domain models are usually structured similarly, allowing us to use the data objects from DataDummies.

internal static class ModelDummies
{
    public static Customer JohnDoe => FromData(DataDummies.JohnDoe);
    public static Customer JaneDoe => FromData(DataDummies.JaneDoe);

    public static Customer FromData(Data.Customer data)
    {
        return Customer(id: data.Id, firstName: data.FirstName,
            lastName: data.LastName, email: data.Email);
    }

    ...
}

With this approach, our test setup becomes simpler and, most importantly, more resilient to changes in the data objects since we only need to adjust them in one place.

[Test]
public void Should_Return_OrderItems()
{
    // Arrange
    var orderId = Guid.NewGuid();

    var orderItem1 = OrderItem(price: 19.75m);
    var orderItem2 = OrderItem(price: 9.66m);
    var orderItemData = Collection(orderItem1, orderItem2);

    var orderItemRepository = Substitute.For<IOrderItemRepository>();
    orderItemRepository.GetByOrderId(orderId).Returns(orderItemData);

    ...
}

After these preparations, we can proceed with refactoring the production code.

Step 2: Removing Interfaces

In the second step, we aim to remove unnecessary abstractions through interfaces and base classes. It’s often argued that test code can leverage these abstractions, replacing dependencies implemented as interfaces with mocks, stubs, or fakes. This is certainly true for external dependencies, such as databases or email servers. However, for self-created abstractions, it usually leads to unnecessary complexity and a high overhead in test setup. Test mocks are challenging to maintain and require knowledge of the internals of the real implementation, necessitating their recreation.

Our first point of focus is the TaxService. The CalculateTax() method is already a pure function. Therefore, we can delete the ITaxService interface, make the class and the method static, and simply call it directly. There’s no need for dependency injection, and the test mock can also be eliminated.

public static class TaxService
{
    public static (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate)
    {
        ...
    }
}

The corresponding Git commit shows 43 deleted lines.

Now let’s turn our attention to the service classes OrderService and OrderItemService. From the dependencies provided via constructor injection (e.g., ICustomerRepository), we only need individual methods or even just the return value of a method. Instead of injecting repository classes, we pass method pointers (delegates) to the service classes. This eliminates the need for private properties, makes the classes stateless and static, and allows us to remove the interfaces.

The OrderService class previously had three dependencies.

public class OrderService : IOrderService
{
    private readonly ICustomerRepository _customerRepository;
    private readonly IOrderItemRepository _orderItemRepository;
    private readonly IOrderRepository _orderRepository;

    public OrderService(IOrderRepository orderRepository,
        ICustomerRepository customerRepository,
        IOrderItemRepository orderItemRepository)
    {
        _orderRepository = orderRepository;
        _customerRepository = customerRepository;
        _orderItemRepository = orderItemRepository;
    }

    public Order GetOrder(Guid id)
    {
        var orderData = _orderRepository.Get(id);
        return GetOrder(orderData);
    }

    private Order GetOrder(Data.Order orderData)
    {
        var customerData = _customerRepository.Get(orderData.CustomerId);
        var orderItemData = _orderItemRepository.GetByOrderId(orderData.Id);

        ...

        return orderModel;
    }
}

After the refactoring, the class looks like this:

public static class OrderService
{
    public static Order GetOrder(Guid id,
        Func<Guid, Data.Order> getOrder,
        Func<Guid, Customer> getCustomer,
        Func<Guid, IReadOnlyCollection<OrderItem>> getOrderItems)
    {
        var orderData = getOrder(id);
        var customerData = getCustomer(orderData.CustomerId);
        var orderItemData = getOrderItems(id);
        return GetOrder(orderData, customerData, orderItemData);
    }

    ...
}

The GetOrder() method is now simply called by passing the relevant methods of the repositories as parameters.

var orders = OrderService.GetOrder(
    id: id,
    getOrder: _orderRepository.Get,
    getCustomer: _customerRepository.Get,
    getOrderItems: _orderItemRepository.GetByOrderId);

If the method signatures differ, we can easily adapt them using lambda expressions.

var orders = OrderService.GetOrder(
    id: id,
    getCustomer: id => _customerRepository.Get(id: id, activeOnly: true),
    ...

The corresponding unit tests also become simpler. We no longer need to assemble mock objects but only define methods. These local lambda expressions are one-liners.

var getOrder = (Guid _) => DataDummies.Order(orderId, peterPan.Id);
var getCustomer = (Guid _) => peterPan;
var getByOrderId = (Guid _) => DataDummies.Collection(orderItem1, orderItem2);

// Act
var order = OrderService.GetOrder(orderId, getOrder, getCustomer, getByOrderId);

Alternatively, with pure functions, you can pass the return value of the same function as a parameter. This is referred to as referential transparency. However, for methods that have side effects (such as database updates) or filter large data sets, this is not always advisable

var order = _orderRepository.Get(id);
var customer = _customerRepository.Get(order.CustomerId);
var orderItems = _orderItemRepository.GetByOrderId(id);

var orders = OrderService.GetOrder(order, customer, orderItems);

By passing dependencies as method parameters rather than using dependency injection to bring them into a class, we shift the responsibility for creating and managing dependencies to the calling code.

Step 3: Removing CQRS

Next, we remove the CQRS pattern implemented with MediatR from our codebase. The library is great, and CQRS is a powerful tool when there is a genuine need to separate commands and queries. However, in our example, we want to demonstrate that this is often unnecessary and might be premature optimization that never materializes.

Instead of distributing the source code that connects the controller and domain logic across multiple IRequest and IRequestHandler<> implementations, we consolidate it into a few integration classes.

Instead of having an AddOrderHandler along with its corresponding AddOrderRequest, we now have a single method that receives the required dependencies as parameters and orchestrates the invocation of the service classes.

public static class OrdersIntegration
{
    public static void AddOrder(Order order,
        ICustomerRepository customerRepository,
        IOrderItemRepository orderItemRepository,
        IOrderRepository orderRepository)
    {
        if (!order.Items.Any())
            throw new InvalidOperationException("Order must have at least one item.");

        var customerData = customerRepository.Get(order.Customer.Id);

        if (customerData.Active is false)
            throw new InvalidOperationException("Customer is not active.");

        foreach (var orderItem in order.Items)
        {
            var orderItemData = OrderItemService.AddOrderItem(orderItem, order);
            orderItemRepository.Add(orderItemData);
        }

        OrderService.AddOrder(order, orderRepository.Add);
    }

    ...
}

In another step, similar to what we did for the services, we can switch from injecting repositories to using method delegates. This allows us to remove all IRepository interfaces since we no longer need to substitute them in our tests. An example Git commit demonstrates this for the IOrderRepository.

Schritt 4: Statische Repositories

After removing a few more abstract base classes and interfaces, let’s take another look at the repository classes. They all have only one dependency on IDatabase. Switching from constructor injection to method injection can be done quickly.

- public class OrderRepository
+ public static class OrderRepository
{
-    private readonly IDatabase _database;
-    public OrderRepository(IDatabase database) => _database = database;

-    public IEnumerable<OrderData> GetOrdersByDate(
-       DateTime startDate, DateTime endDate)
-        => _database.GetAll<OrderData>()
-               .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);


+    public static IEnumerable<OrderData> GetOrdersByDate(
+        DateTime startDate, DateTime endDate, IDatabase db)
+            => db.GetAll<OrderData>()
+                .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);
     ...
}

If we take it a step further here and expect method delegates as method parameters instead of an instance of IDatabase, we can completely remove the dependency on IDatabase from our repositories.

public static class OrderRepository
{
-    public static IEnumerable<OrderData> GetOrdersByDate(
-       DateTime startDate, DateTime endDate, IDatabase db)
-        => db.GetAll<OrderData>()
-            .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);

+    public static IEnumerable<OrderData> GetOrdersByDate(
+        DateTime startDate, DateTime endDate, 
+        Func<IEnumerable<OrderData>> getAll)
+        => getAll().Where(x => x.OrderDate >= startDate &&
+                               x.OrderDate <= endDate);

    ...
}

Alternatively, it may be worth considering passing the return values of these methods to our service method instead of the methods themselves. This eliminates all side effects, resulting in a pure function.

public static IReadOnlyCollection<Order> GetOrdersByDate(
    DateTime startDate, DateTime endDate,
    IEnumerable<OrderData> allOrderData,
    IDictionary<Guid, CustomerData> customerData,
    ILookup<Guid, OrderItemData> orderItemData)
{
    return allOrderData
        .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate)
        .Select(order => GetOrder(order,
            customerData[order.CustomerId], orderItemData[order.Id]))
        .ToList();
}

The calling method is now responsible for collecting the data.

var allOrderData = db.GetAll<OrderData>();

var customerData = db.GetAll<CustomerData>()
    .ToDictionary(x => x.Id, x => x);

var orderData = db.GetAll<OrderItemData>()
    .ToLookup(x => x.OrderId);

var orders = OrderService.GetOrdersByDate(startDate, endDate,
    allOrderData, customerData, orderData);

For external data sources like databases or files, this approach is usually not suitable due to the late filtering, as it may load too much data. We don’t want to load the entire database into memory just to use a few records. However, for small data sets or data already in memory, this is a good way to (reduce complexity).

Results

What have we achieved with these refactoring steps? Our codebase has become significantly smaller, with almost all interfaces removed.

The dependency graph shows significantly fewer lines. The number of lines of code has been reduced to 715 (25% less), the number of files to 34 (35% less), and the Average Component Dependency has dropped from 5.3 to 3.6.

Besides the raw numbers, what’s more important is that the code is now easier to understand and follow. You no longer have to hunt for interfaces and potential implementations to understand the runtime behavior.

The entire source code is available on GitHub.

Test data

For calling methods from tests, they often need to be fed with defined input parameters. The further down we are in the test pyramid, the more synthetic these data will be. The structure of the data can range from simple primitive data types like strings, booleans, or numerical values to complex object structures.

Let’s take a look at an imaginary e-commerce software with the following data classes. The examples are written in C#, but can be adapted to other programming languages.

public record Address(Guid Id, string Street, string City,
  string State, string ZipCode);

public record Customer(Guid Id, string FirstName, string LastName,
  Address Address, string Email, bool Active);

public record Product(string Sku, string Name,
  string Description, decimal Price);

public record Order(string OrderNumber, DateTime OrderDate,
  Customer Customer, IEnumerable<OrderItem> Items);

public record OrderItem(Product Product, int Quantity, decimal Price);

For a method OrderService.PlaceOrder(..), a unit test could begin something like this:

[Test]
public void Should_Place_Order()
{
    // Arrange
    var address = new Address(Guid.NewGuid(), "123 Main St",
      "Anytown", "TX", "12345");
    var customer = new Customer(Guid.NewGuid(), "John", "Doe", address,
      "john.doe@example.com", true);

    var product1 = new Product("P-001", "Product 1", "Product 1 Description", 9.99m);
    var product2 = new Product("P-002", "Product 2", "Product 2 Description", 19.99m);

    var orderItems = new[]
    {
        new OrderItem(product1, 1, product1.Price),
        new OrderItem(product2, 2, product2.Price)
    };
    var order = new Order("O-001", DateTime.UtcNow, customer, orderItems);

    // Act
    var sut = new OrderService();
    sut.PlaceOrder(order);

    // Assert
    //...
}

However, before we can reach the point of calling our method to be tested with the correct parameters, we need to write several lines of setup code just to create a valid Order. An Order contains a Customer with an Address and a quantity of OrderItems with associated Products.

This code not only becomes quickly redundant but also error-prone. Now, if we imagine that we have to create a new Order for each test method, it becomes evident that we can lose a lot of time here.

Another disadvantage: if there are changes to our data classes, for example, if a Customer now also needs to have a phone number, and we add non-optional parameters, we would have to update the constructor calls in all test methods that create these data instances.

Dummy factories

One solution to these issues is to create dummy factories. These are classes and methods that are available to us in all tests after being written once, making it easier to generate test data. For each data class, a dummy method is created, ideally with default parameters. These parameters can be overridden as needed in the test methods for the specific use case. For nested data structures, nullable reference types can be used, which, in the absence of data, can be replaced with dummy values.

public static class Dummies
{
    public static Address Address(
        Guid? id = null,
        string street = "123 Main St",
        string city = "Anytown",
        string state = "TX",
        string zipCode = "12345") =>
        new(id ?? Guid.NewGuid(), street, city, state, zipCode);

    public static Customer Customer(
        Guid? id = null,
        string firstName = "John",
        string lastName = "Doe",
        Address? address = null,
        string email = "john.doe@example.com",
        bool active = true) =>
        new(id ?? Guid.NewGuid(), firstName, lastName, 
          address ?? Address(), email, active);

    public static Product Product(
        string sku = "P-001",
        string name = "Product 1",
        string description = "Product 1 Description",
        decimal price = 9.99m) =>
        new(sku, name, description, price);
    
    // ...
}

With small helper methods, you can further simplify your life.

public static T[] Many<T>(params T[] items) => items.ToArray();

The test method shown above can now look like this:

using static Company.Webstore.Tests.Dummies;

[Test]
public void Should_Place_Order()
{
    // Arrange
    var orderItems = Many(
        OrderItem(),
        OrderItem(Product(sku: "P-002", price: 19.99m), 2));
    var order = Order(items: orderItems);

    // Act
    var sut = new OrderService();
    sut.PlaceOrder(order);

    // Assert
    //...
}

By using a using static statement, you can call the dummy method directly without having to prepend the class name.

With this, our test setup is reduced to just a few relevant lines.

If there are any changes to our data classes, we only need to adjust the dummy method, and the test methods remain untouched.

Alternatives

To generate more or less random test or fake data, libraries like Bogus or FsCheck are available. Of course, using these libraries involves giving up some control, whereas using dummies is much more explicit. Depending on the use case, this can be an advantage and justify the additional complexity.

For HTTP services in conjunction with a reverse proxy, Sablier offers a simple way to implement Scale-to-Zero in your own infrastructure.

Scale-to-Zero

Scale-to-Zero refers to the complete scaling down of workloads to zero, so that no resources are being consumed. In the context of Kubernetes, solutions like Keda exist, but they are more geared towards event-driven use cases and are not primarily suitable for HTTP services. The HTTP Addon for Keda is currently in the beta stage.

Fully shutting down applications can be advantageous when operating a large number of services with only a few requests each. This reduces the number of concurrently running containers and resource consumption. If you’re using a cloud provider and paying per resource or time unit, this can lead to cost savings.

The example code for this post can be found on Github: https://github.com/davull/demo-docker-traefik-sablier

Sablier and Traefik

Sablier is a lightweight solution for starting and stopping HTTP services on demand. It supports various container providers, currently Docker, Docker Swarm, and Kubernetes. To scale up and down the corresponding containers based on incoming requests, there are plugins available for the reverse proxies Traefik, Nginx, and Caddy. Since Sablier is defined as an API, it can theoretically be integrated into other systems as well.

Source https://acouvreur.github.io/sablier/

Below, the use of Sablier with Traefik and Docker is described. However, the configuration for other reverse proxies and container providers is analogous.

The starting point is a Traefik instance and a workload that should be controlled via Sablier. The definition of the services is done using Docker Compose.

The configuration file docker-compose-traefik.yaml for Traefik contains a single service description and a network:

version: "3"

services:
  traefik:
    container_name: traefik
    image: traefik:v2.10
    ports:
      - 80:80
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./traefik/traefik.yml:/etc/traefik/traefik.yml
      - ./traefik/dynamic_config/:/etc/traefik/dynamic_config/
      - ./traefik/log/:/etc/traefik/log/
    networks:
      - traefik
    ...
    
networks:
  traefik:
    name: traefik

The workload consists of three services (all represented by traefik/whoami images), which are meant to simulate a distributed application. The file docker-compose-whoami.yaml has the following content:

version: "3"

services:
  whoami:
    container_name: whoami
    image: traefik/whoami
    networks:
      - traefik
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami-router.rule=Host(`whoami.example.com`)"
      - "traefik.http.routers.whoami-router.entrypoints=web"

  whoami-nginx:
    container_name: nginx
    image: traefik/whoami
    networks:
      - traefik

  whoami-mariadb:
    container_name: mariadb
    image: traefik/whoami
    networks:
      - traefik

networks:
  traefik:
    name: traefik
    external: true

Setting up Sablier

Sablier itself can be run as a Docker container or as a binary. Here, we’re using the container and extending the file docker-compose-traefik.yaml with an additional service description:

sablier:
  container_name: traefik-sablier
  image: acouvreur/sablier:1.3.0
  command:
    - start
    - --provider.name=docker
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  networks:
    - traefik

Sablier requires access to the Docker host service, which is why we’re mounting the path /var/run/docker.sock to the same location in the container. Using the parameter --provider.name, we specify the used container provider as docker.

Adding the Traefik Plugin

To enable Traefik to interact with the Sablier API and be aware of it, we configure the Traefik plugin for Sablier. For this purpose, the configuration file traefik.yml is extended with the following lines:

experimental:
  plugins:
    sablier:
      moduleName: "github.com/acouvreur/sablier"
      version: "v1.3.0"

Preparing Configuration

In order for Sablier to start and stop the containers in our workload, two adjustments need to be made.

Since Traefik no longer has access to container labels when a container is not running (scaled down to zero), we first need to change the configuration of the workload service from container labels to a configuration file. This is only necessary if container labels were used for Traefik configuration.

The labels from the workload service are transferred to a file dynamic_config/whoami.yaml.

From

# docker-compose-whoami.yaml
...
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.whoami-router.rule=Host(`whoami.example.com`)"
  - "traefik.http.routers.whoami-router.entrypoints=web"

it becomes

# dynamic_config/whoami.yaml
http:
  services:
    whoami-service:
      loadBalancer:
        servers:
          - url: http://whoami:80

  routers:
    whoami-router:
      rule: "Host(`whoami.example.com`)"
      service: whoami-service
      entryPoints:
        - web

Afterwards, we can proceed with integrating Sablier.

Configuring Sablier

Sablier has two types of strategies for responding to an incoming HTTP request when the corresponding container is not running:

• Dynamic Strategy: Sablier serves a status webpage that informs the user their requested service is being started and automatically redirects them or refreshes the page after the start.
• Blocking Strategy: Sablier blocks the request until the underlying container is started and then delivers the response.

The Blocking Strategy is especially suitable for APIs, so that the calling client only experiences a longer response time on the first access to a shutdown service, without needing to deal with retries and redirects.

Dynamic Strategy

To configure our workload with the Dynamic Strategy, we start by creating a Traefik middleware for Sablier. This is defined in the dynamic_config/sablier.yaml file:

http:
  middlewares:
    sablier-dynamic:
      plugin:
        sablier:
          sablierUrl: http://sablier:10000
          sessionDuration: 1m
          names: whoami,nginx,mariadb
          dynamic:
            displayName: whoami
            refreshFrequency: 1s
            showDetails: true
            theme: shuffle

sablierUrl points to our Sablier container, which we defined in the docker-compose-traefik.yaml file, and port 10,000 is the default port.

The sessionDuration parameter indicates how long a container should remain running after the last access to it. After that, the container will be shut down.

With names, we specify the names of the containers that Sablier should control. These names must match the names of the containers in our docker-compose-whoami.yaml file (parameter container_name).

Under the dynamic key, the behavior of the Dynamic Strategy is configured. We can provide a display name (displayName) for the status page, set the refresh frequency (refreshFrequency) of the status page, decide whether to show details (showDetails), and specify which theme (theme) to use. There are several themes to choose from, but custom themes can also be defined.

Now we configure our workload to use the Sablier middleware. In the dynamic_config/whoami.yaml file, we modify the definition of the whoami router and add the middleware:

http:
  ...
  routers:
    whoami-router:
      rule: "Host(`whoami.example.com`)"
      service: whoami-service
      entryPoints:
        - web
      middlewares:
        - sablier-dynamic@file

With this, Sablier is ready to receive our request, start the underlying container for us, and shut it down after a minute of inactivity.

A note about the Dynamic Strategy: Unfortunately, the Safari browser on iOS devices doesn’t display the status page on the first access and instead gives a This site can't be reached error.

Blocking Strategy

The Blocking Strategy is configured in a similar way to the Dynamic Strategy. We start by creating another Traefik middleware for Sablier. This is defined in the dynamic_config/sablier.yaml file as well:

http:
  middlewares:
    sablier-dynamic:
      ...

    sablier-blocking:
      plugin:
        sablier:
          sablierUrl: http://sablier:10000
          sessionDuration: 1m
          names: whoami
          blocking:
            defaultTimeout: 10s

The defaultTimeout specifies how long to wait for the target container to start before aborting the request.

In the dynamic_config/whoami.yaml file, we use the new middleware:

http:
  ...
  routers:
    whoami-router:
      ...
      middlewares:
        - sablier-blocking@file

When we call our workload with the Blocking Strategy, on the first access, we experience a longer response time as Sablier needs to start the underlying container.

Conclusion

Sablier offers a straightforward way to implement Scale-to-Zero for HTTP services. Once you’ve gathered the necessary information from the various documentation sources for Sablier, Traefik, and the Traefik plugin, the configuration isn’t overly complex. However, the documentation can sometimes be thin, and you might encounter empty pages here and there.

The example code with commits for each configuration step can be found on GitHub: https://github.com/davull/demo-docker-traefik-sablier.

If you use Infrastructure-as-Code (IaC) tools like Terraform for provisioning your cloud infrastructure, you can also manage DNS configuration through it. However, this approach often restricts you to the major hyperscale cloud providers for DNS services.

DNSControl provides a simpler and less configuration-intensive way to define DNS configuration for dozens of large and small providers using JavaScript code. This allows you to set up and manage your DNS environment in an automated and reproducible manner. The configuration is versioned in a Git repository and can undergo code reviews, seamlessly integrating the process into the DevOps toolchain.

Installation

You can install DNSControl through a package manager like brew or by downloading the binary from the project’s GitHub page. The program, written in Go, is available for Windows, Linux, and macOS. Additionally, there’s a pre-built Docker image.

Configuration

DNSControl understands DNS registrars and DNS service providers (DSP). A registrar allows you to register new domains and specify the responsible nameservers. A DSP manages DNS zones and serves DNS requests. Often, a registrar also functions as a DSP. However, the configuration still needs to be done for both entities.

Providing credentials

In the creds.json file, you store the credentials for the providers you’re using. Most providers require access credentials in the form of an API key or something similar. The exact syntax can be found in the documentation of each provider. Some providers can only be used as DSPs, while others can only be used as registrars. To create a local zone file for BIND configuration, you can use the BIND type. If you’re not using a registrar, you can use the NONE type.

To avoid storing credentials in plain text in the configuration file, you can use environment variables. These variables are referenced in the configuration file using the $NAME syntax.

The following example configures BIND, a dummy entry, and Hetzner as a provider.

{
    "local": {
        "TYPE": "BIND"
    },
    "none": {
        "TYPE": "NONE"
    },
    "hetzner": {
        "TYPE": "HETZNER",
        "api_key": "$DNSCONTROL_HETZNER_API_KEY"
    }
}

You can check if your configuration is correct using check-creds. The get-zones command lets you retrieve the DNS zones that are already present in your DNS provider. Formats like tsv (tab-separated values) and the BIND format zone are available. nameonly displays only the zone names.

# Check credentials
dnscontrol check-creds hetzner

# Get all zones from provider
dnscontrol get-zones --format=nameonly hetzner - all

Configuring DNS Zones

The configuration of DNS zones is done using JavaScript code, typically in the dnsconfig.js file. This approach offers great flexibility for recurring settings such as DNS or mail servers.

The NewRegistrar() and NewDnsProvider() functions are used to read the configured providers from the creds.json file. Entries are identified by their names.

The D() function is used to define a DNS zone. It takes parameters such as the name of the zone, the registrar, the DSP, and a list of DNS entries. For different types of entries, there are corresponding functions known as Domain Modifiers available, such as A() and AAAA() for A and AAAA records, respectively.

var REG = NewRegistrar("none");;
var DNS = NewDnsProvider("hetzner");;

var HETZNER_NAMESERVER_RECORDS = [
    NAMESERVER("helium.ns.hetzner.de."),
    NAMESERVER("hydrogen.ns.hetzner.com."),
    NAMESERVER("oxygen.ns.hetzner.com.")
];

D("production-ready.de", REG, DnsProvider(DNS),
    A("@", "116.203.23.216"),
    A("www", "116.203.23.216"),
    AAAA("@", "2a01:4f8:c0c:bf6a::1"),
    MX("@", 10, "mail.example.com."),
    HETZNER_NAMESERVER_RECORDS
);

For constructing more complex records, there are builder functions available. The resulting object can be easily included in the list of DNS entries.

var CAA = CAA_BUILDER({
    label: "@",
    issue: ["letsencrypt.org"],
    iodef: "mailto:administrator@example.com",
    iodef_critical: true,
    issuewild: "none"
});

var DMARC = DMARC_BUILDER({
    policy: "none",
    subdomainPolicy: "none",
    rua: ["mailto:postmaster@example.de"],
    ruf: ["mailto:postmaster@example.de"],
    reportInterval: "7d"
});

D("example.com", REG, DnsProvider(DNS),
    A("@", "116.203.23.216"),
    ...
    CAA,
    DMARC
);

If you have multiple domains to manage, it’s a good idea to split the configuration into multiple files. These files can then be imported into the main dnsconfig.js file.

require("domains/production-ready.de.js");

Importing Existing DNS Zones

If you want to migrate existing DNS zones into DNSControl, you can save some typing by using get-zones with the output format set to js. Then, you can write the content to a file using --out [file].js. The generated code can serve as a starting point for your own configuration.

> dnscontrol get-zones --format js --out import.js hetzner - production-ready.de

var DSP_HETZNER = NewDnsProvider("hetzner");
var REG_CHANGEME = NewRegistrar("none");
D("production-ready.de", REG_CHANGEME,
        DnsProvider(DSP_HETZNER),
        DefaultTTL(3600),
        //NAMESERVER('oxygen.ns.hetzner.com.'),
        //NAMESERVER('hydrogen.ns.hetzner.com.'),
        //NAMESERVER('helium.ns.hetzner.de.'),
        A('@', '116.203.23.216'),
        A('www', '116.203.23.216'),
        ...
)

Type-Checking

To enable type-checking and code completion similar like TypeScript in your JavaScript files, DNSControl offers a useful feature: generating a TypeScript declaration file.

dnscontrol write-types

At the beginning of the dnsconfig.js file, you reference the generated TypeScript Declaration File.

// @ts-check
/// <reference path="types-dnscontrol.d.ts" />

...

Checking and Applying Changes

For validating the configuration, DNSControl provides the check command. This command checks the JavaScript files for errors but doesn’t interact with any DNS provider. The preview command compares the current configuration with the state of DNS zones at the provider and displays potential changes. In the following example, a CNAME record is added, and an A record is modified.

# Check and validate dnsconfig.js
> dnscontrol check
No errors.

# Preview changes
> dnscontrol preview
******************** Domain: production-ready.de
2 corrections (hetzner)
#1: Batch creation of records:
   + CREATE CNAME www2.production-ready.de www.production-ready.de. ttl=3600
#2: Batch modification of records:
   ± MODIFY A production-ready.de: (116.203.23.216 ttl=3600) -> (192.168.0.1 ttl=3600)
Done. 2 corrections.

If the changes align with the expected results, you can apply them using the push command.

> dnscontrol push

2 corrections (hetzner)
#1: Batch creation of records:
   + CREATE CNAME www2.production-ready.de www.production-ready.de. ttl=3600
SUCCESS!
#2: Batch modification of records:
   ± MODIFY A production-ready.de: (116.203.23.216 ttl=3600) -> (192.168.0.1 ttl=3600)
SUCCESS!
Done. 2 corrections.

With these tools and approaches, you are capable of effectively and transparently managing an entire DNS landscape using an Infrastructure-as-Code approach.

Azure DevOps Pipeline

To avoid the need to execute DNS configuration changes locally, creating a build pipeline is a convenient option. This pipeline can also be used to validate pull requests containing DNS changes. The provided code is tailored for Azure DevOps, but similar approaches can be adapted for other CI/CD systems.

If DNSControl is not installed on your build agent, such as when using Microsoft’s Hosted Agents or your own Docker-based agents, you can perform this installation through a simple CmdLine task. Create a folder, download the file, extract it, and make the binary executable.

- task: CmdLine@2
  displayName: "Install DNSControl"
  inputs:
      script: |
        mkdir -p $(Agent.TempDirectory)/bin
        cd $(Agent.TempDirectory)/bin
        wget -q https://github.com/StackExchange/dnscontrol/releases/download/v4.1.1/dnscontrol_4.1.1_linux_amd64.tar.gz -O dnscontrol.tar.gz
        tar -xf dnscontrol.tar.gz dnscontrol
        chmod +x dnscontrol

Subsequently, you can validate the configuration and display the changes. The API key for the provider can be stored as a secret variable in the pipeline configuration or retrieved from an Azure KeyVault. When using a variable, explicit mapping to an environment variable is crucial; otherwise, the API key won’t be accessible in the script.

- task: CmdLine@2
  displayName: "Run DNSControl check"
  inputs: 
    script: $(Agent.TempDirectory)/bin/dnscontrol check

- task: CmdLine@2
  displayName: "Run DNSControl preview"
  inputs: 
    script: $(Agent.TempDirectory)/bin/dnscontrol preview
  env:
    DNSCONTROL_HETZNER_API_KEY: $(DNSCONTROL_HETZNER_API_KEY)

If the changes align with the desired outcome, you can apply them in a deployment step.

jobs:
  - deployment: 
    displayName: "Apply DNS Update"
    environment: HETZNER_DNS_PROD
    strategy:
      runOnce:
        deploy:
          steps:
            - task: CmdLine@2
              displayName: "Run DNSControl push"
              inputs: 
                script: $(Agent.TempDirectory)/bin/dnscontrol push
              env:
                DNSCONTROL_HETZNER_API_KEY: $(DNSCONTROL_HETZNER_API_KEY)

legacy code is code without tests

– Michael Feathers

In addition to common approaches like example-based testing or snapshot testing, there are other methods that help us verify the correctness of our code. One of these approaches is property-based testing.

Property-based testing doesn’t check individual values for equality; rather, it aims to verify properties that our implementation must exhibit. For example, in mathematical addition, commutativity is a property that we can check without looking at specific numbers. For the addition of two numbers a and b, the commutative property always holds:

a + b = b + a

Property-based testing

Property testing or Property-based testing (PBT) is a testing technique that has become popular in functional programming, often associated with tools like QuickCheck in Haskell. It is well-suited for problem domains where verifying properties is much simpler than solving the problems themselves. However, it can also be valuable for testing more common scenarios.

In property-based testing, you define properties that the code under test must satisfy for a range of input data. Note that a property, in this context, isn’t the same as a C# property.

For instance, the property of commutativity in mathematical addition can be described as a function in C#:

Func<int, int, bool> commutativity = (int a, int b) => a + b == b + a;

The definition of Addition states that the commutative law holds true for all combinations of a and b. This means that our commutativity function must return true for all integer values.

When we implement our own Addition function, we can use this property to verify the correctness of our implementation.

Func<int, int, bool> commutativity = (int a, int b) 
    => MathOperations.Add(a, b) == MathOperations.Add(b, a);

Example-based testing

A naive approach to test the correctness of our Addition function is to call the function with a few example values and verify the return values, here using NUnit.

[TestCase(0, 0)]
[TestCase(1, 2)]
[TestCase(999, 9999)]
public void TestCommutativity_WithExamples(int a, int b)
{
    var left = MathOperations.Add(a, b);
    var right = MathOperations.Add(b, a);

    Assert.AreEqual(left, right);
}

Since we are not interested in the specific values of a and b, we can generate them randomly. This can be done for any number of combinations of a and b, in this case, it’s 1,000 iterations. By doing this, we have tested our Addition function with 1,000 randomly generated values instead of just three concrete values. This makes us more confident that our Addition function is working correctly.

[Test]
public void TestCommutativity_WithRandomValues()
{
    for (var i = 0; i < 1_000; i++)
    {
        var a = Random.Shared.Next(-999, 999);
        var b = Random.Shared.Next(-123, 321);

        var left = MathOperations.Add(a, b);
        var right = MathOperations.Add(b, a);

        Assert.AreEqual(left, right);
    }
}

However, this approach also comes with a few drawbacks: It’s clear that it requires more code, and our test case becomes more complex. Additionally, the generated values are chosen randomly and may not cover the entire range of possible input values.

A more significant issue is that if an error occurs, we won’t know which input values triggered the error since they are randomly generated in each iteration.

FsCheck

The library FsCheck written in F# provides a solution to this issue and can also be used in C#. The comprehensive documentation primarily uses F# syntax but also provides examples in C#.

It offers functions to simplify property testing. A test in FsCheck essentially consists of the following three parts:

> for all (x, y, ..)
> such as precondition(x, y, ...) holds 
> property(x, y, ...) is satisfied

This way, we can test the Commutativity property using FsCheck as follows:

[Test]
public void TestCommutativity()
{
    var property = (int x, int y)
        => MathOperations.Add(x, y) == MathOperations.Add(y, x);

    Prop.ForAll(
            Arb.From<int>(), // Parameter x
            Arb.From<int>(), // Parameter y
            property)
        .QuickCheckThrowOnFailure();
}

It becomes even easier when we use the extension FsCheck.NUnit (equivalent to FsCheck.Xunit for XUnit). Instead of annotating our test method with [Test] or [Fact], we annotate it with [Property] and can directly pass the properties as parameters. FsCheck automatically generates input values of the corresponding type.

[Property]
public bool TestCommutativity(int x, int y)
{
    return MathOperations.Add(x, y) == MathOperations.Add(y, x);
}

If we want to learn something about the distribution of the generated input values, we can classify them based on certain conditions. By calling Classify(), we get a value of type Property, so we need to adjust the return value of the test method accordingly.

[Property]
public Property TestCommutativity_WithClassification(int x, int y)
{
    var property = MathOperations.Add(x, y) == MathOperations.Add(y, x);

    return property
        .Classify(x == 0, "x == 0")
        .Classify(x > 0, "x > 0")
        .Classify(x < 0, "x < 0");
}

The corresponding output provides results similar to the following:

Ok, passed 100 tests.
50% x > 0.
46% x < 0.
4% x == 0.

If you want to have an output for each individual test case, the Collect() method can be helpful.

[Property]
public Property TestCommutativity_WithCollect(int x, int y)
{
    var property = MathOperations.Add(x, y) == MathOperations.Add(y, x);

    return property
        .Collect($"x: {x}, y: {y}");
}

The output provides a line for each combination along with its distribution.

Ok, passed 100 tests.
2% "x: 5, y: 9".
2% "x: 0, y: 0".
2% "x: -16, y: -6".
1% "x: 9, y: 32".
1% "x: 9, y: -26".
...

Conditions

If not all values of the data type of an input parameter are valid for a specific test case, we can use When() to define a precondition. To prevent dividing by 0 when testing Division, we exclude that case using this approach.

[Property]
public Property TestDivide(int x, int y)
{
    var property = () => MathOperations.Divide(x * y, y) == x;
    return property.When(y != 0);
}

Important to note: The definition of the property is executed as a method to allow for lazy evaluation by FsCheck.

Generator, Shrinker, Arbitrary

To generate suitable test data, FsCheck uses Generators, Shrinker, and Arbitraries. The Gen class provides the foundation for generating values with its three functions: Choose(), Constant(), and OneOf(). Values can be transformed and filtered using the Select() and Where() methods.

// Generate a list of numbers between 0 and 100 that are divisible by 2
var generator = Gen.Choose(0, 100)
    .Where(i => i % 2 == 0);

// Randomly choose one of the two values, "yes" or "no"
var generator = Gen.OneOf(
        Gen.Constant(true),
        Gen.Constant(false))
    .Select(b => b ? "yes" : "no");

The Sample() method of a generator provides a list of concrete values. The first parameter, size, has different effects depending on the generator, such as determining the range of values. In the case of Gen.Choose(), it has no effect. The second parameter, numberOfSamples, determines the number of elements in the generated list.

var sample = Gen.Choose(0, 100).Sample(0, 10);
// 22, 6, 16, 8, 27, 22, 14, 49, 42, 99

Shrinkers are used to simplify the process of finding errors. They attempt to find the smallest value for a failed test run, at which point the property being tested no longer holds true. In the following test, if the value is greater than or equal to 20, the test fails. By using shrinking, FsCheck can identify that the first value that causes the test to fail is 20.

[Property]
public bool Test_Shrink(PositiveInt value)
{
    return value.Item < 20;
}

Output:

Falsifiable, after 25 tests (2 shrinks) (StdGen (195734675,297194399)):
Original:
PositiveInt 24
Shrunk:
PositiveInt 20

Arbitraries combine Generators and Shrinkers and serve as inputs for property tests. The Arb class provides a set of default implementations for various data types. It can also be used to generate Generators for complex types.

var arbitrary1 = Arb.Default.PositiveInt();
var arbitrary2 = Arb.Default.DateTime();
var arbitrary3 = Arb.Default.IPv4Address();

var arbitrary4 = Arb.From<int>()
    .Filter(i => i % 2 == 0);

// --- 

Gen<Point> generator = Arb.Generate<Point>();

// --- 

Gen<Point> generator = from x in Arb.Default.PositiveInt().Generator
                       from y in Arb.Default.NegativeInt().Generator
                       select new Point(x.Item, y.Item);

The Property attribute’s properties can be used to control the distribution of values.

[Property(StartSize = 0, EndSize = 10)]
public Property Test_Distribution(int value)
{
    var property = () => true;

    return property.Collect($"value: {value}");
}

The values in the middle of the value range (here 0, since both positive and negative numbers are generated) are generated more frequently than the values at the edges. The specific values for StartSize and EndSize depend on the generator.

Ok, passed 100 tests.
18% "value: 0".
13% "value: 1".
9% "value: 2".
8% "value: -2".
7% "value: -4".
7% "value: -1".
5% "value: 5".
5% "value: 3".
5% "value: -8".
5% "value: -6".
4% "value: 4".
3% "value: 7".
2% "value: 9".
2% "value: 8".
2% "value: -7".
1% "value: 6".
1% "value: -9".
1% "value: -5".
1% "value: -3".
1% "value: -10".

Arguments exhausted after X tests

FsCheck performs 100 test runs by default. The MaxTest property allows you to control the number of runs. If you restrict the valid options too much, it’s possible that FsCheck won’t be able to generate any values and will throw an exception. This helps prevent excessive runtime for individual tests.

[Property(MaxTest = 100)]
public Property Test_Exhausted(int value)
{
    var property = () => true;

    return property
        .When(value % 15 == 0);
}

The test fails with a message:

Exhausted: Arguments exhausted after 61 tests.

Now you have the option to reduce the number of test runs. However, you should also consider whether you need to narrow down the valid range of values too much. In the example, using an int value is not a well-chosen data type.

Addition Example

To complete the example of addition, let’s now test the remaining properties of associativity, identity, and inverse.

[Property]
public bool TestCommutativity(int x, int y)
{
    // x + y == y + x
    return MathOperations.Add(x, y) == MathOperations.Add(y, x);
}

[Property]
public bool TestAssociativity(int x, int y, int z)
{
    // x + (y + z) == (x + y) + z
    return MathOperations.Add(x, MathOperations.Add(y, z)) ==
           MathOperations.Add(MathOperations.Add(x, y), z);
}

[Property]
public bool TestAdditiveIdentity(int x)
{
    // x + 0 == x
    return MathOperations.Add(x, 0) == x;
}

[Property]
public bool TestAdditiveInverse(int x)
{
    // x + (-x) == 0
    return MathOperations.Add(x, -x) == 0;
}

FizzBuzz Kata

For the well-known FizzBuzz kata, the objective is to generate one of the following strings for a positive number:

• “Fizz” if the number is divisible by 3
• “Buzz” if the number is divisible by 5
• “FizzBuzz” if the number is divisible by both 3 and 5
• the number itself, otherwise

A property-based test to verify a potential solution could look like this:

[Property]
public Property Should_Get_Fizz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("Fizz");

    return property.When(n.Item % 3 == 0 && n.Item % 5 != 0);
}

[Property]
public Property Should_Get_Buzz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("Buzz");

    return property.When(n.Item % 3 != 0 && n.Item % 5 == 0);
}

[Property(MaxTest = 10)]
public Property Should_Get_FizzBuzz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("FizzBuzz");

    return property.When(n.Item % 3 == 0 && n.Item % 5 == 0);
}

[Property]
public Property Should_Get_Number(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals(n.Item.ToString());

    return property.When(n.Item % 3 != 0 && n.Item % 5 != 0);
}

A small example project with the demonstrated source code can be found on GitHub.

To make not only the runtime but also the development environment reproducible and portable, Development Containers are a suitable solution.

Development Container

Creating a development environment nowadays often requires more than just a text editor or an IDE. Runtimes, compilers, CLIs, and various tools are needed to develop software. If you work with multiple programming languages or projects, the setup process can quickly consume several hours. Another issue arises when different versions of software are needed. Node.js, for instance, is an example for which the Node Version Switcher provides more of a workaround than a good solution.

To address these problems, pre-configured virtual machines have been used for a long time, either executed locally or accessed remotely through protocols like SSH or RDP. However, the developer experience is often suboptimal in both cases.

When using Visual Studio Code for development, utilizing Devcontainers offers a lightweight alternative. Currently, besides VS Code, only Visual Studio supports the use of Devcontainers, and only for C++ projects. If your workflow can accommodate these limitations, Devcontainers are a great option. An additional advantage is that Devcontainers behave consistently across different computers and operating systems, making them suitable for team collaboration. Configuration can be stored alongside the source code in a Git repository and versioned.

Devcontainers in VS Code

The prerequisites for using Devcontainers in VS Code include having an installed version of Docker and the Dev Containers extension, which is provided directly by Microsoft. Through the Command Palette, this extension offers a set of commands to create and manage Devcontainers.

Creating a Devcontainer

To create a Devcontainer, a JSON file named devcontainer.json in the .devcontainer subfolder is all you need. The definition of a container essentially consists of three sections: Image, Features, and Configuration. When you choose the Dev Containers: Add Dev Container Configuration Files... command in VS Code, you will be guided through these three sections.

• Image: Describes the Docker image that serves as the base for the Devcontainer. You can use a pre-configured Devcontainer image or any other Docker image. Alternatively, you can specify a Dockerfile or a Docker Compose file to create your own image.

• Features: Packages and options to add and configure software to the base image. This can include tools like Git, various CLIs, Docker, or even entire development stacks for programming languages such as Go, .NET, or PHP as features. There are some predefined features, or you can create custom features using shell scripts.

• Configuration: Configuration includes aspects like port forwarding, lifecycle scripts, or adjustments for VS Code.

The following configuration uses the Node.js 20 base image with TypeScript, additionally installs the AWS and GitHub CLI, and runs the yarn install command after creating the container:

{
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
  "name": "Node.js & TypeScript",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-20",
  "features": {
    "ghcr.io/devcontainers/features/aws-cli:1": {
      "version": "latest"
    },
    "ghcr.io/devcontainers/features/github-cli:1": {
      "installDirectlyFromGitHubRelease": true,
      "version": "latest"
    }
  },
  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "yarn install"
}

When you use the VS Code Command Palette to execute the Dev Containers: Reopen in Container command, the Devcontainer is created, and VS Code establishes a connection to the container. The creation process may take a few minutes as it involves downloading the base image and installing the specified features. The root folder of your project is mounted inside the container.

Once the container is up and running, VS Code displays the mounted folder in the Explorer, allowing you to start your development work. You can access a shell running inside the container by clicking the + icon in the Terminal window. This provides a seamless environment for development within the Devcontainer.

Creating a Custom Devcontainer Image

If a preconfigured image combined with the available features doesn’t meet your requirements, you can create a custom Devcontainer image using a Dockerfile.

For a basic Ruby setup, your Dockerfile might look like this:

FROM ruby:3.0-bullseye

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
  && apt-get -y install --no-install-recommends nano libvips libvips-dev libvips-tools

RUN gem install jekyll bundler

Inside the devcontainer.json file, instead of using the image keyword, you provide the Dockerfile path and the build context under the build section. The Features block is used to install ZSH as the default shell and git. Additionally, VS Code is instructed to install the Ruby and Github Copilot extensions. Using the postCreateCommand entry ensures that the required gems are installed.

{
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
  "name": "Ruby DevContainer",
  "build": {
    "dockerfile": "Dockerfile",
    "context": "."
  },
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {
      "installZsh": true,
      "configureZshAsDefaultShell": true,
      "installOhMyZsh": true,
      "username": "vscode",
      "userUid": "1000",
      "userGid": "1000",
      "upgradePackages": true,
      "nonFreePackages": true
    },
    "ghcr.io/devcontainers/features/git:1": {
      "version": "latest",
      "ppa": false
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "rebornix.Ruby",
        "GitHub.copilot"
      ]
    }
  },
  "forwardPorts": [],
  "postCreateCommand": "bundler install --gemfile=./Gemfile && ruby --version",
  "remoteUser": "vscode"
}

If you want to install additional software or have made changes to the container image, you can simply create a new image using the command Dev Containers: Rebuild and Reopen in Container.

With the emergence of “Infrastructure as Code” approaches, infrastructure descriptions are increasingly being stored in the form of code or at least structured text files. This enables the advantages of static code analysis to be applied to infrastructure definitions as well.

Analysis of Terraform Files

For analyzing Terraform definition files, there is the CLI tool tfsec. It is available under the MIT license as an executable file for Windows, Linux, and macOS, or as a Docker image for download. tfsec comes with an extensive set of rules for major hyperscalers like AWS, Azure, and Google Cloud. However, there are fewer rules available for a self-hosted Kubernetes environment or an OpenStack cluster. While you can define custom rules using Custom Checks, using tfsec in a managed environment is probably the most practical approach.

tfsec

In the simplest case, you can run tfsec in the folder containing your Terraform files or pass the path as the first command-line argument. tfsec recursively scans all files with the extensions .tf and .tfvars and displays the results in the console.

./tfsec ./terraform

If no rule violations are detected, tfsec will output some statistics and provide an “no problems” message.

  timings
  ──────────────────────────────────────────
  disk i/o             5.3983ms
  parsing              0s
  adaptation           610.2µs
  checks               3.2634ms
  total                9.2719ms

  counts
  ──────────────────────────────────────────
  modules downloaded   0
  modules processed    1
  blocks processed     11
  files read           1

  results
  ──────────────────────────────────────────
  passed               6
  ignored              0
  critical             0
  high                 0
  medium               0
  low                  0

No problems detected!

When issues are detected, tfsec provides details about the problematic file, the exact location of the issue, as well as hints and links to further information. Using the --concise-output parameter reduces the output to the most essential information.

> ./tfsec ./terraform --concise-output

Result #1 CRITICAL Storage account uses an insecure TLS version. 
────────────────────────────────────────────────────────────────────────────────
  ./Terraform/main.tf:55
────────────────────────────────────────────────────────────────────────────────
          ID azure-storage-use-secure-tls-policy
      Impact The TLS version being outdated and has known vulnerabilities
  Resolution Use a more recent TLS/SSL policy for the load balancer

  More Information
  - https://aquasecurity.github.io/tfsec/v1.28.1/checks/azure/storage/use-secure-tls-policy/
  - https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_account#min_tls_version
────────────────────────────────────────────────────────────────────────────────

  5 passed, 1 potential problem(s) detected.

In the example, tfsec is flagging an outdated TLS version for an Azure Storage Account.

If you want to exclude specific rules from being applied, you can use the --exclude [RULE-ID] parameter to exclude them from the analysis. You can also ignore issues related to individual resources or options within your Terraform definitions by using comments in your code.

resource "azurerm_storage_account" "storage_account" {
  account_kind    = "StorageV2"
  account_tier    = "Standard"
  min_tls_version = "TLS1_1" #tfsec:ignore:azure-storage-use-secure-tls-policy
  ...
}

CI Pipeline

A useful feature of tfsec is its ability to output the results of an analysis in various formats. Using the --format parameter, you can select the desired formats, including options like Markdown, HTML, and JUnit. By using the --out parameter, you specify the directory (which must exist) and the filename prefix for the output files. The first format specified will also be displayed on the console.

The following command generates the files results.lovely, results.junit, and results.markdown in the directory ./terraform/tfsec-results.

./tfsec ./terraform --concise-output \
    --format lovely,junit,markdown \
    --out ./terraform/tfsec-results/results

The results can now be further processed in a CI pipeline, and the build can fail in case of rule violations.

Azure DevOps Pipeline

If you are using Azure DevOps Pipelines, you can publish the JUnit file as test results. This way, you can easily integrate tfsec into existing test and build workflows and visualize errors directly within the pipeline.

For simpler adaptation to other CI systems, I will demonstrate how to use tfsec as a shell command. Additionally, there is a pipeline extension available in the Visual Studio Marketplace and a GitHub Action.

First, download the appropriate binary for your system, set the execute bit if necessary, and create the output folder. Then, run tfsec. If you want to see the result in Markdown format as part of the pipeline run in the web interface, you can upload it using a logging command like echo "##vso[task.uploadsummary]....

In a second task, you can then publish the JUnit file as test results.

- task: CmdLine@2
  displayName: "Run tfsec"
  inputs:
    workingDirectory: "$(System.DefaultWorkingDirectory)/Infrastructure/Terraform"
    script: |
      echo "Download tfsec v1.28.1 ..."
      wget -q https://github.com/aquasecurity/tfsec/releases/download/v1.28.1/tfsec-linux-amd64 -O tfsec
      chmod +x tfsec
      mkdir ./tfsec-results

      ./tfsec . --concise-output \
          --format lovely,junit,markdown \
          --out ./tfsec-results/results

      echo "##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/Infrastructure/Terraform/tfsec-results/results.markdown"

- task: PublishTestResults@2
  displayName: "Publish tfsec results"
  condition: succeededOrFailed()
  inputs:
    testResultsFormat: JUnit
    searchFolder: $(System.DefaultWorkingDirectory)/Infrastructure/Terraform/tfsec-results
    testResultsFiles: "results.junit"
    failTaskOnFailedTests: true
    testRunTitle: tfsec

The tfsec results are included in the test statistics.

The result of the Markdown file is displayed in the Extensions tab.

With this, you have integrated automatic and continuous validation of Terraform files into your CI pipeline.

However, if you want to determine the version and timing of a cluster upgrade yourself, you can achieve this using the Azure CLI or even better, through Terraform. Of course, this assumes that you have provisioned your Kubernetes infrastructure using Terraform.

Azure Kubernetes Versions

Microsoft provides a list of supported Kubernetes versions along with their support periods in the documentation.

It’s important to note that updates are only possible within a minor version or to the next minor version. For example, if you want to update from version 1.24 to 1.26, you need to do it through version 1.25 in two steps.

The available versions depend on the region where the cluster is located. You can use the Azure CLI to query the available versions for a specific region.

az aks get-versions \
  --location westeurope \
  --output table

The output provides a list of available versions and the possible upgrades.

KubernetesVersion    Upgrades
-------------------  -----------------------
1.26.3               None available
1.26.0               1.26.3
1.25.6               1.26.0, 1.26.3
1.25.5               1.25.6, 1.26.0, 1.26.3
1.24.10              1.25.5, 1.25.6
1.24.9               1.24.10, 1.25.5, 1.25.6

You can also query the available upgrades for a specific cluster.

az aks get-upgrades \
  --resource-group rg-aks-test \
  --name aks-test \
  --output table

The result will show the available upgrades precisely.

Name     ResourceGroup    MasterVersion    Upgrades
-------  ---------------  ---------------  --------------
default  rg-aks-test      1.24.10          1.25.5, 1.25.6

Terraform

Configuring an AKS (Azure Kubernetes Service) cluster using Terraform is a straightforward process. Through the Azure Provider, you create the corresponding resource, azurerm_kubernetes_cluster.

In this configuration, you set the version of the control plane using kubernetes_version and the version of the nodes using default_node_pool.orchestrator_version.

terraform {
  required_version = ">= 0.13"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.48.0"
    }
  }
}

# Configure the Azure Provider via environment variables
provider "azurerm" {
  features {}
}

# Resource Group
resource "azurerm_resource_group" "rg" {
  name     = "rg-aks-test"
  location = "westeurope"
}

# AKS Cluster
resource "azurerm_kubernetes_cluster" "aks" {
  name                              = "aks-test"
  location                          = azurerm_resource_group.rg.location
  resource_group_name               = azurerm_resource_group.rg.name
  dns_prefix                        = "k8s"
  kubernetes_version                = "1.24.10"
  role_based_access_control_enabled = true

  default_node_pool {
    name                 = "default"
    node_count           = 2
    vm_size              = "Standard_B2s"
    orchestrator_version = "1.24.10"
  }

  identity {
    type = "SystemAssigned"
  }
}

A simple terraform apply, and after a few minutes, you’ll have an AKS cluster available in the desired version.

Upgrade with Terraform

To upgrade your AKS cluster to a higher version, simply modify the version numbers in your Terraform configuration file, both for the control plane and the node pools. Then, execute a terraform apply command to initiate the upgrade process. The upgrade process will remove each node from the cluster one by one and replace them with updated versions. Running pods will be redistributed among the remaining nodes and will remain accessible throughout the process. The duration of the upgrade process depends on the number of nodes and may take several minutes to hours.

If you are using a CI/CD pipeline for infrastructure changes, make sure that the process doesn’t time out.

You can monitor the upgrade progress through the Azure CLI or the Azure Portal.

az aks list -o table

az aks nodepool list \
  --resource-group rg-aks-test \
  --cluster-name  aks-test \
  --output table

The ProvisioningState will change to Upgrading.

Name     OsType    KubernetesVersion    ProvisioningState
-------  --------  -------------------  -------------------
default  Linux     1.25.6               Upgrading

Upon completion of the upgrade, the ProvisioningState will change back to Succeeded, and all nodes will be running on the new Kubernetes version.

In addition to tracking the number of sent and received emails, there is also a graphic representation for spam and viruses.

Thanks to a patch by Sebastian van de Meer, Mailgraph also provides information on whether incoming servers support SPF, DMARC, or DKIM. For this to work, it’s necessary to have these mechanisms configured on your Postfix instance.

Docker Container

To avoid installing Mailgraph and the corresponding web server directly on your email server, you can certainly run it in a Docker container.

For this purpose, I have created a Dockerfile that includes all the dependencies and can be used immediately. You can specify the path to the mail log file and a folder for storing the RRD files as volumes. Alternatively, you can also use a Docker volume for this purpose.

You can use the -v flag to mount host paths or volumes into the container: -v [Host-Path]:[Container-Path].

The log file is expected within the container at the path /var/log/mail/mail.log, and the RRD files are located at /var/www/mailgraph/rrd/.

The image defaults to serving the Mailgraph website on port 80 and the path /mailgraph.

docker run --rm \
  -v /var/log/mail/mail.log:/var/log/mail/mail.log \
  -v /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/ \
  davidullrich/mailgraph:latest

If you now access http://localhost:80/mailgraph/ in your browser, you will see the initial graphs displayed.

Docker Compose

If you’re using Docker Compose for orchestration, a corresponding configuration might look something like this:

version: '3'

services:
  mailgraph:
    image: davidullrich/mailgraph:latest
    hostname: mail.example.com
    volumes:
      - /var/log/mail/mail.log:/var/log/mail/mail.log
      - /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped

Reverse Proxy with Traefik

If you don’t want your Mailgraph webpage to be publicly accessible, you can set up authentication using a reverse proxy. An easy way to do this is by using Traefik, a reverse proxy that integrates well with Docker Compose. Once you have Traefik set up on your system, configuring Mailgraph through labels becomes straightforward.

version: '3'

services:
  mailgraph:
    image: davidullrich/mailgraph:latest
    hostname: mail.example.com
    volumes:
      - /var/log/mail/mail.log:/var/log/mail/mail.log
      - /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mailgraph-router.rule=Host(`mail.example.com`) && PathPrefix(`/mailgraph`)"
      - "traefik.http.routers.mailgraph-router.entryPoints=websecure"
      - "traefik.http.routers.mailgraph-router.service=mailgraph-service"
      - "traefik.http.services.mailgraph-service.loadBalancer.server.scheme=http"
      - "traefik.http.services.mailgraph-service.loadBalancer.server.port=80"
      - "traefik.http.routers.mailgraph-router.middlewares=mailgraph-middleware-auth"
      - "traefik.http.middlewares.mailgraph-middleware-auth.basicauth.users=user:[password-hash]"

Dovecot Extension

As I use Dovecot as my IMAP server, I’ve extended Mailgraph to display the number of successful and failed IMAP logins.

Source Code and Docker Image

You can find the source code for the Docker image on GitHub, and the pre-built image is available on Docker Hub.