Configuring Enterprise PKS Clusters with Private Docker Registry CA Certificates (Beta)

Page last updated:

Warning: VMware Enterprise PKS v1.6 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how to configure VMware Enterprise PKS Kubernetes clusters with private Docker registry SSL Certificate Authority (CA) certificates.

Overview

Docker allows you to store Docker images in private registries and secures the registries with SSL CA certificates. You can enable your Enterprise PKS Kubernetes clusters to authenticate into your private Docker registries by configuring your clusters with SSL CA certificates.

You can configure both new and existing Enterprise PKS clusters to have Docker registry CA certificates.

Note: Only Linux clusters can be configured to have Docker registry CA certificates.

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 Enterprise PKS 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 Enterprise PKS if you want to apply a single Harbor Registry certificate to all of your Enterprise PKS clusters.

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

Prerequisites

Before configuring Enterprise PKS 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 PKS 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 PKS API endpoints.

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

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

    Where:

    • PKS-API is the FQDN of your PKS API endpoint. For example, api.pks.example.com.
    • USER-ID is your Enterprise PKS user ID.
    • PASSWORD is your Enterprise PKS password.
    • YOUR-ACCESS-TOKEN is the name of your access token environment variable.

    For example:

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

    Note: If your operator has configured Enterprise PKS 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 PKS CLI. For information about configuring SAML, see Connecting Enterprise PKS 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 PKS 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://PKS-API:9021/v1/clusters \
      -H 'Accept: application/json' \
      -H "Authorization: Bearer $YOUR-ACCESS-TOKEN" \
      -H 'Content-Type: application/json' \
      -H 'Host: PKS-API:9021' \
      -d '{
      "name": "CLUSTER-NAME",
      "plan_name": "PLAN-NAME",
      "parameters": {
        "kubernetes_master_host": "KUBERNETES-MASTER-HOST",
        "custom_ca_certs": [
          {
            "domain_name": "DOMAIN-NAME",
            "ca_cert": "CA-CERTFICATE"
          }
        ]
      }
    }'
    

    Where:

    • PKS-API is the FQDN of your PKS API endpoint. For example, api.pks.example.com.
    • YOUR-ACCESS-TOKEN is the name of your access token environment variable.
    • CLUSTER-NAME is the name of your cluster.
    • PLAN-NAME is the name of your plan.
    • KUBERNETES-MASTER-HOST is your Kubernetes master 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 PKS 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 PKS 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://PKS-API:9021/v1/clusters/CLUSTER-NAME \
      -H 'Accept: application/json' \
      -H "Authorization: Bearer $YOUR-ACCESS-TOKEN" \
      -H 'Content-Type: application/json' \
      -H 'Host: PKS-API:9021' \
      -d '{
            "custom_ca_certs": [
              {
                "domain_name": "DOMAIN-NAME",
                "ca_cert": "CA-CERTFICATE"
              }
            ]
          }'
    

    Where:

    • PKS-API is the FQDN of your PKS API endpoint. For example, api.pks.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 PKS 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.

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.

Prepare a Certificate String for Command Line Use

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

Note: The PKS API does not validate certificate strings for correctness. Ensure your certificate string is free of newline characters before using the certificate string in a PKS 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.


Please send any feedback you have to pks-feedback@pivotal.io.