Configuring a custom agent certificate

Learn how to use your own agent certificate instead of the default certificate that is generated by the Monitoring server installation. Create certificates, a tls secret, and a client key secret before you install the Monitoring server.

Before you begin

Note: Many certificate authorities have multiple layers of certificates, such as a root certificate and an issuer (or signer) certificate. The ca.crt file must be the full chain certificate file. You can use openssl to merge certificates. The following example merges the signer.crt and root.crt files with the ca.crt file:

openssl x509 -in signer.crt -subject -issuer > ca.crt

openssl x509 -in root.crt -subject -issuer >> ca.crt

You must obtain the following files:

A certificate authority (CA) certificate (ca.crt) file that contains the chain of certificates up to (but excluding) the agent certificate, with the additional labels that are added during execution of the openssl x509 commands.
A client certificate (client.crt) file that contains the single certificate that is used by the agents.
A client private key (client.key) file that contains the single private key that is used by the agents.

About this task

When the Monitoring server is installed, a set of signed certificates are created, which are used by the server and agents. You can use your own self-signed certificates or certificates that are issued by a CA, based on your local security requirements.

You can change the certificate that is installed on Monitoring server, the agents, or both.

Note: Changing the certificate on either the server or the agent causes an interruption in service for all previously connected agents and data collectors. After configuring a custom certificate, you must reconfigure all agents and data collectors to connect to the server. For more information see the following topics:
Configuring the downloaded images
Connecting IBM Tivoli Monitoring agents to Monitoring Module server
Connecting Cloud APM agents to Monitoring Module server
Deploying ICAM Data Collectors

Procedure

Identify the Kubernetes tls secret files that are used by using Monitoring with the following command:
```
 kubectl get secret -l release=my_release name
```
Where my_release name is the name of your Monitoring Helm chart, such as ibmcloudappmgmt. By default, the secret names are my_release name-ingress-client and my_release name-ingress.tls.

To update the agent certificate, complete the following steps:

Create a new password file, which protects the keystore databases on the agent machine, by running the following command:
```
echo “password” > client.pass
```

Back up the current secret by running the following command:

 kubectl get secret ibmcloudappmgmt-ingress-client --namespace=my_namespace -o yaml > ibmcloudappmgmt-ingress-client.backup.yaml

Replace the current secret with your new certificate by running the following command:

 kubectl create secret generic ibmcloudappmgmt-ingress-client --namespace=my_namespace --dry-run -o yaml --from-file=client.crt=client.crt --from-file=client.key=client.key --from-file=ca.crt=ca.crt --from-file=client.password=client.pass | kubectl apply -f -

Optional: If you want to restore your original secret, complete the following steps:
1. Open the my_backup_file.yaml file with a text editor, such as vi, where my_backup_file is your backup file name.
2. Remove four lines of code from the metadata section, such as the following example:
```
creationTimestamp: 2018-12-04T22:46:57Z
  resourceVersion: "6698199"
  selfLink: /api/v1/namespaces/default/secrets/ibmcloudappmgmt-ingress-tls
  uid: 8122c479-f816-11e8-bb90-00000a150578
```
3. Run the following command:
```
kubectl replace -f my_backup_file
```

After configuring a custom certificate, you must redeploy pods by restarting or deleting cem-users and apmui pods. You must also generate the new agent keystore databases by restarting the agentbootstrap microservice. Run the following command:

kubectl scale --replicas=0 --namespace=my_namespace deployment ibmcloudappmgmt-agentbootstrap ibmcloudappmgmt-amui ibmcloudappmgmt-ibm-cem-cem-users

kubectl scale --replicas=1 --namespace=my_namespace deployment ibmcloudappmgmt-agentbootstrap ibmcloudappmgmt-amui ibmcloudappmgmt-ibm-cem-cem-users

If your server or agent custom certificates use a range scaling algorithm (RSA) key, you must update the agent configuration. Edit the KDEBE_FIPS_MODE_ENABLED setting in the dst_images_dir/global.environment file, where dst_images_dir is the directory to output the configured agent images. If not specified, the configured agent images are saved in the /depot folder within the parent directory that contains the agent configuration pack. Change the value from KDEBE_FIPS_MODE_ENABLED=SuiteB-128 to KDEBE_FIPS_MODE_ENABLED=SP800-131a.