Nginx

Overview

Nginx is a high-performance web server and reverse proxy. This template deploys Nginx as a stateless reverse proxy that routes incoming requests by path to other workloads in the same GVC, so several internal services can share one public endpoint. The nginx.conf is generated from your locations values and mounted into the container from a secret. A default install also deploys a small example backend and routes every request to it, so you can confirm the proxy works before pointing it at your own services.

This template does not create a GVC. It deploys into an existing GVC that you already have, and every workload it proxies to must already exist in that same GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-nginx`	Nginx reverse proxy on port `80` (serverless, autoscaling), open to the internet	—
Secret	`RELEASE_NAME-nginx-config`	Opaque secret holding the generated `nginx.conf`, mounted at `/etc/nginx/nginx.conf`	—
Identity	`RELEASE_NAME-nginx-identity`	Identity bound to the proxy workload	—
Policy	`RELEASE_NAME-nginx-policy`	Grants the identity `reveal` on the configuration secret only	—
Workload	`RELEASE_NAME-example`	Example backend that receives all `/` traffic; reachable only from the proxy	`enableExample: true` (the default)

Prerequisites

None for a default install. To proxy to your own services, each target workload must already exist in the same GVC, and its internal firewall must allow traffic from RELEASE_NAME-nginx (for example same-gvc, or a workload list that includes the proxy).

Installation

Install the template into an existing GVC. No --set values are required:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/nginx \
  --version 1.1.2 --gvc GVC_NAME

To install using another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Proxy Workload

proxyWorkload:
  image: nginx:1.31.4 # pinned: `latest` makes installs non-reproducible
  port: 80
  capacityAI: false
  timeoutSeconds: 5

proxyWorkload.image — the Nginx container image.
proxyWorkload.port — the container port exposed by the workload. Leave it at 80: the generated nginx.conf listens on 80 and the health probes check port 80, neither of which follows this value.
proxyWorkload.capacityAI — enables Control Plane CapacityAI on the proxy workload.
proxyWorkload.timeoutSeconds — the workload request timeout in seconds.

Resources

resources:
  cpu: 100m
  memory: 128Mi

resources.cpu / resources.memory — the CPU and memory limit for each Nginx replica.

Autoscaling

autoscaling:
  minScale: 1
  maxScale: 1
  maxConcurrency: 1000

autoscaling.minScale / autoscaling.maxScale — the minimum and maximum replica count. The proxy is stateless, so raising maxScale scales it horizontally.
autoscaling.maxConcurrency — the maximum number of concurrent requests per replica.

The scaling metric is fixed in the chart: CPU, with a 50 percent target.

Example Backend

enableExample: true # set to true to deploy an example backend workload and route all traffic to it

When true, the chart deploys RELEASE_NAME-example and routes every / request to it. Set it to false before routing to your own services; otherwise the example keeps the / route.

Locations

locations: [] # add your own proxy targets here
  # - path: /
  #   workload: my-workload
  #   port: 8080
  #   regexModifier: ""

Each entry becomes one Nginx location block that forwards matching requests to a workload in the same GVC:

Field	Description
`path`	Path to match, such as `/` or `/api`
`workload`	The bare name of the target workload in the same GVC
`port`	The port the target workload listens on
`regexModifier`	An Nginx location modifier: empty for prefix matching, `~` for a case-sensitive regex, `~*` for a case-insensitive regex

Enter only the workload name in workload. The chart builds the fully qualified internal hostname itself, WORKLOAD_NAME.GVC_NAME.cpln.local, and uses it for both the upstream address and the Host header sent to the target. Example routing two paths to two services:

enableExample: false

locations:
  - path: /
    workload: my-workload
    port: 8080
    regexModifier: ""
  - path: /api
    workload: my-api
    port: 3000
    regexModifier: ""

Built-in Routes

Two routes are always present, whatever locations contains:

Route	Response
`/health`	`200` with `{"success":true,"message":"OK"}`; used by the liveness and readiness probes
`/fail`	`500` with `{"success":false,"message":"Error"}`

Any 500, 502, 503 or 504 from an upstream workload is replaced with the /fail response, so the client sees the JSON error body rather than the upstream page.

Connecting

What	Address	Notes
Public endpoint	`https://CANONICAL_ENDPOINT`	Always open to the internet. Read it from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-nginx --gvc GVC_NAME -o yaml`.
Private tunnel	`cpln port-forward RELEASE_NAME-nginx 8080:80 --gvc GVC_NAME`, then `http://localhost:8080`	Useful for testing routes from your machine.
Other workloads in the GVC	Not reachable	The chart opens no internal access to the proxy, so other workloads cannot reach it. Use its public endpoint.
Credentials	None	The proxy has no login. Any authentication is up to the services behind it.

Read the canonical endpoint:

cpln workload get RELEASE_NAME-nginx --gvc GVC_NAME -o yaml

Then check the built-in health route:

curl -s https://CANONICAL_ENDPOINT/health

