> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-Installation Checklist

> Key decisions to make before installing Metoro on-premises

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?

<AccordionGroup>
  <Accordion title="Option A: Same cluster as monitored workloads" icon="layer-group">
    **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
  </Accordion>

  <Accordion title="Option B: Dedicated cluster for Metoro" icon="server">
    **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
  </Accordion>
</AccordionGroup>

### Architecture ramifications

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

#### Option A: Same Cluster Architecture

```mermaid theme={null}
graph TB
    subgraph "Kubernetes Cluster"
        subgraph "metoro-hub namespace"
            API[API Server]
            I[Ingester]
            CH[(ClickHouse)]
            PG[(PostgreSQL)]
            T[Temporal]
        end
        subgraph "metoro namespace"
            E[Exporters]
            NA["Node Agents<br/>DaemonSet"]
        end
        subgraph "Your Application Namespaces"
            APP[Your Workloads]
        end
        
        NA -.-> APP
        NA --> E
        E --> I
        I --> CH
        API --> CH
        API --> PG
        API --> T
        T --> PG
    end
    
    U[Users] --> API
```

#### Option B: Dedicated Cluster Architecture

```mermaid theme={null}
graph TB
    subgraph "Management Cluster"
        subgraph "metoro-hub namespace"
            API[API Server]
            I[Ingester]
            CH[(ClickHouse)]
            PG[(PostgreSQL)]
            T[Temporal]
            
            I --> CH
            API --> CH
            API --> PG
            API --> T
            T --> PG
        end
    end
    
    subgraph "Application Cluster 1"
        subgraph "metoro namespace"
            E1[Exporters]
            NA1["Node Agents<br/>DaemonSet"]
        end
        subgraph "app namespaces"
            APP1[Your Workloads]
        end
        NA1 -.-> APP1
        NA1 --> E1
    end
    
    subgraph "Application Cluster 2"
        subgraph "metoro namespace "
            E2[Exporters]
            NA2["Node Agents<br/>DaemonSet"]
        end
        subgraph "app namespaces "
            APP2[Your Workloads]
        end
        NA2 -.-> APP2
        NA2 --> E2
    end
    
    E1 --> I
    E2 --> I
    
    U[Users] --> API
```

## 2. PostgreSQL Database

### How will you manage the metadata database?

<AccordionGroup>
  <Accordion title="Option A: In-cluster PostgreSQL" icon="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

    **Configuration**

    If you want to use the in-cluster PostgreSQL, you can enable it in your `values.yaml` file like this:

    ```yaml theme={null}
    postgresql:
      enabled: true
      persistence:
        size: 20Gi
      auth:
        password: "CHANGE_ME_SECURE_PASSWORD"
    ```

    **Required resources:**

    * 2 CPU cores
    * 4GB RAM
    * 20GB+ persistent storage
  </Accordion>

  <Accordion title="Option B: External managed PostgreSQL" icon="cloud">
    **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:

    ```bash theme={null}
    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`:

    ```yaml theme={null}
    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
  </Accordion>
</AccordionGroup>

## 3. ClickHouse Database

### How will you manage the telemetry database?

<AccordionGroup>
  <Accordion title="Option A: In-cluster ClickHouse" icon="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:

    ```bash theme={null}
    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`:

    ```yaml theme={null}
    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)
  </Accordion>

  <Accordion title="Option B: External managed ClickHouse" icon="cloud">
    **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:

    ```bash theme={null}
    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`:

    ```yaml theme={null}
    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
  </Accordion>
</AccordionGroup>

## 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](/docs/on-premises/9.x/configuration) to create your `values.yaml` file
2. Follow the [installation guide](/docs/on-premises/9.x/installation) to deploy Metoro Hub on your Kubernetes cluster

<Note>
  Take time to make these decisions carefully. Changing deployment topology or database backends after installation requires significant migration effort.
</Note>