Services and settings

A service is one API behind GraphPilot, plain HTTP or GraphQL: one origin, one configuration (and, for GraphQL, one schema), and one cache. Each service gets its own service hostname, https://<subdomain>.<label>.graphpilot.cloud, and its own signing key.

The hostname label

<label> is your organization’s hostname label, six characters such as k7m2qp.

• Generated, not chosen. GraphPilot draws it at random when the organization is created.
• Fixed per organization. Every service of the organization is under the same label, and it never changes, also when you rename the organization or a service. Renaming a service changes only the first part of its hostname. The old hostname stops answering once the new one is set up, with no grace period, so move every client to the new hostname (or to a custom domain) before renaming.
• Never reused. After your organization is deleted, its label is not given to anyone else, so a hostname that once was yours cannot later answer for somebody else.
• Shown before you create. The Create a new service dialog shows the full hostname, label included, as you type the subdomain. Settings → General shows it for an existing service.

Existing hostnames keep working. A service created before labels existed keeps https://<subdomain>.graphpilot.cloud, and nothing about it changes until GraphPilot moves it onto the label. A move adds https://<subdomain>.<label>.graphpilot.cloud beside the old hostname, and once the new one serves, it becomes the service hostname the portal and the CLI show. The old hostname keeps answering beside it for a transition, so running clients are not interrupted, until GraphPilot switches it off. While both exist, renaming the service changes only the labelled hostname.

DNS and custom domains. Nothing changes for custom domains: the record you create for your own hostname is the one the portal shows for that domain, as before. GraphPilot manages the DNS of the service hostname itself; there is nothing to set up for it.

When the hostname starts answering. The service hostname resolves as soon as the service is created. HTTPS needs the organization’s certificate, one for all services under the label (*.<label>.graphpilot.cloud):

• The organization’s first service waits for that certificate to be issued, which can take up to an hour. Until then the hostname resolves, but HTTPS requests to it fail with a certificate error.
• Every later service uses the certificate that is already there and serves HTTPS right away.

Whether a service is plain HTTP or GraphQL is not a setting. It follows from the live deployment: one deployed without a schema makes the service plain HTTP, with GraphQL features off, and the Schema pages say No schema stored yet, or A schema was uploaded but is not live when one was uploaded (see a service without a schema). The next deployment with a schema turns them on again. Where a deployment takes its schema from when it names none is the service’s schema source.

Create a service

Permission service:edit

A service’s signing key is shown once, when the service is created: in the portal, in the dialog below, or in the output of gpilot service create. After that, the only way to get a key you can copy is to rotate it.

1. Open the organization’s Dashboard and select New service, or choose Add service under the organization in the organization switcher.

2. Fill in the Create a new service dialog:

   Field	What to enter
   Service name	A display name, for example Checkout API.
   Origin URL	The URL of your API, GraphQL or plain HTTP, for example https://api.example.com. Give only the scheme, host and port: a URL with a path, query or fragment is refused (ORIGIN_URL_PATH_NOT_ALLOWED), because GraphPilot forwards the path the client called. Which paths are GraphQL is request.graphql_paths. Without a port, GraphPilot connects to port 443 for https:// and 80 for http://.
   Subdomain	The first label of the service hostname: checkout-api gives https://checkout-api.k7m2qp.graphpilot.cloud, under your organization’s label. Lowercase letters, digits and hyphens, 2 to 63 characters, not starting or ending with a hyphen. No other service of the organization may use it. Any such name is allowed, api and www included; only a service whose hostname is directly under graphpilot.cloud has reserved names.
   Environment	Development, Staging, Production or Custom (with a name of your own), and a color. It labels the service in the portal and changes nothing about how it behaves.

3. Keep Deploy right away (no schema, default configuration) ticked (the default) to have GraphPilot deploy the service once as a plain pass-through to your origin and then look for a GraphQL API behind it; see set up a new service. Clear it to create the service without deploying anything. If the origin URL is on a private or local address (for example 10.0.0.5, 192.168.1.10, localhost or a name ending in .internal), the dialog says that the edge cannot reach it: the service is still created, but nothing is deployed for it.

