Installer l'Agent Datadog sur Kubernetes

Installation

Cette page décrit la marche à suivre pour installer l’Agent Datadog dans un environnement Kubernetes. Vous pouvez choisir l’une des trois ressources suivantes :

  • Operator Datadog
  • Chart Helm
  • DaemonSet

Pour parcourir la documentation dédiée aux principales distributions Kubernetes, y compris AWS Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Red Hat OpenShift, Rancher et Oracle Container Engine pour Kubernetes (OKE) et découvrir des exemples, référez-vous à la section Distributions Kubernetes.

Pour parcourir la documentation dédiée à la surveillance du plan de contrôle Kubernetes ainsi que des exemples, consultez la section Surveillance du plan de contrôle Kubernetes.

Versions minimales de l’Agent et de l’Agent de cluster

Pour utiliser certaines fonctionnalités des versions récentes de Kubernetes, vous devez exécuter des versions minimales de l’Agent Datadog et de l’Agent de cluster.

Version de KubernetesVersion de l’AgentVersion de l’Agent de clusterRaison
1.16.0+7.19.0+1.9.0+Obsolescence des métriques Kubelet
1.21.0+7.36.0+1.20.0+Obsolescence des ressources Kubernetes
L'Operator Datadog est disponible pour le grand public depuis la version `1.0.0`, il prend en charge la version `v2alpha1` du `DatadogAgent` .

L’Operator Datadog est une fonctionnalité permettant de déployer l’Agent Datadog sur Kubernetes et OpenShift. L’Operator transmet des données sur le statut, la santé et les erreurs du déploiement dans le statut de sa ressource personnalisée. Ses paramètres de niveau supérieur permettent également de réduire les erreurs de configuration.

Prérequis

L’utilisation de l’Operator Datadog nécessite les prérequis suivants :

  • Cluster Kubernetes version >= v1.20.X : les tests ont été réalisés sur les versions >= 1.20.0. Néanmoins, les versions >= v1.11.0 devraient également fonctionner. Pour les versions plus anciennes, en raison de la prise en charge limitée de la CRD, il se peut que l’Operator ne fonctionne pas comme prévu.
  • Helm pour le déploiement de datadog-operator.
  • Interface de ligne de commande Kubectl pour l’installation de datadog-agent.

Déployer un Agent avec l’Operator

Pour déployer l’Agent Datadog avec l’Operator le plus rapidement possible, consultez le chart Helm datadog-operator. Voici la marche à suivre :

  1. Installez l’Operator Datadog :

    helm repo add datadog https://helm.datadoghq.com
    helm install my-datadog-operator datadog/datadog-operator
    
  2. Créez un secret Kubernetes avec vos clés d’API et d’application.

    kubectl create secret generic datadog-secret --from-literal api-key=<DATADOG_API_KEY> --from-literal app-key=<DATADOG_APP_KEY>
    

    Remplacez <DATADOG_API_KEY> et <DATADOG_APP_KEY> par vos clés d’API et d’application Datadog.

  3. Créez un fichier avec les spécifications de la configuration de déploiement de votre Agent Datadog. Voici la configuration la plus simple :

kind: DatadogAgent
apiVersion: datadoghq.com/v2alpha1
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
      appSecret:
        secretName: datadog-secret
        keyName: app-key
  override:
    clusterAgent:
      image:
        name: gcr.io/datadoghq/cluster-agent:latest
    nodeAgent:
      image:
        name: gcr.io/datadoghq/agent:latest
  1. Déployez l’Agent Datadog avec le fichier de configuration ci-dessus :
    kubectl apply -f /path/to/your/datadog-agent.yaml
    

Nettoyage

La commande suivante permet de supprimer toutes les ressources Kubernetes créées par les instructions ci-dessus :

kubectl delete datadogagent datadog
helm delete my-datadog-operator

Pour en savoir plus sur la configuration de l’Operator, notamment sur l’utilisation de tolérances, consultez le guide de configuration avancée de l’Operator Datadog.

Sans privilèges

(Facultatif) Pour exécuter une installation sans privilèges, ajoutez le bloc suivant à la ressource personnalisée Datadog :

kind: DatadogAgent
apiVersion: datadoghq.com/v2alpha1
metadata:
  name: placeholder
  namespace: placeholder
spec:
  override:
    nodeAgent:
      securityContext:
        runAsUser: 1 # <ID_UTILISATEUR>
        supplementalGroups:
          - 123 # <ID_GROUPE_DOCKER>

<ID_UTILISATEUR> correspond à l’UID utilisé pour exécuter l’agent et <ID_GROUPE_DOCKER> à l’ID du groupe auquel appartient le socket containerd ou Docker.

Registres de conteneurs

Pour modifier le registre d’image de conteneur, consultez le guide Modifier votre registre de conteneurs.

Pour installer le chart avec un nom de version <RELEASE_NAME> personnalisé (par exemple, datadog-agent) :

  1. Installez Helm.
  2. Créez votre fichier values.yaml en vous référant au fichier de configuration values.yaml Datadog. Datadog vous conseille d’utiliser uniquement des valeurs qui doivent être remplacées, afin de faciliter la mise à niveau du chart.
  3. S’il s’agit d’une nouvelle installation, ajoutez le référentiel Helm Datadog :
    helm repo add datadog https://helm.datadoghq.com
    helm repo update
    
  4. Récupérez votre clé d’API Datadog à partir des instructions d’installation de l’Agent et exécutez ce qui suit :
  • Helm v3 et ultérieur

    helm install <RELEASE_NAME> -f values.yaml  --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog --set targetSystem=<TARGET_SYSTEM>
    

    Remplacez <TARGET_SYSTEM> par le nom de votre système d’exploitation : linux ou windows.

  • Helm v1 ou v2

    helm install -f values.yaml --name <RELEASE_NAME> --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog
    

Ce chart ajoute l’Agent Datadog à l’ensemble des nœuds dans votre cluster avec un DaemonSet. Il peut également déployer le chart kube-state-metrics et l’utiliser comme source supplémentaire de métriques concernant le cluster. Quelques minutes après l’installation, Datadog commence à transmettre les hosts et les métriques.

Activez ensuite les fonctionnalités Datadog que vous souhaitez utiliser, comme l’APM ou les logs.

Remarques :

Registres de conteneurs

Si Google Container Registry (gcr.io/datadoghq) n’est pas accessible dans votre région de déploiement, utilisez un autre registre avec la configuration suivante dans le fichier values.yaml :

  • Pour le registre AWS ECR public (public.ecr.aws/datadog), utilisez la commande suivante :

    registry: public.ecr.aws/datadog
    
  • Pour le registre Docker Hub (docker.io/datadog), utilisez la commande suivante :

    registry: docker.io/datadog
    

Remarques :

  • Si vous déployez le chart Datadog dans un environnement AWS, il est conseillé d’utiliser le registre AWS ECR public (public.ecr.aws/datadog).

Mise à niveau depuis le chart v1.x

Le chart Datadog a été réusiné dans la v2.0 afin de regrouper plus logiquement les paramètres du fichier values.yaml.

Si vous déployez actuellement un chart antérieur à v2.0.0, suivez le guide de migration (en anglais) afin de mapper vos anciens paramètres avec les nouveaux champs.

Core kube-state-metrics dans les charts v2.x

Dans les nouveaux déploiements, Datadog recommande d’utiliser le nouveau core kube-state-metrics avec les valeurs suivantes :

...
datadog:
...
  kubeStateMetricsCore:
    enabled: true
...

Pour en savoir plus sur le core kube-state-metrics, consultez la documentation dédiée.

Sans privilèges

(Facultatif) Pour exécuter une installation sans privilèges, ajoutez le bloc suivant au fichier values.yaml :

datadog:
  securityContext:
      runAsUser: <ID_UTILISATEUR>
      supplementalGroups:
        - <ID_GROUPE_DOCKER>

<ID_UTILISATEUR> correspond à l’UID utilisé pour exécuter l’agent et <ID_GROUPE_DOCKER> à l’ID du groupe auquel appartient le socket containerd ou docker.

Tirez profit des DaemonSets pour déployer l’Agent Datadog sur l’ensemble de vos nœuds (ou sur un nœud donné grâce aux nodeSelectors).

