> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/getting-started/installation-kubernetes-helm.md).

# Instalação: Kubernetes (Helm)

Implemente o KiloCenter no Kubernetes com Helm — chart, pré-requisitos (k8s 1.25+, PostgreSQL 14+, Redis 7+) e ingress.

### Objetivo

Implante o KiloCenter num cluster Kubernetes usando o chart Helm incluído neste repositório.

### Pré-requisitos

| Requisito          | Versão mínima |
| ------------------ | ------------- |
| Cluster Kubernetes | 1.25+         |
| Helm               | 3.x           |
| PostgreSQL externo | 14+           |
| Redis externo      | 7+            |

PostgreSQL e Redis **não** são implantados por este chart. Providencie-os separadamente (serviços geridos, operadores ou independente) e forneça os detalhes de ligação na sua substituição de valores.

### Arquitetura

```
                  Internet
                     |
               [ Ingress ] (opcional)
                /         \
         kc-web:80    kc-gateway:9090
                          |
                    kc-core:50051 ---- kc-identity:50052
                    /      |      \
             bssci:5000  scaci:5001  mosquitto:1883
                                         |
                                    [clientes MQTT]
```

O chart implanta cinco serviços e um broker MQTT:

| Componente    | Porta(s)                                               | Descrição                                        |
| ------------- | ------------------------------------------------------ | ------------------------------------------------ |
| `kc-core`     | 50051 (gRPC), 5000 (BSSCI), 5001 (SCACI), 8086 (saúde) | Motor do centro de serviço                       |
| `kc-gateway`  | 9090 (gRPC-web), 8087 (saúde)                          | Entrada da API externa                           |
| `kc-identity` | 50052 (gRPC), 8088 (saúde)                             | Identidade, utilizadores, organizações           |
| `kc-web`      | 80                                                     | Interface de gestão web (nginx)                  |
| `mosquitto`   | 1883, 9001 (WebSocket)                                 | broker MQTT                                      |
| `certgen`     | —                                                      | Hook de pré-instalação que gera certificados TLS |

### Passo 1: Crie uma Substituição de Valores

No mínimo, substitua as definições da base de dados, do Redis e dos segredos:

```yaml
# my-values.yaml
postgresql:
  host: my-postgres.default.svc.cluster.local
  password: "a-strong-password"
  sslMode: "require"

redis:
  host: my-redis.default.svc.cluster.local

secrets:
  authHmacSecret: "replace-with-a-random-string-at-least-32-bytes"
  mqttAdminPassword: "strong-mqtt-admin-pw"
  mqttClientPassword: "strong-mqtt-client-pw"

certgen:
  serverName: "kilocenter.example.com"
```

> **Importante:** O `authHmacSecret` é usado para assinar e verificar tokens JWT entre o KC-Gateway e o KC-Identity. Deve ter, no mínimo, 32 caracteres.

### Passo 2: Instale

```bash
helm install kilocenter ./helm/kilocenter -f my-values.yaml
```

Na primeira instalação, é executado um Job de hook de pré-instalação que corre o `certgen` binário para gerar uma CA autoassinada e um certificado de servidor num PVC partilhado. As atualizações subsequentes ignoram a geração se os certificados já existirem.

### Passo 3: Validar

```bash
# Verifique se todos os pods estão em execução
kubectl get pods -l app.kubernetes.io/instance=kilocenter

# Verifique a saúde dos serviços
kubectl exec deploy/kilocenter-kc-core -- wget -qO- http://localhost:8086/health/ping
kubectl exec deploy/kilocenter-kc-identity -- wget -qO- http://localhost:8088/health
kubectl exec deploy/kilocenter-kc-gateway -- wget -qO- http://localhost:8087/health
```

### Passo 4: Aceda à interface

Sem ingress, use encaminhamento de porta:

```bash
kubectl port-forward svc/kilocenter-kc-web 8080:80
```

Depois abra <http://localhost:8080/> no seu navegador.

### Conta de Administrador Padrão

Na primeira inicialização, é criado um utilizador administrador padrão através da migração da base de dados:

|                   |                               |
| ----------------- | ----------------------------- |
| **Email**         | `admin [at] kilocenter.local` |
| **Palavra-passe** | `admin123!`                   |

> Substitua `[at]` por `@` ao iniciar sessão.

> **Aviso:** Altere a palavra-passe ou remova esta conta antes de qualquer implementação voltada para o público. As credenciais estão publicadas neste repositório.

### Ingress

Ative o Ingress padrão do Kubernetes na sua substituição de valores:

```yaml
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: kilocenter.example.com
      paths:
        - path: /
          pathType: Prefix
          service: kc-web
          port: 80
        - path: /kilocenter.api
          pathType: Prefix
          service: kc-gateway
          port: 9090
  tls:
    - secretName: kilocenter-tls
      hosts:
        - kilocenter.example.com
```

Ao usar ingress, adicione o seu domínio às origens permitidas de CORS:

```yaml
kcGateway:
  config:
    corsOrigins:
      - "https://kilocenter.example.com"
```

### Acesso ao Protocolo BSSCI/SCACI

As estações base ligam-se diretamente ao KC-Core via TCP+TLS nas portas 5000 (BSSCI) e 5001 (SCACI). Estas são ligações TCP brutas, não HTTP. Para expô-las externamente, crie um serviço LoadBalancer:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: kilocenter-bssci
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: kc-core
    app.kubernetes.io/instance: kilocenter
  ports:
    - name: bssci
      port: 5000
      targetPort: 5000
    - name: scaci
      port: 5001
      targetPort: 5001
```

### Certificados TLS

O `certgen` o hook gera uma CA autoassinada e um certificado de servidor na primeira instalação. Em produção, substitua-os por certificados assinados por uma CA de confiança montando o seu próprio secret ou PVC em `/app/certificates` no pod kc-core.

### Referência de Configuração

Para a lista completa dos parâmetros configuráveis, consulte o README do chart Helm.

### Atualização

```bash
helm upgrade kilocenter ./helm/kilocenter -f my-values.yaml
```

Defina uma tag de imagem específica para fixar uma versão:

```yaml
global:
  imageTag: "1.0.0"
```

### Resolução de Problemas

| Sintoma                                 | Causa provável                    | Correção                                                                                      |
| --------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| Pods em `ImagePullBackOff`              | Secret de pull da imagem em falta | Adicione `global.imagePullSecrets` com as credenciais do seu registo                          |
| Probe de readiness do KC-Core 503       | Dependência não pronta            | Verifique se o KC-Identity e o PostgreSQL estão em execução                                   |
| `invalid_token` após o início de sessão | Incompatibilidade do segredo HMAC | Certifique-se de que `secrets.authHmacSecret` está definido (o mesmo para gateway e identity) |
| Ligação BSSCI recusada                  | Nenhum serviço externo            | Crie um serviço LoadBalancer para as portas 5000/5001                                         |
| Erros de gRPC-web no navegador          | CORS ou ingress mal configurado   | Verifique `kcGateway.config.corsOrigins` e os caminhos do ingress                             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/getting-started/installation-kubernetes-helm.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.