Concepts
Five words carry most of Tarsana. This page says what each one means and how they fit together.
Tenant
Your tenant is your space in Tarsana. It has an ID that you choose when you sign up, for example acme, and you cannot change it later. Everything you create belongs to your tenant: specs, builds, stored credentials and the servers Tarsana creates for you. No other tenant can read any of it.
Every request that reads or changes something in your tenant names it twice: in the address (/v1/tenants/acme/...) and in the X-Tarsana-Tenant header. Tarsana checks that your credential belongs to that tenant.
People and programs reach your tenant with a role:
| Role | What it can do |
|---|---|
viewer | Can read your submissions and download what your builds produced. Cannot submit specs or change servers. Give it to dashboards, status checks and auditors. |
builder | Can do everything a viewer can, and submit and check specs. Cannot change servers. Give it to CI jobs that build images. |
deployer | Can do everything a builder can, and install images on your servers, manage your servers and store your provider credentials. The widest role a tenant can hold. |
Spec
A spec is a short document that describes the server you want: the operating system and release, the hardening profile, the packages, files and services, and optionally where the server should run (placement). You write it as JSON or YAML.
Tarsana checks a spec before it builds anything. Use validate to see the result without building. The submission ID that submit returns is the spec's hash, sha256: followed by 64 hex digits, so the same spec always gets the same ID.
Image
An image is the disk of a server, built from one spec. Tarsana builds it from pinned package sources, hardens it, removes the tools a running server should not have, and records exactly what went into it: the software bill of materials (SBOM), the resolved package set and the image digest. Read what a build produced with status and fetch.
Attestation
An attestation is a signed statement about one build. It names the image, the SBOM and the package set by their SHA-256 digests, and it is signed with an Ed25519 key. attestation gives you the signed statement and the public key, so you can check the signature with standard tools and without trusting Tarsana. The verify quickstart shows how.
Server
A server is a machine in your own cloud account that runs one of your images. Tarsana creates it with the provider credential you store, from the provider and server type in your spec's placement, with create-server. On its first boot the server connects to Tarsana once to finish its setup. To bring a server you already have, get a one-line command for it with install-command and run it once as root on that server.
Tarsana keeps track of which servers it created. servers lists the other servers in your account, so you can see anything Tarsana cannot account for. You remove a server Tarsana created with decommission-server, and any other server with destroy-server. Tarsana never deletes a server unless you ask.
How it fits together
- You sign up and get a tenant.
- You write a spec and submit it. Tarsana checks it and builds an image.
- Tarsana signs an attestation for the image. You can verify it yourself.
- You create servers from the spec in your cloud account, and decommission them when you are done.
Operation badges
The API reference marks every operation with a badge:
| Badge | What it means |
|---|---|
| Read | Reads information and changes nothing. |
| Change | Checks what you send and stores it if it passes. |
| Session | Starts or ends your session and changes nothing else. |
| Destructive | Deletes or revokes something. You cannot undo it. |