4. Select Create service.

5. The Copy your signing key dialog opens. Copy the key, store it in your secret manager and give it to your origin, then select I have copied the key. With Deploy right away, the dialog says that GraphPilot deploys the service while you copy the key, and the service’s dashboard then shows the setup.

The signing key is shown once

The dialog cannot be dismissed by clicking outside it or pressing Escape, and closing it is final. Everywhere else the portal shows only the key’s prefix and its last four characters. If you lose it, generate a new one under Settings → General → Signing key and activate it once your origin accepts it. See request signing.

Reserved subdomains

A service under your organization’s label may have any valid subdomain, such as api.k7m2qp.graphpilot.cloud or www.k7m2qp.graphpilot.cloud: the label keeps it apart from every name GraphPilot uses itself.

The names below are reserved only for a service whose hostname is directly under graphpilot.cloud (https://<subdomain>.graphpilot.cloud, a service created before labels existed): names for infrastructure and tooling (api, www, mail, cdn, docs, status), and the environment and stage names people often reach for first (dev, staging, prod, test, demo, beta, sandbox). Renaming such a service to one of them is refused under Settings → General, on the Subdomain field, as reserved. A reserved word inside a longer name is fine.

All 72 reserved subdomains

admin, administrator, alpha, api, app, assets, backup, beta, blog, cd, cdn, ci, dashboard, demo, dev, devel, development, dns, docs, documentation, elastic, email, ftp, git, grafana, help, imap, internal, jenkins, kibana, localhost, logs, mail, media, monitoring, mx, mx1, mx2, ns, ns1, ns2, ns3, ns4, pop, portal, preview, private, prod, production, prometheus, public, remote, root, sandbox, secure, sftp, shop, smtp, ssl, stage, staging, static, status, store, support, svn, test, testing, tls, vpn, www, www2

The subdomain is also the service’s slug: the portal’s addresses use it, and so do the gpilot commands that take a service.

If the plan’s service allowance is used up, New service and Add service are disabled, say that all of your plan’s services are in use, and link to See plans. Services are counted across every organization your billing account funds. See Billing and usage.

A service created without Deploy right away serves nothing until its first deployment goes live. Until then its dashboard shows its checklist, which starts with the command to run, gpilot deploy, and its other pages show a short panel with the same command. If the last deployment was canceled, the panel says so and offers the command again; if one failed, it points to the deployment that says why. See the quickstart.

Set up a new service

A service created with Deploy right away is set up in five steps, shown as a Setting up <service> card at the top of its Dashboard: Create, First deployment, Detection, Configuration and Done. The state is stored by GraphPilot, not in your browser, so you can leave the page and come back, or open it on another device, and the card shows the step the setup is on. Every member who may see deployments sees the card; the buttons need the permissions named below.

1. First deployment. GraphPilot deploys the service once, without a schema and without a configuration file: every path is forwarded to your origin as plain HTTP, every setting is at its default, and only responses your origin marks cacheable with Cache-Control are cached. The card shows the build steps while it runs (usually one to two minutes). While the certificate for the service hostname is still being issued, which is the case for an organization’s first service, the card then shows Waiting for the certificate, usually for a few minutes; the service hostname answers once the certificate is issued. The deployment is listed on the Deployments page as requested by GraphPilot.

2. Detection. GraphPilot sends { __typename } through the service’s own hostname to /graphql, /api/graphql, /query and /, in that order, and asks the first path that answers as GraphQL for its schema with an introspection query. The requests leave from the edge, like all traffic to your origin, and are signed with the service’s signing key. With a runtime that recognizes them, they are not billed and not counted as traffic: see platform probes.

3. Configuration. What the card offers depends on what was found:

   Found	The card shows
   GraphQL on a path, with a schema	GraphQL found: the endpoint path, whether introspection answered, the number of types, and the gpilot.toml it would deploy (none when the path is /graphql, the default). Apply suggested configuration and schema starts a deployment with them, as your own deployment. Keep as plain HTTP leaves the service as it is.
   GraphQL on a path, no schema (introspection is off or needs credentials at your origin)	The findings, and no apply button: read the schema yourself with gpilot schema pull and deploy it with gpilot deploy.
   No GraphQL	No GraphQL endpoint detected, the service runs as plain HTTP. If your API answers GraphQL on another path, set request.graphql_paths and deploy it with your schema. Keep as plain HTTP finishes the setup; Retry detection probes again.
   No answer from the origin	The edge could not reach your origin, with GraphPilot’s IP ranges to allow at your firewall and Retry detection. The setup waits in this step until detection succeeds or you choose Keep as plain HTTP.

   A schema read by introspection carries no applied directives, such as @cacheControl, @surrogateKey or @vary. To use them, deploy your own schema.graphql.

4. Done. The card states the service hostname, that requests reach your origin, and how to deploy your own schema (gpilot deploy, or Deploy from the portal). It stays for a day and then disappears.

Apply suggested configuration and schema and Retry detection need deployment:edit; Keep as plain HTTP needs service:edit. A deployment of your own that goes live during the setup replaces it, and the card disappears. If a schema or configuration upload lands while Apply writes the suggestion, nothing is written and the message offers Try again. Apply never replaces a gpilot.toml or schema you uploaded yourself: if the newest upload of either is yours, it is refused with a message saying to set request.graphql_paths in your own gpilot.toml and run gpilot deploy.

If the setup cannot go on, the card says why and what to do:

• Not deployed: your origin is on a private address. The edge cannot reach a private or local address, so nothing was deployed. Deploy once the origin is reachable from the internet, or change it under Edit origin URL.
• The setup stopped. A deployment or the certificate failed, a step was interrupted before it could finish, the member who created the service may create services but not deployments, or the first deployment was not requested because the billing account is locked or the organization is being deleted. The card links to the failed deployment, to Edit origin URL and to Deploy from the portal, and offers Retry detection and Keep as plain HTTP where they apply.

The same setup runs from the CLI with gpilot service create.

The organization dashboard

The organization’s Dashboard is headed Services. It shows a card per service with its status (Live, Not deployed, or Alert while an alert is open), its requests and cache hit rate over the last 24 hours, and a link to the service hostname. Above the cards, a meter shows the Request units this period against your plan’s allowance, with View billing.

The onboarding checklist

Until you dismiss it, a checklist above the meter shows the organization’s steps to going live, and explains the next open one:

1. Create a service.
2. Get a service to its first cached query: a deployment of your own (requested by a member or an API key, not the automatic first deployment of the setup) of one of the organization’s services completed, a request reached a service hostname, and the edge answered a request from its cache. The step shows which of the three are done (Own deployment, First request, First cache hit) and links to the first service’s dashboard, where its checklist walks through them.
3. Read the go-live checklist: open the go-live checklist and tick I have read it.

The checklist is the same on every device and for every member of the organization. The steps that depend on traffic tick themselves within minutes of the request, and stay done once they have. The last step is the only one you tick yourself.

Under the steps, Also worth doing links to Invite your team (the Members page) and Create an API key for deploying from CI (Settings, API keys). They are not steps and are never ticked.

Dismiss appears once every step is done, for members with organization:edit. It hides the checklist for the whole organization, and it does not come back. Ticking I have read it needs no permission beyond membership.

The service dashboard

The service checklist

Until its steps are done, the top of a service’s Dashboard shows the steps that take this service to a first cached query, and explains the next open one:

1. Deploy your own schema and configuration: a deployment of this service that a member or an API key requested is live. The automatic first deployment of the setup does not count: while it is the only one, the step says the service is live as a plain pass-through and shows gpilot deploy and Deploy from the portal. Otherwise the step shows gpilot deploy, or, after a failed deployment, links to the deployment that says why.
2. Send a first request through the edge: a request reached the service hostname.
3. See a first cache hit: the edge answered a request from its cache. For a service without a schema, only responses your origin marks with Cache-Control are cached.

Steps 2 and 3 can be done before step 1, since the automatic first deployment already makes the service reachable. They keep their place in the list.

GraphPilot records the first request and the first cache hit for the organization, not for each service. The checklist therefore shows steps 2 and 3 only while the service is the organization’s only one, and only if neither was recorded before the service was created (a service that replaces a deleted one does not take over its traffic). Otherwise it shows the deployment step alone. Steps 2 and 3 tick themselves within minutes of the request.

The checklist has no Dismiss: it disappears once its steps are done. If the service’s origin URL starts with http://, it says so and links to the service’s settings, where you can register the origin with https:// instead. That warning stays after the steps are done. On a plan with custom domains, members who may manage the service’s hostnames also get a link to Serve it on your own domain.

While nothing of the service is live, the checklist is all the dashboard shows.

Traffic and performance

The service’s Dashboard covers the last 24 hours:

• Requests, Cache hit rate, Origin offload, Error rate, GraphQL error rate and p95 latency, each compared with the previous 24 hours. Each figure links into Insights for the same 24 hours, filtered to the requests behind it where one applies (cache hits, errors, responses with GraphQL errors, the slowest requests).
• Error rate and GraphQL error rate count different failures. Error rate is the share of requests answered with an HTTP status of 400 or higher. GraphQL error rate is the share of GraphQL operations whose response carried at least one GraphQL error, whatever the HTTP status, so it sees the errors that arrive in a 200, which Error rate does not. Both open Insights on the Errors column preset.
• Requests, last 24 hours, as a chart.
• Open alerts, linking to Alerts.
• Top operations: the operations called most often. Select one to open it in Insights.

Top operations is available on Jet (Starter) and above; on Glider (Free) the card says so. p95 latency also needs Jet (Starter) or above, like the p95 in Insights; on Glider (Free) its card shows a dash and says which plan includes it. The other figures are there on every plan. Like everything built from request telemetry, they count only requests that were stored; see Insights.

Service settings

Open Settings in the service’s sidebar. It has four sections: General, Domains, Alerts and Runtime.

General

Permission service:edit

The same four fields as the create dialog: Service name, Origin URL, Subdomain and Environment. Select Save changes to apply them.

The Origin URL is where GraphPilot forwards requests, whether your origin speaks GraphQL or plain HTTP. The change reaches the edge with the next deployment. Only its scheme, host and port are used; see TLS and ports.

Origin allowlist

Under the form, Origin allowlist lists the IP ranges GraphPilot’s edge calls your origin from, as IPv4 and IPv6, with Copy all. Open these at your origin’s firewall. The set changes as the network changes, and nothing warns you when it does, so read it on a schedule rather than once. See Origin allowlist.

Introspection

Introspection shows whether the edge answers schema introspection for the live deployment: Blocked (the default), Allowed, or Unknown when the portal cannot tell. It cannot be changed here: set request.introspection in your gpilot.toml and deploy, and the change takes effect with the next deployment. While it is blocked, queries that select __schema or __type are refused with INTROSPECTION_DISABLED, so GraphiQL, Apollo Studio and codegen pointed at the service hostname stop working against it. The deployed schema is always on the service’s Schema page.

Schema source

Permission service:edit

Schema source decides where a deployment takes its schema from when it names none, such as gpilot deploy without a schema file in a scripted run or New deployment with the default choice:

Setting	A deployment that names no schema
Latest upload (default)	uses the newest uploaded schema.
No schema	deploys without a schema, as plain HTTP, even if a schema was uploaded.
Introspect at deploy	reads the schema from your origin through the service’s own hostname when it builds, and deploys what it read.

Select Save to apply it from the next deployment on. A deployment that names a schema, or deploys without one, is not affected.

With Introspect at deploy:

• Introspection returns no applied directives, such as @cacheControl, @surrogateKey or @vary. Uploading your schema.graphql stays the way to deploy directives.
• Deprecated fields and enum values are read, but deprecated arguments and input fields are not, so a schema read at deploy lacks them. gpilot schema pull --url reads them too.
• If introspection fails, the deployment goes live with the newest stored schema (or without one, if none was stored), and its page says Schema from <date>, introspection failed. See a deployment’s page.
• Your origin has to answer introspection on the GraphQL path for requests from the edge. The requests are platform probes.

Danger zone: reset history

Permission service:delete

Reset history deletes the history a service has recorded and leaves the service running: it keeps serving, and its deployments, configuration, hostnames, signing key and alert rules stay as they are. Choose what goes:

Group	Deletes
Request telemetry	Every recorded request of the service, and with them what Insights shows from them: operations, clients, figures, GraphQL errors and error groups, logs, and the suggestions the filters offer.
Purge history	Every entry of the purge history, automatic and manual.
Alert history	Closed incidents in the incident history. An incident that is still open is kept, and so is one that closed less than an hour ago, so its all-clear email is still sent.

Kept in every case:

• The request counts that billing, the plan’s quota and the usage figures are based on, and every invoice. A reset never changes what is billed.
• The measurements alerting compares against, so alert rules keep working as before.
• The raw telemetry copy and the backups, for as long as a deletion keeps them.

The reset runs in the background. The dialog says when it was requested, and the history is usually gone within a few minutes. Requests that arrive in the meantime are recorded as usual, so the newest of them can survive the reset. Persisted operations show no usage until they are called again, so do not judge which ones are unused right after a reset. A reset cannot be undone.

1. Select Reset history in the danger zone of Settings → General.

2. Choose what to delete (all three are selected to start with), type the service’s name, and select Reset history.

A reset needs service:delete, which only Admins hold, and a signed-in member: API keys cannot reset history. Through the API it is the resetServiceHistory mutation. It is not in the CLI.

Danger zone: signing key

The Signing key block, in the danger zone below Delete service, shows the active key (prefix and last four characters) and runs a staged rotation: Generate a new pending key, deploy it to your origin so it accepts both keys, then Activate pending key. Cancel rotation discards a pending key. See rotating the signing key. Seeing and rotating the key needs service:edit; without it the block says so.

Danger zone: delete the service

Permission service:delete

Deleting a service takes it off the edge at once: requests to it stop being served, its deployments and configuration are removed, and its hostnames are released, so someone else can take them. Its telemetry, logs and stored files stop being readable at once and are deleted within minutes, once the service is off the edge. Some records are kept on purpose; see what a deletion keeps. It cannot be undone.

1. Select Delete service in the danger zone of Settings → General.

2. Read what will be deleted and released, type the service’s name, and select Send confirmation code.

3. Enter the 6-digit code from the email the portal sends you. It is good for ten minutes and for one deletion. Each code allows five tries; after that, send a new one. Send a new code replaces the earlier code, so enter the one from the newest email. You can request at most three codes a minute, across every deletion.

4. Review the summary and select Delete service.

From the CLI

gpilot service delete deletes a service with the same emailed code, when you are signed in as a user rather than with an API key. To take a service off the edge but keep it, see taking a service down.

Domains

Hostnames lists every hostname the service answers on, including the one GraphPilot issued, and is where you add a hostname of your own. See Custom domains.

Alerts

The alert rules GraphPilot evaluates for the service, each with a switch to turn it off. See Alerts.

Runtime

The GraphPilot proxy runtime the service runs on (Running), and the one its next deployment gets (Selection): the stable version, or a version you pin here, with its changelog. Changing the pin needs service:edit and deployment:edit.

When the choice resolves to the version the service already runs, Save stores it without asking and says Saved. The service already runs <version>. Otherwise Save asks first:

• Deploy now with <version> saves the pin and starts a deployment that rebuilds the service with its current schema and configuration on that version: Saved. A new deployment with <version> has started.
• Later (applies to the next deployment) saves the pin alone: Saved. The next deployment will use <version>. For Automatic (stable) the note names the stable version, because the next deployment takes whatever stable is then.

Closing the question saves nothing. A service that was never deployed has nothing to rebuild: Saved. The service’s first deployment will use <version>. If a deployment is still in progress when the choice matches the running version, GraphPilot starts one anyway, so the newest build carries the pin, and the note says so. See runtime versions.

Related

• Quickstart
• Request signing
• Deployments: the service’s deployments in the portal
• Custom domains