Version: Beta

Argo CD

Discovery

Discover and manage Argo CD applications, projects, and instances in your Devgraph knowledge graph.

Overview

The Argo CD molecule connects to Argo CD's API to automatically discover GitOps applications and projects. It creates entities for apps, projects, and the Argo instance itself, with automatic linking to GitHub repositories.

Key Features:

Discover Argo CD applications and projects
Track application deployment status
Automatically link applications to GitHub repositories
Support for multi-source applications
Connect projects to Argo instances

Quick Start

providers:
  - name: argo
    type: argo
    every: 300
    config:
      namespace: default
      api_url: https://argocd.example.com/api
      token: ${ARGO_TOKEN}

Configuration

Basic Configuration

providers:
  - name: argocd-prod
    type: argo
    every: 300
    config:
      namespace: production
      api_url: https://argocd.example.com/api
      token: ${ARGO_TOKEN}
      timeout: 30

Configuration Options

Option	Type	Required	Default	Description
`namespace`	string	No	`default`	Namespace for created entities
`api_url`	string	Yes	-	Argo CD API URL (typically `https://argocd.example.com/api`)
`token`	string	Yes	-	Argo CD authentication token
`timeout`	integer	No	`30`	API request timeout in seconds

Authentication

Create Auth Token

argocd login argocd.example.com

Create token for a user:

argocd account generate-token --account <username>

Or for a project-scoped token:

argocd proj role create-token <project> <role>

Use the token in config:

export ARGO_TOKEN="eyJhbGc..."

Token Permissions

The token needs read access to:

Applications (applications:get)
Projects (projects:get)

For service accounts, configure RBAC:

# In argocd-cm ConfigMap
accounts.devgraph: apiKey, login

