Managed services

A managed service is a database, a cache, a message broker or an object store that Harthelm runs for your team: you say what you want, Harthelm creates it, keeps its secret, connects your services to it and backs it up every night.

The catalogCopy Anchor Link

Managed services in the console's navigation has two tabs: the team's Managed services and the Catalog. The catalog lists the providers your installation offers, each with its versions, plans, settings and what it can do (pause, nightly backups, rotate secrets). hart lists the team's services with hart ms list.

Harthelm has five built-in providers. Your administrator may turn some off or offer more providers and plans.

Plans, as CPU / memory / storage; tiny is the default:

Every instance is a single server, without replicas: a restart, a Rotate or a node drain interrupts it for a few seconds (S3 for about 20). What else to know per provider:

• Valkey keeps half of its plan's memory for data. persistence: none keeps everything in memory only: a restart or a pause empties it, and the console warns before.
• MariaDB can move to a newer series later (11.4 to 11.8 or 12.3, 11.8 to 12.3), upgraded in place; it never goes back, so dump it first. Its details carry a jdbcUrl for Java.
• RabbitMQ: durable queues, such as quorum queues (the default), and persistent messages survive a restart; transient messages do not.
• S3 object storage creates the buckets you list (up to 20). A bucket you remove from the list keeps its objects. publicBuckets are readable without a key; bucketQuotaMiB caps each bucket, and a bucket over its quota refuses writes. Use path-style requests; the region is us-east-1. Bucket names follow S3's rules: 3 to 63 characters, no two dots in a row, no IP address, no name twice, and every public bucket is one of the buckets; a name that breaks them is refused when you create or change the store Since 1.4.0.

Bound and standaloneCopy Anchor Link

A managed service lives in one of two ways:

A bound service is the usual choice: it comes and goes with the landscape, and your services read its address from templates. See Add a database.

ConnectingCopy Anchor Link

Other services of the same harthelm.yml read a bound service's connection in their env:

They are filled in when the service starts. When they change, for example after a Rotate, the services that use them restart once the new value works. Use ${{ services.db.secret }} rather than the vault key (${{ secrets.<key> }}) for the secret alone: the vault key keeps the value of your last Sync, so after a Rotate the service would hold the old one until you sync again.

A standalone service's host and port are in its details; use them like any other address.

In-cluster TLSCopy Anchor Link

Where your installation has in-cluster TLS and cert-manager, Valkey, RabbitMQ and MariaDB Since 1.3.0 and S3 Since 1.4.0 get a certificate of the installation's internal CA. The connection URLs above stay plain and work as before. An app that wants TLS uses:

and trusts the internal CA, the file $HART_INTERNAL_CA_FILE in the editor and in services (see Workspace environment); the AWS SDKs read it from AWS_CA_BUNDLE. The detail tls says whether the instance has the TLS listeners. A renewal, about every 75 days, restarts the server for a few seconds (S3 for about 20 to 35).

From a browserCopy Anchor Link

Managed services are reachable inside your team's namespace only. For browsers, RabbitMQ and S3 get a host of their own Since 1.4.0:

https://ms-<n>.<workspace domain>

<n> is the instance's number; it is never given to another instance, also not after a delete. The details drawer shows the host on its Overview under Browser host, and the API in the service's browser.url. PostgreSQL, MariaDB and Valkey have no host: run an admin tool as a service of your landscape instead. Your administrator can switch the hosts off; then use the forward routes below.

RabbitMQ's management UICopy Anchor Link

Open management UI opens RabbitMQ's management UI in a new tab, already signed in as you: with the tags management and policymaker on the broker's virtual host, for one hour. After that, the UI's Click here to log in signs you in again through the console. The broker's own user and password still work at the UI's login form and for AMQP clients.

The host is always behind your team's sign-in, like a private dev URL, and it is never public. Who gets the single sign-on:

Scripts call RabbitMQ's HTTP API on the host with an API key in Harthelm-Authorization and the broker's user and password.

S3 from browsersCopy Anchor Link

Presign URLs with the store's host, the detail browserEndpoint, and path-style addressing:

  web:
    env:
      S3_ENDPOINT: ${{ services.files.dsn }}                                # in the cluster: http://<host>:8333
      S3_PUBLIC_ENDPOINT: ${{ services.files.details.browserEndpoint }}     # for browsers: https://ms-42.<workspace domain>

The host passes path and query unchanged, so a URL presigned with browserEndpoint works for every key, also for keys with spaces, +, % or non-ASCII characters.

