-
Notifications
You must be signed in to change notification settings - Fork 204
/
Copy pathdoc.yaml
1967 lines (1947 loc) · 70.1 KB
/
doc.yaml
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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
active_version: 3.0
image_arguments:
- argument: --configmap
description: Sets the ConfigMap object that defines global settings for the ingress controller. An empty ConfigMap is deployed by default and you can see its name by calling <code>kubectl get configmaps</code>. You can either override the default ConfigMap with your own object that uses the same name, or you can set this argument to point to a different ConfigMap. See the ConfigMap Options to learn which values you can store in the ConfigMap.
values:
- The name of the ConfigMap that contains global settings. Defaults to `default/haproxy-configmap`
default: default/haproxy-configmap
version_min: "1.4"
example: --configmap=default/my-configmap
- argument: --job-check-crd
description: Special mode for controller that checks if the CRDs are installed and are on latest version. Note that this will not run ingress controller, it just checks if CRDs are OK and exits
values:
- this is boolean flag
default: false
version_min: "1.9"
example: --job-check-crd
- argument: --configmap-tcp-services
tip:
- Ports of TCP services should be exposed on the controller's Kubernetes service
description: |-
Sets the ConfigMap that contains mappings for TCP services to proxy through the ingress controller. This ConfigMap contains mappings like this:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: tcp
namespace: haproxy-controller
data:
3306: # Port where the frontend is going to listen to.
mysql-ns/mysql:3306 # Kubernetes service in the format NS/ServiceName:ServicePort
389:
ldap-ns/ldap:389:ssl # ssl option will enable ssl offloading for target service.
6379:
redis-ns/redis:6379
```
values:
- The name of the ConfigMap that contains mappings for TCP services
version_min: "1.4"
example: --configmap-tcp-services=default/my-tcpservices-configmap
- argument: --configmap-errorfiles
description: |-
Sets the ConfigMap object that defines contents to serve instead of HAProxy errors.
As explained in the [haproxy documentation](https://docs.haproxy.org/2.8/configuration.html#4.2-errorfile) it is important to understand that errorfile content is not meant to rewrite errors returned by the server, but rather errors detected and returned by HAProxy.
In the following example, instead of HAProxy returning a 503 error, it will return the corresponding content in the ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: errorfile
namespace: haproxy-controller
data:
503: |-
HTTP/1.0 503 Service Unavailable
Cache-Control: no-cache
Connection: close
Content-Type: text/html
<html><body><h1>Oops, that's embarrassing!</h1>
There are no servers available to handle your request.
</body></html>
```
values:
- The name of the ConfigMap containing errorfile content
version_min: "1.5"
example: --configmap-errorfiles=default/errorfile
- argument: --configmap-patternfiles
description: |-
Sets the ConfigMap object that defines pattern files to be used in HAProxy configuration.
Controller will create corresponding files and update them when ConfigMap is updated.
Pattern files are particularly useful for [HAProxy ACLs](https://cbonte.github.io/haproxy-dconv/2.3/configuration.html#7.1) where we can load patterns from file.
The following example will load two pattern files:
```
% cat /tmp/ips
127.0.0.1
10.0.0.0/8
1.2.3.4/24
```
```
% cat /tmp/names
foo
bar
toto
bidule
```
```
kubectl create -n default configmap acl-patterns --from-file=/tmp/ips --from-file=/tmp/names
```
The resulting configmap will be:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: acls-patterns
namespace: haproxy-controller
data:
ips: |
127.0.0.1
10.0.0.0/8
1.2.3.4/24
names: |
foo
bar
toto
bidule
```
Pattern files are useful in [config-snippets](./README.md#config-snippet). Example:
```
backend-config-snippet: |
http-request deny if !{ src -f patterns/ips }
```
tip:
- In order to use pattern files, the target file **should be prefixed with "patterns/"**
values:
- The name of the ConfigMap in format NS/ConfigMapName
version_min: "1.8"
example: --configmap-patternfiles=default/acl-patterns
- argument: --default-backend-service
description: |-
The name of the Kubernetes service to send requests to when no Ingress rules match.
By default, it uses the builtin HTTP backend.
values:
- The name of the backend service
version_min: "1.4"
example: --default-backend-service=default/my-default-service
- argument: --default-backend-port
description: if default-backend-service is not used with this you can set default port used for same purpose
values:
- port that will be used for default service within controller pod
version_min: "1.8"
example: --default-backend-port=6060
- argument: --pprof
description: enable pprof endpoint, if default-backend-port is not used 6060 will be used
values:
- this is boolean flag
version_min: "1.4"
example: --pprof
- argument: --prometheus
description: enable prometheus endpoint, if default-backend-port is not used 6060 will be used
values:
- this is boolean flag
version_min: "1.8"
example: --prometheus
- argument: --default-ssl-certificate
description: The name of a TLS Secret that contains the certificate to use for SSL/TLS traffic. This can be overridden with the <code>ssl-certificate</code> setting.
values:
- The name of the TLS Secret
version_min: "1.4"
example: --default-ssl-certificate=default/my-tls
- argument: --ingress.class
description: A name to assign to the ingress controller so that Ingress objects can target it apart from other running ingress controllers.
tip:
- In kubernetes 1.18+, a new `IngressClass` resource can be referenced by Ingress objects to target an Ingress Controller.
More details can be found in the [IngressClass doc entry](./ingressclass.md).
values:
- The name of the ingress class
version_min: "1.4"
example: --ingress.class=haproxy
helm: |-
helm install intranet haproxytech/kubernetes-ingress \
--set controller.ingressClass=haproxy
- argument: --empty-ingress-class
description: A flag to indicate the controller should process ingresses with empty ingress.class annotation.
values:
- No value.Being a flag you add it or not.
default: false
version_min: "1.6"
example: --empty-ingress-class
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--empty-ingress-class}"
- argument: --gateway-controller-name
description: identifier of your controller to know which gatewayclass it will handle
values:
- The name of the controllerName in GatewayClass
version_min: "1.10"
example: --gateway-controller-name=haproxy.org/gateway-controller
helm: |-
helm install intranet haproxytech/kubernetes-ingress \
--set controller.gatewayControllerName=haproxy.org/gateway-controller
- argument: --namespace-blacklist
description: Namespaces that the ingress controller should not monitor for changes to pods and services.
values:
- The namespace to exclude from monitoring; You can specify this argument multiple times
version_min: "1.4"
example: --namespace-blacklist=foo --namespace-blacklist=bar
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--namespace-blacklist=foo}"
- argument: --namespace-whitelist
description: Namespaces that the ingress controller should monitor for changes to pods and service.
values:
- The namespace to monitor; You can specify this argument multiple times
version_min: "1.4"
example: --namespace-whitelist=foo --namespace-whitelist=bar
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--namespace-whitelist=foo}"
- argument: --publish-service
description: Copies the ingress controller's IP address to the 'Address' field in all Ingress objects that the controller manages. This is useful for tools like external-dns, which use this information to create DNS records.
values:
- Name of the ingress controller's service, e.g. default/kubernetes-ingress
version_min: "1.4"
example: --publish-service=default/kubernetes-ingress
- argument: --disable-ipv4
description: Disabling the IPv4 bind support.
values:
- Boolean value, just need to declare the flag to disable the IPv4.
default: false
version_min: "1.5"
example: --disable-ipv4
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--disable-ipv4}"
- argument: --disable-ipv6
description: Disabling the IPv6 bind support.
values:
- Boolean value, just need to declare the flag to disable the IPv6.
default: false
version_min: "1.5"
example: --disable-ipv6
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--disable-ipv6}"
- argument: --ipv4-bind-address
description: Customize the IPv4 binding address.
values:
- "A valid IPv4 addresses. Default: 0.0.0.0"
default: 0.0.0.0
version_min: "1.5"
example: --ipv4-bind-address=10.0.0.1
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--ipv4-bind-address=10.0.0.1}"
- argument: --ipv6-bind-address
description: Customize the IPv6 binding address.
values:
- "A valid IPv6 addresses. Default: ::"
default: "::"
version_min: "1.5"
example: --ipv6-bind-address=::ffff:c0a8:5909
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--ipv6-bind-address=::ffff:c0a8:5909}"
- argument: --http-bind-port
description: Customize the HTTP frontend binding port.
values:
- "A valid port in the range. Default: 8080"
default: 8080
version_min: "1.5"
example: --http-bind-port=8080
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--http-bind-port=8080}"
- argument: --https-bind-port
description: Customize the HTTPS frontend binding port.
values:
- "A valid port in the range. Default: 8443"
default: 8443
version_min: "1.5"
example: --https-bind-port=8443
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--https-bind-port=8443}"
- argument: --disable-http
description: Disabling the HTTP frontend.
values:
- Boolean value, just need to declare the flag to disable the HTTP frontend.
default: false
version_min: "1.5"
example: --disable-http
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--disable-http}"
- argument: --disable-https
description: Disabling the HTTPS frontend.
values:
- Boolean value, just need to declare the flag to disable the HTTPS frontend.
default: false
version_min: "1.5"
example: --disable-https
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--disable-https}"
- argument: --sync-period
description: The interval at which the controller syncs its configuration with updated Kubernetes objects. In the case where the ingress controller is reloading too frequently, a higher value may be required. Note, if using helm charts you must also adjust the `startupProbe`'s `initialDelaySeconds` value. Its value must be higher than the `--sync-period` value.
values:
- An integer with unit of time (1s = 1 second, 1m = 1 minute, 1h = 1 hour); Defaults to 5s
default: 5s
version_min: "1.4"
example: --sync-period=10s
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--sync-period=60s}" \
--set controller.startupProbe.initialDelaySeconds=80
- argument: --cache-resync-period
description: Sets the default re-synchronization period at which the controller will re-apply the desired state.
values:
- The duration in <code>time.Duration</code> format; Defaults to 10m (10 minutes).
default: 10m
version_min: "1.5"
example: --cache-resync-period=30m
- argument: --log
description: The level of logging to perform; Defaults to <i>info</i>
values:
- error
- warning
- info (default)
- debug
- trace
default: info
version_min: "1.4"
example: --log=debug
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set controller.logging.level=debug
- argument: --external
description: Run as external Ingress Controller (out of kubernetes cluster). This can be done by cloning Ingress Controller project and building Controller with `go build`. Or using `export GO111MODULE=on; go get github.com/haproxytech/kubernetes-ingress`.
values:
- Boolean value.
default: false
external: true
version_min: "1.5"
example: --external
- argument: --program
description: Path to HAProxy binary to use when running controller in [external mode](#--external).
values:
- Path to HAProxy binary
default: haproxy in PATH location
external: true
version_min: "1.5"
example: --external --program=/usr/bin/haproxy
- argument: --config-dir
description: Path to HAProxy configuration directory when running controller in [external mode](#--external). Configuration directory is where resources like configuration file, certificates, haproxy map files, are located.
values:
- Path to configuration directory
default: "/tmp/haproxy-ingress/etc"
external: true
version_min: "1.5"
example: --external --config-dir=/haproxy-ingress/etc
- argument: --runtime-dir
description: Path to HAProxy runtime directory when running controller in [external mode](#--external). Runtime directory is where resources like PID file, runtime socket, etc are located.
values:
- Path to runtime directory
default: "/tmp/haproxy-ingress/run"
external: true
version_min: "1.5"
example: --external --runtime-dir=/haproxy-ingress/run
- argument: --disable-service-external-name
description: Disable forwarding to ExternalName Services due to CVE-2021-25740
values:
- Boolean value, just need to declare the flag to disable forwarding to ExternalName Services.
default: "false"
version_min: "1.6"
example: --disable-service-external-name
helm: |-
helm install haproxy haproxytech/kubernetes-ingress \
--set-string "controller.extraArgs={--disable-service-external-name}"
- argument: --channel-size
description: |-
Sets the size of controller buffers used to receive and send k8s events.
This parameter is a cursor to adapt to the number of resources inside your clusters and that generate a lot of events.
Rule of thumb: the more resources the higher the value.
values:
- Size of channels used for k8s resources events with regards to ingresses, etc.
default: 600
version_min: "1.7"
example: --channel-size=10000
- argument: --disable-config-snippets
description: |-
Allow to disable one or several of the following config snippets: backend, frontend, global.
values:
- Comma separated list of the kind of config snippets to disable. Possible values in the list are
- backend,frontend,global,all
- If 'all' is present then all (backend, frontend, global) config snippets are disabled.
version_min: "1.11"
example: --disable-config-snippets=backend,frontend
- argument: --disable-quic
description: option to disable the quic binding used by default if a certificate is provided throug ssl-certificate annotation. Please be aware that the quic implementation is activated with the "limited-quic" global option. Please refer to the documentation for details.
default: false
version_min: "1.11"
example: |-
args:
- --disable-quic
- argument: --quic-announce-port
description: adjust the port in the alt-svc header to redirect to the exposed port in case it differs from the quic binding port.
version_min: "1.11"
example: |-
args:
- --quic-announce-port=10443
- argument: --quic-bind-port
description: sets the binding port for quic in HTTPS frontend.
version_min: "1.11"
example: |-
args:
- --quic-bind-port=4443
- argument: --disable-writing-only-if-reload
description: Disable the delayed writing of files to disk ONLY in case of haproxy reload (= write files to disk even if no reload)
values:
- Boolean value, just need to declare the flag to disable
default: false
version_min: "3.1"
example: --disable-writing-only-if-reload
- argument: --input-file
description: |-
This is the path to a manifest (yaml) of a v1 version to the CRDs to convert to v3.
Goes with --output-file for the result
values:
- Path a to a CRD manifest you want to convert to the latest version
example: --input-file=/home/xxx/convert/v1/global-full.yaml
version_min: "3.2"
- argument: --output-file
description: |-
This is the path to a manifest (yaml) where to write to the converted v3 CRD from a v1 manifest (see --input-file).
Goes with --input-file
values:
- Path a to a CRD manifest where the converted v3 CRDs will be written
example: --output-file=/home/xxx/convert/v3/global-full.yaml
version_min: "3.2"
groups:
config-snippet:
header: |-
- Insert raw HAProxy configuration in specific HAProxy config sections.
- There is **no data validation** done by Ingress Controller. If input is incorrect, HAProxy will fail to apply new configuration.
- It is possible to use [pattern files](controller.md/#--configmap-patternfiles) inside config snippets.
CORS:
header: |-
- *Cross-Origin Resource Sharing (CORS) is an HTTP-header based mechanism that allows a server to indicate any other origins (domain, scheme, or port) than its own from which a browser should permit loading of resources.* - [Mozilla Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
access-control:
header: |-
- Access control is disabled by default
- Access control can be set for all traffic (annotation on configmap) or for a set of hosts (annotation on ingress)
https:
header: |-
- [SSL offloading/decryption](#ssl-offloading) will be automatically enabled if valid SSL certificates are provided.
ssl-offloading:
header: |
- Controller will look into kubernetes secrets for valid SSL certificates to configure in HAProxy.
- A default certificate can be provided via controller [argument](controller.md) `--default-ssl-certificate`=\<namespace\>/\<secret\> or ConfigMap annotation [ssl-certificate](#ssl-certificate).
- Certificates can be defined in Ingress object: `spec.tls[].secretName`
footer: |
- A secret can be of `tls` type (most common) created via :
```
kubectl create secret tls my-secret --key=<key-path> --cert=<cert-path>
```
- A secret can be of `generic` type if we want to have a certificate in multiple formats:
```
kubectl create secret generic my-secret --from-file=rsa.key=<rsa-key-path> --from-file=rsa.crt=<rsa-cert-path> \
--from-file=ecdsa.key=<ecdsa-key-path> --from-file=ecdsa.crt=<ecdsa-cert-path>
```
The only possible keys are the following,
- rsa.key
- rsa.crt
- ecdsa.key
- ecdsa.crt
- dsa.key
- dsa.crt
annotations:
- title: auth-type
type: string
group: authentication
dependencies: ""
default: ""
description:
- Enables the selected HTTP authentication strategy.
tip: []
values:
- basic-auth
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- "auth-type: basic-auth"
- "auth-secret: default/haproxy-credentials"
- title: auth-secret
type: string
group: authentication
dependencies: auth-type
default: ""
description:
- Selects the Kubernetes Secret where authentication data can be found.
tip:
- Encrypted passwords are evaluated using the crypt(3) function, so depending on the system's capabilities, different algorithms are supported.
- Unencrypted passwords (used with HAProxy [insecure-password](https://docs.haproxy.org/2.8/configuration.html#3.4-user) ) **are not accepted**.
values:
- |-
The annotation format is a secret path *namespace/secretName*. If the namespace is omitted (path is only *secretName*) then the ingress namespace will be used.
For Basic Authentication, the Secret data should contain user credentials in the form of `username: encrypted and base-64 encoded password`. For example:
```
bob: JDEkYWJjJEJYQnFwYjlCWmNaaFhMZ2JlZS4wcy8=
```
Create the Kubernetes Secret resource in the following way:
```bash
kubectl create secret generic haproxy-credentials \
--from-literal=bob=$(openssl passwd -1 bobPassword) \
--from-literal=alice=$(openssl passwd -1 alicePassword)
# secret/haproxy-credentials created
```
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- "auth-type: basic-auth"
- "auth-secret: default/haproxy-credentials"
- title: auth-realm
type: string
group: authentication
dependencies: "auth-type, auth-secret"
default: "Protected Content"
description:
- Provides the HTTP Authentication Realm
tip: []
values:
- Realm name
applies_to:
- configmap
- ingress
version_min: "1.5"
example: ["auth-realm: Admin Area"]
- title: blacklist
type: IPs/CIDRs or pattern file
group: access-control
dependencies: ""
default: ""
description:
- "**Deprecated**, use `deny-list` instead."
- Blocks given IP addresses and/or IP address ranges.
tip:
- The value is treated as a pattern file (see `--configmap-patternfiles`) if it starts with `patterns/`. It should consist of a list of IPs or CIDRs, one per line.
values:
- Comma-separated list of IP addresses and/or CIDR ranges
- Path to a pattern file, e.g. `pattern/ips`
applies_to:
- configmap
- ingress
version_min: "1.4"
example: ['blacklist: "192.168.1.0/24, 192.168.2.100"']
- title: deny-list
type: IPs/CIDRs or pattern file
group: access-control
dependencies: ""
default: ""
description:
- Blocks given IP addresses and/or IP address ranges.
tip:
- The value is treated as a pattern file (see `--configmap-patternfiles`) if it starts with `patterns/`. It should consist of a list of IPs or CIDRs, one per line.
values:
- Comma-separated list of IP addresses and/or CIDR ranges
- Path to a pattern file, e.g. `pattern/ips`
applies_to:
- configmap
- ingress
version_min: "1.11"
example: [ 'deny-list: "192.168.1.0/24, 192.168.2.100"' ]
- title: check
type: bool
group: backend-checks
dependencies: ""
default: "true"
description:
- Enables TCP level health checks on pods and attempts a TCP connection periodically.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
- ingress
- service
version_min: "1.4"
example: ['check: "true"']
- title: check-http
type: string
group: backend-checks
dependencies: check
default: ""
description:
- Enables HTTP level health checks on pods and sends an HTTP request periodically.
The `check` setting must be true.
tip: []
values:
- URI to make HTTP requests to, e.g. `/health`
- URI with method, e.g. `HEAD /health`
- URI, method and HTTP version, e.g. `HEAD /health HTTP/1.1`
applies_to:
- configmap
- ingress
- service
version_min: "1.4"
example:
- 'check: "true"'
- 'check-http: "/health"'
- title: check-interval
type: "[time](#time)"
group: backend-checks
dependencies: check
default: ""
description:
- Sets the interval between health checks when `check` is enabled.
tip: []
values:
- Integer with time unit suffix (1m = 1 minute, 10s = 10 seconds)
applies_to:
- configmap
- ingress
- service
version_min: "1.4"
example:
- 'check: "true"'
- 'check-interval: "1m"'
- title: clean-certs
type: bool
group:
dependencies:
default: "true"
description:
- Switches certificates clean up.
- By default controller cleans up unused certificates in haproxy cert directory.
- In the case where certificates may be handled by a side-car container, it is useful not to remove certificates unkown to controller.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
version_min: "1.6"
example:
- 'clean-certs: "false"'
- title: client-ca
type: string
group: authentication
dependencies: ssl-offloading
default: ""
description:
- Sets the client certificate authority enabling HAProxy to check clients certificate (TLS authentication), thus enabling client *mTLS*.
tip:
- NB, [ssl-offloading](#ssl-offloading) **should be enabled** for TLS authentication to work.
values:
- secret path in "namespace/name" format.
applies_to:
- configmap
version_min: "1.6"
example:
- "client-ca: exp/client-ca.crt"
- title: client-crt-optional
type: bool
group: authentication
dependencies: client-ca
default: "false"
description:
- If enabled, certificate verification will be optional which means haproxy will still accept the client connection even if the certificate verification fails.
- If disabled haproxy will enforce verification of client certificates and only accepts client with valid certificate.
tip:
- NB, [client-ca](#client-ca) **should be enabled** for certificate verification to work.
values:
- "true"
- "false"
applies_to:
- configmap
version_min: "1.6"
example:
- "client-crt-optional: true"
- title: client-strict-sni
type: bool
group: ssl-offloading
dependencies: client-ca
default: "false"
description:
- If enabled, HAProxy will only accept TLS client connections where the provided SNI matchs an existing certificate.
- If disabled HAProxy will service the default certificate when the provided SNI does not match.
values:
- "true"
- "false"
applies_to:
- configmap
version_min: "1.8"
example:
- "client-strict-sni: true"
- title: cors-enable
type: bool
group: CORS
dependencies: ""
default: "false"
description:
- Enables CORS rules for corresponding Ingress traffic.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-enable: "true"'
- title: cors-allow-origin
type: string
group: CORS
dependencies: cors-enable
default: "*"
description:
- Sets the `Access-Control-Allow-Origin` response header to tell browsers which origin is allowed to access the requested resource.
tip:
- With "regex" value, it is possible to allow a list of origins. If one of them matches the request Origin header it will be returned to the client.
values:
- Wildcard `*`, allow access form any origin.
- Regex, regex should match an origin (request Origin header) in the format `<scheme> "://" <hostname> [ ":" <port> ]` if the origin is matched then it will be the value of `Access-Control-Allow-Origin`.
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-allow-origin: "*"'
- 'cors-allow-origin: "https://example.com"'
- 'cors-allow-origin: "^https://(.+\.)?(example-1\.com|example-2\.com)(:\d{1,5})?$"'
- title: cors-allow-methods
type: string
group: CORS
dependencies: cors-enable
default: "*"
description:
- Sets the `Access-Control-Allow-Methods` response header to tell browsers the HTTP methods allowed when accessing the request resource.
tip: []
values:
- Wildcard `*`, allow access for all HTTP methods.
- A comma-separated list of HTTP methods
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-allow-methods: "*"'
- 'cors-allow-methods: "GET"'
- 'cors-allow-methods: "GET, POST"'
- title: cors-allow-credentials
type: bool
group: CORS
dependencies: cors-enable
default: "false"
description:
- Sets the `Access-Control-Allow-Credentials` response header to tell browsers if credentials can be used to access the requested resource.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-allow-credentials: "true"'
- title: cors-allow-headers
type: string
group: CORS
dependencies: cors-enable
default: "*"
description:
- Sets the `Access-Control-Allow-Headers` response header to tell browsers which HTTP headers can be used when accessing the request resource.
tip: []
values:
- Wildcard `*`, allow access for all HTTP headers.
- A comma-separated list of HTTP headers
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-allow-headers: "*"'
- 'cors-allow-headers: "X-Custom-Header"'
- 'cors-allow-headers: "X-Custom-Header, Upgrade-Insecure-Requests"'
- title: cors-max-age
type: "[time](#time)"
group: CORS
dependencies: cors-enable
default: "5s"
description:
- Sets the `Access-Control-Allow-Age` response header to tell browsers how long the result of a preflight request can be cached.
tip: []
values:
- A [time](#time) duration
applies_to:
- configmap
- ingress
version_min: "1.5"
example:
- 'cors-max-age: "1m"'
- title: global-config-snippet
type: string
group: config-snippet
dependencies: ""
default: ""
description:
- Defines a group of configuration directives to insert the HAProxy global section.
tip: []
values:
- One or more valid HAProxy directives
applies_to:
- configmap
version_min: "1.5"
example_configmap: |-
global-config-snippet: |
ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11
ssl-default-bind-ciphers TLS13-AES-256-GCM-SHA384:TLS13-AES-128-GCM-SHA256:TLS13-CHACHA20-POLY1305-SHA256:EECDH+AESGCM:EECDH+CHACHA20
tune.ssl.default-dh-param 2048
tune.bufsize 32768
- title: frontend-config-snippet
type: string
group: config-snippet
dependencies: ""
default: ""
description:
- Defines a group of configuration directives to insert in the main HTTP/HTTPS frontends.
tip:
- Because frontend-config-snippet is inserted in the main http/https frontends it will apply to all traffic. To apply configuration by Ingress, annotations should be privileged.
- Ingress Controller logic is inserted in the main frontends before any config-snippet configuration so controller configuration will be **evaluated first**.
- It is safer to privilege [backend-config-snippet](#backend-config-snippet) when possible to avoid conflicts with controller configuration.
values:
- One or more valid HAProxy directives
applies_to:
- configmap
version_min: "1.6"
example_configmap: |-
frontend-config-snippet: |
unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
unique-id-header X-Unique-ID
- title: stats-config-snippet
type: string
group: config-snippet
dependencies: ""
default: ""
description:
- Defines a group of configuration directives to insert in the stats frontend.
tip: []
values:
- One or more valid HAProxy directives
applies_to:
- configmap
version_min: "1.6"
example_configmap: |-
stats-config-snippet: |
stats auth foo:test
- title: backend-config-snippet
type: string
group: config-snippet
dependencies: ""
default: ""
description:
- Defines a group of configuration directives to add directly to a HAProxy backend section.
tip: []
values:
- One or more valid HAProxy directives
applies_to:
- configmap
- ingress
- service
version_min: "1.5"
example:
- |-
backend-config-snippet: |
http-send-name-header x-dst-server
stick-table type string len 32 size 100k expire 30m
stick on req.cook(sessionid)
- title: cookie-persistence
type: string
description:
- Enables persistent connections (sticky sessions) between a client and a pod by inserting a cookie
into the client's browser that is used to remember which backend pod they connected
to before.
- Dynamic cookies are used by default via a [dynamic-cookie-key](https://cbonte.github.io/haproxy-dconv/2.4/configuration.html#4.2-dynamic-cookie-key) in order to support sticky sessions across multiple Ingress Controller instances/replicas.
tip:
- This will insert the following cookie configuration in the corresponding backend `cookie <cookie-name> insert indirect nocache dynamic` with `<cookie-name>` the value of this annotation.
values:
- A name for the cookie
applies_to:
- configmap
- ingress
- service
version_min: "1.4"
example: ['cookie-persistence: "mycookie"']
- title: cookie-persistence-no-dynamic
type: string
description:
- Enables persistent connections (sticky sessions) between a client and a pod by inserting a cookie
into the client's browser that is used to remember which backend pod they connected
to before.
- Dynamic cookies are not used contrary to cookie-persistence annotation. The cookie will have the server name.
tip:
- |-
This will insert the following cookie configuration in the corresponding backend
`cookie <cokkie-name> indirect nocache insert` with `<cookie-name>` the value of this annotation.
The server line will have `server <server-name> <server-address> enabled cookie <server-name>`
values:
- A name for the cookie
applies_to:
- configmap
- ingress
- service
version_min: "3.1"
example: ['cookie-persistence-no-dynamic: "mycookie"']
- title: dontlognull
type: bool
group: logging
dependencies: ""
default: "true"
description:
- Do not log connections that sends no data, which can happen with monitoring systems.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
version_min: "1.4"
example: ['dontlognull: "true"']
- title: src-ip-header
type: string
group: src-ip-header
dependencies: ""
default: "null"
description:
- Set the source IP from a header rather than the L3 connection.
tip: []
values:
- "any header name"
applies_to:
- configmap
- ingress
version_min: "1.5"
example: ['src-ip-header: "True-Client-IP"']
- title: forwarded-for
type: bool
group: x-forwarded-for
dependencies: ""
default: "true"
description:
- Adds the X-Forwarded-For HTTP header to requests to capture and relay the client's
source IP address to backend pods.
tip: []
values:
- "true"
- "false"
applies_to:
- configmap
- ingress
- service
version_min: "1.4"
example: ['forwarded-for: "true"']
- title: hard-stop-after
type: "[time](#time)"
group: hard-stop-after
dependencies: ""
default: "30m"
description:
- Defines the maximum time allowed to perform a clean soft-stop.
tip: []
values:
- An integer with a unit of time (1 second = 1s, 1 minute = 1m, 1h = 1 hour)
applies_to:
- configmap
version_min: "1.4"
example: ["hard-stop-after: 30s"]
- title: http-connection-mode
type: string
group: http-options
dependencies: ""
default: http-keep-alive
description:
- Sets HAProxy connection mode
values:
- http-keep-alive `default` - Enables HTTP Keep-Alive both from the client to HAProxy and
from HAProxy to the backend.
- http-server-close - Disables HTTP Keep-Alive between HAProxy and the backend,
while allowing it to stay enabled from the client to HAProxy.
- httpclose - HAProxy will close connections with the server and the client as
soon as the request and the response are received
applies_to:
- configmap
version_min: "1.8"
example: ['http-connection-mode: "http-server-close"']
- title: http-keep-alive
type: bool
group: http-options
dependencies: ""
default: "true"
description:
- "**Deprecated**, use `http-connection-mode` instead."
- Enables HTTP Keep-Alive both from the client to HAProxy and from HAProxy to the
backend.
tip: []
values: