Install Connect Agent

The GridOS Connect Agent is only supported on version 1.16.0 or later. Make sure you have upgraded your GridOS Connect deployment to a supported version.

Prerequisites

Before you install the Connect Agent, make sure your environment meets the following system requirements:

Hardware

Connect Agent can only be installed on a 64-bit version of Linux. This can be on a dedicated server or virtual machine but must meet the following criteria:

Hardware Recommended minimum requirements

Processor

Dual 64-bit processors. More processors allow for increased, simultaneous flow executions.

Memory

4 GB of RAM. More RAM allows for increased, simultaneous flow executions and might be required to process large data payloads.

Hard disk

10GB. SSD based storage is recommended for the best performance.

Software

You will need to install Docker (with Docker Compose), version 20.10.0 or higher.

  • Remove unused container images after an upgrade to free up storage:

    docker image prune

Create an Agent in the Heartbeat Console

To get started with Connect Agent, first create an Agent in Heartbeat:

  1. Navigate to the Connect Console, and select Agents from the left navigation menu:

    The list of Connect Agent instances includes a name and an auto-generated ID.

  2. Select the Create Agent in the top right corner and enter a name, which generates the Agent ID.

The ID is required for your Heartbeat Agent configuration and for the client mTLS certificate during the Heartbeat Agent installation.

To view the Connect cluster certificate, select the information icon (ⓘ) for the agent you created.

A dialog box opens, where you can view the Connect cluster certificate and copy the certificate details.

Create a Zitadel Service User for the Connect Agent

To send deployment data to the Connect cluster, the Connect Agent authenticates by using the OAuth 2.0 client credentials grant.

Create a Zitadel service user and ensure the following:

  • One of the user groups in the data.groups array for the Zitadel Service User ConfigMap MUST be associated with the Connect Agent role. See Connect Roles for more information about the available GridOS Connect roles.

  • Run the following command to retrieve your Client ID, Client Secret, and Zitadel project ID.

    kubectl get secret connect-deployer -o=yaml

    You can use the obtained values in your configuration file.

  • To retrieve the secrets, see the Zitadel service user credentials, run the kubectl commands and use the values in the configuration file.

Install the Connect Agent

Accessing the Connect Agent artifacts

The Connect Agent artifacts are available in GE Vernova Artifactory, if you don’t have access see the GE Vernova Electrification Software Customer Portal access section of the documentation.

If you are deploying to a machine with network access to Artifactory, login with your docker client.

docker login dig-grid-artifactory.apps.ge.com

Deployment Artifacts for Air-Gapped Machines

If you are deploying to a machine with network access to the Artifactory, you can skip this section.

  1. Visit the connect-releases repository.

  2. Download the connect-agent-cache-container-{version}.tgz file to your deployment machine.

  3. Load the cache container contents to your local environment:

    # Load the Connect Agent cache image
docker load < connect-agent-cache-container-{version}.tgz
# Fetch the Connect agent docker images from the cache
docker run --rm -it \
  -v ${PWD}:/app/artifacts \
  --entrypoint bash \
  grid-oslo-docker/connect-agent-cache:{version} -c 'cp data/connect-agent-images.tar.gz artifacts'
# Extract connect-agent-images.tar
tar xvfz connect-agent-images.tar.gz
# Load the 4 Connect Agent images (vector, postgres, connect-agent and connect-agent-starter)
docker load < connect-agent-images.tar
# you can remove the intermediary container images and tarballs to free up storage
docker rmi grid-oslo-docker/connect-agent-cache:{version}
rm connect-agent-cache-container-*.tgz
rm connect-agent-images.tar*

Target Machine Deployment Preparations

  1. On your deployment target Linux machine, create an installation directory. For example:

    export AGENT_INSTALL_DIR=~/connect-agent-installation
mkdir -p $AGENT_INSTALL_DIR/cert

    Remove unwanted log archive files. These are stored as .gz files in the logging directory: ${AGENT_INSTALL_DIR}/data/connect-agent/logs.

  2. Visit the connect-releases repository.

  3. Download the connect-agent-{version}.zip file to your installation directory.

  4. Extract the zip file to your installation directory:

    cd ${AGENT_INSTALL_DIR}
unzip connect-agent-{version}.zip

  5. To view the connect cluster certificate, select Expand to see certificate. This certificate is your server-ca-cert. Copy the server-ca-cert PEM file to ${AGENT_INSTALL_DIR}/cert/ca.crt.

  6. Create client-ca-cert and upload the ca-crt certificate to the Connect Console.

  7. Copy the client-crt PEM file to ${AGENT_INSTALL_DIR}/cert/client.crt.

  8. Copy the client-key PEM file to ${AGENT_INSTALL_DIR}/cert/client.key.

Rename (or copy) the connect-agent-template.env file to its new name connect-agent.env.

Each new Connect Agent release will come with a (possible modified) version of this file. Hence, renaming it will ensure that the changes applied to this file will not be overwritten by a new release.

Open the new connect-agent.env file and fill in the following properties:

Property Description

CONNECT_AGENT_ID

The unique ID for this Connect Agent. This ID is provided when adding a new Connect Agent in the Connect Console. For example: 22027619-b6ed-43b3-9d9d-4223ff68b087.

CONNECT_OWNER_ID

The ownerId for the organization. As used in the deployment directory as well as the deployment config. For example: gridos.

CONNECT_DOMAIN

The FQDN for the main GridOS Connect cluster. See YOUR_FOUNDATION_DOMAIN in our installation documentation. This information can be found in the GridOS Connect Console, under the Agent settings. For a reference image, see Connect Cluster CA Certificate section. For example: env-connect-mvp-ingress.local.

DEPLOYMENT_ENVIRONMENT

The environment name of the main GridOS Connect cluster. As used in the deployment directory as well as the deployment config. For example: mvp.

DECRYPTION_KEY

Decryption key for credentials stored in connect-agent-override.properties. Optional. Only needed if the properties if the the properties contain sensitive information. See how encrypted values are generated for more information.

POSTGRES_PASSWORD

Select a cryptographically secure password to be used for the Connect Agent PostgreSQL server running on the Agent environment. Do not change after first installation. For example: postgres.

DEPLOYMENT_PUBLISHER_CLIENT_ID

The client ID of the service user used for publishing to the upstream server API. Same as used for SDK deployer. This pertains to the section above. For example: connect-deployer@foundation.local.

DEPLOYMENT_PUBLISHER_CLIENT_SECRET

The client secret of the service user used for publishing to the upstream server API. Same as used for SDK deployer. This pertains to the section above. For example: sa2mkUusTKGn5PQ5nqXFYy4UUiKBeNvbha3FaG0ZBgnxjeVHD1UI0oE7b6eOyLx7.

DEPLOYMENT_PUBLISHER_SCOPE

The scope used for publishing to the upstream server API. Same as used for SDK deployer. This pertains to the section above. For example: openid urn:zitadel:iam:org:project:id:306865721310380478:aud urn:zitadel:iam:org:projects:roles.

DEPLOYMENT_PUBLISHER_HTTP_PROXY_URI

URI for HTTP proxy. (Optional)

DEPLOYMENT_PUBLISHER_HTTP_PROXY_USERNAME

The username which will be used for HTTP proxy authentication. (Optional)

DEPLOYMENT_PUBLISHER_HTTP_PROXY_PASSWORD

The password which will be used for HTTP proxy authentication. (Optional)

POLL_FREQUENCY_SECONDS

Number of seconds between each time the Connect Agent polls for new deployments (default is 120 seconds).