Accessing VPC clusters through the Virtual Private Endpoint gateway

A Virtual Private Endpoint (VPE) gateway is created automatically for each VPC cluster. The cluster master is accessible through this endpoint if authorized users are connected to the same VPC network, such as through a VPC VPN.

For clusters that run version 4.13: If you enabled only the private cloud service endpoint during cluster creation, the VPE of your VPC is used by default to access Red Hat OpenShift components such as the web console or OperatorHub. You must be connected to the private VPC network to access these components.

Before you begin

Install the required CLI tools.
Configure a client-to-site or site-to-site VPN to your VPC and connect.

Accessing a VPC cluster through the VPE gateway

Set the cluster context using the VPE endpoint.

ibmcloud oc cluster config -c CLUSTER_NAME_OR_ID --endpoint vpe

Log in to the cluster using one of the following methods.
- As admin: ibmcloud oc cluster config -c CLUSTER_NAME_OR_ID --admin --endpoint vpe
- With an API key: See Accessing clusters from automation tools.
- With a passcode: oc login -u passcode -p <iam_passcode> --server=https://<VPE_URL>:<port>
Verify access.
```
oc version
```

Creating additional VPE gateways in other VPCs and accounts

In addition to the VPE gateway that is created for a cluster in its VPC, you can create additional VPE gateways for that cluster to allow access over the private network from other VPCs, regions, and accounts.

Additional VPE gateways must be created by using the CLI or API. After creation, they can be managed in the web UI.
For cross-account VPE gateways, you must first create an authorization in the target account. For more information, see Creating service authorization for cross-account VPE in the console.
No transit gateway or special routing is needed. The VPE gateway handles routing to the target cluster.

The following steps show you how to create a cross-account VPE gateway.

Get the necessary information from the target cluster.
1. Set ibmcloud target to the target account, region, and resource group.
2. Get the existing VPE gateway information.
```
ibmcloud is endpoint-gateway iks-TARGET_CLUSTER_ID
```
3. Note the Target CRN (format: crn:v1:bluemix:public:containers-kubernetes:REGION:a/TARGET_ACCOUNT:TARGET_CLUSTER_ID::).
4. Note the Service Endpoints host names.
Create the new VPE gateway in the source account.
1. Set ibmcloud target to the source account, region, and resource group.
2. Verify the VPC exists in this account.
```
ibmcloud is vpcs
```
3. Create the VPE gateway.
```
ibmcloud is endpoint-gateway-create --vpc SOURCE_VPC_NAME --target TARGET_CRN --name new-iks-TARGET_CLUSTER_ID --resource-group-name SOURCE_ACCOUNT_RESOURCE_GROUP
```
  SOURCE_VPC_NAME
  
  The VPC name from the previous step.
  
  TARGET_CRN
  
  The CRN from the target cluster's VPE gateway.
  
  --name
  
  A name for your VPE gateway.
  
  SOURCE_ACCOUNT_RESOURCE_GROUP
  
  The resource group name in the source account.
4. If you get an error Could not find service, verify the Target CRN is correct. If correct, you need to create the authorization in the target account. See Creating service authorization for cross-account VPE in the console.
Add reserved IPs to your VPE gateway.

You must add at least one reserved IP. Reserved IPs come from your source VPC subnets (one per zone maximum) and are added to the source VPC's private DNS entries.
1. Create a reserved IP for each zone.
```
ibmcloud is subnet-reserved-ip-create SOURCE_VPC_SUBNET_NAME --vpc SOURCE_VPC_NAME --name ANY_NAME_YOU_CHOOSE --auto-delete true --target VPE_GATEWAY_NAME
```
2. Optional: Add or modify security groups. By default, only the default security group for the source VPC is attached. For VPE gateways, security groups only protect ingress traffic. Ensure the security groups allow all necessary incoming traffic from clients.
Test the connection.
1. From a VSI in the source VPC, use the same host name as the original VPE gateway. Find this in the Service Endpoints list or the VPE Gateway property from ibmcloud ks cluster get -c CLUSTER_NAME.
2. Verify the connection works.
```
curl -k https://CLUSTERID...:XXXXX/version
```
3. If the connection fails, check the following:
  - Security groups on the VSI and VPE gateway allow the necessary traffic
  - VPC ACL allows the traffic
  - Context Based Restriction (CBR) rules on the target cluster allow private traffic from the source VPC (add the three Cloud Service Endpoint source addresses from your source VPC to the private CBR rule)

