Connect Deployment Operator

The Connect Deployment Operator manages Connect deployables as Kubernetes objects. It supports two Custom Resource Definitions (CRDs): ConnectServiceAccount for managing Connect Service Accounts and ConnectDeploymentSet for managing a collection of Connect deployables including integration flows, resource, secrets, flow accesses and service accounts.

Deploy GridOS Connect Service Accounts

The Connect Deployment Operator supports managing Service Accounts in Kubernetes by using the ConnectServiceAccount Custom Resource Definition (CRD). The service account properties are stored in a Kubernetes Secret, including generated credentials for the BasicAuthentication and ApiKey credential types.

ConnectServiceAccount CR Example

The following is an example of a ConnectServiceAccount custom resource in Kubernetes:

apiVersion: connect.gridos.com/v1
kind: ConnectServiceAccount
metadata:
  name: your-service-account
  namespace: foundation-env-default
spec:
  organizationId: gridos
  userName: test-user
  credentialsType: BasicAuthentication
  serviceAccountSecretRef:
    name: your-service-account-secret

ConnectServiceAccount CR Configuration

The following specification properties are required when creating a ConnectServiceAccount custom resource:

organizationId: The ID of the organization that the deployment belongs to.
userName: The username associated with the Connect service account. This value must be unique within the Connect organization.
credentialsType: The authentication supported by the Connect service account. Supported values are BasicAuthentication, ApiKey, Poller, mTLS, and OIDC.
serviceAccountSecretRef: A reference to the Kubernetes Secret where the Connect service account details are stored after the resource is created.

The Secret contains all specification properties defined on this custom resource, along with the serviceAccountId assigned by Connect during creation. Depending on the selected credentialsType, the Secret also includes additional fields:
- For BasicAuthentication: password - The generated password for the service account.
- For ApiKey: apiKey - The generated API key for the service account.
Once the service account has been reconciled, the current Secret reference is stored in the status subresource under the property status.lastServiceAccountSecretRef. When the operator detects a change to serviceAccountSecretRef, it automatically moves the Secret to the new location.

The following specification properties are optional:

jwtClaimsMatchJsoniqScript: A JSONiq script used to match JWT claims. This property is required when credentialsType is set to OIDC and is ignored for all other credential types.
credentialResetId: An identifier that can be updated to trigger regeneration of credentials for Connect service accounts that use BasicAuthentication or ApiKey.

Once the service account has been reconciled, the current value is stored in the status subresource under the property status.lastCredentialResetId. When the operator detects a change to this value, it triggers a credential reset in Connect and updates the associated Kubernetes Secret with the new credentials. The default value is init.

The ConnectServiceAccount custom resource results in the creation of a new Connect service account only if a service account with the specified userName and organizationId does not already exist in Connect.
The operator sets the following standard Kubernetes status conditions (metav1.Condition) on the resource to reflect reconciliation state:
- The Ready condition is set to True with the reason Reconciled when the Connect service account is confirmed to exist and the Kubernetes Secret referenced by serviceAccountSecretRef is confirmed to exist.
- While reconciliation is in progress, the Ready condition is set to False with the reason Reconciling.
- If reconciliation fails, the Ready condition is set to False with the reason ReconciliationFailed.

Tooling such as Argo CD can observe these conditions through the status subresource to determine when the service account is available.

Service account reconciliation is one-way. When a Connect service account is managed through this custom resource, any manual changes made directly in the Connect Console or through the Connect management API are not reflected in the corresponding Connect Service Account Kubernetes resource.

Deploy GridOS Connect Deployment Sets

The Connect Deployment Operator deploys versioned sets of Connect deployables through the ConnectDeploymentSet CRD. A ConnectDeploymentSet references a deployment bundle, which may contain integration flows, Connect Resources, Connect Secrets, and flow access definitions. The deployment set can also reference additional Kubernetes resources for integration flow configuration overrides, Connect Service Accounts, Connect Secrets, and decryption keys.

The deployment bundle is built with the SDK Deployer and is provided to the operator either as a ConfigMap or a container image.

ConnectDeploymentSet CR Example

Using a container image:

The following example shows a ConnectDeploymentSet custom resource that uses a deployment bundle provided as a container image:

