Configuration du module complémentaire Headlamp

Headlamp est un tableau de bord Kubernetes qui fournit une interface utilisateur graphique pour la gestion et la surveillance des ressources de votre cluster. Le module complémentaire Headlamp pour IBM Cloud® Kubernetes Service permet une installation transparente de Headlamp avec une gestion automatique du cycle de vie et une intégration avec IBM Cloud Identity and Access Management (IAM) pour l'authentification.

Comprendre l'ajout d'une lampe frontale

Le module complémentaire Headlamp est le remplacement recommandé du projet archivé kubernetes-dashboard. Headlamp offre une interface moderne et conviviale pour visualiser et gérer les ressources Kubernetes dans votre cluster.

Les principales caractéristiques de la lampe frontale sont les suivantes :

Authentification IAM OIDC: Authentifiez vous de manière transparente avec votre compte IBM Cloud en utilisant IAM OIDC.
Gestion indépendante du cycle de vie: La version complémentaire est découplée des versions de la nomenclature principale du cluster, ce qui permet des mises à jour indépendantes.
Prêt à l'emploi: Le module complémentaire est automatiquement exposé par le biais d'une ressource Ingress sur le nom d'hôte ingress public par défaut de votre cluster avec un sous-domaine headlamp.
Accès sécurisé: Chaque cluster reçoit un identifiant client OIDC unique afin de prévenir les attaques par usurpation d'authentification.

Prérequis

Avant d'installer le module complémentaire Headlamp, assurez-vous que votre cluster répond aux exigences suivantes :

Vous devez avoir le rôle d'accès au service IAM Writer ou Manager IBM Cloud pour IBM Cloud Kubernetes Service.
Votre cluster doit utiliser une version supportée de Kubernetes.
Pour les clusters classiques, vous devez activer la VRF et les points d'extrémité de service.
Votre navigateur doit avoir accès à :
- Le nom d'hôte d'entrée par défaut du cluster.
- Le point de terminaison de l'autorisation IAM IBM Cloud à l'adresse https://iam.cloud.ibm.com.

Installation de la lampe frontale

Le module complémentaire Headlamp n'est actuellement disponible que par l'intermédiaire de la CLI. Vous ne pouvez pas installer ou gérer le module complémentaire à partir de la console IBM Cloud.

Installation du module complémentaire Headlamp à l’aide de l’interface de ligne de commande (CLI)

Mettez à jour le plug-in container-service vers la version la plus récente.
```
ibmcloud update && ibmcloud plugin update container-service
```

Ciblez votre cluster.

ibmcloud ks cluster config --cluster CLUSTER_NAME_OR_ID

Activez l'additif headlamp.

ibmcloud ks cluster addon enable headlamp --cluster CLUSTER_NAME_OR_ID

Vérifiez que le module complémentaire Headlamp présente le statut Addon Ready.

ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID

Exemple de sortie :

NAME       Version   Health State   Health Status
headlamp   0.1.0     normal         Addon Ready

Vérifiez que les modules Headlamp sont en cours d'exécution.

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

Accès au tableau de bord de la lampe frontale

Après avoir installé le module complémentaire Headlamp, vous pouvez accéder au tableau de bord via le nom d'hôte d'entrée par défaut de votre cluster.

Obtenez le nom d'hôte d'entrée par défaut de votre cluster.

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

Ouvrez votre navigateur et accédez à https://headlamp.<ingress_subdomain>, où <ingress_subdomain> est le nom d'hôte d'entrée par défaut de votre cluster.

Exemple:https://headlamp.mycluster-abc123-0000.us-south.containers.appdomain.cloud
Cliquez sur Sign In pour vous authentifier auprès de IBM Cloud IAM.
Si vous n'êtes pas déjà connecté à IBM Cloud, vous serez redirigé vers la page de connexion IAM. Après l'authentification, vous serez redirigé vers le tableau de bord de Headlamp.
Une fois authentifié, vous pouvez visualiser et gérer les ressources de votre cluster via l'interface Headlamp.

Migration depuis kubernetes-dashboard

La communauté Kubernetes a archivé le projet kubernetes-dashboard. Après avoir installé le module complémentaire Headlamp, vous pouvez réduire le déploiement de kubernetes-dashboard s'il s'exécute dans votre cluster.

Pour réduire le déploiement de kubernetes-dashboard après l'installation de Headlamp :

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

Comprendre l'authentification des lampes frontales

Le module complémentaire Headlamp utilise IBM Cloud IAM OIDC pour sécuriser l'accès aux ressources de votre cluster.

Lorsque vous activez le module complémentaire Headlamp, les composants d'authentification suivants sont automatiquement configurés :

ID client unique: Un identifiant client OIDC unique est créé pour votre cluster et stocké dans un secret Kubernetes dans l'espace de noms ibm-system.
OIDC hybride privé-public: Headlamp utilise des points d'extrémité IAM privés pour les demandes de canal arrière, tandis que le canal avant - connexion dans le navigateur - se fait sur des points d'extrémité IAM publics.
Gestion des jetons: Les jetons d'authentification sont stockés dans les cookies du navigateur et automatiquement inclus dans les demandes adressées au serveur API Kubernetes.

