Portable Multi-Cloud Microservices in Java

Most cloud-agnostic microservices are portable right up to the first line that talks to the cloud.

Ask a team whether their services are cloud-agnostic and the answer is usually yes. They run in containers, they deploy to Kubernetes, the business logic is plain Java, and the infrastructure is in Terraform. Then ask what it would take to run one of those services on Azure instead of AWS, and the answer becomes a project plan.

Over the last few years more teams have had to answer that question for real. Some ship a product into each customer’s own cloud. Some are regulated, and rules such as the EU’s DORA, the UK PRA’s SS2/21 and APRA’s CPS 230 in Australia expect a realistic plan for leaving a cloud provider. Some have data that has to stay in a country where their main cloud isn’t the right fit. And some just want one service to use the best of two clouds at once.

The hard part isn’t Kubernetes or Terraform. It’s the code inside each service that stores a file, publishes a message, reads a secret or logs in to a database. That is where portability is usually lost. For engineers it means rewrites and surprises in production. For technology leaders it’s the gap between an exit strategy on paper and one the organisation could actually carry out.

Where portability is lost

A service starts on one cloud. The quickest path is that cloud’s SDK, or its Spring Cloud project:

@Service
class ReceiptService {
    private final S3Client s3;
    private final SqsTemplate sqs;

    void store(Order order, byte[] pdf) {
        s3.putObject(b -> b.bucket("acme-receipts").key(order.id() + ".pdf"),
                RequestBody.fromBytes(pdf));
        sqs.send("receipts-written", order.id());
    }

    Optional<byte[]> find(String orderId) {
        try {
            return Optional.of(s3.getObjectAsBytes(b -> b.bucket("acme-receipts").key(orderId + ".pdf"))
                    .asByteArray());
        } catch (NoSuchKeyException e) {
            return Optional.empty();
        }
    }
}

It’s clean, idiomatic and correct. Then a customer needs it on Azure. The usual answer is an interface with one implementation per cloud:

interface ReceiptStorage {
    void put(String key, byte[] content);
    Optional<byte[]> get(String key);
}

class S3ReceiptStorage implements ReceiptStorage { ... }
class AzureBlobReceiptStorage implements ReceiptStorage { ... }
class GcsReceiptStorage implements ReceiptStorage { ... }

That is the right instinct, and it’s where most teams stop. The real cost shows up when the second cloud goes to production.

The challenges with building multi-cloud services

1. Cloud SDKs leak past the interface

The interface hides S3Client, but each implementation reports failures in its own way. S3 throws NoSuchKeyException. Azure throws a BlobStorageException with an error code of BlobNotFound. Cloud Storage’s get returns null. Throttling, timeouts and permission errors are all different again. Unless someone maps every one of them carefully, they escape through the interface. Then a retry policy, a circuit breaker or a catch block somewhere upstream ends up knowing which cloud it’s running on.

Why it matters: cloud-specific code spreads beyond the adapters, so the cost of supporting another cloud keeps growing.

2. The same interface, different behaviour

Matching method signatures isn’t the same as matching behaviour, and behaviour is where the bugs are:

  • A conditional write (“only if nobody changed it since I read it”) needs ETags on S3, ETags with If-Match on Azure, and generation numbers on Cloud Storage. Each has its own edge cases.
  • A message published twice is deduplicated on an SNS FIFO topic, on a Service Bus entity with duplicate detection, and never on Pub/Sub.
  • DynamoDB, Cosmos DB and Firestore don’t keep a decimal’s scale, so 3.50 comes back as 3.5. Whether that matters depends on whether you print receipts.
  • Deleting a secret in AWS Secrets Manager doesn’t free its name straight away. Until AWS finishes the delete (18 seconds when I measured it), writing that name again fails.

The second implementation compiles, passes its unit tests and then behaves slightly differently in production. That is worse than not compiling.

Why it matters: these are the defects that reach customers, such as duplicate orders, lost updates and wrong amounts, and they appear only on the cloud you tested least.

3. Every cloud multiplies the code to build and test