A response of {"success":true,"message":"OK"} means Nginx is serving. With the example backend enabled, a request to https://CANONICAL_ENDPOINT/ returns the example greeting page.

Operations

Changing the Routing

The nginx.conf lives in the RELEASE_NAME-nginx-config secret and is rebuilt from your values on every Helm upgrade. Edit locations (and enableExample) in your values file, then upgrade:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/nginx \
  --version 1.1.2 --gvc GVC_NAME \
  -f values.yaml

The values file must use the chart’s nesting, exactly as the blocks in Configuration show. A flat dotted key is accepted without error and silently changes nothing. The configuration is mounted as a file, and a running replica keeps the file it started with. Force a redeployment so every replica starts with the new nginx.conf:

cpln workload force-redeployment RELEASE_NAME-nginx --gvc GVC_NAME

Then confirm a route you changed answers on the public endpoint. Whether the upgrade alone restarts the proxy has not been verified on this template, so run the redeployment every time. Edit routing through Helm values only. Whether a later upgrade overwrites a hand edit to the secret has not been verified, so keep your routing in your values file and re-check the secret after every upgrade.

Upgrading From 1.1.1 or Earlier

Versions 1.1.1 and earlier defaulted proxyWorkload.image to nginx:latest. Version 1.1.2 pins it to nginx:1.31.4, so an upgrade that does not set the image restarts the proxy on the pinned version. The proxy holds no data, so nothing needs to be migrated. To keep a specific image, set proxyWorkload.image explicitly.

Scaling and Availability

The proxy is stateless, so it scales horizontally. The shipped default runs exactly one replica (minScale: 1, maxScale: 1), which means a restart or redeployment briefly interrupts traffic. Set autoscaling.minScale to 2 or more for an endpoint other systems depend on, and raise autoscaling.maxScale to let it scale out under load.

Troubleshooting

Every request returns the example page

Symptom: You added locations, but requests to / still return the example greeting page.Cause: enableExample is still true, so the example backend keeps the / route.Fix: Set enableExample: false, run a Helm upgrade, then force a redeployment as described in Changing the Routing.

A route returns the JSON error body

Symptom: Requests to one of your paths return 500 with {"success":false,"message":"Error"}.Cause: The upstream returned a 5xx or could not be reached. The usual reasons are a workload value that does not match the target name exactly, a wrong port, or a target whose internal firewall does not allow RELEASE_NAME-nginx.Fix: Check that the target exists in the same GVC and listens on the configured port, put only the bare workload name in workload, and allow the proxy in the target’s internal firewall. Read the proxy logs to see the upstream error:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-nginx"}' --limit 50 --since 10m

The proxy never becomes ready after a routing change

Symptom: After an upgrade the proxy restarts repeatedly, while cpln helm upgrade itself reported success.Cause: locations is written into nginx.conf as-is, so a malformed entry is only caught when Nginx starts. Two entries with the same path, or a / entry while enableExample is true, produce a duplicate location that Nginx refuses to load.Fix: Read the startup error in the logs, correct the entry in your values, and upgrade again:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-nginx"} |= "emerg"' --limit 50 --since 10m

cpln workload get-deployments RELEASE_NAME-nginx --gvc GVC_NAME -o yaml

A routing change has no effect

Symptom: The upgrade succeeded, but the proxy still routes the old way.Cause: The running replicas are still using the nginx.conf they started with.Fix: Force a redeployment:

cpln workload force-redeployment RELEASE_NAME-nginx --gvc GVC_NAME

Important Notes

Set enableExample: false before routing to your own services; the default sends all / traffic to the example backend.
Put only the bare workload name in locations[].workload; the chart appends .GVC_NAME.cpln.local itself.
Each target workload’s internal firewall must allow RELEASE_NAME-nginx, or its route returns the JSON error body.
The proxy is always open to the internet; there is no value to make it private.
Leave proxyWorkload.port at 80; Nginx and its health probes are fixed to that port.
After changing routing, force a redeployment so the replicas load the new nginx.conf.
The example backend image, gcr.io/knative-samples/helloworld-go, publishes only :latest and cannot be pinned; it does not affect the proxy.

External References

Nginx Documentation

Official Nginx documentation

Nginx Location Directive

How location paths and regex modifiers are matched

Nginx Reverse Proxy Guide

Proxying requests to upstream servers

Nginx Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Proxy Workload

Resources

Autoscaling

Example Backend

Locations

Built-in Routes

Connecting

Operations

Changing the Routing

Upgrading From 1.1.1 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References

Nginx Documentation

Nginx Location Directive

Nginx Reverse Proxy Guide

Nginx Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Proxy Workload

​Resources

​Autoscaling

​Example Backend

​Locations

​Built-in Routes

​Connecting

​Operations

​Changing the Routing

​Upgrading From 1.1.1 or Earlier

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Nginx Documentation

Nginx Location Directive

Nginx Reverse Proxy Guide

Nginx Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Proxy Workload

Resources

Autoscaling

Example Backend

Locations

Built-in Routes

Connecting

Operations

Changing the Routing

Upgrading From 1.1.1 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References