Skip to main content
Before installing Metoro, you need to make several important architectural decisions. This checklist will guide you through the key choices and help you prepare for a successful deployment. It is worth taking some time to consider these options as changing the after installation can be complex and time-consuming as data migration may be required. If you aren’t sure about some of the options, get in touch with support, we’ll help you make the right choices based on your specific requirements.

​
1. Deployment Topology

​
Where will you run the Metoro Hub?

Best for
  • Proof of concepts
  • Development environments
  • Small production deployments
  • Cost-conscious deployments
Pros
  • Simpler setup
  • Lower infrastructure costs
  • Easier network configuration
Cons
  • If there is a cluster failure, its possible you will not be able to reach Metoro to debug the issue
  • Metoro competes for resources with your applications
  • Potential security concerns (observability data in same cluster)
  • Harder to monitor multiple clusters, requires cross-cluster connectivity
Best for
  • Production environments
  • Multi-cluster monitoring
  • High-security environments
  • Large-scale deployments
Pros
  • Isolated from application workloads
  • Can monitor multiple clusters
  • Better security posture
  • Dedicated resources for observability
Cons
  • Additional infrastructure costs
  • More complex networking setup
  • Requires cross-cluster connectivity

​
Architecture ramifications

Depending on your choice, the architecture will look different. Below are the two main options:

​
Option A: Same Cluster Architecture

​
Option B: Dedicated Cluster Architecture

​
2. PostgreSQL Database

​
How will you manage the metadata database?

Best for
  • Quick deployments
  • Development environments
  • When external database is not available
Pros
  • No external dependencies
  • Simplified installation
  • Included as a dependency in helm chart
Cons
  • Manual backup management
  • Limited high availability options
  • Requires persistent storage configuration
  • Manual upgrade process, tuning and maintenance
ConfigurationIf you want to use the in-cluster PostgreSQL, you can enable it in your values.yaml file like this:
postgresql:
  enabled: true
  persistence:
    size: 20Gi
  auth:
    password: "CHANGE_ME_SECURE_PASSWORD"
Required resources:
  • 2 CPU cores
  • 4GB RAM
  • 20GB+ persistent storage
Best for:
  • Production environments
  • High availability requirements
  • Existing database infrastructure
Pros:
  • Built in backup/restore
  • Built-in high availability
  • Better performance tuning
  • Reduced operational overhead
Cons:
  • Additional service costs
  • Potentially not available
Configuration:First, create the Kubernetes secret:
kubectl create secret generic postgres-external \
  --namespace metoro-hub \
  --from-literal=host="your-postgres.region.rds.amazonaws.com" \
  --from-literal=port="5432" \
  --from-literal=user="metoro_admin" \
  --from-literal=password="SECURE_PASSWORD" \
  --from-literal=database="metoro"
Then configure in values.yaml:
postgresql:
  enabled: false

postgresSecret:
  external:
    enabled: true
    secretName: "postgres-external"
    keys:
      host: "host"
      port: "port"
      user: "user"
      password: "password"
      database: "database"

# IMPORTANT: Temporal also needs to be configured to use the external database
temporal:
  enabled: true
  server:
    config:
      persistence:
        default:
          driver: sql
          sql:
            driver: postgres12
            database: temporal
            user: metoro_admin  # Same user as in the secret
            host: your-postgres.region.rds.amazonaws.com  # Same host as in the secret
            port: 5432
            password: ""  # Leave empty when using existingSecret
            existingSecret: "postgres-external"  # References the secret created above
        visibility:
          driver: sql
          sql:
            driver: postgres12
            database: temporal_visibility
            user: metoro_admin  # Same user as in the secret
            host: your-postgres.region.rds.amazonaws.com  # Same host as in the secret
            port: 5432
            password: ""  # Leave empty when using existingSecret
            existingSecret: "postgres-external"  # References the secret created above
Required databases:
  • metoro - Main application database
  • temporal - Workflow engine database
  • temporal_visibility - Workflow visibility database

