feat(azure): add lowkey vault container

docs/modules/azure.md

@@ -24,6 +24,7 @@ The Azure module exposes the following Go packages:
 !!! warning "EULA Acceptance"
     Due to licensing restrictions you are required to explicitly accept an End User License Agreement (EULA) for the EventHubs container image. This is facilitated through the `WithAcceptEULA` function.
 - [CosmosDB](#cosmosdb): `github.com/testcontainers/testcontainers-go/modules/azure/cosmosdb`.
+- [Lowkey Vault](#lowkey-vault): `github.com/testcontainers/testcontainers-go/modules/azure/lowkeyvault`.
 <!--codeinclude-->
 [Creating a Azurite container](../../modules/azure/azurite/examples_test.go) inside_block:runAzuriteContainer
 <!--/codeinclude-->
@@ -353,3 +354,138 @@ Returns the connection string to connect to the CosmosDB container and an error,
 <!--codeinclude-->
 [Connect_CreateDatabase](../../modules/azure/cosmosdb/examples_test.go) inside_block:ExampleRun_connect
 <!--/codeinclude-->
+
+## Lowkey Vault
+
+### Run function
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+The Lowkey Vault module exposes one entrypoint function to create the Lowkey Vault container, and this function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*LowkeyVaultContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+
+#### Image
+
+Use the second argument in the `Run` function to set a valid Docker image.
+In example: `Run(context.Background(), "nagyesta/lowkey-vault:7.0.9-ubi10-minimal")`.
+
+### Container Options
+
+The Lowkey Vault container exposes two ports, one for the Key Vault API and one for the metadata endpoints such as the token endpoint.
+Since the Key Vault API supports multiple vaults and selects the active vault based on the host authority of the request URL, the 
+container can be configured in two ways:
+
+#### Local mode
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+The default mode is to run the Key Vault container on localhost, meaning that both the Key Vault API and the metadata endpoints are 
+exposed using random host ports, and the container is accessible only from the host machine. The default vault is automatically created 
+and is made available using the host address. 
+
+#### Network mode
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+To prepare the container for running in a network, and making it accessible from other containers in the network, you can use the 
+`WithNetworkAlias` option. For example:
+```golang
+Run(ctx, "nagyesta/lowkey-vault:7.0.9-ubi10-minimal",
+    lowkeyvault.WithNetworkAlias("lowkey-vault", aNetwork),
+)
+```
+
+### Container Methods
+
+The Lowkey Vault container exposes the following methods:
+
+#### ConnectionUrl
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+Returns the connection URL to connect to the Key Vault API of the Lowkey Vault container and an error, passing the Go context and an 
+`accessMode` as parameters. The access mode can be either `lowkeyvault.Local` or `lowkeyvault.Network` depending on the mode you wish
+to use to connect to the Key Vault API.
+
+#### TokenUrl
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+Returns the URL pointing to the token endpoint of the Lowkey Vault container and an error, passing the Go context and an `accessMode` 
+as parameters. The access mode can be either `lowkeyvault.Local` or `lowkeyvault.Network` depending on the mode you wish
+to use to access the token endpoint.
+
+#### SetManagedIdentityEnvVariables
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+Can return an error, passing the Go context as the only parameter. This method conveniently sets the environment variables required 
+to use managed identities with the Lowkey Vault container. When using the Azure Key Vault SDK for Go, you can authenticate with 
+managed identities by using the `azidentity.NewDefaultAzureCredential(nil)` as credential. In order for this authentication to work,
+we need to set two environment variables, `IDENTITY_ENDPOINT` and `IDENTITY_HEADER` on the machine where the client code is running.
+In case the client is running on the host, i.e. we are running the Lowkey Vault container in Local mode, this method can set both 
+environment variables automatically.
+
+#### PrepareClientForSelfSignedCert
+
+- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>
+
+Returns a `http.Client` and requires no parameters. This method can be used to prepare a `http.Client` for connecting to the Key Vault API 
+of the Lowkey Vault container using a self-signed certificate. This is necessary since the Lowkey Vault container uses a self-signed 
+certificate by default.
+
+### Examples
+
+#### Use the Secrets API in Local mode
+
+In the following example, we are starting the Lowkey Vault container in Local mode, set a secret and retrieve it using the Key Vault Secrets API.
+
+<!--codeinclude-->
+[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainer
+[Create Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheSecretClient
+[Set and get a secret](../../modules/azure/lowkeyvault/examples_test.go) inside_block:setAndFetchTheSecret
+<!--/codeinclude-->
+
+#### Use the Keys API in Local mode
+
+In the following example, we are starting the Lowkey Vault container in Local mode, create a key and encrypt and decrypt a message with it.
+
+<!--codeinclude-->
+[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainer
+[Create Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheKeyClient
+[Create a key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createKey
+[Encrypt a message with the key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:encryptMessage
+[Decrypt cipher text with the key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:decryptCipherText
+<!--/codeinclude-->
+
+#### Use the Certificates API in Local mode
+
+In the following example, we are starting the Lowkey Vault container in Local mode, create a certificate using the Key Vault Certificates
+API, and fetch the content of the certificate as a PKCS12 store using the Key Vault Secrets API.
+
+<!--codeinclude-->
+[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainer
+[Create Certificate Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheCertClient
+[Create a certificate](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createCertificate
+[Create Secret Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheSecretClient
+[Fetch the certificate details](../../modules/azure/lowkeyvault/examples_test.go) inside_block:fetchCertDetails
+<!--/codeinclude-->
+
+#### Use the Secrets API in Network mode
+
+In the following example, we are starting the Lowkey Vault container in Network mode and set the parameters of a Go client
+container which will be used to connect to the Key Vault API of the Lowkey Vault container in Network mode.
+
+<!--codeinclude-->
+[Run Lowkey Vault Container in Network mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainerWithNetwork
+[Get the endpoint details in Network mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:obtainEndpointUrls
+[Configure the client container](../../modules/azure/lowkeyvault/examples_test.go) inside_block:configureClient
+<!--/codeinclude-->

modules/azure/go.mod

@@ -5,25 +5,32 @@ go 1.24.0
 toolchain go1.24.7
 
 require (
-	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1
+	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0
+	github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1
 	github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos v1.4.1
 	github.com/Azure/azure-sdk-for-go/sdk/data/aztables v1.3.0
 	github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs v1.3.0
 	github.com/Azure/azure-sdk-for-go/sdk/messaging/azservicebus v1.8.0
+	github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates v1.4.0
+	github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys v1.4.0
+	github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets v1.4.0
 	github.com/Azure/azure-sdk-for-go/sdk/storage/azblob v1.6.0
 	github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue v1.0.0
 	github.com/docker/go-connections v0.6.0
 	github.com/stretchr/testify v1.11.1
 	github.com/testcontainers/testcontainers-go v0.40.0
 	github.com/testcontainers/testcontainers-go/modules/mssql v0.40.0
+	software.sslmate.com/src/go-pkcs12 v0.7.0
 )
 
 require (
 	dario.cat/mergo v1.0.2 // indirect
 	github.com/Azure/azure-sdk-for-go v68.0.0+incompatible // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
+	github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0 // indirect
 	github.com/Azure/go-amqp v1.3.0 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
@@ -40,9 +47,11 @@ require (
 	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0 // indirect
 	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
@@ -55,6 +64,7 @@ require (
 	github.com/morikuni/aec v1.0.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
@@ -68,10 +78,10 @@ require (
 	go.opentelemetry.io/otel v1.35.0 // indirect
 	go.opentelemetry.io/otel/metric v1.35.0 // indirect
 	go.opentelemetry.io/otel/trace v1.35.0 // indirect
-	golang.org/x/crypto v0.45.0 // indirect
-	golang.org/x/net v0.47.0 // indirect
-	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/text v0.31.0 // indirect
+	golang.org/x/crypto v0.47.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )