Add trusted agents to clusters

Perform the following procedures in these situations:

Every time that you create trusted agents.
Every time that you revoke the certificates of existing trusted agents.
To create a gateway to a zone with trusted agents at both ends. You have to do this only a few times.
When you want all agents in cluster to be trusted.

You can select one of these methods to add a trusted agent to a cluster:

Before adding the trusted agent, shut down all but one node in the cluster. Go to Method 1 .
Keep most of the nodes up while adding trusted agents. Go to Method 2 .

Preparing Your Cluster Environment

Perform the following steps one time when configuring the cluster to work with trusted agents. You can skip these steps if you have already done them.

Select the server node. This should be the node you used to upload configuration files to ZooKeeper while performing the procedure in Uploading Configuration Files to ZooKeeper .
Confirm that the certificate files from the node you selected and from ZooKeeper match by using the verifyClusterCertificate.pl script. For detailed instructions and the script output, see the KBEC-00342 - Using the verifyClusterCertificate.pl script for Trusted Agents Knowledge Base article.

In the script output, look for SUCCESS to confirm that certificate files match. If this fails, you might be on the wrong node.
Replace the conf/security folder on all nodes with the conf/security folder from node selected in Step 1 .
If you want to add a trusted agent to a cluster and it is OK to shut down all but one node in the cluster, go to link:#Method1[Method 1] .
If you want to keep most of the nodes up while adding trusted agents, perform the rest of the steps in this procedure.
(Windows platforms) Change directories to the <data_dir>/conf/ folder.

Upload the conf/security folder from the node you selected to ZooKeeper by using the following command:

Linux:

COMMANDER_ZK_CONNECTION=<ZooKeeper_Server_IP>:2181 <install_dir>/jre/bin/java -cp <install_dir>/server/bin/zk-config-tool-jar-with-dependencies.jar com.electriccloud.commander.zkconfig.ZKConfigTool --writeFolder /commander/conf/security <data_dir>/conf/security▼

Windows:

"C:\Program Files\CloudBees\Software Delivery Automation\jre\bin\java.exe" -DCOMMANDER_ZK_CONNECTION=<ZooKeeper_Server_IP>:2181 -jar "C:\Program Files\CloudBees\Software Delivery Automation\server\bin\zk-config-tool-jar-with-dependencies.jar" com.electriccloud.commander.cluster.ZKConfigTool --confSecurityFolder security▼

On all cluster nodes:
1. Open wrapper.conf in the <data_dir>/conf directory.
2. Uncomment the following line:
  wrapper.java.additional.603=-DCLUSTER_CERTIFICATE_SERVICE_USE_ZOOKEEPER=true
  ▼
3. Make sure that DCLUSTER_CERTIFICATE_SERVICE_USE_ZOOKEEPER is set to true.
  
  Ensure that there is no conflict with number 603 and that it is not already used in the system.
Restart the nodes with updated configurations.
Go to link:#Method2[Method 2] .

Method 1

Follow these steps to add a trusted agent to a cluster by first shutting down all but one node in the cluster. Perform the tasks from Step 2 to Step 4 on the agent machine.

Shut down all but one node in the cluster.
On the machine with an agent that you want to make a trusted agent, enter commands such as the following to create the trusted agent:
1. ectool --server <Server_host> login admin changeme to log into the server with the specified hostname of IP address and save the session ID.
2. To make a remote agent trusted, enter:
  <install_dir>/bin/eccert initAgent --remote --force
  ▼
  to generate a certificate request for this agent, send a certificate authority (CA) request to the CloudBees CD/RO server (the CA), receive a signed certificate from the CA for this agent, and add the CA certificate and the agent’s private key (also signed by the CA) to the agent’s keystore.
  
  To make a local agent (that is, local to the CloudBees CD/RO server) trusted, enter:
  <install_dir>/bin/eccert initAgent --remote --force
  ▼
  The CloudBees CD/RO server keeps a copy of the signed agent certificate in the $install_dir/conf/security/certs directory.
  
  Do not use eccert as sudo, which would change the ownership of the configuration files such as the keystore file to the root user. These files must be owned by the user who starts the CloudBees CD/RO services.
On the agent machine, enter
```
ectool createResource <agent_name> --hostName <agent_FQDN_or_IP> --trusted true▼
```
to add the agent as a trusted agent to the CloudBees CD/RO server in the previous step, where <agent_FQDN_or_IP> is the fully-qualified domain name or IP address of the agent.
Restart the agent on the agent machine.

Method 2

Perform the following steps on an agent machine to add a trusted agent to a cluster without shutting down server nodes. This procedure works only in CloudBees CD/RO 6.3 or later.

Due to limitations in ZooKeeper, using this method imposes a maximum of around 500 signed certificates. If you want to use this method and are likely to need more than 500 trusted agents, we recommend re-using a certificate across multiple trusted agents.

On the machine with an agent that you want to make a trusted agent, enter commands such as the following to create the trusted agent:
1. ectool --server <Server_host> login admin changeme to log into the server with the specified hostname of IP address and save the session ID.
2. To make a remote agent trusted, enter:
  <install_dir>/bin/eccert initAgent --remote --force
  ▼
  to generate a certificate request for this agent, send a certificate authority (CA) request to the CloudBees CD/RO server (the CA), receive a signed certificate from the CA for this agent, and add the CA certificate and the agent’s private key (also signed by the CA) to the agent’s keystore.
  
  To make a local agent (that is, local to the CloudBees CD/RO server) trusted, enter:
  <install_dir>/bin/eccert initAgent --remote --force
  ▼
  The CloudBees CD/RO server keeps a copy of the signed agent certificate in the $install_dir/conf/security/certs directory.
On the agent machine, enter
```
ectool createResource <agent_name> --hostName <agent_FQDN_or_IP> --trusted true▼
```
to add the agent as a trusted agent to the CloudBees CD/RO server in the previous step, where <agent_FQDN_or_IP> is the fully-qualified domain name or IP address of the agent.
Restart the agent on the agent machine.