Every adapter is new code against an SDK nobody on the team knows well. It needs its own tests, and in practice it gets fewer of them than the first one did. Running every combination against real services is slow and costs money, so most teams test the cloud they use most and hope the other two behave.

Why it matters: each extra cloud adds engineering time to every service, and that time goes into infrastructure code rather than features.

4. Every cloud has its own security model

Each cloud logs in differently: IAM roles, Microsoft Entra ID, Google service accounts. Databases, caches and Kafka make it worse, because the quick path is a password in a secret. That works on every cloud, but it means rotating passwords on every cloud. Logging in with a cloud identity is the better option, and each cloud does it differently: an RDS auth token, an Entra ID access token, a Cloud SQL IAM login.

Why it matters: long-lived passwords are a security risk and an audit finding, and three different identity models mean three times the chance of getting one wrong.

5. Lowest common denominator, or hidden differences

An abstraction has two bad ways to deal with features one cloud lacks. It can leave them out, so nobody gets presigned URLs because one provider can’t sign without the right credentials. Or it can quietly ignore them, so a “delayed” message is delivered at once on a provider that has no delays. The first makes the abstraction useless; the second makes it dangerous.

Why it matters: teams either lose the cloud features they pay for, or ship behaviour that silently differs between deployments.

6. The exit plan has never been tested

Put all of that together and the exit plan says “we use interfaces”. Nobody has run it. The first real test is a migration under time pressure, which is the worst time to find out that the Azure adapter never handled throttling.

Why it matters: regulators, auditors and boards increasingly ask for evidence that an exit is possible, not just a statement that it is.

The options today

The Java ecosystem has good tools here, and each solves a different part of the problem.

Spring Cloud AWS, Spring Cloud Azure and Spring Cloud GCP are excellent if a service will only ever run on one cloud. They are three separate projects with three separate APIs, though. S3Template, BlobServiceClient and Storage don’t share a type, so moving between them is still a rewrite.

Dapr gives every language one API through a sidecar, with components for many backends. That is a good fit for polyglot platforms, or if you want its workflows and actors. But it’s a second process next to every service, an extra network hop on every call, and behaviour varies between components.

MultiCloudJ offers a portable Java API across AWS, Google Cloud and Alibaba Cloud, but not Azure.

What none of them offer is one Java API, inside the application, that behaves the same on AWS, Azure and Google Cloud, with tests on each cloud to show that it does.

Seven principles for portable services

Whatever tools you use, these principles address the challenges above. None of them need a library; they are what the interface-per-cloud approach becomes once you take it seriously.

Principle 1: Put a portable seam at every cloud service

Every place the service touches the cloud gets an interface: one for object storage, one for documents, one for publishing, one for parameters and secrets, and so on. Business code depends only on those. The cloud SDK appears only behind them, in one adapter per cloud.

Principle 2: Port the behaviour, not just the signatures

The interface’s contract has to say what happens, not just what the method is called. Is delete idempotent? What order does a listing come back in? What does a conditional write compare? When does an entry expire? Each adapter has to do exactly that, even when its cloud’s natural behaviour is different.

Principle 3: One error model

Failures map to a small, closed set of portable errors: not found, already exists, precondition failed, access denied, throttled, unavailable. Each error says whether it’s retryable. Retry policies, circuit breakers and catch blocks are written once, against that set, and never see a native exception. The native exception stays attached as the cause, for logs.

Principle 4: Declare differences, don’t hide them

Where a cloud lacks a feature, the abstraction says so. Code can ask whether a feature is available. Asking a provider for a feature it doesn’t have fails loudly instead of being ignored. For anything really cloud-specific, there’s a documented way to reach the native client, kept in one place.

Principle 5: Identity, not passwords

Every login, including databases, caches and Kafka, uses the platform’s workload identity, found by each cloud’s default credential chain. There are no secrets to rotate, and the code doesn’t name the mechanism.

Principle 6: The cloud is configuration

Which cloud serves a resource is a deployment decision: a provider type, a region, a resource name. The same build, ideally the same container image, runs everywhere. Moving a single bucket or a single topic to another cloud is a configuration change.