Target account example

The following example shows commands run in the target account to gather information about the cluster and its VPE gateway.

Verify you are targeting the correct account.

ibmcloud target

Example output

API endpoint:     https://cloud.ibm.com
Region:           us-east
User:             user2@example.com
Account:          Target Account (9f8e7d6c5b4a321fedcba98765432222) <-> 2222222
Resource group:   default

List your clusters.

ibmcloud ks clusters

Example output

OK
Name                     ID                     State    Created     Workers   Location        Version                  Resource Group Name   Provider
vpe-cross-account-test   c8m5n3p2q4x6z1w7y077   normal   1 day ago   2         Washington DC   4.19.25_1572_openshift   default               vpc-gen2

Get the VPE gateway details. Note the Target CRN and Service Endpoints.

ibmcloud is endpoint-gateway iks-c8m5n3p2q4x6z1w7y077

Example output

Getting endpoint gateway iks-c8m5n3p2q4x6z1w7y077 under account Target Account as user user2@example.com...
                                 
ID                            r014-7a228b24-4bc4-416c-aede-7fda14e88d98   
Name                          iks-c8m5n3p2q4x6z1w7y077
CRN                           crn:v1:bluemix:public:is:us-east:a/9f8e7d6c5b4a321fedcba98765432222::endpoint-gateway:r014-7a228b24-4bc4-416c-aede-7fda14e88d98
Target                        CRN      
                              crn:v1:bluemix:public:containers-kubernetes:us-east:a/9f8e7d6c5b4a321fedcba98765432222:c8m5n3p2q4x6z1w7y077::
                                 
DNS resolution binding mode   primary   
Target Type                   provider_cloud_service   
Target Remote                 ID                        Name   Resource type      
                              No target remote found.      
                                 
VPC                           ID                                          Name      
                              r014-464b4e54-48a8-4f6c-b10a-68edc6fd2be4   new-vpcgen2-default-sec-grp-wdc      
                                 
Private IPs                   ID                                          Name                                   Address       Subnet ID      
                              0757-3bd457cb-af5a-4ab6-b9bb-6e78d3eaf752   iks-useast1-c8m5n3p2q4x6z1w7y077-2e8   172.22.0.11   0757-0c981aa5-cb47-41d9-ab29-edee98b416f8
                                 
Service Endpoints             c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com
Lifecycle State               stable   
Health State                  ok   
Security groups               ID                                          Name      
                              r014-3873358e-3180-482b-927e-abcc300ecbf8   kube-vpegw-c8m5n3p2q4x6z1w7y077
                                 
Created                       2026-04-03T12:14:59-05:00   
Resource Group                default

Optional: Get the cluster details to see the VPE gateway URL.

ibmcloud ks cluster get -c c8m5n3p2q4x6z1w7y077

Example output

Retrieving cluster c8m5n3p2q4x6z1w7y077...
OK
                                
Name:                           vpe-cross-account-test
ID:                             c8m5n3p2q4x6z1w7y077
State:                          normal
Status:                         All Workers Normal
Created:                        2026-04-03 11:56:38 -0500 (1 day ago)
Resource Group ID:              950cec30388441ce809ca0d18b5ca3bc
Resource Group Name:            default
Pod Subnet:                     172.17.0.0/18
Service Subnet:                 172.21.0.0/16
Workers:                        2
Worker Zones:                   us-east-1
Ingress Subdomain:              vpe-cross-account-test-354226545946e7ee0a2c700f061c1661-0000.us-east.containers.appdomain.cloud
Ingress Secret:                 vpe-cross-account-test-354226545946e7ee0a2c700f061c1661-0000
Ingress Status:                 healthy
Ingress Message:                All Ingress components are healthy.
Trusted Profile ID:             -
Public Service Endpoint URL:    https://c111-e.us-east.containers.cloud.ibm.com:31100
Private Service Endpoint URL:   https://c111.private.us-east.containers.cloud.ibm.com:31100
Pull Secrets:                   enabled in the default namespace
VPCs:                           r014-464b4e54-48a8-4f6c-b10a-68edc6fd2be4
VPE Gateway:                    https://c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com:31100
OAuth Server URL:               https://c111-e.us-east.containers.cloud.ibm.com:31264
Konnectivity Server URL:        https://c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com:30996
Secure By Default Networking:   enabled
Outbound Traffic Protection:    enabled

