Create and Advertise a VirtualHost

Objective

This guide provides instructions on how to create and advertise a Virtual Host. A Volterra virtual host is a reverse proxy that provides reachability to destinations that are in the inside network and clients are in the outside network. To know more about Volterra virtual host and associated key system entities, see Virtual Host.

Using the instructions provided in this guide, you can create a virtual host that advertises a service deployed on a site and provide reachability to the endpoint where the service is available.


Prerequisites

The following prerequisites apply:


Configuration

The following image shows the virtual host creation workflow:

FlowChart
Figure: Setting up a Volterra VirtualHost

Configuration Sequence

Creating and advertising a virtual host requires performing the following sequence of actions:

Phase Description
Discover Service Discover a service from a Site or a Virtual Site. Sites are in the system namespace. Virtual Sites can be created in a namespace.
Create Endpoint Create an Endpoint object which requires an endpoint address type. Endpoint address can be of type IP or DNS Name or Service Info.
Create Cluster Create a cluster object which points to one or more endpoints in that namespace.
Create Route Create a Route object which maps to one or more Clusters in that namespace.
Create Advertise Policy Create an Advertise Policy object where the service can be advertised on Site or Virtual Site or Virtual Network (including the Public Internet).
Create Virtual Host Creates a Virtual Host object in a namespace where above Advertise Policy and Route are associated.

Create Endpoint

See Endpoint for more information on endpoint.

Step 1: Select a desired namespace or create a namespace where endpoint needs to be created.

NavNS
Figure: Navigate to Namespace

Step 2: Select Manage from the configuration menu and Endpoints from the options pane. Select Add endpoint on the top. The Add endpoint form gets loaded.

EndptCreate
Figure: Create an Endpoint

Step 3: Enter appropriate values for the Name, Labels, and Description fields.

EPConfig
Figure: Configure an Endpoint

Note: Enter the values as per the following guidelines:

  1. Name: Provide a name for identifying the endpoint object on the Volterra platform
  2. Labels: Associate multiple labels from either known keys/known labels or custom keys and labels
  3. Description: Provide a description to the endpoint object

Step 5: Enter endpoint address by selecting one of the three options as shown in the image.

EPAddr
Figure: Endpoint Address Options

  • IP: IP Address of the origin service. For example, if a service is running in public cloud platform like AWS, provide the publicly reachable IP address in the IP field.

EPIPAddr
Figure: Endpoint Address IP option

  • DNS name: DNS name of the origin service. For example, if a service called ‘webapp’ has a resolvable DNS name ‘webapp.customer1.net’ associated with it, provide the DNS name in the DNS field.

EPDNSName
Figure: Endpoint Address DNS name Option

  • Service Info: Kubernetes Service information of the origin service. Select this option to directly discover a service running on Volterra Kubernetes Service or any other public cloud kubernetes services such as EKS, AKS and GCP. An explicit ‘Service Discovery’ object has to be created if selected service is running on public cloud kubernetes services. There is no need to create ‘Service Discovery’ object if the service is deployed using VoltStack (Virtual Kubernetes Service). Enter the service name in the <Name of the Kubernetes Service>.<Namespace in which the Kubernetes Service is placed> format.

See Service Discovery for more information.

The Service Info field has two options in the ‘Discovery Type’ subfield:

  • K8S: Use this when you deploy the service on Volterra Kubernetes Service or any public cloud platform (EKS/AKS/GCP). Configure an extra object in case a public cloud platform is involved. If the service is hosted on Volterra Kubernetes Service, then Volterra seamlessly enables the service discovery.
  • Consul: Use this option when you have an existing Consul cluster or create a Consul cluster for service discovery where Volterra reads discovery information directly from Consul. This requires you to create a discovery object with Consul connection information.

    EPSrvcInfo
    Figure: Endpoint Service Info

Step 6: Configure RefOrSelector. A selector can be a site, virtual site, virtual network, or known network. This defines the location from which origin service is discovered.

