Etape 1: Création des fichiers de configuration locaux

Il existe plusieurs façons de transmettre des informations de variable d'environnement de configuration d'agent au conteneur. L'exemple suivant utilise des fichiers de configuration. Toutefois, vous pouvez également utiliser la commande docker run --env pour spécifier les valeurs.

Sachez que si vous utilisez --env avec votre clé d'API, celle-ci est exposée à l'environnement de conteneur et est visible dans la sortie de la commande docker inspect. Vous pouvez sécuriser votre clé d'API dans un fichier, puis utiliser le nom de fichier dans la variable d'environnement. Si vous choisissez d'utiliser le nom de fichier, vous devez vous assurer que le chemin de fichier que vous spécifiez dans la variable d'environnement est monté sur un chemin de fichier dans le conteneur, comme illustré dans l'exemple suivant.

Les noms de fichier affichés dans les étapes suivantes sont des exemples et peuvent être personnalisés pour votre environnement.

1. Créez un répertoire pour les fichiers de configuration, dans cet exemple ~/agent/env-files.

2. Créez un fichier dans le répertoire ~/agent/env-files appelé apikey avec une valeur de ligne unique de votre clé d'API IBM Cloud qui peut accéder au connecteur Satellite.

3. Créez un fichier dans le répertoire ~/agent/env-files appelé env.txt avec les valeurs suivantes. Modifiez la variable 'SATELLITE_CONNECTOR_ID avec votre Satellite ID du connecteur.

   SATELLITE_CONNECTOR_ID=<Your Satellite Connector ID>
   SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
   SATELLITE_CONNECTOR_TAGS=sample tag
   

4. A ce stade, votre répertoire contient 2 fichiers et ressemble à l'exemple suivant.

   env-files$ ls
   apikey  env.txt
   

5. Effectuez les étapes de la section suivante pour extraire l'image de l'agent.

Etape 2: Extraction de l'image de l'agent

1. Connectez-vous à IBM Cloud® Container Registry. Ou connectez-vous au référentiel directement à partir de Docker avec votre clé d'API.

   ibmcloud cr region-set icr.io
   

   docker login -u iamapikey -p <your apikey> icr.io
   

2. Tirez la dernière version de l'image publiée qui convient à votre architecture. Les valeurs acceptées sont latest, latest-amd64, latest-arm64, latest-ppc64le et latest-s390x. Vous trouverez la liste des versions publiées sur IBM Satellite Connector Agent Release History.

   docker pull icr.io/ibm/satellite-connector/satellite-connector-agent:latest
   

3. Suivez les étapes suivantes pour exécuter l'image de l'agent.

Etape 3: Exécution de l'image d'agent

1. Pour afficher les versions disponibles de l'image d'agent, exécutez la commande suivante.

   ibmcloud cr images --include-ibm |egrep -i "tag|satellite"
   

   Exemple de sortie :

   Repository                                                  Tag             Digest         Namesp  Created         Size     Security status
   icr.io/ibm/satellite-connector/satellite-connector-agent    latest          63a97392e510   ibm     -               937 B    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    latest-amd64    0d2b1a5773e5   ibm     1 week ago      50 MB    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    latest-arm64    cb60b8d7040f   ibm     1 week ago      94 MB    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    latest-ppc64le  4bcf8b1f6ea7   ibm     1 week ago      107 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    latest-s390x    27588d9d6143   ibm     1 week ago      94 MB    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.0          5f4e42c8d53e   ibm     2 years ago     124 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.1          0caddb11b1c1   ibm     1 year ago      125 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10         52db33f1ec43   ibm     -               937 B    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-amd64   90c920b580fe   ibm     2 months ago    50 MB    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-arm64   322f92d8c373   ibm     2 months ago    94 MB    -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-ppc64le 603b3507f20c   ibm     2 months ago    107 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-s390x   afe670f04ea2   ibm     2 months ago    95 MB    -
   

