Passo 1: creazione dei file di configurazione locali

Esistono diversi modi per passare le informazioni sulla variabile di ambiente di configurazione dell'agent al contenitore. Il seguente esempio utilizza i file di configurazione. Tuttavia, è possibile utilizzare il comando docker run --env per specificare i valori.

Tieni presente che se utilizzi --env con la tua chiave API, la chiave API è esposta all'ambiente del contenitore ed è visibile sull'output del comando docker inspect. Puoi proteggere la tua chiave API in un file e quindi utilizzare il nome file nella variabile di ambiente. Se si sceglie di utilizzare il nome file, è necessario accertarsi che il percorso file specificato nella variabile di ambiente sia montato in un percorso file nel contenitore, come mostrato nel seguente esempio.

I nomi file mostrati nei seguenti passi sono esempi e possono essere personalizzati per il proprio ambiente.

1. Creare una directory per i file di configurazione, in questo esempio ~/agent/env-files.

2. Crea un file nella directory ~/agent/env-files denominata apikey con un valore di riga singola della tua chiave API IBM Cloud che può accedere al connettore Satellite.

3. Creare un file nella directory ~/agent/env-files denominata env.txt con i seguenti valori. Modificare la variabile 'SATELLITE_CONNECTOR_ID con il proprio Satellite ID del connettore.

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

4. A questo punto, la directory contiene 2 file e sembra simile al seguente esempio.

   env-files$ ls
   apikey  env.txt
   

5. Completa la procedura nella seguente sezione per eseguire il pull dell'immagine agent.

Passo 2: estrazione dell'immagine dell'agent

1. Accedi a IBM Cloud® Container Registry. In alternativa, accedi al repository direttamente da Docker con la tua chiave API.

   ibmcloud cr region-set icr.io
   

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

2. Estrarre l'ultima versione dell'immagine pubblicata adatta alla propria architettura. I valori accettati per i tag sono latest, latest-amd64, latest-arm64, latest-ppc64le e latest-s390x. L'elenco delle versioni pubblicate è disponibile all'indirizzo IBM Satellite Connector Agent Release History.

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

3. Seguire i passaggi riportati di seguito per eseguire l'immagine dell'agente.

Passo 3: esecuzione dell'immagine agent

1. Per visualizzare le versioni disponibili dell'immagine dell'agent, eseguire il seguente comando.

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

   Output di esempio:

   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. Montare la directory env-files nella directory /agent-env-files del contenitore utilizzando l'opzione -v. È possibile utilizzare la versione più recente o una versione specifica dell'immagine pubblicata.

   Se una variabile di ambiente utilizza un percorso per un file, tale percorso deve essere un percorso file all'interno del contenitore. Per richiamare il percorso file, utilizzare l'opzione -v sul comando docker run. L'opzione -v viene specificata dal percorso della directory della variabile di ambiente locale, seguito dal percorso montato nel contenitore e separato da :. Ad esempio, -v ~/agent/env-files:/agent-env-files, dove ~/agent/env-files è il tuo percorso locale e /agent-env-files è un percorso nel tuo contenitore.

   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
   

   Comando di esempio che utilizza la versione 1.1.0 dell'immagine, esegui questo comando.

   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. Puoi verificare che il tunnel venga stabilito sul tuo connettore esaminando i log del contenitore.

   docker logs CONTAINER-ID
   

   All'inizio del log, è possibile trovare voci simili ai seguenti esempi.

   {"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"}}
   

Dopo aver impostato un agente, è possibile creare endpoint e ACL per gestire l'accesso a tali endpoint. Per ulteriori informazioni, vedi Creazione e gestione degli endpoint del connettore.

Passo 1: scaricamento dei file dell'agent del connettore dalla CLI

1. Dalla CLI, immetti il seguente comando per scaricare il file .zip dell'agente.

   ibmcloud sat agent attach --platform windows
   

   Output di esempio.

   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. Verificate il sha512sum del .zip eseguendo il seguente comando in PowerShell.

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

3. Eseguire il seguente comando in PowerShell per estrarre il contenuto del file .zip.

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

4. Completare i passi riportati nella sezione seguente per aggiornare i file di configurazione estratti.

Fase 2: aggiornamento del file config.json

Le informazioni di configurazione vengono fornite all'agent tramite le seguenti variabili di ambiente nel file config.json estratto nel passo precedente. Esaminare i parametri seguenti per l'immagine agent.

1. Aggiornare config.json estratto in precedenza con i valori appropriati per ciascun parametro.

   È necessario eseguire l'escape della barra nel percorso file.

   Esempio 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
   }
   

   Esempio config.json con valori popolati.

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

2. Salva il file.

3. Completare i passi riportati nella seguente sezione per avviare l'agent.

Passo 3: avvio dell'agent

1. Avviare l'agent eseguendo il comando install in PowerShell.

   .\install
   

   Se si avvia l'agente e si riceve un errore Windows Microsoft Defender SmartScreen, questo è previsto. Gli script di installazione in testo semplice non sono firmati. Si consiglia di affidarsi al passaggio di verifica del sha512sum dopo aver scaricato l'agente.

2. Verificare che l'agente sia installato eseguendo il comando Get-Service in PowerShell.

   Get-Service 'SatelliteConnectorService'
   

3. Visualizzare i log dell'agent eseguendo il comando Get-Content in PowerShell.

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

4. Facoltativo: Arrestare l'agent eseguendo il comando uninstall in PowerShell.

   .\uninstall
   

Dopo aver impostato un agente, è possibile creare endpoint e ACL per gestire l'accesso a tali endpoint. Per ulteriori informazioni, vedi Creazione e gestione degli endpoint del connettore.

Aggiornamento dell'agent su Windows

È possibile utilizzare il comando update-service nel pacchetto agente per applicare le modifiche alla configurazione dell'agente. Quando si esegue il comando, l'agent viene arrestato, disinstallato e reinstallato. Segui i passaggi riportati di seguito per aggiornare il tuo agente.

1. Prima di effettuare l'aggiornamento, esaminare le modifiche nel registro delle modifiche dell'agente di Windows Connector e verificare se l'ultima versione è più recente dell'agente in esecuzione.

   Il numero di versione corrente si trova nel file version.txt all'interno del pacchetto dell'agente in esecuzione. Se non viene trovato alcun file version.txt o se il numero della versione corrente è inferiore a quello della versione più recente, è disponibile una versione più recente da aggiornare.

2. Se è disponibile una versione più recente dell'agente e si desidera utilizzarla, scaricare la versione più recente seguendo le istruzioni riportate in Fase 1: Download dei file dell'agente Connector dalla CLI prima di procedere con i passaggi successivi.

3. Modificare i parametri di configurazione nel file config.json.

   Esempio 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
   }
   

   Esempio config.json con valori popolati.

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

4. Eseguire il comando update-service in PowerShell.

   .\update-service
   

5. Verificare che l'agente sia installato eseguendo il comando Get-Service in PowerShell.

   Get-Service 'SatelliteConnectorService'
   

6. Visualizzare i log dell'agent eseguendo il comando Get-Content in PowerShell.

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