Configuração do complemento Headlamp

O Headlamp é um painel do site Kubernetes que fornece uma interface gráfica de usuário para gerenciar e monitorar os recursos do cluster. O complemento Headlamp para IBM Cloud® Kubernetes Service oferece uma instalação perfeita do Headlamp com gerenciamento automático do ciclo de vida e integração com IBM Cloud Identity and Access Management (IAM) para autenticação.

Entendendo o complemento do farol

O complemento Headlamp é o substituto recomendado para o projeto kubernetes-dashboard arquivado. O Headlamp oferece uma interface moderna e fácil de usar para visualizar e gerenciar os recursos do Kubernetes em seu cluster.

Os principais recursos do complemento Headlamp incluem:

Autenticação do IAM OIDC: Autentique-se perfeitamente com sua conta IBM Cloud usando o IAM OIDC.
Gerenciamento independente do ciclo de vida: A versão complementar é desacoplada das versões da lista técnica mestre do cluster, permitindo atualizações independentes.
Pronto para acessar: O complemento é exposto automaticamente por meio de um recurso Ingress no nome de host de ingresso público padrão do seu cluster com um subdomínio headlamp.
Acesso seguro: Cada cluster recebe um ID de cliente OIDC exclusivo para evitar ataques de falsificação de autenticação.

Pré-requisitos

Antes de instalar o add-on Headlamp, certifique-se de que seu cluster atenda aos seguintes requisitos:

Você deve ter a função de acesso ao serviço IAM Writer ou Manager IBM Cloud para IBM Cloud Kubernetes Service.
Seu cluster deve estar executando uma versão compatível do Kubernetes.
Para clusters Classic, você deve ativar o VRF e os pontos de extremidade de serviço.
Seu navegador deve ter acesso a:
- O nome de host de entrada padrão do cluster.
- O endpoint de autorização do IAM IBM Cloud em https://iam.cloud.ibm.com.

Instalação do complemento do farol

No momento, o complemento Headlamp só está disponível por meio da CLI. Não é possível instalar ou gerenciar o add-on no console IBM Cloud.

Instalando o complemento Headlamp pela CLI

Atualize o plug-in “ container-service ” para a versão mais recente.
```
ibmcloud update && ibmcloud plugin update container-service
```

Aponte seu cluster como destino.

ibmcloud ks cluster config --cluster CLUSTER_NAME_OR_ID

Ative o complemento headlamp.

ibmcloud ks cluster addon enable headlamp --cluster CLUSTER_NAME_OR_ID

Verifique se o complemento “Headlamp” está com o status “ Addon Ready ”.

ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID

Saída de exemplo:

NAME       Version   Health State   Health Status
headlamp   0.1.0     normal         Addon Ready

Verifique se os módulos dos faróis estão funcionando.

kubectl get pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp

Acesso ao painel do farol

Depois de instalar o complemento Headlamp, você poderá acessar o painel por meio do nome de host de entrada padrão do seu cluster.

Obtenha o nome de host de entrada padrão de seu cluster.

ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep "Ingress Subdomain"

Abra seu navegador e navegue até https://headlamp.<ingress_subdomain>, onde <ingress_subdomain> é o nome de host de entrada padrão de seu cluster.

Exemplo:https://headlamp.mycluster-abc123-0000.us-south.containers.appdomain.cloud
Clique em Sign In para se autenticar no IBM Cloud IAM.
Se ainda não tiver feito login em IBM Cloud, você será redirecionado para a página de login do IAM. Após a autenticação, você será redirecionado para o painel do Headlamp.
Depois de autenticado, você pode visualizar e gerenciar os recursos do cluster por meio da interface do Headlamp.

Migrando do kubernetes-dashboard

A comunidade Kubernetes arquivou o projeto kubernetes-dashboard. Depois de instalar o complemento Headlamp, você pode reduzir a implantação do kubernetes-dashboard se ele estiver em execução no seu cluster.

Para reduzir a implantação do kubernetes-dashboard após a instalação do Headlamp:

