This topic describes how to configure VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) Kubernetes clusters to access private Docker or containerd registries that are secured by SSL Certificate Authority (CA) certificates.

Warning: Configuring TKGI clusters to use private registries 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 for TKGI in private registries that are secured with SSL CA certificates.

To enable new and existing TKGI Kubernetes clusters to access the private registries, you configure them with the local registry addresses and the SSL CA certificates needed to authenticate with the registries.

Note: Only Linux clusters can be configured to use private registries.

To create a new cluster configured to use private registries:

  1. Set up Your API Access Token
  2. Create a Cluster with Private Registry Access

To update an existing cluster to use private registries:

  1. Set up Your API Access Token
  2. Update a Cluster with Private Registry Access

Note: The procedures documented in this topic configure an individual TKGI Kubernetes cluster with SSL CA certificates. 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 access private registries, you must have the following:

  • A private registry secured with 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 registry cannot contain a hyphen, dash, or semicolon. 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 my_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 Private Registry Access

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",
    "k8s_customization_parameters": {
      "insecure_registries": ["DOMAIN-NAME"],
      "unset_http_proxy": ["runtime", "kube-apiserver"]
    },
    "custom_ca_certs": [
      {
        "domain_name": "DOMAIN-NAME",
        "ca_cert": "CA-CERTIFICATE"
      }
    ]
  }
}'

    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 the address of the private registry, for example registry.tkgi.local or 10.148.253.20.

      • 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-CERTIFICATE is the CA certificate for the registry at DOMAIN-NAME. For more information about including CA certificates in a TKGI API command, see Prepare a Certificate String for Command Line Use, below.

      To configure your cluster with additional registries, add them to the insecure_registries list and include their 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 Private Registry Access

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 '{
        "k8s_customization_parameters": {
          "insecure_registries": ["DOMAIN-NAME"],
          "unset_http_proxy": ["runtime", "kube-apiserver"]
        },
        "custom_ca_certs": [
          {
            "domain_name": "DOMAIN-NAME",
            "ca_cert": "CA-CERTIFICATE"
          }
        ]
      }'

    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 the address of the private registry, for example registry.tkgi.local or 10.148.253.20.

      • 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-CERTIFICATE is the CA certificate for the registry at DOMAIN-NAME. For more information about including CA certificates in a TKGI API command, see Prepare a Certificate String for Command Line Use, below.

      To configure your cluster with additional registries, add them to the insecure_registries list and include their 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