Le processus d'authentification se déroule comme suit :

Lorsque vous accédez au tableau de bord de la lampe frontale, une page de connexion s'affiche.
En cliquant sur Sign In, vous êtes redirigé vers le point final d'autorisation IAM public IBM Cloud.
Une fois l'authentification réussie, IAM vous redirige vers Headlamp avec un code d'autorisation.
Headlamp échange le code d'autorisation contre un jeton d'accès sur un réseau privé.
Le jeton d'accès est utilisé pour authentifier les demandes adressées au serveur API Kubernetes.

Votre accès aux ressources du cluster est déterminé par vos rôles IAM IBM Cloud et les autorisations RBAC Kubernetes appliquées par le serveur API Kubernetes.

Mise à jour du module complémentaire Headlamp

Le module complémentaire Headlamp est automatiquement mis à jour lorsque de nouvelles versions sont publiées. Vous pouvez à tout moment vérifier la version actuelle et l'état de santé du module complémentaire.

Pour vérifier la version du module complémentaire :

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Désactivation du module complémentaire Headlamp

Si vous n'avez plus besoin du tableau de bord Headlamp, vous pouvez désactiver le module complémentaire.

Lorsque vous désactivez le module complémentaire Headlamp, les ressources suivantes sont supprimées :

Déploiement des projecteurs et nacelles
Ressources d'entretien et de pénétration des phares
ID du client OIDC et secrets associés

Désactiver le module complémentaire Headlamp à l'aide de la CLI

Désactiver le module complémentaire Headlamp.

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

Vérifiez que le module complémentaire a bien été retiré.

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Accès à Headlamp via une entrée privée sur des clusters VPC

Configurez votre cluster VPC pour qu'il accède à Headlamp par une entrée privée au lieu d'une entrée publique, afin de renforcer la sécurité.

Lorsque vous choisissez d'accéder à Headlamp à partir de réseaux privés, comme par le biais d'un VPC VPN, vous pouvez reconfigurer votre cluster en suivant les étapes suivantes :

Désactivez l'ALB public de votre cluster.

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

Activer l'entrée privée.

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

Enregistrer un domaine auprès de l'ALB privé.

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

Définir le nouveau domaine comme domaine par défaut.

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

Le backend de IBM Cloud met à jour headlamp en 5 minutes environ. Lorsque la mise à jour est terminée, le tableau de bord est disponible sur le nouveau nom d'hôte d'entrée par défaut, avec le sous-domaine headlamp..

Exposition de Headlamp avec la passerelle d'entrée d' Istio

Si votre cluster achemine le trafic externe via la passerelle d'entrée d' Istio, vous pouvez désactiver les ressources Ingress par défaut créées par le module complémentaire Headlamp et exposer Headlamp à l'aide d'un Istio Gateway et VirtualService à la place.

Vous devez exposer Headlamp via un sous-domaine fourni par IBM dans le domaine *.containers.appdomain.cloud. L'identifiant client OIDC de votre cluster est enregistré avec une URI de redirection correspondant à ce domaine. Le nom d’hôte brut du répartiteur de charge istio-ingressgateway ne se trouve pas dans ce domaine, et l’authentification échoue si vous l’utilisez directement.

Avant de commencer

Activez le module complémentaire Istio géré.
Configurez kubectl pour cibler le cluster.

Ouvrez le fichier ConfigMapheadlamp-values en mode édition pour désactiver les ressources Ingress par défaut créées par le module complémentaire Headlamp.
```
kubectl edit cm -n ibm-system headlamp-values
```
Ajoutez ce qui suit à la section data pour empêcher l'extension de créer les ressources par défaut NGINX et Traefik Ingress.
```
data:
  values.yaml: |-
    createDefaultPublicIngressNginx: false
    createDefaultPrivateIngressNginx: false
    createDefaultPublicIngressTraefik: false
    createDefaultPrivateIngressTraefik: false
```
Patientez jusqu'à 5 minutes pour que les valeurs mises à jour soient répercutées sur le cluster.
Vérifiez que les ressources Ingress par défaut ont bien été supprimées.
```
kubectl get ingress -n ibm-system
```

Récupérez l'adresse IP (clusters classiques) ou le nom d'hôte (clusters VPC) de l'équilibreur de charge istio-ingressgateway.

