Tunnel based ingress controller for Kubernetes

Implements a Kubernetes ingress controller using tunnels to connect a Web Relay managed URL (https://yoursubdomain.webrelay.io) to a Kubernetes service based on ingress resources. Single ingress controller can manage multiple tunnels and route to multiple namespaces.

Deployment files and issue tracker is available on GitHub:

https://github.com/webrelay/ingress

Have you ever created a Kubernetes deployment and then spent a considerable amount of time just thinking about how to actually connect to the application?

Configuring load balancers on every cloud requires slightly different resources and settings. Web Relay ingress changes that; every cloud is equal, even the one on your laptop. It opens a reverse tunnel to expose your services. No public IP or external load balancer is required. Therefore, Web Relay ingress controller is a perfect tool for testing, developing and demoing your Kubernetes applications.

This guide covers Web Relay ingress controller installation steps as well as an example ingress resource file for your application to be exposed through Web Relay tunnel.

If you have any questions feel free to contact us [email protected].

Installation instructions can be found here.

Or you can also use Sunstone (after creating your token key and secret here):

kubectl apply -f \
  https://sunstone.dev/webrelay-ingress?key=YOUR_KEY&secret=YOUR_SECRET&relay_name=webrelay-ingress

In order for your application to be exposed, an ingress resource has to be created that defines relationships between virtual hosts (tunnel public endpoints) and internal services (names and their ports). Feel free to read more about ingresses at Kubernetes documentation page.

If you are on a free plan, then you should create tunnels either through UI or via CLI before creating an ingress resource file as free plan doesn't have custom subdomains. Once you create a tunnel, use tunnel's hostname in your ingress.yaml.

Ingress controller will try to dynamically create tunnels if they are not present. Custom subdomains are available for all paid plans. However if you are on a free plan, you will have to create a tunnel first. If you wish to change or upgrade plan, please visit plans page.

Create an ingress resource with webrelay class. Replace host, serviceName and servicePort with your desired domain and services:

# ingress.yml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: webrelay # other ingress classes will be ignored
  name: relay-ingress
  namespace: default
spec:
  rules:
    - host: <your subdomain>.webrelay.io
      http:
        paths:
        - path: /
          backend:
            serviceName: <your service name>
            servicePort: <your service port>

Each virtual host rule will create a separate tunnel.

kubectl apply -f ingress.yml

After a few seconds, a tunnel should be configured and ready:

$ relay ingress ls
ID                                     NAME                                 HOST                BACKENDS             CRYPTO              AUTH                AGE
50bd538d-ab43-4003-a25e-097b6410a498   webrelay-ingress-kuard.webrelay.io   kuard.webrelay.io   default/kuard/8080   off                 -                   2 minutes

You can also see your current tunnels at: https://my.webhookrelay.com/tunnels.

Since free plan does not provide custom subdomains; users need to create a tunnel before defining an ingress resource file. So, the first step is to create
a tunnel that belongs to a group webrelay-ingress:

$ relay tunnel create --group webrelay-ingress mytunnel
oomdwdehm6l9oiilsm6trc.webrelay.io<---->http://127.0.0.1

Now, if you check your ingresses:

$ relay ingress ls
ID                                     NAME        HOST                                 BACKENDS   CRYPTO   AUTH   AGE
6c83e6dd-fbc5-41f1-a7af-76237b4602bf   mytunnel    oomdwdehm6l9oiilsm6twa.webrelay.io              off      -      2 minutes

And then the last step is to modify ingress host field to the newly acquired tunnel’s host:

# ingress.yml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: webrelay # other ingress classes will be ignored
  name: relay-ingress
  namespace: default
spec:
  rules:
    - host: oomdwdehm6l9oiilsm6twa.webrelay.io # <- host has to match tunnel host
      http:
        paths:
        - path: /
          backend:
            serviceName: <your service name>
            servicePort: <your service port>

After a few seconds tunnel should be updated with the ingress route rules and service will be accessible through the supplied host.

You can enable basic authentication for tunnel endpoints by adding these annotations:

webrelay.ingress.kubernetes.io/auth-type: "basic"
webrelay.ingress.kubernetes.io/auth-credentials: "your-username:secret-password"

Example ingress file:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: webrelay    
    webrelay.ingress.kubernetes.io/auth-type: "basic"
    webrelay.ingress.kubernetes.io/auth-credentials: "your-username:secret-password"
  name: relay-ingress
  namespace: default
spec:
  rules:
    - host: kuard.webrelay.io    
      http:
        paths:
        - path: /
          backend:
            serviceName: kuard
            servicePort: 8080

Ingress controller can connect to a non-default (EU) region if RELAY_REGION environment variable is supplied. To install ingress controller that will connect to a different region, use sunstone:

kubectl apply -f https://sunstone.dev/webrelay-ingress?key=YOUR_KEY&secret=YOUR_SECRET&relay_name=webrelay-ingress®ion=us-west

If you encounter any problems that the documentation does not address, send us an email

• Q: How is this different from a regular NGINX ingress?
  A: Regular NGINX or other ingress controllers require an external service/load balancer to point at them while Web Relay ingress controller doesn’t need any of that. A reverse tunnel is created from inside of your environment.
• Q: Why do I have to pre-create tunnels when I am on a free plan?
  A: Since free plan does not have custom subdomain names (where you choose your own host), ingress controller will not be able to create specified tunnels. Therefore, you need to create a tunnel first and once you know your randomly generated host, you can add it to the ingress resource file.
• Q: I want to use it with TCP based services (SSH, etc). How can I achieve this?
  A: At the moment underlying relayd tunneling agent only supports HTTP protocol. Support for TCP exists but it has not been released. Furthermore, ingress resources can only define HTTP services and are not meant for any other purpose.
• Q: Can I have my own custom domain name?
  A: Yes, just enter your domain name in the ‘host’ field when creating the tunnel. You will need to point your DNS C or A records at Webhook Relay public endpoint.