Skip to main content

Documentation Index

Fetch the complete documentation index at: https://platform.docs.zenoo.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Cloud Provider Configuration Reference

Complete reference for all configuration properties related to cloud provider support.

​
Provider Selection

​
hub.cloud.provider.type

Type: String Default: aws Options: aws, gcp, local, azure (future) 
hub:
  cloud:
    provider:
      type: aws  # or gcp, local
Selects which cloud provider implementation to use.
  • aws - Amazon Web Services (DynamoDB, Secrets Manager, CloudWatch)
  • gcp - Google Cloud Platform (Firestore, Secret Manager, Cloud Monitoring)
  • local - In-memory storage for development and testing

​
AWS Provider Configuration

​
Core AWS Settings

​
hub.aws.region

Type: String Required: Yes Example: us-east-1 
hub:
  aws:
    region: us-east-1
AWS region for all services.

​
hub.aws.accessKey

Type: String Optional: Yes (uses AWS default credential chain if omitted) 
hub:
  aws:
    accessKey: ${AWS_ACCESS_KEY_ID}
AWS access key ID. Prefer IAM roles over explicit credentials.

​
hub.aws.secretKey

Type: String Optional: Yes 
hub:
  aws:
    secretKey: ${AWS_SECRET_ACCESS_KEY}
AWS secret access key.

​
DynamoDB Configuration

​
hub.aws.dynamodb.prefix

