Copy page

Self Hosted

Zuplo Self-Hosted

Zuplo Self-Hosted (also known as on-prem) lets you run the Zuplo API Gateway on your own cloud or private data center. It runs on Kubernetes and installs into your cluster with a single Helm chart.

Consider a self-hosted deployment when you need to:

• Control the infrastructure and deployment environment.
• Run Zuplo in a private data center or on-premises environment.
• Keep API traffic and data on your infrastructure for regulatory or data sovereignty requirements.
• Integrate with on-premises systems and networks.

How it works

Your cluster runs two groups of workloads: a small Zuplo management plane that receives deployments, builds gateway images, and manages certificates and routing, and the gateway deployments themselves, which serve your API traffic. You use the same Zuplo project format and deployment workflow as every other Zuplo deployment model.

A deployment runs partly in Zuplo and partly on your infrastructure:

Step	Runs on
Compiling your project into a gateway bundle	Zuplo
Building the container image from that bundle	Your cluster
Storing the image	Your registry
Running the gateway and serving API traffic	Your cluster

Zuplo hosts the portal and compiles the project. Your infrastructure builds, stores, and runs the container image. API requests also stay on your infrastructure.

Quick start

The installation guide uses the following configuration:

• A single cluster in one region. The cluster runs the management plane and the gateways.
• Automatic certificates from the bundled cert-manager. It issues a certificate for each deployment over HTTP-01, so the ingress must be publicly reachable on port 80. You don't need a wildcard certificate or manual renewal.
• A container registry that you provide. The in-cluster builder uses a username and password to push gateway images to the registry.

Start with this configuration to establish a working installation before you introduce infrastructure-specific changes.

Deployment models

Hybrid deployment

You run the gateway and management plane on your infrastructure, while a small set of Zuplo cloud services provides supporting features such as deployment configuration and API key management. All API traffic to your gateways stays on your infrastructure. This is the standard deployment model.

Restricted-egress environments

For environments with strict egress restrictions or stronger isolation requirements, book a meeting to review your requirements with the Zuplo team.

Responsibilities

You manage the infrastructure and apply updates. Zuplo supplies the Helm chart, component images, and product support:

Phase	Your team	Zuplo
Prepare	Kubernetes cluster, DNS records, TLS certificates (optional), container registry	Registry credentials, account configuration, installation guide
Install	Run the Helm install in your cluster	Helm chart, component images, starter configuration reviewed with your team
Operate	Cluster operations, applying updates	Updated charts and images, support

Requirements

This section lists what your team needs to prepare before installing Zuplo Self-Hosted. Use it to plan your platform and security review. The Requirements page includes a checklist and preflight commands. Your Zuplo solutions architect also reviews these items during onboarding.

Kubernetes cluster

• A cluster dedicated to Zuplo. To run Zuplo in a multi-tenant cluster, consult your Zuplo point of contact first.
• A conformant Kubernetes cluster, such as EKS, AKS, GKE, or a self-managed distribution.
• Support for Services of type LoadBalancer to expose the ingress.
• Cluster administrator access for the initial install (the chart installs CRDs and cluster-scoped RBAC).
• Zuplo builds gateway images inside your cluster. The build process runs privileged pods, so clusters that enforce a restricted Pod Security Standard cluster-wide need accommodations. Discuss this with your Zuplo solutions architect during onboarding.
• Helm 3 on the machine performing the install; supported versions are confirmed during onboarding.

DNS and TLS

You control DNS for two names, both pointing at the address of the cluster's ingress load balancer:

• A wildcard subdomain for your gateway environments, for example *.api.example.com. Every deployed environment receives its own hostname under it. Because the names aren't known before deployment, the wildcard record routes all of them to the ingress.
• A hostname for the management API, such as zuplo-admin.example.com. The Zuplo CLI and your CI/CD pipelines use this hostname to deploy.

For TLS, use the bundled cert-manager. It issues certificates from an ACME certificate authority such as Let's Encrypt. It creates one certificate for each hostname and renews the certificates automatically.

Container registry

Gateway images are built inside your cluster and pushed to a container registry that you provide. You need:

• A registry your cluster can push to and pull from (for example ACR, Google Artifact Registry, GitHub Container Registry, or a private Harbor).
• Credentials with push and pull rights for that registry, supplied at install time.

Network egress

In the hybrid deployment model, the cluster needs outbound HTTPS access to:

• Zuplo's private container registry, to pull Zuplo's component images (credentials provided during onboarding).
• Zuplo cloud services, used for deployment configuration and management API authentication.
• Your ACME certificate authority, if using automatic certificates.

The exact hostnames for your egress allow-list are provided during onboarding. If your environment can't allow this egress, book a meeting to review options with the Zuplo team.

Information from Zuplo

• Credentials to pull Zuplo component images from Zuplo's private registry.
• The Helm chart, an installation guide, and a starter configuration reviewed with your team.

You find your account name in the Zuplo portal. For instructions, see Requirements.

Observability

The chart bundles a Prometheus-based metrics stack that Zuplo components use for autoscaling gateway deployments. You can integrate your own logging and monitoring stack alongside it; gateway and component logs are written to standard output for collection by your log shipper.

Components installed in your cluster

A single Helm chart installs everything, across two namespaces.

Namespace	What runs there
zuplo-system	The Zuplo management plane: control-plane, deployer, gateway, storage, and acme-forwarder. Build Jobs run here.
zuplo	Your gateway deployments and the bundled HAProxy ingress controller, cert-manager, Prometheus stack, and prometheus-adapter subcharts.

You supply the cluster, DNS for two hostnames, and a container registry for the gateway images your cluster builds. Zuplo supplies the chart, the component images, and the credentials to pull them.

Get started

1. Review the requirements and run the preflight checks.
2. Install the Helm chart.
3. Verify the installation, including a complete deployment.
4. Upgrade to later chart versions when needed.
5. Use troubleshooting to resolve installation and deployment errors.

To discuss your specific requirements, book a meeting with the Zuplo team.