Creating a Private Path service

Creating a Private Path service in the UI

To create a Private Path service with the IBM Cloud console, follow these steps:

1. From your browser, open the IBM Cloud console and log in to your account.

2. Select the Navigation Menu , then click Infrastructure > Network > Private Path services.

3. Click Create.

4. Review the checklist for important information.

5. In the Location section, ensure that the following fields are correct. If not, click the Edit icon to update.

   • Geography: The general area where you want to create the Private Path service.
   • Region: The region where you want to create the Private Path service.

6. In the Details section, provide the following information:

   • Name: Enter a unique identifier for the Private Path service, such as my-privatepath-service.
   • Resource group: Select a resource group, if necessary.
   • Tags: Optionally, add any relevant tags to help group your Private Path services.
   • Access management tags: Optionally, add access management tags to resources to help organize access control relationships. The only supported format for access management tags is key:value. For more information, see Controlling access to resources by using tags.
   • Virtual private cloud: Select the VPC where you want the Private Path service created.

7. In the Private Path network load balancer section, select a Private Path NLB for the Private Path service, or click Create to create one. To create a Private Path NLB, follow these steps:

   Click Next to go to the next step, or use the navigation menu on the left to go back to a specific section.

   1. In the Define details section, provide the following information:

      • Name: Enter a unique identifier for the Private Path NLB, such as my-privatepath-service.
      • Resource group: Select a resource group for the Private Path NLB.
      • Tags: Optionally, add any relevant tags to help group your Private Path NLBs.
      • Access management tags: Optionally, add access management tags to resources to help organize access control relationships. The only supported format for access management tags is key:value. For more information, see Controlling access to resources by using tags.
      • Subnet: Select the subnet where you want the Private Path NLB created.

   2. In the Create back-end pool section:

      • Name: Enter a unique identifier for the Private Path NLB, such as my-ppnlb.

      • Select the method, which is the load-balancing algorithm. The follow options are shown.

        • Round robin - Forwards requests to each instance in turn. All instances receive approximately an equal number of client connections.
        • Weighted round robin - Forwards requests to each instance in proportion to its assigned weight. For example, if you have instances A, B, and C, and their weights are set to 60, 60 and 30, then instances A and B receive an equal number of connections, and instance C receives half as many connections.

        In the Health check section:

        • Health check path - The health check path is applicable only if you select HTTP as the health check protocol. The health check path specifies the URL used by the load balancer to send the HTTP health check requests to the instances in the pool. By default, health checks are sent to the root path (/).
        • Health protocol - The protocol used by the load balancer to send health check messages to the instances in the pool.
        • Health port - The port on which to the load balancer sends health check requests. By default, health checks are sent on the same port on which traffic is sent to the instance.
        • Interval - The interval in seconds between two consecutive health check attempts. By default, health checks are sent every 5 seconds.
        • Timeout - The maximum amount of time the system waits for a response from a health check request. By default, the load balancer waits 2 seconds for a response.
        • Max retries - The maximum number of health check attempts that the load balancer makes before an instance is declared unhealthy. By default, an instance is no longer considered healthy after two failed health checks.

        Although the load balancer stops sending connections to unhealthy instances, it continues monitoring the health of these instances and resumes their use if they're found healthy again (that is, if they successfully pass two consecutive health check attempts).

      If instances in the pool are unhealthy and you believe that your application is working correctly, double check the health protocol and health path values. Also, check any security groups that are attached to the instances to ensure that the rules allow traffic between the load balancer and the instances.

      • Click Save. Repeat this step if you want to create another back-end pool.

   3. In the Attach servers section:

      • Back-end pool: Select the back-end pool where you want to attach servers.
      • Subnet: Select the subnets that you want to attach. Search for specific subnets in the table, and check the box beside the subnets that you want to attach. In the Port column, enter a port number for each subnet you select.

   4. In the Front-end listener section, select the back-end pool where you want to attach your front-end listener. Then, select the listener port value and click Save. Repeat this step if you want to create another front-end listener.

   5. In the Review section, confirm that the information you submitted is correct. Review the order summary, then click Create.

      It takes several minutes for your Private Path NLB to be created. When the load balancer is created, its status changes from Creating to Active in the table.

8. In the Service endpoint section, click Create. Provide a name for the service endpoint where you want to connect your Private Path service. Click Add +. Then, select to enable or disable zonal affinity for the service endpoints. When zonal affinity is enabled, the endpoint maintains persistence to the zone after the connection is created.

9. In the Account policies section:

   • The default policy is set to review and triage each incoming connection request. You can change the default policy to permit or deny all requests without review.
   • To establish account policies that are different than the default policy, click Create. Provide the account ID of the account for which you want to set up a policy. For the Account policy option, select Review, Permit, or Deny.

   Individual account policies take precedence over the default policy.

10. Review the summary panel, then click Create to order your Private Path service.

    When provisioning completes, the Private Path service status indicates Stable in the Private Path services for VPC table.

Creating a Private Path service from the CLI

Beta participants must export a feature flag to use the CLI. Contact your IBM Support representative to obtain.

The following example shows how to use the CLI to create a Private Path service.

Before you begin, make sure to set up your CLI environment.

You must export the feature flag for Private Path service and Private Path network load balancer related commands to run successfully.

To export the feature flag, enter the following commands:

export IBMCLOUD_IS_FEATURE_PRIVATE_PATH_SERVICE_GATEWAY=true
export IBMCLOUD_IS_FEATURE_PP_NLB_SUPPORT=true

To create a Private Path service from the CLI, follow these steps:

1. Enter the following command:

ibmcloud is private-path-service-gateway-create
    [--load balancer LOAD_BALANCER]
    [--service-endpoints SERVICE_ENDPOINTS]
    [--default-access-policy | deny | permit | review]
    [--name NAME]
    [--zonal-affinity | true | false]
    [--output JSON] [-q, --quiet]

Where:

--load-balancer

Indicates ID or name of load balancer for this Private Path service.

--service-endpoints

Indicates the fully qualified domain names for this Private Path service. Any uppercase letters will be converted to lowercase.

--default-access-policy

Indicates the policy to use for bindings from accounts without an explicit account policy. One of: deny, permit, review. (default: deny).

--name

Indicates the name for this Private Path service.

--zonal-affinity

indicates whether this Private Path service has zonal affinity. One of: false, true.

--output

specify output format, only JSON is supported. One of: JSON.

-q, --quiet

suppress verbose output.

Creating a Private Path service with the API

To create a Private Path service with the API, follow these steps:

1. Set up your API environment.

2. Store the following values in variables to be used in the API command:

   • loadBalancerId - First, get your load balancer and then populate the variable:

     export loadBalancerId=<your_loadbalancer_id>
     

3. When all variables are initiated, do one of the following:

   • To create a private path service:

     curl -X POST -sH "Authorization:${iam_token}" \
     "$vpc_api_endpoint/v1/private_path_service_gateways?version=$api_version&generation=2" \
     -d {
       "default_access_policy": "review",
       "load_balancer": {
         "id": "$loadBalancerId"
       },
       "name": "my-ppsg",
       "service_endpoints": ["example.com"],
       "zonal_affinity": false
     }'
     

Creating a Private Path service with Terraform

Terraform will support this feature after it reaches General Availability (GA) and is officially released.

The following example provisions a Private Path network by using Terraform:

resource "ibm_is_private_path_service_gateway" "ppsg" {
    default_access_policy = "deny"
    load_balancer = ibm_is_lb.ppnlb.id
    service_endpoints = ["my-service.example.com"]
    zonal_affinity = false
    name = "my-example-ppsg"
}