Skip to main content
Video tutorial · 2:20

Elchi module

Keeps the certificate in TLS secrets on Elchi. Elchi serves certificates as secrets: a TLS context on a listener names a secret, and Elchi sends it to every proxy that runs the listener. CertAutoPilot creates its own secret in every version Elchi serves — found on the controller, never typed — records the resource id Elchi gives it, and from then on updates only those secrets; Elchi publishes the new certificate to the listeners that use them. When Elchi moves a listener to a new version it copies the secret there, and that copy is updated too.

Only CertAutoPilot's secrets are written

CertAutoPilot never searches Elchi for secrets to take over. A secret of the target's name that it did not create stops the deploy before anything is written, in every version (ELCHI_CONFLICT) — set another secret name. Binding the secret to a listener (a Downstream TLS context that names it) is done in Elchi.

Prerequisites​

  • A dedicated service account. Elchi keeps one session per user: every login replaces the previous one. A person logging in with the same account ends CertAutoPilot's session (CertAutoPilot logs in again once and repeats the request) and the other way round.
  • Role Admin (recommended — CertAutoPilot can then read which versions Elchi serves) or Editor, and member of a group of the target project — in Elchi a role alone gives no project access; a non-owner account reaches a project through one of its groups (Settings → Groups).
  • No one-time code on the account, and a project that does not force OTP on it.
  • Choose the password first. Elchi makes a password an admin set temporary: sign in once with the new account and choose its own password, then store that one in CertAutoPilot.
  • HTTPS from CertAutoPilot to the controller API. Plain http is refused — the password and the private key travel on this connection.

Minimum access: role Editor on the service account and membership in the group the project's listeners and clusters are shared with (usually the project's own group). Nothing else — Admin and Owner are not needed. An Editor may not read which versions Elchi serves, so CertAutoPilot uses the versions of the listeners and clusters it can see. With role Admin any group of the project is enough. A Viewer is refused.

WherePermissionUsed byWhy
Elchi userAdmin (or Editor)Deploy, Rollbackcreating and updating secrets (a Viewer is refused: ELCHI_PERMISSION)
Elchi userAdminDeploy, Rollback, Dry run, Health checkreading which versions Elchi serves — an Editor is refused there and the versions come from the project's listeners and clusters, so it must be in the group they are shared with
Elchi groupmember of a group of the projecteverythingproject access (otherwise "access denied": ELCHI_PERMISSION)

Credential​

Credential type elchi_credentials: {"username": "...", "password": "..."}.

Target​

FieldRequiredDescription
base_urlyesController API address, https:// only, e.g. https://elchi.example.com. A path is allowed when a front door serves the API under one. No query, no credentials in the URL. Redirects are never followed.
projectnoThe Elchi project id (picked from the projects the account belongs to). Empty = the account's base project.
secret_namenoThe name a TLS context references: a letter or digit, then letters, digits, - and _ (max 100). Names are case-sensitive. Empty = cap-<token>-<slug>, one name per certificate, so one target serves many certificates.
ca_certnoCA of the controller certificate (PEM) when it is not publicly trusted.
tls_skip_verifynoAccept any controller certificate (prefer ca_cert).
http_timeoutnoSeconds per request, 5–120 (default 30).

Module configuration: concurrency (default 5) — how many targets of the module run at once.

Per-distribution override: secret_name gives one certificate its own name on the target. The same rules apply.