Master      
Status:     Ready (1 day ago)
State:      deployed
Health:     normal
Version:    4.19.25_1572_openshift
Location:   Washington DC
URL:        https://c111-e.us-east.containers.cloud.ibm.com:31100

Source account example

The following example shows commands run in the source account to create a VPE gateway that connects to the cluster in the target account.

Verify you are targeting the correct source account.

ibmcloud target

Example output

API endpoint:     https://cloud.ibm.com
Region:           us-south
User:             user1@example.com
Account:          Source Account (a1b2c3d4e5f6789abcdef01234561111) <-> 1111111
Resource group:   Default

List your VPCs.

ibmcloud is vpcs

Example output

Listing vpcs in resource group Default and region us-south under account Source Account as user user1@example.com...
ID                                          Name                      Status      Classic access   Default network ACL                             Default security group                           Resource group   Health state   DNS Hub   DNS Resolver Type   
r006-6f450c4b-c808-40e7-9de6-c61c262a2ae9   dev-ansiblepr-vpc         available   false            vendor-paradox-ravioli-tank                     harmonica-hypnoses-tranquil-alkalize             Default          ok             false     system   
r006-bd06a98a-1183-42d2-810d-1c564eeb5f39   fvt-vpc-sdnlb-server-40   available   false            sloppy-program-venue-subsiding                  prattle-pension-wilt-recycled                    Default          ok             false     system   
r006-ecf65055-6868-4368-aa7c-48fc5ac29ff8   network-fvt-us-south      available   false            doorknob-baffle-quintet-poem                    spotted-sandpaper-auction-unluckily              Default          ok             false     system   
r006-4ff93772-cee9-4d64-9d87-d8b1b781e201   network-fvt-vpc-gen2      available   false            stegosaur-reach-boxlike-alone-stranger-uncork   earplugs-preface-county-juicy-sensitize-babied   Default          ok             false     system

Create the VPE gateway using the Target CRN from the target account.

ibmcloud is endpoint-gateway-create --vpc network-fvt-us-south --target crn:v1:bluemix:public:containers-kubernetes:us-east:a/9f8e7d6c5b4a321fedcba98765432222:c8m5n3p2q4x6z1w7y077:: --name new-iks-c8m5n3p2q4x6z1w7y077 --resource-group-name Default

Example output

Creating endpoint gateway new-iks-c8m5n3p2q4x6z1w7y077 in resource group Default under account Source Account as user user1@example.com...
                                 
ID                            r006-2009f147-768a-4f6a-b8fa-75f20456cec2   
Name                          new-iks-c8m5n3p2q4x6z1w7y077
CRN                           crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2
Target                        CRN      
                              crn:v1:bluemix:public:containers-kubernetes:us-east:a/9f8e7d6c5b4a321fedcba98765432222:c8m5n3p2q4x6z1w7y077::
                                 
DNS resolution binding mode   primary   
Target Type                   provider_cloud_service   
Target Remote                 ID                        Name   Resource type      
                              No target remote found.      
                                 
VPC                           ID                                          Name      
                              r006-ecf65055-6868-4368-aa7c-48fc5ac29ff8   network-fvt-us-south      
                                 
Private IPs                   -   
Service Endpoints             c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com
Lifecycle State               pending   
Health State                  ok   
Security groups               ID                                          Name      
                              r006-7ae081e2-743d-4046-b755-5ca9997ae077   spotted-sandpaper-auction-unluckily      
                                 
Created                       2026-04-04T18:17:12-05:00   
Resource Group                Default

List the subnets to identify which to use for reserved IPs.

ibmcloud is subnets --vpc network-fvt-us-south

Example output

