You are looking at the documentation of a prior release. To read the documentation of the latest release, please visit here.
New to Voyager? Please start here.
Voyager operator can be installed via a script or as a Helm chart.
To install Voyager in your Kubernetes cluster, pick the appropriate cluster provider and run the following command:
# provider=acs
# provider=aks
# provider=aws
# provider=azure
# provider=baremetal
# provider=gce
# provider=gke
# provider=minikube
# provider=openstack
# provider=metallb
# provider=digitalocean
# provider=linode
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider
After successful installation, you should have a voyager-operator-*** pod running in the kube-system namespace.
$ kubectl get pods -n kube-system | grep voyager-operator
voyager-operator-846d47f489-jrb58 1/1 Running 0 48s
The installer script and associated yaml files can be found in the /hack/deploy folder. To see the full list of flags available to installer, use the -h flag.
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh | bash -s -- -h
voyager.sh - install voyager operator
voyager.sh [options]
options:
-h, --help show brief help
-n, --namespace=NAMESPACE specify namespace (default: kube-system)
-p, --provider=PROVIDER specify a cloud provider
--rbac create RBAC roles and bindings (default: true)
--docker-registry docker registry used to pull voyager images (default: appscode)
--haproxy-image-tag tag of Docker image containing HAProxy binary (default: 1.8.12-7.3.0-alpine)
--image-pull-secret name of secret used to pull voyager operator images
--restrict-to-namespace restrict voyager to its own namespace
--run-on-master run voyager operator on master
--enable-validating-webhook enable/disable validating webhooks for voyager CRDs
--template-cfgmap=CONFIGMAP name of configmap with custom templates
--enable-status-subresource If enabled, uses status sub resource for Voyager crds
--enable-analytics send usage events to Google Analytics (default: true)
--uninstall uninstall voyager
--purge purges Voyager crd objects and crds
If you would like to run Voyager operator pod in master instances, pass the --run-on-master flag:
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider --run-on-master [--rbac]
Voyager operator will be installed in a kube-system namespace by default. If you would like to run Voyager operator pod in voyager namespace, pass the --namespace=voyager flag:
$ kubectl create namespace voyager
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider --namespace=voyager [--run-on-master] [--rbac]
By default, Voyager operator will watch Ingress objects in any namespace. If you would like to restrict Voyager to Ingress and Services in its own namespace, pass the --restrict-to-namespace flag:
$ kubectl create namespace voyager
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider --namespace=voyager --restrict-to-namespace [--run-on-master] [--rbac]
If you are using a private Docker registry, you need to pull the following 2 docker images:
To pass the address of your private registry and optionally a image pull secret use flags --docker-registry and --image-pull-secret respectively.
$ kubectl create namespace voyager
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider --docker-registry=MY_REGISTRY [--image-pull-secret=SECRET_NAME] [--rbac]
By default, Voyager uses Alpine based HAProxy image (1.8.12-7.3.0-alpine). But you can also Debian based image for HAProxy by setting –haproxy-image-tag=1.8.12-7.3.0 flag.
Voyager implements a validating admission webhook to validate Voyager CRDs. This is enabled by default for Kubernetes 1.9.0 or later releases. To disable this feature, pass the --enable-validating-webhook=false flag.
$ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/7.3.0/hack/deploy/voyager.sh \
| bash -s -- --provider=$provider --enable-validating-webhook [--rbac]
Voyager 7.3.0 or later releases can use status sub resource for CustomResourceDefintions. This is enabled by default for Kubernetes 1.11.0 or later releases. To disable this feature, pass the --enable-status-subresource=false flag.
To use custom templates to render HAProxy configuration, visit here.
Voyager can be installed via Helm 2.9.x or later versions using the chart from AppsCode Charts Repository. To install the chart with the release name my-release:
$ helm repo add appscode https://charts.appscode.com/stable/
$ helm repo update
$ helm search appscode/voyager
NAME CHART VERSION APP VERSION DESCRIPTION
appscode/voyager 7.3.0 7.3.0 Voyager by AppsCode - Secure HAProxy Ingress Controller...
# Kubernetes 1.8.x
$ helm install appscode/voyager --name voyager-operator --version 7.3.0 \
--namespace kube-system \
--set cloudProvider=$provider
# Kubernetes 1.9.x - 1.10.x
$ helm install appscode/voyager --name voyager-operator --version 7.3.0 \
--namespace kube-system \
--set cloudProvider=$provider \
--set apiserver.ca="$(onessl get kube-ca)" \
--set apiserver.enableValidatingWebhook=true
# Kubernetes 1.11.x or later
$ helm install appscode/voyager --name voyager-operator --version 7.3.0 \
--namespace kube-system \
--set cloudProvider=$provider \
--set apiserver.ca="$(onessl get kube-ca)" \
--set apiserver.enableValidatingWebhook=true \
--set apiserver.enableStatusSubresource=true
To install onessl, run the following commands:
# Mac OSX amd64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.3.0/onessl-darwin-amd64 \
&& chmod +x onessl \
&& sudo mv onessl /usr/local/bin/
# Linux amd64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.3.0/onessl-linux-amd64 \
&& chmod +x onessl \
&& sudo mv onessl /usr/local/bin/
# Linux arm64:
curl -fsSL -o onessl https://github.com/kubepack/onessl/releases/download/0.3.0/onessl-linux-arm64 \
&& chmod +x onessl \
&& sudo mv onessl /usr/local/bin/
To see the detailed configuration options, visit here.
If you are installing Voyager on a GKE cluster, you will need cluster admin permissions to install Voyager operator. Run the following command to grant admin permision to the cluster.
# get current google identity
$ gcloud info | grep Account
Account: [user@example.org]
$ kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=user@example.org
Voyager can be used in minikube using --provider=minikube. In Minikube, a LoadBalancer type ingress will only assigned a NodePort.
Voyager works great in baremetal cluster. To install, set --provider=baremetal. In baremetal cluster, LoadBalancer type ingress in not supported. You can use NodePort, HostPort or Internal ingress objects.
Follow the instructions for installing on baremetal cluster but specify metallb as provider. Then install MetalLB following the instructions here. Now, you can use LoadBalancer type ingress in baremetal clusters.
To use LoadBalancer type ingress in DigitalOcean cluster, install Kubernetes cloud controller manager for DigitalOcean. Otherwise set cloud provider to barematal.
To use LoadBalancer type ingress in Linode cluster, install Kubernetes cloud controller manager for Linode. Otherwise set cloud provider to barematal.
To check if Voyager operator pods have started, run the following command:
$ kubectl get pods --all-namespaces -l app=voyager --watch
Once the operator pods are running, you can cancel the above command by typing Ctrl+C.
Now, to confirm CRD groups have been registered by the operator, run the following command:
$ kubectl get crd -l app=voyager
Now, you are ready to create your first ingress using Voyager.
Voyager creates two CRDs: Ingress and Certificate. Voyager installer will create 2 user facing cluster roles:
| ClusterRole | Aggregates To | Desription |
|---|---|---|
| appscode:voyager:edit | admin, edit | Allows edit access to Voyager CRDs, intended to be granted within a namespace using a RoleBinding. |
| appscode:voyager:view | view | Allows read-only access to Voyager CRDs, intended to be granted within a namespace using a RoleBinding. |
These user facing roles supports ClusterRole Aggregation feature in Kubernetes 1.9 or later clusters.
Since Voyager uses its own TPR/CRD, you need to use full resource kind to find it with kubectl.
# List all voyager ingress
$ kubectl get ingress.voyager.appscode.com --all-namespaces
# List voyager ingress for a namespace
$ kubectl get ingress.voyager.appscode.com -n <namespace>
# Get Ingress YAML
$ kubectl get ingress.voyager.appscode.com -n <namespace> <ingress-name> -o yaml
# Describe Ingress. Very useful to debug problems.
$ kubectl describe ingress.voyager.appscode.com -n <namespace> <ingress-name>
To detect Voyager version, exec into the operator pod and run voyager version command.
$ POD_NAMESPACE=kube-system
$ POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=voyager -o jsonpath={.items[0].metadata.name})
$ kubectl exec -it $POD_NAME -n $POD_NAMESPACE voyager version
Version = 7.3.0
VersionStrategy = tag
Os = alpine
Arch = amd64
CommitHash = ab0b38d8f5d5b4b4508768a594a9d98f2c76abd8
GitBranch = release-4.0
GitTag = 7.3.0
CommitTimestamp = 2017-10-08T12:45:26