Create and Install the Control Plane

The Control Plane is a machine with access to the message broker such that configurations of the broker as well as calling the cb-ctl command can be performed.

In a production environment usually many users will use cb-ctl outside of the control plane. As there are many different access scenarious thinkable, this documentation is based on the most simple access method which is based on ssh to the control plane and calling cb-ctl from there. Please note this is not the recommended way for a production environment.

Note

The following requires Kafka to run. The steps to setup the control plane are documented based on Kafka running on Amazon MSK and with the control plane to be an instance running on Amazon EC2, both in the same region. If these prerequisites do not match your environment, some of the following information will not apply.

  1. Start an instance to become the control plane

    The used AMI ID points to a Leap system.

    Replace the camel case parameter values with your own.

    leap_15_3_ami=ami-0b4f49bedf96b14c9
username=ec2-user

  2. SSH to the control plane

    ssh -i PathToPkeyMatchingMySSHKeyPairName \
    ${username}@InstanceIP

  3. Install Cloud Builder on the control plane

    sudo zypper addrepo https://download.opensuse.org/repositories/Virtualization:/Appliances:/CloudBuilder/openSUSE_Leap_15.3 cloud-builder
sudo zypper install python3-cloud_builder

  4. Install Kafka admin utilities

    sudo zypper install java-1_8_0-openjdk
wget https://archive.apache.org/dist/kafka/2.2.1/kafka_2.12-2.2.1.tgz
tar -xzf kafka_2.12-2.2.1.tgz

Control Plane Configuration

Now that the control plane runs the following configurations are required:

  1. Fetch the Zookeeper Connect String

    In the pop up window under the headline Apache ZooKeeper connection Copy and preserve this information temporarily

  2. Login to the Control Plane

    ssh -i PathToPkeyMatchingMySSHKeyPairName \
    ${username}@InstanceIP

  3. Create Cloud Builder Publish/Subscribe message topics

    A message queue in Kafka is named a topic. The following topics are used by Cloud Builder in Publish/Subscribe mode. This means each message is broadcast to all readers. This setting applies to the topics cb-response, cb-info-request, cb-info-response. Create these topics as follows:

    cd kafka_2.12-2.2.1
for topic in cb-response cb-info-request cb-info-response; do
    bin/kafka-topics.sh \
        --create \
        --zookeeper ZookeeperConnectString \
        --replication-factor 2 \
        --partitions 1 \
        --topic ${topic};
done

  4. Create Cloud Builder Shared message topic

    Cloud Builder is designed to scale automatically on the number of runner instances. This means if there are e.g 10 runners in the runner_group e.g fedora, it is expected that package requests gets distributed to all runners. For this concept to work in Kafka it’s important to assign 10 partitions to the topic that handles the requests. For more details on how kafka balances consumers click here

    At this point a decision about the later size of the system needs to be made. It’s possible to change the assigned number of partitions at a later point in time. For this example setup the following conditions are set:

    • 2 runner groups, fedora and suse.

    • 2 partitions for each runner group

    This will require to run 4 runner instances later, 2 for each runner group. Create the topics for these setup as follows:

    cd kafka_2.12-2.2.1
for topic in fedora suse; do
    bin/kafka-topics.sh \
        --create \
        --zookeeper ZookeeperConnectString \
        --replication-factor 2 \
        --partitions 2 \
        --topic ${topic};
done

  5. Set appropriate retention time for topics

    By default kafka topics have a retention time of 7 days which is quite long for some of the topics created before. As a good start the following retention times should be set:

    Runner Group Topics: 60min

    The runner group topics are the ones receiving the build requests. Keeping build requests for an hour should be enough to survive a potential kafka rebalance.

    cb-info-response and cb-info-request: 2min

    The cb-info-* topics are used to communicate with the build cluster. It is expected that requests sent will be answered more or less immeditately. Thus the retention time for these topics should be small.

    cb-response: keep or increase

    The cb-response topic receives all messages from all Cloud Builder services. It is used to watch the cluster for basically everything. The default retention time of 7 days is a good start but could also increased.

    cd kafka_2.12-2.2.1
for topic in fedora suse; do
    bin/kafka-topics.sh \
        --alter \
        --zookeeper ZookeeperConnectString \
        --config retention.ms=3600000 \
        --topic ${topic};
done
for topic in cb-info-response cb-info-request; do
    bin/kafka-topics.sh \
        --alter \
        --zookeeper ZookeeperConnectString \
        --config retention.ms=120000 \
        --topic ${topic};
done

  6. Configure cb-ctl

    Last step is the configuration of Cloud Builder to allow access to the Kafka service and the later runners.

    In the pop up window under the headline Bootstrap servers Copy and preserve this information temporarily

    Create the file /etc/cloud_builder_broker.yml as follows:

    sudo vi /etc/cloud_builder_broker.yml

    Place the following content:

    broker:
  host: BootstrapServersString
this_host: external_IP_or_Hostname_of_this_instance

    For collecting build results and log information Cloud Builder services uses SSH with public/private key authorization. This requires the setup of an SSH keypair associated with a trusted user on the runner. In the setup procedure of the runner this user is created and called cb-collect. In the setup procedure of the control plane the used SSH keypair is created once as folows:

    ssh-keygen -t rsa -f ~/.ssh/id_cb_collect

    Create the file ~/.config/cb/cbctl.yml as follows:

    vi ~/.config/cb/cbctl.yml

    Place the following content:

    cluster:
  ssh_user: cb-collect
  ssh_pkey_file: HOME/.ssh/id_cb_collect
  runner_count: 2

    Replace HOME with the absolute path to the home directory of the user that is expected to call cb-ctl

    Note

    runner count

    The configured number of runners (2) in this example is optional but recommended and tells cb-ctl to expect information from 2 runners. This setting avoids unneeded wait times as explained in step 5 of the runner setup from here Runner Setup

Congrats, the control plane is now running, the kafka message broker is up and configured and cb-ctl would be ready for a first package build request. However, there are no runners which could work on such a request. Learn how to setup the Cloud Builder runner(s) next: Runner Setup