Behind the sign-in (the default), only members of your team reach the host. Open the store's host in the drawer, or opening a presigned URL in a fresh browser, signs the browser in for 12 hours.

Add Harthelm-Authorization after your S3 client has signed the request. Harthelm removes the header before the store sees it, so a signature over it fails with SignatureDoesNotMatch. Hook it in where the SDK hands over the signed request: botocore's before-send event, a middleware of the AWS SDK for JavaScript v3 after its signing step, a http.RoundTripper around the client's transport in Go. Presigned URLs are not affected.

Public. Public host in the drawer switches the host public, after a confirmation that names what becomes reachable. A public host has no sign-in: anyone can read the objects of the store's publicBuckets (no listings), and every other request needs a signature with the store's key, so a presigned URL works for anyone who holds it until it expires. The switch takes effect within a second and restarts nothing. Every member of the team may switch it; for a store bound to a landscape, the editors and admins of its workspace. harthelm.yml has no key for it, and a Sync never changes it. With hart: hart ms create s3 … --public; with the API: "public": true in PATCH /managed-services/{ms}. Your administrator may forbid public hosts; then the switch is disabled and says so, and a store switched public before is served behind the sign-in again until they are allowed.

Pages on your dev hosts may send presigned requests, uploads included, to a public host: the store's CORS rule allows the origins https://*.<workspace domain>. Since 1.5.0 a page on one of your team's custom domains may do the same: the router answers for an Origin that is exactly https://<name> of a custom domain of the store's own team that is verified and has not lapsed (a restricted domain counts, it is the team's too). It answers a preflight itself, with GET, HEAD, PUT, POST, DELETE, the requested header names and a cache time of 300 seconds, and it adds the origin and the exposed headers (ETag, which a multipart upload needs, and the x-amz ids and checksums) to the answer. It never sends Access-Control-Allow-Credentials and never *. Nothing restarts when a domain comes or goes: the routers follow within a second, and a domain that is removed, lapses or moves to another team gets nothing from the next request on (a browser that cached a preflight may send requests for up to 300 seconds more; the store's signature check decides those as for any client). Another team's domain, an unverified one and any other origin get no CORS answer. Gated hosts get no CORS for custom domains (a page on another site sends no cookie of the host, so the gate answers its preflight with 401), and neither does RabbitMQ's management host. A paused store's preflight is still answered, but its requests get the paused page without CORS headers, so the script sees a CORS error. Nothing is needed in harthelm.yml.

Forward routesCopy Anchor Link

Without the hosts, or for script uploads from a dev host during development, route through a forward service on your dev domain, behind your workspace's sign-in. A forward target names the object behind the service: ws-<workspace id>-<name> for a bound one, ms-<name> for a standalone one, in the team's namespace rg-<team id>.

RabbitMQ's management UI, for a bound broker mq, at https://<dev domain>/mq/ (with the trailing slash); sign in with the broker's user and password:

  mq-ui:
    type: forward
    target: http://ws-${{ workspace.id }}-mq.rg-${{ team.id }}.svc:15672/
    routes: [{path: /mq, strip: true}]

S3: route each bucket's path to the store as it is, without strip, and presign with https://${{ workspace.devDomain }} as the endpoint. For a bound store files with the buckets uploads and assets:

  s3:
    type: forward
    target: http://ws-${{ workspace.id }}-files.rg-${{ team.id }}.svc:8333
    routes: [{path: /uploads}, {path: /assets}]

The requests are same-origin with your app, so its sign-in cookie goes along. An app's own routes must not take a bucket's name. Behind a route with a prefix and strip (such as /s3), only keys of letters, digits and - . _ ~ / work.

What can change laterCopy Anchor Link

The provider and its version are a service's identity: another provider is a new service, which starts empty. Some settings are fixed once the service exists (such as postgresVersion, a database's user, Valkey's persistence), versions may only move up (MariaDB to a newer series, Valkey and RabbitMQ to a later minor version), and storage can only grow. Where your installation's storage class cannot grow volumes, a plan that needs more storage is refused. Sync and the console check these rules and say what they refuse.

BackupsCopy Anchor Link

Managed services are backed up every night unless you turn it off (backups: false, or Nightly backups off). The details drawer shows the last dump and has Dump now. A paused service cannot be dumped.

Restoring a backup is a task for your administrator (Backups and restore).

Sizes and quotaCopy Anchor Link

A managed service counts against the team's quota at its whole plan, CPU and memory, because its server reserves all of it Since 1.3.0. A paused one counts nothing. See Plans and quotas.

Next stepsCopy Anchor Link