.. _controlcenter_userguide_connect:

##########
|kconnect|
##########

.. meta::
  :title: Manage Kafka Connect cluster and connectors in Confluent Control Center
  :description: This document describes managing Kafka Connect clusters and 
                connectors in the Confluent Control Center user interface. 
                You can add a connector by either uploading a configuration file
                or by completing the fields in the UI. Download a connector 
                configuration file after completing the UI fields. Use the 
                downloaded file as a template or upload the file and reuse the 
                connector configuration in another cluster. 
                Pause a running connector. Resume a paused connector. 
                Edit or delete a connector. If RBAC is enabled, you can enter 
                the necessary fields for your connector configuration.
  :keywords: Confluent Control Center, Connect, connectors, upload connector 
             config file, download connector config file, connector status,
             pause connector, resume paused connector, edit connector,
             delete connector, RBAC

|c3-short| provides the convenience of managing connectors for multiple 
|kconnect-long| clusters. Use |c3-short| to:

- :ref:`Add a connector <c3-add-connector>` by completing UI fields.
- Add a connector by 
  :ref:`uploading a connector configuration file <c3_upload_connector_config>`.
- :ref:`Download connector configuration files <c3_download_connector_config>` 
  to reuse in another connector or cluster, or to use as a template.
- :ref:`Edit a connector configuration <c3_edit_connector>` and relaunch it.
- :ref:`Pause a running connector <c3_pause_resume_connector>`; 
  resume a paused connector.
- :ref:`Delete a connector <c3_delete_connector>`.
- View the status of connectors in |kconnect| clusters.

|c3-short| uses the |kconnect| API
to get information on running connectors.

For more information about |kconnect|, see :ref:`kafka_connect`. For more 
information about connectors, see :ref:`connect_managing`.

.. tip:: If you are getting started learning about connectors, try out 
          the :ref:`connect_filestreamconnector` in a non-production
          (local) environment.
          Follow the instructions in :ref:`connect_quickstart`.

.. _c3_config_connect_cluster:

Configure |c3-short| for |kconnect| clusters
############################################

When you start a local |cp| install using the 
:ref:`confluent_local_start` command from the |confluent-cli|, a 
default |kconnect| cluster named **connect-default**
is created for you. To configure |c3-short| to communicate with your own 
|kconnect| clusters in a production environment, set the 
``confluent.controlcenter.connect.<name>.cluster=<host>:<port>,<host>:<port>,...`` option. 
This option is required for connecting |c3-short| to your |kconnect| clusters. 
For more information, see the ``confluent.controlcenter.connect.*`` options in 
the :ref:`controlcenter_configuration`.

.. figure:: ../images/c3-connect-no-clusters-found.png
   :width: 600px
 
   Message displayed when Control Center not configured for Connect in a production environment
   
=================================
Multiple |kconnect-long| clusters
=================================

You can configure |c3| to manage multiple |kconnect-long| clusters. For example, if you have a development |kconnect| cluster and a production |kconnect| cluster, you could add two ``confluent.controlcenter.connect.<name>.cluster=<host>:<port>`` references to the |c3-short| configuration properties file. An example of this is shown below:

::
   
   ############################# Control Center Settings #############################

   ...

   # A comma separated list of Connect host names
   confluent.controlcenter.connect.development.cluster=http://connect-dev:8083
   confluent.controlcenter.connect.production.cluster=https://connect-prod:8443

   ...
   
For the full property definition, see the |c3-short| |kconnect| :ref:`configuration property <c3-connect-cluster-setting>`.

.. _c3_all_connect_clusters_page:

============================
All |kconnect| Clusters page
============================

The All |kconnect| Clusters page provides an overview of all |kconnect| clusters.

To access the All |kconnect| Clusters page:

- Click the Connect menu for a cluster.
- Click the Connect panel on the cluster Overview page.

Use the All |kconnect| Clusters page to:

- Search for a |kconnect| cluster by its cluster name and ID.
- Sort a column by clicking in the column title cell.
- Navigate to the :ref:`c3_connectors_page`.
- View a breakdown for each |kconnect| cluster by connector status.

The total number of running, degraded, failed, and paused connectors are shown.

.. figure:: ../images/c3-all-connect-clusters-page.png
   :width: 600px

.. _c3_connectors_page:

===============
Connectors page
===============

The Connectors page provides an overview of the connectors configured for a 
|kconnect| cluster.

To access the Connectors page, click the **Cluster name** 
link in the :Ref:`c3_all_connect_clusters_page` for a |kconnect| cluster.

Use the Connectors page to:

