zuplo 7.7.11 → 7.7.12

package/docs/dedicated/advanced/host-header-override.mdx

@@ -0,0 +1,93 @@
+---
+title: "Managed Dedicated: Host Header Override"
+sidebar_label: Host Header Override
+---
+
+By default, the `Host` header your gateway sends to a backend is derived from
+the URL it connects to. Host header override lets your code send a `Host` header
+that differs from the hostname in the request URL, so the gateway can connect to
+one address while the backend sees the hostname it expects.
+
+This setting is only available on [Managed Dedicated](../overview.mdx) instances
+and is off by default.
+
+## When to use it
+
+Reach for this when the address you connect to and the hostname your backend
+expects aren't the same:
+
+- **Virtual-hosted backends.** A single load balancer, ingress controller, or
+  web server hosts several sites and picks one based on the `Host` header. Your
+  gateway connects to the shared address and names the site it wants.
+- **Private networking.** With
+  [private networking](../aws-private-networking.mdx), you reach a backend
+  through an internal endpoint or IP whose DNS name doesn't match the public
+  hostname the backend is configured for, such as `https://10.0.4.12` with a
+  `Host` of `api.acme.com`.
+- **Testing a new backend before DNS moves.** Point the gateway at the new
+  origin's address while sending the production `Host` header, so you can
+  validate the migration without changing public DNS.
+- **Legacy backends keyed on the hostname.** Applications that route, build
+  links, or select a tenant from the `Host` header keep working when the gateway
+  sits in front of them.
+
+:::caution
+
+An incorrect `Host` header can send traffic to the wrong site on a shared
+backend, and some applications trust the header when building redirects and
+links. Enable this setting only if you need it, and set the header to a value
+your code controls rather than one copied from client input.
+
+:::
+
+## Enable the setting
+
+Add `allowHostHeaderOverride` to the `zuplo.jsonc` file at the root of your
+project and deploy:
+
+```jsonc
+{
+  "version": 1,
+  "projectType": "managed-dedicated",
+  "allowHostHeaderOverride": true,
+}
+```
+
+The setting applies to the whole project. Without it, a `Host` header you set on
+an outbound request is ignored.
+
+:::note
+
+The `zuplo.jsonc` file isn't editable in the Zuplo Portal. Connect your project
+to [source control](../source-control.mdx) and edit the file there or push a
+local change with git. See
+[Project Configuration](../../programmable-api/zuplo-json.mdx) for the other
+settings this file supports.
+
+:::
+
+## Example
+
+Once the setting is enabled, set the `Host` header on any outbound request. This
+[custom handler](../../handlers/custom-handler.mdx) connects to an internal load
+balancer and tells it which site to serve:
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const url = new URL(request.url);
+
+  return fetch(`${environment.INTERNAL_ORIGIN}${url.pathname}${url.search}`, {
+    method: request.method,
+    body: request.body,
+    headers: {
+      ...Object.fromEntries(request.headers),
+      Host: "api.acme.com",
+    },
+  });
+}
+```
+
+With `INTERNAL_ORIGIN` set to `https://10.0.4.12`, the gateway connects to
+`10.0.4.12` and the backend receives a request for `api.acme.com`.

package/docs/programmable-api/zuplo-json.mdx

@@ -89,11 +89,14 @@ to `false`.
 
 Allow the Host header to be overridden by the client. This configuration
 defaults to `false`. This is only supported in managed dedicated environments.
-Only enable this setting if you understand the implications.
+Only enable this setting if you understand the implications. See
+[Host Header Override](../dedicated/advanced/host-header-override.mdx) for when
+to use it and an example.
 
 ```jsonc
 {
   "version": 1,
+  "projectType": "managed-dedicated",
   "allowHostHeaderOverride": true,
 }
 ```

package/docs/self-hosted/install.md

@@ -12,24 +12,22 @@ certificates from cert-manager. Before you begin, complete the
 Set these variables in the shell that you use for the installation:
 
 ```bash
-# 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'
+# 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 chart is an OCI artifact in Zuplo's registry. The same credential pulls the
-chart and the component images.
+The Zuplo Helm chart is an OCI artifact in Zuplo's registry. The same credential
+pulls the chart and the component images.
 
 ```bash
 printf '%s' "$ZUPLO_REGISTRY_KEY" |
