Skip to content

Commit d9c0ae7

Browse files
alessfgalessfg
authored
Update Stream template documentation (#224)
1 parent 834cf82 commit d9c0ae7

File tree

6 files changed

+226
-65
lines changed

6 files changed

+226
-65
lines changed

‎defaults/main/template.yml

Lines changed: 198 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ nginx_config_http_template:
124124
valid: 30s
125125
ipv6: false # Boolean
126126
status_zone: backend_mem_zone
127-
resolver_timeout: 30s
127+
resolver_timeout: 30s # Available only in NGINX Plus
128128
sticky_cookie: # You can only set one type of sticky session affinity
129129
name: cookie # Required
130130
expires: 1d
@@ -241,7 +241,7 @@ nginx_config_http_template:
241241
address: 127.0.0.1 # Required -- String or a list of strings
242242
valid: 60s
243243
ipv6: false # Boolean
244-
status_zone: zone # Only available in NGINX Plus
244+
status_zone: zone # Available only in NGINX Plus
245245
resolver_timeout: 30s
246246
root: html
247247
index: path # Note -- This directive originally belongs to the NGINX index module, but we are making an exception here.
@@ -270,7 +270,7 @@ nginx_config_http_template:
270270
underscores_in_headers: false # Boolean -- Not available in the 'location' context
271271
variables_hash_bucket_size: 64 # Available only in the 'http' context
272272
variables_hash_max_size: 1024 # Available only in the 'http' context
273-
ssl:
273+
ssl: # Configure SSL
274274
buffer_size: 16k
275275
certificate: /path/to/file # String or a list of strings
276276
certificate_key: /path/to/file # String or a list of strings
@@ -708,57 +708,202 @@ nginx_config_rest_api_dashboard_deny: # Optional
708708

709709
# Enable creating dynamic templated NGINX stream configuration files.
710710
# Defaults will not produce a valid configuration. Instead they are meant to showcase
711-
# the options available for templating. Each key represents a new configuration file.
711+
# the options available for templating. Each dictionary in the top level list/array represents a new configuration file.
712+
# Unless otherwise noted, all variables are *strings* and *optional* (*required* values inside a dictionary are only required if the top level variable is defined).
713+
# Most (not all) of these directives can also be used under the 'server' and 'location' contexts, as briefly seen at the end of the below dictionary.
712714
nginx_config_stream_template_enable: false
713715
nginx_config_stream_template:
714716
- template_file: stream/default.conf.j2
715-
conf_file_name: default.conf
716-
conf_file_location: /etc/nginx/conf.d/stream/
717-
backup: true
718-
network_streams:
719-
- listen:
720-
- ip: 0.0.0.0 # Wrap in square brackets for IPv6 addresses
717+
deployment_location: /etc/nginx/conf.d/streams/stream_default.conf
718+
config:
719+
upstreams: # Configure NGINX upstreamds
720+
- name: stream_upstream # Required
721+
servers:
722+
- address: 0.0.0.0:9091 # Required
723+
weight: 1 # Number
724+
max_conns: 100 # Number
725+
max_fails: 3 # Number
726+
fail_timeout: 5s
727+
backup: false # Boolean
728+
down: false # Boolean
729+
resolve: false # Boolean
730+
service: http
731+
slow_start: 0s
732+
zone:
733+
name: stream_zone # Required
734+
size: 64k
735+
state: /var/lib/nginx/state/servers.conf # Available only in NGINX Plus -- Cannot be used if 'servers' directive is defined
736+
hash: # You can only set one load balancing method -- 'round_robin' is used if no method is specified
737+
key: key # Required
738+
consistent: false # Boolean
739+
least_conn: false # Boolean -- You can only set one load balancing method
740+
least_time: # You can only set one load balancing method
741+
response: last_byte # Required -- Can be set to 'header' or 'last_byte'
742+
inflight: false # Boolean
743+
random: # You can only set one load balancing method
744+
two: true # Boolean
745+
method: least_time=last_byte # Requires two to be set to 'true'
746+
resolver: # Available only in NGINX Plus
747+
address: [] # Required -- String or a list of strings
748+
valid: 30s
749+
ipv6: false # Boolean
750+
status_zone: backend_mem_zone
751+
resolver_timeout: 30s # Available only in NGINX Plus
752+
core: # Configure NGINX Stream core directives
753+
include: path # String or a list of strings. Note -- This directive originally belongs to the NGINX core module, but we are making an exception here.
754+
listen: # Available only in the 'server' context
755+
- address: 0.0.0.0 # Can also be a unix path
721756
port: 80
722-
ssl: false
723-
opts: [] # Listen opts like udp which will be added (ssl is automatically added if you specify 'ssl:').
724-
ssl:
725-
cert: /etc/ssl/certs/default.crt
726-
key: /etc/ssl/private/default.key
727-
dhparam: /etc/ssl/private/dh_param.pem
728-
protocols: TLSv1 TLSv1.1 TLSv1.2
729-
ciphers: HIGH:!aNULL:!MD5
730-
prefer_server_ciphers: true
731-
session_cache: none
732-
session_timeout: 5m
733-
disable_session_tickets: false
734-
trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt
735-
ecdh_curve: auto
736-
include_files: []
737-
proxy_pass: backend
738-
proxy_timeout: 3s
739-
proxy_connect_timeout: 1s
740-
proxy_protocol: false
741-
proxy_ssl:
742-
cert: /etc/ssl/certs/proxy_default.crt
743-
key: /etc/ssl/private/proxy_default.key
744-
trusted_cert: /etc/ssl/certs/proxy_ca.crt
745-
protocols: TLSv1 TLSv1.1 TLSv1.2
746-
ciphers: HIGH:!aNULL:!MD5
747-
verify: false
748-
verify_depth: 1
749-
session_reuse: true
750-
health_check_plus: false
751-
# custom_options: []
752-
upstreams:
753-
- name: backend
754-
lb_method: least_conn
755-
zone_name: backend
756-
zone_size: 64k
757-
sticky_cookie: false
758-
servers:
759-
- address: localhost
760-
port: 8080
761-
weight: 1
762-
health_check: max_fails=1 fail_timeout=10s
763-
# custom_options: []
764-
# custom_options: []
757+
ssl: false # Boolean
758+
udp: false # Boolean
759+
proxy_protocol: false # Boolean
760+
fastopen: 12 # Number
761+
backlog: 511 # Number
762+
rcvbuf: 512
763+
sndbuf: 512
764+
bind: false # Boolean
765+
ipv6only: false # Boolean
766+
reuseport: false # Boolean
767+
so_keepalive: # false # Can alternatively be set to a 'boolean'
768+
keepidle: 30m
769+
keepintvl: 5
770+
keepcnt: 10
771+
preread_buffer_size: 16k
772+
preread_timeout: 30s
773+
proxy_protocol_timeout: 30s
774+
resolver:
775+
address: 127.0.0.1 # Required -- String or a list of strings
776+
valid: 60s
777+
ipv6: false # Boolean
778+
status_zone: zone # Available only in NGINX Plus
779+
resolver_timeout: 30s
780+
tcp_nodelay: true # Boolean
781+
variables_hash_bucket_size: 64
782+
variables_hash_max_size: 1024
783+
ssl: # Configure Stream SSL
784+
alpn: http/1.1 # String or a list of strings
785+
certificate: /etc/ssl/certs/molecule.crt # String or a list of strings
786+
certificate_key: /etc/ssl/private/molecule.key # String or a list of strings
787+
ciphers: # String or a list of strings
788+
- HIGH
789+
- "!aNull"
790+
- "!MD5"
791+
client_certificate: /path/to/file
792+
conf_command: Protocol TLSv1.2 # String or a list of strings
793+
crl: /path/to/file
794+
dhparam: /path/to/file
795+
ecdh_curve: auto # String or a list of strings
796+
handshake_timeout: 60s
797+
password_file: /path/to/file
798+
prefer_server_ciphers: false # Boolean
799+
protocols: # String or a list of strings
800+
- TLSv1
801+
- TLSv1.1
802+
- TLSv1.2
803+
session_cache: # none # Can be set to 'false', 'none', 'builtin' (uses the 'enable' and 'size' dict), or 'shared' (uses the 'name' and 'size' dict)
804+
builtin:
805+
enable: false # Required
806+
size: 16k
807+
# shared:
808+
# name: cache # Required
809+
# size: 16k # Required
810+
session_ticket_key: /path/to/file # String or a list of strings
811+
session_tickets: true # Boolean
812+
session_timeout: 5m
813+
trusted_certificate: /path/to/file
814+
verify_client: false # Boolean -- Can also be set to 'optional' or 'optional_no_ca'
815+
verify_depth: 1 # Number
816+
proxy: # Configure Stream Proxy
817+
bind: # Set to 'false' and remove/comment nested variables to disable proxy_bind
818+
address: 0.0.0.0 # Required
819+
transparent: false # Boolean
820+
buffer_size: 4k
821+
connect_timeout: 60s
822+
download_rate: 0
823+
half_close: false # Boolean
824+
next_upstream: true # Boolean
825+
next_upstream_timeout: 0
826+
next_upstream_tries: 0 # Number
827+
pass: 127.0.0.1 # Available only in the 'server' context
828+
protocol: false # Boolean
829+
requests: 0 # Number
830+
responses: 0 # Number
831+
session_drop: false # Available only in NGINX Plus -- Boolean
832+
socket_keepalive: false # Boolean
833+
ssl: false
834+
ssl_certificate: /path/to/file
835+
ssl_certificate_key: /path/to/file
836+
ssl_ciphers: HIGH # String or a list of strings
837+
ssl_conf_command: # String or a list of strings
838+
- Protocol TLSv1.2
839+
ssl_crl: /path/to/file
840+
ssl_name: $hostname
841+
ssl_password_file: /path/to/file
842+
ssl_protocols: TLSv1.2 # String or a list of strings
843+
ssl_server_name: false # Boolean
844+
ssl_session_reuse: true # Boolean
845+
ssl_trusted_certificate: /path/to/file
846+
ssl_verify: false # Boolean
847+
ssl_verify_depth: 1 # Number
848+
timeout: 10m
849+
upload_rate: 0
850+
health_check: # Available only in NGINX Plus -- Configure NGINX Plus health checks
851+
health_checks: # Available only in the 'server' context
852+
- interval: 5s
853+
jitter: 0
854+
fails: 1 # Number
855+
passes: 1 # Number
856+
uri: /
857+
mandatory: false # Boolean
858+
persistent: false # Boolean
859+
match: match
860+
port: 80
861+
udp: false
862+
match:
863+
- name: nginx_stream
864+
conditions:
865+
- status 200
866+
timeout: 60s
867+
keyval: # Available only in NGINX Plus -- Configure NGINX Plus key value store
868+
keyvals: # Available only in the 'stream' context
869+
- key: key # Required
870+
variable: $var # Required
871+
zone: one # Required
872+
zones: # Available only in the 'stream' context
873+
- name: one # Required
874+
size: 32k # Required
875+
state: /var/lib/nginx/state/one.keyval
876+
timeout: 60m
877+
type: string # Can be set to 'string', 'ip' or 'prefix'
878+
sync: false # Boolean
879+
log: # Configure logs
880+
format: # Available only in the 'stream' context
881+
- name: main # Required
882+
escape: default # Can be set to 'default', 'json' or 'none'
883+
format: | # Required
884+
'$remote_addr - $remote_user [$time_local] "$request" '
885+
'$status $body_bytes_sent "$http_referer" '
886+
'"$http_user_agent" "$http_x_forwarded_for"'
887+
access: # false # Can alternatively be set to 'false'
888+
- path: /var/log/nginx/access.log # Required
889+
format: main
890+
buffer: 1m
891+
gzip: 5 # Number -- Can alternatively be set to 'true'
892+
flush: 10h
893+
if: $loggable
894+
error: # /var/log/nginx/error.log # String, a list of strings, a dictionary, or a list of dictionaries. The 'file' variable is only required when setting a 'level'. This directive originally belongs to the NGINX core module, but we are making an exception.
895+
file: /var/log/nginx/error.log # Required
896+
level: notice
897+
# - /var/log/nginx/error.log
898+
# - file: /var/log/nginx/error.log # Required
899+
# level: notice
900+
open_log_file_cache: # Set to 'false' to set to 'off'
901+
max: 1000 # Required
902+
inactive: 20s
903+
min_uses: 2 # Number
904+
valid: 1m
905+
custom_directives: # String or a list of strings. Custom directive for specific use cases not covered by templates. Note: You need to add a semi-colon at the end of each directive.
906+
- server {};
907+
servers:
908+
- core:
909+
proxy:

‎molecule/plus/converge.yml

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -601,10 +601,6 @@
601601
config:
602602
upstreams:
603603
- name: stream_upstream
604-
zone:
605-
name: stream_zone
606-
size: 64k
607-
least_conn: true
608604
servers:
609605
- address: 0.0.0.0:9091
610606
weight: 1
@@ -614,6 +610,10 @@
614610
backup: false
615611
down: false
616612
resolve: false
613+
zone:
614+
name: stream_zone
615+
size: 64k
616+
least_conn: true
617617
core:
618618
preread_buffer_size: 16k
619619
preread_timeout: 30s
@@ -659,6 +659,7 @@
659659
requests: 0
660660
responses: 0
661661
session_drop: false
662+
socket_keepalive: false
662663
ssl: false
663664
ssl_certificate: /etc/ssl/certs/molecule.crt
664665
ssl_certificate_key: /etc/ssl/private/molecule.key

‎templates/http/default.conf.j2

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ server {
225225
{% if server['custom_directives'] is defined and server['custom_directives'] is not mapping %}
226226
{% for directive in server['custom_directives'] if server['custom_directives'] is not string %}
227227
{% filter indent(4) %}
228-
{{ directive }}
228+
{{ directive }}
229229
{% endfilter %}
230230
{% else %}
231231
{{ server['custom_directives'] }}

‎templates/http/upstream.j2

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,13 @@ upstream {{ upstream['name'] }} {
3030
state {{ upstream['state'] }};
3131
{% endif %}
3232
{% if upstream['hash']['key'] is defined %}
33-
hash {{ upstream['hash']['key'] }}{{ ' consistent' if upstream['hash']['consistent'] is defined and upstream['hash']['consistent'] is boolean }};
33+
hash {{ upstream['hash']['key'] }}{{ ' consistent' if upstream['hash']['consistent'] is defined and upstream['hash']['consistent'] is boolean and upstream['hash']['consistent'] | bool }};
3434
{% elif upstream['ip_hash'] is defined and upstream['ip_hash'] is boolean %}
3535
ip_hash;
3636
{% elif upstream['least_conn'] is defined and upstream['least_conn'] is boolean %}
3737
least_conn;
3838
{% elif upstream['least_time']['response'] is defined %}
39-
least_time {{ upstream['least_time']['response'] }}{{ ' inflight' if upstream['least_time']['inflight'] is defined and upstream['least_time']['inflight'] is boolean }};
39+
least_time {{ upstream['least_time']['response'] }}{{ ' inflight' if upstream['least_time']['inflight'] is defined and upstream['least_time']['inflight'] is boolean and upstream['least_time']['inflight'] | bool }};
4040
{% elif upstream['random'] is defined %}
4141
random {{ 'two' if upstream['random']['two'] is defined and upstream['random']['two'] is boolean }}{{ (' ' + upstream['random']['method'] | string) if upstream['random']['method'] is defined }};
4242
{% endif %}
@@ -55,7 +55,7 @@ upstream {{ upstream['name'] }} {
5555
{% if upstream['keepalive_timeout'] is defined %}
5656
keepalive_timeout {{ upstream['keepalive_timeout'] }};
5757
{% endif %}
58-
{% if upstream['ntlm'] is defined and upstream['ntlm'] is boolean and upstream['ntlm'] is boolean %}
58+
{% if upstream['ntlm'] is defined and upstream['ntlm'] is boolean and upstream['ntlm'] | bool %}
5959
ntlm;
6060
{% endif %}
6161
{% if upstream['resolver']['address'] is defined %}
@@ -72,7 +72,7 @@ upstream {{ upstream['name'] }} {
7272
{{- (' expires=' + upstream['sticky_cookie']['expires'] | string) if upstream['sticky_cookie']['expires'] is defined -}}
7373
{{- (' domain=' + upstream['sticky_cookie']['domain'] | string) if upstream['sticky_cookie']['domain'] is defined -}}
7474
{{- ' httponly' if upstream['sticky_cookie']['httponly'] is defined and upstream['sticky_cookie']['httponly'] is boolean and upstream['sticky_cookie']['httponly'] | bool -}}
75-
{{- (' samesite' + upstream['sticky_cookie']['samesite'] | string) if upstream['sticky_cookie']['samesite'] is defined and upstream['sticky_cookie']['samesite'] in ['strict', 'lax', 'none'] -}}
75+
{{- (' samesite=' + upstream['sticky_cookie']['samesite'] | string) if upstream['sticky_cookie']['samesite'] is defined and upstream['sticky_cookie']['samesite'] in ['strict', 'lax', 'none'] -}}
7676
{{- ' secure' if upstream['sticky_cookie']['secure'] is defined and upstream['sticky_cookie']['secure'] is boolean and upstream['sticky_cookie']['secure'] | bool -}}
7777
{{- (' path=' + upstream['sticky_cookie']['path'] | string) if upstream['sticky_cookie']['path'] is defined }};
7878
{% elif upstream['sticky_route'] is defined %}

‎templates/stream/default.conf.j2

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,13 @@
2828
{% from 'stream/modules.j2' import log with context %}
2929
{{ log(item['config']['log']) }}
3030
{%- endif %}
31-
31+
{% if item['config']['custom_directives'] is defined and item['config']['custom_directives'] is not mapping %}
32+
{% for directive in item['config']['custom_directives'] if item['config']['custom_directives'] is not string %}
33+
{{ directive }}
34+
{% else %}
35+
{{ item['config']['custom_directives'] }}
36+
{% endfor %}
37+
{% endif %}
3238
{% if item['config']['servers'] is defined %}
3339
{% for server in item['config']['servers'] %}
3440
server {
@@ -67,6 +73,15 @@ server {
6773
{% filter indent(4) %}
6874
{{ log(server['log']) }}
6975
{%- endfilter %}
76+
{%- endif %}
77+
{% if server['custom_directives'] is defined and server['custom_directives'] is not mapping %}
78+
{% for directive in server['custom_directives'] if server['custom_directives'] is not string %}
79+
{% filter indent(4) %}
80+
{{ directive }}
81+
{% endfilter %}
82+
{% else %}
83+
{{ server['custom_directives'] }}
84+
{% endfor %}
7085
{% endif %}
7186
}
7287
{% endfor %}

‎templates/stream/upstream.j2

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ upstream {{ upstream['name'] }} {
2828
state {{ upstream['state'] }};
2929
{% endif %}
3030
{% if upstream['hash']['key'] is defined %}
31-
hash {{ upstream['hash']['key'] }}{{ ' consistent' if upstream['hash']['consistent'] is defined and upstream['hash']['consistent'] is boolean }};
31+
hash {{ upstream['hash']['key'] }}{{ ' consistent' if upstream['hash']['consistent'] is defined and upstream['hash']['consistent'] is boolean and upstream['hash']['consistent'] | bool }};
3232
{% elif upstream['least_conn'] is defined and upstream['least_conn'] is boolean %}
3333
least_conn;
3434
{% elif upstream['least_time']['response'] is defined %}
35-
least_time {{ upstream['least_time']['response'] }}{{ ' inflight' if upstream['least_time']['inflight'] is defined and upstream['least_time']['inflight'] is boolean }};
35+
least_time {{ upstream['least_time']['response'] }}{{ ' inflight' if upstream['least_time']['inflight'] is defined and upstream['least_time']['inflight'] is boolean and upstream['least_time']['inflight'] | bool }};
3636
{% elif upstream['random'] is defined %}
3737
random {{ 'two' if upstream['random']['two'] is defined and upstream['random']['two'] is boolean }}{{ (' ' + upstream['random']['method'] | string) if upstream['random']['method'] is defined }};
3838
{% endif %}

0 commit comments

Comments
 (0)