​
3. ClickHouse Database

​
How will you manage the telemetry database?

Best for:
  • Self-contained deployments
  • When external ClickHouse is not available
  • Full control over configuration
Pros:
  • No external dependencies
  • Full configuration control
  • Included in helm chart
  • Less costly than managed services
Cons:
  • Complex to manage at scale (PBs of data)
  • Manual performance tuning at scale
  • Backup complexity
  • Storage management overhead
Configuration:First, create the Kubernetes secret:
kubectl create secret generic clickhouse-external \
  --namespace metoro-hub \
  --from-literal=password="CHANGE_ME_SECURE_PASSWORD" \
  --from-literal=user="metoro" \
  --from-literal=url="clickhouse://clickhouse-metoro:9440" \
  --from-literal=database="default"
Then configure in values.yaml:
clickhouse:
  enabled: true
  storage: 500Gi  # Start with 500GB for production
  replicaCount: 3  # For high availability
  credentials:
    external:
      enabled: true
      secretName: "clickhouse-external"
      key: "password"
  keeper:
    replicaCount: 3
    storage: 10Gi

# Also configure the clickhouseSecret to reference the same secret
clickhouseSecret:
  external:
    enabled: true
    secretName: "clickhouse-external"
    keys:
      user: "user"
      password: "password"
      url: "url"
      database: "database"

clickhouseSpecs:
  isOssClickhouse: true
  isSecure: false
Required resources:
  • 4+ CPU cores
  • 16GB+ RAM
  • 100GB+ fast SSD storage (scales with retention)
Best for:
  • Production environments
  • Large-scale deployments
  • When performance is critical
Pros:
  • Professional management
  • Automatic scaling options
  • Optimized performance
  • Built-in backup/restore
Cons:
  • Additional service costs
  • Vendor lock-in considerations
  • Network bandwidth costs
Configuration:First, create the Kubernetes secret:
kubectl create secret generic clickhouse-external \
  --namespace metoro-hub \
  --from-literal=url="clickhouse://your-clickhouse.region.clickhouse.cloud:9440" \
  --from-literal=user="metoro_user" \
  --from-literal=password="SECURE_PASSWORD" \
  --from-literal=database="metoro"
Then configure in values.yaml:
clickhouse:
  enabled: false

clickhouseSecret:
  external:
    enabled: true
    secretName: "clickhouse-external"
    keys:
      user: "user"
      password: "password"
      url: "url"
      database: "database"
Recommended providers:
  • ClickHouse Cloud
  • Altinity.Cloud
  • Self-managed ClickHouse cluster

​
Pre-Installation Tasks

Based on your decisions above, complete these tasks before installation:

​
If using dedicated cluster:

  • Provision management cluster
  • Configure network connectivity between clusters
  • Ensure there is an ingress controller

​
If using external PostgreSQL:

  • Provision PostgreSQL instance (v12+)
  • Create a user with full permissions
  • Configure network security groups/firewall rules so the PostgreSQL instance is accessible from the Kubernetes cluster
  • Create Kubernetes secret with database credentials (see configuration examples)

​
If using in-cluster PostgreSQL:

  • Ensure persistent storage class is available

​
If using external ClickHouse:

  • Provision ClickHouse instance/cluster (v25.4+)
  • Provision a ClickHouse user with full permissions
  • Configure network access from the Kubernetes cluster
  • Create Kubernetes secret with database credentials (see configuration examples)

​
If using in-cluster ClickHouse

  • Ensure persistent storage class is available

​
General preparation:

  • Install Helm 3.x
  • Obtain Metoro helm charts and image pull secrets from your Metoro representative

​
Next Steps

Once you’ve made these decisions and completed the preparation tasks:
  1. Proceed to the configuration guide to create your values.yaml file
  2. Follow the installation guide to deploy Metoro Hub on your Kubernetes cluster
Take time to make these decisions carefully. Changing deployment topology or database backends after installation requires significant migration effort.