Skip to content

Commit dc95a97

Browse files
teeohhemteeohhem
authored
chore: update readme with ingress info (#54)
1 parent 4b6c5f8 commit dc95a97

File tree

1 file changed

+170
-68
lines changed

1 file changed

+170
-68
lines changed

‎README.md‎

Lines changed: 170 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Welcome to the official HyperDX Helm charts repository. This guide provides inst
1818
- [API Key Setup](#api-key-setup)
1919
- [Task Configuration](#task-configuration)
2020
- [Using Secrets](#using-secrets)
21+
- [Ingress Setup](#ingress-setup)
2122
- [Operations](#operations)
2223
- [Upgrading](#upgrading-the-chart)
2324
- [Uninstalling](#uninstalling-hyperdx)
@@ -108,36 +109,7 @@ hyperdx:
108109
109110
#### Configuring Ingress for OTEL Collector
110111
111-
If you need to expose your OTEL collector endpoints through ingress, you can use the additional ingresses configuration. The example below uses a regex pattern to capture all OTLP endpoints (traces, metrics, and logs) in a single path rule:
112-
113-
```yaml
114-
hyperdx:
115-
ingress:
116-
enabled: true
117-
additionalIngresses:
118-
- name: otel-collector
119-
annotations:
120-
nginx.ingress.kubernetes.io/ssl-redirect: "false"
121-
nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
122-
nginx.ingress.kubernetes.io/use-regex: "true"
123-
ingressClassName: nginx
124-
hosts:
125-
- host: collector.yourdomain.com
126-
paths:
127-
- path: /v1/(traces|metrics|logs)
128-
pathType: Prefix
129-
port: 4318
130-
tls:
131-
- hosts:
132-
- collector.yourdomain.com
133-
secretName: collector-tls
134-
```
135-
136-
This configuration creates a separate ingress resource for the OTEL collector endpoints, allowing you to:
137-
- Use a different domain for collector traffic
138-
- Configure specific TLS settings
139-
- Apply custom annotations for the collector ingress
140-
- Route all telemetry signals through a single regex-based path rule
112+
For instructions on exposing your OTEL collector endpoints via ingress (including example configuration and best practices), see the [OTEL Collector Ingress](#otel-collector-ingress) section in the [Ingress Setup](#ingress-setup) chapter above.
141113
142114
### Minimal Deployment
143115
@@ -263,6 +235,173 @@ By default, there is one task in the chart setup as a cronjob, responsible for c
263235
| `tasks.checkAlerts.schedule` | Cron schedule for the check-alerts task | `*/1 * * * *` |
264236
| `tasks.checkAlerts.resources` | Resource requests and limits for the check-alerts task | See `values.yaml` |
265237

238+
## Ingress Setup
239+
240+
- [General Ingress Setup](#general-ingress-setup)
241+
- [OTEL Collector Ingress](#otel-collector-ingress)
242+
- [Troubleshooting Ingress](#troubleshooting-ingress)
243+
244+
### General Ingress Setup
245+
246+
To expose the HyperDX UI and API via a domain name, enable ingress in your `values.yaml`:
247+
248+
```yaml
249+
hyperdx:
250+
ingress:
251+
enabled: true
252+
host: "hyperdx.yourdomain.com" # Set this to your desired domain
253+
```
254+
255+
#### Configuring `ingress.host` and `hyperdx.appUrl`
256+
257+
- **`hyperdx.ingress.host`**: Set to the domain you want to use for accessing HyperDX (e.g., `hyperdx.yourdomain.com`).
258+
- **`hyperdx.appUrl`**: Should match the ingress host and include the protocol (e.g., `https://hyperdx.yourdomain.com`).
259+
260+
**Example:**
261+
```yaml
262+
hyperdx:
263+
appUrl: "https://hyperdx.yourdomain.com"
264+
ingress:
265+
enabled: true
266+
host: "hyperdx.yourdomain.com"
267+
```
268+
269+
This ensures that all generated links, cookies, and redirects work correctly.
270+
271+
#### Enabling TLS (HTTPS)
272+
273+
To secure your deployment with HTTPS, enable TLS in your ingress configuration:
274+
275+
```yaml
276+
hyperdx:
277+
ingress:
278+
enabled: true
279+
host: "hyperdx.yourdomain.com"
280+
tls:
281+
enabled: true
282+
tlsSecretName: "hyperdx-tls" # Name of the Kubernetes TLS secret
283+
```
284+
285+
- Create a Kubernetes TLS secret with your certificate and key:
286+
```sh
287+
kubectl create secret tls hyperdx-tls \
288+
--cert=path/to/tls.crt \
289+
--key=path/to/tls.key
290+
```
291+
- The ingress will reference this secret to terminate HTTPS connections.
292+
293+
#### Example Minimal Ingress YAML
294+
295+
```yaml
296+
apiVersion: networking.k8s.io/v1
297+
kind: Ingress
298+
metadata:
299+
name: hyperdx-app-ingress
300+
annotations:
301+
nginx.ingress.kubernetes.io/rewrite-target: /$1
302+
nginx.ingress.kubernetes.io/use-regex: "true"
303+
spec:
304+
ingressClassName: nginx
305+
rules:
306+
- host: hyperdx.yourdomain.com
307+
http:
308+
paths:
309+
- path: /(.*)
310+
pathType: ImplementationSpecific
311+
backend:
312+
service:
313+
name: <service-name>
314+
port:
315+
number: 3000
316+
tls:
317+
- hosts:
318+
- hyperdx.yourdomain.com
319+
secretName: hyperdx-tls
320+
```
321+
322+
#### Common Pitfalls
323+
324+
- **Path and Rewrite Configuration:**
325+
- For Next.js and other SPAs, always use a regex path and rewrite annotation as shown above. Do not use just `path: /` without a rewrite, as this will break static asset serving.
326+
- **Mismatched `appUrl` and `ingress.host`:**
327+
- If these do not match, you may experience issues with cookies, redirects, and asset loading.
328+
- **TLS Misconfiguration:**
329+
- Ensure your TLS secret is valid and referenced correctly in the ingress.
330+
- Browsers may block insecure content if you access the app over HTTP when TLS is enabled.
331+
- **Ingress Controller Version:**
332+
- Some features (like regex paths and rewrites) require recent versions of nginx ingress controller. Check your version with:
333+
```sh
334+
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"
335+
```
336+
337+
---
338+
339+
### OTEL Collector Ingress
340+
341+
If you need to expose your OTEL collector endpoints (for traces, metrics, logs) through ingress, you can use the `additionalIngresses` configuration. This is useful for organizations that want to send telemetry data from outside the cluster or use a custom domain for the collector.
342+
343+
**Example configuration:**
344+
345+
```yaml
346+
hyperdx:
347+
ingress:
348+
enabled: true
349+
additionalIngresses:
350+
- name: otel-collector
351+
annotations:
352+
nginx.ingress.kubernetes.io/ssl-redirect: "false"
353+
nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
354+
nginx.ingress.kubernetes.io/use-regex: "true"
355+
ingressClassName: nginx
356+
hosts:
357+
- host: collector.yourdomain.com
358+
paths:
359+
- path: /v1/(traces|metrics|logs)
360+
pathType: Prefix
361+
port: 4318
362+
tls:
363+
- hosts:
364+
- collector.yourdomain.com
365+
secretName: collector-tls
366+
```
367+
368+
- This creates a separate ingress resource for the OTEL collector endpoints.
369+
- You can use a different domain, configure specific TLS settings, and apply custom annotations for the collector ingress.
370+
- The regex path rule allows you to route all OTLP signals (traces, metrics, logs) through a single rule.
371+
372+
**Note:**
373+
- If you do not need to expose the OTEL collector externally, you can skip this section.
374+
- For most users, the general ingress setup is sufficient.
375+
376+
---
377+
378+
### Troubleshooting Ingress
379+
380+
- **Check Ingress Resource:**
381+
```sh
382+
kubectl get ingress -A
383+
kubectl describe ingress <ingress-name>
384+
```
385+
- **Check Pod Logs:**
386+
```sh
387+
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
388+
```
389+
- **Test Asset URLs:**
390+
Use `curl` to verify static assets are served as JS, not HTML:
391+
```sh
392+
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
393+
# Should return Content-Type: application/javascript
394+
```
395+
- **Browser DevTools:**
396+
- Check the Network tab for 404s or assets returning HTML instead of JS.
397+
- Look for errors like "Unexpected token <" in the console (indicates HTML returned for JS).
398+
- **Check for Path Rewrites:**
399+
- Ensure the ingress is not stripping or incorrectly rewriting asset paths.
400+
- **Clear Browser and CDN Cache:**
401+
- After changes, clear your browser cache and any CDN/proxy cache to avoid stale assets.
402+
403+
---
404+
266405
## Operations
267406

268407
### Upgrading the Chart
@@ -392,41 +531,4 @@ For HTTP-only deployments (development/testing), some browsers may show crypto A
392531

393532
```sh
394533
kubectl logs -l app.kubernetes.io/name=hdx-oss-v2
395-
```
396-
397-
### OTEL Collector OpAMP Connection Issues
398-
399-
If you see connection refused errors in OTEL collector logs:
400-
401-
```sh
402-
# Check OTEL collector logs
403-
kubectl logs -l app=otel-collector
404-
405-
# Verify service DNS resolution
406-
kubectl exec -it deployment/my-hyperdx-hdx-oss-v2-otel-collector -- nslookup my-hyperdx-hdx-oss-v2-app
407-
```
408-
409-
### Debugging a Failed Install
410-
411-
```sh
412-
helm install my-hyperdx hyperdx/hdx-oss-v2 --debug --dry-run
413-
```
414-
415-
### Verifying Deployment
416-
417-
```sh
418-
kubectl get pods -l app.kubernetes.io/name=hdx-oss-v2
419-
```
420-
421-
For more details, refer to the [Helm documentation](https://helm.sh/docs/) or open an issue in this repository.
422-
423-
---
424-
425-
## Contributing
426-
427-
We welcome contributions! Please open an issue or submit a pull request if you have improvements or feature requests.
428-
429-
## License
430-
431-
This project is licensed under the [MIT License](LICENSE).
432-
534+
```

0 commit comments

Comments
 (0)