Listing subnets in resource group Default and region us-south under account Source Account as user user1@example.com...
ID                                          Name                           Status      Subnet CIDR       Addresses   ACL                            Public Gateway                             VPC                    Zone         Resource group   
0717-04288f84-4aef-4938-9fa7-5544a40ba258   network-fvt-us-south-1-priv    available   10.240.0.0/24     251/256     doorknob-baffle-quintet-poem   -                                          network-fvt-us-south   us-south-1   Default   
0717-cdd4b20c-b48f-454b-b092-ad7aa14b39c8   network-fvt-us-south-1-pubgw   available   10.240.1.0/24     246/256     doorknob-baffle-quintet-poem   pgw-33eb53d0-74e4-11ee-a747-33927b3ab784   network-fvt-us-south   us-south-1   Default   
0727-8813de08-fffa-45e3-ae67-2ba70703866e   network-fvt-us-south-2-priv    available   10.240.64.0/24    250/256     doorknob-baffle-quintet-poem   -                                          network-fvt-us-south   us-south-2   Default   
0727-50b14707-c9f6-4f93-9f49-99de13c66161   network-fvt-us-south-2-pubgw   available   10.240.65.0/24    251/256     doorknob-baffle-quintet-poem   pgw-34fe4a70-74e4-11ee-a747-33927b3ab784   network-fvt-us-south   us-south-2   Default   
0737-7a644374-f121-44c1-b216-5fd94c0362b2   network-fvt-us-south-3-priv    available   10.240.128.0/24   251/256     doorknob-baffle-quintet-poem   -                                          network-fvt-us-south   us-south-3   Default   
0737-71a34942-304c-4419-9205-3714a3574962   network-fvt-us-south-3-pubgw   available   10.240.129.0/24   251/256     doorknob-baffle-quintet-poem   pgw-36088e80-74e4-11ee-a747-33927b3ab784   network-fvt-us-south   us-south-3   Default

Create a reserved IP in the first zone and attach it to the VPE gateway.

ibmcloud is subnet-reserved-ip-create network-fvt-us-south-1-pubgw --vpc network-fvt-us-south --name reserved-ip-for-us-south-1 --auto-delete true --target new-iks-c8m5n3p2q4x6z1w7y077

Example output

Creating reserved IP in subnet network-fvt-us-south-1-pubgw under account Source Account as user user1@example.com...
                     
ID                0717-685e1410-2fa1-4e7a-a4e5-27a097ec7a7a   
Name              reserved-ip-for-us-south-1   
Address           0.0.0.0   
Auto delete       true   
Owner             user   
Created           2026-04-04T18:18:51-05:00   
Lifecycle state   pending   
Target            ID                                          Name                           Resource type      CRN      
                  r006-2009f147-768a-4f6a-b8fa-75f20456cec2   new-iks-c8m5n3p2q4x6z1w7y077   endpoint_gateway   crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2

Verify the reserved IP was added.

ibmcloud is eg new-iks-c8m5n3p2q4x6z1w7y077

Example output

Getting endpoint gateway new-iks-c8m5n3p2q4x6z1w7y077 under account Source Account as user user1@example.com...
                                 
ID                            r006-2009f147-768a-4f6a-b8fa-75f20456cec2   
Name                          new-iks-c8m5n3p2q4x6z1w7y077
CRN                           crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2
Target                        CRN      
                              crn:v1:bluemix:public:containers-kubernetes:us-east:a/9f8e7d6c5b4a321fedcba98765432222:c8m5n3p2q4x6z1w7y077::
                                 
DNS resolution binding mode   primary   
Target Type                   provider_cloud_service   
Target Remote                 ID                        Name   Resource type      
                              No target remote found.      
                                 
VPC                           ID                                          Name      
                              r006-ecf65055-6868-4368-aa7c-48fc5ac29ff8   network-fvt-us-south      
                                 
Private IPs                   ID                                          Name                         Address      Subnet ID      
                              0717-685e1410-2fa1-4e7a-a4e5-27a097ec7a7a   reserved-ip-for-us-south-1   10.240.1.5   0717-cdd4b20c-b48f-454b-b092-ad7aa14b39c8      
                                 
Service Endpoints             c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com
Lifecycle State               stable   
Health State                  ok   
Security groups               ID                                          Name      
                              r006-7ae081e2-743d-4046-b755-5ca9997ae077   spotted-sandpaper-auction-unluckily      
                                 
Created                       2026-04-04T18:17:12-05:00   
Resource Group                Default

Create a reserved IP in the second zone and attach it to the VPE gateway.

ibmcloud is subnet-reserved-ip-create network-fvt-us-south-2-pubgw --vpc network-fvt-us-south --name reserved-ip-for-us-south-2 --auto-delete true --target new-iks-c8m5n3p2q4x6z1w7y077

Example output

Creating reserved IP in subnet network-fvt-us-south-2-pubgw under account Source Account as user user1@example.com...
                     
