Generating and Registering the NSX Manager Superuser Principal Identity Certificate and Key

Page last updated:

This topic describes how to generate and register the NSX Manager superuser principal identity certificate and key in preparation for installing VMware Enterprise PKS on vSphere with NSX-T.

The NSX Manager superuser for PKS has the Enterprise Administrator role and permissions. See Role-Based Access Control in the VMware documentation for more information.

Prerequisites

Before you begin this procedure, ensure that you have successfully completed all preceding steps for installing Enterprise PKS on vSphere with NSX-T, including the following:

How Pivotal Platform Accesses NSX Manager

To create, delete, and modify NSX-T networking resources, Pivotal Platform tiles and APIs use a VMware NSX Manager account with the Enterprise Administrator role and permissions.

Users configure Pivotal Platform to authenticate to NSX Manager for different purposes in different tiles:

  • Enterprise PKS tile
    The Enterprise PKS tile uses NSX Manager to create load balancers, providing a Kubernetes service described in the Create an External Load Balancer section of the Kubernetes documentation.

    To configure the Enterprise PKS tile’s authentication to NSX Manager, see About the NSX Manager Superuser Principal Identity, below.

  • BOSH Director for vSphere tile
    The BOSH Director for vSphere tile uses NSX Manager to configure networking and security for external-facing Pivotal Platform component VMs, such as Pivotal Application Service routers.

    To configure the BOSH Director for vSphere tile’s authentication to NSX Manager, see Configure vCenter for Enterprise PKS in Configuring BOSH Director with NSX-T for Enterprise PKS.

About the NSX Manager Super User Principal Identity

The PKS API accesses the NSX Manager through an Enterprise Administrator account. This superuser account lets PKS use NSX-T to create, delete, and modify networking resources for Kubernetes cluster nodes.

When you configure Enterprise PKS with NSX-T as the container networking interface, you must provide the certificate and private key for the NSX Manager Enterprise Administrator account in the Networking pane of the Enterprise PKS tile.

See the NSX Manager Super User Principal Identity Certificate field in the following screenshot:

NSX Manager Principal Identity Certificate and Key

View a larger version of this image.

For more information, see the Networking section of Installing Enterprise PKS on vSphere with NSX‑T.

Options for Generating the Certificate and Key

There are two options for generating the principal identity certificate and private key:

Once you have generated the principal identity certificate and key, you must register both with the NSX Manager using an HTTPS POST operation on the NSX API. There is no user interface for this operation.

Option A: Generate and Register the Certificate and Key Using Scripts

This option uses Bash shell scripts to generate and register the NSX Manager superuser principal identity certificate and key. When you configure Enterprise PKS for deployment, copy and paste the contents of pks-nsx-t-superuser.crt and pks-nsx-t-superuser.key to the NSX Manager Super User Principal Identity Certificate field in the Networking pane of the Enterprise PKS tile.

Note: The Linux VM must have OpenSSL installed and have network access to the NSX Manager. For example, you can use the PKS client VM where you install the PKS CLI.

Step 1: Generate and Register the Certificate and Key

Provided below is the create_certificate.sh script that generates a certificate and private key, and then uploads the certificate to the NSX Manager. Complete the following steps to run this script:

  1. Log in to a Linux VM in your Enterprise PKS environment.
  2. Create an empty file using vi create_certificate.sh or nano create_certificate.sh.
  3. Modify the file you created to have the following script contents:

    #!/bin/bash
    #create_certificate.sh
    
    NSX_MANAGER="NSX-MANAGER-IP"
    NSX_USER="NSX-MANAGER-USERNAME"
    
    PI_NAME="pks-nsx-t-superuser"
    NSX_SUPERUSER_CERT_FILE="pks-nsx-t-superuser.crt"
    NSX_SUPERUSER_KEY_FILE="pks-nsx-t-superuser.key"
    
    stty -echo
    printf "Password: "
    read NSX_PASSWORD
    stty echo
    
    openssl req \
      -newkey rsa:2048 \
      -x509 \
      -nodes \
      -keyout "$NSX_SUPERUSER_KEY_FILE" \
      -new \
      -out "$NSX_SUPERUSER_CERT_FILE" \
      -subj /CN=pks-nsx-t-superuser \
      -extensions client_server_ssl \
      -config <(
        cat /etc/ssl/openssl.cnf \
        <(printf '[client_server_ssl]\nextendedKeyUsage = clientAuth\n')
      ) \
      -sha256 \
      -days 730
    
    cert_request=$(cat <<END
      {
        "display_name": "$PI_NAME",
        "pem_encoded": "$(awk '{printf "%s\\n", $0}' $NSX_SUPERUSER_CERT_FILE)"
      }
    END
    )
    
    curl -k -X POST \
        "https://${NSX_MANAGER}/api/v1/trust-management/certificates?action=import" \
        -u "$NSX_USER:$NSX_PASSWORD" \
        -H 'content-type: application/json' \
        -d "$cert_request"
    

    Where:

    • NSX-MANAGER-IP is the IP address of the NSX Management Cluster VIP or NSX Management Load Balancer IP.
    • NSX-MANAGER-USERNAME is the Username for NSX Manager.
  4. Save the create_certificate.sh file.

  5. Run the script using bash create_certificate.sh.

  6. When prompted, enter the NSX_MANAGER_PASSWORD for the NSX-T user you specified in the script.

  7. Verify results:

    • The certificate, pks-nsx-t-superuser.crt, and private key, pks-nsx-t-superuser.key, are generated in the directory where you ran the script.
    • The CERTIFICATE-ID value is returned to the console.
    • The certificate is uploaded to the NSX-T Manager node in the System > Certificates screen.
  8. Copy the UUID that is returned or from the NSX-T UI. You need it for the second script.

