Install GridOS Connect

This is an installation guide for GridOS Connect deployed on GridOS Foundation environments. Foundation is the Kubernetes-based platform that provides the core infrastructure services on which Connect runs. For more information about Foundation, see the Foundation documentation.

A base Foundation installation requires additional configuration to run Connect correctly. This guide includes all required Foundation-specific configuration steps for Connect.

1. Deployment

1.1. Prerequisites

Before deploying Connect, complete all prerequisites in this section: tools, Artifactory access, sizing, and Foundation configuration. Completing these steps first prevents most installation errors and avoids expensive rework later.

1.1.1. Command-line Tools

Install these command-line tools on your machine:

kubectl
helm
helmfile (Required only when installing using Helmfile.)
helm-diff (Required only when installing using Helmfile.)

1.1.2. GE Vernova Artifactory Access

All Connect artifacts (Helm charts, Docker images, Maven dependencies, and installation tools) are stored on GE Vernova Artifactory.

Contact your GE Vernova Support representative for more information on how to get access to GE Vernova Artifactory.

Generate an Artifactory token:

Go to: https://gart.software.gevernova.com/ui/user_profile
Once logged in, click on Generate an Identity Token. The description should help you remember its purpose, e.g: GridOS Connect Token.
Click Next. The generated token is used as your password credential, with your SSO as the username.

1.1.3. Cluster Sizing

To install Connect, request an appropriately sized Foundation cluster. For sizing guidance, see Sizing and Scaling Guidelines.

1.1.4. Kubernetes and Foundation Configuration

To configure or verify the Foundation installation, set your kubectl current-context to your Foundation environment.

Connect relies on Foundation services (including Zitadel and Apisix). Some of these services require explicit configuration before Connect can be installed.

Configure Local DNS

To access these services from your local machine, configure local DNS by mapping required domains to the externally accessible worker IP (worker-ip).

Determine worker-ip from a node without the control-plane role. In POSIX (macOS or Linux) shells:
```
kubectl get nodes -o wide | grep -v control-plane | tail -n 1 | awk '{ print $6 }'
```

Add these host mappings:

{worker-ip} admin.YOUR_FOUNDATION_DOMAIN
{worker-ip} api.YOUR_FOUNDATION_DOMAIN
{worker-ip} console.YOUR_FOUNDATION_DOMAIN
{worker-ip} service.YOUR_FOUNDATION_DOMAIN
{worker-ip} zitadel.YOUR_FOUNDATION_DOMAIN

console.YOUR_FOUNDATION_DOMAIN becomes available after Connect is deployed.

If you use a Connect Agent or mTLS service account, add this pattern as well:

{worker-ip} {org-id}.mtls.YOUR_FOUNDATION_DOMAIN

Example:

10.227.xx.xxx gridos.mtls.env-connect-pte-ingress.local

Foundation Version

Connect is continuously tested with the latest Foundation changes in a combined test environment. We recommend Foundation version {latest-foundation-version}. Deploying on older Foundation versions may cause unexpected behavior.

For known issues and compatibility details, see:

Enable CPU Throttling for Kubernetes

Connect requires Kubernetes CPU throttling for predictable performance and behavior.

You can enable CPU throttling during cluster setup or apply it to an existing cluster. For existing clusters, you need SSH access to each Kubernetes node and cluster admin privileges.

Apply to Existing Cluster

SSH to each Kubernetes node and update the RKE2 kubelet setting:

# Edit this file on all nodes
vi /etc/rancher/rke2/config.yaml

# Set cpu-cfs-quota to true
kubelet-arg:
  - "cpu-cfs-quota=true"

# Restart rke2-server
sudo systemctl restart rke2-server

# Restart rke2 worker node if applicable
sudo systemctl restart rke2-agent

Apply During Foundation Installation Using PDI

See example manifest in Foundation docs. Set cpu_limits_enforcement: true under param group k8s_all_group_vars:

...
- id: k8s_all_group_vars
  params:
    cpu_limits_enforcement: true
...

Apply During Foundation Installation Without PDI

See Foundation installation documentation and set cpu_limits_enforcement to true.

TLS

Ensure TLS is configured correctly in Foundation. If your environment uses a private CA, add the CA chain to your local trust store.