See Volterra Virtual Site for more information.

EPRefSel
Figure: Endpoint Reference Selector

Configure the selector as per the following guidelines:

  • Site: Select a site that is already registered in the specific tenant. You can list all the registered sites from system:Sites:SiteList. Sites are scoped under a Volterra tenant. Choose a ‘Site’ from the ‘Select Ref’ pane once the Selector type is chosen.
  • Virtual Site: Select a virtual site that is already created in the specific namespace (volterra-demo in this example) or in the shared namespace. A virtual site can map one or more sites. Choose a ‘Virtual Site’ from the ‘Select Ref’ pane once the Selector type is chosen.
  • Virtual Network: Select a virtual network that is already created in the tenant. Choose a ‘Virtual Network’ from the ‘Select Ref’ pane once the Selector type is chosen.

Step 7: Configure port and protocol. Port refers to the port on which the service is serving and protocol refers to the protocol that the application uses.

EPPortProto
Figure: Endpoint Port and Protocol

Configure the port and protocol as per the following guidelines:

  • Port: port on which the application is serving. For example a web service application serving on port 8080.
  • Protocol: Defaults value is TCP. TCP is the only protocol supported.

Step 8: Click Add endpoint to create the endpoint.

After all the parameters are entered in the respective fields, clicking Add endpoint adds the endpoint object to Volterra.

EPCreated
Figure: Endpoint Created


Create Cluster

See Cluster for more information.

Step 1: Select the Namespace in which the associated endpoint is located.

NavtoNS
Figure: Navigate to Namespace

Step 2: Select Manage and select Clusters from the options pane. Click Add cluster on the top.

AddClust
Figure: Add Cluster

Step 3: The Add cluster form loads.

ConfigClust
Figure: Configure Cluster

Step 4: Configure name, labels, and description as per the following guidelines:

  1. Name: Provide a name for identifying cluster object
  2. Labels: Associate multiple labels from either known keys/known labels or custom keys and labels
  3. Description: Provide a description to the cluster object

Step 5: Configure endpoints associated with the cluster. Endpoints refer to list of endpoints that are mapped to a specific cluster. A cluster can point to one or more endpoints. Choose Endpoints from the Select endpoint pane.

ClustEPSel
Figure: Cluster Endpoint Selection

Step 6: Configure health checks associated with the cluster. Health check refers to configuring checks to ensure underlying endpoints are available. It is required to configure a health check object first to list them while creating the cluster.

ClustHC
Figure: Cluster Health Check

Step 7: Select the health check object created and click Select health check.

ClustHCSel
Figure: Cluster Health Check Selection

Step 8: Configure load-balancer algorithm. The Load balancer algorithm refers to a specific method of load-balancing to be applied on cluster object. Choose from the supported algorithms Random, Round_Robin, Least_Request, and Ring_Hash. If no value is configured, the default value Round_Robin is applied.

ClustLBAlgo
Figure: Cluster Load Balance Algorithm

Step 9: Configure endpoint subsets for fallback policy. Endpoint subset is a subset of endpoints grouped together using a key/value pair. Provide multiple keys and associate a label to group available endpoints. These are used in setting fallback policy.

ClustEPSubSet
Figure: Cluster Endpoint Subsets

Step 10: Configure TLS for cluster object.You can set TLS version and configure TLS certificates for the cluster object using the TLS parameters.

ClustTLS
Figure: Cluster TLS Config

Step 11: After all the parameters are entered in the respective fields, click Add cluster. This adds the cluster object to Volterra.

ClustCreated
Figure: Cluster Created


Create Route

See Route for more information.

Step 1: Select the Namespace in which the associated cluster object is located.

NavNS
Figure: Navigate to Namespace

Step 2: Select Manage from configuration menu and Routes from the options pane. Click Add route. The Add route form gets loaded.

AddRoute
Figure: Add Route

Step 3: Enter the values for Name, Labels, and Description fields.

