Migration du SDK AWS ( v1 ) vers le SDK AWS ( v2 )

Modifier en ligne

AWS a officiellement mis fin au support du SDK AWS Java v1 le 31 décembre 2025. Afin de garantir un environnement de surveillance sécurisé, stable et prêt pour l'avenir, Instana procède à la migration de tous les capteurs et composants de découverte d' AWS vers le SDK AWS, entièrement pris en charge v2.

Ce guide fournit des informations sur le processus de migration et les mesures que vous devez prendre en fonction de votre type de déploiement.

Pourquoi passer au SDK d' AWS v2

AWS La version SDK v1 ne bénéficiera plus de mises à jour de sécurité, de corrections de bogues ni d'améliorations de maintenance après le 31 décembre 2025. La poursuite de l'utilisation du SDK v1 comporte des risques potentiels en matière de sécurité et d'exploitation.

Pour plus d'informations, consultez AWS Java SDK v1 – Fin du support.

La migration vers le SDK d' AWS, disponible à l'adresse v2, offre les avantages suivants :

Mises à jour de sécurité et assistance technique continues assurées par AWS
Amélioration des performances et de l'efficacité grâce à une architecture moderne
Compatibilité améliorée avec les services d' AWS, qu'ils soient nouveaux ou en constante évolution
Stabilité à long terme pour la surveillance basée sur l' AWS

Pour plus d'informations sur le SDK d' AWS v2, consultez le guide du développeur du SDK d' AWS pour Java 2.x.

Impact de la migration

Modifier en ligne

Le processus de migration est conçu pour s'effectuer en toute transparence et sans perturber vos opérations de surveillance.

Contrôle de la continuité

La surveillance de votre AWS reste pleinement opérationnelle tout au long du processus de migration, sans aucune interruption de la collecte de données ni de la visibilité sur vos ressources AWS.

Conservation de la configuration

Vos configurations existantes d' AWS, notamment les rôles et politiques IAM, les clés d'accès et les identifiants, les configurations du service d' AWS et les paramètres réseau, restent inchangées.

Condition de redémarrage de l'agent

Il suffit de redémarrer brièvement l'agent pour activer les capteurs d' AWS s qui utilisent le SDK d' AWS v2. Le redémarrage suit les procédures standard de mise à jour des agents et n'entraîne qu'un temps d'arrêt minimal.

Améliorations à venir

Toutes les nouvelles fonctionnalités et améliorations du capteur d' AWS s sont développées exclusivement à l'aide du SDK d' AWS v2, ce qui vous garantit l'accès aux dernières fonctionnalités.

Étapes de migration par type de déploiement

Modifier en ligne

Les étapes de migration varient en fonction de la manière dont vous avez déployé votre agent d' Instana. Sélectionnez la section qui correspond à votre type de déploiement.

Déploiements sur hôte

L'agent « Instana » est fourni avec Azul JVM ou OpenJ9 JVM. Les étapes de migration varient légèrement selon l' JVM ion que vous utilisez.

Pour plus d'informations sur la configuration d' JVM, consultez la page « Installation de l'agent » sur Linux.

Vous pouvez migrer vers le SDK d' AWS v2 en utilisant l'une des options suivantes :

Option 1 : Migration automatique (recommandée)

Réinstallez l'agent d' Instana dynamique afin d'appliquer automatiquement les modifications apportées au SDK d' AWS v2 et les ajustements de configuration de la mémoire.

Option 2 : Configuration manuelle

Pour les installations existantes de l'agent d' Instana dynamique qui utilisent l' JVM Azul, configurez manuellement l'allocation de mémoire en modifiant le fichier de configuration de la mémoire.

Remarque : cette modification de configuration n’est pas requise pour les agents qui utilisent la JVM OpenJ9.

Modifiez le fichier /opt/instana/agent/bin/memory-config.
Ajoutez les paramètres suivants sous INSTANA_AGENT_MEMORY_CONFIGURATION_OPTS :
```
-XX:CompressedClassSpaceSize=48m \
-XX:MaxMetaspaceSize=256m \
```
Augmentez la mémoire de l'agent en définissant la variable d'environnement AGENT_MAX_MEM =768M.
Suivez les étapes restantes pour votre type d' JVM, comme décrit dans les sections suivantes.

Redémarrer l'agent

Une fois les étapes de configuration terminées, redémarrez l'agent pour activer les capteurs d' AWS s à l'aide du SDK AWS v2:

Redémarrez l'agent.
```
sudo systemctl restart instana-agent
```
Vérifiez que l'agent est en cours d'exécution.
```
sudo systemctl status instana-agent
```

Pour OpenJ9 JVM, aucune configuration supplémentaire n'est nécessaire après le redémarrage.

