Configuring

The default DC/OS Confluent Kafka installation provides reasonable defaults for trying out the service, but may not be sufficient for production use. You may require a different configuration depending on the context of the deployment.

Installing with Custom Configuration

The following are some examples of how to customize the installation of your Confluent Kafka instance.

In each case, you would create a new Confluent Kafka instance using the custom configuration as follows:

dcos package install confluent-kafka --options=sample-confluent-kafka.json

We recommend that you store your custom configuration in source control.

Installing multiple instances

By default, the Confluent Kafka service is installed with a service name of confluent-kafka. You may specify a different name using a custom service configuration as follows:

{
  "service": {
    "name": "confluent-kafka-other"
  }
}

When the above JSON configuration is passed to the package install confluent-kafka command via the --options argument, the new service will use the name specified in that JSON configuration:

dcos package install confluent-kafka --options=confluent-kafka-other.json

Multiple instances of Confluent Kafka may be installed into your DC/OS cluster by customizing the name of each instance. For example, you might have one instance of Confluent Kafka named confluent-kafka-staging and another named confluent-kafka-prod, each with its own custom configuration.

After specifying a custom name for your instance, it can be reached using dcos confluent-kafka CLI commands or directly over HTTP as described below.

WARNING: The service name cannot be changed after initial install. Changing the service name would require installing a new instance of the service against the new name, then copying over any data as necessary to the new instance.

Installing into folders

In DC/OS 1.10 and later, services may be installed into folders by specifying a slash-delimited service name. For example:

{
  "service": {
    "name": "/foldered/path/to/confluent-kafka"
  }
}

The above example will install the service under a path of foldered => path => to => confluent-kafka. It can then be reached using dcos confluent-kafka CLI commands or directly over HTTP as described below.

WARNING: The service folder location cannot be changed after initial install. Changing the folder location would require installing a new instance of the service against the new name, then copying over any data as necessary to the new instance.

Addressing named instances

After you’ve installed the service under a custom name or under a folder, it may be accessed from all dcos confluent-kafka CLI commands using the --name argument. By default, the --name value defaults to the name of the package, or confluent-kafka.

For example, if you had an instance named confluent-kafka-dev, the following command would invoke a pod list command against it:

dcos confluent-kafka --name=confluent-kafka-dev pod list

The same query would be over HTTP as follows:

curl -H "Authorization:token=$auth_token" <dcos_url>/service/confluent-kafka-dev/v1/pod

Likewise, if you had an instance in a folder like /foldered/path/to/confluent-kafka, the following command would invoke a pod list command against it:

dcos confluent-kafka --name=/foldered/path/to/confluent-kafka pod list

Similarly, it could be queried directly over HTTP as follows:

curl -H "Authorization:token=$auth_token" <dcos_url>/service/foldered/path/to/confluent-kafka-dev/v1/pod

You may add a -v (verbose) argument to any dcos confluent-kafka command to see the underlying HTTP queries that are being made. This can be a useful tool to see where the CLI is getting its information. In practice, dcos confluent-kafka commands are a thin wrapper around an HTTP interface provided by the DC/OS Confluent Kafka Service itself.

Integration with DC/OS access controls

In Enterprise DC/OS, DC/OS access controls can be used to restrict access to your service. To give a non-superuser complete access to a service, grant them the following list of permissions:

dcos:adminrouter:service:marathon full
dcos:service:marathon:marathon:<service-name> full
dcos:service:adminrouter:<service-name> full
dcos:adminrouter:ops:mesos full
dcos:adminrouter:ops:slave full

Where <service-name> is your full service name, including the folder if it is installed in one.

Service Settings

Placement Constraints

Placement constraints allow you to customize where a service is deployed in the DC/OS cluster. Placement constraints use the Marathon operators syntax. For example, [["hostname", "UNIQUE"]] ensures that at most one pod instance is deployed per agent.

A common task is to specify a list of whitelisted systems to deploy to. To achieve this, use the following syntax for the placement constraint:

[["hostname", "LIKE", "10.0.0.159|10.0.1.202|10.0.3.3"]]

IMPORTANT: Be sure to include excess capacity in such a scenario so that if one of the whitelisted systems goes down, there is still enough capacity to repair your service.

Updating Placement Constraints

Clusters change, and as such so will your placement constraints. However, already running service pods will not be affected by changes in placement constraints. This is because altering a placement constraint might invalidate the current placement of a running pod, and the pod will not be relocated automatically as doing so is a destructive action. We recommend using the following procedure to update the placement constraints of a pod:

Update the placement constraint definition in the service.
For each affected pod, one at a time, perform a pod replace. This will (destructively) move the pod to be in accordance with the new placement constraints.

Zones Enterprise

Requires: DC/OS 1.11 Enterprise or later.

Placement constraints can be applied to DC/OS zones by referring to the @zone key. For example, one could spread pods across a minimum of three different zones by including this constraint:

[["@zone", "GROUP_BY", "3"]]

For the @zone constraint to be applied correctly, DC/OS must have Fault Domain Awareness enabled and configured.