AddRouteConfig
Figure: Add Route Config Options

Enter the values as per the following guidelines:

  1. Name: Provide a name for identifying route object on Volterra platform
  2. Labels: You can associate multiple labels from either known keys/known labels or custom keys and labels
  3. Description: Provide a description to the route object

Step 4: Configure routes associated with the route object. Click Add route to open the Routes configuration form for different routing options.

ConfRoutesforRouteObj
Figure: Configure Routes for Route Object

Enter the configuration parameters as per the following guidelines:

Route Action: Route action specifies the action executed when this route object is accessed. You can choose one of the three options:

  • Route Destination: Route destination enables you to map one or more cluster objects to this specific route
  • Route redirect: Route redirect enables you to redirect requests received by this route
  • Route direct response: Route direct response enables you to provide a response code

    RouteAction
    Figure: Route Action Options

Configuring Route Destination:

Selecting ‘Route destination’ in route action provides with options to associate one or more clusters to the destination.

RouteDest
Figure: Route Action Route Destination Option

RouteDestClust
Figure: Route Action Route Destination Select Cluster

Step 5: Click Add Match in the Match field to implement traffic match patterns and rules based on different HTTP methods like GET, PUT, POST, etc.

Choose one of the three available match patterns:

  • Prefix
  • Path
  • Regex

You can also specify an optional combination of headers, query parameters, and HTTP methods. Click Add match.

RouteMatch
Figure: Route Match Options

Step 7: After entering all parameters in the respective fields, click Add route to add the route object to Volterra.

RouteCreated
Figure: Route Created


Create Advertise Policy

See Advertise Policies for more information.

Step 1: Select the namespace in which the advertise policy needs to be created.

NavNS
Figure: Navigate to Namespace

Step 2: Select Manage from configuration menu and Advertise Policies from the options pane. Click Add advertise policy.

AddAdvPol
Figure: Add Advertise Policy

Step 3: Enter name, labels, and description in the Add advertise policy form.

ConfAdvPolOpt
Figure: Advertise Policy Config Options

Enter the values as per the following guidelines:

  1. Name: Provide a name for identifying advertise policy
  2. Labels: Users can associate multiple labels from either Known Keys/Know Labels or custom keys and labels
  3. Description: Users can provide a description to Advertise policy object

Step 4: Enter Where to advertise the service. The field Where enables you to advertise a service on a site, virtual site, and virtual network. For example, if multiple sites are spatially distributed across regions (cloud and physical), you can discover a service from one site and advertise the same on one or more sites.

AdvPolWhere
Figure: Advertise Policy Where Options

Enter the site, virtual site, or virtual network as per the following guidelines:

  • Site: A site registered and listed in the Site List in the system namespace.

    AdvPolWhereSite
    Figure: Advertise Policy Where Site Option

    • Virtual Site: One or more sites grouped into a virtual site using key/label. If a virtual site has more than one site, advertise policy will announce the services on all the sites.

    AdvPolWhereVsite
    Figure: Advertise Policy Where VirtualSite Option

    • Virtual Network: A Virtual network created by user. Advertise policy advertises the service on all devices which comprise the chosen virtual network.

    AdvPolWhereVNW
    Figure: Advertise Policy Where VirtualNetwork Option

Step 5: Enter port and protocol in the Port and Protocol fields respectively.

AdvPolPortProto
Figure: Advertise Policy Protocol and Port

Enter the values as per the following guidelines:

  • Port: Refers to port on which the discovered service is advertised. This can be a different port than the originally discovered port from the ‘Endpoint’ object. Advertising on public networks is supported for only ports 80 and 443.
  • Protocol: Refers to protocol that the service supports. Default is ‘TCP’.

Step 5: After entering all required parameters in the respective fields, click Add advertise policy button to add the advertise policy object to Volterra.

AdvPolCreated
Figure: Advertise Policy Created


Create Virtual Host

See Virtual Host for more information.