Step 2: Create and Register the Principal Identity

Provided below is the create_pi.sh script that creates the principal identity and registers it with the NSX-T Manager. This script requires the CERTIFICATE_ID returned from the create_certificate.sh script.

Note: Perform these steps on the same Linux VM where you ran the create_certificate.sh script.

  1. Create an empty file for the script using vi create_pi.sh or nano create_pi.sh.
  2. Copy the script contents into the create_pi.sh file you created.
  3. Modify the file you created to have the following script contents:

    #!/bin/bash
    #create_pi.sh
    
    NSX_MANAGER="NSX-MANAGER-IP"
    NSX_USER="NSX-MANAGER-USERNAME"
    CERTIFICATE_ID='CERTIFICATE-ID'
    
    PI_NAME="pks-nsx-t-superuser"
    NSX_SUPERUSER_CERT_FILE="pks-nsx-t-superuser.crt"
    NSX_SUPERUSER_KEY_FILE="pks-nsx-t-superuser.key"
    NODE_ID=$(cat /proc/sys/kernel/random/uuid)
    
    stty -echo
    printf "Password: "
    read NSX_PASSWORD
    stty echo
    
    pi_request=$(cat <<END
        {
             "display_name": "$PI_NAME",
             "name": "$PI_NAME",
             "permission_group": "superusers",
             "certificate_id": "$CERTIFICATE_ID",
             "node_id": "$NODE_ID"
        }
    END
    )
    
    curl -k -X POST \
        "https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
        -u "$NSX_USER:$NSX_PASSWORD" \
        -H 'content-type: application/json' \
        -d "$pi_request"
    
    curl -k -X GET \
        "https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
        --cert $(pwd)/"$NSX_SUPERUSER_CERT_FILE" \
        --key $(pwd)/"$NSX_SUPERUSER_KEY_FILE"
    </pre>
    

    Where:

    • NSX-MANAGER-IP is the IP address of the NSX Management Cluster VIP or NSX Management Load Balancer IP.
    • NSX-MANAGER-USERNAME is the Username for NSX Manager.
    • CERTIFICATE-ID is the response from the create_certificate.sh script.
  4. Save the changes to the create_pi.sh script.

  5. Run the script using bash create_pi.sh.

  6. When prompted, enter the NSX_MANAGER_PASSWORD for the NSX user you specified in the script.

  7. Verify results: Review the NSX-T Manager System > Users > Role Assignments screen. Confirm the principal identity pks-nsx-t-superuser is registered with the role Enterprise Admin.
    NSX-T Manager System > Users > Role Assignments

    View a larger version of this image.

Option B: Generate and Register the Certificate and Key Using the Enterprise PKS Tile

Step 1: Generate the Certificate and Key

To generate the certificate and key automatically in the Networking pane in the Enterprise PKS tile, follow the steps below:

  1. Navigate to the Networking pane in the Enterprise PKS tile. For more information, see Networking in Installing Enterprise PKS on vSphere with NSX-T Integration.
  2. Click Generate RSA Certificate and provide a wildcard domain. For example, *.nsx.pks.vmware.local.

Step 2: Copy the Certificate and Key to the Linux VM

To copy the certificate and key you generated to a Linux VM, follow the steps below:

