---
title: "Flow Kubernetes agent installation"
canonical: "https://support.appfire.com/space/FD/2320106158/Flow%20Kubernetes%20agent%20installation"
format: markdown
---
> Macro (aura-html)

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:
> 📝 
> 📝 - [GitHub Cloud](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802535065)/ [GitHub Enterprise Server](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802305684)
> 📝   - Hybrid Connection
> 📝   - Full Agent Connection
> 📝 - [GitLab Cloud](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802600546)/ [GitLab self-hosted](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802469481)
> 📝   - Hybrid Connection
> 📝   - Full Agent Connection

> ℹ️ 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.