Step 1: Select the Namespace in which virtual host needs to be created.

NavNS
Figure: Navigate to Namespace

Step 2: Select Manage from the configuration menu and select virtual host from the options pane. Click Add virtual host.

AddVHost
Figure: Add Virtual Host

Step 3: Enter name, labels, and description in the Add virtual host form.

AddVHConf
Figure: Virtual Host Config Options

Enter the values as per the following guidelines:

  1. Name: Provide a name for identifying advertise policy object on Volterra platform
  2. Labels: You can associate multiple labels from either known keys/known labels or custom keys and labels
  3. Description: Provide a description to advertise policy object

Step 4:. Click Add domain in the Domains field. Domain is used to access the virtual host. A virtual host can have one or more domains associated with it.

VHDomConf
Figure: Virtual Host Domain Config

Step 5: Select a value for the Proxy Type field. Proxy type enables you to configure specific type of proxy on the virtual host. The supported proxy types are TCP_PROXY, TCP_PROXY_WITH_SNI, HTTPS_PROXY and HTTP_PROXY.

VHProxType
Figure: Virtual Host Proxy Type Options

Step 6: Click Select route to associate one or more routes with the virtual host.

VHRouteSel
Figure: Virtual Host Route Selection

Step 7: Click Select advertise policy to associate an advertise policy with the virtual host.

VHAdvPol
Figure: Virtual Host Advertise Policy Selection

Step 8: After entering all required parameters, click Add virtual host to create a virtual host object.


Configure Optional Parameters

Virtual host supports including additional optional configuration depending on your requirement. For example, you can apply TLS for in case you are configuring HTTPS proxy.

Configure TLS

Step 1: Click TLS Parameters to open the TLS configuration form. Click Add TLS certificates and enter the certificate in the string:/// URL format.

Step 2: Click Private Key to open the private key configuration form. Select a value for the Secret info field as per the following guidelines:

  • Select Vault Secret if your secret is encrypted by Hashicorp Vault. Configure the following fields for Vault secret.

    • Enter the name of the secret management access object in the Provider field.
    • Enter the path to secret in the Location field.
    • Optionally, enter the key of a specific secret in the Key field to apply that secret. If you do not specify a key, entire secret map is applied.
    • Optionally, enter a specific version for vault secret in the Version field. By default, latest version is applied.
  • Select Clear Secret if your secret is not encrypted by any specific provider. Configure the following fields for clear secret.

    • Enter the value for the URL field in the string:/// format.
  • Select Blindfold Secret if your secret is encrypted by Volterra blindfold. Configure the following fields for blindfold.

    • Enter the path to secret in the Location field. The supported formats are string:/// and path to the HTTP or HTTPS location depending on the provider.
    • Optionally, enter the name of the secret management access object in the Decryption rovider field.
    • Optionally, enter name of the the secret management access object in the Store Provider field. Not required if the location is specified in the string:/// format.
  • Select Bootstrap Secret if the secret is applied as bootstrap secret in wingman. Configure the following fields for bootstrap secret:

    • Enter the name of the bootstrap secret in the Name field.
  • Select Base64 for the Secret Encoding field. Selcting EncodingNone does not apply any encryption.

Step 3: Click Apply to apply the private key and click Add TLS Certificate to apply the certificate.

Step 4: Enter your CA URL for the Trusted CA field.

Step 5: Select a minimum version and maximum version for the Minimum TLS Version and Maximum TLS version respectively.

Step 6: Click Cipher suites and add cipher suites of your choice.

Step 7: Configure the parameters for the Trusted CA Validation params fields as per the following guidelines:

  • Enter your CA URL for the Trusted CA field.
  • Select Skip verification of hostname checkbox to disable matching of the CN or Subject Alternate Name(SAN) to the connecting hostname.
  • Click Add verify subject alt name to add SANs. If this is empty and the Skip verification of hostname field is not selected, the hostname of the peer is used to match the SANs.