- View a summary of connectors for the |kconnect| cluster.
- Search for a connector by its name and ID.
- Filter the view of connectors by Source or Sink type.
- :ref:`c3-add-connector` by either completing the UI fields manually or 
  :ref:`uploading a connector configuration file <c3_upload_connector_config>`.
- Sort a column by clicking in the column title cell.
- :ref:`c3-add-connector` to the |kconnect| cluster.
- Navigate to view connector details, :ref:`edit a connector <c3_edit_connector>`, or 
  :ref:`delete a connector <c3_delete_connector>`.

.. figure:: ../images/c3-connectors-page.png
   :width: 600px

The Status, Name, Category, Type, Topics (for sink connectors only), and Number 
of Tasks are shown for each configured connector.

Status column color legend:

- Running connectors display a green sidebar.
- Degraded connectors display an orange sidebar.
- Failed connectors display a red sidebar.
- :ref:`Paused <c3_pause_resume_connector>` connectors display a gray 
  sidebar.

.. _c3-add-connector:

Add a connector (non-|rbac| environment)
########################################

Follow these steps to configure a source or sink connector by completing the 
applicable UI fields. For details about 
connector settings common and unique to source and sink connectors, see 
:ref:`connect_managing_config_connectors`. This procedure is applicable to
a non-|rbac| workflow. For an |rbac| workflow, see 
:ref:`c3-add-connector-rbac-workflow`).

There are two steps (tabs) to complete in this workflow:

#. Set up the connection
#. Test and verify

.. tip:: You can also add a connector by 
         :ref:`uploading a connector configuration file <c3_upload_connector_config>`.

#. Select a cluster from the navigation bar and click the **Connect** menu. 
   The :ref:`c3_all_connect_clusters_page` appears.

   .. figure:: ../images/c3-all-connect-clusters-page.png
      :width: 600px

#. In the **Cluster name** column, click the **connect-default** link (or the link 
   for your |kconnect| cluster). The :ref:`c3_connectors_page` appears.

   .. figure:: ../images/c3-no-connectors.png
      :width: 600px

#. Click **Add connector**. The Browse page for selecting connectors appears. 
   The connectors that initially display in this page are connectors that 
   are :ref:`bundled <connect_bundled_connectors>` with |cp|.

   .. figure:: ../images/c3-connect-upload-config-browse.png
      :width: 600px

   .. tip:: From the **Filter by type** menu, select either **Sources** or 
            **Sinks** to narrow 
            the available selections for the connector type.

            .. figure:: ../images/c3-filter-source-sink.png
               :scale: 50%

#. Click the **Connect** button on the connector panel you want to configure. 
   The Add Connector page opens to the 01 Setup Connection tab.

   .. figure:: ../images/c3-add-connector.png
      :width: 600px

   .. tip:: There are many available fields for configuring connectors. Click a 
            link in the shortcut panel to quickly jump to a section. The 
            sections shown depend on the connector being set up.

#. Complete the fields as appropriate for the connector. Required fields are 
   indicated with an asterisk.

   .. _c3-add-connector-prop-step:

#. (Optional) If there are additional properties you need to add, click 
   **Add a property**. The Additional Properties dialog opens for you to enter 
   the property name. After entering the property name, enter the value for the 
   property.

   .. figure:: ../images/c3-connector-add-property.png
      :scale: 50%

      Add a property link

   .. figure:: ../images/c3-connector-add-prop-modal.png
      :scale: 50%

      Add property dialog

   .. figure:: ../images/c3-connector-addl-props.png
      :scale: 50%

      Added property

      .. tip:: Click the trash icon to delete an additional property. You have 
               the option to undo the operation.

#. Click **Continue**. The 02 Test and verify page appears (non-|rbac| worfklow).

   .. note:: For an |rbac| workflow, the 02 Security page appears. For more 
             information, see :ref:`c3-add-connector-rbac-workflow`. 

   .. figure:: ../images/c3-connect-download-config-link.png
      :width: 600px

#. (Optional) Click **Download connector config file**. See 
   :ref:`c3_download_connector_config` for details.

#. Review the information and click **Launch**. The 
   information displayed is sent to the 
   :ref:`Connect REST API <connect_userguide_rest>`.

   - If the configuration was successful, the connector appears in the 
     connectors table within the :ref:`c3_connectors_page`.
     Green bars indicate the connector is running.

   - If the configuration was unsuccessful, the **Status** column indicates 
     Failed. Red bars indicate the connector is not running.
     In the **Name** column, click the link for the connector and edit the 
     configuration fields. Repeat the process as necessary.

.. _c3-add-connector-rbac-workflow:

Add a connector (|rbac| environment)
####################################

Follow this procedure to add a connector in |c3-short| when 
|rbac| is enabled. There are typically three steps (tabs) to complete in this 
scenario:

