README.md

Lowkey Vault - Testcontainers

This is the root of the Java Testcontainers support library. Visit the Readme in the repo root for more information about the project in general.

Usage

Dependency

The Testcontainers specific dependencies can be found below. The following examples assume that Azure Key Vault Key client and Azure Key Vault Secret client, are already on your classpath.

Maven

<dependency>
    <groupId>com.github.nagyesta.lowkey-vault</groupId>
    <artifactId>lowkey-vault-testcontainers</artifactId>
    <version>RELEASE</version>
    <scope>test</scope>
</dependency>
<!-- In case you wish to use the provided Lowkey Vault Client too -->
<dependency>
    <groupId>com.github.nagyesta.lowkey-vault</groupId>
    <artifactId>lowkey-vault-client</artifactId>
    <version>RELEASE</version>
    <scope>test</scope>
</dependency>

Gradle

testImplementation 'com.github.nagyesta.lowkey-vault:lowkey-vault-testcontainers:+'
//In case you wish to use the provided Lowkey Vault Client too
testImplementation 'com.github.nagyesta.lowkey-vault:lowkey-vault-client:+'

Creating a container

The recommended way of creating a container is by using LowkeyVaultContainerBuilder.

Example auto-registering a vault

In this example we would like to register the https://default.localhost:8443 vault and let the container start using a random port on the host machine.

import org.testcontainers.utility.DockerImageName;
import com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainer;
import static com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainerBuilder.lowkeyVault;

class Test {
    public LowkeyVaultContainer startVault() {
        //Please consider using latest image regardless of the value in the example
        final DockerImageName imageName = DockerImageName.parse("nagyesta/lowkey-vault:<version>");
        final LowkeyVaultContainer lowkeyVaultContainer = lowkeyVault(imageName)
                .vaultNames(Set.of("default"))
                .build()
                .withImagePullPolicy(PullPolicy.defaultPolicy());
        lowkeyVaultContainer.start();
        return lowkeyVaultContainer;
    }
}

ARM builds

Tip

Lowkey Vault offers a multi-arch image variant too. You can find the relevant project here.

Example importing contents from file

In this example we are importing a file including the placeholder specific configuration and setting additional parameters to use a specific port on the host machine and disable automatic vault registration.

import org.testcontainers.utility.DockerImageName;
import com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainer;
import static com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainerBuilder.lowkeyVault;

class Test {
    public LowkeyVaultContainer startVault(final File importFile) {
        //Please consider using latest image regardless of the value in the example
        final DockerImageName imageName = DockerImageName.parse("nagyesta/lowkey-vault:<version>");
        final LowkeyVaultContainer lowkeyVaultContainer = lowkeyVault(imageName)
                .noAutoRegistration()  
                .importFile(importFile, BindMode.READ_ONLY)
                .logicalPort(8443)
                .logicalHost("127.0.0.1")
                .build()
                .withImagePullPolicy(PullPolicy.defaultPolicy());
        lowkeyVaultContainer.start();
        return lowkeyVaultContainer;
    }
}

Note

Since v2.7.0, the container can use a dynamically allocated port thanks to the relaxed port matching feature. This will ignore the port number when searching for a vault based on the request authority (essentially only matching based on the request's hostname).

Example using your own certificate file

In this example we are importing a custom SSL certificate from a key store file.

import org.testcontainers.utility.DockerImageName;
import com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainer;
import static com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainerBuilder.lowkeyVault;

class Test {
    public LowkeyVaultContainer startVault(final File certFile) {
        //Please consider using latest image regardless of the value in the example
        final DockerImageName imageName = DockerImageName.parse("nagyesta/lowkey-vault:<version>");
        final LowkeyVaultContainer lowkeyVaultContainer = lowkeyVault(imageName)
                .noAutoRegistration()
                .customSslCertificate(certFile, "password", StoreType.JKS)
                .hostPort(8443)
                .build()
                .withImagePullPolicy(PullPolicy.defaultPolicy());
        lowkeyVaultContainer.start();
        return lowkeyVaultContainer;
    }
}

Example using additional startup arguments

In this example we are passing through additional arguments to the container.

import org.testcontainers.utility.DockerImageName;
import com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainer;
import static com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainerBuilder.lowkeyVault;

class Test {
    public LowkeyVaultContainer startVault() {
        //Please consider using latest image regardless of the value in the example
        final DockerImageName imageName = DockerImageName.parse("nagyesta/lowkey-vault:<version>");
        final LowkeyVaultContainer lowkeyVaultContainer = lowkeyVault(imageName)
                .additionalArgs(List.of("--logging.level.root=INFO"))
                .build()
                .withImagePullPolicy(PullPolicy.defaultPolicy());
        lowkeyVaultContainer.start();
        return lowkeyVaultContainer;
    }
}

Example using aliases

In this example we are starting Lowkey vault with additional aliases (https://alias1 and https://alias2:8443) defined for the default vault named https://localhost:8443.

import org.testcontainers.utility.DockerImageName;
import com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainer;
import static com.github.nagyesta.lowkeyvault.testcontainers.LowkeyVaultContainerBuilder.lowkeyVault;

class Test {
    public LowkeyVaultContainer startVault() {
        //Please consider using latest image regardless of the value in the example
        final DockerImageName imageName = DockerImageName.parse("nagyesta/lowkey-vault:<version>");
        final LowkeyVaultContainer lowkeyVaultContainer = lowkeyVault(imageName)
                .vaultAliases(Map.of("localhost", Set.of("alias1", "alias2:8443")))
                .build()
                .withImagePullPolicy(PullPolicy.defaultPolicy());
        lowkeyVaultContainer.start();
        return lowkeyVaultContainer;
    }
}

Other examples

• Generic
• JUnit Jupiter