Working with Virtual Services

1. Creating Virtual Services

Property	Description	Example
metadata.name	Name of the virtual service	`frontend-vs`
metadata.namespace	Namespace where the virtual service is created	`default`
spec.hosts	List of hostnames to which traffic is being routed	`["frontend.example.com"]`
spec.gateways	List of gateways to which the virtual service is bound	`["mesh-gateway"]`
spec.http	HTTP route rules for traffic routing	`[ { "route": [ { "destination": { "host": "frontend" } } ] } ]`

Example: Basic Virtual Service Definition

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: frontend-vs
  namespace: default
spec:
  hosts:
  - frontend.example.com
  gateways:
  - mesh-gateway
  http:
  - route:
    - destination:
        host: frontend

2. Configuring HTTP Routes

Property	Description	Example
match	Defines the conditions under which a route is matched	`{ "path": "/api/users", "method": "GET" }`
route	Specifies the destination service and port to route traffic to	`{ "destination": { "name": "user-service", "port": { "number": 8080 } } }`
weight	Percentage of traffic to send to this route (optional)	`{ "weight": 70 }`

Example: Basic HTTP Route Configuration

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: user-service-route
spec:
  hosts:
    - user-service
  http:
    - match:
        - path:
            exact: /api/users
      route:
        - destination:
            name: user-service
            port:
              number: 8080

Example: Route with Weighted Distribution

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: api-route
spec:
  hosts:
    - api-service
  http:
    - match:
        - path:
            prefix: /api
      route:
        - destination:
            name: api-v1
            port:
              number: 8080
          weight: 80
        - destination:
            name: api-v2
            port:
              number: 8080
          weight: 20

3. Configuring TCP Routes

Property	Description	Example
host	Hostname or IP address to route traffic to	`backend-service.default.svc.cluster.local`
port	Port number to route traffic to	`8080`
weight	Weight for traffic distribution (optional)	`50`

Example: TCP Route Configuration

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: tcp-route-example
spec:
  hosts:
  - backend-service.default.svc.cluster.local
  tcp:
  - match:
    - port: 8080
    route:
    - destination:
        host: backend-service.default.svc.cluster.local
        port:
          number: 8080

4. Implementing TLS Routes

Property	Description	Values	Notes
tls.mode	Specifies the TLS mode for the route	`simple`, `mutual`, `passthrough`	Default is `simple`
tls.certificate	Path to the certificate file	`/etc/certs/tls.crt`	Required for `mutual` and `simple`
tls.key	Path to the private key file	`/etc/certs/tls.key`	Required for `mutual` and `simple`
tls.caCertificate	Path to the CA certificate file	`/etc/certs/ca.crt`	Required for `mutual`

Example: TLS Route Configuration

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: tls-route-example
spec:
  hosts:
  - https://api.example.com
  tls:
  - match:
    - port: 443
      sniHosts:
      - api.example.com
    route:
    - destination:
        host: api-service
        port:
          number: 443

Example: Mutual TLS Route

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mutual-tls-route
spec:
  hosts:
  - https://secure.example.com
  tls:
  - match:
    - port: 443
      sniHosts:
      - secure.example.com
    route:
    - destination:
        host: secure-service
        port:
          number: 443
    tls:
      mode: mutual
      certificate: /etc/certs/client.crt
      key: /etc/certs/client.key
      caCertificate: /etc/certs/ca.crt

Note: When using passthrough, the service mesh does not terminate TLS, and traffic is forwarded as-is to the destination.

5. Setting Route Matching Rules

Rule Type	Description	Example
method	HTTP method to match	`GET`, `POST`
path	URL path to match	`/api/users`
headers	HTTP headers to match	`{ "Authorization": "Bearer.*" }`
query	Query parameters to match	`{ "version": "v1" }`

Example: Route Matching Configuration

routes:
  - match:
      method: GET
      path: /api/users
      headers:
        Authorization: Bearer.*
      query:
        version: v1
    route:
      destination:
        host: user-service

6. Configuring Route Destinations

Property	Description	Values	Notes
destination.host	Service name or FQDN to route traffic to	`backend-service`	Must be resolvable within the mesh
destination.port.number	Port to route traffic to	`8080`	Must match service port
destination.subset	Subset of the service to route to	`v1`	Used for version-based routing

Example: Route to a specific version

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-service-route
spec:
  hosts:
  - my-service
  http:
  - route:
    - destination:
        host: my-service
        subset: v2
        port:
          number: 8080

Note: The subset must be defined in a corresponding DestinationRule.

7. Implementing Traffic Mirroring

Traffic mirroring in service meshes allows you to copy traffic from one service to another for analysis, testing, or debugging without affecting the primary request flow.

Property	Description	Example
sourceService	The originating service from which traffic is mirrored	`frontend`
destinationService	The service to which traffic is mirrored	`analytics`
percentage	Percentage of traffic to mirror (0-100)	`50`