WARNING: A service installed without a zone constraint cannot be updated to have one, and a service installed with a zone constraint may not have it removed.

Virtual networks

DC/OS Confluent Kafka supports deployment on virtual networks on DC/OS (including the dcos overlay network), allowing each container (task) to have its own IP address and not use port resources on the agent machines. This can be specified by passing the following configuration during installation:

{
  "service": {
    "virtual_network_enabled": true
  }
}

NOTE: Once the service is deployed on a virtual network, it cannot be updated to use the host network.

User

By default, all pods’ containers will be started as system user “nobody”. If your system configured for using over system user (for instance, you may have externally mounted persistent volumes with root’s permissions), you can define the user by defining a custom value for the service’s property “user”, for example:

{
  "service": {
    "properties": {
      "user": "root"
    }
  }
}

Regions

The service parameter region can be used to deploy the service in an alternate region. By default the service is deployed in the “local” region, which is the region the DC/OS masters are running in. To install a service in a specific reason, include in its options:

{
  "service": {
    "region": "<region>"
  }
}

WARNING: A service may not be moved between regions.

Switching to Confluent Kafka Community

WARNING: It is not recommended to use Community service for production.

To enable Community flavour of Confluent Kafka, issue an update with following steps.

Create file named options.json with the following contents.
```
{
  "service": {
    "community": true
  }
}
```
Install Confluent Kafka Community with the options file you created.
```
$ dcos package install confluent-kafka --options="options.json"
```

Add Enterprise License Confluent Kafka Enterprise

License can be added to Confluent Kafka brokers even after the service has been installed. To add the license to brokers, issue an update with the following steps.

Create file named options.json with the following contents.

{
  "service": {
    "license": "your license",
    "community": false
  }
}

IMPORTANT: License can only be added for Enterprise version. Make sure to turn the community flag to false.

Install Confluent Kafka Community with the options file you created.
```
$ dcos package install confluent-kafka --options="options.json"
```

Configuring the ZooKeeper Connection.

Confluent Kafka requires a running ZooKeeper ensemble to perform its own internal accounting. By default, the DC/OS Confluent Kafka Service uses the ZooKeeper ensemble made available on the Mesos masters of a DC/OS cluster at master.mesos:2181/dcos-service-<servicename>. At install time, you can configure an alternate ZooKeeper for Confluent Kafka to use. This enables you to increase Confluent Kafka’s capacity and removes the DC/OS System ZooKeeper ensemble’s involvement in running it.

NOTE: If you are using the DC/OS Apache ZooKeeper service, use the DNS addresses provided by the dcos confluent-zookeeper endpoints clientport command as the value of kafka_zookeeper_uri.

To configure an alternate Zookeeper instance:

Create a file named options.json with the following contents. Here is an example options.json which points to a confluent-zookeeper instance named confluent-zookeeper:

{
  "kafka": {
    "kafka_zookeeper_uri": "zookeeper-0-server.confluent-zookeeper.autoip.dcos.thisdcos.directory:1140,zookeeper-1-server.confluent-zookeeper.autoip.dcos.thisdcos.directory:1140,zookeeper-2-server.confluent-zookeeper.autoip.dcos.thisdcos.directory:1140"
  }
}

Install Confluent Kafka with the options file you created.

$ dcos package install confluent-kafka --options="options.json"

You can also update an already-running Confluent Kafka instance from the DC/OS CLI, in case you need to migrate your ZooKeeper data elsewhere.

NOTE: Before performing this configuration change, you must first copy the data from your current ZooKeeper ensemble to the new ZooKeeper ensemble. The new location must have the same data as the previous location during the migration.

$ dcos confluent-kafka --name=confluent-kafka update start --options=options.json

Extend the Kill Grace Period

When performing a requested restart or replace of a running broker, the Kafka service will wait a default of 30 seconds for a broker to exit, before killing the process. This grace period may be customized via the brokers.kill_grace_period setting. In this example we will use the DC/OS CLI to increase the grace period delay to 60 seconds. This example assumes that the Kafka service instance is named confluent-kafka.

During the configuration update, each of the Kafka broker tasks are restarted. During the shutdown portion of the task restart, the previous configuration value for brokers.kill_grace_period is in effect. Following the shutdown, each broker task is launched with the new effective configuration value. Take care to monitor the amount of time Kafka brokers take to cleanly shut down by observing their logs.

Replacing a Broker with Grace

The grace period must also be respected when a broker is shut down before replacement. While it is not ideal that a broker must respect the grace period even if it is going to lose persistent state, this behavior will be improved in future versions of the SDK. Broker replacement generally requires complex and time-consuming reconciliation activities at startup if there was not a graceful shutdown, so the respect of the grace kill period still provides value in most situations. We recommend setting the kill grace period only sufficiently long enough to allow graceful shutdown. Monitor the Kafka broker clean shutdown times in the broker logs to keep this value tuned to the scale of data flowing through the Kafka service.

Configuring Confluent Kafka