Etapa 1: Criando os arquivos de configuração locais

Há várias maneiras de transmitir informações de variável de ambiente de configuração do agente ao contêiner. O exemplo a seguir usa os arquivos de configuração. No entanto, também é possível usar o comando docker run --env para especificar os valores

Esteja ciente de que se você usar o --env com sua chave de API, a chave de API será exposta para o ambiente de contêiner e estará visível na saída do comando docker inspect. É possível proteger sua chave de API em um arquivo e, em seguida, usar o nome do arquivo na variável de ambiente. Se você optar por usar o nome do arquivo, deverá certificar-se de que o caminho de arquivo especificado na variável de ambiente seja montado em um caminho de arquivo no contêiner, conforme mostrado no exemplo a seguir..

Os nomes de arquivos mostrados nas etapas a seguir são exemplos e podem ser customizados para seu ambiente..

1. Crie um diretório para os arquivos de configuração, neste exemplo, ~/agent/env-files

2. Crie um arquivo no diretório ~/agent/env-files chamado apikey com um valor de linha único de sua chave de API do IBM Cloud que possa acessar o Conector Satellite.

3. Crie um arquivo no diretório ~/agent/env-files chamado env.txt com os valores a seguir: Modifique a variável ' SATELLITE_CONNECTOR_ID com seu Satellite ID do conector.

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

4. Neste ponto, seu diretório contém 2 arquivos e é semelhante ao exemplo a seguir.

   env-files$ ls
   apikey  env.txt
   

5. Conclua as etapas na seção a seguir para fazer pull da imagem do agente

Etapa 2: extração da imagem do agente

1. Efetue login no IBM Cloud® Container Registry. Ou efetue login no repositório diretamente do Docker com sua chave de API.

   ibmcloud cr region-set icr.io
   

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

2. Obtenha a versão mais recente da imagem publicada que seja adequada à sua arquitetura. Os valores de tag aceitos são latest, latest-amd64, latest-arm64, latest-ppc64le e latest-s390x. Você pode encontrar a lista de versões publicadas em IBM Satellite Connector Agent Release History.

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

3. Siga as etapas a seguir para executar a imagem do agente.

Etapa 3: Executando a imagem do agente

1. Para visualizar as versões disponíveis da imagem do agente, execute o comando a seguir:

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

   Saída de exemplo:

   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. Monte seu diretório env-files para o diretório /agent-env-files do contêiner usando a opção -v É possível usar a versão mais recente ou uma versão específica da imagem publicada.

   Se uma variável de ambiente estiver usando um caminho para um arquivo, esse caminho deverá ser um caminho de arquivo no contêiner. Para recuperar o caminho de arquivo, use a opção -v no comando docker run A opção -v é especificada pelo caminho do diretório da variável de ambiente local, seguido pelo caminho montado no contêiner e separado por :. Por exemplo, -v ~/agent/env-files:/agent-env-files, em que ~/agent/env-files é o caminho local e /agent-env-files é um caminho no contêiner.

   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 de exemplo que usa a versão 1.1.0 da imagem, execute o comando a seguir:

   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. É possível verificar se o túnel foi estabelecido para o seu Conector consultando os logs do contêiner

   docker logs CONTAINER-ID
   

   Próximo ao início do log, é possível localizar entradas semelhantes aos exemplos a seguir:

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

Após configurar um agente, é possível criar Terminais e ACLs para gerenciar o acesso a esses terminais. Para obter mais informações, consulte Criando e gerenciando terminais do Connector.

Etapa 1: fazendo download dos arquivos do agente do Connector a partir da CLI

1. Na CLI, execute o comando a seguir para fazer download do arquivo .zip do agente.

   ibmcloud sat agent attach --platform windows
   

   Saída de exemplo

   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. Verifique o sha512sum do .zip executando o seguinte comando no PowerShell.

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

3. Execute o comando a seguir no PowerShell para extrair o conteúdo do arquivo .zip

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

4. Conclua as etapas na seção a seguir para atualizar os arquivos de configuração extraídos.

Etapa 2: Atualizando o arquivo config.json

As informações de configuração são fornecidas ao agente por meio das variáveis de ambiente a seguir no arquivo config.json extraído na etapa anterior. Revise os seguintes parâmetros para a imagem do agente.

1. Atualize o config.json extraído anteriormente com os valores apropriados para cada parâmetro.

   Deve-se escapar a barra no caminho de arquivo

   Exemplo: 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
   }
   

   Exemplo config.json com valores preenchidos.

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

2. Salve o arquivo .

3. Conclua as etapas na seção a seguir para iniciar o agente

Etapa 3: Iniciando o Agente

1. Inicie o agente executando o comando install no PowerShell.

   .\install
   

   Se você iniciar o agente e receber um erro do Windows Microsoft Defender SmartScreen, isso é esperado. Os scripts de instalação de texto simples não são assinados. Sugerimos que você confie na etapa de verificação do sha512sum após o download do agente.

2. Verifique se o agente está instalado executando o comando Get-Service no PowerShell.

   Get-Service 'SatelliteConnectorService'
   

3. Visualize os logs do agente executando o comando Get-Content no PowerShell

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

4. Opcional: pare o agente executando o comando uninstall no PowerShell.

   .\uninstall
   

Após configurar um agente, é possível criar Terminais e ACLs para gerenciar o acesso a esses terminais. Para obter mais informações, consulte Criando e gerenciando terminais do Connector.

Atualização do agente no Windows

Você pode usar o comando update-service no pacote do agente para aplicar alterações de configuração ao seu agente. Quando você executa o comando, o agente é interrompido, desinstalado e reinstalado Siga as etapas a seguir para atualizar seu agente.

1. Antes de atualizar, examine as alterações no registro de alterações do agente do Connector Windows e verifique se a versão mais recente é mais recente do que o agente em execução no momento.

   Você pode encontrar o número da versão atual no arquivo version.txt dentro do pacote do agente para o agente em execução no momento. Se nenhum arquivo version.txt for encontrado ou se o número da versão atual for menor do que o número da versão mais recente, há uma versão mais recente disponível para atualização.

2. Se houver uma versão mais recente do agente disponível e você quiser usá-la, faça o download da versão mais recente seguindo as instruções em Etapa 1: download dos arquivos do agente do Connector da CLI antes de prosseguir para as etapas a seguir.

3. Modifique os parâmetros de configuração no arquivo config.json .

   Exemplo: 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
   }
   

   Exemplo config.json com valores preenchidos.

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

4. Execute o comando update-service no PowerShell..

   .\update-service
   

5. Verifique se o agente está instalado executando o comando Get-Service no PowerShell.

   Get-Service 'SatelliteConnectorService'
   

6. Visualize os logs do agente executando o comando Get-Content no PowerShell

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