1. User Guide
  2. Load Balancer as a Service
  3. Virtual Hostnames

Virtual Hostnames

This section describes how to use virtual hostnames with a load balancer for one or more listeners.

Creating a Load Balancer Virtual Hostname

A virtual hostname is associated with a load balancer (LB) and used by one or more listeners. Hostnames associated with a listener correspond to the backend set of that listener. The backend set routes traffic to specific backends which host different applications.

Virtual hostnames simplify the construction of the hostnames associated with listeners and backend servers because virtual hostnames can use wild card asterisks (*) at the start or end of the hostname. Listeners detect a hostname pattern that matches the virtual hostname patterns created.

Note:

The asterisk (*) doesn't have to be used in a virtual hostname. However, when used, the asterisk can only be added at the beginning or ending of a virtual hostname. Traffic sent to app.example.com is load balanced by a listener and backend server set when configured as app.example.com (exact), *example.com (wild card at start), or app.example* (wild card at end).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Load Balancers.

  2. Click the name of the Compartment for which you want to create the load balancer virtual hostname.

  3. Click the name of the LB for which you want to create the virtual hostname.
  4. Under Resources, click Hostnames.
  5. Click Create Hostname.

  6. In the Load Balancer Create Hostname window, in the Name field, give a name to the LB virtual hostname. For example, my_virtual_hostname.

  7. In the Hostname field, enter the virtual hostname. For example, *example.com.

    Note:

    Both fields are required.

  8. Click the Create Hostname button in the dialog.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • LB OCID (oci lb load-balancer list --compartment-id compartment_OCID)

  2. Run the virtual hostname create command.

    Use the LB OCID, name, and virtual hostname to create the virtual hostname for the LB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci lb hostname create --hostname virtual-hostname --load-balancer-id load-balancer_OCID \
--name virtual-hostname-friendly-name

    Where:

    • virtual-hostname is virtual hostname itself, such as *example.com.

    • load-balancer_OCID is the OCID of the load balancer associated with the backend set and servers.

    • virtual-hostname-friendly-name is the user-friendly name of the virtual hostname, such as my_virtual_hostname.

    Example:

    $ oci lb hostname create --hostname *example.com \
--load-balancer-id ocid1.loadbalancer....….….….uniqueID \
--name my_virtual_hostname
 
{
  "opc-work-request-id": "ocid1.workrequest.oc1.pca.....….….….uniqueID"
}

    Note:

    To see the virtual hostname results, you must list all virtual hostnames associated with the specified LB and verify that the hostname created is listed. Use the oci lb hostname list command to view the virtual hostname details. 
    $ oci lb hostname list --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": [
    {
      "hostname": "app.example.com",
      "name": "match-exact-hostname"
    },
    {
      "hostname": "*example.com",
      "name": "my_virtual_hostname"
    },
    {
      "hostname": "app.example*",
      "name": "suffix-match-hostname"
    }
  ]
}
    oci lb load-balancer get --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": {
    "backend-sets": {},
    "certificates": {},
    "compartment-id": "ocid1.tenancy.....….….….uniqueID",
    "defined-tags": null,
    "display-name": "Pub_LB1",
    "freeform-tags": null,
    "hostnames": {
      "match-exact-hostname": {
        "hostname": "app.example.com",
        "name": "match-exact-hostname"
      },
      "my-virtual-hostname": {
         "hostname": "*example.com",
         "name": "my-virtual-hostname"
      },
      "suffix-match-hostname": {
         "hostname": "app.example*",
         "name": "suffix-match-hostname"
      }
    },
   "id": "ocid1.loadbalancer......….….….uniqueID"",
   "ip-addresses": null,
    "is-private": false,
    "lifecycle-state": "ACTIVE",
    "listeners": {},
    "network-security-group-ids": null,
    "path-route-sets": {}, 
    "routing-policies": null,
    "rule-sets": {},
    "shape-details": null,
    "shape-name": "IGNORE",
    "ssl-cipher-suites": {},
    "subnet-ids": [
    "ocid1.subnet......….….….uniqueID"",
    "ocid1.subnet......….….….uniqueID""
    ],
  "system-tags": null,
  "time-created": "2022-08-30T18:25:31+00:00"
  },
  "etag": "9326dbb5-d842-4975-9cfb-ced7717e92d6"
}

Viewing Load Balancer Virtual Hostnames

