Import templates
This guide explains how to work with configuration templates in NGINX One Console.
In this guide, you will learn how to:
- Import base and augment templates into NGINX One Console
- Submit templates with values for preview rendering
- Review the rendered configuration and any validation errors
- Save the configuration as a new Staged Config in NGINX One Console
Make sure you have the following:
- Access to the NGINX One Console in your organization. See Before you begin in the Get started guide.
- API credentials for the Templates API. See Authenticate with the API.
- The
tar
command installed. - The absolute path to your NGINX configuration file (for example,
/etc/nginx/nginx.conf
). This path is required when submitting templates for preview.
This section provides step-by-step instructions to create template archives. You can import these archives into NGINX One Console with the Templates API.
Each template archive must contain:
- Exactly one
.tmpl
file (required) - contains your NGINX configuration template - One
schema.yaml
orschema.json
file (optional) - required only if your template uses variables. For more information, see Schema Definitions - No other files - additional files will be ignored or cause import failure
<archive-name>.tar.gz
│
├── <template-file>.tmpl
└── <schema-file>.yaml
Use the following convention for archive and template file names:
Name your archives to clearly reflect their specific use case:
Good Examples:
load-balancer-base.tar.gz
- Base template for load balancingreverse-proxy-base.tar.gz
- Base template for reverse proxycors-headers.tar.gz
- Augment for Cross-Origin Resource Sharing (CORS) header configurationssl-termination.tar.gz
- Augment for SSL/TLS terminationrate-limiting-http.tar.gz
- Rate limiting for HTTP contextrate-limiting-location.tar.gz
- Rate limiting for location context
Avoid Generic Names:
template.tar.gz
config.tar.gz
nginx.tar.gz
Base Templates:
- The
.tmpl
filename extension doesn’t affect the rendered output - Content always renders to the main NGINX config path specified during submission
- Use descriptive names like
reverse-proxy.tmpl
Augment Templates:
- The
.tmpl
filename becomes part of the rendered config filename. For example, filename ascors-headers.tmpl
will render as/etc/nginx/conf.d/augments/cors-headers.{hash}.conf
. - Use clear, descriptive names that indicate the augment’s purpose
Before creating template archives, see the Template Authoring Guide for guidance on:
- Choosing between base and augment template types
- Using Go template syntax
- Defining schema files for template variables
- Creating extensible templates with
augment_includes
Go custom function
Create a dedicated directory for each template to ensure clean archives:
# Create your template workspace
mkdir -p templates/reverse-proxy-base
cd templates/reverse-proxy-base
Create your template and schema files in the directory:
# Create template file
cat > reverse-proxy.tmpl << 'EOF'
user nginx;
worker_processes auto;
events {
worker_connections 1048;
}
http {
server {
listen 80;
server_name _;
location / {
proxy_pass {{ .backend_url }};
proxy_set_header Host $host;
}
}
}
EOF
# Create schema file (only if template uses variables)
cat > schema.yaml << 'EOF'
$schema: "http://json-schema.org/draft-07/schema#"
type: object
properties:
backend_url:
type: string
description: "Backend server URL"
required:
- backend_url
additionalProperties: false
EOF
ImportantAlways create archives from within the template directory to ensure files are at the root level.
# Create archive with files at root level
tar -czf ../reverse-proxy-base.tar.gz *
# Verify archive contents (should show files at root, no directories)
tar -tzf ../reverse-proxy-base.tar.gz
Before importing, verify your archive structure:
# Check archive contents
tar -tzf reverse-proxy-base.tar.gz
# Extract to temporary location for verification
mkdir -p /tmp/verify-archive
tar -xzf reverse-proxy-base.tar.gz -C /tmp/verify-archive
ls -la /tmp/verify-archive/
Expected contents of the compressed archive:
reverse-proxy.tmpl
schema.yaml
### Complete example workflow
Here's a complete example creating multiple related templates:
```bash
# Create workspace
mkdir -p templates && cd templates
# Create base template
mkdir reverse-proxy-base && cd reverse-proxy-base
cat > reverse-proxy.tmpl << 'EOF'
user nginx;
worker_processes auto;
events {
worker_connections 1048;
}
http {
{{ augment_includes "http" . }}
server {
listen 80;
server_name _;
{{ augment_includes "http/server" . }}
location / {
proxy_pass {{ .backend_url }};
{{ augment_includes "http/server/location" . }}
}
}
}
EOF
cat > schema.yaml << 'EOF'
$schema: "http://json-schema.org/draft-07/schema#"
type: object
properties:
backend_url:
type: string
description: "Backend server URL"
required:
- backend_url
additionalProperties: false
EOF
tar -czf ../reverse-proxy-base.tar.gz *
cd ..
# Create CORS augment template
mkdir cors-headers && cd cors-headers
cat > cors-headers.tmpl << 'EOF'
add_header 'Access-Control-Allow-Origin' '{{ .cors_allowed_origins }}' always;
add_header 'Access-Control-Allow-Methods' '{{ .cors_allowed_methods }}' always;
EOF
cat > schema.yaml << 'EOF'
$schema: "http://json-schema.org/draft-07/schema#"
type: object
properties:
cors_allowed_origins:
type: string
default: "*"
cors_allowed_methods:
type: string
default: "GET, POST, PUT, DELETE, OPTIONS"
required:
- cors_allowed_origins
- cors_allowed_methods
additionalProperties: false
EOF
tar -czf ../cors-headers.tar.gz *
cd ..
# Create augment without variables
mkdir health-check && cd health-check
cat > health-check.tmpl << 'EOF'
location /health {
access_log off;
return 200 "healthy\n";
add_header Content-Type text/plain;
}
EOF
# No schema.yaml needed - template has no variables
tar -czf ../health-check.tar.gz *
cd ..
# Final structure
ls -la *.tar.gz
-
Do not create nested directories in archives
bash# Avoid - nested directory structure is not supported tar -czf template.tar.gz template-dir/ # Correct - keep files at root level cd template-dir && tar -czf ../template.tar.gz *
-
Do not include unnecessary files
bash# Avoid - hidden files, backups or other file extensions will be ignored tar -czf template.tar.gz *~ .* *.bak *.tmpl schema.yaml # Correct - only include required files tar -czf template.tar.gz *.tmpl schema.yaml
-
Include a schema for templates with variables
- If your
.tmpl
file contains{{ .variable }}
, you must include a schema file. - The import is rejected without a valid schema.
- If your
-
Do not include multiple template files in one archive
- Each archive must contain exactly one
.tmpl
file - Create separate archives for related templates
- Each archive must contain exactly one
After creating the archives, import them using the Import a template API operation.
In addition to your template archive, the import API requires several parameters. Read the API specification for full details, but the key parameters include:
name (required):
- A unique name for the template within your organization. For clarity, use the same name as the archive (without the extension), for example,
reverse-proxy-base
,cors-headers
, orhealth-check
.
type (required):
base
- For main NGINX configuration templatesaugment
- For templates that extend base configurations
For Augment Templates Only:
- allowed_in_contexts - Specify which contexts this augment can be included in (for example,
http
,http/server
, orhttp/server/location
). Knowing where an augment fits in the NGINX configuration structure is crucial for integration. See the Template Authoring Guide for details on contexts and designing augments that integrate with base templates.
During import, the system will validate:
- Archive structure (one .tmpl file, optional schema)
- Template syntax
- Schema validity (if provided)
- Variable references match schema definitions
ImportantTheallowed_in_contexts
parameter is required to import augment templates. The import process checks that this parameter is included, but it doesn’t confirm whether the contexts are valid for your template’s NGINX directives. Context validation happens during template submission. Ensure your specified contexts match where your NGINX directives are allowed to appear to avoid submission errors.
If the import succeeds, you’ll receive a response like this:
{
"allowed_in_contexts": [],
"augment_includes": [
"http",
"http/server",
"http/server/location"
],
"created_at": "2025-09-25T19:20:47.473935Z",
"description": "",
"name": "reverse-proxy-base",
"object_id": "tmpl_0rQSkSNSTamthLQVtSZb1g",
"type": "base"
}
{
"allowed_in_contexts": [
"http/server"
],
"augment_includes": [],
"created_at": "2025-09-25T19:13:07.977943Z",
"description": "",
"name": "health-check",
"object_id": "tmpl_rT6Ul8RvQtSZPkNfsIExPQ",
"type": "augment"
}
{
"allowed_in_contexts": [
"http/server/location"
],
"augment_includes": [],
"created_at": "2025-09-25T18:22:18.149122Z",
"description": "",
"name": "cors-headers",
"object_id": "tmpl_AFVNBQcoRDeV9jk9panxbw",
"type": "augment"
}