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
# From the Zuplo portal. See Requirements for instructions.
export ZUPLO_ACCOUNT_NAME='acme-corp'

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

# Yours.
export ZUPLO_SUBDOMAIN='api.example.com'
export ZUPLO_MANAGEMENT_HOSTNAME='zuplo-admin.example.com'
export ZUPLO_BUILD_REGISTRY='us-docker.pkg.dev/acme-corp/zuplo-gateways'
export ACME_EMAIL='platform@example.com'

Authenticate to the Zuplo registry

The 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
  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:
  # Issues and renews one certificate per deployment hostname. Leaving this on
  # is what keeps a wildcard certificate out of the picture.
  enabled: true
  acme:
    # Required when cert-manager.enabled is true. The certificate authority
    # sends expiration warnings to this address.
    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: _json_key_base64
  password: ${ZUPLO_REGISTRY_KEY}
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 and neither behind a TLS-terminating proxy:

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

Certificates can't be issued until these records resolve. cert-manager checks the challenge URL from inside the cluster before it contacts the certificate authority.

Next, verify your installation.