generate-nsx-pi-cert.html.md.erb

---
title: Generating and Registering the NSX Manager Superuser Principal Identity Certificate and Key
owner: PKS
---

<strong><%= modified_date %></strong>

This topic describes how to generate and register the NSX Manager superuser principal identity certificate and key in preparation for installing Pivotal Container Service (PKS) on vSphere with NSX-T.

##<a id='prerequisites'></a>Prerequisites

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

<ul>
  <li>
    <a href="./nsxt-deploy.html">Deploying NSX-T for PKS</a>
  </li>
  <li>
    <a href="./nsxt-prepare-mgmt-plane.html">Creating the PKS Management Plane</a>
  </li>
  <li>
    <a href="./nsxt-prepare-compute-plane.html">Creating the PKS Compute Plane</a>
  </li>
  <li>
    <a href="./vsphere-nsxt-om-deploy.html">Deploying Ops Manager with NSX-T for PKS</a>
  </li>
  <li>
    <a href="./generate-nsx-ca-cert.html">Generating and Registering the NSX Manager Certificate for PKS</a>
  </li>
  <li>
    <a href="./vsphere-nsxt-om-config.html">Configuring BOSH Director with NSX-T for PKS</a>
  </li>
</ul>

##<a id='certificates-nsx-pid-about'></a> About the NSX Manager Superuser Principal Identity

The PKS API uses the NSX Manager superuser to communicate with NSX-T to create, delete, and modify networking resources for Kubernetes cluster nodes.

When you configure PKS with NSX-T as the container networking interface, for security purposes you must provide the principal identity certificate and private key for the NSX Manager superuser in the **Networking** pane of the PKS tile.

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

  <img src="images/nsxt/nsx-pi-cert.png" alt="NSX Manager Principal Identity Certificate and Key" width="375">

For more information, see the [Networking](installing-nsx-t.html#networking) section of _Installing PKS on vSphere with NSX-T_.

##<a id='certificates-nsx-pid-options'></a> Options for Generating the Certificate and Key

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

- [Option A](#certificate-super-user-ui): Use the automatic **Generate RSA Certificate** option in the PKS tile.
- [Option B](#certificate-super-user-script): Run a script on a Linux host with OpenSSL installed that generates the 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.

###<a id='certificate-super-user-ui'></a> Option A: Generate and Register the Certificate and Key Using the PKS Tile

####<a id='generate-pi-cert-ui'></a> Step 1: Generate the Certificate and Key

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

1. Navigate to the **Networking** pane in the PKS tile. For more information, see [Networking](installing-nsx-t.html#networking) in _Installing PKS on vSphere with NSX-T Integration_.
1. Click **Generate RSA Certificate** and provide a wildcard domain. For example, `*.nsx.pks.vmware.local`.

####<a id='copy-pi-cert'></a> 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:
<p class="note"><strong>Note</strong>: 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.</p>

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.
1. 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.
1. Save both files.

####<a id='variables'></a> 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:

```
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)
```

####<a id='register-pi-certificate'></a> Step 4: Register the Certificate

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

    <pre class="terminal">
    cert_request=$(cat <span><<</span>END
      {
        "display_name": "$PI_NAME",
        "pem_encoded": "$(awk '{printf "%s\\n", $0}' $NSX_SUPERUSER_CERT_FILE)"
      }
    END
    )
    </pre>

    <pre class="terminal">
    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"
    </pre>

1. Verify that the response includes the `CERTIFICATE_ID` value. You use this value in the following step.

####<a id='register-pi'></a> 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"
    ```

1. Register the principal identity with NSX Manager by running the following commands:
    <pre class="terminal">
    pi_request=$(cat <span><<</span>END
      {
        "display_name": "$PI_NAME",
        "name": "$PI_NAME",
        "permission_group": "superusers",
        "certificate_id": "$CERTIFICATE_ID",
        "node_id": "$NODE_ID"
      }
    END
    )
    </pre>

    <pre class="terminal">
    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"
    </pre>

####<a id='verify-pi-certificate'></a> Step 6: Verify the Certificate and Key

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

<pre class="terminal">
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>

###<a id='certificate-super-user-script'></a> 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.
<p class="note"><strong>Note</strong>: 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.</p>

####<a id='script-generate'></a> 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 PKS environment. For example, you can use the PKS client VM.
1. To create an empty file for the first script, run `nano create_certificate.sh`.
1. Copy the following script contents into `create_certificate.sh`, updating the values for the first two lines to match your environment:
  - `NSX_MANAGER_IP`: IP address of the NSX Manager host.
  - `NSX_MANAGER_USERNAME`: Username for NSX Manager.

    <pre class="terminal">
    <span>#</span>!/bin/bash
    <span>#</span>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 \
        <span><</span>(printf '[client_server_ssl]\nextendedKeyUsage = clientAuth\n')
      ) \
      -sha256 \
      -days 730

    cert_request=$(cat <span><<</span>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"
    </pre>

1. Save the script and run `bash create_certificate.sh`.
1. When prompted, enter the `NSX_MANAGER_PASSWORD` for the NSX user you specified in the script.
1. Complete the following steps to verify the results of the script:
  - 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 is uploaded to the NSX Manager and the `CERTIFICATE_ID` value is returned to the console. You need this ID for the second script.

#### <a id='script-register'></a> 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 Manager. This script requires the `CERTIFICATE_ID` returned from the `create_certificate.sh` script.

<p class="note"><strong>Note</strong>: Perform these steps on the same Linux VM where you ran the <code>create_certificate.sh</code> script.</p>

1. To create an empty file for the second script, run `nano create_pi.sh`.
1. Copy the following script contents into `create_pi.sh`, updating the values for the first three lines to match your environment:
  - `NSX_MANAGER_IP`: IP address of the NSX Manager host.
  - `NSX_MANAGER_USERNAME`: Username for NSX Manager.
  - `CERTIFICATE_ID`: Response from the `create_certificate.sh` script.

    <pre class="terminal">
    <span>#</span>!/bin/bash
    <span>#</span>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 <span><<</span>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>

1. Save the script and run `bash create_pi.sh`.
1. When prompted, enter the `NSX_MANAGER_PASSWORD` for the NSX user you specified in the script.
1. When you configure 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 PKS tile. For more information, see the [Networking](installing-nsx-t.html#networking) section of _Installing PKS on vSphere with NSX-T_.

##<a id='next'></a> Next Step

After you complete this procedure, follow the instructions in <a href="./nsxt-create-objects.html">Creating NSX-T Objects for PKS</a>.