# Ingest data from Self-hosted Kafka How to connect a self-hosted Kafka cluster as a source to Materialize. [//]: # "TODO(morsapaes) The Kafka guides need to be rewritten for consistency with the Postgres ones. We should include spill to disk in the guidance then." This guide goes through the required steps to connect Materialize to a self-hosted Kafka cluster. > **Tip:** For help getting started with your own data, you can schedule a [free guided > trial](https://materialize.com/demo/?utm_campaign=General&utm_source=documentation). ## Before you begin Before you begin, you must have: - A Kafka cluster running Kafka 3.2 or later. - A client machine that can interact with your cluster. ## Configure network security There are various ways to configure your Kafka network to allow Materialize to connect: - **Use AWS PrivateLink**: If your Kafka cluster is running on AWS, you can use AWS PrivateLink to connect Materialize to the cluster. - **Use an SSH tunnel**: If your Kafka cluster is running in a private network, you can use an SSH tunnel to connect Materialize to the cluster. - **Allow Materialize IPs**: If your Kafka cluster is publicly accessible, you can configure your firewall to allow connections from a set of static Materialize IP addresses. Select the option that works best for you. **Cloud:** **Privatelink:** > **Note:** Materialize provides Terraform modules for both [Amazon MSK clusters](https://github.com/MaterializeInc/terraform-aws-msk-privatelink) > and [self-managed Kafka clusters](https://github.com/MaterializeInc/terraform-aws-kafka-privatelink) > which can be used to create the target groups for each Kafka broker (step 1), > the network load balancer (step 2), the TCP listeners (step 3) and the VPC > endpoint service (step 5). This section covers how to create AWS PrivateLink connections and retrieve the AWS principal needed to configure the AWS PrivateLink service. 1. Create target groups. Create a dedicated [target group](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-target-group.html) **for each broker** with the following details: a. Target type as **IP address**. b. Protocol as **TCP**. c. Port as **9092**, or the port that you are using in case it is not 9092 (e.g. 9094 for TLS or 9096 for SASL). d. Make sure that the target group is in the same VPC as the Kafka cluster. e. Click next, and register the respective Kafka broker to each target group using its IP address. 1. Create a [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html) that is **enabled for the same subnets** that the Kafka brokers are in. 1. Create a [TCP listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-listener.html) for every Kafka broker that forwards to the corresponding target group you created (e.g. `b-1`, `b-2`, `b-3`). The listener port needs to be unique, and will be used later on in the `CREATE CONNECTION` statement. For example, you can create a listener for: a. Port `9001` → broker `b-1...`. b. Port `9002` → broker `b-2...`. c. Port `9003` → broker `b-3...`. 1. Verify security groups and health checks. Once the TCP listeners have been created, make sure that the [health checks](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-health-checks.html) for each target group are passing and that the targets are reported as healthy. If you have set up a security group for your Kafka cluster, you must ensure that it allows traffic on both the listener port and the health check port. **Remarks**: a. Network Load Balancers do not have associated security groups. Therefore, the security groups for your targets must use IP addresses to allow traffic. b. You can't use the security groups for the clients as a source in the security groups for the targets. Therefore, the security groups for your targets must use the IP addresses of the clients to allow traffic. For more details, check the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html). 1. Create a VPC [endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and associate it with the **Network Load Balancer** that you’ve just created. Note the **service name** that is generated for the endpoint service. 1. Create an AWS PrivateLink connection. In Materialize, create an [AWS PrivateLink connection](/sql/create-connection/#aws-privatelink) that references the endpoint service that you created in the previous step. ↕️ **In-region connections** To connect to an AWS PrivateLink endpoint service in the **same region** as your Materialize environment: ```mzsql CREATE CONNECTION privatelink_svc TO AWS PRIVATELINK ( SERVICE NAME 'com.amazonaws.vpce..vpce-svc-', AVAILABILITY ZONES ('use1-az1', 'use1-az2', 'use1-az4') ); ``` - Replace the `SERVICE NAME` value with the service name you noted earlier. - Replace the `AVAILABILITY ZONES` list with the IDs of the availability zones in your AWS account. For in-region connections the availability zones of the NLB and the consumer VPC **must match**. To find your availability zone IDs, select your database in the RDS Console and click the subnets under **Connectivity & security**. For each subnet, look for **Availability Zone ID** (e.g., `use1-az6`), not **Availability Zone** (e.g., `us-east-1d`). ↔️ **Cross-region connections** To connect to an AWS PrivateLink endpoint service in a **different region** to the one where your Materialize environment is deployed: ```mzsql CREATE CONNECTION privatelink_svc TO AWS PRIVATELINK ( SERVICE NAME 'com.amazonaws.vpce.us-west-1.vpce-svc-', -- For now, the AVAILABILITY ZONES clause **is** required, but will be -- made optional in a future release. AVAILABILITY ZONES () ); ``` - Replace the `SERVICE NAME` value with the service name you noted earlier. - The service name region refers to where the endpoint service was created. You **do not need** to specify `AVAILABILITY ZONES` manually — these will be optimally auto-assigned when none are provided. - For Kafka connections, it is required for [cross-zone load balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancers.html) to be enabled on the VPC endpoint service's NLB when using cross-region Privatelink. 1. Configure the AWS PrivateLink service. Retrieve the AWS principal for the AWS PrivateLink connection you just created: ```mzsql SELECT principal FROM mz_aws_privatelink_connections plc JOIN mz_connections c ON plc.id = c.id WHERE c.name = 'privatelink_svc'; ``` ``` principal --------------------------------------------------------------------------- arn:aws:iam::664411391173:role/mz_20273b7c-2bbe-42b8-8c36-8cc179e9bbc3_u1 ``` Follow the instructions in the [AWS PrivateLink documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/add-endpoint-service-permissions.html) to configure your VPC endpoint service to accept connections from the provided AWS principal. 1. If your AWS PrivateLink service is configured to require acceptance of connection requests, you must manually approve the connection request from Materialize after executing `CREATE CONNECTION`. For more details, check the [AWS PrivateLink documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests). **Note:** It might take some time for the endpoint service connection to show up, so you would need to wait for the endpoint service connection to be ready before you create a source. 1. Validate the AWS PrivateLink connection you created using the [`VALIDATE CONNECTION`](/sql/validate-connection) command: ```mzsql VALIDATE CONNECTION privatelink_svc; ``` If no validation error is returned, move to the next step. 1. Create a source connection In Materialize, create a source connection that uses the AWS PrivateLink connection you just configured: ```mzsql CREATE CONNECTION kafka_connection TO KAFKA ( BROKERS ( -- The port **must exactly match** the port assigned to the broker in -- the TCP listerner of the NLB. 'b-1.hostname-1:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9001, AVAILABILITY ZONE 'use1-az2'), 'b-2.hostname-2:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9002, AVAILABILITY ZONE 'use1-az1'), 'b-3.hostname-3:9096' USING AWS PRIVATELINK privatelink_svc (PORT 9003, AVAILABILITY ZONE 'use1-az4') ), -- Authentication details -- Depending on the authentication method the Kafka cluster is using SASL MECHANISMS = 'SCRAM-SHA-512', SASL USERNAME = 'foo', SASL PASSWORD = SECRET kafka_password ); ``` If you run into connectivity issues during source creation, make sure that: * The `(PORT )` value **exactly matches** the port assigned to the corresponding broker in the **TCP listener** of the Network Load Balancer. Misalignment between ports and broker addresses is the most common cause for connectivity issues. * For **in-region connections**, the correct availability zone is specified for each broker. **SSH Tunnel:** Materialize can connect to a Kafka broker, a Confluent Schema Registry server, a PostgreSQL database, or a MySQL database through an SSH tunnel connection. In this guide, you will create an SSH tunnel connection, configure your Materialize authentication settings, and create a source connection. Before you begin, make sure you have access to a bastion host. You will need: * The bastion host IP address and port number * The bastion host username 1. Create an SSH tunnel connection. In Materialize, create an [SSH tunnel connection](/sql/create-connection/#ssh-tunnel) to the bastion host: ```mzsql CREATE CONNECTION ssh_connection TO SSH TUNNEL ( HOST '', USER '', PORT ); ``` 1. Configure the SSH bastion host. The bastion host needs a **public key** to connect to the Materialize tunnel you created in the previous step. Materialize stores public keys for SSH tunnels in the system catalog. Query [`mz_ssh_tunnel_connections`](/reference/system-catalog/mz_catalog/#mz_ssh_tunnel_connections) to retrieve the public keys for the SSH tunnel connection you just created: ```mzsql SELECT mz_connections.name, mz_ssh_tunnel_connections.* FROM mz_connections JOIN mz_ssh_tunnel_connections USING(id) WHERE mz_connections.name = 'ssh_connection'; ``` ``` | id | public_key_1 | public_key_2 | |-------|---------------------------------------|---------------------------------------| | u75 | ssh-ed25519 AAAA...76RH materialize | ssh-ed25519 AAAA...hLYV materialize | ``` > Materialize provides two public keys to allow you to rotate keys without connection downtime. Review the [`ALTER CONNECTION`](/sql/alter-connection) documentation for more information on how to rotate your keys. 1. Log in to your SSH bastion server and add each key to the bastion `authorized_keys` file: ```bash # Command for Linux echo "ssh-ed25519 AAAA...76RH materialize" >> ~/.ssh/authorized_keys echo "ssh-ed25519 AAAA...hLYV materialize" >> ~/.ssh/authorized_keys ``` 1. Configure your internal firewall to allow the SSH bastion host to connect to your Kafka cluster or PostgreSQL instance. If you are using a cloud provider like AWS or GCP, update the security group or firewall rules for your PostgreSQL instance or Kafka brokers. Allow incoming traffic from the SSH bastion host IP address on the necessary ports. For example, use port `5432` for PostgreSQL and ports `9092`, `9094`, and `9096` for Kafka. Test the connection from the bastion host to the Kafka cluster or PostgreSQL instance. ```bash telnet telnet ``` If the command hangs, double-check your security group and firewall settings. If the connection is successful, you can proceed to the next step. 1. Verify the SSH tunnel connection from your source to your bastion host: ```bash # Command for Linux ssh -L 9092:kafka-broker:9092 @ ``` Verify that you can connect to the Kafka broker or PostgreSQL instance via the SSH tunnel: ```bash telnet localhost 9092 ``` If you are unable to connect using the `telnet` command, enable `AllowTcpForwarding` and `PermitTunnel` on your bastion host SSH configuration file. On your SSH bastion host, open the SSH config file (usually located at `/etc/ssh/sshd_config`) using a text editor: ```bash sudo nano /etc/ssh/sshd_config ``` Add or uncomment the following lines: ```bash AllowTcpForwarding yes PermitTunnel yes ``` Save the changes and restart the SSH service: ```bash sudo systemctl restart sshd ``` 1. Retrieve the static egress IPs from Materialize and configure the firewall rules (e.g. AWS Security Groups) for your bastion host to allow SSH traffic for those IP addresses only. ```mzsql SELECT * FROM mz_catalog.mz_egress_ips; ``` ``` XXX.140.90.33 XXX.198.159.213 XXX.100.27.23 ``` 1. To confirm that the SSH tunnel connection is correctly configured, use the [`VALIDATE CONNECTION`](/sql/validate-connection) command: ```mzsql VALIDATE CONNECTION ssh_connection; ``` If no validation errors are returned, the connection can be used to create a source connection. 1. In Materialize, create a source connection that uses the SSH tunnel connection you configured in the previous section: ```mzsql CREATE CONNECTION kafka_connection TO KAFKA ( BROKER 'broker1:9092', SSH TUNNEL ssh_connection ); ``` **Allow Materialize IPs:** 1. In the [SQL Shell](/console/), or your preferred SQL client connected to Materialize, find the static egress IP addresses for the Materialize region you are running in: ```mzsql SELECT * FROM mz_egress_ips; ``` 1. Update your Kafka cluster firewall rules to allow traffic from each IP address from the previous step. 1. Create a [Kafka connection](/sql/create-connection/#kafka) that references your Kafka cluster: ```mzsql CREATE SECRET kafka_password AS ''; CREATE CONNECTION kafka_connection TO KAFKA ( BROKER '', SASL MECHANISMS = 'SCRAM-SHA-512', SASL USERNAME = '', SASL PASSWORD = SECRET kafka_password ); ``` **Self-Managed:** There are various ways to configure your Kafka network to allow Materialize to connect: - **Use an SSH tunnel**: If your Kafka cluster is running in a private network, you can use an SSH tunnel to connect Materialize to the cluster. - **Allow Materialize IPs**: If your Kafka cluster is publicly accessible, you can configure your firewall to allow connections from a set of static Materialize IP addresses. Select the option that works best for you. **SSH Tunnel:** Materialize can connect to a Kafka broker, a Confluent Schema Registry server, a PostgreSQL database, or a MySQL database through an SSH tunnel connection. In this guide, you will create an SSH tunnel connection, configure your Materialize authentication settings, and create a source connection. Before you begin, make sure you have access to a bastion host. You will need: * The bastion host IP address and port number * The bastion host username 1. Create an SSH tunnel connection. In Materialize, create an [SSH tunnel connection](/sql/create-connection/#ssh-tunnel) to the bastion host: ```mzsql CREATE CONNECTION ssh_connection TO SSH TUNNEL ( HOST '', USER '', PORT ); ``` 1. Configure the SSH bastion host. The bastion host needs a **public key** to connect to the Materialize tunnel you created in the previous step. Materialize stores public keys for SSH tunnels in the system catalog. Query [`mz_ssh_tunnel_connections`](/reference/system-catalog/mz_catalog/#mz_ssh_tunnel_connections) to retrieve the public keys for the SSH tunnel connection you just created: ```mzsql SELECT mz_connections.name, mz_ssh_tunnel_connections.* FROM mz_connections JOIN mz_ssh_tunnel_connections USING(id) WHERE mz_connections.name = 'ssh_connection'; ``` ``` | id | public_key_1 | public_key_2 | |-------|---------------------------------------|---------------------------------------| | u75 | ssh-ed25519 AAAA...76RH materialize | ssh-ed25519 AAAA...hLYV materialize | ``` > Materialize provides two public keys to allow you to rotate keys without connection downtime. Review the [`ALTER CONNECTION`](/sql/alter-connection) documentation for more information on how to rotate your keys. 1. Log in to your SSH bastion server and add each key to the bastion `authorized_keys` file: ```bash # Command for Linux echo "ssh-ed25519 AAAA...76RH materialize" >> ~/.ssh/authorized_keys echo "ssh-ed25519 AAAA...hLYV materialize" >> ~/.ssh/authorized_keys ``` 1. Configure your internal firewall to allow the SSH bastion host to connect to your Kafka cluster or PostgreSQL instance. If you are using a cloud provider like AWS or GCP, update the security group or firewall rules for your PostgreSQL instance or Kafka brokers. Allow incoming traffic from the SSH bastion host IP address on the necessary ports. For example, use port `5432` for PostgreSQL and ports `9092`, `9094`, and `9096` for Kafka. Test the connection from the bastion host to the Kafka cluster or PostgreSQL instance. ```bash telnet telnet ``` If the command hangs, double-check your security group and firewall settings. If the connection is successful, you can proceed to the next step. 1. Verify the SSH tunnel connection from your source to your bastion host: ```bash # Command for Linux ssh -L 9092:kafka-broker:9092 @ ``` Verify that you can connect to the Kafka broker or PostgreSQL instance via the SSH tunnel: ```bash telnet localhost 9092 ``` If you are unable to connect using the `telnet` command, enable `AllowTcpForwarding` and `PermitTunnel` on your bastion host SSH configuration file. On your SSH bastion host, open the SSH config file (usually located at `/etc/ssh/sshd_config`) using a text editor: ```bash sudo nano /etc/ssh/sshd_config ``` Add or uncomment the following lines: ```bash AllowTcpForwarding yes PermitTunnel yes ``` Save the changes and restart the SSH service: ```bash sudo systemctl restart sshd ``` 1. Ensure materialize cluster pods have network access to your SSH bastion host. 1. Validate the SSH tunnel connection To confirm that the SSH tunnel connection is correctly configured, use the [`VALIDATE CONNECTION`](/sql/validate-connection) command: ```mzsql VALIDATE CONNECTION ssh_connection; ``` If no validation errors are returned, the connection can be used to create a source connection. 1. In Materialize, create a source connection that uses the SSH tunnel connection you configured in the previous section: ```mzsql CREATE CONNECTION kafka_connection TO KAFKA ( BROKER 'broker1:9092', SSH TUNNEL ssh_connection ); ``` **Allow Materialize IPs:** 1. Update your Kafka cluster firewall rules to allow traffic from Materialize. 1. Create a [Kafka connection](/sql/create-connection/#kafka) that references your Kafka cluster: ```mzsql CREATE SECRET kafka_password AS ''; CREATE CONNECTION kafka_connection TO KAFKA ( BROKER '', SASL MECHANISMS = 'SCRAM-SHA-512', SASL USERNAME = '', SASL PASSWORD = SECRET kafka_password ); ``` ## Creating a source The Kafka connection created in the previous section can then be reused across multiple [`CREATE SOURCE`](/sql/create-source/kafka/) statements: ```mzsql CREATE SOURCE json_source FROM KAFKA CONNECTION kafka_connection (TOPIC 'test_topic') FORMAT JSON; ``` By default, the source will be created in the active cluster; to use a different cluster, use the `IN CLUSTER` clause. ## Related pages - [`CREATE SECRET`](/sql/create-secret) - [`CREATE CONNECTION`](/sql/create-connection) - [`CREATE SOURCE`: Kafka](/sql/create-source/kafka)