@@ -52,7 +50,8 @@ account:
 
 deployments:
   # Parent domain for your APIs. Needs wildcard DNS:
-  #   *.api.example.com -> your ingress address
+  #   *.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:
@@ -68,12 +67,11 @@ builder:
   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.
+  # cert-manager is used for managing the lifecyle of each deployment certificate.
   enabled: true
   acme:
-    # Required when cert-manager.enabled is true. The certificate authority
-    # sends expiration warnings to this address.
+    # Required when cert-manager.enabled is true. Used to register the ACME
+    # account with the certificate authority.
     email: platform@example.com
 ```
 
@@ -91,17 +89,25 @@ zuploImageRegistry:
   password: ${ZUPLO_REGISTRY_KEY}
 
 builder:
-  username: _json_key_base64
-  password: ${ZUPLO_REGISTRY_KEY}
+  username: ${BUILDER_REGISTRY_USER}
+  password: ${BUILDER_REGISTRY_PASSWORD}
 EOF
 ```
 
-:::danger{title="Treat this file as a secret"}
+:::danger{title="Protect registry credentials"}
+
+This file contains registry credentials. Add `zuplo-secrets.yaml` to
+`.gitignore` before creating it, restrict access to the file, and delete the
+local copy after installation. Keep the credentials in your organization's
+secret manager for future upgrades.
+
+For automated installations, generate the file from CI secrets or a secret
+manager. If you store the file in Git, encrypt it with a tool such as SOPS and
+decrypt it when running Helm.
 
-The chart doesn't support `existingSecret`. It stores these values in Kubernetes
-Secrets and in the Helm release history. Don't commit this file as plaintext.
-Encrypt it with SOPS or Sealed Secrets, or generate it in CI from a secret
-store. Add it to `.gitignore` with your kubeconfig.
+Helm stores these credentials in its release history, and the chart creates
+Kubernetes Secrets from them. Restrict access to these Secrets, including Helm's
+release Secrets.
 
 :::
 
@@ -139,7 +145,8 @@ namespaces:
 
 Without `--version`, Helm selects the most recent chart available at
 installation time. Record the pinned version with `zuplo-values.yaml` so that
-you can review and reproduce upgrades.
+you can review and reproduce upgrades. Your Zuplo solutions architect will tell
+you which version to install.
 
 :::
 
@@ -156,17 +163,19 @@ NAME                    TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)
 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:
+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` |
 
-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.
+Certificate issuance requires the HTTP-01 challenge URL at
+http://<hostname>/.well-known/acme-challenge/<token> 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
 

package/docs/self-hosted/requirements.md

@@ -105,11 +105,18 @@ For HTTP-01 validation, the certificate authority must also reach the ingress on
 port 80. If your cluster can't expose port 80 to the public internet, discuss an
 alternative certificate configuration with your Zuplo solutions architect.
 
-## Access to Zuplo services
-
-The cluster needs outbound HTTPS to Zuplo services, both container registries,
-and your certificate authority. The management API hostname is the only inbound
-path.
+The cluster also needs outbound access to:
+
+- Zuplo services for deployment configuration and management API authentication.
+- Zuplo's private container registry and the public registries used by the
+  chart's bundled components.
+- Your container registry to push and pull gateway images.
+- Docker Hub and Debian package repositories to build gateway images.
+- Your ACME certificate authority to issue and renew certificates.
+
+The Helm chart installs the required components, but the cluster downloads their
+container images and gateway build dependencies. If you restrict outbound
+traffic, allow access to these dependencies.
 
 :::note
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.7.11",
+  "version": "7.7.12",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.7.11",
-    "@zuplo/core": "7.7.11",
-    "@zuplo/runtime": "7.7.11",
-    "@zuplo/test": "7.7.11"
+    "@zuplo/cli": "7.7.12",
+    "@zuplo/core": "7.7.12",
+    "@zuplo/runtime": "7.7.12",
+    "@zuplo/test": "7.7.12"
   }
 }