#. Set up the connection
#. Configure security (|rbac|)
#. Test and verify

To use this procedure, your connector configuration must use the standard OAuthBearer 
SASL mechanism, and your worker configuration must not contain principal 
credentials. Otherwise, skip this procedure (02 Security page).

.. important::  If your :ref:`worker configuration <connect-rbac-workers>`
                does not use the OAuthBearer SASL 
                mechanism, do not enter the Connector Username and Password 
                fields in the 02 Security page. The connector configuration will 
                not work if you do so. If you configure a connector to use a 
                different authentication mechanism, that should work as long as 
                the authentication mechanism is enabled on the |ak| cluster.

.. tip:: If you use the OAuthBearer SASL mechanism, it's recommended that you 
         exclude the ``producer.sasl.jaas.config`` and ``consumer.sasl.jaas.config`` 
         properties from your worker file. Instead, specify those properties on 
         a per connector basis with the ``producer.override.sasl.jaas.config`` 
         and ``consumer.override.sasl.jaas.config`` properties. To specify these 
         configurations in a connector, use the 
         **Additional Properties** fields in the 
         **Add Connector > 01 Setup Connection** tab. For instructions on adding 
         a property, see the 
         :ref:`additional properties step <c3-add-connector-prop-step>`. If you 
         specify these additional properties, do not enter the Connector 
         Username and Password fields in the Add Connector page 02 Security tab.
         Simply click **Continue** to skip the 02 Security tab and go directly 
         to the 03 Test and Verify tab.

**To add a connector in a standard RBAC environment**

Complete the steps for adding a connector as described in the non-|rbac| workflow,
:ref:`c3-add-connector`. This procedure describes the details for the 
**02 Security** step in the |rbac| connector workflow.

.. login include

.. include:: security/includes/c3-login.rst

#. Follow steps 1 through 7 in :ref:`c3-add-connector`.

#. (Optional/Conditional) 
   In the step 02 Security page, enter your credentials: 

   - Connector Username (``principal.service.name``)
   - Connector Password (``principal.service.password``)

   .. figure:: ../images/c3-rbac-connector-step3-collapsed.png
      :width: 600px

      Add connector RBAC security workflow collapsed page view

      The ``principal.service.name`` and ``principal.service.password`` are 
      converted into ``producer.override.sasl.jaas.config`` and 
      ``consumer.override.sasl.jaas.config``.

#. (Optional) If you do not have the information, click the
   **How do I get these credentials?** link. The page expands.

   .. figure:: ../images/c3-rbac-connector-template-upper.png
      :width: 600px

      Add Connector RBAC Security Workflow expanded upper page 

   .. figure:: ../images/c3-rbac-connector-template-lower.png
      :width: 600px

      Add connector RBAC security workflow expanded lower page view

   a. Review the information presented on the page, including the documentation 
      links.

   b. Click **Copy to Clipboard**. Send the information to your RBAC
      administrator so that they can grant you the necessary privileges.

      .. tip:: Your |rbac| administrator can also create role bindings
               using the |c3-short| UI rather than the CLI. See 
               :ref:`c3_rbac_manage_roles_ui`.

   c. When you receive the information from your RBAC administrator, 
      complete your credentials.

#. Click **Continue**. The 03 Test and verify page appears.

#. Review the information and click **Launch**.


.. _c3_download_connector_config:

Download a connector configuration file
#######################################

Download a connector configuration file while you are 
:ref:`adding a connector <c3-add-connector>`. 
After downloading the configuration file, you can upload the configuration file 
into another |kconnect| cluster or use it as a template for another connector in 
the same or another |kconnect| cluster.

Supported formats for download:

- ``.json`` file
- ``.properties`` file


#. Select a cluster from the navigation bar and click the **Connect** menu.
   The :ref:`c3_all_connect_clusters_page` appears.
#. In the **Cluster name** column, click the **connect-default** link (or the link 
   for your |kconnect| cluster). The :ref:`c3_connectors_page` appears.

   .. tip: If a connector has already been created, navigate to its Settings
           page to access the download link.

#. Click **Add connector**. Complete the fields as described in 
   :ref:`adding a connector <c3-add-connector>`. Continue to the Test and verify 
   page.

   .. figure:: ../images/c3-connect-download-config-link.png
      :width: 600px

#. Click **Download connector config file**. The Download config file dialog 
   appears.

   .. figure:: ../images/c3-connector-download-config.png
      :scale: 50%