You can view the virtual hostnames associated with a load balancer (LB).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Load Balancers.

  2. Click the name of the Load Balancer for which you want to view the virtual hostnames.

  3. Under Resources, click Hostnames.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • LB OCID (oci lb load-balancer list --compartment-id compartment_OCID)

  2. Run the virtual hostname get command.

    Use the LB OCID, name, and virtual hostname to update the virtual hostname for the LB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci lb hostname get --load-balancer-id load-balancer_OCID

    Where:

    • load-balancer_OCID is the OCID of the load balancer associated with the backend set and servers.

    Example:

    $ oci lb hostname get --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": [
    {
      "hostname": "app.example.com",
      "name": "match-exact-hostname"
    },
    {
      "hostname": "*example.com",
      "name": "my_virtual_hostname"
    },
    {
      "hostname": "app.example*",
      "name": "suffix-match-hostname"
    }
  ]
}

    Note:

    Use the lb load-balancer get command to view the virtual hostname details. 
    oci lb load-balancer get --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": {
    "backend-sets": {},
    "certificates": {},
    "compartment-id": "ocid1.tenancy.....….….….uniqueID",
    "defined-tags": null,
    "display-name": "Pub_LB1",
    "freeform-tags": null,
    "hostnames": {
      "match-exact-hostname": {
        "hostname": "app.example.com",
        "name": "match-exact-hostname"
      },
      "my-virtual-hostname": {
         "hostname": "app.example*",
         "name": "my-virtual-hostname"
      },
      "suffix-match-hostname": {
         "hostname": "app.example*",
         "name": "suffix-match-hostname"
      }
    },
   "id": "ocid1.loadbalancer......….….….uniqueID"",
   "ip-addresses": null,
    "is-private": false,
    "lifecycle-state": "ACTIVE",
    "listeners": {},
    "network-security-group-ids": null,
    "path-route-sets": {}, 
    "routing-policies": null,
    "rule-sets": {},
    "shape-details": null,
    "shape-name": "IGNORE",
    "ssl-cipher-suites": {},
    "subnet-ids": [
    "ocid1.subnet......….….….uniqueID"",
    "ocid1.subnet......….….….uniqueID""
    ],
  "system-tags": null,
  "time-created": "2022-08-30T18:25:31+00:00"
  },
  "etag": "9326dbb5-d842-4975-9cfb-ced7717e92d6"
}

Editing a Load Balancer Virtual Hostname

You can change the virtual hostname associated with a load balancer (LB).

Virtual hostnames can use wild card asterisks (*) at the start or end of the hostname. Listeners detect a hostname pattern that matches the virtual hostname patterns created.

Note:

The asterisk (*) does not have to be used in a virtual hostname. However, when used, the asterisk can only be added at the beginning or ending of a virtual hostname. Traffic sent to app.example.com is load balanced by a listener and backend server set when configured as app.example.com (exact), *example.com (wild card at start), or app.example* (wild card at end).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Load Balancers.

  2. Click the name of the Load Balancer for which you want to edit the virtual hostnames.

  3. In the Load Balancer Hostnames window, in the three-dot pull-down menu under Actions, select Edit.

  4. In the Hostname field, enter the new virtual hostname. For example, app.example*.

    Note:

    You can't edit the Name field. You must delete the old Hostname and create another Name to accomplish this.

  5. Click the Save Changes button in the dialog.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • LB OCID (oci lb load-balancer list --compartment-id compartment_OCID)

  2. Run the virtual hostname update command.

    Use the LB OCID, name, and virtual hostname to update the virtual hostname for the LB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci lb hostname update --hostname virtual-hostname --load-balancer-id load-balancer_OCID \
--name virtual-hostname-friendly-name

    Where:

    • virtual-hostname is virtual hostname itself, such as *example.com.

    • load-balancer_OCID is the OCID of the load balancer associated with the backend set and servers.

    • virtual-hostname-friendly-name is the user-friendly name of the virtual hostname, such as my_virtual_hostname.

    Example:

    $ oci lb hostname update --hostname app.example*, \
--load-balancer-id ocid1.loadbalancer....….….….uniqueID
--name my_virtual_hostname
 