Principle 7: One test suite, run against every cloud

The contract from Principle 2 is a test suite, and every adapter has to pass it. It runs against an in-memory implementation in unit tests, against emulators on every build, and against the real clouds on a schedule. Emulators don’t model IAM logins, throttling or eventual consistency. Those are exactly the things that fail in production.

Halyx: one API for AWS, Azure and Google Cloud

Building all of that for one service is a lot of work, and repeating it for every service is where the shortcuts creep back in. The principles belong in a library, built and tested once and shared by every service. That’s why I built Halyx, an open-source Java library (Java 21+, Apache 2.0) that implements all seven, with one API for cloud services on AWS, Azure and Google Cloud:

ServiceHalyx APIAWSAzureGoogle Cloud
Object storageBlobStoreS3Blob StorageCloud Storage
NoSQL documentsDocumentStoreDynamoDBCosmos DBFirestore
MessagingPublisher, SubscriptionSNS, SQSService BusPub/Sub
EventsEventPublisherEventBridgeEvent Grid namespacesEventarc Advanced
StreamsStreamProducer, StreamConsumerMSKEvent Hubs (Kafka endpoint)Managed Service for Apache Kafka
FunctionsFunctionInvokerLambdaAzure FunctionsCloud Run functions
SQLDatabaseRDS, AuroraAzure Database, Azure SQLCloud SQL
CachesCacheElastiCacheAzure Cache for Redis, Azure Managed RedisMemorystore
Parameters and secretsParameterStoreSSM, Secrets ManagerApp Configuration, Key VaultParameter Manager, Secret Manager
Keys and encryption*KeyStore, CryptoKeyKMSKey Vault keysCloud KMS

* Key management is available from Halyx 1.2.0.

HashiCorp Vault and an in-memory provider sit alongside them. It’s a library, not a platform: it runs inside your application, with no sidecar and no agent.

A seam for every service

Principle 1 is the API itself. The receipt service from the start of this post becomes:

@Service
class ReceiptService {
    private final BlobStore receipts;
    private final Publisher events;

    ReceiptService(@Qualifier("receipts") BlobStore receipts, @Qualifier("receipts-written") Publisher events) {
        this.receipts = receipts;
        this.events = events;
    }

    void store(Order order, byte[] pdf) {
        receipts.put(BlobKey.of(order.id() + ".pdf"), BlobContent.ofBytes(pdf));
        events.publish(OutgoingMessage.builder(order.id()).attribute("type", "receipted").build());
    }
}

There is no S3 in it, no Service Bus and no Pub/Sub, and no adapter classes to write. Under the hood, each API is a bridge to a driver per cloud. Validation, capability checks, interceptors and error translation live once, in the shared core, around every driver call, so a driver only has to talk to its cloud. halyx-core has no cloud SDK dependency, and the build enforces that.

The cloud is configuration

Principle 6 is a Spring profile per cloud. The resources are named once:

halyx:
  blob-stores:
    receipts: { bucket: acme-receipts }
  topics:
    receipts-written: { name: receipts-written }

---
spring.config.activate.on-profile: aws
halyx.providers.aws: { type: aws, region: eu-west-2 }

---
spring.config.activate.on-profile: azure
halyx.providers.azure:
  type: azure
  properties:
    azure.storage.account: acmereceipts
    azure.servicebus.namespace: acme

---
spring.config.activate.on-profile: gcp
halyx.providers.gcp:
  type: gcp
  properties:
    gcp.project-id: acme-prod

The same jar starts with SPRING_PROFILES_ACTIVE=aws, azure or gcp. Because each cloud is a named provider, one service can also use several at once, such as files on S3, a cache on Azure and events on Pub/Sub, through the same API.

The same behaviour, not just the same methods

Principle 2 is where most of the work in Halyx goes. A conditional write looks the same on every cloud and means the same:

PutResult v1 = receipts.put(key, content, PutOptions.builder().ifNotExists().build());