kubectl scale deployment -n kube-system kubernetes-dashboard --replicas=0
kubectl scale deployment -n kube-system dashboard-metrics-scraper --replicas=0

Entendendo a autenticação do farol

O complemento Headlamp usa a autenticação IBM Cloud IAM OIDC para proteger o acesso aos recursos do cluster.

Quando você ativa o add-on Headlamp, os seguintes componentes de autenticação são configurados automaticamente:

ID de cliente exclusivo: Um ID de cliente OIDC exclusivo é criado para seu cluster e armazenado em um segredo Kubernetes no namespace ibm-system.
OIDC híbrido público-privado: o Headlamp usa pontos de extremidade IAM privados para solicitações de backchannel, enquanto o frontchannel - login no navegador - ocorre em pontos de extremidade IAM públicos.
Gerenciamento de tokens: Os tokens de autenticação são armazenados em cookies do navegador e incluídos automaticamente nas solicitações ao servidor da API Kubernetes.

O fluxo de autenticação funciona da seguinte forma:

Ao acessar o painel do Headlamp, você verá uma página de login.
Ao clicar em Sign In, você será redirecionado para o endpoint de autorização pública do IAM IBM Cloud.
Após a autenticação bem-sucedida, o IAM redireciona você de volta ao Headlamp com um código de autorização.
O Headlamp troca o código de autorização por um token de acesso em uma rede privada.
O token de acesso é usado para autenticar solicitações ao servidor da API Kubernetes.

Seu acesso aos recursos do cluster é determinado pelas funções de IAM IBM Cloud e pelas permissões RBAC Kubernetes aplicadas pelo servidor de API Kubernetes.

Atualizando o complemento Headlamp

O complemento Headlamp é atualizado automaticamente quando novas versões são lançadas. Você pode verificar a versão atual e o status de integridade do complemento a qualquer momento.

Para verificar a versão do complemento:

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Desativar o complemento Headlamp

Se você não precisar mais do painel Headlamp, poderá desativar o complemento.

Quando você desativa o complemento Headlamp, os seguintes recursos são removidos:

Implantação de faróis e cápsulas
Recursos de manutenção e entrada de faróis
ID do cliente OIDC e segredos associados

Desativar o complemento Headlamp com a CLI

Desative o complemento Headlamp.

ibmcloud ks cluster addon disable headlamp --cluster <cluster_name_or_ID>

Verifique se o complemento foi removido.

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Acesso ao Headlamp por meio de entrada privada em clusters VPC

Configure seu cluster VPC para acessar o Headlamp por meio de entrada privada em vez de entrada pública para aumentar a segurança.

Ao optar por acessar o Headlamp a partir de redes privadas, como em uma VPN VPC, você pode reconfigurar o cluster com as etapas a seguir:

Desative o ALB público de seu cluster.

ibmcloud ks ingress alb disable --cluster <cluster_name_or_ID> --alb <public_ALB_ID>

Habilitar o ingresso privado.

ibmcloud ks ingress alb enable vpc-gen2 --cluster <cluster_name_or_ID> --alb <private_ALB_ID>

Registre um domínio no ALB privado.

ibmcloud ks ingress domain create --cluster <cluster_name_or_ID> --hostname $<private_ALB_ID_hostname>

Defina o novo domínio como padrão.

ibmcloud ks ingress domain default replace --cluster <cluster_name_or_ID> --domain <new_domain>

O backend do IBM Cloud atualiza o headlamp em aproximadamente 5 minutos. Quando a atualização for concluída, o painel estará disponível no novo nome de host de entrada padrão, com o subdomínio headlamp..

Exposição do Headlamp com o gateway de entrada do Istio

Se o seu cluster encaminhar o tráfego externo por meio do gateway de entrada Istio, você poderá desativar os recursos de Ingress padrão criados pelo complemento Headlamp e, em vez disso, expor o Headlamp por meio de Istio, Gateway e VirtualService.

Você deve disponibilizar o Headlamp por meio de um subdomínio fornecido pelo IBM no domínio *.containers.appdomain.cloud. O ID do cliente OIDC do seu cluster está registrado com um URI de redirecionamento que corresponde a esse domínio. O nome do host do balanceador de carga istio-ingressgateway, em seu formato bruto, não está nesse domínio, e a autenticação falha se você o utilizar diretamente.

