Configuring a custom server certificate

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

Before you begin

If you use the HTTPS protocol to communicate between the Cloud App Management server and the agents, the server allows connections from the resources that authenticate themselves with a valid certificate. To enable communication between the IBM® Cloud App Management server, browsers, and agents, you can configure custom certificates.

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 server certificate, with the additional labels that are added during execution of the openssl x509 commands.
A server certificate (server.crt) file that contains the single certificate used by the server.
A server private key (server.key) file that contains the single private key used by the server.

About this task

When the Cloud App Management 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 issued by a CA, based on your local security requirements.

You can change the certificate installed on the Cloud App Management 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:

Procedure

Identify the Kubernetes tls secret files used by IBM Cloud App Management with the following command:
```
kubectl get secret -l release=my_release name
```
Where my_release name is the name of your Cloud App Management 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 server certificate, complete the following steps:
1. Back up the current secret by running the following command:
```
kubectl get secret ibmcloudappmgmt-ingress-tls --namespace=my_namespace -o yaml > ibmcloudappmgmt-ingress-tls.backup.yaml
```
  where -- denotes an optional parameter and my_namespace is the namespace that the installation image file is loaded to.
2. Replace the current secret with your new certificate by running the following command:
```
kubectl create secret generic ibmcloudappmgmt-ingress-tls --namespace=my_namespace --dry-run -o yaml --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt | kubectl apply -f -
```
3. 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 custom certificate uses 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.