Example: Mirroring 50% of Traffic

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: mirror-traffic
spec:
  hosts:
  - frontend
  http:
  - route:
    - destination:
        host: frontend
    mirror:
      host: analytics
      port:
        number: 80
    mirrorPercentage:
      value: 50.0

Note: Mirroring is supported in Istio and Linkerd. It does not affect the original request flow or response handling.

8. Configuring Request/Response Headers

Header Type	Configuration	Description
request.headers.add	`Authorization: Bearer token`	Adds a new header to the request
response.headers.add	`X-Response-Id: 12345`	Adds a new header to the response
request.headers.remove	`User-Agent`	Removes a header from the request
response.headers.remove	`Server`	Removes a header from the response

Example: Adding Request Headers

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: example-vs
spec:
  hosts:
  - example.com
  http:
  - route:
    - destination:
        host: example-service
    headers:
      request:
        add:
          Authorization: Bearer token

Example: Removing Response Headers

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: example-vs
spec:
  hosts:
  - example.com
  http:
  - route:
    - destination:
        host: example-service
    headers:
      response:
        remove:
        - Server

9. Managing Virtual Service Precedence

Property	Description	Default	Notes
precedence	Defines the order in which virtual services are evaluated	`0`	Higher values are processed first. If not set, services are evaluated in an undefined order
match	Defines matching criteria for routing rules	`null`	Used to determine which virtual service applies to a request

Example: Setting Precedence in Virtual Service

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: example-virtual-service
spec:
  hosts:
  - example.com
  precedence: 10
  http:
  - route:
    - destination:
        host: example-service

Note: Precedence is particularly useful when multiple virtual services target the same host, allowing control over which rules take effect first.

10. Troubleshooting Virtual Service Issues

Common Troubleshooting Steps

Verify that the virtual service is correctly defined in the configuration file.
Check if the associated route rules are properly configured and applied.
Ensure that the destination rule for the service is correctly set up to handle traffic.
Validate that the service mesh is running and all components are healthy.
Review logs from the sidecar proxies for any error messages or warnings related to virtual services.
Confirm that the service names in the virtual service match those registered in the service registry.

Issue	Possible Cause	Solution
Traffic Not Routing Correctly	Incorrect route match conditions or weight distribution	Review and adjust the route match criteria in the virtual service definition
Timeout Errors	Service unavailability or misconfigured timeouts	Adjust timeout values in the virtual service or check backend service health
503 Service Unavailable	Service instance not found or overloaded	Verify service instances are running and check resource allocation
504 Gateway Timeout	Proxy timeout due to long-running requests	Increase timeout settings in the virtual service or use circuit breaker patterns

Example: Virtual Service with Timeout Configuration

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: example-virtual-service
spec:
  hosts:
  - example-service
  http:
  - route:
    - destination:
        host: example-service
        port:
          number: 8080
    timeout: 30s

Note: Use istioctl proxy-config to inspect the configuration of sidecars and verify that the virtual service is correctly applied.

Warning: Misconfigurations in virtual services can lead to traffic routing failures or unexpected behavior. Always validate changes in a test environment before applying to production.

11. Implementing Virtual Service Delegation

Virtual service delegation allows you to define a virtual service that delegates traffic to other virtual services or to specific destinations. This is useful for organizing complex routing rules and promoting reusability.

Property	Description	Example
delegate	Specifies the name of the virtual service to delegate to.	`delegate: "user-service"`
routes	Defines the specific routes within the delegated service to use.	`routes: ["v1", "v2"]`

Example: Delegating to a User Service

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: user-service-delegation
spec:
  hosts:
  - user-service
  delegate:
    name: user-service-virtual

Note: The delegated virtual service must exist in the same namespace or be accessible via cross-namespace references.

12. Managing Cross-Namespace Virtual Services

Property	Description	Values	Notes
name	Unique identifier for the virtual service	`cross-namespace-vs`	Must be unique within the namespace
namespace	Namespace where the virtual service is defined	`istio-system`	Can reference services in other namespaces
hosts	Hostnames to which traffic is routed	`[service-a.namespace-a.svc.cluster.local]`	Can include wildcard patterns
http	HTTP route rules for traffic routing	`[{route: [{destination: {host: service-b.namespace-b.svc.cluster.local}}]}]`	Supports weighted routing and fault injection

Example: Cross-Namespace Virtual Service Definition

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: cross-namespace-vs
  namespace: istio-system
spec:
  hosts:
  - service-a.namespace-a.svc.cluster.local
  http:
  - route:
    - destination:
        host: service-b.namespace-b.svc.cluster.local
        port:
          number: 80

Note: The hosts field can reference services in different namespaces, provided the necessary permissions and cross-namespace access are configured.

Warning: Ensure that the DestinationRule in the target namespace allows traffic to the referenced service.