All posts

Deploying without knowing Kubernetes: how Zeabur hides Deployment, Service, and Ingress

Want teammates who don't know Kubernetes to ship their own services? Zeabur's open-source 2.0 doesn't invent a new object model. It changes the questions the form asks, the words on screen, and what it says when something fails. Seven practices from its source code that an internal deployment platform can borrow, and what each one costs.

"I have an API to ship. It needs PostgreSQL and a public URL. CI has already pushed the image to the company registry. What do I do next?"

If you build an internal deployment platform, developers ask you this all the time. The service will end up as a Deployment, a Service, and an Ingress, but you want developers to ship it themselves without learning those first.

Zeabur 2.0, open-sourced in October 2026, is a useful example because it doesn't invent its own service model. The form creates standard Kubernetes objects with no Zeabur-specific fields. The official docs also say Zeabur doesn't have its own database: the projects and services on screen are read directly from the cluster, and the objects stay after Zeabur is removed.

So its abstraction isn't in the objects. It's in what the user sees: what the form asks, which answers the platform looks up itself, which words appear on screen, and what it says when something fails. This article collects seven practices from the source code. Each one uses the developer from the opening as an example and covers what it costs to follow.

The scenario is hypothetical. I didn't install or run Zeabur. Everything here comes from the source code (commit d4bd01b, version 0.1.1, still pre-alpha) and the official docs, and the latest version may differ. Quotes from the source, the development guidelines, the docs, and the English UI are verbatim.

1. Ask questions users can answer, and let objects follow from the answers

The most direct way to wrap YAML in a form is one form field per Kubernetes field. Developers still can't fill in that form, because each field requires understanding the object behind it.

Zeabur asks questions developers can answer instead, starting with "what do you have?" The New menu offers Docker image, Deploy from Git, Upload a folder, Docker Compose, App template, and databases. None of them is called Deployment or Ingress; creating from YAML sits last, under Advanced.

The developer has an image, so they pick Docker image. The form then asks for the image, a name, a port, and whether to add a public domain; environment variables, volumes, size, and the rest are under More settings. In the browser, these answers become a set of objects:

What the developer answersObject created
Image, nameDeployment
PortService, plus a TCP readiness probe on the container
Public domainIngress, with TLS when the cluster has a cert-manager issuer
Environment variablesSecret <name>-env
VolumePersistentVolumeClaim
Size: small, medium, or largerequests and a memory limit

The developer answers "should it accept connections?" and "should it be reachable from outside?"; the Service and the Ingress follow from those answers. Leave the port empty and it's a background service that takes no connections, with only a Deployment.

What can't be done is said before the form is filled in, too. If the cluster doesn't have a PostgreSQL operator yet (Zeabur uses CloudNativePG), the option says "Install … first" and opens the installation steps. An option the user's role can't use is still shown, but disabled, with the role that can use it. The developer never fills in a whole form only to fail at the last step.

Once the questions change, the platform has to maintain the rules that turn answers into objects. The image, Git, and Compose entry points all end up as Deployments, so they have to share those rules; otherwise the same answers coming in through different entry points produce different objects.

2. What users can't answer, the platform looks up

Some questions are still unanswerable in plain words: which port does the service listen on? Which "security" option should I choose? Zeabur has the platform look it up and pre-fill what it finds.

Port: once an image is entered, Zeabur reads the port the image declares, the Dockerfile's EXPOSE, from the registry and fills it in. Private company images work too, using the registry credentials the developer typed or an existing pull Secret in the project.

Security: the form offers only two options, Strict and Compatible, which map to the restricted and baseline Pod Security levels. The default depends on the user the image runs as. Only a numeric UID other than 0 (such as USER 1000) defaults to Strict; a user named by name, like USER app, defaults to Compatible even if it isn't root.

The reason is the kubelet. With runAsNonRoot set, the kubelet can't tell from a name whether the user is root, so it refuses to start the container. If the platform always defaulted to Strict, a developer's first deployment of a USER app image would run into an error about runAsNonRoot.