Step 8: Select Require Client Certificate(enable mTLS) checkbox to enable checking for a valid client certificate. Click Apply to add TLS configuration.

Note: TLS can be configured for advertise policy or virtual host.


Configure WAF

Step 1: Select either WAF or WAF Rules in the WAF Config field.

Step 2: Click Select WAF or Select WAF Rules as per the choice made in Step 1. Select WAFs or WAF rules in the selection form.

Step 3: Click Select WAF or Select WAF rule to apply the WAF or WAF rule.

Note: You must first create WAF or WAF rule to apply them in the configuration. To create WAF or WAF rule, see Configure WAF.


Configure Dynamic Reverse Proxy

Step 1: Click Dynamic Reverse Proxy to open the configuration form.

Step 2: Select the Dynamic Endpoint Resolution checkbox.

Note: The resolution mechanism is dependent on the proxy type of the virtual host. For HTTP and HTTPS proxy, the HOST header is used for resolution. For TCP proxy with SNI, SNI is used.

Step 3: Select a network type for the Resolution Network Type field. Click Select resolution network and select a network from the displayed list.

Step 4: Click Select resolution network to apply the network and click Apply to add the dyanmic reverse proxy configuration.


Configure HTTP Header Processing

This chapter provides steps on additional processing of HTTP headers.

Step 1: Click Request headers to add and Add request headers to add. Enter name and value of the header in the Name and Value fields respectively. Click Apply to add headers.

Note: You can add multiple headers using the Add request headers to add button. Optionally, select the Append checkbox to append the value to existing values.

Step 2: Click Request headers to remove and Add request headers to remove. Enter the header keys. Click Apply to add headers.

Note: You can add multiple headers using the Add request headers to remove button.

Step 3: Click Response headers to add and Add response headers to add. Enter name and value of the header in the Name and Value fields respectively. Click Apply to add headers.

Note: You can add multiple headers using the Add response headers to add button. Optionally, select the Append checkbox to append the value to existing values.

Step 4: Click Response headers to remove and Add response theaders to remove. Enter the header keys. Click Apply to add headers.

Note: You can add multiple headers using the Add response headers to remove button.

Step 5: Click Buffer Policy. Enter values for the Max Request Bytes and Max Request Time fields. Enter the header keys. Click Apply to set the buffering policy. The buffer policy sets maximum request size to buffer and maximum request time exceeding which, the buffering is stopped.

Note: Optionally, select Disable to disable buffering for a specific route.

Configure CORS Policy

Step 5: Click CORS Policy. Click Add allow origin to add an origin domain name. Click Add allow origin regex to specify a regular expression to match domain names.

Note: You can add multiple origins using the Add allow origin or Add allow origin regex options.

Step 6: Enter methods in the Allow Methods field.

Note: Supported methods are HTTP methods such as GET, POST, etc. To specify more than one method, use comma separated list.

Step 7: Enter headers in the Allow Headers and Expose Headers fields to allow and expose specific headers.

Note: For example, you can allow cookie header and expose Content-Type header.

Step 8: Set a value for time in seconds for the Max Age field to set a time limit for the CORS policy.

Step 9: Select Allow Credentials checkbox to enable the resource to allow credentials. Click Apply to apply the CORS policy to the configuration of virtual host.

NoteSelect Disabled checbox to disable the CORS policy for a specific route.

Step 10: Select the Add Location checkbox to allow the x-volterra-location header in the HTTP responses.

Step 11: Set a value in bytes for the Content Length field in the Compression Parameters area.

Note: The minimum value allowed is 30 bytes.

Step 12: Click Add content type and enter one of the following mime-types:

  • application/javascript
  • application/json
  • application/xhtml+xml
  • image/svg+xml
  • text/css
  • text/html
  • text/xml
  • text/plain

Step 13: Select the Disable On Etag Header checkbox to disable compression when the response contain etag header.

Step 14: Select the Remove Accept-Encoding Heade checkbox to remove the accept-encoding header in the request headers.

