Confluent Platform Installation FAQ

This FAQ addresses common questions and issues encountered when installing, upgrading, and configuring Confluent Platform. Use this guide to quickly find solutions and make informed decisions about your deployment strategy.

Planning and prerequisites

What are the minimum hardware requirements for Confluent Platform?

Hardware requirements for Confluent Platform vary significantly with your workload and deployment type. For optimal performance, use identical hardware specifications for all cluster nodes.

For complete hardware recommendations, see Confluent Platform System Requirements.

Which operating systems does Confluent Platform support?

Confluent Platform supports various Linux distributions and container platforms, each with specific version and architecture requirements. Always use a supported operating system to avoid security vulnerabilities and compatibility issues.

For supported operating systems, see Confluent Platform System Requirements. For Docker-specific information, see Install Confluent Platform Using Docker.

How do I know which Java version to use with my Confluent Platform version?

Each Confluent Platform version requires a specific Java version. You must use the exact recommended version and set the JAVA_HOME environment variable correctly or Confluent Platform might not start.

For complete Java version requirements, Java.

What network ports does Confluent Platform use?

Confluent Platform components use various default ports that you can configure. Make sure your firewall allows access to the required ports for your deployment.

Key ports: Kafka brokers (9092 external, 9091 internal), KRaft KRaft controllers (9093), Schema Registry (8081), Connect (8083), ksqlDB (8088), Confluent Control Center (9021), MDS or Confluent Server API (8090).

For the complete ports reference and internal/external access requirements, Confluent Platform System Requirements.

What’s the difference between Confluent Platform and Confluent Community packages?

  • confluent-platform: Contains the complete Confluent Platform, including commercial features like RBAC and Tiered Storage.
  • confluent-community: Contains only the open-source components.

Use confluent-platform for commercial features and confluent-community for basic Kafka functionality.

What’s the difference between Confluent Server and Kafka?

  • Confluent Server (confluent-server package): An enhanced version of Kafka with commercial features like role-based access control (RBAC), Tiered Storage, and Confluent Self-Balancing Clusters.
  • Apache Kafka (confluent-kafka package): The standard open-source Kafka.

Confluent Server is fully compatible with Kafka and supports in-place migration. For more information, see Migrate Confluent Platform to Confluent Server.

How do I choose the right installation method for my environment?

Choose an installation method based on your environment and operational needs. Orchestrated installation methods like Confluent for Kubernetes are recommended for production environments. For development, the Confluent CLI with Confluent local or Docker with docker-compose provide the quickest setups.

Installation procedures

How do I install Confluent Platform using Docker?

Use external volumes for persistent data (especially for Kafka brokers) and choose the correct networking approach (host networking for production). Images are available for Linux AMD64/x86_64 and ARM64/aarch64.

Example pull command:

docker pull confluentinc/cp-server:latest

For detailed instructions, see Install Confluent Platform Using Docker.

Why does my Docker installation fail with memory errors?

This issue occurs because Docker Desktop’s default memory is too low for Confluent Platform. Increase Docker Desktop memory allocation to 8 GB: Settings > Resources > Advanced. For production, ensure your host system has adequate memory.

For complete Docker memory configuration procedures, see Docker Developer Guide for Confluent Platform.

How do I properly configure persistent storage for Docker deployments?

For production deployments, you need external volumes for data directories, proper file ownership (UID 1000 for Confluent containers) to avoid permission errors.

For complete configuration procedures and examples, see Mount Docker External Volumes in Confluent Platform.

How do I resolve “NO_PUBKEY” errors during package installation?

This error indicates missing or outdated GPG keys for package verification. You must remove old keys and import the current Confluent signing key for your specific platform.

For platform-specific key import commands and troubleshooting, see the Install Confluent Platform On-Premises GPG key management section.

Migration and upgrades

Do I need to migrate from ZooKeeper to KRaft?

Yes, if you plan to upgrade to Confluent Platform 8.0 or later. ZooKeeper support was completely removed from Confluent Platform 8.0+. You must migrate to KRaft mode on a supported version (Confluent Platform 7.7.1 or later) before you upgrade.

For complete migration guidance, see Migrate from ZooKeeper to KRaft on Confluent Platform.

What are the phases of ZooKeeper to KRaft migration?

Migration involves 5 distinct phases:

  1. Phase 1: Cluster running in ZooKeeper mode (starting point)
  2. Phase 2: Provision and start KRaft controllers
  3. Phase 3: Migrate broker metadata from ZooKeeper to KRaft (the hybrid phase)
  4. Phase 4: Migrate brokers to use the KRaft controller
  5. Phase 5: Take KRaft controllers out of migration mode (finalization)