Both inferences follow three principles:

  • Fill only empty fields: "The person's own value always wins."
  • Don't block deployment when the lookup fails. If the registry can't be reached, the developer types the port. In the source's words, "deploying never waits on it."
  • Explain the basis. The form says why it chose Strict or Compatible, and the choice can still be changed before creating.

A wrong guess is worse than no guess, so defaults should lean toward whatever won't break the first deployment, even when that side is less secure.

3. Make trade-offs for users, but tell them the consequences

Some Kubernetes constraints are ones users shouldn't need to know about, yet they're easy to trip over. Zeabur writes these constraints into the code that creates objects, so users can't pick a combination that breaks, and then states the consequence in plain words.

Suppose the developer's API needs to keep uploaded files, so they add a volume in the form. The form creates a ReadWriteOnce PVC, and with the default RollingUpdate, a new replica scheduled to another Node can't mount the disk. So whenever there's a volume, Zeabur fixes replicas at 1 and switches the update strategy to Recreate. The developer doesn't need to know any of this, but the docs state the consequence: "During an update, the old replica stops before the new one starts. The service is unavailable during that time."

Size is a trade-off too. The small, medium, and large sizes set only a memory limit, with no CPU limit. Neither the source nor the docs give a reason. My reading: a CPU limit can throttle a service with low average usage during bursts, which is hard to diagnose even for people who know Kubernetes well (see CPU is only 30% used, so why is it throttled?); using too much memory gets a container killed, so memory needs a limit.

Making the same choice for everyone always blocks someone. A service that needs two replicas and a disk can't be set up in the form; it has to go through YAML (section 7).

4. Users pick which database to connect, and the platform does the wiring

The developer from the opening also needs PostgreSQL. A connection needs the Secret's name and key and the database's address. The developer doesn't know them, but the platform can look them all up: the database and the service are in the same project, and it can read the objects on both sides. So Zeabur doesn't ask for a connection string, only which database to connect.

The developer can tick the services to connect while creating the PostgreSQL database, or later click Connect to a service on the database page. Each ticked service gets DATABASE_URL, whose value references the Secret CloudNativePG created:

env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: <the database's Secret>
        key: uri

The developer doesn't need to know the Secret's key or the DNS name of the database's Service, and the password never appears in plain text in the Deployment. Variable names follow Railway's convention: MONGO_URL for MongoDB, REDIS_URL for Dragonfly.

The wiring code has to follow each operator's Secret format. For PostgreSQL, it references the full connection string CloudNativePG provides; for other databases, it first reads the password into a variable, then builds the URL with $(VARIABLE). Each additional database means another way of wiring to maintain.

5. Translate only the words people see every day

The first four practices get the service built and connected to its database. Once it's live, the developer looks at the service page every day, and Kubernetes objects keep showing up in forms and on service pages. Keep every Kubernetes name and the developer can't follow; translate all of them and you create a vocabulary nobody recognizes.

Zeabur's wording guidelines give plain words to only four kinds people meet every day: Pod is replica, PersistentVolumeClaim is disk, Secret is secret, and ConfigMap is config file. Other kinds and fields, such as Deployment and replicas, stay as they are. Kind names appear only in YAML, on the Objects page, and as a small label beside the plain word.

The reasoning is to avoid inventing a middle word that neither side uses: "a professional searches for the kind, a beginner for the plain word." If you renamed Ingress to "public entrance," people who know Kubernetes couldn't find it, and people who don't would understand it no better.

Two other rules in the guidelines can be used as they are:

  • One term per concept. Service means what the user deploys; when the Service object is meant, it's always written "Kubernetes Service."
  • Show the real value instead of explaining it. Display api.shop.svc.cluster.local:8080 with a copy button, rather than explaining what a private address is.

These rules live in a guidelines document in the repo, along with a term list. Wording has to be settled before the screens are built. If each screen is translated on its own and unified later, every screen has to be changed again.

6. When something fails, translate the error and say who can fix it

When a service fails, Kubernetes reports CrashLoopBackOff, OOMKilled, or ImagePullBackOff. If the platform only wraps the creation flow, the developer still has to understand Kubernetes at this point, or go back to the platform team.

