/
Flow Kubernetes agent installation

Flow Kubernetes agent installation

Flow’s Agent is client-side software that sends commit, pull request, and ticket-related metadata to Flow from your git servers. This ensures source code never leaves your environment and you are still able to take advantage of Flow’s insights and metrics. 

The agent is an optional add-on to your Flow plan. Reach out to your Flow contact for information on how to get started with an agent installation.

Agent is used when you set up integrations for the following apps:

If you plan to use the agent with a Flow single tenant environment, there are additional prerequisites you must meet before installing the agent.

Prerequisites

Before using the agent, ensure you have:

  • Helm version 3.

  • Kubernetes version 1.26 or newer.

  • A private docker repository for hosting the agent image.

Storage requirements

Type: Persistence storage (PVC) is required for the project cache. The default storage class is used unless you override it in overrides.yaml

Size: Provide the sum of the total size of all of your git repositories multiplied by at least 1.3 to account for growth.

Permissions/Access

  • You must have kubeAPI access with the cluster admin role for installing in the cluster.

Network requirements:

  • Host needs access to the git repositories and projects.

  • Egress to S3 & the Flow API gateway.

Logging

  • Logs are configured as JSON format and sent to stdout.

Kubernetes installation steps

Create your integrations in Flow

Before downloading the agent assets or registering the image, create all your integrations in Flow. This will ensure your agent config file is populated with the correct information for each integration. If you add additional integrations after you download the config file, you must update it in your system.

  1. In Flow navigate to Settings, then Integrations.

  2. Click Add integration.

  3. Choose your integration provider.

    1. If you select GitHub Cloud or GitHub Enterprise, choose either a hybrid agent connection or a full agent connection.

    2. For all other vendors, select I will use the Git Metadata Collector (Agent) to push data to Flow and standard API methods.

  4. Add the credentials Flow will use to gather project lists and PR/ticket data.

    1. This step does not apply if you select a full agent connection.

  5. Enable the desired services.

  6. Name your integration.

Download and unzip the agent assets

  1. In Flow, navigate to Settings, then Integrations.

  2. Click Download metadata collector assets.

  3. In the Kubernetes tab, click Download Agent config file to download your confit.toml file.

  4. Click Generate download link to get a link to the Agent container image bundle.

  5. Download the bundle using the link, then unzip the bundle.

The unzipped archive will include:

  • A container image.

  • The Helm chart.

  • The overrides.yaml file.

Register the agent image in a private registry

Next you will load the agent image into your private registry. The examples in this article use Docker but you can use your preferred image registry CLI tool.

Docker prerequisites include:

  • Docker or equivalent installed on your local machine

  • Access to your private Docker registry

  • The container image (flow-agent-image.tar)

Log in to your private Docker registry

Use the docker login command to authenticate with your private Docker registry. Replace <registry> with the address of your registry.

docker login <registry>

You will be prompted to enter your username and password for the private registry

Load the image from the flow-agent-image.tar file

Use the docker load command to load the Docker image from the .tar file

docker load -i /path/to/flow-agent-image.tar

Replace /path/to/saved/flow-agent-image.tar with the path to your saved .tar file

Tag the image

After loading the image, tag it with the address of your private registry. You need to tag it in the format <registry>/<image_name>:<tag>. Below is an example for Docker:

docker tag flow-agent-image <registry>/<image_id>:<tag>

  • <image_id>: The ID of the image you just loaded in step 2. You can find it by running docker images.

  • <registry>: The address of your private Docker registry.

  • <image_name>: The name you want to give to your Docker image in the registry (ex flow-agent-image)

  • <tag>: We recommend tagging the agent version you downloaded from Flow (ex v0.8.4)

Push to the registry

Push the image to the private registry

Verify the Image in the registry:

To verify that the image has been successfully uploaded to your private Docker registry, you can log into your registry’s web interface.

Configuring your agent

Add config.toml

  • Add the config.toml that you downloaded to the root of the image bundle directory (alongside the overrides.yaml)

