Implementing Cloud Providers

Guide for implementing support for new cloud providers (Azure, GCP, or custom infrastructure).

Overview

Adding a new cloud provider requires:

Implementing cloud-provider-api interfaces
Mapping provider exceptions to CloudProviderException
Creating Spring Boot autoconfiguration
Writing tests

Reference Implementations

Before implementing a new provider, review existing implementations:

Local Provider (Simple Reference)

Module: cloud-provider-local The local provider is the simplest complete implementation and serves as an excellent reference: Advantages as a reference:

Single module (easier to understand)
No external dependencies (focus on core interfaces)
Simple storage (ConcurrentHashMap)
Clear error handling patterns
Well-commented code
Complete test coverage

Key classes to study:

cloud-provider-local/
├── store/
│   ├── LocalComponentStore.java          # ComponentStore implementation
│   ├── LocalApiKeyStore.java             # ApiKeyStore implementation
│   └── LocalSharableStore.java           # SharableStore implementation
├── secret/
│   └── LocalApiKeySecretStorage.java     # ApiKeySecretStorage implementation
├── config/
│   ├── LocalComponentConfigStorage.java  # ComponentConfigStorage implementation
│   └── LocalComponentConfigReader.java   # Synchronous config reader
├── support/
│   └── LocalStoreSupport.java            # Base class with error handling
└── autoconfigure/
    ├── LocalCloudProviderAutoConfiguration.java
    ├── LocalProviderConfig.java
    └── SharableCleanupScheduler.java

Example: Simple ComponentStore:

@Service
public class LocalComponentStore extends LocalStoreSupport
                                 implements ComponentStore {

    private final ConcurrentHashMap<String, StringComponent> components =
        new ConcurrentHashMap<>();

    @Override
    public Mono<StringComponent> get(ComponentId id) {
        return wrapWithErrorHandling(
            Mono.fromCallable(() -> {
                ComponentId resolvedId = resolveLatestRevision(id);
                StringComponent component = components.get(toKey(resolvedId));
                if (component == null) {
                    throw new NoSuchElementException("Component not found: " + id);
                }
                return component;
            }),
            "get component",
            id.getName()
        );
    }

    // Error handling in base class (LocalStoreSupport)
    protected Throwable wrapException(Throwable throwable) {
        if (throwable instanceof NoSuchElementException) {
            return new StorageException(
                throwable.getMessage(),
                throwable,
                CloudProviderException.ErrorType.NOT_FOUND
            );
        }
        // ... other mappings
    }
}

Study these patterns:

Error Handling - LocalStoreSupport.wrapWithErrorHandling()
Exception Mapping - Java exceptions -> CloudProviderException
Reactive Wrapping - Mono.fromCallable() for synchronous operations
LATEST Resolution - resolveLatestRevision() pattern
Auto-Configuration - Conditional bean creation

AWS Provider (Production Reference)

Module: cloud-provider-aws (4 submodules) The AWS provider is a production-ready implementation showing advanced patterns: Advantages as a reference:

Real-world external service integration (DynamoDB, Secrets Manager)
Advanced error handling and retries
Multi-region support
Metrics publishing (CloudWatch)
Production-grade testing

Module structure:

cloud-provider-aws/
├── aws-stores/              # DynamoDB storage implementations
├── aws-secrets/             # Secrets Manager implementations
├── aws-metrics/             # CloudWatch metrics
└── aws-spring-boot-starter/ # Auto-configuration

Study these patterns:

SDK Integration - AWS SDK v2 async client usage
Retry Logic - Exponential backoff for transient errors
Connection Pooling - Managing client lifecycle
Metric Publishing - CloudWatch integration
Multi-Module Structure - When to split providers

View AWS provider documentation

Choosing a Reference

Aspect	Local Provider	AWS Provider
Complexity	Simple	Complex
Lines of Code	~1,500	~5,000
External Deps	None	AWS SDK, DynamoDB, Secrets Manager
Module Structure	Single	4 submodules
Best for Learning	Core patterns	Production patterns
Best for Starting	Yes	Use as second reference

Recommendation: Start with the local provider to understand core patterns, then review AWS provider for production considerations.

Module Structure

Create a new module following the pattern:

cloud-provider-{name}/
├── {name}-stores/
│   └── src/main/java/com/zenoo/hub/cloudprovider/{name}/stores/
├── {name}-secrets/
│   └── src/main/java/com/zenoo/hub/cloudprovider/{name}/secrets/
├── {name}-metrics/
│   └── src/main/java/com/zenoo/hub/cloudprovider/{name}/metrics/
└── {name}-spring-boot-starter/
    └── src/main/java/com/zenoo/hub/cloudprovider/{name}/autoconfigure/

Implementing Storage Interfaces

ComponentStore Implementation

@Service
public class AzureComponentStore implements ComponentStore {

    private final CosmosClient cosmosClient;

    @Override
    public Mono<StringComponent> get(ComponentId id) {
        return Mono.defer(() -> {
            try {
                var response = cosmosClient
                    .getDatabase(databaseName)
                    .getContainer(containerName)
                    .readItem(id.getFullName(),
                             new PartitionKey(id.getName()),
                             ComponentRecord.class);
                return Mono.just(response.getItem().toStringComponent());
            } catch (CosmosException e) {
                return Mono.error(mapException(e));
            }
        });
    }