Note: The Linux VM must have OpenSSL installed and have network access to the NSX Manager. For example, you can use the PKS client VM where you install the PKS CLI.

  1. On the Linux VM you want to use to register the certificate, create a file named pks-nsx-t-superuser.crt. Copy the generated certificate into the file.
  2. On the Linux VM you want to use to register the key, create a file named pks-nsx-t-superuser.key. Copy the generated private key into the file.
  3. Save both files.

Step 3: Export Environment Variables

On the Linux VM where you created the certificate and key files, export the environment variables below. Change the NSX_MANAGER_IP, NSX_MANAGER_USERNAME, and NSX_MANAGER_PASSWORD values to match your environment. Use the NSX Management Cluster VIP or load balancer for the NSX_MANAGER_IP.

export NSX_MANAGER="NSX_MANAGER_IP"
export NSX_USER="NSX_MANAGER_USERNAME"
export NSX_PASSWORD='NSX_MANAGER_PASSWORD'
export PI_NAME="pks-nsx-t-superuser"
export NSX_SUPERUSER_CERT_FILE="pks-nsx-t-superuser.crt"
export NSX_SUPERUSER_KEY_FILE="pks-nsx-t-superuser.key"
export NODE_ID=$(cat /proc/sys/kernel/random/uuid)

Step 4: Register the Certificate

  1. On the same Linux VM, run the following commands to register the certificate with NSX Manager:

    cert_request=$(cat <<END
      {
        "display_name": "$PI_NAME",
        "pem_encoded": "$(awk '{printf "%s\\n", $0}' $NSX_SUPERUSER_CERT_FILE)"
      }
    END
    )
    
    curl -k -X POST \
    "https://${NSX_MANAGER}/api/v1/trust-management/certificates?action=import" \
    -u "$NSX_USER:$NSX_PASSWORD" \
    -H 'content-type: application/json' \
    -d "$cert_request"
    
  2. Verify that the response includes the CERTIFICATE_ID value. You use this value in the following step.

Step 5: Register the Principal Identity

  1. On the same Linux VM, export the CERTIFICATE_ID environment variable, where the value is the response from the previous step:

    export CERTIFICATE_ID="CERTIFICATE_ID"
    
  2. Register the principal identity with NSX Manager by running the following commands:

    pi_request=$(cat <<END
      {
        "display_name": "$PI_NAME",
        "name": "$PI_NAME",
        "permission_group": "superusers",
        "certificate_id": "$CERTIFICATE_ID",
        "node_id": "$NODE_ID"
      }
    END
    )
    
    curl -k -X POST \
      "https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
      -u "$NSX_USER:$NSX_PASSWORD" \
      -H 'content-type: application/json' \
      -d "$pi_request"
    

Step 6: Verify the Certificate and Key

To verify that the certificate and key can be used with NSX-T, run the following command:

curl -k -X GET \
"https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
--cert $(pwd)/"$NSX_SUPERUSER_CERT_FILE" \
--key $(pwd)/"$NSX_SUPERUSER_KEY_FILE"

Option B: Generate and Register the Certificate and Key Using Scripts

This option uses Bash shell scripts to generate and register the NSX Manager superuser principal identity certificate and key. When you configure Enterprise PKS for deployment, copy and paste the contents of pks-nsx-t-superuser.crt and pks-nsx-t-superuser.key to the NSX Manager Super User Principal Identity Certificate field in the Networking pane of the Enterprise PKS tile.

Note: The Linux VM must have OpenSSL installed and have network access to the NSX Manager. For example, you can use the PKS client VM where you install the PKS CLI.

Step 1: Generate and Register the Certificate and Key

