Skip to main content
Version: 0.19

Vault: publish and verify two consumers

Publish one certificate to your Vault KV v2 and deploy that version to Linux consumers. Choose file delivery alone, or also reload and verify a service. The issuing agent owns issuance/renewal; consumers retrieve the published version instead of issuing certificates themselves. TokenTimer coordinates jobs and stores public evidence, not the bundle's private key.

Before you start​

Job approval is off by default. One authorized operator can publish and roll out; arrange another authorized manager only when workspace policy or the request requires approval.

Use a reachable HTTPS Vault or OpenBao with a KV v2 mount, DNS/CA access for the issuer, and distinct enrolled issuer and consumer identities. Choose Installed files only when no service should reload; only Served/Trust require existing services and listeners. Keep the selected workspace throughout. Core and Enterprise need a running CertOps worker; Cloud operates that worker and applies its plan/workspace admission rules.

Start the setup guide with Share one certificate across servers → Linux server. Select the existing agents where appropriate and merge local policy without dropping identity, write paths, reload rights or trust configuration.

If publication fails, repair the reported cause. In Configure material store → Prepare a real publication, review the original job, complete any required host-local reconciliation, acknowledge that review and choose Retry original publication. This preserves the original version and request. Never delete an uncertain checkpoint or create another order to hide the failure.

Allocate the group and configure the hosts​

Before the first publication, pass the issuer's signed no-op in Turn on execution safely; each consumer runs its own check after enrollment. This checks dispatch/reporting only. Then stop issuer polling (execution.enabled: false) and restart the issuer agent while preparing the group.

The publication job returns the real group ID used by its policies. Do not invent an unrelated group ID. Holding polling prevents an approval-disabled publication being claimed before that ID is configured; dryRun: true alone does not hold a queued real job.

  • Job approval on: create the pending publication once, keep it unapproved while preparing the group, then have a different authorized manager approve it after readiness checks.
  • Job approval off: do not assume submission will wait. Follow the guide's prerequisite/configuration order before submitting. If allocating through the API first, keep issuer execution disabled until the returned group is applied and checks are complete. Only enable publication deliberately.

Use the generated group-scoped store/binding configuration and separate Vault Agent roles on the actual hosts. At Connect and validate consumers, choose Distribute certificate files only or Distribute and reload a service before assigning consumers. Check the local store alias, group, profile, allowed paths and token sink. File-only bindings omit reload commands and listener probes. Service delivery also needs allowlisted validate/reload commands and TLS probes. Each consumer needs its own credentials and binding authorization revision. Keep SecretIDs, tokens and private keys out of dashboard/API requests and terminal output.

In the Vault GUI, inspect the KV v2 engine and the actual policies: issuer create/read, each consumer read-only within the intended group's bundle path. Authenticate through your normal administrator method. This view complements the host setup; it does not install the TokenTimer agent or replace Vault Agent configuration.

Publish and inspect one version​

Once the returned group, local policy and Vault access are ready, set issuer execution.enabled: true and execution.dryRun: false, then restart the agent. Complete the original publication under the workspace's actual approval policy. Do not enable polling with dry-run protection merely to repeat a no-op while the real publication is queued: it can claim and block that job. Follow the publication timeline and read-only Agent output directly in the guide; no Jobs or terminal API handoff is needed for this step.

Confirm the publication's public result, then inspect the corresponding Vault object's version metadata/history. Use version metadata for status checks; bundle Data or raw JSON contains private-key material. A published object is not a deployment. TokenTimer material version, Vault provider version and rollout generation are separate identifiers.

Assign consumers and request a rollout​

In Configure material store, inspect the accepted publication receipt. Continue to Connect and validate consumers: register each new host with its own bootstrap token, select First consumer, choose Verification policy, then assign it. Apply the returned authorization revision and generated local configuration, pass its signed no-op, and confirm the restart. Use Additional consumer for another host. Keep destinations and reload commands local.

Choose Published certificate version, review Maximum parallel deployments, then choose Deploy the selected version. Follow the rollout request and each consumer's deployment timeline and Agent output inside onboarding. With workspace Job approval off, the rollout starts without a second user; with approval on, another authorized manager must approve it through the existing Jobs review surface. Child-job approval follows the same workspace policy. Require All selected consumers installed for file-only delivery, or All selected consumers verified for service delivery. Files installed is not proof of live use; make independent live checks when a service is configured. A successful coordinator request alone does not prove installation. The API reference remains available for automation and advanced recovery.

For a new consumer, create its short-lived bootstrap token directly in Connect and validate consumers, then supply it through the installer's hidden prompt. An already enrolled consumer keeps its existing identity; it does not need another token.

If a rollout pauses, fix the host-side cause first. Reconcile an uncertain binding against the intended certificate, retry its failed job, and use Resume rollout in the guide once the selected consumers are ready. Refresh the inline timeline and Agent output to follow the new attempt. Resume continues the same rollout; it is not proof that the service is verified. To hold a particular rollout even when approval is off, set requiresApproval: true in the API request. Workspace-forced approval cannot be bypassed.

Verify both consumers​

For file-only delivery, inspect each installed certificate/key pair and its installation evidence; no listener is asserted. For service delivery, inspect each deployment/validation/reload result. Use two fresh independent TLS checks against the two concrete listeners, with hostname/SNI and trusted CA validation. Both must serve the intended published identity; do not reuse one endpoint's observation as proof for the other.

In Certificates → certificate → Deployments, compare desired/current versions and verification freshness. Renewals contains the source profile, not proof of all consumer rollouts. Keep published → deployed → verified in use distinct. A later publication needs a separate rollout under the workspace approval policy.