    private Throwable mapException(CosmosException e) {
        if (e.getStatusCode() == 404) {
            return new StorageException(
                "Component not found",
                e,
                CloudProviderException.ErrorType.NOT_FOUND
            );
        }
        return new StorageException(
            "Storage error",
            e,
            CloudProviderException.ErrorType.SERVICE_ERROR
        );
    }
}

SharableStore Implementation

@Service
public class AzureSharableStore implements SharableStore {

    @Override
    public Mono<SharableRecord> get(String token) {
        // Implementation using Azure Cosmos DB or Table Storage
    }

    @Override
    public Mono<String> store(SharableRecord record) {
        // Implementation with TTL support
    }
}

Implementing Configuration Interfaces

ComponentConfigStorage Implementation

@Service
public class AzureComponentConfigStorage implements ComponentConfigStorage {

    private final SecretClient secretClient;

    @Override
    public Mono<String> get(ComponentConfigId configId) {
        return Mono.defer(() -> {
            try {
                KeyVaultSecret secret = secretClient.getSecret(
                    buildSecretName(configId)
                );
                return Mono.just(secret.getValue());
            } catch (ResourceNotFoundException e) {
                return Mono.empty();
            } catch (Exception e) {
                return Mono.error(mapException(e));
            }
        });
    }
}

Spring Boot Autoconfiguration

Main Configuration Class

@AutoConfiguration
@ConditionalOnClass(CosmosClient.class)
@ConditionalOnProperty(
    name = "hub.cloud.provider.type",
    havingValue = "azure"
)
@Import({
    AzureStoresAutoConfiguration.class,
    AzureSecretsAutoConfiguration.class
})
public class AzureCloudProviderAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public CosmosClient cosmosClient(AzureConfig config) {
        return new CosmosClientBuilder()
            .endpoint(config.getEndpoint())
            .key(config.getKey())
            .buildClient();
    }
}

Register Autoconfiguration

Create META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports:

com.zenoo.hub.cloudprovider.azure.autoconfigure.AzureCloudProviderAutoConfiguration

Configuration Properties

@Data
@Validated
@ConfigurationProperties(prefix = "hub.azure")
public class AzureConfig {
    @NotBlank
    private String endpoint;

    @NotBlank
    private String key;

    @NotBlank
    private String databaseName;
}

Testing

Unit Tests

@ExtendWith(MockitoExtension.class)
class AzureComponentStoreTest {

    @Mock
    private CosmosClient cosmosClient;

    private AzureComponentStore store;

    @Test
    void shouldGetComponent() {
        // Test implementation
    }
}

Integration Tests

Use Test Containers or Azure emulator for integration tests.

Example: Azure Provider Structure

// Configuration
@ConfigurationProperties("hub.azure")
public class AzureConfig {
    String endpoint;
    String key;
}

// Component Store
@Service
public class AzureComponentStore implements ComponentStore {
    // Cosmos DB implementation
}

// Secrets Management
@Service
public class AzureKeyVaultStorage implements ApiKeySecretStorage {
    // Key Vault implementation
}

// Autoconfiguration
@AutoConfiguration
@ConditionalOnProperty(name = "hub.cloud.provider.type", havingValue = "azure")
public class AzureCloudProviderAutoConfiguration {
    // Bean definitions
}

Hub Backend

Hub Client

Implementing Cloud Providers

Implementing Cloud Providers

Overview

Reference Implementations

Local Provider (Simple Reference)

AWS Provider (Production Reference)

Choosing a Reference

Module Structure

Implementing Storage Interfaces

ComponentStore Implementation

SharableStore Implementation

Implementing Configuration Interfaces

ComponentConfigStorage Implementation

Spring Boot Autoconfiguration

Main Configuration Class

Register Autoconfiguration

Configuration Properties

Testing

Unit Tests

Integration Tests

Example: Azure Provider Structure

See Also

​Implementing Cloud Providers

​Overview

​Reference Implementations

​Local Provider (Simple Reference)

​AWS Provider (Production Reference)

​Choosing a Reference

​Module Structure

​Implementing Storage Interfaces

​ComponentStore Implementation

​SharableStore Implementation

​Implementing Configuration Interfaces

​ComponentConfigStorage Implementation

​Spring Boot Autoconfiguration

​Main Configuration Class

​Register Autoconfiguration

​Configuration Properties

​Testing

​Unit Tests

​Integration Tests

​Example: Azure Provider Structure

​See Also

Implementing Cloud Providers

Overview

Reference Implementations

Local Provider (Simple Reference)

AWS Provider (Production Reference)

Choosing a Reference

Module Structure

Implementing Storage Interfaces

ComponentStore Implementation

SharableStore Implementation

Implementing Configuration Interfaces

ComponentConfigStorage Implementation

Spring Boot Autoconfiguration

Main Configuration Class

Register Autoconfiguration

Configuration Properties

Testing

Unit Tests

Integration Tests

Example: Azure Provider Structure

See Also