Install grafts
To add a graft to your instance, install it with orchardctl or Helm values. The list of grafts is part of the instance’s configuration: a grafts list in the Orchard chart values. orchardctl graft edits that list on hosts set up by the installer. GitOps setups edit it in Git. In both cases, a change rolls Orchard out like an upgrade.
Install with orchardctl
Section titled “Install with orchardctl”-
Find a graft:
sudo orchardctl graft search -
Review its versions, and which of them work with your instance:
sudo orchardctl graft info announcements -
Add the graft:
sudo orchardctl graft add announcements --apply
add selects the newest version that works with your Orchard, unless you give a version with <id>@<version>. It then runs these checks on the server:
- It checks the download against its digest, and the signature against your trust policy.
- It checks the graft against your Orchard version, the doors it uses, and the grafts it depends on.
- It lists the database migrations that would run. No graft SQL runs at this point.
orchardctl then shows the graft’s capabilities, the core tables it reads, its paths outside its own ID, and its routes open to anyone. It also checks that any CRDs the graft requires exist.
A graft’s migrations run with Orchard’s database user. If a graft ships a Helm chart, orchardctl installs it with cluster-admin rights and asks you to type the graft’s ID first. To accept a chart with --yes, add --allow-chart. Community grafts cannot ship a chart.
After you confirm, Orchard rehearses the migrations inside a transaction and rolls them back. If that passes, orchardctl writes the graft into your values. --apply rolls Orchard out immediately. Without it, run sudo orchardctl update when you are ready.
Commands
Section titled “Commands”| Command | Action |
|---|---|
orchardctl graft search [term] |
Searches the Extension Marketplace and your taps. |
orchardctl graft info <id> |
Shows a graft’s tier, publisher, versions, and compatibility. |
orchardctl graft add <id>[@version] |
Installs from the Extension Marketplace. |
orchardctl graft add ./file.graft |
Installs a file. Orchard stores it in its database, so this works offline and on clusters with several nodes. |
orchardctl graft add https://.../x.graft |
Installs from an https address, pinned to the digest it had when you added it. |
orchardctl graft list |
Shows what is installed, whether it is running, and recent server messages about grafts. |
orchardctl graft upgrade [id] |
Moves to the newest compatible version. Refer to Upgrade and roll back grafts. |
orchardctl graft rollback <id> |
Returns to the previous version and its data. |
orchardctl graft remove <id> |
Uninstalls the graft. Its data stays. |
orchardctl graft remove <id> --purge --apply |
Uninstalls the graft and deletes its schema, stored files, and settings. |
orchardctl graft pool <id> [n|default] |
Shows or sets the database connections the graft can open per pod. |
orchardctl graft tap add|list|remove |
Manages taps. |
orchardctl graft trust [level] |
Shows or sets the trust policy. |
add and upgrade accept these flags:
| Flag | Effect |
|---|---|
--yes |
Skips the confirmation prompt. |
--dry-run |
Runs every check and changes nothing. |
--apply |
Rolls Orchard out afterward. |
--allow-third-party |
With --yes, accepts a graft that Orchard did not make. |
--allow-chart |
With --yes, accepts a graft’s Helm chart. |
If a graft includes a cluster chart for CRDs or RBAC, add installs it as the Helm release orchard-graft-<id>. remove leaves that release in place and prints the helm uninstall command.
Install with Helm values
Section titled “Install with Helm values”Add an entry to your values. The graft’s Extension Marketplace page shows the entry to copy.
grafts: - id: announcements version: <version> digest: sha256:<digest>
graftSettings: trust: listeddigest is the SHA-256 of the .graft file. It is required, and Orchard does not install a graft whose bytes do not match. source is optional and defaults to the Extension Marketplace. Set it to an https:// address to install from elsewhere.
A graft with a cluster chart needs that chart installed as its own HelmRelease.
Where grafts come from
Section titled “Where grafts come from”| Kind | Publisher | How Orchard identifies it | Label |
|---|---|---|---|
| Official | Orchard | Signed with Orchard’s key | Official |
| Community | Another author, listed in the Extension Marketplace | Signed with the author’s key, from a listing that Orchard signed | Community · by the author |
| Tap | Anyone, from a tap you added | Signed with the tap’s key, which you trusted when you added the tap | Tap: its name |
An Orchard maintainer reviews a community graft when it is first listed. Each new version passes automated checks, but no one reviews it by hand. Orchard does not check taps.
graftSettings.trust controls which grafts can load. To load only Orchard’s own grafts, set it to official:
| Policy | Loads |
|---|---|
official |
Only Orchard’s own grafts |
listed (default) |
Official and community grafts, and grafts signed by a key in graftSettings.keys |
taps |
All of the above, and grafts from taps you added |
any |
Unsigned grafts too. Anything in the grafts directory runs. |
signed is an older name for listed, and it still works.
To change the policy, run the following command:
sudo orchardctl graft trust taps --applyA publisher can also give you a public key, a short base64 string from graft keygen. To trust grafts signed with it, run sudo orchardctl config edit and add the key to graftSettings.keys.
The Extension Marketplace can revoke a version or delist a community graft. orchardctl does not offer or install a revoked version. An instance that has it refuses to load it on its next start.
Add a tap
Section titled “Add a tap”A tap is a catalog of grafts in a folder on an https host.
-
Add the tap. The command shows the tap’s signing key and asks you to confirm it.
sudo orchardctl graft tap add acme https://grafts.example.com/orchard -
Allow taps in your trust policy:
sudo orchardctl graft trust taps --apply -
Install a graft with the tap’s name in front:
sudo orchardctl graft add acme/notes --apply
Every graft from a tap must be signed with the tap’s key.
With Helm values:
graftSettings: trust: taps taps: - name: acme url: https://grafts.example.com/orchard key: <the key that tap add showed>grafts: - id: notes version: <version> digest: sha256:<digest> tap: acmeAn instance has one graft per ID, whatever its source. orchardctl refuses acme/notes if a notes graft from another source is installed.
View installed grafts
Section titled “View installed grafts”Go to Instance admin > Grafts. The page lists each graft with its status, signature, capabilities, core table reads, and routes, including routes open to anyone. A failed graft shows the phase it failed in and the reason. Settings that a graft adds appear in Instance admin > Configuration.
Settings
Section titled “Settings”| Value | Environment variable | Default |
|---|---|---|
grafts |
ORCHARD_GRAFTS |
None |
graftSettings.trust |
ORCHARD_GRAFT_TRUST |
listed. One of official, listed, taps, or any. |
graftSettings.registrySignature |
ORCHARD_REGISTRY_SIGNATURE |
required. Set auto to accept an unsigned revocation list from a registry you run yourself. |
graftSettings.taps |
ORCHARD_GRAFT_TAPS |
None. Each tap has a name, url, and key. |
graftSettings.keys |
ORCHARD_GRAFT_KEYS |
None |
graftSettings.marketplaceUrl |
ORCHARD_GRAFT_MARKETPLACE_URL |
https://assets.orchard.my/registry |
graftSettings.strict |
ORCHARD_GRAFTS_STRICT |
false. When true, a graft that fails stops the pod instead of being skipped. The rollout halts and the previous pods keep serving. |
graftSettings.safeMode |
ORCHARD_GRAFTS_SAFE_MODE |
false. When true, no grafts load. |
graftSettings.pools |
ORCHARD_GRAFT_POOLS |
None. Database connections per pod by graft ID, for example { greenhouse: 15 }. |
ORCHARD_GRAFT_DB_POOL |
3. Database connections per pod for grafts that do not ask for a size. |
Database connections
Section titled “Database connections”Each graft opens its own pool of database connections on every server and worker pod. A graft asks for a size in its graft.json. Greenhouse asks for 10. To change a graft’s size, run the following command:
sudo orchardctl graft pool greenhouse 15 --applyTo return to the size the graft asks for, use default instead of a number.
Connections open when needed and close after about 10 seconds idle. Every pod can open its whole pool at once, and during an update the old and new server pods run side by side.
Orchard compares this peak against the database’s max_connections at boot and in Instance admin > Grafts:
- Past 80% of usable connections, Orchard warns.
- Past 100%, Orchard reports that the budget is exceeded. With
graftSettings.strict, new pods refuse to start and the rollout halts.
When the database runs out of connections, new requests fail until connections free up. Lower a pool or raise max_connections.
Related resources
Section titled “Related resources”- Upgrade and roll back grafts - Move between versions and keep the graft’s data.
- Troubleshooting grafts - Find out why a graft did not load.
- Run Greenhouse - Install and configure the largest first-party graft.