Voyager

Voyager is a HAProxy backed secure L7 and L4 ingress controller for Kubernetes developed by AppsCode. This can be used with any Kubernetes cloud providers including aws, gce, gke, azure, acs. This can also be used with bare metal Kubernetes clusters.

From here you can learn all about Voyager’s architecture and how to deploy and use Voyager.

• Concepts. Concepts explain some significant aspect of Voyager. This is where you can learn about what Voyager does and how it does it.
• Setup. The setup contains instructions for installing the Voyager in various cloud providers.
• Guides. Guides show you how to perform tasks with Voyager. These are organized under Ingress and Certificate.
• Reference. Detailed exhaustive lists of command-line options, configuration options, API definitions, and procedures.

Ingress

Voyager provides L7 and L4 load balancing using Kubernetes standard Ingress resource. This is built on top of the HAProxy to support high availability, sticky sessions, name and path-based virtual hosting among other features. The following diagram shows how voyager operator works. Voyager also provides a custom Ingress resource under voyager.appscode.com API group that extends the functionality of standard Ingress in a Kubernetes native way.

When Voyager is installed in a Kubernetes cluster, a pod named voyager-operator-*** starts running in Kube-system namespace by default. This operator pod watches for Kubernetes Ingress resources and Voyager’s own Ingress CRD. When an Ingress object is created, the Voyager operator creates 3 Kubernetes resources in the same namespace of the Ingress:

a Configmap named voyager-${ingress-name}: This contains the auto-generated HAProxy configuration under haproxy.cfg key.

a Deployment named voyager-${ingress-name}: This runs HAProxy pods that mount the above config map. Each pod has one container for HAProxy. This container also includes some additional binary to reload HAProxy when the respective config map updates. This also includes logic for mounting and updating SSL secrets referenced in the corresponding Ingress resource. HAProxy pods can also contain a side-car container for exporting Prometheus ready metrics if enabled.

a Service named voyager-${ingress-name}: This Kubernetes Service exposes the above HAProxy pods to the internet. The type of Service can be configured by the user via ingress.appscode.com/type annotation on the Ingress.

a Service named voyager-${ingress-name}-stats: This Kubernetes Service is used to expose Prometheus ready metrics for HAProxy pods. This service is always of type ClusterIP and only created if stats are enabled.

Certificate

Voyager can automagically provision and refresh SSL certificates issued from Let’s Encrypt using a custom Kubernetes Certificate resource.

• Provision free TLS certificates from Let’s Encrypt,
• Manage issued certificates using a Kubernetes Third Party Resource,
• Domain validation using ACME DNS-01 challenges,
• Support for multiple DNS providers,
• Auto Renew Certificates,
• Use issued Certificates with Ingress to Secure Communications.

Versioning Policy

There are 2 parts to versioning policy:

• Operator version: Voyager does not follow semver, rather the major version of operator points to the Kubernetes client-go version. You can verify this from the glide.yaml file. This means there might be breaking changes between point releases of the operator. This generally manifests as changed annotation keys or their meaning. Please always check the release notes for upgrade instructions.
• CRD version: appscode.com/v1beta1 is considered in beta. This means any change

Run Voyager with other Ingress controllers in the same cluster

voyager can be used to manager Ingress objects alongside another ingress controller. Voyager comes with its own CRD called Ingress under API version voyager.appscode.com/v1beta1. This CRD is not recognized by other ingress controllers that work with the Kubernetes official Ingress object under extensions/v1beta1 API version.

By default, Voyager will also manage Kubernetes Ingress objects under extensions/v1beta1 API version. Voyager can be configured to only handle default Kubernetes Ingress objects with ingress.class voyager. To do that, pass the flag --ingress-class=voyager in operator pod. After that

annotations:
kubernetes.io/ingress.class=voyager