Validate TLS by opening https://zitadel.YOUR_FOUNDATION_DOMAIN in a browser without certificate warnings.

Namespace Requirements (Istio)

If Connect is to be deployed in the default Foundation namespace, Istio injection is typically already enabled. For custom namespaces, ensure the namespace has label istio-injection=enabled.

Verify:

kubectl get namespace <namespace> -o jsonpath='{.metadata.labels}'

Expected output includes:

{"istio-injection":"enabled","kubernetes.io/metadata.name":"<name of namespace>"}

If the label is missing, one option is to apply it using the foundation-namespaces Helm chart.

Connect-specific Foundation Helm Values

Base Foundation installations require additional Connect-specific settings. Use Foundation Helm overlay values and merge them into your Foundation Helm values (for example local-overrides.yaml).

If you are uncertain about applying these Foundation settings, contact Foundation support.

Authentication and Authorization

Authorization and authentication (auth) in Foundation is managed by Zitadel, which is configured to connect with your Identity Provider (IdP) during Foundation installation. Auth-related configurations required for Connect can be applied during Foundation installation via the Foundation Data Loader.

You can validate such configurations in Security Admin Console.

If Connect-specific auth configurations were not applied during Foundation installation, you can configure them now in Security Admin Console manually.

Connect Roles and Permissions

To grant a user access to Connect for logging in to the Connect Console or deploy integration flows, ensure all the following:

The user account is a member of your IdP user group (AD/LDAP)
A Role Manager Permission for the target Connect role is created
A Role Manager Role is created and assigned the Role Manager Permission
A Role Manager Usergroup is created and assigned the Role Manager Role
A mapping between the Role Manager Usergroup and the IdP user group is created

For each Connect role you need, create a Role Manager Permission, Role, Usergroup, and mapping to the IdP group.

Use this Role Manager Permission format:

connect.<ORG_ID>.<GRIDOS_CONNECT_ROLE>

connect. is required
<ORG_ID> identifies your tenant organization (for example acme)
<GRIDOS_CONNECT_ROLE> must be a lowercase role from Connect roles, i.e., admin, monitor, or agent.

<ORG_ID> corresponds to the required owner-id parameter when deploying flows using SDK deployer.

Connect Identity Reconciler UserGroup

Connect Identity Reconciler applications require a mapped user group named connect-identity-reconciler with the following permissions:

roleManager.userGroups.read.readAll
roleManager.permissions.read.readAll
roleManager.roles.read.readAll

In Security Admin Console:

Create role Connect Identity Reconciler and assign the permissions above.
Create user group Connect Identity Reconciler with mapped group name connect-identity-reconciler.
Assign role Connect Identity Reconciler to that user group.

Optional Multi-site Configuration

If you plan a multi-site deployment, enable it during Foundation deployment:

1.2. Deploy Connect

1.2.1. Prepare for Deployment

The Connect installation includes the main chart, connect, a CRD chart connect-crds, and three dependency charts: connect-postgresql, connect-victoria-metrics, and connect-openbao.

These charts, along with the required value override and auxiliary deployment files, are packaged into a ZIP artifact called the Helm Deployment Template.

Download the Helm Deployment Template to your local machine.
Unpack the ZIP file.

Review the allocated resources. The Helm Deployment Template includes a values.yaml file for each chart. Review and override the default resource allocations as needed for your use case.

The service resource values are set conservatively. Since the Connect team cannot anticipate customer-specific requirements, these resource allocations must be reviewed carefully. Misconfiguration can lead to broken clusters, poor performance, or excessive compute costs.

To review and override the chart values, see Chart Value Override Recommendations.

Set the kube-context and namespace for Connect installation.

# Unix
KUBE_CONTEXT=<KUBE_CONTEXT>
CONNECT_NS=<CONNECT_NAMESPACE>

# Windows - PowerShell
$KUBE_CONTEXT=<KUBE_CONTEXT>
$CONNECT_NS=<CONNECT_NAMESPACE>