Antes de Iniciar

Ative o Complemento Istio gerenciado.
Configure o kubectl para direcionar para o cluster.

Abra o arquivo headlamp-values ( ConfigMap ) para edição, a fim de desativar os recursos padrão do Ingress criados pelo complemento Headlamp.

kubectl edit cm -n ibm-system headlamp-values

Adicione o seguinte à seção data para impedir que o complemento crie os recursos padrão NGINX e Traefik Ingress.

data:
  values.yaml: |-
    createDefaultPublicIngressNginx: false
    createDefaultPrivateIngressNginx: false
    createDefaultPublicIngressTraefik: false
    createDefaultPrivateIngressTraefik: false

Aguarde até 5 minutos para que os valores atualizados sejam propagados para o cluster.
Verifique se os recursos padrão do Ingress foram removidos.
```
kubectl get ingress -n ibm-system
```

Obtenha o endereço IP (clusters clássicos) ou o nome do host (clusters VPC) do balanceador de carga do istio-ingressgateway.

Clusters clássicos:

    kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    ```
* Clusters de VPC:
```sh {: pre}
    kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
    ```
Se o comando retornar um valor vazio, significa que o balanceador de carga ainda não foi provisionado. Verifique se o serviço possui um endereço IP externo e analise os eventos do serviço em busca de erros, como um limite de cota do balanceador de carga.
{: note}

```sh {: pre}
kubectl describe service istio-ingressgateway -n istio-system

Registre o endereço IP (clássico) ou o nome do host (VPC) do balanceador de carga criando um subdomínio fornecido pelo IBM. Especifique o namespace istio-system para o segredo TLS, de modo que o certificado TLS fique disponível para o istio-ingressgateway.

