helm-charts/charts/zrok2/README.md.gotmpl at 04a85121b5d866271936f4d171a49031314d0437 · openziti/helm-charts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
<!-- README.md generated by helm-docs from README.md.gotmpl -->

{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

## Overview

This chart deploys the zrok2 controller and frontend as Kubernetes Deployments. For a
complete self-hosting walkthrough, see the
[Kubernetes self-hosting guide](https://docs.zrok.io/docs/self-hosting/kubernetes/).

### External Services

The chart references external services by connection string — no subcharts are included.
This avoids version lock-in and redundant deployments when you already run PostgreSQL,
RabbitMQ, or InfluxDB in your cluster.

| Service | Required | Purpose |
|---------|----------|---------|
| **Ziti controller** | Yes | Overlay network |
| **PostgreSQL** | No (SQLite3 fallback) | Production database |
| **RabbitMQ** | No | Metrics event pipeline |
| **InfluxDB** | No | Metrics storage |

When a dependency is not configured, the chart degrades gracefully:

| postgresql.host | rabbitmq.url | influxdb.url | Result |
|---|---|---|---|
| empty | empty | empty | Minimal: SQLite3 PVC, no metrics |
| set | empty | empty | Production DB, no metrics |
| set | set | set | Full production: PostgreSQL + metrics pipeline |
| empty | set | set | SQLite3 + metrics (dev/test only) |

## Requirements

### Add the OpenZiti Charts Repo to Helm

```bash
helm repo add openziti https://docs.openziti.io/helm-charts/
```

## Minimal Example with Traefik Ingress

This example does not configure TLS termination for the API or public shares, metrics, or limits. You must configure a
wildcard DNS record (A record) that resolves to the value of `ZROK2_DNS_ZONE`.

Use an `sslip.io` wildcard/zone like `zrok2.192.168.49.2.sslip.io` for testing and tiny scale deployments if you
want to avoid setting up DNS. This works with any IP address.

```bash
ZROK2_DNS_ZONE=zrok.example.com
ZITI_NAMESPACE=miniziti
ZITI_MGMT_API_HOST=ziti-controller-client.${ZITI_NAMESPACE}.svc.cluster.local
ZITI_PWD=$(kubectl -n "${ZITI_NAMESPACE}" get secrets "ziti-controller-admin-secret" \
    --output go-template='{{"{{"}}index .data "admin-password" | base64decode{{"}}"}}')

helm upgrade \
    --install \
    --namespace zrok2 --create-namespace \
    --values https://raw.githubusercontent.com/openziti/helm-charts/main/charts/zrok2/values-ingress-traefik.yaml \
    --set "ziti.advertisedHost=${ZITI_MGMT_API_HOST}" \
    --set "ziti.password=${ZITI_PWD}" \
    --set "ziti.ca_cert_configmap=ziti-controller1-ctrl-plane-cas" \
    --set "dnsZone=${ZROK2_DNS_ZONE}" \
    --set "controller.ingress.hosts[0]=zrok2.${ZROK2_DNS_ZONE}" \
    zrok2 openziti/zrok2
```

## TLS termination with Traefik

One way to terminate TLS with Traefik is to use Cert Manager. Cert Manager will issue a certificate, store it in the specified Secret, and configure the Ingress to use the certificate. This example shows the default behavior to use the Ingress host(s) as DNS SANs.

1. Install Cert Manager
1. Create a ClusterIssuer with a Let's Encrypt account and DNS challenge solver. Solving the DNS challenge is one way
    for Cert Manager to obtain a wildcard certificate which is necessary for zrok2 frontend's Ingress.
1. Set input values to annotate zrok2's Ingresses with the name of the ClusterIssuer and specify a TLS secret name.

    ```bash
    helm upgrade zrok2 \
        --set "controller.ingress.annotations=cert-manager.io/cluster-issuer: letsencrypt-prod" \
        --set "controller.ingress.tlsSecretName=zrok2-api-tls" \
        --set "frontend.ingress.annotations=cert-manager.io/cluster-issuer: letsencrypt-prod" \
        --set "frontend.ingress.tlsSecretName=zrok2-wildcard-tls" \
        openziti/zrok2
    ```

## Default account

The chart automatically creates a zrok2 account in the database. You can use the account token to enable a device environment with `zrok2 enable ${ZROK2_ENABLE_TOKEN}` and you can log in to the zrok2 console with the username and password.

Get the zrok2 account token:

```bash
kubectl -n zrok2 \
    get secrets zrok2-ziggy-account-token \
    -o go-template='{{`{{"\n"}}{{index .data "token" | base64decode }}{{"\n"}}`}}'
```

```text title="Output"

qEP0MNtA74T3

```

Get the zrok2 console login credentials:

```bash
kubectl -n zrok2 \
    get secrets zrok2-ziggy-account-password \
    -o go-template='{{`{{"\n"}}{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}`}}'
```

```text title="Output"

password: p7XWVyjHbMWazLc6PZveF2b8SB2wzxDD
username: ziggy@zrok.192.168.49.2.sslip.io

```

The zrok2 console URL depends on how you configure ingress. If you used the Traefik Ingress example, then you can query the URL with:

```bash
kubectl -n zrok2 get ingress zrok2
```

```text title="Output"
NAME    CLASS    HOSTS                              ADDRESS        PORTS   AGE
zrok2   traefik  zrok2.zrok.192.168.49.2.sslip.io   192.168.49.2   80      8m41s
```

## Values Reference

{{ template "chart.valuesTable" . }}

<!-- README.md generated by helm-docs from README.md.gotmpl -->