Pour installer l’Agent Datadog sur votre cluster Kubernetes :

  1. Configurez les autorisations de l’Agent : si le contrôle d’accès basé sur des rôles (RBAC) est activé pour votre déploiement Kubernetes, configurez les autorisations RBAC pour le compte de service de votre Agent Datadog. Depuis la version 1.6 de Kubernetes, le RBAC est activé par défaut. Créez les ClusterRole, ServiceAccount et ClusterRoleBinding appropriés à l’aide de la commande suivante :

    kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/clusterrole.yaml"
    
    kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/serviceaccount.yaml"
    
    kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/clusterrolebinding.yaml"
    

    Remarque : ces configurations RBAC sont définies pour l’espace de nommage default. Si vous utilisez un espace de nommage personnalisé, modifiez le paramètre namespace avant d’appliquer les configurations.

  2. Créez le manifeste de l’Agent Datadog. Créez le manifeste datadog-agent.yaml à partir de l’un des modèles suivants :

    Pour activer toutes les fonctionnalités de collecte de traces, vous devez suivre plusieurs étapes supplémentaires lors de la configuration des pods de votre application. Consultez également les sections relatives aux logs, à APM, aux processus, à Network Performance Monitoring et à la sécurité pour découvrir comment activer chacune de ces fonctionnalités.

    Remarque : ces manifestes sont définis pour l’espace de nommage default. Si vous utilisez un espace de nommage personnalisé, modifiez le paramètre metadata.namespace avant d’appliquer les manifestes.

  3. Dans le manifeste secret-api-key.yaml, remplacez PUT_YOUR_BASE64_ENCODED_API_KEY_HERE par votre clé d’API Datadog encodée en base64. Pour obtenir la version base64 de votre clé d’API, exécutez la commande suivante :

    echo -n '<Your API key>' | base64
    
  4. Dans le manifeste secret-cluster-agent-token.yaml, remplacez PUT_A_BASE64_ENCODED_RANDOM_STRING_HERE par une chaîne aléatoire encodée en base64. Pour obtenir la version base64 de cette chaîne, exécutez la commande suivante :

    echo -n 'Random string' | base64
    

    Remarque : la chaîne aléatoire doit inclure au moins 32 caractères alphanumériques, afin de sécuriser les communications entre l’Agent de cluster et l’Agent.

  5. Définissez votre site Datadog sur en utilisant la variable d’environnement DD_SITE dans le manifeste datadog-agent.yaml.

    Remarque : si la variable d’environnement DD_SITE n’est pas explicitement définie, sa valeur par défaut correspond au site US, à savoir datadoghq.com. Si vous utilisez l’un des autres sites (EU, US3 ou US1-FED), un message de clé d’API non valide s’affiche. Utilisez le menu de sélection de site de la documentation pour accéder à la documentation spécifique à votre site.

  6. Déployez le DaemonSet avec cette commande :

    kubectl apply -f datadog-agent.yaml
    
  7. Vérification : pour vérifier que l’Agent Datadog s’exécute dans votre environnement en tant que DaemonSet, exécutez ce qui suit :

    kubectl get daemonset
    

    Si l’Agent est déployé, une sortie similaire au texte ci-dessous s’affiche. Les valeurs DESIRED et CURRENT correspondent au nombre de nœuds exécutés dans votre cluster.

    NAME            DESIRED   CURRENT   READY     UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
    datadog-agent   2         2         2         2            2           <none>          10s
    
  8. Configurez des métriques Kubernetes State (facultatif) : téléchargez le dossier de manifestes Kube-State, puis appliquez les manifestes à votre cluster Kubernetes pour recueillir automatiquement des métriques kube-state :

    kubectl apply -f <NAME_OF_THE_KUBE_STATE_MANIFESTS_FOLDER>
    

Sans privilèges

(Facultatif) Pour exécuter une installation sans privilèges, ajoutez le bloc suivant à votre modèle de pod :

  spec:
    securityContext:
      runAsUser: <ID_UTILISATEUR>
      supplementalGroups:
        - <ID_GROUPE_DOCKER>

<ID_UTILISATEUR> correspond à l’UID utilisé pour exécuter l’agent et <ID_GROUPE_DOCKER> à l’ID du groupe auquel appartient le socket containerd ou docker.

Étapes suivantes

Pour configurer des live containers, consultez la section Configuration des live containers.

Pour recueillir des événements, remplacer les paramètres de proxy, envoyer des métriques custom avec DogStatsD, configurer des listes d’inclusion et d’exclusion de conteneurs ou consulter la liste complète des variables d’environnement disponibles, consultez la section Configurer l’Agent Datadog sur Kubernetes.

Pour configurer des intégrations, consultez la section Intégrations Autodiscovery avec Kubernetes.

Pour configurer la solution APM, consultez la section Collecte de traces Kubernetes.

Pour configurer la collecte de logs, consultez la section Collecte de logs Kubernetes.