Clusters clássicos:

    ibmcloud ks nlb-dns create classic --cluster <cluster_name_or_ID> --ip <istio_ingressgateway_IP> --secret-namespace istio-system
    ```
* Clusters de VPC:
```sh {: pre}
    ibmcloud ks nlb-dns create vpc-gen2 --cluster <cluster_name_or_ID> --lb-host <istio_ingressgateway_hostname> --secret-namespace istio-system
    ```

Verifique se o subdomínio foi criado e anote o nome do subdomínio e o nome do segredo do certificado “ SSL ”.

ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>

Saída de exemplo para clusters clássicos:

Subdomain                                                                               IP(s)              SSL Cert Status   SSL Cert Secret Name                            Secret Namespace
mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud     ["168.1.1.1"]      created           mycluster-a1b2cdef345678g9hi012j3kl4567890-0001 istio-system

Saída de exemplo para clusters VPC:

Subdomain                                                                               Target(s)                                     SSL Cert Status   SSL Cert Secret Name                            Secret Namespace
mycluster-a1b2cdef345678g9hi012j3kl4567890-0001.us-south.containers.appdomain.cloud     1234abcd-us-south.lb.appdomain.cloud          created           mycluster-a1b2cdef345678g9hi012j3kl4567890-0001 istio-system

Se o cluster tiver várias entradas de NLB-DNS, identifique o subdomínio que você criou na etapa anterior, comparando a coluna Target(s) ou IP(s) com o endereço do balanceador de carga istio-ingressgateway e verificando se a coluna Secret Namespace exibe istio-system.

Crie um arquivo chamado “ headlamp-istio.yaml ” que defina um “ Gateway ” e um “ VirtualService ” para o Headlamp. Substitua <subdomain> pelo subdomínio da etapa anterior e <ssl_cert_secret_name> pelo nome do segredo do certificado SSL.

O segredo do certificado “ TLS ” é criado no namespace “ istio-system ”. O istio-ingressgateway lê o segredo indicado no campo credentialName desse namespace. Não copie o valor do certificado no recurso Gateway .

apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: headlamp-gateway
  namespace: ibm-system
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: SIMPLE
      credentialName: <ssl_cert_secret_name>
    hosts:
    - <subdomain>
---
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: headlamp
  namespace: ibm-system
spec:
  hosts:
  - <subdomain>
  gateways:
  - headlamp-gateway
  http:
  - route:
    - destination:
        host: headlamp.ibm-system.svc.cluster.local
        port:
          number: 80

Utilize os recursos Gateway e VirtualService.
```
kubectl apply -f headlamp-istio.yaml
```
Abra o painel do Headlamp em um navegador da web usando o subdomínio que você anotou na etapa 6.
```
https://<subdomain>
```
Para verificar a conectividade pela linha de comando, execute o comando a seguir. Use a opção -k para ignorar a verificação de certificados apenas durante os testes — não utilize -k em ambientes de produção.
```
curl -k -s -o /dev/null -w "%{http_code}\n" https://<subdomain>
```

Kubernetes recursos criados pelo addon

O complemento Headlamp cria vários recursos Kubernetes em seu cluster que exigem configuração de rede adequada.

Se você tiver um firewall personalizado ou configurações de rede, será necessário configurá-lo para permitir a comunicação entre os seguintes recursos:

4 Recursos do Ingress
- privado com private-iks-k8s-nginx ingressClass
- público com public-iks-k8s-nginx ingressClass
- private com private-iks-traefik ingressClass
- público com public-iks-traefik ingressClass
1 Serviço ( ClusterIP na porta 80 → 4466)
1 Implantação
- contêiner do farol (porta 4466)
- Contêiner sidecar do nginx

Ativar o OIDC para o complemento Headlamp por meio de endpoints públicos

Se o seu cluster não conseguir se conectar aos endpoints privados do IAM, substitua as configurações do endpoint OIDC para usar endpoints públicos.

Essas etapas pressupõem que o cluster tenha acesso aos endpoints públicos do IAM.

Antes de começar, certifique-se de que o kubectl esteja configurado para o cluster.

Abra o arquivo headlamp-values ConfigMap para edição:

kubectl edit cm -n ibm-system headlamp-values

No editor, adicione o seguinte à seção data . Substitua <account_id> pelo ID da conta na qual o cluster está implantado.

data:
  values.yaml: |-
    oidc:
      overrides:
        tokenEndpointUrl: "https://iam.cloud.ibm.com/identity/token?account=<account_id>"
        jwksUri: "https://iam.cloud.ibm.com/identity/keys"

Aguarde até 5 minutos para que os valores atualizados sejam propagados para o cluster.

Reinicie a implantação do Headlamp:

kubectl rollout restart deployment/headlamp -n ibm-system

Solução de problemas do complemento Headlamp

Use as informações a seguir para solucionar problemas comuns com o complemento Headlamp.

Não é possível acessar o painel do farol

Se não conseguir acessar o painel do Headlamp, verifique o seguinte:

Verifique se o complemento está instalado e funcionando corretamente.
```
ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
```

Verifique se os módulos dos faróis estão funcionando.

kubectl get pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp

Verifique se o recurso de entrada está configurado corretamente.
```
kubectl get ingress -n ibm-system
```
Para clusters exclusivamente públicos, verifique se as regras de segurança de rede permitem conexões de saída do tipo “ HTTPS ” para endpoints públicos do IAM. Se necessário, consulte “Ativar o OIDC para o complemento Headlamp em endpoints públicos ” para atualizar a configuração do OIDC.

Falha na autenticação

Se a autenticação falhar ao acessar o painel do Headlamp:

Verifique se você tem as permissões de IAM necessárias para acessar o cluster.
Verifique se o seu navegador pode acessar https://iam.cloud.ibm.com.
Limpe os cookies do navegador e tente novamente.
Verifique se o segredo do ID do cliente OIDC existe em seu cluster.
```
kubectl get secret clientid-secrets -n ibm-system
```

Os pods não estão funcionando

Se os pods do farol não estiverem funcionando:

Verifique o status e os eventos do pod.

kubectl describe pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp

Verifique se há erros nos logs do pod.

kubectl logs -n ibm-system -l app.kubernetes.io/name=addon-headlamp