Provided below is the create_certificate.sh script that generates a certificate and private key, and then uploads the certificate to the NSX Manager. Complete the following steps to run this script:

  1. Log in to a Linux VM in your Enterprise PKS environment.
  2. Create an empty file using vi create_certificate.sh or nano create_certificate.sh.
  3. Copy the script contents below into the file you created.
  4. Update the values for the first two lines to match your environment:
    • NSX_MANAGER_IP: IP address of the NSX Management Cluster VIP or NSX Management Load Balancer IP.
    • NSX_MANAGER_USERNAME: Username for NSX Manager.
  5. Save the file create_certificate.sh.
  6. Run the script using bash create_certificate.sh.
  7. When prompted, enter the NSX_MANAGER_PASSWORD for the NSX-T user you specified in the script.
  8. Verify results:
    • The certificate, pks-nsx-t-superuser.crt, and private key, pks-nsx-t-superuser.key, are generated in the directory where you ran the script.
    • The CERTIFICATE_ID value is returned to the console.
    • The certificate is uploaded to the NSX-T Manager node in the System > Certificates screen.
  9. Copy the UUID that is returned or from the NSX-T UI. You need it for the second script.

    #!/bin/bash
    #create_certificate.sh
    
    NSX_MANAGER="NSX_MANAGER_IP"
    NSX_USER="NSX_MANAGER_USERNAME"
    
    PI_NAME="pks-nsx-t-superuser"
    NSX_SUPERUSER_CERT_FILE="pks-nsx-t-superuser.crt"
    NSX_SUPERUSER_KEY_FILE="pks-nsx-t-superuser.key"
    
    stty -echo
    printf "Password: "
    read NSX_PASSWORD
    stty echo
    
    openssl req \
      -newkey rsa:2048 \
      -x509 \
      -nodes \
      -keyout "$NSX_SUPERUSER_KEY_FILE" \
      -new \
      -out "$NSX_SUPERUSER_CERT_FILE" \
      -subj /CN=pks-nsx-t-superuser \
      -extensions client_server_ssl \
      -config <(
        cat /etc/ssl/openssl.cnf \
        <(printf '[client_server_ssl]\nextendedKeyUsage = clientAuth\n')
      ) \
      -sha256 \
      -days 730
    
    cert_request=$(cat <<END
      {
        "display_name": "$PI_NAME",
        "pem_encoded": "$(awk '{printf "%s\\n", $0}' $NSX_SUPERUSER_CERT_FILE)"
      }
    END
    )
    
    curl -k -X POST \
        "https://${NSX_MANAGER}/api/v1/trust-management/certificates?action=import" \
        -u "$NSX_USER:$NSX_PASSWORD" \
        -H 'content-type: application/json' \
        -d "$cert_request"
    

Step 2: Create and Register the Principal Identity

Provided below is the create_pi.sh script that creates the principal identity and registers it with the NSX-T Manager. This script requires the CERTIFICATE_ID returned from the create_certificate.sh script.

Note: Perform these steps on the same Linux VM where you ran the create_certificate.sh script.

  1. Create an empty file for the script using vi create_pi.sh or nano create_pi.sh.
  2. Copy the script contents into the create_pi.sh file you created.
  3. Update the values for the first three lines to match your environment:
    • NSX_MANAGER_IP: IP address of the NSX Management Cluster VIP or NSX Management Load Balancer IP.
    • NSX_MANAGER_USERNAME: Username for NSX Manager.
    • CERTIFICATE_ID: Response from the create_certificate.sh script.
  4. Save the changes to the create_pi.sh script.
  5. Run the script using bash create_pi.sh.
  6. When prompted, enter the NSX_MANAGER_PASSWORD for the NSX user you specified in the script.
  7. Verify results: The principal identity is registered with the NSX-T Manager at the System > Certificate screen.

    #!/bin/bash
    #create_pi.sh
    
    NSX_MANAGER="NSX_MANAGER_IP"
    NSX_USER="NSX_MANAGER_USERNAME"
    CERTIFICATE_ID='CERTIFICATE_ID'
    
    PI_NAME="pks-nsx-t-superuser"
    NSX_SUPERUSER_CERT_FILE="pks-nsx-t-superuser.crt"
    NSX_SUPERUSER_KEY_FILE="pks-nsx-t-superuser.key"
    NODE_ID=$(cat /proc/sys/kernel/random/uuid)
    
    stty -echo
    printf "Password: "
    read NSX_PASSWORD
    stty echo
    
    pi_request=$(cat <<END
        {
             "display_name": "$PI_NAME",
             "name": "$PI_NAME",
             "permission_group": "superusers",
             "certificate_id": "$CERTIFICATE_ID",
             "node_id": "$NODE_ID"
        }
    END
    )
    
    curl -k -X POST \
        "https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
        -u "$NSX_USER:$NSX_PASSWORD" \
        -H 'content-type: application/json' \
        -d "$pi_request"
    
    curl -k -X GET \
        "https://${NSX_MANAGER}/api/v1/trust-management/principal-identities" \
        --cert $(pwd)/"$NSX_SUPERUSER_CERT_FILE" \
        --key $(pwd)/"$NSX_SUPERUSER_KEY_FILE"
    

Next Step

After you complete this procedure, follow the instructions in Installing Enterprise PKS on vSphere with NSX-T.


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