2. Montez votre répertoire env-files dans le répertoire /agent-env-files du conteneur à l'aide de l'option -v. Vous pouvez utiliser la version la plus récente ou une version spécifique de l'image publiée.

   Si une variable d'environnement utilise un chemin d'accès à un fichier, ce chemin doit être un chemin de fichier dans le conteneur. Pour extraire le chemin d'accès au fichier, utilisez l'option -v dans la commande docker run. L'option -v est spécifiée par le chemin de répertoire de la variable d'environnement locale, suivi du chemin monté dans le conteneur et séparé par :. Par exemple, -v ~/agent/env-files:/agent-env-files, où ~/agent/env-files est votre chemin d'accès local et /agent-env-files est un chemin d'accès dans votre conteneur.

   docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:latest
   

   Exemple de commande utilisant la version 1.1.0 de l'image, exécutez la commande suivante.

   docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:v1.1.0
   

3. Vous pouvez vérifier que le tunnel est établi pour votre connecteur en consultant les journaux du conteneur.

   docker logs CONTAINER-ID
   

   Vers le début du journal, vous pouvez trouver des entrées similaires aux exemples suivants.

   {"level":30,"time":"2023-06-20T16:12:20.133Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_ID value from SATELLITE_CONNECTOR_ID environment variable."}
   {"level":30,"time":"2023-06-20T16:12:20.138Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A01","msg":"Load SATELLITE_CONNECTOR_IAM_APIKEY value from file /agent-env-files/apikey."}
   {"level":30,"time":"2023-06-20T16:12:20.140Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_TAGS value from SATELLITE_CONNECTOR_TAGS environment variable."}
   {"level":30,"time":"2023-06-20T16:12:20.142Z","pid":8,"hostname":"6b793f671c79","name":"connector-agent","msgid":"LA2","msg":"Connector id: U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI, region: us-south, release info: 20230610-dd48822928d35a84b31029a996fa9abc9d29fc93_A."}
   {"level":30,"time":"2023-06-20T16:12:20.392Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
   {"level":30,"time":"2023-06-20T16:12:21.560Z","pid":8,"hostname":"6b793f671c79","name":"utilities","msg":"MakeLinkAPICall GET /v1/connectors/U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI status code 200"}
   {"level":30,"time":"2023-06-20T16:12:21.563Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT03","msg":"Got configuration"}
   {"level":30,"time":"2023-06-20T16:12:21.565Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT04-wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws","msg":"Connecting to wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws"}
   {"level":30,"time":"2023-06-20T16:12:21.922Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
   {"level":30,"time":"2023-06-20T16:12:22.294Z","pid":8,"hostname":"6b793f671c79","name":"TunnelCore","msgid":"TC24","msg":"Tunnel open","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI"}
   {"level":30,"time":"2023-06-20T16:12:22.299Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB26-U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","msg":"Send connector information to tunnel server"}
   {"level":30,"time":"2023-06-20T16:12:22.307Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB27","msg":"Tunnel connected","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","cipher":{"name":"TLS_AES_256_GCM_SHA384","standardName":"TLS_AES_256_GCM_SHA384","version":"TLSv1.3"}}
   

Après avoir configuré un agent, vous pouvez créer des noeuds finaux et des listes de contrôle d'accès pour gérer l'accès à ces noeuds finaux. Pour plus d'informations, voir Création et gestion des noeuds finaux de connecteur.

Etape 1: Téléchargement des fichiers d'agent de connecteur à partir de l'interface de ligne de commande

1. A partir de l'interface de ligne de commande, exécutez la commande suivante pour télécharger le fichier .zip de l'agent.

   ibmcloud sat agent attach --platform windows
   

   Exemple de sortie.

   Downloading agent setup tools for windows...
   OK
   Satellite connector agent for windows was successfully returned /var/folders/17/y8wr4y_x1tb4yf__g3wr6g8m0000gp/T/windows_satellite_connector_4097559421.zip
   

2. Vérifiez la sha512sum de la .zip en exécutant la commande suivante dans PowerShell.

   Get-FileHash -Algorithm SHA512 -Path c:\windows_satellite_connector_1420916628.zip
   

3. Exécutez la commande suivante dans PowerShell pour extraire le contenu du fichier .zip.

   Expand-Archive -Path 'C:\path\to\windows_satellite_connector_4097559421.zip' -DestinationPath ‘C:\path\to\extract'
   

4. Effectuez les étapes de la section suivante pour mettre à jour les fichiers de configuration que vous avez extraits.

Etape 2: Mise à jour du fichier config.json

Les informations de configuration sont fournies à l'agent via les variables d'environnement suivantes dans le fichier config.json que vous avez extrait à l'étape précédente. Passez en revue les paramètres suivants pour l'image d'agent.

1. Mettez à jour le fichier config.json que vous avez extrait précédemment avec les valeurs appropriées pour chaque paramètre.

   Vous devez mettre en échappement la barre oblique dans le chemin d'accès au fichier.

   Exemple config.json.

   {
     "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

   Exemple de config.json avec des valeurs renseignées.

   {
     "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

2. Sauvegardez le fichier.

3. Effectuez les étapes de la section suivante pour démarrer l'agent.

Etape 3: Démarrage de l'agent

1. Démarrez l'agent en exécutant la commande install dans PowerShell.

   .\install
   

   Si vous démarrez l'agent et recevez une erreur Windows Microsoft Defender SmartScreen, c'est normal. Les scripts d'installation en texte brut ne sont pas signés. Nous vous suggérons de vous fier à l'étape de vérification de l'sha512sum après avoir téléchargé l'agent.

2. Vérifiez que l'agent est installé en exécutant la commande Get-Service dans PowerShell.

   Get-Service 'SatelliteConnectorService'
   

3. Affichez les journaux de l'agent en exécutant la commande Get-Content dans PowerShell.

   Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'
   

4. Facultatif: arrêtez l'agent en exécutant la commande uninstall dans PowerShell.

   .\uninstall
   

Après avoir configuré un agent, vous pouvez créer des noeuds finaux et des listes de contrôle d'accès pour gérer l'accès à ces noeuds finaux. Pour plus d'informations, voir Création et gestion des noeuds finaux de connecteur.

Mise à jour de l'agent sous Windows

Vous pouvez utiliser la commande update-service dans le paquetage de l'agent pour appliquer les changements de configuration à votre agent. Lorsque vous exécutez la commande, l'agent est arrêté, désinstallé et réinstallé. Suivez les étapes suivantes pour mettre à jour votre agent.

1. Avant de procéder à la mise à jour, examinez les modifications apportées au Journal des modifications de l'agent Windows du connecteur et vérifiez si la dernière version est plus récente que l'agent en cours d'exécution.

   Vous trouverez votre numéro de version actuel dans le fichier version.txt à l'intérieur du paquetage de l'agent en cours d'exécution. Si aucun fichier version.txt n'est trouvé ou si le numéro de votre version actuelle est inférieur au numéro de la dernière version, c'est qu'une version plus récente est disponible pour la mise à jour.

2. Si une version plus récente de l'agent est disponible et que vous souhaitez l'utiliser, téléchargez la dernière version en suivant les instructions de Étape 1 : Téléchargement des fichiers de l'agent Connector à partir de la CLI avant de passer aux étapes suivantes.

3. Modifiez les paramètres de configuration dans le fichier config.json.

   Exemple config.json.

   {
     "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
     "SATELLITE_CONNECTOR_TAGS":"<tags>",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

   Exemple de config.json avec des valeurs renseignées.

   {
     "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

4. Exécutez la commande update-service dans PowerShell.

   .\update-service
   

5. Vérifiez que l'agent est installé en exécutant la commande Get-Service dans PowerShell.

   Get-Service 'SatelliteConnectorService'
   

6. Affichez les journaux de l'agent en exécutant la commande Get-Content dans PowerShell.

   Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'