Configuración del complemento Faro

Headlamp es un panel de control de Kubernetes que proporciona una interfaz gráfica de usuario para gestionar y supervisar los recursos de su clúster. El complemento Headlamp para IBM Cloud® Kubernetes Service proporciona una instalación perfecta de Headlamp con gestión automática del ciclo de vida e integración con IBM Cloud Identity and Access Management (IAM) para la autenticación.

Comprender el complemento Faro

El complemento Headlamp es el reemplazo recomendado para el proyecto archivado kubernetes-dashboard. Headlamp proporciona una interfaz moderna y fácil de usar para visualizar y gestionar los recursos Kubernetes en su clúster.

Entre las principales características del complemento Faro se incluyen:

  • Autenticación IAM OIDC: Autentifícate sin problemas con tu cuenta de IBM Cloud utilizando IAM OIDC.
  • Gestión independiente del ciclo de vida: La versión complementaria se desacopla de las versiones de la lista de materiales maestra del clúster, lo que permite realizar actualizaciones independientes.
  • Listo para acceder: El complemento se expone automáticamente a través de un recurso Ingress en el nombre de host ingress público predeterminado de su clúster con un subdominio headlamp.
  • Acceso seguro: Cada clúster recibe un ID de cliente OIDC único para evitar ataques de suplantación de autenticación.

Requisitos previos

Antes de instalar el complemento Faro, asegúrese de que su cluster cumple los siguientes requisitos:

Instalación del complemento Faro

Actualmente, el complemento Faro sólo está disponible a través de la CLI. No es posible instalar o gestionar el complemento desde la consola IBM Cloud.

Instalación del complemento Headlamp mediante la CLI

  1. Actualiza el complemento container-service a la versión más reciente.
    ibmcloud update && ibmcloud plugin update container-service
  2. Seleccione su clúster como destino.
    ibmcloud ks cluster config --cluster CLUSTER_NAME_OR_ID
  3. Habilite el complemento headlamp.
    ibmcloud ks cluster addon enable headlamp --cluster CLUSTER_NAME_OR_ID
  4. Comprueba que el complemento Headlamp tenga el estado Addon Ready.
    ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID
    Salida de ejemplo:
    NAME       Version   Health State   Health Status
headlamp   0.1.0     normal         Addon Ready
  5. Comprueba que los módulos Headlamp estén en funcionamiento.
    kubectl get pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp

Acceso al cuadro de mandos de los faros

Una vez instalado el complemento Headlamp, podrá acceder al panel de control a través del nombre de host de entrada predeterminado de su clúster.

  1. Obtenga el nombre de host de entrada predeterminado de su clúster.

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

  2. Abra su navegador y navegue hasta https://headlamp.<ingress_subdomain>, donde <ingress_subdomain> es el nombre de host de entrada predeterminado de su clúster.

    Ejemplo:https://headlamp.mycluster-abc123-0000.us-south.containers.appdomain.cloud

  3. Haga clic en Iniciar sesión para autenticarse con IBM Cloud IAM.

  4. Si aún no ha iniciado sesión en IBM Cloud, se le redirigirá a la página de inicio de sesión de IAM. Tras la autenticación, se le redirigirá de nuevo al panel de control de Headlamp.

  5. Una vez autenticado, podrá ver y gestionar los recursos de su clúster a través de la interfaz de Headlamp.

Migración desde kubernetes-dashboard

La comunidad Kubernetes ha archivado el proyecto kubernetes-dashboard. Después de instalar el complemento Headlamp, puede reducir la implementación de kubernetes-dashboard si se está ejecutando en su clúster.

Para reducir el despliegue de kubernetes-dashboard después de instalar Headlamp:

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

Comprender la autentificación de los faros

El complemento Headlamp utiliza la autenticación IAM OIDC de IBM Cloud para proteger el acceso a los recursos de su clúster.

Al activar el complemento Headlamp, se configuran automáticamente los siguientes componentes de autenticación:

  • ID de cliente único: Se crea un ID de cliente OIDC único para su clúster y se almacena en un secreto Kubernetes en el espacio de nombres ibm-system.
  • OIDC híbrido público-privado: Headlamp utiliza puntos finales IAM privados para las solicitudes de backchannel, mientras que el frontchannel (inicio de sesión en el navegador) se realiza a través de puntos finales IAM públicos.
  • Gestión de tokens: Los tokens de autenticación se almacenan en las cookies del navegador y se incluyen automáticamente en las solicitudes al servidor API Kubernetes.

