Skip to content

Commit b585edd

Browse files
pratapalakshmipratapalakshmi
committed
Updated READMEs
1 parent 6108bb2 commit b585edd

1 file changed

Lines changed: 192 additions & 25 deletions

File tree

‎content/plane-ee.md‎

Lines changed: 192 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -27,35 +27,197 @@ If you plan to use Traefik as your ingress controller, install it before deployi
2727
2828
## Migrating the Ingress Controller
2929

30-
The chart selects between three ingress templates based on `ingress.ingressClass`:
31-
32-
| `ingressClass` value | Template rendered | Resource kind |
33-
| ----------------------------- | ---------------------------------- | -------------------------------------------- |
34-
| `traefik` (or starts with it) | `templates/ingress-traefik.yaml` | `traefik.io/v1alpha1 IngressRoute` |
35-
| `openshift` | `templates/ingress-openshift.yaml` | `route.openshift.io/v1 Route` (one per path) |
36-
| `nginx` | `templates/ingress.yaml` | `networking.k8s.io/v1 Ingress` |
37-
38-
> **Any other value renders no ingress at all**, silently. `templates/ingress.yaml` is
39-
> gated on `ingressClass` being exactly `nginx`, so `alb`, `haproxy`, `contour`,
40-
> `openshift-default` or a custom IngressClass name produce a successful-looking
41-
> install with nothing reachable. Use one of the three values above, or create the
42-
> Ingress yourself.
30+
The chart renders one of three ingress templates — nginx, Traefik or OpenShift.
31+
**Which one** is chosen by the *controller type*, kept separate from the *class
32+
name*, so a class name your controller happens to use (e.g. `nginx-new`) no longer
33+
has to double as the template selector.
34+
35+
`ingress.controller` selects the resource kind:
36+
37+
| `ingress.controller` value | Template rendered | Resource kind |
38+
| --------------------------------- | ---------------------------------- | -------------------------------------------- |
39+
| `traefik` (or starts with it) | `templates/ingress-traefik.yaml` | `traefik.io/v1alpha1 IngressRoute` |
40+
| `openshift` | `templates/ingress-openshift.yaml` | `route.openshift.io/v1 Route` (one per path) |
41+
| `nginx` | `templates/ingress-nginx.yaml` | `networking.k8s.io/v1 Ingress` |
42+
43+
> **nginx, Traefik and OpenShift are the supported configurations.** The value is
44+
> only a selector and is never written into a manifest; the class name comes from
45+
> `ingress.ingressClass` (`spec.ingressClassName`), which can be any string your
46+
> controller exposes. Any `controller` value other than `traefik*`/`openshift`
47+
> renders the same standard `Ingress` as `nginx` — that is how a class name like
48+
> `nginx-new` is served — but only the three above are tested.
4349
4450
> **No body-size limit on Routes.** `ingress.traefik.maxRequestBodyBytes` has no
4551
> OpenShift equivalent; HAProxy Routes cannot cap request bodies. Enforce upload
4652
> limits in the application or at a WAF/CDN in front of the router.
4753
48-
The default value is `"traefik"`. If you are switching to a standard ingress controller such as nginx, follow the migration steps below.
54+
#### If you leave `ingress.controller` empty
55+
56+
The selection falls back to `ingress.ingressClass`, and is **exactly** what it was
57+
before this value existed:
58+
59+
| `ingressClass` with no `controller` | Renders |
60+
| --------------------------------------- | ---------------------------- |
61+
| `traefik`, or anything starting with it | Traefik `IngressRoute` |
62+
| `openshift` | OpenShift `Route`s |
63+
| `nginx` | Standard `Ingress` |
64+
| **anything else** | **nothing at all, silently** |
65+
66+
> ⚠️ **Any class other than `nginx`, `openshift` or `traefik*` renders no ingress**
67+
> while `ingress.controller` is empty — `nginx-new`, `openshift-default`, a custom
68+
> `IngressClass` name or an empty string included. `helm install` succeeds and
69+
> nothing is reachable. **Set `ingress.controller: nginx`** to get a standard
70+
> `Ingress` carrying your class name, or `ingress.enabled: false` if you manage the
71+
> ingress yourself.
72+
73+
This no-op is kept on purpose rather than widened: an operator on such a class today
74+
gets no ingress from the chart and will have their own in place, so making the
75+
fallback render one would create a second, conflicting `<release>-ingress` on
76+
upgrade — or fail the upgrade outright if theirs shares that name. Opting in via
77+
`ingress.controller` keeps upgrades inert until you ask for the change.
78+
79+
The default is a Traefik `IngressRoute` (`ingressClass: traefik`, no `controller`).
80+
If you are switching to a standard ingress controller, follow the migration steps
81+
below.
82+
83+
### Configuration snippets
84+
85+
Every snippet below is the `ingress` block of your `values.yaml`. All of them also
86+
need `license.licenseDomain` set — no ingress of any kind renders without it:
87+
88+
```yaml
89+
license:
90+
licenseDomain: plane.example.com
91+
```
92+
93+
#### Already supported — no `ingress.controller` needed
94+
95+
These four worked before `ingress.controller` existed and are unchanged. Leave
96+
`controller` out entirely.
97+
98+
**1. Traefik `IngressRoute` — the chart default**
99+
100+
```yaml
101+
ingress:
102+
enabled: true
103+
ingressClass: 'traefik'
104+
traefik:
105+
maxRequestBodyBytes: 20971520 # 20 MiB upload cap
106+
entryPoints: [] # empty = derive from your ssl.* settings
107+
```
108+
109+
Renders `IngressRoute` + `Middleware`. Requires the Traefik CRDs. Any class
110+
starting with `traefik` works here (`traefik-v2`, `traefikee`, ...).
111+
112+
**2. Standard `Ingress` with ingress-nginx**
113+
114+
```yaml
115+
ingress:
116+
enabled: true
117+
ingressClass: 'nginx'
118+
ingress_annotations:
119+
nginx.ingress.kubernetes.io/proxy-body-size: '20m'
120+
nginx.ingress.kubernetes.io/proxy-buffer-size: '16k' # avoids 502 "too big header"
121+
```
122+
123+
Renders one `Ingress` with `ingressClassName: nginx`. The class must be exactly
124+
`nginx` for this to work without `controller`.
125+
126+
**3. OpenShift Route's**
127+
128+
```yaml
129+
ingress:
130+
enabled: true
131+
ingressClass: 'openshift'
132+
openshift:
133+
timeout: '300s' # router default is 30s and severs /live/ WebSockets
134+
termination: 'edge' # edge | reencrypt (passthrough cannot do path routing)
135+
insecureEdgeTerminationPolicy: 'Redirect'
136+
```
137+
138+
Renders one `Route` per path. See [`examples/values-openshift.yaml`](examples/values-openshift.yaml)
139+
for a complete OpenShift values file.
140+
141+
**4. No chart-managed ingress — bring your own**
142+
143+
```yaml
144+
ingress:
145+
enabled: false
146+
```
147+
148+
Renders nothing at all. Use this when you expose Plane through your own `Ingress`,
149+
`HTTPRoute`, `LoadBalancer` Service, Cloudflare Tunnel or service mesh. This is the
150+
right setting if you are managing the ingress yourself — do not rely on an
151+
unrecognised `ingressClass` to suppress it.
152+
153+
#### Newly possible — set `ingress.controller`
154+
155+
Each of these rendered **no ingress at all** before this change, because the class
156+
name was not one of the three the chart recognised. `controller` picks the resource
157+
kind; `ingressClass` is then used verbatim as `spec.ingressClassName`.
158+
159+
**5. Standard `Ingress` with a class name that is not `nginx`** — e.g. a second
160+
ingress-nginx install, or an nginx build that exposes its own `IngressClass`
161+
162+
```yaml
163+
ingress:
164+
enabled: true
165+
controller: 'nginx' # any value but traefik*/openshift selects the Ingress
166+
ingressClass: 'nginx-new' # whatever your controller actually exposes
167+
ingress_annotations:
168+
nginx.ingress.kubernetes.io/proxy-body-size: '20m'
169+
```
170+
171+
Renders one `Ingress` with `ingressClassName: nginx-new`.
172+
173+
**6. Traefik `IngressRoute` with a class name that is not `traefik*`**
174+
175+
```yaml
176+
ingress:
177+
enabled: true
178+
controller: 'traefik'
179+
ingressClass: 'internal-lb' # unused by the IngressRoute; kept for your own bookkeeping
180+
```
181+
182+
Renders `IngressRoute` + `Middleware`. Useful when your platform's naming convention
183+
does not allow a class called `traefik`.
184+
185+
**7. OpenShift Route's with a class name that is not `openshift`**
186+
187+
```yaml
188+
ingress:
189+
enabled: true
190+
controller: 'openshift'
191+
ingressClass: 'ocp-internal' # unused by Routes
192+
openshift:
193+
timeout: '300s'
194+
```
195+
196+
Renders one `Route` per path.
197+
198+
**8. OpenShift, letting the ingress-to-route controller convert a plain `Ingress`**
199+
200+
```yaml
201+
ingress:
202+
enabled: true
203+
controller: 'nginx' # emit a standard Ingress...
204+
ingressClass: 'openshift-default' # ...for OpenShift's router to convert
205+
```
206+
207+
Renders one `Ingress` with `ingressClassName: openshift-default`. Note this path gets
208+
**no** per-route HAProxy timeout, so `/live/` WebSockets are subject to the router's
209+
30s default — prefer snippet 3 or 9 unless you specifically need the conversion.
49210

