ArtifactHub

O ChatCLI publica seus Helm charts no ArtifactHub, 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

ChatCLI Server

Gateway gRPC multi-provedor de LLMs com modo agente, K8s watcher, MCP e AIOps. Registry OCI: oci://ghcr.io/diillson/charts/chatcli

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

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

repositoryID: 193ab92d-52ac-4ac1-863f-aa29927c8d74
owners:
  - name: Edilson Freitas
    email: diillson@hotmail.com

artifacthub/chatcli-operator-repo.yml

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 com o MIME type application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml, permitindo que o ArtifactHub descubra e indexe os charts automaticamente.

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.

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:

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:

Trigger do release

Um push na branch main aciona o Release Please, que cria automaticamente um PR de release e, ao ser mergeado, gera a GitHub Release com a tag de versão.

Versionamento automático

O pipeline atualiza a versão nos Chart.yaml de ambos os charts:

sed -i "s/^version:.*/version: ${VERSION}/" deploy/helm/chatcli/Chart.yaml
sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" deploy/helm/chatcli/Chart.yaml

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.

Empacotamento

Os charts são empacotados com helm package:

helm package deploy/helm/chatcli/ -d /tmp/charts/
helm package deploy/helm/chatcli-operator/ -d /tmp/charts/

Push para o registro OCI

Os pacotes são enviados para o GitHub Container Registry:

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

Assinatura com Cosign

Ambos os charts são assinados com Cosign usando OIDC keyless, garantindo a integridade e procedência dos artefatos:

cosign sign --yes "ghcr.io/diillson/charts/chatcli@${CHART_DIGEST}"
cosign sign --yes "ghcr.io/diillson/charts/chatcli-operator@${CHART_DIGEST}"

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:

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

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.

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

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.

Instalação via ArtifactHub

ChatCLI Server

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --create-namespace \
  --set llm.provider=OPENAI \
  --set secrets.openaiApiKey=sk-xxx

ChatCLI Operator

helm install chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system --create-namespace

A Partir do Código-Fonte

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

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

# Server
helm upgrade chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --reset-then-reuse-values

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

--reset-then-reuse-values (Helm 3.14+) parte dos padrões do chart novo e reaplica os seus overrides anteriores. O --reuse-values puro ignora os padrões de chaves acrescentadas por versões novas do chart e pode quebrar a renderização; com um Helm mais antigo, passe o seu arquivo de values (-f meus-values.yaml). Antes de atualizar o operator atravessando várias releases, leia Upgrade e desinstalação: o que reinicia, o que o status da Instance mostra durante o rollout e as releases que exigem ação antes. Para o chart do servidor, veja Upgrade, rollback, desinstalação.

Os CRDs são atualizados em todo upgrade. Os dois charts rodam um Job de hook pre-install,pre-upgrade que aplica todos os CRDs do chart com kubectl apply --server-side antes do rollout do controller novo. O Helm em si nunca atualiza crds/ depois da primeira instalação, e um controller rodando contra um schema antigo tem os campos novos descartados e os valores novos de enum recusados. Desligue o hook (--set crdUpgrade.enabled=false) só quando você gerencia os CRDs por fora, e aí aplique o crds/ do chart novo você mesmo antes do upgrade; as notas de instalação do chart do operator imprimem os comandos.

Desinstalar

Apague seus recursos Instance antes de remover o operator: o operator remove o finalizer deles, e uma Instance apagada depois que ele saiu fica em Terminating (veja Desinstalar).

kubectl delete instances --all -A     # com o operator ainda rodando
helm uninstall chatcli -n chatcli
helm uninstall chatcli-operator -n chatcli-system

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

kubectl get crd -o name | grep platform.chatcli.io | xargs kubectl delete

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:

Non-Root

Containers executam como usuário não-root (UID 1000) com runAsNonRoot: true.

Filesystem Read-Only

readOnlyRootFilesystem: true — apenas volumes montados são graváveis.

Capabilities Removidas

Todas as Linux capabilities são removidas com drop: ["ALL"].

Seccomp

Perfil RuntimeDefault do seccomp habilitado por padrão.

Requisitos

Kubernetes: 1.30+
Helm: 3.8+ (suporte a registros OCI), Helm 4 incluído
Provedor LLM: Uma credencial de pelo menos um provider suportado (uma API key, IAM no Bedrock, ou um Ollama local)

Próximos Passos

Deploy com Docker e K8s

Guia completo de deployment com Docker, Compose e Helm.

K8s Operator

Detalhes do operator AIOps com 17 CRDs.

Plataforma AIOps

Visão geral da plataforma de operações inteligentes.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Charts Disponíveis

ChatCLI Server

ChatCLI Operator

Como Funciona a Integração

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

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

Anotações Disponíveis

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

CRDs Documentadas

Instalação via ArtifactHub

ChatCLI Server

ChatCLI Operator

A Partir do Código-Fonte

Usando um Secret Existente

Atualização e Remoção

Atualizar para a Última Versão

Desinstalar

Estrutura dos Charts

Diferenças entre os Charts

Segurança dos Charts

Non-Root

Filesystem Read-Only

Capabilities Removidas

Seccomp

Requisitos

Próximos Passos

Deploy com Docker e K8s

K8s Operator

Plataforma AIOps

​Charts Disponíveis

ChatCLI Server

ChatCLI Operator

​Como Funciona a Integração

​1. Arquivos de Repositório (artifacthub/)

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

​Anotações Disponíveis

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

​CRDs Documentadas

​Instalação via ArtifactHub

​ChatCLI Server

​ChatCLI Operator

​A Partir do Código-Fonte

​Usando um Secret Existente

​Atualização e Remoção

​Atualizar para a Última Versão

​Desinstalar

​Estrutura dos Charts

​Diferenças entre os Charts

​Segurança dos Charts

Non-Root

Filesystem Read-Only

Capabilities Removidas

Seccomp

​Requisitos

​Próximos Passos

Deploy com Docker e K8s

K8s Operator

Plataforma AIOps

Charts Disponíveis

Como Funciona a Integração

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

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

Anotações Disponíveis

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

CRDs Documentadas

Instalação via ArtifactHub

ChatCLI Server

ChatCLI Operator

A Partir do Código-Fonte

Usando um Secret Existente

Atualização e Remoção

Atualizar para a Última Versão

Desinstalar

Estrutura dos Charts

Diferenças entre os Charts

Segurança dos Charts

Requisitos

Próximos Passos