How a deploy works​

  1. Log in — once per controller and account per run (POST /auth/login). Deploys and rollbacks against one controller are serialised across CertAutoPilot nodes, because two logins with one account end each other's session. A dry run, health check or picker opened during a deploy logs in too and can end the deploy's session; the deploy logs in again once.
  2. Check the record of the last deploy (controller, project, secret name, one resource id per version). A record from another controller or project is not applied: new secrets are created here, the old ones stay there (ELCHI_TARGET_MOVED). A changed secret name creates secrets under the new name and leaves the old ones.
  3. Find the versions and the secrets. The versions are the ones Elchi serves (its maintenance version listing, readable by an Admin account). Elchi keeps a project's resources in versions it no longer serves, so where the resources live is not enough. An account that cannot read the listing (Editor) gets the versions the project's listeners and clusters live in, plus every version that already holds a secret of this name — and a version Elchi no longer serves answers 503 and is skipped, not failed. The secrets of this name are listed across all versions. No version at all is ELCHI_VALIDATION; when Elchi serves none of them nothing is written (ELCHI_UNAVAILABLE).
  4. Decide per version.
    • A secret of this name carrying CertAutoPilot's marker (general.metadata.certautopilot.certificate_id, kept by Elchi from the create) for this certificate is updated, and so is the one the record names for that version.
    • An unmarked one is taken for the copy Elchi makes when a listener moves to a new version (Elchi clears metadata there) when it was created after a marked secret of this name for this certificate, or when it carries this certificate's automatic name (cap-<token>-…, the token comes from the certificate). It is updated.
    • Any other secret of this name stops the whole target before anything is written (ELCHI_CONFLICT — set another secret name). Nothing is created next to it in other versions.
    • A version without one gets one created (POST /api/v3/xds/secrets?validate=true); our secret deleted in Elchi is created again (ELCHI_RECREATED).
    • If the record says the secret already holds this certificate and nobody changed it since, nothing is written.
  5. Update by id and publish — the certificate (leaf first, then the chain) and the key go to the recorded id with a raised revision (PUT …?resource_id=…&save_or_publish=publish&validate=true). A create is followed by the same publishing update, so a listener that already names the secret gets it at once. Elchi checks the certificate: an expired one or a broken chain is ELCHI_VALIDATION with Elchi's findings.
  6. Follow the publish job (every 2 s, up to 60 s): completed = done; NO_WORK_NEEDED = no listener uses the secret yet, success with ELCHI_NOT_BOUND; failed = ELCHI_PUBLISH_FAILED naming the listeners; still running = ELCHI_PUBLISH_TIMEOUT. In both last cases the secret is saved and the next run writes and publishes it again.

A version that fails at step 5 or 6 does not stop the others; the target is then partial, and every created id is kept.

Dry run makes the same decision per version without writing: create / update by id (saying when it is Elchi's copy) / already current, or the refusal. With an Editor account it can list a version Elchi no longer serves; the deploy skips it. Health check logs in, names the versions (served, or with an Editor the project's) and reads the project's secrets. Validate checks, per recorded secret, that it still exists under its name and version, that the record says it carries the expected certificate, and that nobody changed it in Elchi since. Picker: the project field lists the projects of the account.

Rollback​

Supported, manual and automatic: the previous version is written into the same secrets through the same update. A target refused before writing (name conflict, login, project access) does not trigger auto-rollback of the others. See Rollback.

Limits​

  • Binding is manual (TLS context and listener in Elchi).
  • With an Editor account the versions come from the project's listeners and clusters it can see (so it must be in the project's own group), and a version Elchi no longer serves is skipped at deploy.
  • One session per user — use a dedicated account.
  • An unmarked secret of this name created after CertAutoPilot's own is indistinguishable from Elchi's upgrade copy and is updated.
  • Secrets are never deleted, also not when the certificate, the distribution or the target is deleted.
  • Elchi never returns the certificate it stores, so "unchanged" is decided from the record and the secret's last-update time: a secret someone edited in Elchi is written again.

Error codes​

CodeMeaningRetried
ELCHI_CONNECTcontroller not reachable, or it redirectedyes
ELCHI_AUTHlogin refused, or a one-time code requiredno
ELCHI_PERMISSIONthe account is not in a group of the project, or its role cannot writeno
ELCHI_VALIDATIONElchi refused the certificate or the request, or there is no version to write tono
ELCHI_CONFLICTa secret of this name exists and was not created by CertAutoPilot for this certificate — nothing writtenno
ELCHI_UNAVAILABLEElchi could not reach its control plane for that version, or serves none of themyes
ELCHI_PUBLISH_FAILEDsaved, but pushing to a listener failed — the next run publishes againyes
ELCHI_PUBLISH_TIMEOUTsaved, still publishing after 60 s — the next run publishes againyes
ELCHI_APIa server error, an answer CertAutoPilot could not read (is base_url the API address?), or the session replaced again right after logging inyes

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Deliver Certificates to ElchiYouTube ↗