Update config.toml secrets

  • Update api_key with a flow API key

  • Update access_token with your vendor secret 

Example config.toml file:

org_slug = "my-org-1234" cache_directory = "/var/lib/flow/agent/repoCache" progress_notification_frequency = 60 workers = 2 commit_workers = 4 [[integrations]] id = 813815 username = "flow-github-service-account" access_token = "<token>" auth_type = "access_token" vendor_type = "github-enterprise" uri = "https://my-github-enterprise-instance.com" [persistent_data] backend = "flow-agent-api" api_key = "<flow_api_key>" endpoint_url = "https://agent-api.appfireflow.com"

Create a kubernetes secret from the config.toml

  • Create a namespace of your choice (examples use flow)

  • Create a kubernetes secret in your cluster from the config.toml file

Example

kubectl create secret generic flow-agent-config-secret --from-file=path/to/config.toml --namespace flow

Update overrides.yaml

Set the container image

  • repository: Update the repository to point to the agent image added to your internal docker repository in

  • tag: Update the tag to match the image tag

Enable cronjobs

  • For full agent integrations, enable all cronjobs. For hybrid agent integrations, only enable git-agent-ingest.

Example

backend: image: repository: docker.mycompany.com/dev/flow-agent-image tag: v0.8.4 cronjobs: git-ingestion: enabled: true project-discovery: enabled: true api-ingestion: enabled: true

Run helm install

helm install flow-agent ./flow-agent-helm-chart.tgz -f overrides.yaml --namespace flow

The above install command will:

  • Update the helm chart with the values from overrides.yaml

  • Set the cron job(s)

  • Install the agent image on the K8s cluster

Testing the connection to Flow

Test that your connections to Flow and the your integration vendor are working properly

Manually run the flow-project-discovery job: kubectl create job flow-project-discovery-manual-$(date +%s) --from=cronjob/flow-project-discovery

Get the pod name from the list of running commands: kubectl get pods

Check the logs to confirm the job completed successfully: logs -f <pod_name_from_above>

Select repos for import

Confirm that repos are showing in Flow by going to Settings, then Repos. Go to the Available tab. Click import on the repos you want inside Flow

Once repos are selected for import in the Flow UI, the Flow agent will begin sending data according to the scheduled cron jobs. By default this will be roughly every 3 hours.

Upgrading to new versions of the agent

When you want to upgrade your agent version:

  1. Download new image bundle

  2. Follow Kubernetes installation steps to register the agent image in a private registry and complete the config.toml configuration.

  3. run helm upgrade flow-agent ./flow-agent-helm-chart.tgz -f overrides.yaml

Sometimes customers ask us about how to handle multiple integrations:

  • A single agent instance can be used for multiple vendor integrations.

  • Multiple running agents can be used with a single Flow instance as long they don’t point to any of the same Flow integration ids

  • Testing or DR instances of the agent can not be running against the same Flow integration ids simultaneously with the production instance

Adding a new integration

When you want to add a new integration to Flow to ingest new data.

  1. Add the new integration in Flow.

  2. Download a new config.toml file from Flow.

  3. Update the secrets in the config.toml file.

  4. Delete the previous Kubernetes secret from the config.toml.

    1. kubectl delete secret flow-agent-config-secret --namespace flow

  5. Create a new Kubernetes secret from the config.toml.

    1. kubectl create secret generic flow-agent-config-secret --from-file=path/to/config.toml --namespace flow

Updating secrets

When you need to upgrade Kubernetes secrets:

  1. Update secrets in config.toml

  2. Delete the previous Kubernetes secret from the config.toml

    1. kubectl delete secret flow-agent-config-secret --namespace flow

  3. Create a new Kubernetes secret from the config.toml

    1. kubectl create secret generic flow-agent-config-secret --from-file=path/to/config.toml --namespace flow

Run kubectl get cronjobs to verify all cronjobs have been created.

Need support? Create a request with our support team.

Copyright © 2005 - 2026 Appfire | All rights reserved.