Using virtual private endpoints (VPEs)

Create and manage Key Protect resources on IBM Cloud's virtual private endpoints (VPEs) by targeting a private service endpoint.

As of 11 January 2024, it is possible to access VPEs using the Key Protect control plane UI, allowing users to create and manage keys for instances using a private endpoint (for example, in a Satellite location). Similarly, keys created using the CLI or the SDK or related method can now be seen and updated using the UI.

To get started, enable virtual routing and forwarding (VRF) and service endpoints for your infrastructure account. After you enable VRF for your account, you can connect to Key Protect by using a private IP that is accessible only through the IBM Cloud private network. To learn more about private connections on IBM Cloud, see Service endpoints for private connections.

Before you begin

Before you target a VPE for Key Protect:

Ensure that your IBM Cloud infrastructure account is enabled for virtual routing and forwarding (VRF).

When you enable VRF, a separate routing table is created for your account, and connections to and from your account's resources are routed separately on the IBM Cloud network. To learn more about VRF technology, see Virtual routing and forwarding on IBM Cloud.

Enabling VRF permanently alters networking for your account. Be sure that you understand the impact to your account and resources. After you enable VRF, it cannot be disabled.
Ensure that your IBM Cloud infrastructure account is enabled for VPEs.

After you enable VRF and VPE for your account, all existing and future Key Protect resources and instances become available from both the public endpoints and VPEs.

VPE settings, specifically the Internet Protocol (IP) address, may need to be manually updated during Disaster recovery and business continuity actions.

Step 1. Configure the IBM Cloud VPE on your virtual server

Prepare your VSI or test machine by configuring your routing table for the IBM Cloud VPE.

To route traffic to the IBM Cloud VPE, run the following command on your VSI:
```
route add -net 166.9.0.0/16 gw <gateway> dev <gateway_interface>
```
Replace <gateway> (for example, 10.x.x.x) and <gateway_interface> (for example, eth10) with the appropriate values.
Optional: Verify that the route was added successfully by displaying your new routing table.
```
route -n
```

Step 2. Target the Key Protect VPE

After you configure your VSI to accept IBM Cloud traffic over a VPE, you can target the VPE for Key Protect by using the Key Protect API or Key Protect CLI plug-in.

In a terminal window, log in to IBM Cloud.
```
ibmcloud login
```
If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time passcode.

Optional: Ensure that your account is enabled for VRF and service endpoints.

ibmcloud account show

The following CLI output shows the account details of a VRF and service endpoint-enabled account.

Retrieving account John Doe's Account of john.doe@email.com...
OK

Account ID:                   d154dfbd0bc2edefthyufffc9b5ca318
Currently Targeted Account:   true
Linked Softlayer Account:     1008967
VRF Enabled:                  true
Service Endpoint Enabled:     true

See Enabling VRF and service endpoints to learn how to set up your account for connecting to a VPE.

Set an environment variable to target a Key Protect VPE.
```
export KP_PRIVATE_ADDR=https://private.<region>.kms.cloud.ibm.com
```
Replace <region> with the region abbreviation that represents the geographic area where your Key Protect instance resides. For the complete list of endpoints, see Regions and endpoints.

Step 3. Create a Key Protect resource on the VPE

Test your VPE connection by using the Key Protect CLI plug-in.

Create a root key by targeting the VPE.
```
ibmcloud kp key create <key_name> -i <instance_ID>
```
Replace <key_name> with a human-readable alias for easy identification of your key. Replace <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect instance.
Optional: Verify that the key was created successfully by listing the keys that are available in your Key Protect instance.
```
ibmcloud kp keys -i <instance_ID>
```
Replace <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect instance.

Next steps

You're now set to interact with Key Protect through a VPE.

To find out more about managing keys with Key Protect, check out the Key Protect CLI reference doc.