Skip to main content

Targets & groups

A target is one concrete endpoint of a given module type — an SSH host, a K8s cluster, an F5 BIG-IP management URL, a Vault instance. A target group is a named collection of targets for bulk distribution. Both live under Settings → Distribution.

Model​

  • Identity vs display: every target has an immutable _id (used in jobs, audit, references) and a mutable _name (safe to rename for humans). References use IDs; UI surfaces names.
  • Module type: fixed at creation time. Change requires deleting + recreating the target.
  • Credential reference: most modules authenticate via a module credential. Multiple targets can share one credential (e.g. ten SSH hosts, one key). Rotating the credential rotates it for every target that references it.
  • Project scope: targets belong to a single project. Cross-project reuse is not supported — create a target per project.

Create a target​

  1. Settings → Distribution → Targets → New.
  2. Pick a module type. The form reveals type-specific fields:
    • SSH — hostname, port, username, credential reference (SSH key or password).
    • Kubernetes — cluster endpoint or in-cluster mode, service-account credential, namespace, secret name template.
    • IIS — WinRM host + port, auth scheme (NTLM / Basic), credential reference, certificate store + binding site.
    • F5 BIG-IP — management host + port, partition, credential.
    • NetScaler (Citrix ADC) — NSIP, credential, intermediate naming strategy (fingerprint-based recommended; see NetScaler).
    • HashiCorp Vault — Vault address, KV v2 mount path, credential (AppRole / JWT / TLS cert).
    • Webhook — URL, HTTP method, headers, timeout, retry policy.
    • Huawei Cloud — region, project ID, credential (AK/SK), scope (ELB / CDN / WAF).
    • MerlinCDN — distribution ID, canonical-name ID (or domain to match/create), credential (personal access token + org/workspace), optional API host, delete_old_cert toggle.
  3. Give the target a descriptive name. prod-web-lb-1 beats target-42.
  4. Optional validation endpoints (post-distribution TLS check):
    • Host + port (443 for HTTPS).
    • SNI (optional; defaults to the cert CN).
    • Expected fingerprint source: server (recompute from the server's response after deploy) or pinned (a known-good SHA-256).
    • Retry policy: count, delay, timeout.Validation endpoints can also be defined per-distribution later; per-target is the common case.
  5. Save. The UI runs an immediate health check — a read-only handshake to confirm the endpoint is reachable and the credential authenticates. Failure shows a red badge with the reason.

Health check​

Clicking Health check on the target detail page re-runs a minimal reachability test:

  • SSH: connect + echo ok.
  • K8s: GET /api/v1/namespaces/<ns>.
  • F5 / NetScaler: list partitions / system stats.
  • IIS: Invoke-Command over WinRM returning hostname.
  • Vault: sys/health.
  • Webhook: HTTP OPTIONS (or a GET probe if configured).
  • Huawei: cert-service list call.
  • MerlinCDN: authenticated distribution lookup.

Health-check failures do not disable the target — distribution still attempts it — but the list view shows a red dot so you have a warning before execution.

Create a target group​

  1. Settings → Distribution → Target groups → New.
  2. Name it (e.g. prod-web-lbs).
  3. All targets in a group must share the same module type — you cannot mix SSH and Kubernetes in one group.
  4. Pick members from the list. Member count is shown in the list view.

On an attached distribution, you pick a single target or a single group, not both. Distributing to a group of 50 triggers fan-out if 50 ≥ the fan-out threshold (configurable; default 10).

Edit / delete​

  • Rename is always safe — it updates the display name; the immutable ID stays.
  • Change credential — allowed; all future distributions pick up the new credential on next execution.
  • Change module type — not allowed. Create a new target and update the distribution binding.
  • Delete — blocked if any distribution currently references the target. Either remove those distributions first, or add a replacement target to the group and drop the old one from membership.

Variables in target config​

Target connection fields (hostname, host, IP, NSIP, etc.) are literal values — they are not templated or variable-substituted. Project variables (Project variables) are resolved only in SSH/WinRM PathSet paths and ActionSet commands/scripts, via ${{ NAME }} placeholder substitution (not Go templates) — see primitives. For staging vs prod where only the hostname differs, create a separate target per environment.

Security notes​

  • Targets are scoped to a project; no cross-project leakage.
  • Credential references are by ID — revoking a credential (admin-only) does not delete the target, but the next execution will fail with auth classification.
  • SSRF: target hostnames are resolved via the standard network policy — link-local and cloud-metadata blocked by default.

Troubleshooting​

Health check is red but I can reach the target manually​

Usually credential scope or network path. Check the exact error on the detail page. Common causes:

  • K8s: service-account missing secrets: create, update in the target namespace.
  • SSH: wrong port (22 vs 2222), wrong credential, or firewall between the backend pod and the host.
  • IIS: WinRM not configured (Enable-PSRemoting -Force on the Windows side) or firewall on TCP 5985/5986.

Cannot delete target​

A distribution still references it. Go to Certificates → filter by target, remove or repoint those distributions, then retry.

"module type mismatch" when adding a member to a group​

Groups are homogeneous. Create a second group for the other module type. If you want to distribute to both types for the same cert, attach two distributions to the cert (one per module type).

See also​