Skip to main content

Certificate Management

Palette installs Kubernetes through the tool, kubeadm. As a result, all deployed clusters include auto-generated Public Key Infrastructure (PKI) certificates created by kubeadm. We recommend you review the PKI certificates and requirement Kubernetes documentation to learn more about the auto-generated certificates and to better understand their purpose.

This reference page focuses on how to renew the PKI certificates through Palette. You have two options for how you can renew the cluster PKI certificates:


  • Automatic Certificate Renewal

  • Manual Certificate Renewal

info

Certificates created by kubeadm expire after 365 days. The Root Certificate Authority (CA) is valid for 3652 days or 10 years.

You can learn more about each option in the following sections.

Automatic Certificate Renewal​

When you upgrade the control plane on a cluster, the PKI certificates are automatically updated. Upgrading a cluster's Kubernetes version, whether a minor patch or a major release, results in renewed PKI certificates. This is the method that requires the least user actions when it comes to renewing PKI certificates. We recommend regularly updating your clusters to stay current with security fixes and best practices. By keeping your host cluster updated, you prevent the scenario of PKI certificates from reaching their one-year expiration date.


info

You can upgrade the Kubernetes version of a cluster by updating the Kubernetes layer of the cluster profile and applying the cluster profile update to the cluster. For guidelines on updating pack versions, review Update the Pack Version.

Manual Certificate Renewal​

You can renew the cluster PKI certificates on-demand using the Palette API or the Palette User Interface (UI). When you manually trigger a certificate renewal action, it results in cluster nodes becoming repaved. Palette will scale up the cluster control plane nodes count and deploy new nodes with new PKI certificates auto-generated by kubeadm. Once the new control plane nodes are active and available, Palette will remove the previous control plane nodes. The worker nodes renew once the control plane nodes are updated and available.


warning

A manual renewal of cluster PKI certificates results in all cluster nodes becoming repaved.

Review the following sections to learn more about manually renewing the cluster PKI certificates. Choose your preferred update method, using the Palette UI or the API.


Use the following steps to update the cluster PKI certificates through the Palette UI.

UI​

Prerequisites​

  • A deployed host cluster.

  • Access to the host cluster.

Renew Cluster Certificate​

  1. Log in to Palette.

  2. Navigate to the left Main Menu and select Clusters.

  3. Select the host cluster to renew its PKI certificates.

  4. From the cluster details page, click on View K8s Certificates.


A view of the Palette UI with an arrow pointing to the View K8s Certificates button.

  1. Next, select Renew All to start the renewal process.

A view of the cluster certificates displaying the expiration date

The renewal process may take several minutes, depending on the number of cluster nodes.

Validate​

Using the following steps, you can validate that the cluster's PKI certificates were renewed.


  1. Log in to Palette.

  2. Navigate to the left Main Menu and select Clusters.

  3. Select the host cluster with the renewed PKI certificates.

  4. From the cluster details page, click on View K8s Certificates.

  5. Review the expiration date for each component. Each component's expiration date will have a status of 365d with a date that is one year away.

API​

Use the following steps to update the cluster PKI certificates through the Palette API.

Prerequisites​

  • A Palette API key. You can learn how to create a Palette API key by reviewing the API Key documentation.

  • A deployed host cluster.

  • Access to the host cluster.

Renew Cluster Certificate​

  1. Set your Palette API key as an environment variable. Add your actual API key in place of REPLACE_ME.

export API_KEY=REPLACE_ME
  1. Set the project ID as an environment variable. Add your project ID in place of REPLACE_ME. You can find the project ID on the Palette landing page. The project ID is displayed in the top right corner of the page.

export PROJECT_ID=REPLACE_ME
  1. Set the cluster ID as an environment variable. Add your cluster's ID in place of REPLACE_ME. You can get the cluster ID from the cluster detail's page URL. The value after clusters/ is the cluster ID.

export CLUSTER_ID=REPLACE_ME
  1. Use the Palette API endpoint https://api.spectrocloud.com/v1/spectroclusters/{uid}/k8certificates/renew to renew a cluster's PKI certificates. The endpoint accepts the HTTP method PATCH, and the only required parameter is the cluster ID.

curl --request PATCH \
  --url  'https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_ID/k8certificates/renew' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "ApiKey: $API_KEY" \
  --header "ProjectUid: $PROJECT_ID"
  1. No output is returned and an HTTP status 204 is expected.

