Configuring CMA with PostgreSQL

Create CMA databases.

Run the setup script from the parcel directory on any host that has psql installed and can reach the PostgreSQL server:

/opt/cloudera/parcels/cma/bin/setup-cma-postgres.sh \
          --host <pg-host> \
          --admin-user postgres \
          --admin-password <superuser-password>

The script creates three databases and their owning users:

Passwords are auto-generated and printed at the end. Save them for configuring CMA.

Setup Script Options

Manual Database Creation

If you prefer to create the databases manually instead of using the setup script:

sudo -u postgres psql

        CREATE USER cma WITH PASSWORD 'your_secure_password';
        CREATE USER "cma-agent" WITH PASSWORD 'your_agent_password';

        CREATE DATABASE cma OWNER cma;
        CREATE DATABASE "cma-auth" OWNER cma;
        CREATE DATABASE "cma-agent" OWNER "cma-agent";

        GRANT ALL PRIVILEGES ON DATABASE cma TO cma;
        GRANT ALL PRIVILEGES ON DATABASE "cma-auth" TO cma;
        GRANT ALL PRIVILEGES ON DATABASE "cma-agent" TO "cma-agent";

        \c cma
        GRANT ALL ON SCHEMA public TO cma;
        \c cma-auth
        GRANT ALL ON SCHEMA public TO cma;
        \c cma-agent
        GRANT ALL ON SCHEMA public TO "cma-agent";

Configure CMA

Parcel Deployment (Cloudera Manager)

In Cloudera Manager, configure the following parameters for each CMA service:

CMA Master service configuration:

CMA Agent service configuration:

Then restart both CMA services.

Environment variables reference

Parcel deployments map these environment variables from Cloudera Manager service configuration. Use the safety valve section below when additional variables are required for the Auth Server role.

CMA Master

CMA Auth Server

CMA Agent

Schema Management

CMA uses Liquibase for automatic schema management. When starting with the postgres profile, Liquibase creates all required tables, indexes, and seed data automatically. No manual schema creation is needed.

Deployment Topologies

Single cluster (Master + Agent co-located)

All three databases (cma, cma-auth, cma-agent) on a single PostgreSQL instance. Run the setup script once. Configure both services to point to the same PostgreSQL host.

Master-Agent split (separate clusters)

CMA Master on the target cluster, CMA Agent on the source cluster. Each can use a local PostgreSQL instance:

• Target cluster PostgreSQL: cma, cma-auth, cma-agent databases (the target Agent and Master share the same PostgreSQL)

• Source cluster PostgreSQL: cma-agent database only

Run the setup script on each PostgreSQL host. Configure the CMA Agent on the source cluster with the CMA Master URL pointing to the Master's gRPC port (default 8091) on the target cluster.

When the CMA Agent is on a different cluster from the Master, the CMA Master URL parameter must be set in the Agent's service configuration in Cloudera Manager (format: http://<master-host>:<grpc-port>).

Limitations

• No H2-to-PostgreSQL migration: Switching from H2 to PostgreSQL requires a fresh start. Existing H2 data cannot be migrated automatically.

• Separate databases: CMA Master, the Auth Server, and CMA Agent each use separate databases. All must be configured when using PostgreSQL.

Switching from H2 to PostgreSQL

When switching an existing CMA deployment from H2 to PostgreSQL, the Master starts with a fresh database. CMA Agents, however, retain their local H2 databases which contain stale server and cluster IDs referencing the old Master database. This causes agents to fail registration because those IDs no longer exist.

To resolve this, wipe the agent H2 databases on every agent host after switching the Master to PostgreSQL:

# On each CMA Agent host:
        # 1. Stop the CMA Agent service (via CM or systemctl)

        # 2. Delete the agent's local H2 database
        rm -f /var/lib/cma-agent/data/db/cma-agent.mv.db

        # 3. Start the CMA Agent service

After restart, each agent will re-register with the Master and receive new IDs.

Similarly, if the Master was previously running with H2 and accumulated data (/var/lib/cma/data/, /var/lib/cma/config/), clear those directories before switching to PostgreSQL to avoid H2 startup errors:

# On the CMA Master host (stop service first):
        sudo rm -rf /var/lib/cma/data/* /var/lib/cma/config/*

Troubleshooting

PostgreSQL superuser password not known

Cloudera Manager's PostgreSQL typically uses md5 authentication for all connections. If you don't have the postgres superuser password, you can temporarily enable peer authentication (OS-level user matching) to set one:

# Add peer auth as the first rule (takes priority)
        sudo sed -i '1i local   all   postgres   peer' /var/lib/pgsql/12/data/pg_hba.conf
        sudo systemctl reload postgresql-12

        # Set a known password
        sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'new_password';"

        # Remove the peer auth rule
        sudo sed -i '1d' /var/lib/pgsql/12/data/pg_hba.conf
        sudo systemctl reload postgresql-12

Remote connections rejected

If the CMA Agent connects to a PostgreSQL on a different host and gets "connection refused" or authentication errors, verify:

1. PostgreSQL listens on all interfaces (listen_addresses = '*' in

postgresql.conf)

1. pg_hba.conf allows remote connections:

host    all    all    0.0.0.0/0    md5

1. Reload PostgreSQL after changes: sudo systemctl reload postgresql-12

Connection refused or hostname resolution error

Verify the PostgreSQL host is reachable from the CMA host:

psql -h <pg-host> -p <pg-port> -U <user> -d postgres -c "SELECT 1"

Check that pg_hba.conf on the PostgreSQL server allows connections from the CMA hosts.

Missing Database Host or Password error on startup

When CMA_DB_TYPE is set to postgres, the Database Host and Database Password parameters are required. In Cloudera Manager, verify these are set in the CMA service configuration.

Parcel deployment: environment variable injection via safety valve

In parcel deployments, CMA reads database parameters from the CM-managed service configuration. If additional environment variables are needed (e.g., for the Auth Server), you can inject them using CM safety valves.

In Cloudera Manager, set the following for the CMA_AUTH_SERVER role:

CMA_AUTH_SERVER > Configuration > CMA_AUTH_SERVER role Environment Advanced Configuration Snippet (Safety Valve):

CMA_AUTH_DB_HOST=db.example.com
        CMA_AUTH_DB_PORT=5432
        CMA_AUTH_DB_NAME=cma-auth
        CMA_AUTH_DBA_USER=cma
        CMA_AUTH_DBA_PASS=your_secure_password

Safety valve values are injected directly into the Java process environment by CM, bypassing any shell script issues. Restart the CMA service after applying these changes.