{
  "opc-work-request-id": "ocid1.workrequest.oc1.pca.....….….….uniqueID"
}

    Note:

    To see the virtual hostname results, you must list all virtual hostnames associated with the specified LB and verify that the hostname edited is listed with the new value. Use the oci lb hostname list command to view the virtual hostname details. 
    $ oci lb hostname list -load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": [
    {
      "hostname": "app.example.com",
      "name": "match-exact-hostname"
    },
    {
      "hostname": "app.example*",
      "name": "my_virtual_hostname"
    },
    {
      "hostname": "app.example*",
      "name": "suffix-match-hostname"
    }
  ]
}
    oci lb load-balancer get --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": {
    "backend-sets": {},
    "certificates": {},
    "compartment-id": "ocid1.tenancy.....….….….uniqueID",
    "defined-tags": null,
    "display-name": "Pub_LB1",
    "freeform-tags": null,
    "hostnames": {
      "match-exact-hostname": {
        "hostname": "app.example.com",
        "name": "match-exact-hostname"
      },
      "my-virtual-hostname": {
         "hostname": "app.example*",
         "name": "my-virtual-hostname"
      },
      "suffix-match-hostname": {
         "hostname": "app.example*",
         "name": "suffix-match-hostname"
      }
    },
   "id": "ocid1.loadbalancer......….….….uniqueID"",
   "ip-addresses": null,
    "is-private": false,
    "lifecycle-state": "ACTIVE",
    "listeners": {},
    "network-security-group-ids": null,
    "path-route-sets": {}, 
    "routing-policies": null,
    "rule-sets": {},
    "shape-details": null,
    "shape-name": "IGNORE",
    "ssl-cipher-suites": {},
    "subnet-ids": [
    "ocid1.subnet......….….….uniqueID"",
    "ocid1.subnet......….….….uniqueID""
    ],
  "system-tags": null,
  "time-created": "2022-08-30T18:25:31+00:00"
  },
  "etag": "9326dbb5-d842-4975-9cfb-ced7717e92d6"
}

Deleting a Load Balancer Virtual Hostname

You can delete the virtual hostname associated with a load balancer (LB).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Load Balancers.

  2. Click the name of the Load Balancer for which you want to edit the virtual hostnames.

  3. In the Load Balancer Hostnames window, in the three-dot pull-down menu under Actions, select Delete.

  4. Click the Confirm button in the dialog.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • LB OCID (oci lb load-balancer list --compartment-id compartment_OCID)

  2. Run the virtual hostname delete command.

    Use the LB OCID, name, and virtual hostname to delete the virtual hostname for the LB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci lb hostname delete --load-balancer-id load-balancer_OCID \
--name virtual-hostname-friendly-name

    Where:

    • load-balancer_OCID is the OCID of the load balancer associated with the backend set and servers.

    • virtual-hostname-friendly-name is the user-friendly name of the virtual hostname, such as my_virtual_hostname.

    Example:

    $ oci lb hostname delete --load-balancer-id ocid1.loadbalancer....….….….uniqueID
--name my_virtual_hostname
 
{
  "opc-work-request-id": "ocid1.workrequest.oc1.pca.....….….….uniqueID"
}

    Note:

    To see the virtual hostname results, you must list all virtual hostnames associated with the specified LB and verify that the hostname deleted no longer appears in the list. Use the oci lb hostname list command to view the virtual hostname details. 
    $ oci lb hostname list --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": [
    {
      "hostname": "app.example.com",
      "name": "match-exact-hostname"
    },
    {
      "hostname": "app.example*",
      "name": "suffix-match-hostname"
    }
  ]
}
    oci lb load-balancer get --load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": {
    "backend-sets": {},
    "certificates": {},
    "compartment-id": "ocid1.tenancy.....….….….uniqueID",
    "defined-tags": null,
    "display-name": "Pub_LB1",
    "freeform-tags": null,
    "hostnames": {
      "match-exact-hostname": {
        "hostname": "app.example.com",
        "name": "match-exact-hostname"
      },
      "suffix-match-hostname": {
         "hostname": "app.example*",
         "name": "suffix-match-hostname"
      }
    },
   "id": "ocid1.loadbalancer......….….….uniqueID"",
   "ip-addresses": null,
    "is-private": false,
    "lifecycle-state": "ACTIVE",
    "listeners": {},
    "network-security-group-ids": null,
    "path-route-sets": {}, 
    "routing-policies": null,
    "rule-sets": {},
    "shape-details": null,
    "shape-name": "IGNORE",
    "ssl-cipher-suites": {},
    "subnet-ids": [
    "ocid1.subnet......….….….uniqueID"",
    "ocid1.subnet......….….….uniqueID""
    ],
  "system-tags": null,
  "time-created": "2022-08-30T18:25:31+00:00"
  },
  "etag": "9326dbb5-d842-4975-9cfb-ced7717e92d6"
}