#. Click the file type to download: **Download .JSON** or 
   **Download .properties**.

   The file is downloaded into your downloads directory. When you are done
   downloading files, click **x** to close the download dialog.

   Example JSON connector config file:

   .. code-block:: JSON

      {
       "name": "datagen-users",
       "connector.class": "io.confluent.kafka.connect.datagen.DatagenConnector",
       "key.converter": "org.apache.kafka.connect.storage.StringConverter",
       "kafka.topic": "users",
       "max.interval": "990",
       "iterations": "1000000000",
       "quickstart": "users"
      }

   Example properties connector config file:

   .. sourcecode:: bash
 
      name = datagen-users
      connector.class = io.confluent.kafka.connect.datagen.DatagenConnector
      key.converter = org.apache.kafka.connect.storage.StringConverter
      kafka.topic = users
      max.interval = 990
      iterations = 1000000000
      quickstart = users

#. Click **Launch** to launch the connector.

.. logged MMA-5482 to add a close button

.. _c3_upload_connector_config:

Upload a connector configuration file to add a connector
########################################################

Upload a connector configuration file to add a connector. You can upload a 
connector config file from either the Browse connectors page when adding a 
connector, or directly from the :ref:`c3_connectors_page`.

.. figure:: ../images/c3-connect-upload-config-browse.png
   :width: 600px

   Upload config from Browse connectors

Supported formats for upload:

- ``.json`` file
- ``.properties`` file

#. Select a cluster from the navigation bar and click the **Connect** menu.
   The :ref:`c3_all_connect_clusters_page` appears.
#. In the **Cluster name** column, click the **connect-default** link (or the link 
   for your |kconnect| cluster). The :ref:`c3_connectors_page` appears.

   .. figure:: ../images/c3-connect-upload-config-connectors.png
      :width: 600px

      Upload config from Connectors page

#. Click **+ Upload connector config file**.
#. In the Downloads directory (or navigate to the directory where your 
   config resides), select the configuration file you want to upload and click 
   **Open**.

   - The Connector UI fields are populated with the entries in the configuration 
     file.
   
   - If an error is displayed, make sure the file has valid JSON if applicable. 
     Ensure the JSON or properties file has valid properties for the type of 
     connector.


.. _c3_edit_connector:

Edit a connector
################

:ref:`Pause <c3_pause_resume_connector>` the connector before making configuration 
changes.


#. Select a cluster from the navigation bar and click the **Connect** menu. 
   The :ref:`c3_all_connect_clusters_page` appears.

#. In the **Cluster name** column, click the **connect-default** link (or the link 
   for your |kconnect| cluster). The :ref:`c3_connectors_page` appears.

#. Click the **Name** column for the connector.

#. Click the **Settings** tab.

   .. figure:: ../images/c3-settings-tab.png
      :width: 600px

   .. tip:: Click the **Overview** tab to view a summary.

#. Make the changes you want to the connector fields.

   .. tip:: Hover on a field info (i) icon to get more information about the field.

   .. note:: The Connector class and name fields are locked and cannot be changed.

#. Click **Continue**.

#. (Optional) Click **Download connector config file**. See 
   :ref:`c3_download_connector_config` for details.

#. Review the information and click **Launch**.

.. _c3_pause_resume_connector:

Pause and resume a running connector
####################################

Pause a running connector if you need to troubleshoot or make configuration 
changes. You can pause or resume a connector from either the Overview or the 
Settings pages.

The Overview and Connectors pages display Paused in the Connectors summary 
panel and the Status column for a paused connector.

.. figure:: /images/c3-connect-paused-ov-page.png
   :width: 600px

   Paused connector Overview page

.. figure:: /images/c3-paused-status-connectors-page.png
   :width: 600px

   Paused connector Connectors page

#. :ref:`c3_edit_connector`. The Overview page appears. 

#. Click the Pause icon to pause a running connector.

#. Click the resume (play) icon to allow the connector to run again.

.. tip:: You can also :ref:`delete a connector <c3_delete_connector>` when 
         :ref:`editing a connector <c3_edit_connector>` by clicking 
         the trash can icon. You are prompted to confirm deleting the connector.

.. _c3_delete_connector:

Delete a connector
##################

Delete a connector that is no longer needed. You can 
:ref:`pause <c3_pause_resume_connector>` a 
connector before deleting it. Deleting a connector stops a connector if it is 
running.

You can delete a connector from the Overview or Settings pages.

#. Select a cluster from the navigation bar and click the **Connect** menu. 
   The :ref:`c3_all_connect_clusters_page` appears.

#. In the **Cluster name** column, click the **connect-default** link. The 
   :ref:`c3_connectors_page` appears.

#. Click the **Name** column for the connector. The Overview page appears.

#. Click the trash icon. You are prompted to confirm the deletion.

#. Click **Confirm**.