Ensure that you set (override) the value of the property global.clusterExternalUrl to the externally available service domain in the form of an HTTPS URL (e.g., https://YOUR_FOUNDATION_DOMAIN).

1.2.2. Enable the Connect Deployment Operator

This step is optional. You can choose to deploy the Connect Deployment Operator now or skip it and deploy it later, depending on your requirements.

The Connect Deployment Operator manages Connect deployables as Kubernetes objects.

Connect Deployment Operator Configuration

The operator is an opt-in feature and must be enabled in a Connect Helm value override:

deploymentoperator:
  enabled: true

The operator requires OAuth 2.0 authentication with Connect Admin privileges to manage deployments. It retrieves the required credentials from a Zitadel Service User Secret in the same Kubernetes namespace where Connect is deployed.

By default, the operator expects a Zitadel service user secret named connect-deployment-operator-creds. This service user must be added to the Connect deployment and is not created automatically by the Connect chart.

You can configure the operator to use a different Zitadel service user secret by overriding the secret name. This allows you to reuse an existing Zitadel service user secret that has Connect Admin privileges.

deploymentoperator:
  enabled: true
  secrets:
    existing:
      connect-deployment-operator-creds:
        name: 'your-existing-zitadel-service-user-secret'

1.2.3. Enable the Connect Email API

This step is optional. You can choose to enable the Connect Email API now or skip it and enable it later, depending on your requirements.

The Connect Email API is an optional module that exposes a REST endpoint for sending emails through the sendEmail processor.

The sendEmail processor uses SMTP to send emails. You must configure the SMTP connection details and credentials as described in the sendEmail SMTP Configuration section.

Connect Email API Configuration

The Email API is an opt-in feature and must be enabled in a Connect Helm value override:

emailApi:
  enabled: true

The Email API supports all the service account credential types in Connect. The default is apiKey.

You must enable the Deployment Operator to deploy the Connect Email API.

The Email API requires the Connect custom resource definitions (CRDs) to be present, which are included in Connect 26R03 or later.

1.2.4. Perform the Deployment

Make sure you have completed all prerequisites before starting the deployment. Then continue with one of the following deployment options: Deploy Air-gapped, Deploy with Helm, or Deploy with Helmfile.

Deploy Air-gapped

Download the Connect Cache Container, which contains the Docker images required for installation, to the machine where you unpacked the Helm Deployment Template files.

For Connect versions earlier than 1.22.0, download the Connect Cache Container (.tgz file).
For Connect versions 1.22.0 and later, download the Connect Cache Container (.tar.gz file).

The Helm Deployment Template unpacked in the Prepare for Deployment step, contains a docs/README.adoc file with detailed instructions about how to perform an air-gapped installation of Connect.

Deploy with Helm

To ensure correct installation, a file is provided in the Helm Deployment Template that specifies the required arguments for the helm upgrade command.

Perform the following steps for each chart, in this order: connect-crds, then connect-postgresql, connect-victoria-metrics, connect-openbao, and finally connect.

Navigate to the unpacked ZIP folder.

Set the release name. Start with connect-crds, then repeat for each subsequent chart.

# Unix
RELEASE_NAME="connect-crds"

# Windows - PowerShell
$RELEASE_NAME="connect-crds"

Set the chart archive reference with the value provided in connect-charts.csv.

# Unix
CHART_ARCHIVE_PATH=$(grep "$RELEASE_NAME," connect-charts.csv | cut -d, -f3)

# Windows - PowerShell
$CHART_ARCHIVE_PATH=$(Get-Content connect-charts.csv | Select-String -Pattern "$RELEASE_NAME," | ForEach-Object { ($_ -split ',')[2].Trim() })

Install the Helm chart.

helm upgrade -i \
--kube-context $KUBE_CONTEXT \
-n $CONNECT_NS \
$RELEASE_NAME \
$CHART_ARCHIVE_PATH \
--values "$RELEASE_NAME/values.yaml" \
--set "global.clusterExternalUrl=https://YOUR_FOUNDATION_DOMAIN" \
--wait-for-jobs \
--wait \
--timeout=15m

Deploy with Helmfile

Helmfile diffs should be run in a dry-run mode, which can be set with the environment variable: HELM_DIFF_USE_UPGRADE_DRY_RUN=true.
Install the CRDs first. On a fresh cluster, the connect chart references CRD-based resources that do not yet exist. Installing connect-crds separately ensures the CRDs are registered before the remaining charts are diffed and applied.

Unix:
```
helmfile --kube-context $KUBE_CONTEXT -n $CONNECT_NS apply -l name=connect-crds
```
Windows - PowerShell:
```
helmfile --kube-context $KUBE_CONTEXT -n $CONNECT_NS apply -l name=connect-crds
```

Apply the full helmfile:

Unix:

CLUSTER_EXTERNAL_DNS=YOUR_FOUNDATION_DOMAIN; helmfile --kube-context $KUBE_CONTEXT -n $CONNECT_NS apply --set "global.clusterExternalUrl=https://$CLUSTER_EXTERNAL_DNS"

Windows - PowerShell:

$CLUSTER_EXTERNAL_DNS="YOUR_FOUNDATION_DOMAIN"
helmfile --kube-context $KUBE_CONTEXT -n $CONNECT_NS apply --set "global.clusterExternalUrl=https://$CLUSTER_EXTERNAL_DNS"

The two-step process is only required for the initial installation. Subsequent upgrades can use a single helmfile apply when the CRDs already exist.

1.2.5. Restart Fluentbit Pods

Restart fluenbit pods

kubectl delete po -n foundation-cluster-monitoring -l app.kubernetes.io/name=fluent-bit

Restart flowserver pods

kubectl delete po -n foundation-env-default -l app.kubernetes.io/name=flowserver

For more information, see Flow-traces/Logs workaround.

For more information on how to create a machine user, see Create a machine user with the client credentials grant.

2. Chart Value Override Recommendations

After you extract the Helm Deployment Template, you can view the default chart values for each chart by running the following Helm command:

helm show values $CHART_ARCHIVE_PATH

See Deploy with Helm for details on how to resolve CHART_ARCHIVE_PATH.

Alternatively, you can reference the following for the default chart configurations:

It is recommended that you maintain custom value overrides in separate files stored in version control.

Defining value override files separately makes it easier to apply them while following the standard install or upgrade instructions.

For example, to increase the flow-server memory limit to 6GB for the connect chart:

Connect applications in the connect chart are JVM-based. Memory limits and requests must be set to the same value to ensure predictable performance and avoid JVM heap sizing issues.

The javaMaxRamPercentage setting controls what percentage of the container’s total memory the JVM uses for heap. For example, setting it to 70 means the JVM uses 70% of container memory for heap, while the remaining 30% is reserved for non-heap memory (such as metaspace, thread stacks, and native memory).

Create a separate values file values.resource.yaml.

# contents of values.resource.yaml
flowserver:
  resources:
    requests:
      cpu: 1.0
      memory: 6Gi
    limits:
      memory: 6Gi
  javaMaxRamPercentage: 70

Install or upgrade existing installation.

Using Helm:

helm upgrade -i \
--kube-context $KUBE_CONTEXT \
-n $CONNECT_NS \
$RELEASE_NAME \
$CHART_ARCHIVE_PATH \
--values "$RELEASE_NAME/values.yaml" \
--values values.resource.yaml  #<-- additional overrides
--wait-for-jobs \
--wait \
--timeout=15m

When applying custom value overrides using a values file (-f/--values) or a single property override (--set), the last (rightmost) argument specified takes precedence.

Using Helmfile:

Add the custom values file to the release entry in helmfile.yaml.gotmpl.

...
- name: connect
  chart: ./Charts/connect-xxx.tgz
  version: x.x.x
  values:
    - ./connect/values.yaml
    - values.resources.yaml  #<-- additional overrides
...

When specifying value override files in the releases[].values element of a Helmfile, the files are applied in order. The last file specified takes precedence.

The -f/--values and --set flags can also be passed to the helmfile apply command. They are applied to each release item, which can be useful for setting global values. For non-global value overrides, it is recommended to define them in the helmfile.yaml.gotmpl file.

2.1. Resource Scaling

Assuming you still have the Helm Deployment Template bundle extracted on your local machine:

Review the resource allocation in the values.yaml files provided for each chart.
Define any overrides as described in the Chart Value Override Recommendations section.
Run helmfile apply.

For more information about scaling Connect Kubernetes Deployments and the required configuration changes, see Scaling Kubernetes Deployments.

2.2. Add Host Aliases to Service Pods

Use the hostAliases override to configure flow server (Connect service) to communicate with other services that are outside the cluster where Connect is installed. For example, add the following override to your connect/values.yaml file to configure flow server to communicate with services in another cluster:

flowserver:
  hostAliases:
    - ip: "x.x.x.x" # IP address of the target service
      hostnames:
        - "xxx.xxx.xxx" # Hostname to resolve in the service pods

After you update the override file, run helmfile apply to apply the changes.

2.3. Connect Service Log Retention

Elastic Search stores Connect service logs. These logs provide Flow traces, an archive of integration executions. Log retention requires resources and for some use cases it may be beneficial to control when logs are purged. This can be configured using the jobs.elasticsearch.index.delete.minAge in the connect/values.yaml file located in the Helm Deployment Template.

For example, to decrease the retention time to 90 days, provide the following values override snippet:

jobs:
  # ...
  elasticsearch:
    index:
      delete:
        minAge: 90d
  # ...

Place the snippet directly in connect/values.yaml (from the Helm Deployment Template) or in a separate file, and apply it as described in Chart value override recommendations.

Run helmfile apply.

Make sure you have read the Elastic Search documentation on lifecycle policy updates.

3. Known Limitations

This section identifies known limitations and constraints when installing and operating Connect on Foundation.

3.1. CPU Throttling Requirement

Kubernetes CPU throttling must be enabled for Connect to function correctly. Without CPU throttling enabled, Connect services may exhibit unpredictable performance and behavior. See Enable CPU Throttling for Kubernetes for configuration instructions.

3.2. Flow server 1.27.0 has an error in the Foundation overlay file

The rancher-monitoring: override is incorrect, please use the equivalent entry from the 1.28.0 release.

3.3. Flow Server Upgrade Limitation

When upgrading from Connect version 1.18.0 or earlier to Connect version 1.19.0 or later, the flow-server deployment must be restarted. Rolling upgrades are not supported for this version transition.

Workaround: After upgrading Connect, restart the flow-server deployment:

Scale down the flow-server deployment to zero replicas:

kubectl -n foundation-env-default scale deploy connect-flowserver --replicas 0

Wait for all flow-server pods to terminate.

Scale up the flow-server deployment:

kubectl -n foundation-env-default scale deploy connect-flowserver --replicas 3

3.4. Fluentbit Log Collection Issue

After deploying Connect, Fluentbit may not automatically collect flowserver logs due to a known issue with the Fluentbit Operator. This manifests as missing flow traces in the Connect Console and an index_not_found_exception error for the flowserver-logs index.

Workaround: Restart both Fluentbit and flowserver pods after installation. See Flow-traces/Logs workaround for detailed instructions.

3.5. Log Duplication in Elasticsearch

The default Foundation Fluent-bit configuration causes Connect flowserver logs to be duplicated across Elasticsearch indices. Each log event is stored three times (twice in the log index and once in the flowserver-log index), increasing storage usage.

See Prevent Log Duplication of Connect Flow Server for configuration steps to eliminate redundant log storage.

3.6. Service Account Creation and Flow Access Granting Errors

The connect-identity and connect-resourceregistry services use OpenBao for secrets management. With Connect versions prior to 1.24.0, users may encounter errors when creating service accounts or granting flow access. This occurs because the connect-identity and connect-resourceregistry services are configured to use the connect-openbao:8200 Kubernetes service, which load balances requests across all OpenBao pods, including follower nodes. Follower nodes reject write operations.

Workaround: Add the following override in your connect/values.yaml to route requests to the OpenBao leader pod:

...
identity:
  config:
    application.yml:
      openbao:
        address: http://connect-openbao-active:8200
...
resourceregistry:
  config:
    application.yml:
      openbao:
        address: http://connect-openbao-active:8200
...

4. Next Steps

You have completed the installation of Connect on Foundation. If you want to deploy a new integration flow on Connect, review the following options:

To deploy Connect flows, see the SDK Deployer guide to configure your deployment settings. The management-api-root endpoint is https://api.YOUR_FOUNDATION_DOMAIN.
To deploy Connect service accounts, see Deploy Connect Service Accounts section.
To upgrade Connect, see Upgrade GridOS Connect.
To uninstall Connect, see Uninstall Connect.

5. Additional Resources

To manage access to platform services that support Connect, see Platform Services.
To troubleshoot Connect issues, see Troubleshoot GridOS Connect.
For information on Flow Server configuration properties, see Flow server Configuration.