Clusters classiques :

    kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    ```
* Clusters VPC :
```sh {: pre}
    kubectl get service istio-ingressgateway -n istio-system -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
    ```
Si la commande renvoie une valeur vide, cela signifie que l'équilibreur de charge n'est pas encore provisionné. Vérifiez que le service dispose d'une adresse IP externe et examinez les événements du service pour détecter d'éventuelles erreurs, telles qu'un dépassement du quota de l'équilibreur de charge.
{: note}

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

Enregistrez l’adresse IP (classique) ou le nom d’hôte (VPC) de l’équilibreur de charge en créant un sous-domaine fourni par IBM. Spécifiez l'espace istio-system de noms du secret TLS afin que le certificat TLS soit accessible à istio-ingressgateway.

Clusters classiques :

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

Vérifiez que le sous-domaine a bien été créé, puis notez le nom du sous-domaine et le nom du secret du certificat SSL.

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

Exemple de sortie pour les clusters classiques :

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

Exemple de sortie pour les clusters 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 le cluster comporte plusieurs entrées NLB-DNS, identifiez le sous-domaine que vous avez créé à l'étape précédente en faisant correspondre la colonne IP(s) Target(s) ou à l'adresse de l'équilibreur de charge istio-ingressgateway, et en vérifiant que la Secret Namespace colonne affiche istio-system.

Créez un fichier nommé headlamp-istio.yaml qui définit un Gateway et un pour VirtualService Headlamp. Remplacez <subdomain> par le sous-domaine de l'étape précédente et <ssl_cert_secret_name> par le nom du secret du certificat SSL.

Le secret du certificat TLS est créé dans l’espace de noms istio-system. Le istio-ingressgateway lit la clé secrète indiquée dans le champ credentialName à partir de cet espace de noms. Ne copiez pas la valeur du certificat dans la ressource 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

Utilisez les ressources VirtualService Gateway et.
```
kubectl apply -f headlamp-istio.yaml
```
Ouvrez le tableau de bord Headlamp dans un navigateur Web à l'aide du sous-domaine que vous avez noté à l'étape 6.
```
https://<subdomain>
```
Pour vérifier la connectivité depuis la ligne de commande, exécutez la commande suivante. Utilisez l'option -k pour ignorer la vérification du certificat uniquement pendant les tests — ne l'utilisez pas -k dans les environnements de production.
```
curl -k -s -o /dev/null -w "%{http_code}\n" https://<subdomain>
```

Kubernetes les ressources créées par l'addon

L'addon Headlamp crée plusieurs ressources Kubernetes dans votre cluster qui nécessitent une configuration réseau appropriée.

Si vous disposez d'un pare-feu ou de paramètres réseau personnalisés, vous devez les configurer de manière à autoriser la communication entre les ressources suivantes :

4 ressources Ingress
- privé avec private-iks-k8s-nginx ingressClass
- public avec public-iks-k8s-nginx ingressClass
- privé avec private-iks-traefik ingressClass
- public avec public-iks-traefik ingressClass
1 Service ( ClusterIP sur le port 80 → 4466)
1 Déploiement
- conteneur de lampes frontales (port 4466)
- conteneur nginx sidecar

Activer l'OIDC pour le module complémentaire Headlamp via des points de terminaison publics

Si votre cluster ne parvient pas à se connecter aux points de terminaison IAM privés, remplacez les paramètres du point de terminaison OIDC afin d'utiliser les points de terminaison publics.

Ces étapes partent du principe que le cluster peut accéder aux points de terminaison publics IAM.

Avant de commencer, assurez-vous que la fonctionnalité « kubectl » est configurée pour le cluster.

Ouvrez le fichier ConfigMap headlamp-values pour le modifier :

kubectl edit cm -n ibm-system headlamp-values

Dans l'éditeur, ajoutez ce qui suit à la section « data ». Remplacez par <account_id> l'identifiant du compte sur lequel le cluster est déployé.

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

Patientez jusqu'à 5 minutes pour que les valeurs mises à jour soient répercutées sur le cluster.

Relancer le déploiement de Headlamp :

kubectl rollout restart deployment/headlamp -n ibm-system

Dépannage du module complémentaire de la lampe frontale

Utilisez les informations suivantes pour résoudre les problèmes courants liés au module complémentaire Headlamp.

Impossible d'accéder au tableau de bord des phares

Si vous ne pouvez pas accéder au tableau de bord de la lampe frontale, vérifiez les points suivants :

Vérifiez que le module complémentaire est installé et qu'il fonctionne correctement.
```
ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
```

Vérifiez que les modules Headlamp sont en cours d'exécution.

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

Vérifiez que la ressource d'entrée est correctement configurée.
```
kubectl get ingress -n ibm-system
```
Pour les clusters exclusivement publics, vérifiez que les règles de sécurité réseau autorisent les connexions sortantes de type « HTTPS » vers les points de terminaison IAM publics. Si nécessaire, consultez la section « Activer l'OIDC pour le module complémentaire Headlamp via des points de terminaison publics » afin de mettre à jour la configuration OIDC.

Échec de l'authentification

Si l'authentification échoue lors de l'accès au tableau de bord Headlamp :

Vérifiez que vous disposez des autorisations IAM nécessaires pour accéder au cluster.
Vérifiez que votre navigateur peut accéder à https://iam.cloud.ibm.com.
Effacez les cookies de votre navigateur et réessayez.
Vérifiez que le secret d'identification du client OIDC existe dans votre cluster.
```
kubectl get secret clientid-secrets -n ibm-system
```

Les pods ne fonctionnent pas

Si les lampes frontales ne fonctionnent pas :

Vérifier l'état et les événements du pod.

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

Vérifiez les journaux du pod pour détecter d'éventuelles erreurs.

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