El flujo de autenticación funciona del siguiente modo:

  1. Cuando acceda al panel de control de Headlamp, se le presentará una página de inicio de sesión.
  2. Al hacer clic en Iniciar sesión, se le redirige al punto final de autorización IAM público de IBM Cloud.
  3. Tras autenticarse correctamente, IAM le redirige de nuevo a Headlamp con un código de autorización.
  4. Headlamp intercambia el código de autorización por un token de acceso a través de una red privada.
  5. El token de acceso se utiliza para autenticar las solicitudes al servidor API Kubernetes.

Su acceso a los recursos del clúster está determinado por sus roles IAM de IBM Cloud y los permisos RBAC de Kubernetes aplicados por el servidor API de Kubernetes.

Actualización del complemento Faro

El complemento Faro se actualiza automáticamente cuando se publican nuevas versiones. Puede comprobar la versión actual y el estado de salud del complemento en cualquier momento.

Para comprobar la versión del complemento:

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Desactivar el complemento Faro

Si ya no necesitas el panel del faro, puedes desactivar el complemento.

Al desactivar el complemento Headlamp, se eliminan los siguientes recursos:

  • Despliegue de faros y vainas
  • Servicio de faros y recursos de entrada
  • ID de cliente OIDC y secretos asociados

Desactivación del complemento Headlamp con la CLI

  1. Desactiva el complemento Faro.
    ibmcloud ks cluster addon disable headlamp --cluster <cluster_name_or_ID>
  2. Verifique que el complemento se ha eliminado.
    ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Acceso a Headlamp a través de la entrada privada en clusters VPC

Configure su clúster VPC para acceder a Headlamp a través de la entrada privada en lugar de la entrada pública para mejorar la seguridad.

Cuando elija acceder a Headlamp desde redes privadas, como a través de una VPN VPC, puede reconfigurar su clúster con los siguientes pasos:

  1. Desactive el ALB público de su clúster.

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

  2. Activar la entrada privada.

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

  3. Registrar un dominio en el ALB privado.

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

  4. Establece el nuevo dominio como predeterminado.

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

El backend IBM Cloud actualiza el faro en aproximadamente 5 minutos. Cuando finalice la actualización, el panel de control estará disponible en el nuevo nombre de host de entrada predeterminado, con el subdominio headlamp..

Exposición de Headlamp con la pasarela de acceso Istio

Si tu clúster redirige el tráfico externo a través de la puerta de enlace de entrada de Istio, puedes desactivar los recursos de Ingress predeterminados que crea el complemento Headlamp y, en VirtualService su lugar, exponer Headlamp mediante Istio Gateway y.

Debes exponer Headlamp a través de un subdominio proporcionado por IBM en el dominio *.containers.appdomain.cloud. El ID de cliente OIDC de tu clúster está registrado con un URI de redireccionamiento que coincide con ese dominio. El nombre de host sin procesar del equilibrador de carga istio-ingressgateway no pertenece a ese dominio, y la autenticación falla si se utiliza directamente.

Antes de empezar

  1. Abre el archivo ConfigMapheadlamp-values para editarlo y desactivar los recursos de Ingress predeterminados que crea el complemento Headlamp.

    kubectl edit cm -n ibm-system headlamp-values

    Añade lo siguiente a la sección data para evitar que el complemento cree los recursos predeterminados de NGINX y Traefik Ingress.

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

  2. Espera hasta 5 minutos a que los valores actualizados se propaguen al clúster.

  3. Comprueba que se hayan eliminado los recursos predeterminados de Ingress.

    kubectl get ingress -n ibm-system

  4. Obtén la dirección IP (clústeres clásicos) o el nombre de host (clústeres VPC) del equilibrador de carga istio-ingressgateway.

    • Clústeres clásicos:
        kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    ```
* Clústeres VPC:
```sh {: pre}
    kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
    ```
Si el comando devuelve un valor vacío, significa que el equilibrador de carga aún no se ha aprovisionado. Comprueba que el servicio disponga de una IP externa y revisa los eventos del servicio en busca de errores, como un límite de cuota del equilibrador de carga.
{: note}

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

  5. Registra la dirección IP (clásica) o el nombre de host (VPC) del equilibrador de carga creando un subdominio proporcionado por IBM. Especifica el espacio istio-system de nombres del secreto TLS para que el certificado TLS esté disponible para el istio-ingressgateway.

    • Clústeres clásicos:
        ibmcloud ks nlb-dns create classic --cluster <cluster_name_or_ID> --ip <istio_ingressgateway_IP> --secret-namespace istio-system
    ```