// later: replace it only if nobody else has
receipts.put(key, updated, PutOptions.builder().ifMatch(v1.etag()).build());

Listing order, idempotent deletes, versions, expiry, ordering and redelivery are defined once and implemented to match. Where a cloud is eventually consistent, Halyx doesn’t hide it by sleeping on your behalf. It fails fast with a retryable error, and you decide how to retry.

One error model

Principle 3 is a sealed hierarchy: NotFoundException, PreconditionFailedException, AccessDeniedException, ThrottledException, UnavailableException and a few others, all under CloudException. Providers can’t add types, so a switch over it stays exhaustive.

try (Blob blob = receipts.get(key)) {
    return Optional.of(blob.readAllBytes());
} catch (NotFoundException e) {
    return Optional.empty();       // NoSuchKey, BlobNotFound or a 404, whichever cloud
} catch (CloudException e) {
    if (e.isRetryable()) { ... }   // throttled or briefly unavailable, on any cloud
    throw e;
}

The native code is still there for your logs (e.providerErrorCode(), e.getCause()), but nothing has to branch on it.

Differences declared, with an escape hatch

Principle 4 is capabilities and unwrap. A feature one cloud lacks is a capability you can check, and asking for it where it’s missing throws UnsupportedFeatureException rather than doing nothing:

if (receipts.capabilities().supports(StorageCapability.PRESIGNED_URL)) {
    return receipts.presignDownload(key, Duration.ofMinutes(10)).uri();
}
return proxyDownload(key);

When you need something only one cloud has, every service except Database (which already gives you its JDBC pool) hands over the native client it’s already using, configured with the provider’s region, credentials and HTTP settings:

S3Client s3 = receipts.unwrap(S3Client.class);

On another cloud, that line fails clearly instead of doing something unexpected. Keep it behind your own interface and the rest of the service stays portable.

No passwords

Principle 5 applies to databases, caches and Kafka too. A PostgreSQL database logs in with an RDS IAM token, an Entra ID token or a Cloud SQL IAM login, and the pool fetches a fresh one as connections are made:

halyx:
  databases:
    orders:
      engine: postgresql
      host: ${ORDERS_DB_HOST}
      database: orders
      auth: { type: iam, username: orders_app }

You get a normal JDBC DataSource, so JdbcTemplate, JPA and Flyway work as usual. On Kubernetes, the pods log in with EKS Pod Identity, GKE Workload Identity Federation or Entra Workload ID. There are no keys in the cluster, and the code doesn’t name the mechanism.

It feels like Spring

The starter brings the things a Spring service expects: listeners, Spring Data repositories over document stores, @Cacheable, health indicators, Micrometer metrics and traces, and spring.config.import for parameters and secrets. It works on Spring Boot 3.5 and 4.

public interface OrderRepository extends DocumentRepository<Order, Key> {
    List<Order> findByCustomerIdOrderByOrderIdDesc(String customerId);
}

@HalyxListener("fulfilment")       // SQS, a Service Bus subscription or a Pub/Sub subscription
void onOrderPlaced(String body) { ... }

Returning from a listener acknowledges the message, and throwing redelivers it, the same way on every cloud.

One test suite, run on every cloud

Principle 7 is the part I think matters most, and the part that took the longest to build. Each service has a conformance kit, a shared test suite that defines what the API means. Every driver has to pass it:

  • in memory: the memory provider passes the same kits, so unit tests need no cloud and no containers:
    Halyx halyx = Halyx.builder().register("test", ProviderConfig.of("memory")).build();
    
  • on emulators, on every build: Floci for AWS, Azure and Google Cloud, Google’s Pub/Sub and Firestore emulators, Microsoft’s Service Bus emulator, and PostgreSQL, Valkey and Kafka in containers. Where an emulator doesn’t implement something, the gap is declared and the test reported as skipped, never quietly passed.
  • on real AWS, Azure and Google Cloud accounts, with the results published. The latest full run passed 220 to 240 tests per cloud for the serverless services alone, plus tiers for managed SQL, caches, Kafka and cloud logins, with no test relaxed for the real cloud.