# In argocd-rbac-cm ConfigMap
p, role:devgraph, applications, get, */*, allow
p, role:devgraph, projects, get, *, allow
g, devgraph, role:devgraph

Entities Created

ArgoInstance

Represents an Argo CD instance.

apiVersion: entities.devgraph.ai/v1
kind: ArgoInstance
metadata:
  name: argo
  namespace: default
spec:
  api_url: https://argocd.example.com/api

One instance entity is created per provider.

ArgoProject

Represents an Argo CD project (AppProject).

apiVersion: entities.devgraph.ai/v1
kind: ArgoProject
metadata:
  name: platform
  namespace: default
spec:
  name: platform

ArgoApplication

Represents an Argo CD application.

apiVersion: entities.devgraph.ai/v1
kind: ArgoApplication
metadata:
  name: backend-api
  namespace: default
spec:
  name: backend-api

Relationships

Application → Project

ArgoApplication --BELONGS_TO--> ArgoProject

Every application belongs to a project.

Project → Instance

ArgoProject --BELONGS_TO--> ArgoInstance

Every project belongs to an Argo instance.

Application → Repository (Field-Selected)

ArgoApplication --USES--> GithubRepository

Applications are automatically linked to their source GitHub repositories using field-selected relations. The molecule matches:

spec.source.repoURL (single source apps)
spec.sources[].repoURL (multi-source apps)

To the spec.url field of GithubRepository entities.

Example:

ArgoApplication(backend-api) --USES--> GithubRepository(myorg/backend-api)
  Matched by: app.spec.source.repoURL == repo.spec.url
  https://github.com/myorg/backend-api

Use Cases

Multi-Environment Tracking

# Production Argo
- name: argo-prod
  type: argo
  config:
    namespace: production
    api_url: https://argocd-prod.example.com/api
    token: ${ARGO_PROD_TOKEN}

# Staging Argo
- name: argo-staging
  type: argo
  config:
    namespace: staging
    api_url: https://argocd-staging.example.com/api
    token: ${ARGO_STAGING_TOKEN}

GitOps Visibility

Combine with GitHub molecule to see the full GitOps pipeline:

GithubRepository → ArgoApplication → KubernetesCluster

Track which repos are deployed and where:

# Query: What repos are deployed by Argo?
MATCH (repo:GithubRepository)<-[:USES]-(app:ArgoApplication)
RETURN repo.metadata.name, app.metadata.name

Deployment Tracking

Link Argo apps to services or teams:

# Use labels to track ownership
entities:
  - kind: Service
    metadata:
      name: backend-api
      labels:
        team: platform

# Query: What apps does platform team own?
MATCH (app:ArgoApplication)-[:IMPLEMENTS]->(service:Service)
WHERE service.metadata.labels.team = "platform"
RETURN app.metadata.name

Troubleshooting

Authentication Errors

Symptom: "401 Unauthorized" or "403 Forbidden"

Solutions:

Verify token is valid and not expired
Check token has required RBAC permissions
Test token manually:

curl -H "Authorization: Bearer $ARGO_TOKEN" \
  https://argocd.example.com/api/v1/applications

Connection Timeout

Symptom: "Connection timeout" errors

Solutions:

Increase timeout value in config: timeout: 60
Check network connectivity to Argo CD
Verify firewall rules allow outbound HTTPS
Check if Argo CD is behind VPN/proxy

Missing Applications

Symptom: Expected applications not appearing

Solutions:

Verify token has access to applications
Check applications exist in Argo CD:

argocd app list

Review molecule logs for errors
Verify RBAC permissions for token

Failed Repository Links

Symptom: Applications not linked to GitHub repos

Solutions:

Ensure GitHub molecule is running and has discovered repos
Check repoURL in Argo app matches spec.url in GitHub repo entity
Verify both molecules use compatible namespaces
Check logs for field-selection warnings

API Version Errors

Symptom: "Unsupported API version" errors

Solutions:

Verify Argo CD version is supported (v2.0+)
Check API URL ends with /api (not /api/v1)
Update Argo CD if using very old version

Performance Tips

Adjust interval: Balance freshness vs. API load
- Fast deployments: every: 60 (1 minute)
- Normal: every: 300 (5 minutes)
- Slow-changing: every: 600 (10 minutes)
Increase timeout: For large Argo instances with many apps
- Default: timeout: 30
- Large instances: timeout: 60 or higher
Use read-only tokens: Minimize permissions for security

Integration Examples

Track Deployment Pipeline

Combine multiple molecules to see full pipeline:

Developer → GitHub Repo → Argo App → Kubernetes

Molecules needed:

GitHub: Discovers repos
Argo CD: Discovers apps and links to repos
LDAP (optional): Discovers developers
Kubernetes (future): Discovers clusters and deployments

Service Catalog

Link Argo apps to service entities:

# In repo's .devgraph.yaml
entities:
  - kind: Service
    metadata:
      name: backend-api
    spec:
      type: rest-api

relations:
  - source:
      kind: ArgoApplication
      name: backend-api
    target:
      kind: Service
      name: backend-api
    relation: DEPLOYS

Team Ownership

Track which teams own which applications:

# Label applications by team
entities:
  - kind: ArgoApplication
    metadata:
      name: backend-api
      labels:
        team: platform
        criticality: high

Query:

MATCH (app:ArgoApplication)
WHERE app.metadata.labels.team = "platform"
RETURN app.metadata.name, app.metadata.labels.criticality

Advanced Configuration

Multiple Argo Instances

Run separate providers for each instance:

providers:
  - name: argo-prod
    type: argo
    config:
      namespace: argo-prod
      api_url: https://argocd-prod.example.com/api
      token: ${ARGO_PROD_TOKEN}

  - name: argo-staging
    type: argo
    config:
      namespace: argo-staging
      api_url: https://argocd-staging.example.com/api
      token: ${ARGO_STAGING_TOKEN}

Cross-Namespace Relations

Link apps to repos in different namespaces:

# GitHub in "default" namespace
- name: github
  config:
    namespace: default

# Argo in "production" namespace
- name: argo
  config:
    namespace: production

# Field-selected relation works across namespaces
# ArgoApplication(production) --USES--> GithubRepository(default)

Custom Timeout for Large Instances

# For Argo instances with 100+ apps
timeout: 120  # 2 minutes

Monitoring

Check molecule logs for health:

# View Argo molecule logs
devgraph logs | grep -i argo

# Check for errors
devgraph logs | grep -i "argo.*error"

# View discovered entities
devgraph logs | grep "ArgoApplication"

Next Steps

Configure GitHub molecule to enable repo linking
Set up GitLab molecule for GitLab repos
Learn about field-selected relations
Explore queries

Argo CD

Overview​

Quick Start​

Configuration​

Basic Configuration​

Configuration Options​

Authentication​

Create Auth Token​

Token Permissions​

Entities Created​

ArgoInstance​

ArgoProject​

ArgoApplication​

Relationships​

Application → Project​

Project → Instance​

Application → Repository (Field-Selected)​

Use Cases​

Multi-Environment Tracking​

GitOps Visibility​

Deployment Tracking​

Troubleshooting​

Authentication Errors​

Connection Timeout​

Missing Applications​

Failed Repository Links​

API Version Errors​

Performance Tips​

Integration Examples​

Track Deployment Pipeline​

Service Catalog​

Team Ownership​

Advanced Configuration​

Multiple Argo Instances​

Cross-Namespace Relations​

Custom Timeout for Large Instances​

Monitoring​

Next Steps​

Overview

Quick Start

Configuration

Basic Configuration

Configuration Options

Authentication

Create Auth Token

Token Permissions

Entities Created

ArgoInstance

ArgoProject

ArgoApplication

Relationships

Application → Project

Project → Instance

Application → Repository (Field-Selected)

Use Cases

Multi-Environment Tracking

GitOps Visibility

Deployment Tracking

Troubleshooting

Authentication Errors

Connection Timeout

Missing Applications

Failed Repository Links

API Version Errors

Performance Tips

Integration Examples

Track Deployment Pipeline

Service Catalog

Team Ownership

Advanced Configuration

Multiple Argo Instances

Cross-Namespace Relations

Custom Timeout for Large Instances

Monitoring

Next Steps