Configure TLS certificates for cluster applications

The Container Cloud web UI and StackLight endpoints are available through Transport Layer Security (TLS) with self-signed certificates generated by the Container Cloud provider.

Caution

The Container Cloud endpoints are available only through HTTPS.

You can configure TLS certificates for the following applications on a Container Cloud management cluster or regional clusters:

  • Keycloak

  • Container Cloud web UI

  • mcc-cache Available since 2.20.0

Since Container Cloud 2.20.0, you can configure TLS certificates for MKE on managed clusters deployed or updated by Container Cloud using the latest Cluster release in its series.

Note

TLS certificates configuration for MKE is not supported:

  • For MOSK-based clusters

  • For attached MKE clusters that were not originally deployed by Container Cloud

Caution

  • The organization administrator must ensure that the application host name is resolvable within and outside the cluster.

  • Custom TLS certificates for Keycloak are supported for new and existing clusters originally deployed using Container Cloud 2.9.0 or later.

Prepare TLS certificates

  1. Obtain your DNS server name. For example, container-cloud-auth.example.com.

  2. Buy or generate a certificate from a certification authority (CA) that contains the following items:

    • A full CA bundle including the root and all intermediate CA certificates.

    • Your server certificate issued for the container-cloud-auth.example.com DNS name.

    • Your secret key that was used to sign the certificate signing request. For example, cert.key.

  3. Select the root CA certificate from your CA bundle and add it to root_ca.crt.

  4. Combine all certificates including the root CA, intermediate CA from the CA bundle, and your server certificate into one file. For example, full_chain_cert.crt.

Configure TLS certificates

  1. For clusters deployed using the Container Cloud release earlier than 2.9.0, download the latest version of the bootstrap script on the management cluster:

    wget https://binary.mirantis.com/releases/get_container_cloud.sh
    chmod 0755 get_container_cloud.sh
    ./get_container_cloud.sh
    
  2. Change the directory to kaas-boostrap.

    If you deleted this directory, restore it using the step 1 of the Collect cluster logs procedure.

  3. Select from the following options:

    • Set a TLS certificate for Keycloak:

      ./container-cloud set certificate \
        --cacert-file <fullRootpathToCACertForKeycloak> \
        --cert-file <fullPathToCertForKeycloak> \
        --key-file <pathToPrivateKeyForKeycloak> \
        --for keycloak  --hostname  <applicationHostName> \
        --kubeconfig <mgmtClusterKubeconfig>
      
    • Set a TLS certificate for the Container Cloud web UI:

      ./container-cloud set certificate \
        --cert-file <fullPathToCertForUI> \
        --key-file <pathToPrivateKeyForUI> \
        --for ui \
        --hostname  <applicationHostName> \
        --kubeconfig <mgmtClusterKubeconfig>
      
    • Since Container Cloud 2.20.0, set a TLS certificate for MKE:

      ./container-cloud set certificate \
        --cacert-file <fullRootpathToCACertForMKE> \
        --cert-file <fullPathToCertForMKE> \
        --key-file <pathToPrivateKeyForMKE> \
        --for mke  --hostname  <applicationHostName> \
        --kubeconfig <mgmtClusterKubeconfig>
        --cluster-name <targetClusterName>
        --cluster-namespace <targetClusterNamespace>
      
    • Since Container Cloud 2.20.0, set a TLS certificate for mcc-cache:

      ./container-cloud set certificate \
        --cacert-file <fullRootpathToCACertForCache> \
        --cert-file <fullPathToCertForCache> \
        --key-file <pathToPrivateKeyForCache> \
        --for cache  --hostname  <applicationHostName> \
        --kubeconfig <mgmtClusterKubeconfig>
        --cluster-name <targetClusterName>
        --cluster-namespace <targetClusterProjectName>
      

      Caution

      • All managed clusters in the region must be updated to the latest available Cluster release.

      • The organization administrator must ensure that the mcc-cache host name is resolvable for all managed clusters in the region.

    In the commands above, replace the parameters enclosed in angle brackets with the corresponding values of your cluster.

    Flag

    Description

    --cacert-file

    Must contain only one PEM-encoded root CA certificate in the certificate chain of trust.

    --cert-file

    Must contain all certificates in the server certificate chain of trust including the PEM-encoded server certificate.

    --key-file

    Private key used to generate the provided certificate.

    --for keycloak/ui/cache/mke

    Configures a certificate for Keycloak, the Container Cloud web UI, mcc-cache on management or regional clusters, or MKE on managed clusters.

    --hostname

    DNS server host name.

    --kubeconfig

    Management cluster kubeconfig that is by default located in the kaas-bootstrap directory.

    --cluster-name

    Target cluster name.

    --cluster-namespace

    Target cluster project name in Container Cloud.

    Example command:

    ./container-cloud set certificate \
      --cacert-file root_ca.crt \
      --cert-file full_chain_cert.crt \
      --key-file cert.key \
      --for keycloak \
      --hostname container-cloud-auth.example.com \
      --kubeconfig kubeconfig
    

The self-signed certificates generated and managed by the Container Cloud provider are stored in *-tls-certs secrets in the kaas and stacklight namespaces.

Renew expired TLS certificates

Container Cloud provides automatic renewal of certificates for internal Container Cloud services and for MKE on managed clusters deployed by Container Cloud. Custom certificates require manual renewal.

If you have permissions to view the default project in the Container Cloud web UI, you may see the Certificate Is Expiring Soon warning for custom certificates. The warning appears on top of the Container Cloud web UI. It displays the certificate with the least number of days before expiration. Click See Details and get more information about other expiring certificates. You can also find the details about the expiring certificates in the Status column’s Certificate Issues tooltip on the Clusters page.

The Certificate Issues status may include the following messages:

  • Some certificates require manual renewal

    A custom certificate is expiring in less than seven days. Renew the certificate manually using the same container-cloud binary as for the certificate configuration. For details, see Configure TLS certificates.

  • Some certificates were not renewed automatically

    An automatic certificate renewal issue. Unexpected error, contact Mirantis support.