This topic describes how to configure VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) Kubernetes clusters with private registry SSL Certificate Authority (CA) certificates.

Warning: Configuring TKGI clusters with private Docker registry CA certificates is currently in beta and is intended for evaluation and test purposes only. Do not use this feature in a TKGI production environment.



Overview

You can store images in a private Docker registry and secure the registry with SSL CA certificates:

  • You can enable your TKGI Kubernetes clusters to authenticate into a private Docker registry by configuring your clusters with SSL CA certificates.

  • You can configure both new and existing TKGI clusters to have Docker registry CA certificates.

Note: Only Linux clusters can be configured to have Docker registry CA certificates. Configuring containerd container runtime Linux clusters requires TKGI v1.14.1.

To create a new cluster configured with Docker registry SSL CA certificates, complete the following procedures:

  1. Set up Your API Access Token
  2. Create a Cluster with SSL CA Certificates

To update an existing cluster with Docker registry SSL CA certificates, complete the following procedures:

  1. Set up Your API Access Token
  2. Update a Cluster with SSL CA Certificates

Note: The procedures documented in this topic configure an individual TKGI Kubernetes cluster with a Docker Registry SSL CA certificate. See Import the CA Certificate Used to Sign the Harbor Certificate and Key to BOSH in Integrating VMware Harbor Registry with Tanzu Kubernetes Grid Integrated Edition if you want to apply a single Harbor Registry certificate to all of your TKGI clusters.



Prerequisites

Before configuring TKGI Kubernetes clusters to have Docker registry CA certificates, you must have the following:

  • A private Docker registry configured to use SSL CA certificates. For more information about securing a private Docker registry, see Use self-signed certificates in the Docker Registry manual.

Warning: The FQDN for the private Docker registry cannot contain a hyphen, dash, or semi-colon. If such a character is included in the registry name the TKGI API will reject it as not a valid character.



Set up Your API Access Token

The curl commands in this topic use an access token environment variable to authenticate to the TKGI API endpoints.

  1. To export your access token into an environment variable, run the following command:

    tkgi login -a TKGI-API -u USER-ID -p 'PASSWORD' -k; \
export YOUR-ACCESS-TOKEN=$(bosh int ~/.pks/creds.yml --path /access_token)

    Where:

    • TKGI-API is the FQDN of your TKGI API endpoint. For example, api.tkgi.example.com.
    • USER-ID is your Tanzu Kubernetes Grid Integrated Edition user ID.
    • PASSWORD is your Tanzu Kubernetes Grid Integrated Edition password.
    • YOUR-ACCESS-TOKEN is the name of your access token environment variable.

    For example:

    $ tkgi login -a tkgi.my.lab -u alana -p 'psswrdabc123...!' -k; \
export access_token=$(bosh int ~/.pks/creds.yml --path /access_token)

    Note: If your operator has configured Tanzu Kubernetes Grid Integrated Edition to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in TKGI CLI. For information about configuring SAML, see Connecting Tanzu Kubernetes Grid Integrated Edition to a SAML Identity Provider



Create a Cluster with SSL CA Certificates

You can create a new cluster configured with one or more SSL CA certificates by using the TKGI API create-cluster endpoint.

  1. To create a cluster configured with one or more SSL CA certificates, run the following command:

    curl -X POST \
  https://TKGI-API:9021/v1/clusters \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $YOUR-ACCESS-TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Host: TKGI-API:9021' \
  -d '{
  "name": "CLUSTER-NAME",
  "plan_name": "PLAN-NAME",
  "parameters": {
    "kubernetes_master_host": "KUBERNETES-CONTROLPLANE-HOST",
    "custom_ca_certs": [
      {
        "domain_name": "DOMAIN-NAME",
        "ca_cert": "CA-CERTFICATE"
      }
    ]
  }
}'

    Where:

    • TKGI-API is the FQDN of your TKGI API endpoint. For example, api.tkgi.example.com.
    • YOUR-ACCESS-TOKEN is the name of your access token environment variable.
    • CLUSTER-NAME is the name of your cluster.

      Note: Use only lowercase characters when naming your cluster if you manage your clusters with Tanzu Mission Control (TMC). Clusters with names that include an uppercase character cannot be attached to TMC.

    • PLAN-NAME is the name of your plan.
    • KUBERNETES-CONTROLPLANE-HOST is your Kubernetes control plane host.
    • DOMAIN-NAME is a Docker Registry URL. You cannot remove an existing Docker Registry URL from a cluster. If you specify a URL that is already registered with your cluster, the cluster’s existing CA certificate for that URL is overwritten.
    • CA-CERTFICATE is the CA certificate that corresponds to DOMAIN-NAME.
      For more information about using a CA certificate in a TKGI API command, see Prepare a Certificate String for Command Line Use, below.

      You can configure your cluster with additional certificates by including the certificates in the custom_ca_certs array as additional domain_name, ca_cert pairs.

      Note: You can include wildcard characters in your domain_name URLs. For example, *.docker.com.



Update a Cluster with SSL CA Certificates

You can update an existing cluster with one or more SSL CA certificates by using the TKGI API update-cluster endpoint.

  1. To configure an existing cluster with one or more SSL CA certificates, run the following command:

    curl -X PATCH \
  https://TKGI-API:9021/v1/clusters/CLUSTER-NAME \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $YOUR-ACCESS-TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Host: TKGI-API:9021' \
  -d '{
        "custom_ca_certs": [
          {
            "domain_name": "DOMAIN-NAME",
            "ca_cert": "CA-CERTFICATE"
          }
        ]
      }'

    Where:

    • TKGI-API is the FQDN of your TKGI API endpoint. For example, api.tkgi.example.com.
    • YOUR-ACCESS-TOKEN is the name of your access token environment variable.
    • CLUSTER-NAME is the name of your cluster.
    • DOMAIN-NAME is a Docker Registry URL. You cannot remove an existing Docker Registry URL from a cluster. If you specify a URL that is already registered with your cluster, the cluster’s existing CA certificate for that URL is overwritten.
    • CA-CERTFICATE is the CA certificate that corresponds to DOMAIN-NAME. For more information about using a CA certificate in a TKGI API command, see Prepare a Certificate String for Command Line Use, below.

      You can configure your cluster with additional certificates by including the certificates in the custom_ca_certs array as additional domain_name, ca_cert pairs.

      Note: You can include wildcard characters in your domain_name URLs. For example, *.docker.com.



Prepare a Certificate String for Command Line Use

When you provide a certificate string on a command line or TKGI API command, as in the TKGI API commands above, your certificate string must be provided without newline wrapping.

For information on certificate string formatting, see SSL CA Certificate Formats below.

Note: The TKGI API does not validate certificate strings for correctness. Ensure your certificate string is free of newline characters before using the certificate string in a TKGI API command.

To prepare your certificate string for command line use:

  1. To remove newline wrapping from a certificate string, run the following command:

    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}'  CA-PEM

    Where CA-PEM is the filename of your PEM-formatted CA certificate file.

    This command returns your certificate string without newline wrapping.


SSL CA Certificate Formats

SSL CA certificates are unique CA-issued ASCII text strings.

The CAs issue most certificates as a PEM formatted ASCII text files. PEM certificate files typically have the extensions .pem, .crt, .cer, or .key.

PEM files start with the string -----BEGIN CERTIFICATE-----, terminate with -----END CERTIFICATE-----, and are Base64-encoded. Certificate strings are long and are frequently stored within a certificate file with newline wrapping every 64 characters.

check-circle-line exclamation-circle-line close-line
Scroll to top icon