Skip to content

Latest commit

 

History

History
198 lines (128 loc) · 9.15 KB

hostrule.md

File metadata and controls

198 lines (128 loc) · 9.15 KB
Raw

HostRule

HostRule CRD is primarily targeted to be used by the Operator. This CRD can be used to express additional virtual host properties. The virtual host FQDN is matched from either Kubernetes Ingress or OpenShift Route based objects.

A sample HostRule CRD looks like this:

apiVersion: ako.vmware.com/v1alpha1
kind: HostRule
metadata:
  name: my-host-rule
  namespace: red
spec:
  virtualhost:
    fqdn: foo.region1.com # mandatory
    enableVirtualHost: true
    tls: # optional
      sslKeyCertificate:
        name: avi-ssl-key-cert
        type: ref
      sslProfile: avi-ssl-profile
      termination: edge
    gslb:
      fqdn: foo.com
    httpPolicy: 
      policySets:
      - avi-secure-policy-ref
      overwrite: false
    datascripts:
    - avi-datascript-redirect-app1
    wafPolicy: avi-waf-policy
    applicationProfile: avi-app-ref
    analyticsProfile: avi-analytics-ref
    errorPageProfile: avi-errorpage-ref

Specific usage of HostRule CRD

HostRule CRD can be created in a given namespace where the operator desires to have more control. The section below walks over the details and associated rules of using each field of the HostRule CRD.

Enable/Disable Virtual Host

HostRule CRD can be used to enable/disable corresponding virtual services created by AKO on Avi. This removes any virtual host related configuration from the data plane (Avi service engines) in addition to disabling traffic on the virtual host/fqdn.

    enableVirtualHost: false

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The default value is true.

Express HTTP policy object refs.

HostRule CRD can be used to express httppolicyset references. These httppolicyset objects should be pre-created in the Avi controller.

    httpPolicy: 
      policySets:
      - avi-secure-policy-ref
      overwrite: false

The httppolicyset currently is only applicable for secure FQDNs and cannot be applied for insecure routes. The order of evaluation of the httpolicyset rules is in the same order they appear in the CRD definition. The list of httpolicyset rules are always intepreted as an AND operation.

AKO currently uses httppolicyset objects on the SNI virtualservices to route traffic based on host/path matches. These rules are always at a lower index than the httppolicyset objects specified in the CRD object. In case, a user would want to overwrite all httppolicyset objects on a SNI virtualservice with the ones specified in the HostRule CRD, the overwrite flag can be set to true. The default value for overwrite is false.

Express WAF policy object refs.

HostRule CRD can be used to express WAF policy references. The WAF policy object should have been created in the Avi Controller prior to this CRD creation.

    wafPolicy: avi-waf-policy

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. WAF policies are useful when deep layer 7 packet filtering is required.

Express custom application profiles

HostRule CRD can be used to express application profile references. The application profile reference should have been created in the Avi Controller prior to this CRD creation. The application profile should be of TYPE of APPLICATION_PROFILE_TYPE_HTTP.

    applicationProfile: avi-app-ref

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The application profiles can be used for various HTTP/HTTP2 protocol settings.

Express custom analytics profiles

HostRule CRD can be used to express analytics profile references. The analytics profile reference should have been created in the Avi Controller prior to this CRD creation.

    analyticsProfile: avi-analytics-ref

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The analytics profiles can be used for various Network/HTTP/Healthscore analytics settings, log processing etc.

Express custom error page profiles

HostRule CRD can be used to express error page profile references. The error page profile reference should have been created in the Avi Controller prior to this CRD creation.

    errorPageProfile: avi-errorpage-ref

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The error page profiles can be used to send a custom error page to the client generated by the proxy.

Express datascripts

HostRule CRD can be used to express error datascript references. The datascript references should have been created in the Avi Controller prior to this CRD creation.

    datascripts:
    - avi-datascript-redirect-app1

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The datascripts can be used to apply custom scripts to data traffic. The order of evaluation of the datascripts is in the same order they appear in the CRD definition.

Express TLS configuration

If the kubernetes operator wants to control the TLS termination from a privileged namespace then the HostRule CRD can be created in such a namespace.

    tls:
      sslKeyCertificate:
        name: avi-ssl-key-cert
        type: ref
      sslProfile: avi-ssl-profile
      termination: edge

The name field refers to an Avi object if type specifies the value as ref. Alternatively in the future, we will be able to support a kubernetes Secret as a type where the sslkeyandcertificate object can be created by AKO using the Secret.

sslProfile, additionally, can be used to determine the set of SSL versions and ciphers to accept for SSL/TLS terminated connections. If the sslProfile is not defined, AKO defaults to the sslProfile System-Standard-PFS defined in Avi.

Currently only one of type of termination is supported viz. edge. In the future, we should be able to support other types of termination policies.

Configure GSLB FQDN

A GSLB FQDN can be specified within the HostRule CRD. This is only used if AKO is used with AMKO and not otherwise.

    gslb:
      fqdn: foo.com

This additional FQDN inherits all the properties of the root FQDN specified under the the virtualHost section. Use this flag if you would want traffic with a GSLB FQDN to get routed to a site local FQDN. For example, in the above CRD, the client request from a GSLB DNS will arrive with the host header as foo.com to the VIP hosting foo.region1.com in region1. This CRD property would ensure that the request is routed appropriately to the backend service of foo.region1.com

This knob is currently only supported with the SNI model and not with Enhanced Virtual Hosting model.

Status Messages

The status messages are used to give instanteneous feedback to the users about the reference objects specified in the HostRule CRD.

Following are some of the sample status messages:

Accepted HostRule object
$ kubectl get hr
NAME                 HOST                  STATUS     AGE
secure-waf-policy    foo.avi.internal      Accepted   3d3h

A HostRule is accepted only when all the reference objects specified inside it exist in the Avi Controller.

A Rejected HostRule object
$ kubectl get hr
NAME                     HOST                  STATUS     AGE
secure-waf-policy-alt    foo.avi.internal      Rejected   2d23h

The detailed rejection reason can be obtained from the status:

status:
error: duplicate fqdn foo.avi.internal found in default/secure-waf-policy-alt
status: Rejected

Conditions and Caveats

Converting insecure FQDNs to secure

The HostRule CRD can be used to convert an insecure host fqdn to a secure one. This is done by specifying a tls section in the CRD object. Whatever sslKeyCertificate is provided for the FQDN, will override all sslkeyandcertificates generated for the FQDN. This maybe useful if:

  • The operator wants to convert an insecure ingress FQDN to secure.

  • The operator wants to override any existing secrets for a given host fqdn and define tls termination semantics.

Certificate precedence

If the ingress object specifies a Secret for SNI termination and the HostRule CRD also specifies a sslKeyCertificate for the same virtualhost then the sslkeycertificate in the HostRule CRD will take precedence over the Secret object associated with the Ingress.

HostRule deletion

If a HostRule is deleted, all the settings for the FQDNs are withdrawn from the Avi controller.

HostRule admission

A HostRule CRD is only admitted if all the objects referenced in it, exist in the Avi Controller. If after admission the object references are deleted out-of-band, then AKO does not re-validate the associated HostRule CRD objects. The user needs to manually edit or delete the object for new changes to take effect.

Duplicate FQDN rules

Two HostRule CRDs cannot be used for the same FQDN information across namespaces. If AKO finds a duplicate FQDN in more than one HostRules, AKO honors the first HostRule that gets created and rejects the others. In case of AKO reboots, the CRD that gets honored might not be the same as the one honored earlier.