The renewal process may take several minutes, depending on the number of cluster nodes.

Validate​

Using the following steps, you can validate that the cluster's PKI certificates were renewed.


  1. Set your Palette API key as an environment variable. Add your actual API key in place of REPLACE_ME.

export API_KEY=REPLACE_ME
  1. Set the project ID as an environment variable. Add your project ID in place of REPLACE_ME.

export PROJECT_ID=REPLACE_ME
  1. Set the cluster ID as an environment variable. Add your cluster's ID in place of REPLACE_ME.

export CLUSTER_ID=REPLACE_ME
  1. Retrieve the cluster's certificate information from Palette by using the https://api.spectrocloud.com/v1/spectroclusters/{uid}/k8certificates endpoint.

curl \
 --url  'https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_ID/k8certificates' \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "ApiKey: $API_KEY" \
 --header "ProjectUid: $PROJECT_ID"
  1. Validate the output and confirm the expiration date is one year away.

{
  "machineCertificates": [
    {
      "certificateAuthorities": [
        {
          "certificates": [
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "front-proxy-client"
            }
          ],
          "expiry": "2033-05-23T16:45:22.209Z",
          "name": "front-proxy-ca"
        },
        {
          "certificates": [
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-apiserver"
            },
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-apiserver-kubelet-client"
            }
          ],
          "expiry": "2033-05-23T16:45:22.209Z",
          "name": "ca"
        },
        {
          "certificates": [
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-apiserver-etcd-client"
            },
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-etcd-healthcheck-client"
            },
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-etcd-peer"
            },
            {
              "expiry": "2024-05-23T16:51:05.000Z",
              "name": "kube-etcd-server"
            }
          ],
          "expiry": "2033-05-23T16:45:22.209Z",
          "name": "etcd-ca"
        }
      ],
      "name": "ip-10-0-1-120.ec2.internal"
    }
  ]
}

Advanced - Only Renew Control Plane Nodes​

You can configure Palette to only renew the PKI certificates for the control plane nodes. You can achieve this by using the annotation spectrocloud.com/cert-renew-controlplane-only and setting the value to true. To enable this behavior, you must use kubectl and apply the update to a Custom Resource Definition (CRD) created by Palette during the cluster deployment process.

Use the following steps to configure Palette only to renew the certificates for control plane nodes.

Prerequisites​

  • Kubectl is installed in your system.

  • A host cluster deployed.

  • Access to the host cluster's kubeconfig file. Refer to the Access Cluster with CLI guide to learn how to use your cluster's kubeconfig file.

Configure Cluster​

  1. Set your cluster name as an environment variable. Add your cluster's name in place of REPLACE_ME.

export CLUSTER_NAME=REPLACE_ME
  1. Use the following command to retrieve the namespace of the CRD Palette created in your cluster.

namespace=$(kubectl get spc --all-namespaces --output jsonpath='{range .items[?(@.metadata.name=="'"$CLUSTER_NAME"'")]}{.metadata.namespace}{"\n"}{end}')
  1. Use kubectl to update the CRD to include the spectrocloud.com/cert-renew-controlplane-only annotation.

kubectl annotate spc/certificate-renew --namespace $namespace spectrocloud.com/cert-renew-controlplane-only="true"
  1. Verify the annotation was set correctly with the command below. The expected output is true.

kubectl get spc/$CLUSTER_NAME --namespace $(kubectl get spc --all-namespaces --output jsonpath='{range .items[?(@.metadata.name=="'"$CLUSTER_NAME"'")]}{.metadata.namespace}{"\n"}{end}') --output jsonpath='{.metadata.annotations.spectrocloud\.com/cert-renew-controlplane-only}'

Output

true
  1. Next, trigger a certificate renewal using either Automatic Certificate Renewal or Manual Certificate Renewal.

The renewal process may take several minutes, depending on the number of cluster nodes.

Validate​

Using the following steps, you can validate that the cluster's PKI certificates are renewed only for the control plane nodes.


  1. Log in to Palette.

  2. Navigate to the left Main Menu and select Clusters.

  3. Select the host cluster to renew its PKI certificates.

  4. From the cluster details page, click on View K8s Certificates.

  5. Review the expiration date for each component. Each component's expiration date will have a status of 365d with a date that is one year away.

  6. Navigate to the Nodes tab and verify the Worker Pool nodes' Age is not updated recently.


View of the cluster nodes where only the control plane nodes are modified