apiVersion: connect.gridos.com/v1
kind: ConnectDeploymentSet
metadata:
  name: my-deployment-set
  namespace: foundation-env-default
spec:
  organizationId: gridos
  environment: prod
  bundleImage: my-registry.example.com/my-deployment-bundle-image:1.0.0
  flowConfigConfigMapRefs:
    - name: my-flow-config
  flowConfigSecretRefs:
    - name: my-flow-config-secrets
  serviceAccountRefs:
    - name: my-service-account
  connectSecretsRefs:
    - name: my-connect-secret
  flowsToDelete:
    - deprecated-flow
  resourcesToDelete:
    - deprecated-resource
  secretsToDelete:
    - deprecated-secret-key

Using a ConfigMap:

The following example shows a ConnectDeploymentSet custom resource that uses a deployment bundle provided as a ConfigMap instead of a container image:

apiVersion: connect.gridos.com/v1
kind: ConnectDeploymentSet
metadata:
  name: my-deployment-set
  namespace: foundation-env-default
spec:
  organizationId: gridos
  environment: prod
  bundleConfigMapRef:
    name: my-deployment-bundle

ConnectDeploymentSet CR Configuration

The following diagram shows how the Kubernetes resources feed into the Connect Deployment Operator, which deploys configurations to the Connect Management API.

The Connect Deployment Operator watches ConnectDeploymentSet resources and deploys the contained deployables to the target environment.

The following specification properties are required when creating a ConnectDeploymentSet custom resource:

organizationId: The ID of the organization that the deployment belongs to. Corresponds to ownerId in the SDK Deployer directory layout.
environment: The target environment for the deployment. Corresponds to environment in the SDK Deployer directory layout.
bundleImage: The name of a container image that provides the deployment bundle ZIP at /connect-deployment-bundle.zip and includes curl in the PATH. Either bundleImage or bundleConfigMapRef is required; they are mutually exclusive. See Deployment Bundle Image.
bundleConfigMapRef: A reference to a ConfigMap with a binaryData entry named connect-deployment-bundle.zip containing the base64-encoded deployment bundle. Either bundleConfigMapRef or bundleImage is required; they are mutually exclusive. See Deployment Bundle ConfigMap.

The following specification properties are optional:

flowConfigConfigMapRefs: A list of references to ConfigMaps containing flow configuration overrides. See Flow Configuration Overrides.
flowConfigSecretRefs: A list of references to Kubernetes Secrets containing flow configuration overrides. See Flow Configuration Overrides.
serviceAccountRefs: A list of references to ConnectServiceAccount resources that the deployment depends on. See Deploy GridOS Connect Service Accounts.
connectSecretsRefs: A list of references to Kubernetes Secrets containing Connect Secrets specifications. See Connect Secrets.
flowsToDelete: A list of flow IDs to delete from the target environment. See Deployment Process.
resourcesToDelete: A list of resource identifiers for Connect Resources to delete from the target environment. See Deployment Process.
secretsToDelete: A list of secret keys for Connect Secrets to delete from the target environment. See Deployment Process.
decryptionKeySecretRef: A reference to a Kubernetes Secret containing a decryption-key entry. Used to decrypt Connect secret properties. See Decryption Key Secret.
groups: Corresponds to the groups SDK Deployer parameter.
flowPattern: Corresponds to the flow-pattern SDK Deployer parameter.
resourcePattern: Corresponds to the resource-pattern SDK Deployer parameter.
secretsPattern: Corresponds to the secrets-pattern SDK Deployer parameter.

Properties specified on the ConnectDeploymentSet take precedence over equivalent properties specified in the deployment bundle.

The operator sets the following standard Kubernetes status conditions (metav1.Condition) on the resource to reflect reconciliation state:

The Ready condition is set to True when all deployables are successfully deployed and all flows report Up status.
While reconciliation is in progress, the Ready condition is set to False with the reason Reconciling.
If the deployment fails, the Ready condition is set to False with the reason DeploymentFailed.

Tooling such as Argo CD can observe these conditions through the status subresource to determine when the deployments are available.

Deployment Bundle Provisioning

The deployment bundle ZIP file is created using the SDK Deployer and provided to the operator in one of two ways: as an Open Container Initiative (OCI) image or as a base64-encoded ConfigMap entry.