Each phase must be completed successfully before proceeding to the next.

Can I revert a ZooKeeper to KRaft migration?

Yes, but only up until Phase 5 (finalization). After you complete Phase 5, you can’t revert the migration. It is a best practice to wait 1-2 weeks after Phase 4 before you finalize (Phase 5) to ensure everything is stable.

For detailed revert procedures, see Reverting to ZooKeeper mode.

What should I check before starting ZooKeeper to KRaft migration?

Before you start migration, complete these steps:

  • Upgrade to Confluent Platform 7.7.1 or later in ZooKeeper mode. Make sure all cluster nodes run the same Confluent Platform version.
  • Check KRaft limitations and unsupported features.
  • Make sure all ZooKeeper ACLs are correctly formatted.
  • For migration troubleshooting, enable TRACE logging: log4j.logger.org.apache.kafka.metadata.migration=TRACE

How do I format storage directories for KRaft mode?

Before starting KRaft controllers, you must format the log directories with a cluster ID using the kafka-storage tool. Do not reformat directories after initial setup, as this causes data loss.

For complete step-by-step instructions, see:

Should I do a rolling upgrade or downtime upgrade?

A rolling upgrade is recommended for production as it maintains cluster availability. A downtime upgrade is faster but requires a planned service interruption.

What’s the correct order for upgrading Confluent Platform?

Upgrade components in this order: Confluent Control Center > Kafka brokers > Kafka controllers > Other Confluent Platform components > Client applications. For KRaft clusters, upgrade all brokers before you upgrade controllers.

For detailed procedures, see Upgrade order.

How do I upgrade the metadata version after upgrading brokers?

After you upgrade all brokers and controllers, use kafka-features to finalize the metadata version upgrade. This step completes the upgrade process, but after you upgrade, you can only downgrade if there are no breaking changes between versions.

For specific metadata versions by Confluent Platform release and complete upgrade procedures, see Upgrade order.

What should I backup before upgrading?

Back up essential items like all configuration files, unit files, and custom scripts. It is also recommended to back up data directories. Note that Confluent Platform might not start if proper file ownership isn’t preserved on configuration files.

For backup procedures, see Preparation.

What should I do if migration from ZooKeeper to KRaft fails?

Before Phase 5 (finalization), you can revert the migration. Use the kafka-migration-check tool to diagnose issues and review logs for specific error messages. Common causes include malformed ZooKeeper ACLs, version mismatches, and network problems.

For complete troubleshooting procedures and revert steps by phase, see Migrate from ZooKeeper to KRaft on Confluent Platform.

My upgrade is taking too long. Is this normal?

Yes, upgrade time depends on factors like data size, number of partitions, and network speed. Rolling upgrades take longer but maintain availability. Be concerned if brokers are failing to start or the cluster becomes unavailable during a rolling upgrade.

Configuration and management

How do I properly configure systemd services for Confluent Platform?

Systemd service management is the recommended approach for production deployments. Proper configuration ensures automatic startup and easier operational management, allowing you to control service status, enable startup, and create service overrides for custom settings.

For complete systemd configuration procedures, including service override examples and startup scripts, see Use Confluent Platform systemd Service Unit Files.

How do I configure JVM heap settings and tune performance?

Proper JVM configuration is crucial for performance. Set JVM heap size with environment variables in startup scripts or service overrides. Use G1GC for heaps over 4 GB, and never set heap larger than 75% of available system memory.

For complete JVM tuning procedures and advanced configuration examples, see:

Troubleshooting

Confluent Platform won’t start. What should I check?

Check for common issues like Java version mismatch, missing license, port conflicts, file permission errors, and configuration typos. Always review log files in $CONFLUENT_HOME/logs/ for specific error messages.

Confluent Platform services fail to start with permission denied errors. How do I fix this?

This is a common issue related to file ownership and permissions. Ensure that configuration files, log directories, and data directories are owned by the service user. For Docker, use UID 1000 for file ownership.

For detailed ownership requirements and specific chown commands, see the installation guides: Install Confluent Platform using Systemd on Ubuntu and Debian and Install Confluent Platform using Systemd on RHEL, CentOS, and Fedora-based Linux.

My cluster nodes can’t communicate with each other. What should I check?

Inter-node communication problems can cause cluster instability. Check for common issues like firewall-blocked ports, incorrect listener configurations, or DNS resolution problems. You can use tools like telnet, nslookup, and netstat to troubleshoot network connectivity.

For detailed networking requirements and troubleshooting procedures, see: