1.2. Certificates

Various certificates are created and used throughout Red Hat Advanced Cluster Management for Kubernetes.

You can bring your own certificates. You must create a Kubernetes TLS Secret for your certificate. After you create your certificates, you can replace certain certificates that are created by the Red Hat Advanced Cluster Management for Kubernetes installer.

Required access: Cluster administrator or team administrator.

Note: Replacing certificates is supported only on native Red Hat Advanced Cluster Management for Kubernetes installations.

All certificates required by services that run on Red Hat Advanced Cluster Management for Kubernetes are created during the installation of Red Hat Advanced Cluster Management for Kubernetes. Certificates are created and managed by the Red Hat Advanced Cluster Management for Kubernetes Certificate manager (cert-manager) service.

See the following topics to replace certificates:

1.2.1. Certificates

The Red Hat Advanced Cluster Management for Kubernetes Root CA Certificate is stored within the Kubernetes Secret multicloud-ca-cert in the hub cluster namespace. The certificate can be imported into your client truststores to access Red Hat Advanced Cluster Management for Kubernetes Platform APIs.

1.2.1.1. Created and managed by Red Hat Advanced Cluster Management for Kubernetes Certificate manager (cert-manager)

View the following table of the internal services that use cert-manager to create and manage their certificates:

表 1.8. Internal services for certificate manager
Certificate Name	Issuer Name	Secret Name	Usage
`console-chart-ef680-ca-cert`	`multicluster-hub-mcm-server-ca-issuer`	`console-chart-ef680-uiapi-secrets`	Red Hat Advanced Cluster Management for Kubernetes Console CA cert
`grc-59010-ca-cert`	`multicluster-hub-mcm-server-ca-issuer`	`grc-59010-grc-secrets`	Red Hat Advanced Cluster Management for Kubernetes Govern and risk CA cert
`kui-proxy`	`multicloud-ca-issuer`	`kui-proxy-secret`	Visual Web Terminal
`management-ingress-a0ae5-cert`	`multicloud-ca-issuer`	`management-ingress-c38ac-tls-secret`	Ingress
`multicloud-ca-cert`	`cert-manager-rhacm-selfsign`	`multicloud-ca-cert`	Red Hat Advanced Cluster Management for Kubernetes root CA
`search-prod-c62a6-aggregator-ca-cert`	`multicloud-ca-issuer`	`search-prod-95fcc-search-secrets`	Search
`search-prod-c62a6-redis-ca-cert`	`multicloud-ca-issuer`	`search-prod-95fcc-redisgraph-secrets`	Search
`search-prod-c62a6-search-ca-cert`	`multicloud-ca-issuer`	`search-prod-95fcc-search-api-secrets`	Search
`topology-276c4-ca-cert`	`multicluster-hub-mcm-server-ca-issuer`	`topology-b24e0-topology-secrets`	Topology

The OpenShift Container Platform certificate is not included in the Red Hat Advanced Cluster Management for Kubernetes management ingress. For more information, see the Security known issues. Use the certificate policy controller to create and manage certificate policies on managed clusters. See Policy controllers to learn more about controllers. Return to the Security page for more information.

1.2.2. Replacing the root CA certificate

You can replace the root CA certificate.

1.2.2.1. Prerequisites for root CA certificate

Verify that your Red Hat Advanced Cluster Management for Kubernetes cluster is running.

Back up the existing Red Hat Advanced Cluster Management for Kubernetes certificate resource by running the following command:

oc get cert multicloud-ca-cert -n open-cluster-management -o yaml > multicloud-ca-cert-backup.yaml

1.2.2.2. Creating the root CA certificate with OpenSSL

Complete the following steps to create a root CA certificate with OpenSSL:

Generate your certificate authority (CA) RSA private key by running the following command:
```
openssl genrsa -out ca.key 4096
```

Generate a self-signed CA certificate by using your CA key. Run the following command:

openssl req -x509 -new -nodes -key ca.key -days 400 -out ca.crt -config req.cnf

Your req.cnf file might resemble the following file:

[ req ]               # Main settings
default_bits = 4096       # Default key size in bits.
prompt = no               # Disables prompting for certificate values so the configuration file values are used.
default_md = sha256       # Specifies the digest algorithm.
distinguished_name = dn   # Specifies the section that includes the distinguished name information.
x509_extensions = v3_ca   # The extentions to add to the self signed cert

[ dn ]               # Distinguished name settings
C = US                    # Country
ST = North Carolina             # State or province
L = Raleigh                # Locality
O = Red Hat Open Shift     # Organization
OU = Red Hat Advanced Container Management        # Organizational unit
CN = www.redhat.com  # Common name.

[ v3_ca ]          # x509v3 extensions
basicConstraints=critical,CA:TRUE # Indicates whether the certificate is a CA certificate during the certificate chain verification process.

1.2.2.3. Replacing root CA certificates

Create a new secret with the CA certificate by running the following command:

kubectl -n open-cluster-management create secret tls byo-ca-cert --cert ./ca.crt --key ./ca.key

Edit the CA issuer to point to the BYO certificate. Run the following commnad:
```
oc edit issuer -n open-cluster-management multicloud-ca-issuer
```
Replace the string mulicloud-ca-cert with byo-ca-cert. Save your deployment and quit the editor.
Edit the management ingress deployment to reference the Bring Your Own (BYO) CA certificate. Run the following command:
```
oc edit deployment management-ingress-435ab
```
Replace the multicloud-ca-cert string with the byo-ca-cert. Save your deployment and quit the editor.
Validate the custom CA is in use by logging in to the console and view the details of the certificate being used.

1.2.2.4. Refreshing cert-manager certificates

After the root CA is replaced, all certificates that are signed by the root CA must be refreshed and the services that use those certificates must be restarted. Cert-manager creates the default Issuer from the root CA so all of the certificates issued by cert-manager, and signed by the default ClusterIssuer must also be refreshed.

Delete the Kubernetes secrets associated with each cert-manager certificate to refresh the certificate and restart the services that use the certificate. Run the following command:

oc delete secret -n open-cluster-management $(oc get cert -n open-cluster-management -o wide | grep multicloud-ca-issuer | awk '{print $3}')

1.2.2.5. Restoring root CA certificates

To restore the root CA certificate, update the CA issuer by completing the following steps:

Edit the CA issuer. Run the following command:

oc edit issuer -n open-cluster-management multicloud-ca-issuer

Replace the byo-ca-cert string with multicloud-ca-cert in the editor. Save the issuer and quit the editor.
Edit the management ingress depolyment to reference the original CA certificate. Run the following command:
```
oc edit deployment management-ingress-435ab
```
Replace the byo-ca-cert string with the multicloud-ca-cert string. Save your deployment and quit the editor.
Delete the BYO CA certificate. Run the following commnad:
```
oc delete secret -n open-cluster-management byo-ca-cert
```

Refresh all cert-manager certificates that use the CA. For more information, see the forementioned section, Refreshing cert-manager certificates.

See Certificates for more information about certificates that are created and managed by Red Hat Advanced Cluster Management.

1.2.3. Replacing the management ingress certificates

You can replace management ingress certificates. If you replace the default ingress certificate for OpenShift Container Platform, you need to make modifications to the management ingress. For more information see, 500 Internal error during login to the console in the Security known issues.

1.2.3.1. Prerequisites to replace management ingress certificate

Prepare and have your management-ingress certificates and private keys ready. If needed, you can generate a TLS certificate by using OpenSSL. Set the common name parameter,CN, on the certificate to manangement-ingress. If you are generating the certificate, include the following settings:

Include the following IP addresses and domain names in your certificate Subject Alternative Name (SAN) list:
- The service name for the management ingress: management-ingress.
- Include the route name for Red Hat Advanced Cluster Management for Kubernetes. Recieve the route name by running the following command:
```
oc get route -n open-cluster-management
```
  You might receieve the following response:
```
multicloud-console.apps.grchub2.dev08.red-chesterfield.com
```
- Add the localhost IP address: 127.0.0.1.
- Add the localhost entry: localhost.

1.2.3.1.1. Example configuration file for generating a certificate

The following example configuration file and OpenSSL commands provide an example for how to generate a TLS certificate by using OpenSSL. View the following csr.cnf configuration file, which defines the configuration settings for generating certificates with OpenSSL.

[ req ]               # Main settings
default_bits = 2048       # Default key size in bits.
prompt = no               # Disables prompting for certificate values so the configuration file values are used.
default_md = sha256       # Specifies the digest algorithm.
req_extensions = req_ext  # Specifies the configuration file section that includes any extensions.
distinguished_name = dn   # Specifies the section that includes the distinguished name information.

[ dn ]               # Distinguished name settings
C = US                    # Country
ST = North Carolina             # State or province
L = Raleigh                # Locality
O = Red Hat Open Shift     # Organization
OU = Red Hat Advanced Container Management        # Organizational unit
CN = management-ingress  # Common name.

[ req_ext ]          # Extensions
subjectAltName = @alt_names # Subject alternative names

[ alt_names ]        # Subject alternative names
DNS.1 = management-ingress
DNS.2 = multicloud-console.apps.grchub2.dev08.red-chesterfield.com
DNS.3 = localhost
DNS.4 = 127.0.0.1

[ v3_ext ]          # x509v3 extensions
authorityKeyIdentifier=keyid,issuer:always  # Specifies the public key that corresponds to the private key that is used to sign a certificate.
basicConstraints=CA:FALSE                   # Indicates whether the certificate is a CA certificate during the certificate chain verification process.
#keyUsage=keyEncipherment,dataEncipherment   # Defines the purpose of the key that is contained in the certificate.
extendedKeyUsage=serverAuth                 # Defines the purposes for which the public key can be used.
subjectAltName=@alt_names                   # Identifies the subject alternative names for the identify that is bound to the public key by the CA.

注意

Be sure to update the SAN labeled, DNS.2 with the correct hostname for your management ingress.

1.2.3.1.2. OpenSSL commands for generating a certificate

The following OpenSSL commands are used with the preceding configuration file to generate the required TLS certificate.

Generate your certificate authority (CA) RSA private key:
```
openssl genrsa -out ca.key 4096
```

Generate a self-signed CA certificate by using your CA key:

openssl req -x509 -new -nodes -key ca.key -subj "/C=US/ST=North Carolina/L=Raleigh/O=Red Hat OpenShift" -days 400 -out ca.crt

Generate the RSA private key for your certificate:
```
openssl genrsa -out ingress.key 4096
```
Generate the Certificate Signing request (CSR) by using the private key:
```
openssl req -new -key ingress.key -out ingress.csr -config csr.cnf
```

Generate a signed certificate by using your CA certificate and key and CSR:

openssl x509 -req -in ingress.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out ingress.crt -sha256 -days 300 -extensions v3_ext -extfile csr.cnf

Examine the certificate contents:

openssl x509  -noout -text -in ./ingress.crt

1.2.3.2. Replace the Bring Your Own (BYO) ingress certificate

Complete the following steps to replace your BYO ingress certificate:

Create the byo-ingress-tls secret by using your certificate and private key. Run the following command:

kubectl -n open-cluster-management create secret tls byo-ingress-tls-secret --cert ./ingress.crt --key ./ingress.key

Verify that the secret is created in the correct namespace.

kubectl get secret -n open-cluster-management | grep byo-ingress | grep tls

Create a secret containing the CA certificate by running the following command:

kubectl -n open-cluster-management create secret tls byo-ca-cert --cert ./ca.crt --key ./ca.key

Edit the management ingress deployment. Get the name of the deployment. Run the following commands:
```
export MANAGEMENT_INGRESS=`oc get deployment -o custom-columns=:.metadata.name | grep management-ingress`

oc edit deployment $MANAGEMENT_INGRESS -n open-cluster-management
```
- Replace the multicloud-ca-cert string with byo-ca-cert.
- Replace the $MANAGEMENT_INGRESS-tls-secret string with byo-ingress-tls-secret.
- Save your deployment and close the editor. The management ingress automatically restarts.
After the management ingress pod has restarted, navigate to the Red Hat Advanced Cluster Management for Kubernetes console from your browser. Verify that the current certificate is your certificate, and that all console access and login functionality remain the same.

1.2.3.3. Restore the default self-signed certificate for management ingress

Edit the management ingress deployment. Replace the string multicloud-ca-cert with byo-ca-cert. Get the name of the deployment. Run the following commands:
```
export MANAGEMENT_INGRESS=`oc get deployment -o custom-columns=:.metadata.name | grep management-ingress`

oc edit deployment $MANAGEMENT_INGRESS -n open-cluster-management
```
1. Replace the byo-ca-cert string with multicloud-ca-cert.
2. Replace the byo-ingress-tls-secret string with the $MANAGEMENT_INGRESS-tls-secret.
3. Save your deployment and close the editor. The management ingress automatically restarts.
After all pods are restarted, navigate to the Red Hat Advanced Cluster Management for Kubernetes console from your browser. Verify that the current certificate is your certificate, and that all console access and login functionality remain the same.

Delete the Bring Your Own (BYO) ingress secret and ingress CA certificate by running the following commands:

oc delete secret -n open-cluster-management byo-ingress-tls-secret
oc delete secret -n open-cluster-management byo-ca-cert

See Certificates for more information about certificates that are created and managed by Red Hat Advanced Cluster Management. Return to the Security page for more information on securing your cluster.