Deployment Bundle Image

An OCI container image provides the deployment bundle ZIP at /connect-deployment-bundle.zip and includes curl in the PATH. The image USER must not be root UID 0 and must have execution access to curl and read access to the bundle ZIP. The image is referenced from the ConnectDeploymentSet resource using the bundleImage property.

The operator creates a temporary job for the image, which posts the bundle to an internal operator endpoint. The endpoint is protected by a Universally Unique Identifier (UUID) mechanism to ensure that only valid bundles are accepted.

Deployment Bundle ConfigMap

A ConfigMap contains a binaryData entry named connect-deployment-bundle.zip that holds the base64-encoded deployment bundle. The ConfigMap is referenced from the ConnectDeploymentSet resource and monitored by the Deployment Operator.

The resource must have the label app.kubernetes.io/component=connect-deploymentoperator to be processed by the operator.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-deployment-bundle
  namespace: foundation-env-default
  labels:
    app.kubernetes.io/component: connect-deploymentoperator
binaryData:
  connect-deployment-bundle.zip: <base64-encoded-bundle>

If a deployment bundle exceeds the maximum allowed ConfigMap size, deployables can be split across multiple ConnectDeploymentSet resources or a bundle image can be used instead.

Flow Configuration Overrides

Flow configuration overrides let you customize specific integration flow properties for the target environment. This enables the same deployment bundle to be reused across multiple environments with different configurations.

The Deployment Operator applies the overrides on top of the flow definitions in the bundle during deployment and performs type conversion as needed, based on the property type defined in the flow spec.

Overrides are provided as key-value pairs in ConfigMaps or Kubernetes Secrets, where each key specifies the path to a flow spec property and the corresponding value is the override.

Flow Configuration ConfigMap Example

Use a ConfigMap to provide non-sensitive flow configuration values for integration flows.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-flow-config
  namespace: foundation-env-default
  labels:
    app.kubernetes.io/component: connect-deploymentoperator
data:
  order-api.maxNumberOfInFlightMessages: "50"
  order-api.processors.http-sender.address: "https://backend.production.example.com"
  order-api.processors.http-sender.timeout: "30000"

Flow Configuration Secret Example

Use a Kubernetes Secret instead of a ConfigMap when configuration values contain sensitive information:

apiVersion: v1
kind: Secret
metadata:
  name: my-flow-config-secrets
  namespace: foundation-env-default
  labels:
    app.kubernetes.io/component: connect-deploymentoperator
stringData:
  order-api.processors.http-sender.address: "https://backend.production.example.com"

Override Key Format

The most common use case is to override flow processor properties. Processor properties are specified using the following key format:

<flow-id>.processors.<processor-id>.<property-name>

You can also override selected top-level flow spec properties, such as the flow control properties maxNumberOfInFlightMessages, maxBufferSize, and maxStashSize.

Fundamental top-level properties, such as id and exchangePattern cannot be overridden.

Connect Secrets

Connect Secrets can be sourced from Kubernetes Secrets and referenced from the ConnectDeploymentSet resource. This enables managing sensitive Connect Secret values using Kubernetes-native secret management.

The Kubernetes Secret contains key-value pairs in the same format as SDK Deployer Secrets, with one additional required entry: secretKey. The secretKey specifies the unique key used to look up the Connect Secret from integration flows.

The resource must have the label app.kubernetes.io/component=connect-deploymentoperator to be processed by the operator.

Connect Secret Example

The following example shows a Kubernetes Secret that defines a Connect Secret referenced by integration flows through the secretKey.

apiVersion: v1
kind: Secret
metadata:
  name: my-connect-secret
  namespace: foundation-env-default
  labels:
    app.kubernetes.io/component: connect-deploymentoperator
stringData:
  secretKey: "my-secret-key"
  userName: "my-username"
  password: "my-password"

Connect Secrets deployed as Kubernetes Secrets take precedence over secrets defined for the same secretKey in the deployment bundle.

Decryption Key Secret

The decryption key used to decrypt Connect secret properties can be sourced from a Kubernetes Secret. This corresponds to the decryption-key SDK Deployer parameter.

