.. _connect_quickstart: Quick Start: Move Data In and Out of |ak| with |kconnect-long| =============================================================== This tutorial provides a hands-on look at how you can move data into and out of |ak-tm| without writing a single line of code. It is helpful to review the :ref:`concepts ` for |kconnect-long| in tandem with running the steps in this guide to gain a deeper understanding. At the end of this tutorial you will be able to: * Use |confluent-cli| to manage Confluent services, including starting a single connect worker in distributed mode and loading and unloading connectors. * Read data from a file and publish to a |ak| topic. * Read data from a |ak| topic and publish to file. * Integrate |sr| with a connector. To demonstrate the basic functionality of |kconnect-long| and its integration with the |sr-long|, a few local standalone |kconnect-long| processes with connectors are run. You can insert data written to a file into |ak| and write data from a |ak| topic to the console. If you are using JSON as the |kconnect| data format, see the instructions `here `_ for a tutorial that does not include |sr|. .. include:: ../includes/installation-types-cli.rst Start the services ------------------ .. include:: ../includes/install-cli-prereqs.rst In this guide, assume services will run on ``localhost`` with default properties. .. tip:: If not configured already, configure CONFLUENT_HOME and add Confluent's ``bin`` directory to your PATH by running: ``export CONFLUENT_HOME=`` and then ``export PATH=$PATH:$CONFLUENT_HOME/bin``. Now that you have Confluent's ``bin`` directory in your ``$PATH`` variable, you can start all the services with the following commands: .. codewithvars:: bash |confluent_start| .. include:: ../includes/cli.rst :start-after: cli_limitations_start :end-before: cli_limitations_end Every service will start in order, printing a message with its status: .. include:: ../includes/cli.rst :start-after: CE_CLI_startup_output :end-before: COS_CP_CLI_startup_output .. important:: This will start |cp| in |zk| mode. If you want to use |kraft| mode, see the :ref:`cp-quickstart-step-1`. You may choose to open |kconnect|'s log to make sure the service has started successfully: .. codewithvars:: bash confluent local services connect log If an error occurred while starting services with the previous commands, you may access the logs of each service in one place by navigating to the directory where these logs are stored. For example: .. codewithvars:: bash # Show the log directory |confluent_current| /tmp/confluent.w1CpYsaI # Navigate to the log directory cd /tmp/confluent.w1CpYsaI # View the log less connect/connect.stderr For complete details on getting these services up and running, see the |cp| :ref:`installation documentation `. Read File Data with |kconnect| ------------------------------ To startup a FileStream Source connector that reads structured data from a file and exports the data into |ak|, using |sr| to inform |kconnect| of their structure, the following example uses one of the supported connector configurations that come pre-defined. To get the list of all the pre-defined connector configurations, run: .. codewithvars:: bash |confluent_list| Bundled Predefined Connectors (edit configuration under etc/): file-source file-sink replicator .. note:: You may see additional connectors listed if you have previously installed connectors. The name of the following pre-configured connector is ``file-source`` and its configuration file is located at ``./etc/kafka/connect-file-source.properties``. The following is an explanation of the contents: .. codewithvars:: bash # User defined connector instance name. name=file-source # The class implementing the connector connector.class=FileStreamSource # Maximum number of tasks to run for this connector instance tasks.max=1 # The input file (path relative to worker's working directory) # This is the only setting specific to the FileStreamSource file=test.txt # The output topic in Kafka topic=connect-test If choosing to use this tutorial without |sr|, you must also specify the ``key.converter`` and ``value.converter`` properties to use ``org.apache.kafka.connect.json.JsonConverter``. This will override the converters' settings for this connector only. You are now ready to load the connector, but before you do that, update the file with some sample data. Note that the connector configuration specifies a relative path for the file, so you should create the file in the same directory that you will run the |kconnect-long| worker from. .. codewithvars:: bash for i in {1..3}; do echo "log line $i"; done > test.txt Next, start an instance of the FileStreamSourceConnector using the configuration file you defined previously. You can easily do this from the command line using the following commands: .. codewithvars:: bash |confluent_load| file-source { "name": "file-source", "config": { "connector.class": "FileStreamSource", "tasks.max": "1", "file": "test.txt", "topics": "connect-test", "name": "file-source" }, "tasks": [] } Upon success it will print a snapshot of the connector's configuration. To confirm which connectors are loaded any time, run: .. codewithvars:: bash |confluent_status| [ "file-source" ] .. tip:: With the |cp| running and the CLI installed, you can find the path to the |kconnect-long| log file at: ``$(confluent local current)/connect/connect.stdout``. For example, to search the file for errors you can run: ``cat $(confluent local current)/connect/connect.stdout | grep ERROR`` You will get a list of all the loaded connectors in this worker. The same command supplied with the connector name will give you the status of this connector, including an indication of whether the connector has started successfully or has encountered a failure. For instance, running this command on the connector you just loaded would give you the following: .. codewithvars:: bash |confluent_status| file-source { "name": "file-source", "connector": { "state": "RUNNING", "worker_id": "192.168.10.1:8083" }, "tasks": [ { "state": "RUNNING", "id": 0, "worker_id": "192.168.10.1:8083" } ] } Soon after the connector starts, each of the three lines in our log file should be delivered to |ak|, having registered a schema with |sr|. One way to validate that the data is there is to use the console consumer in another console to inspect the contents of the topic: .. codewithvars:: bash kafka-avro-console-consumer --bootstrap-server localhost:9092 --topic connect-test --from-beginning "log line 1" "log line 2" "log line 3" Note that ``kafka-avro-console-consumer`` is used because the data has been stored in |ak| using Avro format. This consumer uses the Avro converter that is bundled with |sr| in order to properly lookup the schema for the Avro data. Write File Data with |kconnect| ------------------------------- Now that you have written some data to a |ak| topic with |kconnect|, you can now consume that data with a downstream process. In this section, you will load a sink connector to the worker in addition to the source that you started in the last section. The sink will write messages to a local file. The following is the connector's configuration as it is stored in ``etc/kafka/connect-file-sink.properties``: .. codewithvars:: bash # User defined name for the connector instance name=file-sink # Name of the connector class to be run connector.class=FileStreamSink # Max number of tasks to spawn for this connector instance tasks.max=1 # Output file name relative to worker's current working directory # This is the only property specific to the FileStreamSink connector file=test.sink.txt # Comma separate input topic list topics=connect-test Note that the configuration contains similar settings to the file source. A key difference is that multiple input topics are specified with ``topics`` whereas the file source allows for only one output topic specified with ``topic``. Now start the FileStreamSinkConnector. The sink connector will run within the same worker as the source connector, but each connector task will have its own dedicated thread. .. codewithvars:: bash |confluent_load| file-sink { "name": "file-sink", "config": { "connector.class": "FileStreamSink", "tasks.max": "1", "file": "test.sink.txt", "topics": "connect-test", "name": "file-sink" }, "tasks": [] } To ensure the sink connector is up and running, use the following command to get the state of the connector: .. codewithvars:: bash |confluent_status| file-sink { "name": "file-sink", "connector": { "state": "RUNNING", "worker_id": "192.168.10.1:8083" }, "tasks": [ { "state": "RUNNING", "id": 0, "worker_id": "192.168.10.1:8083" } ] } as well as the list of all loaded connectors: .. codewithvars:: bash |confluent_status| connectors [ "file-source", "file-sink" ] .. tip:: Because of the rebalancing that happens between worker tasks every time a connector is loaded, a call to :litwithvars:`|confluent_status| ` might not succeed immediately after a new connector is loaded. Once rebalancing completes, such calls will be able to return the actual status of a connector. By opening the file ``test.sink.txt`` you should see the two log lines written to it by the sink connector. With both connectors running, you can see data flowing end-to-end in real time. To check this out, use another terminal to tail the output file: .. codewithvars:: bash tail -f test.sink.txt and in a different terminal start appending additional lines to the text file: .. codewithvars:: bash for i in {4..1000}; do echo "log line $i"; done >> test.txt You should see the lines being added to ``test.sink.txt``. The new data was picked up by the source connector, written to |ak|, read by the sink connector from |ak|, and finally appended to the file. .. codewithvars:: bash "log line 1" "log line 2" "log line 3" "log line 4" "log line 5" ... After you are done experimenting with reading from and writing to a file with |kconnect|, you have a few options with respect to shutting down the connectors: * Unload the connectors but leave the |kconnect| worker running. .. codewithvars:: bash |confluent_unload| file-source |confluent_unload| file-sink * Stop the |kconnect| worker altogether. .. codewithvars:: bash confluent local services connect stop Stopping Connect Connect is [DOWN] * Stop the |kconnect| worker as well as all the rest Confluent services. .. codewithvars:: bash |confluent_stop| Your output should resemble: .. include:: ../includes/cli.rst :start-after: ce_cli_stop_output_start :end-before: ce_cli_stop_output_stop * Stop all the services and wipe out any data of this particular run of Confluent services. .. codewithvars:: bash |confluent_destroy| Your output should resemble: .. include:: ../includes/cli.rst :start-after: ce_cli_stop_destroy_output_start :end-before: ce_cli_stop_destroy_output_stop Both source and sink connectors can track offsets, so you can start and stop the process any number of times and add more data to the input file and both will resume where they previously left off. The connectors demonstrated in this tutorial are intentionally simple so no additional dependencies are necessary. Most connectors will require a bit more configuration to specify how to connect to the source or sink system and what data to copy, and for many you will want to execute on a |kconnect-long| cluster for scalability and fault tolerance. To get started with |kconnect-long| you'll want to see the :connect-common:`user guide|userguide.html` for more details on running and managing |kconnect-long|, including how to run in distributed mode. The :connect-common:`Connectors|supported.html` section includes details on configuring and deploying the connectors that ship with |cp|. .. tip:: The easiest way to create, configure, and manage connectors is with |c3|. To learn more about Control Center, see :ref:`control_center`.