Type: String Required: Yes Pattern: ^[\w.\-#{}]+$ 
hub:
  aws:
    dynamodb:
      prefix: zenoo-hub
Prefix for all DynamoDB table names. Creates tables: {prefix}-components, {prefix}-api-key-lookup, {prefix}-sharables.

​
hub.aws.dynamodb.endpoint

Type: String Optional: Yes Use Case: LocalStack or custom DynamoDB endpoint 
hub:
  aws:
    dynamodb:
      endpoint: http://localhost:4566

​
hub.aws.dynamodb.createTables

Type: Boolean Default: true 
hub:
  aws:
    dynamodb:
      createTables: true
Automatically create DynamoDB tables on startup.

​
hub.aws.dynamodb.tags

Type: Map<String, String> Optional: Yes 
hub:
  aws:
    dynamodb:
      tags:
        Environment: production
        CostCenter: engineering
        DataClassification: Restricted
Tags applied to all DynamoDB tables.

​
hub.aws.dynamodb.replicas

Type: List<String> Optional: Yes 
hub:
  aws:
    dynamodb:
      replicas:
        - us-west-2
        - eu-west-1
AWS regions for DynamoDB Global Table replication.

​
hub.aws.dynamodb.retryStrategy.requestTimeout

Type: Duration Default: 500ms 
hub:
  aws:
    dynamodb:
      retryStrategy:
        requestTimeout: 500ms
Timeout for individual DynamoDB requests.

​
hub.aws.dynamodb.retryStrategy.maxRetries

Type: Integer Default: 10 
hub:
  aws:
    dynamodb:
      retryStrategy:
        maxRetries: 10
Maximum number of retry attempts for failed requests.

​
hub.aws.dynamodb.retryStrategy.backoff

Type: Duration Default: 100ms 
hub:
  aws:
    dynamodb:
      retryStrategy:
        backoff: 100ms
Initial backoff duration for exponential retry.

​
Secrets Manager Configuration

​
hub.aws.secrets.prefix

Type: String Required: Yes 
hub:
  aws:
    secrets:
      prefix: zenoo-hub
Prefix for all secret names.

​
hub.aws.secrets.cache

Type: Boolean Default: true 
hub:
  aws:
    secrets:
      cache: true
Enable in-memory caching of secrets.

​
hub.aws.secrets.cacheTtl

Type: Duration Default: 300s (5 minutes) 
hub:
  aws:
    secrets:
      cacheTtl: 300s
Time-to-live for cached secrets.

​
hub.aws.secrets.forceDelete

Type: Boolean Default: false 
hub:
  aws:
    secrets:
      forceDelete: false
When true, deletes secrets immediately without recovery window. When false, uses AWS’s default 30-day recovery period.

​
hub.aws.secrets.tags

Type: Map<String, String> Optional: Yes 
hub:
  aws:
    secrets:
      tags:
        Environment: production
        DataClassification: HighlyRestricted
Tags applied to all secrets.

​
hub.aws.secrets.replicas

Type: List<String> Optional: Yes 
hub:
  aws:
    secrets:
      replicas:
        - us-west-2
        - eu-west-1
AWS regions for secret replication.

​
CloudWatch Metrics Configuration

​
hub.aws.dynamodb.metrics.enabled

Type: Boolean Default: true 
hub:
  aws:
    dynamodb:
      metrics:
        enabled: true
Enable CloudWatch metrics publishing.

​
hub.aws.dynamodb.metrics.namespace

Type: String Default: ZenooHub 
hub:
  aws:
    dynamodb:
      metrics:
        namespace: ZenooHub
CloudWatch namespace for metrics.

​
Local Provider Configuration

The local provider uses in-memory storage and requires minimal configuration.

​
hub.cloud.provider.type

Type: String Value: local Required: Yes (to activate local provider) 
hub:
  cloud:
    provider:
      type: local
Activates the local provider for in-memory storage.

​
hub.local.cleanupEnabled

Type: Boolean Default: true 
hub:
  local:
    cleanupEnabled: true
Enables automatic cleanup of expired sharables. When enabled, a background task periodically removes expired tokens from the sharable store. Note: Cleanup only applies to sharables, not components or configurations.

​
hub.local.cleanupInterval

Type: Duration Default: 5m (5 minutes) Supported Units: ms (milliseconds), s (seconds), m (minutes), h (hours), d (days) 
hub:
  local:
    cleanupInterval: 5m
Interval between cleanup runs. Shorter intervals reduce memory usage but increase CPU overhead. Longer intervals reduce CPU overhead but may accumulate expired sharables. Recommendations:
  • Development: 5m (default)
  • Integration tests: 1m (faster cleanup)
  • CI/CD: 30s (aggressive cleanup)
  • Disabled: Set cleanupEnabled: false

​
hub.local.verboseLogging

Type: Boolean Default: false 
hub:
  local:
    verboseLogging: true
Enables detailed logging for debugging. When enabled, logs all storage operations:
  • Component create/update/delete
  • API key associations
  • Secret operations
  • Sharable store operations
  • Cleanup activities
Use Cases:
  • Debugging storage issues
  • Understanding data flow
  • Learning the local provider
  • Troubleshooting tests
Warning: Generates significant log volume in production-like scenarios. Only enable for debugging.

​
hub.local.simulatedDelay

Type: Duration Default: 0ms (no delay) Optional: Yes 
hub:
  local:
    simulatedDelay: 10ms
Introduces artificial delay to simulate network latency. Useful for testing timeout handling and async behavior. Use Cases:
  • Testing timeout configurations
  • Simulating slow storage
  • Load testing with realistic latency
  • Validating retry logic
Note: Only use in testing scenarios. Do not enable in production.

​
Complete Local Configuration Example

Minimal (Development): 
hub:
  cloud:
    provider:
      type: local
With Optional Settings: 
hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: true
    cleanupInterval: 5m
    verboseLogging: false
    simulatedDelay: 0ms
Integration Testing: 
hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: true
    cleanupInterval: 1m      # Faster cleanup
    verboseLogging: false
    simulatedDelay: 0ms
Debugging: 
hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: true
    cleanupInterval: 10m
    verboseLogging: true     # See all operations
    simulatedDelay: 0ms
Latency Testing: 
hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: false    # Disable for performance
    verboseLogging: false
    simulatedDelay: 50ms     # Simulate network latency

​
Switching Between Local and AWS

Local Development Profile (application-local.yml): 
hub:
  cloud:
    provider:
      type: local

  local:
    cleanupEnabled: true
    cleanupInterval: 5m
AWS Production Profile (application-aws.yml): 
hub:
  cloud:
    provider:
      type: aws

  aws:
    region: us-east-1
    dynamodb:
      prefix: my-hub
      createTables: true
    secrets:
      prefix: my-hub
Activate with: 
# Local
./gradlew bootRun --args='--spring.profiles.active=local'

# AWS
./gradlew bootRun --args='--spring.profiles.active=aws'

# GCP
./gradlew bootRun --args='--spring.profiles.active=gcp'

​
GCP Provider Configuration

The GCP provider uses Cloud Firestore (Native Mode), Secret Manager, and Cloud Monitoring for full cloud-based storage.

​
Core GCP Settings

​
hub.cloud.provider.type

Type: String Value: gcp Required: Yes (to activate GCP provider) 
hub:
  cloud:
    provider:
      type: gcp
Activates the GCP provider for Cloud Firestore storage and Secret Manager.

​
hub.gcp.projectId

Type: String Required: Yes 
hub:
  gcp:
    projectId: your-gcp-project-id
GCP project ID where Firestore and Secret Manager resources will be created.

​
hub.gcp.credentialsLocation

Type: String Optional: Yes (uses Application Default Credentials if omitted) 
hub:
  gcp:
    credentialsLocation: /path/to/service-account-key.json
Path to service account key JSON file. If omitted, uses Application Default Credentials (ADC) which automatically detects credentials from:
  • GOOGLE_APPLICATION_CREDENTIALS environment variable
  • gcloud auth application-default login credentials
  • Attached service account on GCE, GKE, or Cloud Run
  • Compute Engine metadata service
Best Practice: Prefer ADC over explicit key files for better security.

​
hub.gcp.enabled

Type: Boolean Default: true 
hub:
  gcp:
    enabled: true
Enable or disable GCP provider. Set to false to temporarily disable GCP provider without changing provider type.

​
Cloud Firestore Configuration

​
hub.gcp.firestore.database

Type: String Default: "(default)" 
hub:
  gcp:
    firestore:
      database: "(default)"
Firestore database name. Use "(default)" for the default database, or specify a custom database name. Important: Hub requires Firestore in Native Mode, not Datastore Mode.

​
hub.gcp.firestore.prefix

Type: String Default: "zenoo-hub" Pattern: ^[\w-]+$ 
hub:
  gcp:
    firestore:
      prefix: "zenoo-hub"
Prefix for all Firestore collection names. Creates collections:
  • {prefix}-components - Component definitions with versioning
  • {prefix}-api-keys - API key lookup mappings
  • {prefix}-sharables - Temporary sharable tokens

​
hub.gcp.firestore.createIndexes

Type: Boolean Default: true 
hub:
  gcp:
    firestore:
      createIndexes: true
Automatically create composite indexes for complex queries. Set to false if you prefer to manage indexes manually via Firebase Console or firestore.indexes.json.

​
hub.gcp.firestore.ttlEnabled

Type: Boolean Default: true 
hub:
  gcp:
    firestore:
      ttlEnabled: true
Enable Time-To-Live (TTL) field for automatic cleanup of expired sharables. When enabled, Firestore automatically deletes documents when the TTL timestamp is reached.

​
hub.gcp.firestore.ttlField

Type: String Default: "ttl" 
hub:
  gcp:
    firestore:
      ttlField: "ttl"
Name of the TTL field in sharable documents. Must match the TTL policy configured in Firestore.

​
hub.gcp.firestore.retryStrategy.requestTimeout

Type: Duration Default: 500ms Supported Units: ms, s, m, h 
hub:
  gcp:
    firestore:
      retryStrategy:
        requestTimeout: 500ms
Per-request timeout for Firestore operations. Increase for large documents or slow networks.

​
hub.gcp.firestore.retryStrategy.maxRetries

Type: Integer Default: 10 
hub:
  gcp:
    firestore:
      retryStrategy:
        maxRetries: 10
Maximum number of retry attempts for transient errors (e.g., UNAVAILABLE, DEADLINE_EXCEEDED).

​
hub.gcp.firestore.retryStrategy.backoff

Type: Duration Default: 100ms 
hub:
  gcp:
    firestore:
      retryStrategy:
        backoff: 100ms
Base duration for exponential backoff between retries. Actual backoff increases exponentially: 100ms, 200ms, 400ms, etc.

​
Secret Manager Configuration

​
hub.gcp.secrets.prefix

Type: String Default: "zenoo-hub" Pattern: ^[\w-/]+$ 
hub:
  gcp:
    secrets:
      prefix: "zenoo-hub"
Prefix for all Secret Manager secret names. Creates secrets:
  • {prefix}/component-config/{key}/{version} - Component configuration
  • {prefix}/api-key/{keyName} - API key secrets

​
hub.gcp.secrets.cacheSize

Type: Integer Default: 128 
hub:
  gcp:
    secrets:
      cacheSize: 128
Maximum number of secrets to cache in memory (Caffeine cache). Increase for applications with many configuration keys to reduce Secret Manager API calls.

​
hub.gcp.secrets.cacheExpiry

Type: Duration Default: 30m Supported Units: ms, s, m, h, d 
hub:
  gcp:
    secrets:
      cacheExpiry: 30m
Time-to-live for cached secrets. Balance between freshness (shorter TTL) and API cost reduction (longer TTL).

​
hub.gcp.secrets.versionsLimit

Type: Integer Default: 18 
hub:
  gcp:
    secrets:
      versionsLimit: 18
Maximum number of versions to keep per secret. When limit is reached, oldest versions are automatically deleted. Increase for more extensive version history, decrease to reduce storage costs.

​
hub.gcp.secrets.forceDelete

Type: Boolean Default: true 
hub:
  gcp:
    secrets:
      forceDelete: true
Immediate deletion of secrets vs 30-day recovery window.
  • true - Secrets deleted immediately (cannot be recovered)
  • false - Secrets scheduled for deletion after 30 days (can be recovered)
Recommendation: Use false for production environments to enable recovery.

​
hub.gcp.secrets.retryStrategy.requestTimeout

Type: Duration Default: 2s 
hub:
  gcp:
    secrets:
      retryStrategy:
        requestTimeout: 2s
Per-request timeout for Secret Manager operations. Longer than Firestore timeout to handle eventual consistency.

​
hub.gcp.secrets.retryStrategy.maxRetries

Type: Integer Default: 5 
hub:
  gcp:
    secrets:
      retryStrategy:
        maxRetries: 5
Maximum retry attempts for Secret Manager operations.

​
hub.gcp.secrets.retryStrategy.backoff

Type: Duration Default: 200ms 
hub:
  gcp:
    secrets:
      retryStrategy:
        backoff: 200ms
Base duration for exponential backoff between retries.

​
Cloud Monitoring Configuration

​
hub.gcp.metrics.enabled

Type: Boolean Default: true 
hub:
  gcp:
    metrics:
      enabled: true
Enable Cloud Monitoring metrics publishing. Set to false to disable metrics (reduces API calls and costs).

​
hub.gcp.metrics.prefix

Type: String Default: "hub" 
hub:
  gcp:
    metrics:
      prefix: "hub"
Prefix for custom metric names in Cloud Monitoring.

​
hub.gcp.metrics.batchSize

Type: Integer Default: 200 Maximum: 200 (GCP limit) 
hub:
  gcp:
    metrics:
      batchSize: 200
Maximum number of time series to send per Cloud Monitoring API request. GCP limit is 200.

​
Complete GCP Configuration Examples

​
Minimal GCP Configuration (Development)

Uses Application Default Credentials and all defaults: 
hub:
  cloud:
    provider:
      type: gcp
  gcp:
    projectId: dev-project-123

​
Production GCP Configuration

Full production configuration with service account key: 
hub:
  cloud:
    provider:
      type: gcp
  gcp:
    projectId: prod-project-456
    credentialsLocation: /run/secrets/gcp-sa-key.json

    firestore:
      prefix: "hub-prod"
      database: "(default)"
      createIndexes: true
      ttlEnabled: true
      retryStrategy:
        requestTimeout: 1s
        maxRetries: 15
        backoff: 100ms

    secrets:
      prefix: "hub-prod"
      cacheSize: 256
      cacheExpiry: 1h
      versionsLimit: 30
      forceDelete: false        # Enable 30-day recovery
      retryStrategy:
        requestTimeout: 2s
        maxRetries: 5
        backoff: 200ms

    metrics:
      enabled: true
      prefix: "hub-prod"
      batchSize: 200

​
High Performance GCP Configuration

Optimized for throughput: 
hub:
  cloud:
    provider:
      type: gcp
  gcp:
    projectId: perf-project-789

    firestore:
      prefix: "hub-perf"
      retryStrategy:
        requestTimeout: 500ms
        maxRetries: 20
        backoff: 50ms           # Faster retries

    secrets:
      cacheSize: 512            # Larger cache
      cacheExpiry: 2h           # Longer TTL
      versionsLimit: 50

    metrics:
      batchSize: 200            # Max batch size

​
Multi-Environment GCP Profile Example

GCP Development Profile (application-gcp-dev.yml): 
hub:
  cloud:
    provider:
      type: gcp

  gcp:
    projectId: hub-dev-project
    firestore:
      prefix: "hub-dev"
    secrets:
      prefix: "hub-dev"
      forceDelete: true         # Immediate deletion for dev
    metrics:
      enabled: false            # Reduce costs in dev
GCP Production Profile (application-gcp-prod.yml): 
hub:
  cloud:
    provider:
      type: gcp

  gcp:
    projectId: hub-prod-project
    credentialsLocation: /run/secrets/gcp-sa-key.json
    firestore:
      prefix: "hub-prod"
      createIndexes: true
    secrets:
      prefix: "hub-prod"
      cacheSize: 256
      cacheExpiry: 1h
      forceDelete: false        # Enable recovery
    metrics:
      enabled: true
Activate with: 
# Development
./gradlew bootRun --args='--spring.profiles.active=gcp-dev'

# Production
./gradlew bootRun --args='--spring.profiles.active=gcp-prod'

​
Component Storage Configuration

​
hub.cloud.provider.component.operationTimeout

Type: Duration Default: 30s 
hub:
  cloud:
    provider:
      component:
        operationTimeout: 30s
Timeout for component storage operations.

​
Sharable Storage Configuration

​
hub.cloud.provider.sharable.operationTimeout

Type: Duration Default: 10s 
hub:
  cloud:
    provider:
      sharable:
        operationTimeout: 10s
Timeout for sharable token operations.

​
hub.cloud.provider.sharable.defaultTtl

Type: Duration Default: 24h 
hub:
  cloud:
    provider:
      sharable:
        defaultTtl: 24h
Default time-to-live for sharable tokens.

​
Configuration Examples

​
Minimal Production Configuration

hub:
  aws:
    region: us-east-1
    dynamodb:
      prefix: prod-hub
      createTables: true
    secrets:
      prefix: prod-hub

​
Development with LocalStack

hub:
  aws:
    region: us-east-1
    accessKey: test
    secretKey: test
    dynamodb:
      endpoint: http://localhost:4566
      prefix: dev-hub
      createTables: true
    secrets:
      endpoint: http://localhost:4566
      prefix: dev-hub

​
Multi-Region Production

hub:
  cloud:
    provider:
      type: aws
      component:
        operationTimeout: 30s
      sharable:
        operationTimeout: 10s
        defaultTtl: 24h

  aws:
    region: us-east-1
    dynamodb:
      prefix: prod-hub
      createTables: true
      replicas:
        - us-west-2
        - eu-west-1
      tags:
        Environment: production
        CostCenter: engineering
      retryStrategy:
        requestTimeout: 500ms
        maxRetries: 10
        backoff: 100ms
    secrets:
      prefix: prod-hub
      cache: true
      cacheTtl: 600s
      replicas:
        - us-west-2
        - eu-west-1
      tags:
        Environment: production
        DataClassification: HighlyRestricted

​
High-Performance Configuration

hub:
  cloud:
    provider:
      type: aws
      component:
        operationTimeout: 15s  # Reduced timeout
      sharable:
        operationTimeout: 5s   # Reduced timeout

  aws:
    region: us-east-1
    dynamodb:
      prefix: fast-hub
      retryStrategy:
        requestTimeout: 300ms  # Aggressive timeout
        maxRetries: 5          # Fewer retries
        backoff: 50ms          # Faster backoff
    secrets:
      prefix: fast-hub
      cache: true
      cacheTtl: 900s          # Longer cache (15 min)

​
Environment Variable Substitution

All configuration properties support Spring Boot’s property placeholder syntax: 
hub:
  aws:
    region: ${AWS_REGION:us-east-1}
    dynamodb:
      prefix: ${HUB_TABLE_PREFIX:zenoo-hub}
      endpoint: ${DYNAMODB_ENDPOINT:}
    secrets:
      prefix: ${HUB_SECRET_PREFIX:zenoo-hub}

​
Profile-Specific Configuration

Use Spring profiles for environment-specific settings: 
# application.yml (common)
hub:
  aws:
    dynamodb:
      createTables: true

---
# application-dev.yml
hub:
  aws:
    region: us-east-1
    dynamodb:
      endpoint: http://localhost:4566
      prefix: dev-hub

---
# application-staging.yml
hub:
  aws:
    region: us-east-1
    dynamodb:
      prefix: staging-hub

---
# application-prod.yml
hub:
  aws:
    region: us-east-1
    dynamodb:
      prefix: prod-hub
      replicas:
        - us-west-2

​
Configuration Precedence

Configuration sources in order of precedence (highest to lowest):
  1. Command-line arguments: --hub.aws.region=us-west-2
  2. Environment variables: HUB_AWS_REGION=us-west-2
  3. Profile-specific files: application-prod.yml
  4. Application properties: application.yml
  5. Default values

​
See Also