The Kubernetes Secret contains a single entry named decryption-key which holds the key used to encrypt secret properties when the deployment bundle was built. The Secret is referenced from the ConnectDeploymentSet resource using the decryptionKeySecretRef property.

The resource must have the label app.kubernetes.io/component=connect-deploymentoperator to be processed by the operator.

apiVersion: v1
kind: Secret
metadata:
  name: my-decryption-key
  namespace: foundation-env-default
  labels:
    app.kubernetes.io/component: connect-deploymentoperator
stringData:
  decryption-key: "my-secret-decryption-key"

Deployment Process

The operator processes a ConnectDeploymentSet by waiting for the deployment bundle and all referenced resources to become available. It then performs the deployment in the following order:

Deletions: Deletes any flows, resources, and secrets specified for deletion in the ConnectDeploymentSet, if they exist.
Connect Service Accounts: Creates any referenced Connect Service Accounts that do not already exist and publishes their details to the configured Kubernetes Secrets.
Connect Secrets: Collects all Connect Secrets from the deployment bundle and any referenced Kubernetes Secrets. Referenced Kubernetes Secrets take precedence over secrets defined in the bundle for the same secretKey. Deploys missing secrets and updates changed ones.
Connect Resources: Collects all Connect Resources from the deployment bundle. Deploys missing resources, and updates changed ones.
Integration Flows: Collects all integration flows from the deployment bundle, applies any referenced configuration overrides, deploys missing flows, and updates changed ones.

After the initial deployment, the operator continues to monitor the ConnectDeploymentSet and all referenced resources for changes. Any change triggers a new reconciliation cycle.

The operator does not automatically delete deployables that are no longer part of the deployment bundle. To remove deployables, specify them explicitly using the flowsToDelete, resourcesToDelete, or secretsToDelete properties on the ConnectDeploymentSet.

Deleting a ConnectDeploymentSet resource stops the operator from watching it and its associated resources. It does not delete the previously deployed Connect deployables.

Observability

The Connect Deployment Operator provides several mechanisms for monitoring the deployment state and diagnosing issues.

Status Conditions

Both the ConnectServiceAccount and ConnectDeploymentSet custom resources expose standard Kubernetes status conditions through the status subresource. These conditions indicate whether a resource has been successfully reconciled and can be observed by tools such as Argo CD or kubectl.

Status:
   Conditions:
     Last Transition Time:    2026-03-02T09:51:30.551235156Z
     Message:                 Successfully reconciled service account my-service-account
     Observed Generation:     1
     Reason:                  Reconciled
     Status:                  True
     Type:                    Ready

Use kubectl to inspect the current status of a resource:

kubectl get csa my-service-account -n foundation-env-default -o yaml
kubectl get cds my-deployment-set -n foundation-env-default -o yaml

Kubernetes Events

The operator publishes Kubernetes events on custom resources to provide human-readable information about errors and important lifecycle transitions. These events help you identify issues without inspecting the operator logs.

Events:
   Type    Reason       Age    From                        Message
   ----    ------       ----   ----                        -------
   Normal  reconciling  6m47s  connect-deploymentoperator  Waiting for secondary resources: (ConfigMap/foundation-env-default/my-flow-override: missing, Secret/foundation-env-default/my-secret: missing)
   Normal  reconciling  4m23s  connect-deploymentoperator  Waiting for secondary resources: (Secret/foundation-env-default/my-secret: missing)
   Normal  reconciling  3m47s  connect-deploymentoperator  Starting deployment
   Normal  deployed     3m46s  connect-deploymentoperator  Deployment succeeded

Use kubectl to view events for a specific resource:

kubectl describe csa my-service-account -n foundation-env-default
kubectl describe cds my-deployment-set -n foundation-env-default

Alternatively, you can list events filtered by the resource:

kubectl get events -n foundation-env-default --field-selector involvedObject.name=my-deployment-set

Operator Logs

For more detailed diagnostic information, review the logs of the Connect Deployment Operator. The operator logs include detailed information about each reconciliation cycle, such as referenced resource resolution, individual deployable deployments, and any errors encountered.

To view operator logs in Kibana, select the logs* data view and filter on kubernetes.container_name: "connect-deploymentoperator".