The real-cloud runs earned their keep. Emulators missed every one of these:

  • AWS reporting some permission errors with a 400 status code, so they were mapped as invalid arguments.
  • Secrets Manager’s delete lag, and a listing that can see a new secret before a read can.
  • The Redis client resolving host names with its own DNS client, ignoring the JVM’s DNS settings.

Each of these is now handled in Halyx: the errors map correctly, the eventual consistency is declared and allowed for in the kits, and caches can opt in to the JVM’s own DNS resolution.

One image on three clusters

The portable orders sample puts it all together. It’s a Spring Boot service that uses object storage, documents through a Spring Data repository, messaging, events, Kafka streams, a cache, SQL with IAM login, and parameters and secrets. It’s built once, as one container image. Scripts deploy that same image to EKS, GKE and AKS, each against its cloud’s real services, check that the pods run the exact image that was pushed, and run the same end-to-end tests against each. The Helm values say what differs: the profile, the resource names and the workload identity binding. The code has no cloud-specific branches.

Challenges and solutions at a glance

ChallengeHow Halyx addresses it
Cloud SDKs leak past the interfaceOne API per service, with one driver per cloud behind it, and one error model with isRetryable(); halyx-core has no cloud SDK
The same interface, different behaviourBehaviour defined per service and checked by conformance kits on every provider
Every cloud multiplies the code to build and testNo adapters to write; the in-memory provider and emulators for your own tests
Every cloud has its own security modelIAM, Entra ID and Google IAM logins for databases, caches and Kafka; workload identity on Kubernetes
Lowest common denominator, or hidden differencesDeclared capabilities that fail loudly when missing, and unwrap for the native client
The exit plan has never been testedThe cloud is configuration, and the same tests pass on every cloud, real ones included

What Halyx doesn’t do

Halyx is deliberately focused, and it’s worth being clear about its limits.

It doesn’t create or manage infrastructure. Halyx never creates buckets, tables, topics, databases or keys. Terraform, Pulumi or whatever you already use stays in charge of that, and of IAM. Halyx uses what’s there.

It doesn’t move your data. Switching a bucket to another cloud is a configuration change for the code. Copying the objects, and the cost of egress while you do it, is still yours to plan.

It’s Java only. If you have services in several languages and want one API for all of them, Dapr is the better fit.

It doesn’t make clouds identical. Pub/Sub has no deduplication and Azure Functions have no asynchronous trigger. Halyx says so through capabilities rather than pretending otherwise. Some features stay cloud-specific, and unwrap is there for those. A service that uses a lot of them is still tied to that cloud, but now that’s visible, and kept in one place.

It isn’t a platform. There’s no control plane, console or service mesh. It’s a set of jars that run inside your application.

Halyx isn’t a replacement for Terraform or Kubernetes, or a way to avoid choosing a cloud. It makes the code in the middle as portable as the container around it, so the choice of cloud becomes a configuration decision you can actually change.

Trying it out

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.halyx</groupId>
            <artifactId>halyx-bom</artifactId>
            <version>1.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>dev.halyx</groupId>
        <artifactId>halyx-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>dev.halyx</groupId>
        <artifactId>halyx-aws</artifactId>   <!-- or halyx-azure, halyx-gcp, or all three -->
    </dependency>
</dependencies>

Use halyx-core with a provider module for plain Java. The documentation covers getting started, the API for each service, Spring Boot, the portable sample and the real-cloud results, and the roadmap shows what’s next. Next is key management in 1.2.0: envelope encryption and signing with AWS KMS, Azure Key Vault, Google Cloud KMS and Vault Transit, in one published format, so data sealed for keys on two clouds opens on either. Issues and contributions are welcome on GitHub.

Portability isn’t a property of the container or the Terraform. It’s a property of the code that talks to the cloud. Give that code a seam, port the behaviour as well as the signatures, and prove it with the same tests on every cloud. Do that, with Halyx or without it, and multi-cloud stops being a slide in a strategy deck and becomes something your teams can deliver.