* Clústeres VPC:
```sh {: pre}
    ibmcloud ks nlb-dns create vpc-gen2 --cluster <cluster_name_or_ID> --lb-host <istio_ingressgateway_hostname> --secret-namespace istio-system
    ```

  6. Comprueba que se haya creado el subdominio y anota el subdominio y el nombre secreto del certificado SSL.

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

    Ejemplo de salida para clústeres clásicos:

    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

    Ejemplo de salida para clústeres de 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

    Si el clúster tiene varias entradas NLB-DNS, identifica el subdominio que has creado en el paso anterior haciendo coincidir la columna IP(s) Target(s) o con la dirección del equilibrador de carga istio-ingressgateway, y comprobando que la columna Secret Namespace muestre istio-system.

  7. Crea un archivo llamado headlamp-istio.yaml que defina un y Gateway un para VirtualService Headlamp. Sustituye <subdomain> por el subdominio del paso anterior y <ssl_cert_secret_name> por el nombre secreto del certificado SSL.

    El secreto del certificado TLS se crea en el espacio istio-system de nombres. El istio-ingressgateway lee el secreto indicado en el campo credentialName de ese espacio de nombres. No copie el valor del certificado en el 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

  8. Utiliza los recursos VirtualService Gateway y.

    kubectl apply -f headlamp-istio.yaml

  9. Abre el panel de control de Headlamp en un navegador web utilizando el subdominio que anotaste en el paso 6.

    https://<subdomain>

    Para comprobar la conectividad desde la línea comando, ejecute el siguiente comando. Utiliza la opción -k para omitir la verificación del certificado únicamente durante las pruebas; no la utilices -k en entornos de producción.

    curl -k -s -o /dev/null -w "%{http_code}\n" https://<subdomain>

Kubernetes recursos creados por el complemento

El complemento Headlamp crea varios recursos Kubernetes en su clúster que requieren una configuración de red adecuada.

Si tiene un cortafuegos o una configuración de red personalizados, deberá configurarlos para permitir la comunicación entre los siguientes recursos:

  • 4 Recursos de Ingress
    • privado con private-iks-k8s-nginx ingressClass
    • público con public-iks-k8s-nginx ingressClass
    • privado con private-iks-traefik ingressClass
    • público con public-iks-traefik ingressClass
  • 1 Servicio ( ClusterIP en el puerto 80 → 4466)
  • 1 Despliegue
    • contenedor faro (puerto 4466)
    • contenedor sidecar nginx

Habilitar OIDC para el complemento Headlamp a través de puntos de acceso públicos

Si tu clúster no puede conectarse a los puntos de conexión privados de IAM, modifica la configuración de los puntos de conexión OIDC para utilizar puntos de conexión públicos.

Estos pasos dan por hecho que el clúster puede acceder a los puntos de conexión públicos de IAM.

Antes de empezar, asegúrate de que kubectl esté configurado para el clúster.

  1. Abre el archivo ConfigMap headlamp-values para editarlo:

    kubectl edit cm -n ibm-system headlamp-values

    En el editor, añade lo siguiente a la sección « data ». Sustituye « <account_id> » por el ID de la cuenta en la que está implementado el clúster.

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

  2. Espera hasta 5 minutos a que los valores actualizados se propaguen al clúster.

  3. Reiniciar la implementación de Headlamp:

    kubectl rollout restart deployment/headlamp -n ibm-system

Solución de problemas con el complemento Faro

Utilice la siguiente información para solucionar problemas comunes con el complemento Faro.

No se puede acceder al cuadro de mandos de los faros

Si no puede acceder al panel de control del faro, compruebe lo siguiente:

  1. Comprueba que el complemento esté instalado y funcione correctamente.
    ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
  2. Comprueba que los módulos Headlamp estén en funcionamiento.
    kubectl get pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp
  3. Comprueba que el recurso de Ingress esté configurado correctamente.
    kubectl get ingress -n ibm-system
  4. En el caso de los clústeres exclusivamente públicos, comprueba que las reglas de seguridad de red permitan las conexiones salientes de HTTPS a los puntos finales públicos de IAM. Si es necesario, consulta « Habilitar OIDC para el complemento Headlamp a través de puntos finales públicos » para actualizar la configuración de OIDC.

La autenticación falla

Si falla la autenticación al acceder al panel de control del faro:

  1. Compruebe que dispone de los permisos IAM necesarios para acceder al clúster.

  2. Compruebe que su navegador puede acceder a https://iam.cloud.ibm.com.

  3. Borra las cookies de tu navegador e inténtalo de nuevo.

  4. Compruebe que el secreto de ID de cliente OIDC existe en su clúster.

    kubectl get secret clientid-secrets -n ibm-system

Los pods no funcionan

Si las vainas de los faros no funcionan:

  1. Compruebe el estado y los eventos del pod.
    kubectl describe pods -n ibm-system -l app.kubernetes.io/name=addon-headlamp
  2. Comprueba si hay errores en los registros del pod.
    kubectl logs -n ibm-system -l app.kubernetes.io/name=addon-headlamp