Step 15: Specify labels for the Custom Error Responses field to match custom HTTP response pages.

Step 16: Enter a value in KiB for the Maximum Request Header Size field to set maximum header size for HTTP requests.

Note: The default value is 60 KiB and maximum allowed value is 96 KiB. Exceeding the set limit returns error with 431 code.


Configure Javascript Challenge

Step 1: Select Enable checkbox in the Javascript Challenge area to enable the javascript challenge.

Step 2: Set a time in milli seconds for the Javascript Delay field.

Step 3: Set a time in milli seconds for the Cookie Expiry period. Expiry of this period enables the loadbalancer to invoke javascript challenge.

Step 4: Enter a URL for the Custom page for Javascript Challenge Redirect field to specify the redirect page for the java script challenge.

Note: The URL can be a http or https location or can be specified in a string:/// format.


Example - Redirect HTTP to HTTPS

This example redirects a HTTP request for the destination bookinfovk8s-qasim.customer1.demo1.volterra.us.02 to secured HTTPS service. Enabling HTTP redirection requires you to configure two virtual hosts with one host of type HTTPS_PROXY and other of type HTTP_PROXY. Although there are two virtual hosts, the endpoint needs to be associated only with the host of type HTTPS_PROXY as the other host is used for redirection purpose.

The following image shows the configuration topology for redirecting HTTP to HTTPs.

http https
Figure: HTTP Redirecting Using Virtual Hosts

Perform the following steps to configure HTTP redirection:

Step 1: Select the namespace in which the virtual hosts are needed to be created. Select Manage from configuration menu and Endpoints from the options pane. Click Add endpoint. The Add endpoint form loads.

ep
Figure: Add endpoint

Step 2: Fill the necessary fields as applicable. This example uses Kubernetes as the service discovery mechanism and the service name as the service information. The service is available at port 9080. This example has the endpoint on a virtual site. Click Save changes.

ep k8s
Figure: Endpoint Service Information

Step 3: Select Clusters from the options pane and click Add cluster to load cluster creation form. Select the endpoint created in Step 2 for the Select endpoint field. Fill the necessary fields as applicable and click Save changes.

cluster
Figure: Cluster Creation

Step 4: Select Routes from the options pane and click Add route to load route creation form. Create a route with the route destination as the cluster created in Step 3. Click Apply and Save changes to save the route.

add route form
Figure: Route Creation

route http
Figure: Route Configuration for Destination

Step 5: Create another route with the Redirect as the Route action and apply the appropriate settings for redirection. This example uses URL for the host.

route https
Figure: Route Configuration for Redirection

Step 6: Select Advertise Policies from the options pane and click Add advertise policy to load advertise policy creation form. Select Virtual Network for the Where field and select the virtual network. Select 80 for the Port field. Click Apply and Save changes.

adv pol http
Figure: Advertise Policy for HTTP Service

Step 7: Create another advertise policy with the same virtual network and 443 as the port value.

adv pol https
Figure: Advertise Policy for HTTPS Service

Step 8: Select Virtual Hosts from the options pane and click Add virtual host to load virtual host creation form. Create a virtual host with the following values:

  • Select proxy type as HTTPS Proxy.
  • Apply route configured in Step 4 (the route with the destination as the cluster).
  • Apply advertise policy configured in Step 7 (policy for HTTPS service).
  • Select virtual host type as Virtual service.

vh direct route
Figure: Virtual Host of Type HTTP Proxy

vh type vsrvc
Figure: Virtual Host Type Selection

Click Apply and Save changes to create first virtual host.

Step 9: Create another virtual host with the following values.

  • Select proxy type as HTTP Proxy.
  • Apply route configured in Step 5 (the route with redirection configured).
  • Apply advertise policy configured in Step 6 (policy for HTTP service).
  • Select virtual host type as Virtual service.

vh redirect
Figure: Virtual Host of Type HTTPS Proxy


Concepts


API References