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
root.crt files with the
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:
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
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:
- Open the
my_backup_file.yamlfile with a text editor, such as vi, where my_backup_file is your backup file name.
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
Run the following command:
kubectl replace -f my_backup_file
- Open the
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_ENABLEDsetting in the
dst_images_dir/global.environmentfile, where dst_images_dir is the directory to output the configured agent images. If not specified, the configured agent images are saved in the
/depotfolder within the parent directory that contains the agent configuration pack. Change the value from