Remarque : le SDK AWS v2 utilise une architecture plus moderne comprenant des composants supplémentaires par rapport au SDK v1, ce qui peut augmenter les besoins en mémoire, notamment pour le métaspace et le chargement des classes. En conséquence, l'agent ajuste automatiquement l'allocation de mémoire afin de garantir des ressources suffisantes pour l' AWS ation des capteurs et la découverte, en augmentant les limites de l'espace de mémoire alloué aux processus ( MaxMetaspace ), en ajustant les limites de l'espace de classe compressé (Compressed Class Space) et en redistribuant la mémoire en conséquence.

Docker déploiements

Pour les agents Instana basés sur l' Docker, mettez à jour votre conteneur d'agent vers la dernière version, qui inclut la prise en charge du SDK AWS v2. Le processus de mise à jour consiste à récupérer la dernière image, à arrêter le conteneur existant, puis à démarrer un nouveau conteneur avec l'image mise à jour.

Pour plus d'informations sur la procédure de mise à niveau, consultez la section « Mise à niveau de l'image du conteneur de l'agent d' Instana ».

Kubernetes et les déploiements d' Helm

Pour les déploiements d' Kubernetes, la migration s'effectue via une mise à jour progressive basée sur l' Helm. Kubernetes effectue automatiquement une mise à jour progressive : les nouveaux pods démarrent avec les configurations mises à jour et les pods existants s'arrêtent en douceur une fois que les nouveaux pods sont prêts, garantissant ainsi un déploiement sans interruption et une surveillance continue.

Pour obtenir des instructions détaillées, consultez la section « Administration de l'agent Instana » sur Kubernetes.

Exemples de commandes de mise à jour :

# Update Helm repository
helm repo update

# Upgrade the Instana agent
helm upgrade instana-agent instana/instana-agent \
  --namespace instana-agent \
  --reuse-values

# Verify the rollout status
kubectl rollout status daemonset/instana-agent -n instana-agent

Remarque : pour l'agent statique, il n'est pas possible de migrer vers le SDK d' AWS v2 via une mise à niveau standard. Réinstallez la dernière version de l'agent statique pour activer la prise en charge du SDK AWS v2.

Vérification de la migration

Modifier en ligne

Après avoir redémarré ou mis à niveau votre agent, vérifiez que les capteurs d' AWS s fonctionnent correctement.

Consulter les journaux des agents

Consultez les journaux de l'agent pour confirmer l'initialisation du kit de développement logiciel AWS v2 et vérifier qu'il n'y a pas d'erreurs.

Pour les déploiements sur serveur :

sudo journalctl -u instana-agent -f

Pour les déploiements d' Docker :

docker logs -f instana-agent

Pour les déploiements d' Kubernetes :

kubectl logs -f daemonset/instana-agent -n instana-agent

Vérification de la découverte des services d' AWS

Connectez-vous à l'interface utilisateur d' Instana.
Dans le menu de navigation, cliquez sur Infrastructure > AWS.
Vérifiez que vos ressources AWS sont bien détectées et surveillées.
Vérifiez que les métriques sont bien collectées à partir de vos services AWS.

Traitement des incidents

Modifier en ligne

Si vous rencontrez des problèmes pendant ou après la migration, consultez la liste suivante des problèmes courants et de leurs solutions.

Tableau 1. Problèmes courants et solutions
Problème	La solution
L'agent ne démarre pas après la mise à jour	Vérifiez l'allocation de mémoire et assurez-vous que les ressources disponibles sont suffisantes. Consultez les journaux de l'agent pour rechercher des messages d'erreur spécifiques.
AWS les capteurs ne s'affichent pas	Vérifiez que les autorisations IAM et les identifiants d' AWS s sont correctement configurés. Assurez-vous que l'agent dispose d'une connexion réseau permettant d'accéder aux API d' AWS.
Augmentation de l'utilisation de la mémoire	Ce problème est connu avec la version v2 du SDK. L'agent ajuste automatiquement l'allocation de mémoire et, en cas de saturation, augmente les ressources de l'hôte.
Utilisation explicite du SDK d' AWS v1	Si la migration du SDK AWS v1 vers v2 échoue et que vous souhaitez revenir au SDK AWS v1, définissez la variable d'environnement `USE_AWS_SDK_V1` =`true` et redémarrez l'agent. L'agent utilisera alors les capteurs et la fonctionnalité de découverte du SDK d' AWS v1.

Pour plus d'informations sur le dépannage, consultez Instana AWS agent troubleshooting.

Support

Si vous rencontrez des difficultés pendant la migration ou si vous avez des questions, veuillez contacter le service d'assistance d' IBM via le portail d'assistance IBM.