Skip to content

Document automatic tunnel Ingress generation for Inlets Uplink #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Document automatic tunnel Ingress generation for Inlets Uplink #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
73ea0b7
Update uplink Helm configuration reference
welteki Feb 17, 2025
4240ba1
Update uplink docs for automatic tunnel Ingress generation
welteki Feb 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 38 additions & 63 deletions docs/uplink/expose-tunnels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

Any tunnelled service can be accessed directly from within the cluster using a ClusterIP Service and does not need to be exposed to the public Internet in order to be used by a SaaS product.

Each inlets uplink tunnel is provisioned with a ClusterIP service that you can access internally within the cluster. The same service can be used to expose the tunnel to the public Internet using an Ingress resource. This approach is recommended for new users for dozens of tunnels.
Each inlets uplink tunnel is provisioned with a ClusterIP service that you can access internally within the cluster. The same service can be used to expose the tunnel to the public Internet using an Ingress resource. The uplink operator can be configured to automatically generate ingress resources for tunnels. This approach is recommended for new users for dozens of tunnels.

[![Each tunnel's data-plane is exposed via a separate Ingress and Certificate](/images/uplink/ingress-per-data-plane.png)](/images/uplink/ingress-per-data-plane.png)
> Each tunnel's data-plane is exposed via a separate Ingress and Certificate
Expand Down Expand Up @@ -35,6 +35,8 @@ Both tunnels can be created with `kubectl` using the Custom Resource Definition,
licenseRef:
name: inlets-uplink-license
namespace: tunnels
ingressDomains:
- grafana.example.com
---
apiVersion: uplink.inlets.dev/v1alpha1
kind: Tunnel
Expand All @@ -45,106 +47,79 @@ Both tunnels can be created with `kubectl` using the Custom Resource Definition,
licenseRef:
name: inlets-uplink-license
namespace: tunnels
ingressDomains:
- openfaas.example.com
EOF
```

=== "cli"

```bash
$ inlets-pro tunnel create grafana
$ inlets-pro tunnel create grafana \
--ingress grafana.example.com
Created tunnel openfaas. OK.

$ inlets-pro tunnel create openfaas
$ inlets-pro tunnel create openfaas \
--ingress openfaas.example.com
Created tunnel openfaas. OK.
```

Follow the instruction for Kubernetes Ingress or Istio depending on how you deployed inlets uplink.

## Expose the Tunnel with Ingress

1. Create a new certificate Issuer for tunnels:
1. Create a new certificate Issuer for tunnels.

```bash
export EMAIL="[email protected]"

cat > tunnel-issuer-prod.yaml <<EOF
cat > letsencrypt-prod-tunnels <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
kind: ClusterIssuer
metadata:
name: tunnels-letsencrypt-prod
namespace: inlets
name: letsencrypt-prod-tunnels
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: $EMAIL
privateKeySecretRef:
name: tunnels-letsencrypt-prod
name: letsencrypt-prod-tunnels
solvers:
- http01:
ingress:
class: "nginx"
EOF
```

2. Create an ingress resource for the tunnel:
We are creating a `ClusterIssuer` that can be used to issue certificates for tunnels in multiple namespaces. If you don't want to use a cluster wide issuer it is also possible to define an `Issuer` with the same name in each individual tunnel namespace. This requires a lot more configuration and we would recommend to use the `ClusterIssuer` instead.

2. Update the Inlets Uplink deployment to enable automatic Ingress resource generation.

To enable ingress resource generation for tunnels you will need to update the Uplink deployment. Modify the `values.yaml` file you created during the [initial installation](/uplink/installation/) of Inlets Uplink.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: grafana-tunnel-ingress
namespace: tunnels
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/issuer: tunnels-letsencrypt-prod
spec:
rules:
- host: grafana.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: grafana
port:
number: 8000
tls:
- hosts:
- grafana.example.com
secretName: grafana-cert
operator:
tunnelIngress:
enabled: true
class: nginx
issuer:
name: letsencrypt-prod-tunnels
# Change the issuer type to Issuer of you chose to use an
# issuer per namespace instead of a ClusterIssuer.
type: ClusterIssuer
```

Note that the annotation `cert-manager.io/issuer` is used to reference the certificate issuer created in the first step.
Apply the updated values:

To setup ingress for multiple tunnels simply define multiple ingress resources. For example, you could create a second ingress resource for the openfaas tunnel:
```sh
helm upgrade --install inlets-uplink \
oci://ghcr.io/openfaasltd/inlets-uplink-provider \
--namespace inlets \
--values ./values.yaml
```

The Uplink operator will automatically generate new Ingress resources for all hosts included in the IngressDomain field of the Tunnel spec.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: openfaas-tunnel-ingress
namespace: tunnels
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/issuer: tunnels-letsencrypt-prod
spec:
rules:
- host: openfaas.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: openfaas
port:
number: 8000
tls:
- hosts:
- openfaas.example.com
secretName: openfaas-cert
```

## Expose the Tunnel with an Istio Ingress Gateway

Expand Down Expand Up @@ -327,7 +302,7 @@ spec:
solvers:
- dns01:
digitalocean:
tokenSecretRef:
apiTokenSecretRef:
name: digitalocean-dns
key: access-token
EOF
Expand Down
36 changes: 29 additions & 7 deletions docs/uplink/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,25 +301,47 @@ Overview of inlets-uplink parameters in `values.yaml`.
| Parameter | Description | Default |
| ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------ |
| `pullPolicy` | The a imagePullPolicy applied to inlets-uplink components. | `Always` |
| `operator.image` | Container image used for the uplink operator. | `ghcr.io/openfaasltd/uplink-operator:0.1.5` |
| `tunnelsNamespace` | Deployments, Services and Secrets will be created in this namespace. Leave blank for a cluster-wide scope, with tunnels in multiple namespaces. | `""` |
| `inletsVersion` | Inlets Pro release version for tunnel server Pods. | `0.9.39` |
| `ingress.issuer.name` | Name of cert-manager Issuer. | `letsencrypt-prod` |
| `ingress.issuer.enabled` | Create a cert-manager Issuer. Set to false if you wish to specify your own pre-existing object for each component. | `true` |
| `ingress.issuer.email` | Let's Encrypt email. Only used for certificate renewing notifications. | `""` |
| `ingress.class` | Ingress class for client router ingress. | `nginx` |
| `clientRouter.image` | Container image used for the client router. | `ghcr.io/openfaasltd/uplink-client-router:0.1.5` |
| `operator.image` | Container image used for the uplink operator. | `ghcr.io/openfaasltd/uplink-operator:0.4.32` |
| `operator.tunnelIngress.enabled` | Enable automatic generation of tunnel Ingress resources. | `false` |
| `operator.tunnelIngress.class` | Ingress class name to use for tunnel ingress resources. | `nginx` |
| `operator.tunnelIngress.annotations` | Additional annotations to be added to tunnel ingress resources. | `{}` |
| `operator.tunnelIngress.issuer.name`| Name of cert-manager Issuer used for tunnel ingress. | `letsencrypt-prod-tunnels` |
| `operator.tunnelIngress.issuer.type` | Issuer type used, ClusterIssuer or Issuer. | `ClusterIssuer` |
| `clientRouter.image` | Container image used for the client router. | `ghcr.io/openfaasltd/uplink-client-router:0.4.32` |
| `clientRouter.domain` | Domain name for inlets uplink. Customer tunnels will connect with a URI of: wss://uplink.example.com/namespace/tunnel. | `""` |
| `clientRouter.tls.ingress.enabled` | Enable ingress for the client router. | `enabled` |
| `clientRouter.tls.issuerName` | Name of cert-manager Issuer to be used for the client router. (Use to override global value set by `ingress.issuer.name`) | `""` |
| `clientRouter.tls.ingress.enabled` | Enable ingress for the client router. | `false` |
| `clientRouter.tls.ingress.annotations` | Annotations to be added to the client router ingress resource. | `{}` |
| `clientRouter.tls.istio.enabled` | Use an Istio Gateway for incoming traffic to the client router. | `false` |
| `clientRouter.service.type` | Client router service type | `ClusterIP` |
| `clientRouter.service.nodePort` | Client router service port for NodePort service type, assigned automatically when left empty. (only if clientRouter.service.type is set to "NodePort")| `nil` |
| `tunnelsNamespace` | Deployments, Services and Secrets will be created in this namespace. Leave blank for a cluster-wide scope, with tunnels in multiple namespaces. | `""` |
| `inletsVersion` | Inlets Pro release version for tunnel server Pods. | `0.9.12` |
| `dataRouter.enabled` | Enable data router. | `false` |
| `dataRouter.image` | Container image used for the data router. | `ghcr.io/openfaasltd/uplink-data-router:0.4.32` |
| `dataRouter.wildcardDomain` | Wildcard domain to use for tunnel ingress though the data router. (Leave out the asterix i.e. *.t.example.com would be: t.example.com) | `""` |
| `dataRouter.tls.issuerName` | Name of cert-manager Issuer to be used for the data router. (Use to override global value set by `ingress.issuer.name`) | `""` |
| `dataRouter.tls.ingress.enabled` | Enable ingress for the data router. | `false` |
| `dataRouter.tls.ingress.annotations` | Annotations to be added to the data router ingress resource. | `{}` |
| `dataRouter.service.type` | Data router service type | `ClusterIP` |
| `dataRouter.service.nodePort` | Data router service port for NodePort service type, assigned automatically when left empty. (only if dataRouter.service.type is set to "NodePort")| `nil` |
| `clientApi.enabled` | Enable tunnel management REST API. | `false` |
| `clientApi.image` | Container image used for the client API. | `ghcr.io/openfaasltd/uplink-api:0.1.5` |
| `clientApi.image` | Container image used for the client API. | `ghcr.io/openfaasltd/uplink-api:0.4.32` |
| `clientApi.domain` | Domain name for client api is exposed on. | `""` |
| `clientApi.issuerURl` | Set the issuer URL when using OAuth/OIDC tokens to authenticate the API. | `""` |
| `clientApi.audience` | OAuth audience when using OAuth/OIDC tokens to authenticate the API. | `""` |
| `clientApi.tls.issuerName` | Name of cert-manager Issuer to be used for the client api. (Use to override global value set by `ingress.issuer.name`) | `""` |
| `clientApi.tls.ingress.enabled` | Enable ingress for the client api. | `false` |
| `clientApi.tls.ingress.annotations` | Annotations to be added to the client api ingress resource. | `{}` |
| `clientApi.service.type` | Client api router service type | `ClusterIP` |
| `clientApi.service.nodePort` | Data router service port for NodePort service type, assigned automatically when left empty. (only if clientApi.service.type is set to "NodePort")| `nil` |
| `prometheus.create` | Create the Prometheus monitoring component. | `true` |
| `prometheus.resources` | Resource limits and requests for prometheus containers. | `{}` |
| `prometheus.image` | Container image used for prometheus. | `prom/prometheus:v2.40.1` |
| `prometheus.image` | Container image used for prometheus. | `prom/prometheus:v3.0.1` |
| `prometheus.service.type` | Prometheus service type | `ClusterIP` |
| `prometheus.service.nodePort` | Prometheus service port for NodePort service type, assigned automatically when left empty. (only if prometheus.service.type is set to "NodePort")| `nil` |
| `nodeSelector` | Node labels for pod assignment. | `{}` |
Expand Down