Zeabur turns events and status into diagnoses. Each diagnosis has a cause, a why, a fix, and the status and events it was based on. Suppose the developer's API exits on startup because it can't read an environment variable. The UI says (the service name and the count are illustrative):

  • Cause: "api keeps crashing and restarting."
  • Why: "It has restarted 7 times; the cluster starts it again each time, waiting longer between tries, up to 5 minutes by default."
  • Fix: "The error is in the logs of the run before the restart."

The original reason and exit code are still there, under Raw error, which is collapsed by default. The runAsNonRoot error from section 2 gets the same translation: if the developer switches a USER app image to Strict, they see "api can't start: the service's security is Strict, and its image names its user by name, so the cluster can't tell it isn't root." The fix is to specify the user by number, or switch back to Compatible.

The part of the diagnosis most worth borrowing is that "where the problem is" and "who can fix it" are two separate fields. The source explains why: "A person must not read a full node or an unreachable registry as a bug of their own."

SituationWhere the problem isWho can fix it
The program keeps exiting with a non-zero codeApplication codeThe user
A ResourceQuota blocks it, or no Node has roomClusterCluster administrator
Nodes can't reach the registryRegistryCluster administrator
Killed when the Node ran out of memory, with no memory limit setClusterThe user

The last row shows why the split matters. The Node as a whole ran out of memory, but what prevents it from happening again is a memory limit on the service. With a single field, you either blame the developer for a cluster problem or push something the developer can fix onto the administrator. When an administrator is needed, the fix starts with "This needs a cluster administrator: ", and the main button is Copy diagnosis, so the developer can hand the whole diagnosis to the right person.

When a URL doesn't open, there's no single error to translate. Zeabur instead checks along the request path, from DNS down to ready replicas, and points out which hop broke; a hop it can't check, such as a domain behind a CDN, is marked unconfirmed, not failed.

Diagnoses have to be written one error at a time, and they can never cover every case. Zeabur keeps an Unexplained diagnosis for the rest, so the raw error message is never the only explanation on screen.

7. When the form isn't enough, fall back to plain Kubernetes

Every abstraction has things it can't do. Zeabur doesn't invent another layer for those cases; it lets people fall back to plain Kubernetes:

  • Several tabs on the service page have a second view: a terminal next to the logs, events next to the deployment history, YAML next to the settings.
  • The form has no field for a start command. To change command and args, switch to YAML. For fields the form doesn't have, click Edit as YAML, and the current form contents come along. These edits go through Review changes, just like the form.
  • Objects managed by Helm, Argo CD, or Flux can only be restarted from the UI; changes go back to the original tool.

Because the form creates standard objects to begin with, falling back to YAML doesn't expose a platform-private format. The docs include equivalent YAML, and applying it with kubectl apply gives the same result as the form.

Falling back to YAML also means leaving the form's protection. The trade-offs section 3 made for the developer, such as volumes and replica count, are the developer's own responsibility in YAML.

Conclusion: seven practices

Back to the developer from the opening. On Zeabur, the developer answers "what do I have?", "should it accept connections?", "should it be reachable from outside?", and "which database should it use?" from start to finish; the Deployment, Service, Ingress, and Secret follow from the answers. When something goes wrong, the screen tells the developer the cause, what to do, and who should handle it.

If you're building an internal deployment platform, you can check it against these seven practices:

  1. Ask questions users can answer, and let objects follow from the answers; say what can't be done before the form is filled in.
  2. Look up what users can't answer: the user's value wins, a failed lookup doesn't block deployment, and the basis is explained.
  3. Write Kubernetes constraints into the code that creates objects, and state the consequences of trade-offs made for users in plain words.
  4. To connect a database, users only pick which one; the platform generates connection variables that reference the Secret.
  5. Translate only the words people see every day, with one term per concept.
  6. Translate errors into causes and fixes, and separate "where the problem is" from "who can fix it."
  7. When the form isn't enough, fall back to plain Kubernetes; the output is always standard objects.

This article covers only the screens and the object-creation side. What 2.0 pays for not keeping its own state, and how it shares the same objects with Helm, Argo CD, and kubectl, are separate topics.

References

The source is pinned to commit d4bd01b of zeabur-oss/zeabur, listed by section:

Read more posts