Pre-Installation Checklist - Metoro Documentation

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?

Option A: Same cluster as monitored workloads

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

Option B: Dedicated cluster for Metoro

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?

Option A: In-cluster PostgreSQL

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

Option B: External managed PostgreSQL

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?

Option A: In-cluster ClickHouse

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)

Option B: External managed ClickHouse

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:

Proceed to the configuration guide to create your values.yaml file
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.

​1. Deployment Topology

​Where will you run the Metoro Hub?

​Architecture ramifications

​Option A: Same Cluster Architecture

​Option B: Dedicated Cluster Architecture

​2. PostgreSQL Database

​How will you manage the metadata database?

​3. ClickHouse Database

​How will you manage the telemetry database?

​Pre-Installation Tasks

​If using dedicated cluster:

​If using external PostgreSQL:

​If using in-cluster PostgreSQL:

​If using external ClickHouse:

​If using in-cluster ClickHouse

​General preparation:

​Next Steps

1. Deployment Topology

Where will you run the Metoro Hub?

Architecture ramifications

Option A: Same Cluster Architecture

Option B: Dedicated Cluster Architecture

2. PostgreSQL Database

How will you manage the metadata database?

3. ClickHouse Database

How will you manage the telemetry database?

Pre-Installation Tasks

If using dedicated cluster:

If using external PostgreSQL:

If using in-cluster PostgreSQL:

If using external ClickHouse:

If using in-cluster ClickHouse

General preparation:

Next Steps