50211
### Switching from Traefik to a standard Ingress controller (e.g. nginx)
51212

52213
1. **Install your target ingress controller** if it is not already running.
53214

54-
2. **Update `ingress.ingressClass`** in your `values.yaml`:
215+
2. **Set `ingress.controller` and `ingress.ingressClass`** in your `values.yaml`:
55216

56217
```yaml
57218
ingress:
58-
ingressClass: "nginx" # supported: nginx | traefik* | openshift
219+
controller: "nginx" # selects templates/ingress-nginx.yaml
220+
ingressClass: "nginx" # spec.ingressClassName — whichever class your controller exposes (e.g. "nginx-new")
59221
```
60222

61223
3. **Run `helm upgrade`**:
@@ -80,11 +242,12 @@ The default value is `"traefik"`. If you are switching to a standard ingress con
80242

81243
1. **Install Traefik** with CRD support enabled (see [Installing Traefik Ingress Controller](#installing-traefik-ingress-controller-optional) above).
82244

83-
2. **Update `ingress.ingressClass`**:
245+
2. **Set `ingress.controller`**:
84246

85247
```yaml
86248
ingress:
87-
ingressClass: "traefik"
249+
controller: "traefik"
250+
ingressClass: "traefik" # unused by the IngressRoute, kept for clarity
88251
```
89252

90253
3. **Run `helm upgrade`**. The old `Ingress` resource is orphaned — delete it:
@@ -97,11 +260,12 @@ The default value is `"traefik"`. If you are switching to a standard ingress con
97260

98261
| Value | Default | Effect |
99262
| ------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
100-
| `ingress.enabled` | `true` | Master switch — set to `false` to render neither template. |
101-
| `ingress.ingressClass` | `traefik` | Selects which template is active (see table above). |
263+
| `ingress.enabled` | `true` | Master switch — set to `false` to render no ingress at all. |
264+
| `ingress.controller` | `''` | Selects the resource kind: `traefik` → IngressRoute, `openshift` → Routes, `nginx` → standard `Ingress` with your class name. Empty = legacy selection from `ingressClass`, where only `nginx`/`openshift`/`traefik*` render anything. |
265+
| `ingress.ingressClass` | `traefik` | Free-form `spec.ingressClassName` on the standard `Ingress`. Also drives the legacy selection while `controller` is empty. Unused by Traefik and OpenShift. |
102266
| `ingress.traefik.maxRequestBodyBytes` | `20971520` | Max request body size for Traefik's buffering middleware. Ignored when not using Traefik. |
103267
| `ingress.traefik.entryPoints` | `[]` | Traefik entrypoints for the `IngressRoute`. Empty means derive from your SSL settings — see below. Ignored when not using Traefik. |
104-
| `ingress.ingress_annotations` | `{}` | Standard `Ingress` annotations. Only rendered when `ingressClass` is exactly `nginx`; the `openshift` Route path uses `ingress.openshift.route_annotations`. |
268+
| `ingress.ingress_annotations` | `{}` | Standard `Ingress` annotations (e.g. cert-manager). Rendered only on the standard `Ingress`; the `openshift` path uses `ingress.openshift.route_annotations` and Traefik ignores them. |
105269
| `ingress.openshift.timeout` | `300s` | HAProxy per-route timeout. The router default of 30s severs `/live/` WebSockets and `/pi/` streaming. |
106270
| `ingress.openshift.termination` | `edge` | Route TLS termination (`edge` or `reencrypt`; `passthrough` cannot do path routing). |
107271
| `ingress.openshift.externalCertificate` | `''` | Name of a TLS Secret for the router to serve instead of its wildcard cert. OpenShift 4.16+. |
@@ -264,7 +428,7 @@ If the redirection is present, every plain-HTTP request is answered with a
264428
permanent redirect *before* it reaches a route, so Option 1 cannot serve Plane on
265429
that cluster. Either drop the redirection, or use Option 2/3/4.
266430

267-
#### A note on nginx (`ingress.ingressClass: nginx`)
431+
#### A note on the standard `Ingress` path (`ingress.controller: nginx`)
268432

269433
The `ssl.*` settings above drive the standard `Ingress` path too — everything in
270434
the table applies except the **Entrypoint** column, which is Traefik-only:
@@ -276,6 +440,7 @@ the table applies except the **Entrypoint** column, which is Traefik-only:
276440

277441
```yaml
278442
ingress:
443+
controller: nginx
279444
ingressClass: nginx
280445
ingress_annotations: { "nginx.ingress.kubernetes.io/proxy-body-size": "5m" }
281446
ssl:
@@ -375,6 +540,7 @@ ingress:
375540
- `planeVersion: v3.1.4 <or the last released version>`
376541
- `license.licenseDomain: <The domain you have specified to host Plane>`
377542
- `ingress.enabled: <true | false>`
543+
- `ingress.controller: <traefik | openshift | nginx — required unless ingressClass is exactly nginx/openshift/traefik*>`
378544
- `ingress.ingressClass: <traefik or any other ingress class configured in your cluster>`
379545
- `env.storageClass: <default storage class configured in your cluster>`
380546

@@ -1145,10 +1311,11 @@ Note: When the email service is enabled, the cert-issuer will be automatically c
11451311
| ingress.enabled | true | | Ingress setup in kubernetes is a common practice to expose application to the intended audience. Set it to `false` if you are using external ingress providers like `Cloudflare` |
11461312
| ingress.minioHost | | | Based on above configuration, if you want to expose the `minio` web console to set of users, use this key to set the `host` mapping or leave it as `EMPTY` to not expose interface. |
11471313
| ingress.rabbitmqHost | | | Based on above configuration, if you want to expose the `rabbitmq` web console to set of users, use this key to set the `host` mapping or leave it as `EMPTY` to not expose interface. |
1148-
| ingress.ingressClass | nginx | Yes | Kubernetes cluster setup comes with various options of `ingressClass`. Based on your setup, set this value to the right one (eg. nginx, traefik, etc). Leave it to default in case you are using external ingress provider. |
1314+
| ingress.controller | | | Selects the ingress resource kind. Supported: `traefik` renders a Traefik `IngressRoute`; `openshift` renders one `route.openshift.io/v1 Route` per path; `nginx` renders a standard `Ingress` using `ingressClass` verbatim. **Required when your class is not exactly `nginx`, `openshift` or `traefik*`** — left empty, any other class renders no ingress at all. |
1315+
| ingress.ingressClass | traefik | Yes | Free-form class name written to the standard `Ingress` `spec.ingressClassName` (eg. nginx, traefik, nginx-new, etc). While `controller` is empty it also selects the template, and only `nginx`, `openshift` and `traefik*` are recognised. Unused by the Traefik `IngressRoute` and by OpenShift `Route`s. |
11491316
| ingress.ingress_annotations | `{ "nginx.ingress.kubernetes.io/proxy-body-size": "5m" }` | | Ingress controllers comes with various configuration options which can be passed as annotations. Setting this value lets you change the default value to user required. |
1150-
| ingress.traefik.entryPoints | `[]` | | Traefik entrypoints the `IngressRoute` binds to. Leave empty to derive them from your `ssl.*` settings (`websecure` when TLS is configured, otherwise `web`). Set explicitly only if your Traefik renamed the default entrypoints, e.g. `['websecure','web']`. Ignored unless `ingressClass` starts with `traefik` |
1151-
| ingress.traefik.maxRequestBodyBytes | 20971520 | | Max request body size in bytes for Traefik's buffering middleware (upload size limit). Ignored unless `ingressClass` starts with `traefik` |
1317+
| ingress.traefik.entryPoints | `[]` | | Traefik entrypoints the `IngressRoute` binds to. Leave empty to derive them from your `ssl.*` settings (`websecure` when TLS is configured, otherwise `web`). Set explicitly only if your Traefik renamed the default entrypoints, e.g. `['websecure','web']`. Ignored unless the controller resolves to `traefik` |
1318+
| ingress.traefik.maxRequestBodyBytes | 20971520 | | Max request body size in bytes for Traefik's buffering middleware (upload size limit). Ignored unless the controller resolves to `traefik` |
11521319
| ssl.createIssuer | false | | Kubernets cluster setup supports creating `issuer` type resource. After deployment, this is step towards creating secure access to the ingress url. Issuer is required for you generate SSL certifiate. Kubernetes can be configured to use any of the certificate authority to generate SSL (depending on CertManager configuration). Set it to `true` to create the issuer. Applicable only when `ingress.enabled=true` |
11531320
| ssl.issuer | http | | CertManager configuration allows user to create issuers using `http` or any of the other DNS Providers like `cloudflare`, `digitalocean`, etc. As of now Plane supports `http`, `cloudflare`, `digitalocean` |
11541321
| ssl.token | | | To create issuers using DNS challenge, set the issuer api token of dns provider like cloudflare`or`digitalocean`(not required for http) |

0 commit comments

Comments
 (0)