ID                0727-d315d943-c501-4f69-823d-bb82a2b13b29   
Name              reserved-ip-for-us-south-2   
Address           0.0.0.0   
Auto delete       true   
Owner             user   
Created           2026-04-04T18:19:24-05:00   
Lifecycle state   pending   
Target            ID                                          Name                           Resource type      CRN      
                  r006-2009f147-768a-4f6a-b8fa-75f20456cec2   new-iks-c8m5n3p2q4x6z1w7y077   endpoint_gateway   crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2

Create a reserved IP in the third zone and attach it to the VPE gateway.

ibmcloud is subnet-reserved-ip-create network-fvt-us-south-3-pubgw --vpc network-fvt-us-south --name reserved-ip-for-us-south-3 --auto-delete true --target new-iks-c8m5n3p2q4x6z1w7y077

Example output

Creating reserved IP in subnet network-fvt-us-south-3-pubgw under account Source Account as user user1@example.com...
                     
ID                0737-afbebd9f-02bd-4b9a-be90-5bacf9836041   
Name              reserved-ip-for-us-south-3   
Address           0.0.0.0   
Auto delete       true   
Owner             user   
Created           2026-04-04T18:19:32-05:00   
Lifecycle state   pending   
Target            ID                                          Name                           Resource type      CRN      
                  r006-2009f147-768a-4f6a-b8fa-75f20456cec2   new-iks-c8m5n3p2q4x6z1w7y077   endpoint_gateway   crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2

Verify all reserved IPs were added.

ibmcloud is eg new-iks-c8m5n3p2q4x6z1w7y077

Example output

Getting endpoint gateway new-iks-c8m5n3p2q4x6z1w7y077 under account Source Account as user user1@example.com...
                                 
ID                            r006-2009f147-768a-4f6a-b8fa-75f20456cec2   
Name                          new-iks-c8m5n3p2q4x6z1w7y077
CRN                           crn:v1:bluemix:public:is:us-south:a/a1b2c3d4e5f6789abcdef01234561111::endpoint-gateway:r006-2009f147-768a-4f6a-b8fa-75f20456cec2
Target                        CRN      
                              crn:v1:bluemix:public:containers-kubernetes:us-east:a/9f8e7d6c5b4a321fedcba98765432222:c8m5n3p2q4x6z1w7y077::
                                 
DNS resolution binding mode   primary   
Target Type                   provider_cloud_service   
Target Remote                 ID                        Name   Resource type      
                              No target remote found.      
                                 
VPC                           ID                                          Name      
                              r006-ecf65055-6868-4368-aa7c-48fc5ac29ff8   network-fvt-us-south      
                                 
Private IPs                   ID                                          Name                         Address        Subnet ID      
                              0737-afbebd9f-02bd-4b9a-be90-5bacf9836041   reserved-ip-for-us-south-3   10.240.129.5   0737-71a34942-304c-4419-9205-3714a3574962      
                              0717-685e1410-2fa1-4e7a-a4e5-27a097ec7a7a   reserved-ip-for-us-south-1   10.240.1.5     0717-cdd4b20c-b48f-454b-b092-ad7aa14b39c8      
                              0727-d315d943-c501-4f69-823d-bb82a2b13b29   reserved-ip-for-us-south-2   10.240.65.5    0727-50b14707-c9f6-4f93-9f49-99de13c66161      
                                 
Service Endpoints             c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com
Lifecycle State               stable   
Health State                  ok   
Security groups               ID                                          Name      
                              r006-7ae081e2-743d-4046-b755-5ca9997ae077   spotted-sandpaper-auction-unluckily      
                                 
Created                       2026-04-04T18:17:12-05:00   
Resource Group                Default

Test the connection from a VSI in the source VPC.

curl -k https://c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com:31100/version

Example output

{
  "major": "1",
  "minor": "32",
  "gitVersion": "v1.32.12",
  "gitCommit": "9b706b45b52a0c8bb05847295ee98ffccbabba32",
  "gitTreeState": "clean",
  "buildDate": "2026-02-19T13:30:47Z",
  "goVersion": "go1.23.10 (Red Hat 1.23.10-10.el9) X:strictfipsruntime",
  "compiler": "gc",
  "platform": "linux/amd64"
}

Verify the host name resolves to a reserved IP.

dig +short c8m5n3p2q4x6z1w7y077.vpe.private.us-east.containers.cloud.ibm.com

Example output

10.240.65.5