> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ArtifactHub

> Distribução dos Helm charts do ChatCLI via ArtifactHub — o registro público de pacotes para Kubernetes.

O **ChatCLI** publica seus Helm charts no [ArtifactHub](https://artifacthub.io), o registro público oficial de pacotes para o ecossistema **Cloud Native**. Isso permite que qualquer pessoa descubra, instale e mantenha os charts atualizados diretamente pelo catálogo do ArtifactHub ou via CLI do Helm.

***

## Charts Disponíveis

<CardGroup cols={2}>
  <Card title="ChatCLI Server" icon="server" href="https://artifacthub.io/packages/search?repo=chatcli">
    Gateway gRPC multi-provedor de LLMs com modo agente, K8s watcher, MCP e AIOps.
    **Registry OCI:** `oci://ghcr.io/diillson/charts/chatcli`
  </Card>

  <Card title="ChatCLI Operator" icon="dharmachakra" href="https://artifacthub.io/packages/search?repo=chatcli-operator">
    Operator Kubernetes para detecção autônoma de incidentes, análise com IA e remediação automática.
    **Registry OCI:** `oci://ghcr.io/diillson/charts/chatcli-operator`
  </Card>
</CardGroup>

***

## Como Funciona a Integração

A integração com o ArtifactHub é totalmente automatizada e baseada em três pilares:

### 1. Arquivos de Repositório (`artifacthub/`)

No diretório `artifacthub/` do projeto existem **dois arquivos separados**, um para cada chart, que registram os repositórios no ArtifactHub:

**`artifacthub/chatcli-repo.yml`**

```yaml theme={"system"}
repositoryID: 193ab92d-52ac-4ac1-863f-aa29927c8d74
owners:
  - name: Edilson Freitas
    email: diillson@hotmail.com
```

**`artifacthub/chatcli-operator-repo.yml`**

```yaml theme={"system"}
repositoryID: ccc35f25-d27b-41ca-ba20-b8de9ee2f828
owners:
  - name: Edilson Freitas
    email: diillson@hotmail.com
```

Esses arquivos são enviados para o registro OCI via [ORAS](https://oras.land/) com o MIME type `application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml`, permitindo que o ArtifactHub descubra e indexe os charts automaticamente.

<Info>
  Cada chart possui um `repositoryID` único e seu próprio arquivo de metadados. O ArtifactHub lê esses artefatos OCI para sincronizar os metadados dos repositórios automaticamente.
</Info>

### 2. Anotações nos Charts (`Chart.yaml`)

Os arquivos `Chart.yaml` de cada chart contêm anotações específicas do ArtifactHub que enriquecem a página do pacote no catálogo:

```yaml theme={"system"}
annotations:
  artifacthub.io/license: Apache-2.0
  artifacthub.io/containsSecurityUpdates: 'false'
  artifacthub.io/prerelease: 'false'
  artifacthub.io/operator: 'false'         # 'true' no chart do operator
  artifacthub.io/operatorCapabilities: Seamless Upgrades  # apenas no operator
  artifacthub.io/crds: |
    - kind: AIInsight
      version: v1alpha1
      description: Análise e recomendações geradas por IA
    # ... 17 CRDs no total
  artifacthub.io/crdsExamples: |
    - apiVersion: platform.chatcli.io/v1alpha1
      kind: Issue
      metadata:
        name: high-cpu-api-server
      spec:
        title: "High CPU usage on api-server"
        severity: critical
    # ... exemplos de ApprovalPolicy, ServiceLevelObjective, etc.
  artifacthub.io/links: |
    - name: Documentation
      url: https://chatcli.edilsonfreitas.com
    - name: Source
      url: https://github.com/diillson/chatcli
  artifacthub.io/maintainers: |
    - name: Edilson Freitas
      email: diillson@hotmail.com
```

#### Anotações Disponíveis

| Anotação                                 | Descrição                              |   Server   |      Operator     |
| ---------------------------------------- | -------------------------------------- | :--------: | :---------------: |
| `artifacthub.io/license`                 | Licença do chart                       | Apache-2.0 |     Apache-2.0    |
| `artifacthub.io/operator`                | Indica se é um operador Kubernetes     |   `false`  |       `true`      |
| `artifacthub.io/operatorCapabilities`    | Nível de maturidade do operador        |      —     | Seamless Upgrades |
| `artifacthub.io/containsSecurityUpdates` | Sinaliza atualizações de segurança     |   `false`  |      `false`      |
| `artifacthub.io/prerelease`              | Marca como versão pré-release          |   `false`  |      `false`      |
| `artifacthub.io/crds`                    | Lista de CRDs instaladas pelo chart    |   17 CRDs  |      17 CRDs      |
| `artifacthub.io/crdsExamples`            | Exemplos de uso das CRDs               | 3 exemplos |     4 exemplos    |
| `artifacthub.io/links`                   | Links para documentação e código-fonte |   2 links  |      2 links      |
| `artifacthub.io/maintainers`             | Mantenedores do chart                  |      1     |         1         |

### 3. Pipeline de Publicação (GitHub Actions)

A publicação é completamente automatizada via GitHub Actions no workflow `3-publish-release.yml`. A cada release:

<Steps>
  <Step title="Trigger do release">
    Um push na branch `main` aciona o [Release Please](https://github.com/googleapis/release-please-action), que cria automaticamente um PR de release e, ao ser mergeado, gera a GitHub Release com a tag de versão.
  </Step>

  <Step title="Versionamento automático">
    O pipeline atualiza a versão nos `Chart.yaml` de ambos os charts:

    ```bash theme={"system"}
    sed -i "s/^version:.*/version: ${VERSION}/" deploy/helm/chatcli/Chart.yaml
    sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" deploy/helm/chatcli/Chart.yaml
    ```
  </Step>

  <Step title="Injeção de changelog">
    O script `scripts/generate-artifacthub-changelog.sh` extrai as mudanças do `CHANGELOG.md` e injeta como anotação `artifacthub.io/changes` nos `Chart.yaml`, com tipos estruturados (added, fixed, changed, etc.) e links para PRs.
  </Step>

  <Step title="Empacotamento">
    Os charts são empacotados com `helm package`:

    ```bash theme={"system"}
    helm package deploy/helm/chatcli/ -d /tmp/charts/
    helm package deploy/helm/chatcli-operator/ -d /tmp/charts/
    ```
  </Step>

  <Step title="Push para o registro OCI">
    Os pacotes são enviados para o GitHub Container Registry:

    ```bash theme={"system"}
    helm push /tmp/charts/chatcli-${VERSION}.tgz oci://ghcr.io/diillson/charts
    helm push /tmp/charts/chatcli-operator-${VERSION}.tgz oci://ghcr.io/diillson/charts
    ```
  </Step>

  <Step title="Assinatura com Cosign">
    Ambos os charts são assinados com [Cosign](https://docs.sigstore.dev/cosign/) usando OIDC keyless, garantindo a integridade e procedência dos artefatos:

    ```bash theme={"system"}
    cosign sign --yes "ghcr.io/diillson/charts/chatcli@${CHART_DIGEST}"
    cosign sign --yes "ghcr.io/diillson/charts/chatcli-operator@${CHART_DIGEST}"
    ```
  </Step>

  <Step title="Push de metadados ArtifactHub via ORAS">
    Os arquivos de repositório são enviados como artefatos OCI com MIME types específicos do ArtifactHub, permitindo a descoberta automática:

    ```bash theme={"system"}
    oras push ghcr.io/diillson/charts/chatcli:artifacthub.io \
      --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \
      artifacthub/chatcli-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml
    ```
  </Step>

  <Step title="Sincronização com o ArtifactHub">
    O ArtifactHub detecta os metadados no registro OCI e indexa automaticamente as novas versões dos charts no catálogo.
  </Step>
</Steps>

***

## CRDs Documentadas

Ambos os charts declaram **17 Custom Resource Definitions** nas anotações, que aparecem automaticamente na página do ArtifactHub:

| CRD                     | Versão   | Descrição                                                             |
| ----------------------- | -------- | --------------------------------------------------------------------- |
| `AIInsight`             | v1alpha1 | Análise e recomendações geradas por IA para problemas detectados      |
| `Anomaly`               | v1alpha1 | Sinal bruto dos watchers, antes da correlação em issues               |
| `ApprovalPolicy`        | v1alpha1 | Requisitos de aprovação para ações de remediação (auto/manual/quórum) |
| `ApprovalRequest`       | v1alpha1 | Aprovação pendente com avaliação de blast radius                      |
| `AuditEvent`            | v1alpha1 | Registro imutável de ações na plataforma AIOps                        |
| `ChaosExperiment`       | v1alpha1 | Experimento de engenharia do caos em recursos Kubernetes              |
| `ClusterRegistration`   | v1alpha1 | Cluster registrado para federação multi-cluster                       |
| `EscalationPolicy`      | v1alpha1 | Cadeias de escalação para gestão de incidentes                        |
| `IncidentSLA`           | v1alpha1 | Metas de SLA para resposta e resolução por severidade                 |
| `Instance`              | v1alpha1 | Configuração de instância do ChatCLI                                  |
| `Issue`                 | v1alpha1 | Problema operacional detectado e correlacionado                       |
| `NotificationPolicy`    | v1alpha1 | Regras de entrega de notificações multicanal                          |
| `PostMortem`            | v1alpha1 | Relatório completo do ciclo de vida do incidente                      |
| `RemediationPlan`       | v1alpha1 | Plano de remediação com mais de 54 tipos de ação                      |
| `Runbook`               | v1alpha1 | Procedimentos operacionais vinculados a tipos de issue                |
| `ServiceLevelObjective` | v1alpha1 | SLO com alertas de burn rate e error budgets                          |
| `SourceRepository`      | v1alpha1 | Vincula workloads ao repositório de código-fonte                      |

<Note>
  As CRDs são compartilhadas entre os charts server e operator. Se ambos estiverem instalados no mesmo cluster, as CRDs do chart instalado primeiro serão utilizadas.
</Note>

***

## Instalação via ArtifactHub

### ChatCLI Server

```bash theme={"system"}
helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --create-namespace \
  --set llm.provider=OPENAI \
  --set secrets.openaiApiKey=sk-xxx
```

### ChatCLI Operator

```bash theme={"system"}
helm install chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system --create-namespace
```

### A Partir do Código-Fonte

```bash theme={"system"}
git clone https://github.com/diillson/chatcli.git

# Server
helm install chatcli deploy/helm/chatcli \
  --namespace chatcli --create-namespace

# Operator
helm install chatcli-operator deploy/helm/chatcli-operator \
  --namespace chatcli-system --create-namespace
```

### Usando um Secret Existente

```bash theme={"system"}
kubectl create secret generic chatcli-llm-keys \
  --namespace chatcli \
  --from-literal=OPENAI_API_KEY=sk-xxx \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-xxx

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli \
  --set llm.provider=OPENAI \
  --set secrets.existingSecret=chatcli-llm-keys
```

***

## Atualização e Remoção

### Atualizar para a Última Versão

```bash theme={"system"}
# Server
helm upgrade chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --reuse-values

# Operator
helm upgrade chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system --reuse-values
```

<Note>
  **CRDs são atualizados automaticamente** (GAP-06 fix). Ambos charts incluem
  um Helm Job `pre-install,pre-upgrade` que roda `kubectl apply --server-side`
  em todas as CRDs do chart antes do controller rolar. Sem esse hook, o
  `helm upgrade` mantém os CRDs antigos por design do Helm 3 e o binário novo
  quebra ao escrever campos/enums que o schema antigo não conhece (foi
  exatamente o sintoma da regressão pós-1.152.0).

  **Opt-out** quando você gerencia CRDs fora do Helm (cert-manager-style
  chart separado, GitOps com aplicação explícita):

  ```bash theme={"system"}
  helm upgrade ... --set crdUpgrade.enabled=false
  ```

  O `NOTES.txt` printa um warning com o comando manual quando o hook está
  desabilitado. Veja [Chaos Test Fixes — GAP-06](/pt/features/aiops/chaos-test-2026-05-23-fixes#gap-06-crds-nao-atualizados-no-helm-upgrade-alta-regressao-pos-1.152.0)
  para o detalhe completo.
</Note>

### Desinstalar

```bash theme={"system"}
helm uninstall chatcli -n chatcli
helm uninstall chatcli-operator -n chatcli-system
```

<Warning>
  As CRDs **não** são removidas automaticamente pelo Helm. Para removê-las manualmente:

  ```bash theme={"system"}
  kubectl get crd -o name | grep platform.chatcli.io | xargs kubectl delete
  ```
</Warning>

***

## Estrutura dos Charts

Os Helm charts ficam em `deploy/helm/` no repositório:

```
deploy/helm/
├── chatcli/                          # Chart do servidor
│   ├── Chart.yaml                    # Metadados + anotações ArtifactHub
│   ├── README.md                     # Documentação exibida no ArtifactHub
│   ├── values.yaml                   # Valores padrão (322 linhas)
│   ├── crds/                         # 17 CRDs YAML
│   │   ├── platform.chatcli.io_aiinsights.yaml
│   │   ├── platform.chatcli.io_anomalies.yaml
│   │   └── ... (15 mais)
│   └── templates/
│       ├── deployment.yaml
│       ├── service.yaml
│       ├── secret.yaml
│       ├── configmap.yaml
│       ├── rbac.yaml
│       ├── hpa.yaml
│       ├── pdb.yaml
│       ├── ingress.yaml
│       ├── networkpolicy.yaml
│       ├── pvc.yaml
│       ├── serviceaccount.yaml
│       ├── servicemonitor.yaml
│       ├── mcp-configmap.yaml
│       ├── agents-configmap.yaml
│       ├── bootstrap-configmap.yaml
│       ├── skills-configmap.yaml
│       └── _helpers.tpl
│
└── chatcli-operator/                 # Chart do operator
    ├── Chart.yaml
    ├── README.md
    ├── values.yaml
    ├── crds/
    └── templates/
```

***

## Diferenças entre os Charts

| Aspecto                       | ChatCLI Server                             | ChatCLI Operator                                     |
| ----------------------------- | ------------------------------------------ | ---------------------------------------------------- |
| **Função**                    | Gateway gRPC de LLMs com agentes e watcher | Detecção autônoma de incidentes e remediação         |
| **Tipo no ArtifactHub**       | Application                                | Operator                                             |
| **`artifacthub.io/operator`** | `false`                                    | `true`                                               |
| **Capabilities**              | —                                          | Seamless Upgrades                                    |
| **Exemplos de CRDs**          | Issue, ApprovalPolicy, SLO                 | Issue, ApprovalPolicy, ChaosExperiment, SLO          |
| **Keywords**                  | chatcli, llm, grpc, ai, mcp, aiops         | operator, aiops, remediation, sre, chaos-engineering |
| **Registry OCI**              | `oci://ghcr.io/diillson/charts/chatcli`    | `oci://ghcr.io/diillson/charts/chatcli-operator`     |

***

## Segurança dos Charts

Ambos os charts seguem as melhores práticas de segurança para Kubernetes:

<CardGroup cols={2}>
  <Card title="Non-Root" icon="shield-halved">
    Containers executam como usuário não-root (UID 1000) com `runAsNonRoot: true`.
  </Card>

  <Card title="Filesystem Read-Only" icon="lock">
    `readOnlyRootFilesystem: true` — apenas volumes montados são graváveis.
  </Card>

  <Card title="Capabilities Removidas" icon="ban">
    Todas as Linux capabilities são removidas com `drop: ["ALL"]`.
  </Card>

  <Card title="Seccomp" icon="fingerprint">
    Perfil `RuntimeDefault` do seccomp habilitado por padrão.
  </Card>
</CardGroup>

***

## Requisitos

* **Kubernetes**: 1.30+
* **Helm**: 3.10+ (suporte a registros OCI)
* **Provedor LLM**: Pelo menos uma API key configurada (OpenAI, Anthropic, Google, xAI, StackSpot, GitHub Copilot ou Ollama)

***

## Próximos Passos

<CardGroup cols={3}>
  <Card title="Deploy com Docker e K8s" icon="docker" href="/pt/getting-started/docker-deployment">
    Guia completo de deployment com Docker, Compose e Helm.
  </Card>

  <Card title="K8s Operator" icon="dharmachakra" href="/pt/features/k8s-operator">
    Detalhes do operator AIOps com 17 CRDs.
  </Card>

  <Card title="Plataforma AIOps" icon="brain" href="/pt/features/aiops-platform">
    Visão geral da plataforma de operações inteligentes.
  </Card>
</CardGroup>