---
name: analyze-ansible-component
description: "Deep-dive a single application or infrastructure component (k3s, ClickHouse, PostgreSQL, MongoDB, valkey, MinIO, Kafka, pgvector, VictoriaLogs, Vector, nginx, node_exporter) and produce a Component Spec: image/tag or install model, ports, config, persistence, healthcheck, auth, and deployment gotchas. Use this before write-ansible-role when a role must deploy or integrate that component."
license: MIT
handoffs:
  - label: "Write the Ansible role"
    agent: "write-ansible-role"
    prompt: "Run the write-ansible-role skill and use the Component Spec at {spec_path} to generate the infra-service role, or to fill in infrastructure defaults/templates of the app-deploy role."
---

# What I do

I analyze **one component** (an application or infrastructure service) and
produce a **Component Spec** — a compact reference that `write-ansible-role`
can turn into an `infra-service` role (native binary / package + systemd), or
wire into an `app-deploy` role (connection strings, healthchecks, env keys).

I reuse existing knowledge in the local roles repo when available, and only
fall back to external docs (web) when the component is new or a version
changed.

# When to use me

- A role must deploy a standalone component (e.g. `k3s`, `clickhouse`,
  `kafka`) — call me before `write-ansible-role`.
- An `app-deploy` role needs an infra dependency wired in (DB, cache, queue,
  object storage, logging) and its exact image/port/healthcheck/connection
  format must be pinned down.
- The project spec from `analyze-ansible-role-project` lists a dependency but
  lacks its deployment details.

# User Input

> You **MUST** consider the user input before proceeding (if not empty).

`$ARGUMENTS` may contain any of:

- Component name (e.g. `clickhouse`, `k3s`, `postgres`, `kafka`).
- Optional: required version / constraints.
- Optional: the existing roles directory (e.g. `ANSIBLE_ROLES/`) to reuse an
  already-written role for that component.

# Operating Constraints

- Only record **verified** values (from the existing role, official image/docs,
  or the product's own compose). Never guess image tags or versions.
- Pin image tags and versions — never `latest` unless the product pins it.
- Healthchecks must be commands that actually work inside the container image
  or against the running service.
- Mark anything unverified as an **Open Question**; do not fill it with a guess.

# Execution Steps

## 1. Reuse before research

If a role for the component already exists locally (e.g. in `ANSIBLE_ROLES/`),
study it first — reuse its image/version choices, healthchecks, and layout.
Note what it got right and any gaps.

## 2. Determine the install model

For each component, first decide how a role deploys it:

- **Container** (compose service): image + tag, ports, healthcheck, persistence.
- **Native binary**: tarball URL, version/scala-variant, install dir, systemd
  unit (kafka, node_exporter, ...).
- **OS package**: repo gpg key + `apt_repository`/`yum_repos`, package name
  (clickhouse, postgresql, ...).
- **Cluster installer**: k3s/kube — server/agent host groups, main node var,
  registry mirrors (k3s).

## 3. Gather component facts

For each item below, record **verified** values (from the existing role, the
official image/docs, or the product's own compose). Never guess — if unknown,
mark as open question.

- **Image**: official image + recommended tag (and why that tag) — or binary
  tarball URL + version + variant.
- **Ports**: default ports; which are API/client-facing vs internal;
  how to keep them internal to the compose network / bound to localhost.
- **Config**: required env vars / config file, defaults, and the minimal safe
  config for a locked-down on-prem deploy.
- **Persistence**: volumes, data paths, backup/restore considerations.
- **Healthcheck**: the exact command/endpoint (e.g. `pg_isready`,
  `mongosh ping`, ClickHouse HTTP `SELECT 1`, k3s `kubectl get nodes`,
  Kafka `kafka-broker-api-versions`, node_exporter `/metrics`).
- **Auth/security**: default creds, TLS, network exposure rules.
- **Tuning**: memory/CPU caps, limits flags, common failure modes.
- **Connection format**: how other services connect (connection string, URL,
  env keys) — this is what the app env templates need.
- **Init/bootstrap**: schema init, bucket creation, first-run steps.
- **systemd**: service unit template shape, user/group, exec start/stop,
  env file path, restart policy.
- **Gotchas**: air-gap, multi-instance suffix, restart policies, version
  pinning, cluster bootstrap ordering.

## 4. Write the Component Spec

Write to `component-spec.md` in the target dir (or present as the final
message) using `templates/component-spec.md` in this skill folder. List
anything unverified as an **Open Question**.

# Validation

- Every value in the spec is verified against a real source (existing role,
  official docs) — not a memory guess.
- Image tags / versions are pinned, never `latest` unless the product pins it.
- Healthchecks are commands that actually work inside the container image or
  against the running service.
- Connection format matches what the consuming application expects.
- Any unresolved item is explicitly listed as an Open Question.

# Output

A `component-spec.md` per the template in this folder. It is consumed by
`write-ansible-role` to generate `infra-service` roles or to fill in
infrastructure defaults/templates of `app-deploy` roles.

# Quality bar

- Every value verified against a real source (existing role, official docs).
- Image tags and versions pinned, never `latest` unless the product pins it.
- Healthchecks must be commands that actually work inside the container image.
- Connection format matches what the consuming application expects.