Copy page

Self Hosted

Install

Use this guide to install Zuplo Self-Hosted in a single cluster with automatic certificates from cert-manager. Before you begin, complete the requirements.

Set environment variables

Set these variables in the shell that you use for the installation:

Code

# Provided by Zuplo during onboarding.
export ZUPLO_CHART_VERSION='<chart version from onboarding>'
export ZUPLO_REGISTRY_KEY='<base64 credential from onboarding>'

# Provided by you

# These are the credentials to your gateway image registry.
export BUILDER_REGISTRY_USER='your-example-registry-user'
export BUILDER_REGISTRY_PASSWORD='your-example-registry-user-pw'

Authenticate to the Zuplo registry

The Zuplo Helm chart is an OCI artifact in Zuplo's registry. The same credential pulls the chart and the component images.

Code
printf '%s' "$ZUPLO_REGISTRY_KEY" |
  helm registry login us-docker.pkg.dev -u _json_key_base64 --password-stdin

Code
Login Succeeded

Create the values file

Create zuplo-values.yaml and commit it to your infrastructure repository. Pass this file to Helm during every upgrade.

Code
account:
  # Your Zuplo account name.
  name: acme-corp

deployments:
  # Parent domain for your APIs. Needs wildcard DNS:
  #   *.api.example.com -> your ingress address. For example, a preview
  #  domain deployment might look like your-preview-branch-abs0ef.api.example.com.
  subdomain: api.example.com

managementApi:
  # Where deployments are pushed IN. Must be reachable by Zuplo and your CI/CD.
  hostname: zuplo-admin.example.com
  dedicatedIngress:
    enabled: false

builder:
  # Where the in-cluster builder pushes built gateway images.
  provider: docker
  registry: us-docker.pkg.dev/acme-corp/zuplo-gateways
  secretName: builder-secret

cert-manager:
  # cert-manager is used for managing the lifecyle of each deployment certificate.
  enabled: true
  acme:
    # Required when cert-manager.enabled is true. Used to register the ACME
    # account with the certificate authority.
    email: platform@example.com

Create the credentials file

The chart creates Kubernetes Secrets from Helm values. Put credentials in a separate values file so that you don't commit them with the rest of the configuration.

Code
cat > zuplo-secrets.yaml <<EOF
zuploImageRegistry:
  registry: us-docker.pkg.dev
  username: _json_key_base64
  password: ${ZUPLO_REGISTRY_KEY}

builder:
  username: ${BUILDER_REGISTRY_USER}
  password: ${BUILDER_REGISTRY_PASSWORD}
EOF

Install the chart

Install the pinned chart version:

Code
helm install zuplo \
  oci://us-docker.pkg.dev/zuplo-customers/self-hosted/helm-charts/zuplo \
  --version "$ZUPLO_CHART_VERSION" \
  --namespace zuplo --create-namespace \
  -f zuplo-values.yaml \
  -f zuplo-secrets.yaml

Code
Pulled: us-docker.pkg.dev/zuplo-customers/self-hosted/helm-charts/zuplo:<version>
NAME: zuplo
LAST DEPLOYED: ...
NAMESPACE: zuplo
STATUS: deployed
REVISION: 1

The installation takes one to two minutes and creates resources in two namespaces:

• zuplo is the release namespace created by --create-namespace. It contains gateway deployments and the subcharts.
• zuplo-system is created by the chart and contains the Zuplo management plane.

Point DNS to the load balancer

Get the address of the LoadBalancer Service created by the chart:

Code
kubectl get svc zuplo-haproxy-ingress -n zuplo

Code
NAME                    TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                      AGE
zuplo-haproxy-ingress   LoadBalancer   10.128.82.11   203.0.113.24     80:31670/TCP,443:31011/TCP   50s

Create two DNS A records pointing at EXTERNAL-IP, both resolving publicly:

Type	Name	Value
A	*.api.example.com	203.0.113.24
A	zuplo-admin.example.com	203.0.113.24

Certificate issuance requires the HTTP-01 challenge URL at http:///.well-known/acme-challenge/ to be reachable from inside the cluster and the public internet. If you use a proxy such as Cloudflare, configure it to forward these requests to the cluster without authentication or changes to the challenge response. cert-manager checks the URL before asking the certificate authority to validate the challenge.

Verify your installation

Use the Zuplo self-hosted doctor to check the installation. Doctor is a CLI that reads your installation through your kubeconfig and probes its DNS, TLS, and HTTP endpoints. It checks the Helm release, the Configuration resource, Deployment health, ingress reachability, certificate issuance, DNS records, the management API, and the builder configuration. It reads the installation and doesn't change it.

Download the archive for your machine from the releases page, verify its checksum, extract it, and run the full suite against your current kubeconfig context:

Code
./zuplo-self-hosted-doctor verify

Doctor exits 0 when no check failed, 1 when a check failed, and 3 when it couldn't run. Each warning and failure names a diagnostic step and links to the matching entry in Troubleshooting.

To also check authenticated access to the management API, set ZUPLO_API_KEY in your shell before running verify. Without a key, Doctor checks only that unauthenticated requests are rejected.

The repository's README covers selecting individual checks, comparing a local values file, private certificate authorities, and JSON output.