Skip to content

Commit 7666fd8

Browse files
mjangtravisamartin
mjang
and
travisamartin
authored
feat: Set up config templates for N1 Console (#1233)
* Content from F5 user vrmare in internal repo * Update content/nginx-one/nginx-configs/config-templates/author-templates.md * Update content/nginx-one/nginx-configs/config-templates/import-templates.md * Update content/nginx-one/nginx-configs/config-templates/author-templates.md * Add changelog * Apply suggestions from code review Co-authored-by: Travis Martin <[email protected]> * Apply suggestions from code review --------- Co-authored-by: Travis Martin <[email protected]>
1 parent 3271f69 commit 7666fd8

File tree

7 files changed

+1983
-0
lines changed

7 files changed

+1983
-0
lines changed

‎content/nginx-one/changelog.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,13 @@ h2 {
3030

3131
Stay up-to-date with what's new and improved in the F5 NGINX One Console.
3232

33+
## October 2, 2025
34+
35+
### You can now set up config templates
36+
37+
- Start with how you can [Author templates]({{< ref "/nginx-one/nginx-configs/config-templates/author-templates.md" >}})
38+
- Automate with our **experimental** endpoints for [NGINX One Console templates]({{< ref "/nginx-one/api/api-reference-guide/#tag/Templates" >}})
39+
3340
## September 16, 2025
3441

3542
### IPv6 endpoints for NGINX Agent and NGINX Plus usage reporting

‎content/nginx-one/nginx-configs/config-templates/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
description:
3+
title: Manage config templates
4+
weight: 400
5+
url: /nginx-one/nginx-configs/config-templates
6+
---

‎content/nginx-one/nginx-configs/config-templates/add-multiple-services.md‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
---
2+
nd-docs: null
3+
title: Add service-specific locations
4+
toc: true
5+
weight: 400
6+
type:
7+
- how-to
8+
nd-product: NGINX One Console
9+
---
10+
11+
# Overview
12+
13+
This guide shows how to extend a working submission from the [Submit Templates Guide]({{< ref "submit-templates.md" >}}) by adding server augments for new services with dedicated location augments.
14+
15+
{{< call-out "note" "Note" >}}Because you can’t retrieve previous submissions, you must include the full request with any updates.{{< /call-out >}}
16+
17+
## Import template
18+
19+
If there aren't existing augment templates that fit your needs, you will need to create and import them.
20+
21+
### New server augment template
22+
23+
Because there isn’t a server augment yet, you need to create one. This template creates dedicated server blocks for each service.
24+
25+
`http-server.tmpl`
26+
27+
```text
28+
server {
29+
listen {{ .listen_port }};
30+
server_name{{ range .server_names }} {{ . }}{{ end }};
31+
32+
{{ augment_includes "http/server/location" . }}
33+
}
34+
```
35+
36+
`schema.yaml`
37+
38+
```text
39+
$schema: "http://json-schema.org/draft-07/schema#"
40+
type: object
41+
properties:
42+
listen_port:
43+
type: integer
44+
description: "Port for the server to listen on"
45+
minimum: 1
46+
maximum: 65535
47+
default: 80
48+
server_names:
49+
type: array
50+
description: "Array of domain names for this server"
51+
items:
52+
type: string
53+
minItems: 1
54+
required:
55+
- listen_port
56+
- server_names
57+
additionalProperties: false
58+
```
59+
60+
#### Import parameters
61+
62+
When [Importing]({{< ref "import-templates.md#ready-to-import" >}}) this template allows you to set up:
63+
64+
- name: `http-server`
65+
- type: `augment`
66+
- allowed_in_contexts: `["http"]`
67+
68+
### New location augment template
69+
70+
Create a location augment template to add location blocks within each server.
71+
72+
{{< call-out "note" "Note" >}}
73+
If you already have a "health-check" location augment from earlier steps, you can add it to the new servers.
74+
{{< /call-out >}}
75+
76+
`location-proxy.tmpl`
77+
78+
```text
79+
location {{ .path }} {
80+
proxy_pass {{ .upstream_url }};
81+
proxy_connect_timeout {{ .proxy_timeout }};
82+
proxy_read_timeout {{ .proxy_read_timeout }};
83+
}
84+
```
85+
86+
`schema.yaml`
87+
88+
```text
89+
$schema: "http://json-schema.org/draft-07/schema#"
90+
type: object
91+
properties:
92+
path:
93+
type: string
94+
description: "Location path (for example, /api, /admin)"
95+
pattern: "^/.*$"
96+
upstream_url:
97+
type: string
98+
description: "Backend service URL"
99+
pattern: "^https?://[^\\s]+$"
100+
proxy_timeout:
101+
type: string
102+
description: "Proxy connection timeout"
103+
pattern: "^\\d+[smhd]?$"
104+
default: "30s"
105+
proxy_read_timeout:
106+
type: string
107+
description: "Proxy read timeout"
108+
pattern: "^\\d+[smhd]?$"
109+
default: "60s"
110+
required:
111+
- path
112+
- upstream_url
113+
additionalProperties: false
114+
```
115+
116+
#### Import parameters
117+
When [Importing]({{< ref "import-templates.md#ready-to-import" >}}) this template allows you to:
118+
119+
- name: `location-proxy`
120+
- type: `augment`
121+
- allowed_in_contexts: `["http/server/location"]`
122+
123+
## Submit to add multiple services
124+
125+
### Request structure
126+
127+
Example API request:
128+
129+
```json
130+
{
131+
"conf_path": "/etc/nginx/nginx.conf",
132+
"base_template": {
133+
"object_id": "<ID of your template object>",
134+
"values": {
135+
"backend_url": "http://example.com:8080"
136+
}
137+
},
138+
"augments": [
139+
{
140+
"object_id": "<ID of your template object>",
141+
"target_context": "http/server/location",
142+
"values": {
143+
"cors_allowed_origins": "https://app.example.com",
144+
"cors_allowed_methods": "GET, POST, PUT, DELETE, OPTIONS"
145+
}
146+
},
147+
{
148+
"object_id": "<ID of your template object>",
149+
"target_context": "http/server"
150+
},
151+
{
152+
"object_id": "<ID of your template object>",
153+
"target_context": "http",
154+
"values": {
155+
"listen_port": 80,
156+
"server_names": ["admin.example.com"]
157+
},
158+
"child_augments": [
159+
{
160+
"object_id": "<ID of your template object>",
161+
"target_context": "http/server/location",
162+
"values": {
163+
"path": "/admin",
164+
"upstream_url": "http://admin-backend:8080"
165+
}
166+
},
167+
{
168+
"object_id": "<ID of your template object>",
169+
"target_context": "http/server/location",
170+
"values": {
171+
"health_check_path": "/admin/health"
172+
}
173+
}
174+
]
175+
}
176+
]
177+
}
178+
```
179+
180+
### New config template contents
181+
182+
- **Existing augments remain:** CORS headers and the health-check location still apply to the main server.
183+
- **New server augments** Adds an extra server block.
184+
- **Service-specific routing:** The new `admin.example.com` server name has its own location blocks and routing rules.
185+
186+
### Response format
187+
188+
If the request succeeds, the response includes the following output and the rendered NGINX configuration:
189+
190+
#### Successful response (200 OK)
191+
192+
```json
193+
{
194+
"config": {
195+
"aux": [],
196+
"conf_path": "/etc/nginx/nginx.conf",
197+
"config_version": "nuZ4+d1T159/0vVV9vKaajrEw7QXc6T3fAnxKcVkC6I=",
198+
"configs": [
199+
{
200+
"files": [
201+
{
202+
"contents": "<base64_encoded_nginx_conf>",
203+
"mtime": "0001-01-01T00:00:00Z",
204+
"name": "nginx.conf",
205+
"size": 483
206+
}
207+
],
208+
"name": "/etc/nginx"
209+
},
210+
{
211+
"files": [
212+
{
213+
"contents": "<base64_encoded_nginx_conf>",
214+
"mtime": "0001-01-01T00:00:00Z",
215+
"name": "cors-headers.tmpl.4aaf36d4a643.conf",
216+
"size": 159
217+
},
218+
{
219+
"contents": "<base64_encoded_nginx_conf>",
220+
"mtime": "0001-01-01T00:00:00Z",
221+
"name": "health-check.tmpl.78346de4dae4.conf",
222+
"size": 109
223+
},
224+
{
225+
"contents": "<base64_encoded_nginx_conf>",
226+
"mtime": "0001-01-01T00:00:00Z",
227+
"name": "http-server.tmpl.81761e94d463.conf",
228+
"size": 145
229+
},
230+
{
231+
"contents": "<base64_encoded_nginx_conf>",
232+
"mtime": "0001-01-01T00:00:00Z",
233+
"name": "location-proxy.tmpl.66ebf3e1dfd9.conf",
234+
"size": 121
235+
}
236+
],
237+
"name": "/etc/nginx/conf.d/augments"
238+
}
239+
]
240+
},
241+
"errors": null
242+
}
243+
```
244+
245+
#### Rendered NGINX configuration
246+
247+
```nginx
248+
# configuration file /etc/nginx/nginx.conf:
249+
user nginx;
250+
worker_processes auto;
251+
252+
events {
253+
worker_connections 1048;
254+
}
255+
256+
http {
257+
server {
258+
listen 80;
259+
server_name admin.example.com;
260+
261+
location /admin {
262+
proxy_pass http://admin-backend:8080;
263+
proxy_connect_timeout 30s;
264+
proxy_read_timeout 60s;
265+
}
266+
267+
}
268+
269+
270+
server {
271+
listen 80;
272+
server_name _;
273+
274+
location /health {
275+
access_log off;
276+
return 200 "healthy\n";
277+
add_header Content-Type text/plain;
278+
}
279+
280+
281+
location / {
282+
proxy_pass http://example.com:8080;
283+
add_header 'Access-Control-Allow-Origin' 'https://app.example.com' always;
284+
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
285+
286+
}
287+
}
288+
}
289+
```
290+
291+
## Child augments
292+
293+
Child augments let you nest one augment inside another, creating hierarchical configurations. This is often used when a parent augment creates a container (such as a server block) that requires specific sub-configurations (such as location blocks).
294+
295+
**How child augments work**
296+
297+
When an augment template includes an `{{ augment_includes "context_path" . }}` extension point, you can provide child augments that target that context path. The child augments render only within their parent augment’s output.
298+
299+
**Key behaviors**
300+
- Child location augments apply only to their parent server.
301+
- Different servers can have different location configurations.
302+
- Each server runs independently with its own routing rules.
303+
304+
For details on designing templates with extension points, see the [Template Authoring Guide]({{< ref "author-templates.md" >}}).

0 commit comments

Comments
 (0)