ArgoCD

Port's ArgoCD integration allows you to model ArgoCD resources in your software catalog and ingest data into them.

Overview

This integration allows you to:

• Map and organize your desired ArgoCD resources and their metadata in Port (see supported resources below).
• Watch for ArgoCD object changes (create/update/delete) in real-time, and automatically apply the changes to your software catalog.

Supported Resources

The resources that can be ingested from ArgoCD into Port are listed below. It is possible to reference any field that appears in the API responses linked below in the mapping configuration.

• cluster
• project
• application
• deployment-history
• kubernetes-resource
• managed-resource

Prerequisites

Generate an ArgoCD token

1. Navigate to <serverURL>/settings/accounts/<user>. For example, if you access your ArgoCD at https://localhost:8080, you should navigate to https://localhost:8080/settings/accounts/<user>

2. The user should have apiKey capabilities to allow generating authentication tokens for API access. If you don't have a user created yet, follow the guide on how to create a new ArgoCD user

3. Newly created users may have limited scope to resources by default. For that reason, You will need to configure the RBAC policy for the new user by following this guide

4. Ensure that the policy definition grants enough permission to read resources such as applications, clusters, projects, repositories etc.

5. Under Tokens on your ArgoCD UI, Click Generate New to create a new token for the user or use the CLI:

   argocd account generate-token --account <username>

6. Create an ArgoCD user with readonly permissions

   1. Create an argocd-user.yaml file with the below manifest to create a new user port-ocean-user
   Create user manifest (click to expand)

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-cm
     namespace: argocd
     labels:
       app.kubernetes.io/name: argocd-cm
       app.kubernetes.io/part-of: argocd
   data:
     # add an additional local user with apiKey and login capabilities
     #   apiKey - allows generating API keys
     #   login - allows to login using UI
     accounts.port-ocean-user: apiKey, login
     accounts.port-ocean-user.enabled: "true"
   2. Apply the manifest with kubectl to create the user:

   kubectl apply -f argocd-user.yaml
   3. Grant read only RBAC policy to the new user using the below manifest file (argocd-rbac-cm.yaml)
   RBAC policy to grant readonly role to the new user (click to expand)

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-rbac-cm
     namespace: argocd
   data:
     policy.default: role:readonly
     policy.csv: |
       p, role:read-only-role, applications, *, */*, allow
       p, role:read-only-role, clusters, get, *, allow
       p, role:read-only-role, repositories, get, *, allow
       p, role:read-only-role, projects, get, *, allow
       p, role:read-only-role, logs, get, *, allow
   
       g, port-ocean-user, role:read-only-role
   4. Apply the argocd-rbac-cm.yaml manifest with kubectl:

   kubectl apply -f argocd-rbac-cm.yaml
   5. Go to your ArgoCD UI to generate a new token for the user or use the CLI

   argocd account generate-token --account <username>

Setup

Choose one of the following installation methods:

Real-time (self-hosted)

Using this installation method means that the integration will be able to update Port in real time using webhooks.

Prerequisites

To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to.

Please make sure that you have kubectl and helm installed on your machine, and that your kubectl CLI is connected to the Kubernetes cluster where you plan to install the integration.

Troubleshooting

If you are having trouble installing this integration, please refer to these troubleshooting steps.

For details about the available parameters for the installation, see the table below.

Helm

To install the integration using Helm:

1. Go to the Argocd data source page in your portal.

2. Select the Real-time and always on method:

   

3. A helm command will be displayed, with default values already filled out (e.g. your Port cliend ID, client secret, etc).
   Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
• If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

ArgoCD

To install the integration using ArgoCD:

1. Create a values.yaml file in argocd/my-ocean-argocd-integration in your git repository with the content:

Variable Replacement

Remember to replace the placeholders for TOKEN and SERVER_URL, which represents your ArgoCD API token and server url respectively.

initializePortResources: true
scheduledResyncInterval: 120
integration:
  identifier: my-ocean-argocd-integration
  type: argocd
  eventListener:
    type: POLLING
  config:
    serverUrl: SERVER_URL
  secrets:
    token: TOKEN

2. Install the my-ocean-argocd-integration ArgoCD Application by creating the following my-ocean-argocd-integration.yaml manifest:

Variable Replacement

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID YOUR_PORT_CLIENT_SECRET and YOUR_GIT_REPO_URL.

Multiple sources ArgoCD documentation can be found here.

ArgoCD Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-ocean-argocd-integration
  namespace: argocd
spec:
  destination:
    namespace: my-ocean-argocd-integration
    server: https://kubernetes.default.svc
  project: default
  sources:
  - repoURL: 'https://port-labs.github.io/helm-charts/'
    chart: port-ocean
    targetRevision: 0.1.18
    helm:
      valueFiles:
      - $values/argocd/my-ocean-argocd-integration/values.yaml
      parameters:
        - name: port.clientId
          value: YOUR_PORT_CLIENT_ID
        - name: port.clientSecret
          value: YOUR_PORT_CLIENT_SECRET
        - name: port.baseUrl
          value: https://api.getport.io
  - repoURL: YOUR_GIT_REPO_URL
    targetRevision: main
    ref: values
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
• If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

1. Apply your application manifest with kubectl:

kubectl apply -f my-ocean-argocd-integration.yaml

This table summarizes the available parameters for the installation. Note the parameters specific to this integration, they are last in the table.

Parameter	Description	Required
port.clientId	Your port client id	✅
port.clientSecret	Your port client secret	✅
port.baseUrl	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.io for US	✅
initializePortResources	Default true, When set to true the integration will create default blueprints and the port App config Mapping	❌
sendRawDataExamples	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true	❌
integration.identifier	Change the identifier to describe your integration	✅
integration.type	The integration type	✅
integration.eventListener.type	The event listener type	✅
integration.secrets.token	The ArgoCD API token, docs can be found here	✅
integration.config.serverUrl	The ArgoCD server url	✅
integration.config.ignoreServerError	Whether to ignore server errors when fetching data from ArgoCD. The default value is false meaning the integration will raise exceptions and fail the resync event	❌
scheduledResyncInterval	The number of minutes between each resync	❌

Scheduled (CI)

This workflow/pipeline will run the ArgoCD integration once and then exit, this is useful for scheduled ingestion of data.

Real-time updates

If you want the integration to update Port in real time using webhooks you should use the Real-time (self-hosted) installation option

GitHub

Make sure to configure the following Github Secrets:

Parameter	Description	Required
OCEAN__INTEGRATION__CONFIG__TOKEN	The ArgoCD API token	✅
OCEAN__INTEGRATION__CONFIG__SERVER_URL	The ArgoCD server URL	✅
OCEAN__INTEGRATION__CONFIG__IGNORE_SERVER_ERROR	Whether to ignore server errors when fetching data from ArgoCD. The default value is false meaning the integration will raise exceptions and fail the resync event	❌
OCEAN__INITIALIZE_PORT_RESOURCES	Default true, When set to false the integration will not create default blueprints and the port App config Mapping	❌
OCEAN__INTEGRATION__IDENTIFIER	Change the identifier to describe your integration, if not set will use the default one	❌
OCEAN__PORT__CLIENT_ID	Your port client id	✅
OCEAN__PORT__CLIENT_SECRET	Your port client secret	✅
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.io for US	✅
OCEAN__SEND_RAW_DATA_EXAMPLES	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true	❌

Here is an example for argocd-integration.yml workflow file:

name: ArgoCD Exporter Workflow

on:
  workflow_dispatch:
  schedule:
    - cron: '0 */1 * * *' # Determines the scheduled interval for this workflow. This example runs every hour.

jobs:
  run-integration:
    runs-on: ubuntu-latest
    timeout-minutes: 30 # Set a time limit for the job

    steps:
      - uses: port-labs/ocean-sail@v1
        with:
          type: 'argocd'
          port_client_id: ${{ secrets.OCEAN__PORT__CLIENT_ID }}
          port_client_secret: ${{ secrets.OCEAN__PORT__CLIENT_SECRET }}
          port_base_url: https://api.getport.io
          config: |
            token: ${{ secrets.OCEAN__INTEGRATION__CONFIG__TOKEN }}
            server_url: ${{ OCEAN__INTEGRATION__CONFIG__SERVER_URL }}
            ignore_server_error: false

Jenkins

tip

Your Jenkins agent should be able to run docker commands.

Make sure to configure the following Jenkins Credentials of Secret Text type:

Parameter	Description	Required
OCEAN__INTEGRATION__CONFIG__TOKEN	The ArgoCD API token	✅
OCEAN__INTEGRATION__CONFIG__SERVER_URL	The ArgoCD server URL	✅
OCEAN__INTEGRATION__CONFIG__IGNORE_SERVER_ERROR	Whether to ignore server errors when fetching data from ArgoCD. The default value is false meaning the integration will raise exceptions and fail the resync event	❌
OCEAN__INITIALIZE_PORT_RESOURCES	Default true, When set to false the integration will not create default blueprints and the port App config Mapping	❌
OCEAN__INTEGRATION__IDENTIFIER	Change the identifier to describe your integration, if not set will use the default one	❌
OCEAN__SEND_RAW_DATA_EXAMPLES	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true	❌
OCEAN__PORT__CLIENT_ID	Your port client id	✅
OCEAN__PORT__CLIENT_SECRET	Your port client secret	✅
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.io for US	✅

Here is an example for Jenkinsfile groovy pipeline file:

pipeline {
    agent any

    stages {
        stage('Run ArgoCD Integration') {
            steps {
                script {
                    withCredentials([
                        string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__TOKEN'),
                        string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__SERVER_URL', variable: 'OCEAN__INTEGRATION__CONFIG__SERVER_URL'),
                        string(credentialsId: 'OCEAN__PORT__CLIENT_ID', variable: 'OCEAN__PORT__CLIENT_ID'),
                        string(credentialsId: 'OCEAN__PORT__CLIENT_SECRET', variable: 'OCEAN__PORT__CLIENT_SECRET'),
                    ]) {
                        sh('''
                            #Set Docker image and run the container
                            integration_type="argocd"
                            version="latest"
                            image_name="ghcr.io/port-labs/port-ocean-${integration_type}:${version}"
                            docker run -i --rm --platform=linux/amd64 \
                                -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
                                -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
                                -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
                                -e OCEAN__INTEGRATION__CONFIG__TOKEN=$OCEAN__INTEGRATION__CONFIG__TOKEN \
                                -e OCEAN__INTEGRATION__CONFIG__SERVER_URL=$OCEAN__INTEGRATION__CONFIG__SERVER_URL \
                                -e OCEAN__INTEGRATION__CONFIG__IGNORE_SERVER_ERROR=false \
                                -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \
                                -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \
                                -e OCEAN__PORT__BASE_URL='https://api.getport.io' \
                                $image_name

                            exit $?
                        ''')
                    }
                }
            }
        }
    }
}

GitLab

Make sure to configure the following GitLab variables:

Parameter	Description	Required
OCEAN__INTEGRATION__CONFIG__TOKEN	The ArgoCD API token	✅
OCEAN__INTEGRATION__CONFIG__SERVER_URL	The ArgoCD server URL	✅
OCEAN__INTEGRATION__CONFIG__IGNORE_SERVER_ERROR	Whether to ignore server errors when fetching data from ArgoCD. The default value is false meaning the integration will raise exceptions and fail the resync event	❌
OCEAN__INITIALIZE_PORT_RESOURCES	Default true, When set to false the integration will not create default blueprints and the port App config Mapping	❌
OCEAN__SEND_RAW_DATA_EXAMPLES	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true	❌
OCEAN__INTEGRATION__IDENTIFIER	Change the identifier to describe your integration, if not set will use the default one	❌
OCEAN__PORT__CLIENT_ID	Your port client id	✅
OCEAN__PORT__CLIENT_SECRET	Your port client secret	✅
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.io for US	✅

Here is an example for .gitlab-ci.yml pipeline file:

default:
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind
  before_script:
    - docker info
    
variables:
  INTEGRATION_TYPE: argocd
  VERSION: latest

stages:
  - ingest

ingest_data:
  stage: ingest
  variables:
    IMAGE_NAME: ghcr.io/port-labs/port-ocean-$INTEGRATION_TYPE:$VERSION
  script:
    - |
      docker run -i --rm --platform=linux/amd64 \
        -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
        -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
        -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
        -e OCEAN__INTEGRATION__CONFIG__TOKEN=$OCEAN__INTEGRATION__CONFIG__TOKEN \
        -e OCEAN__INTEGRATION__CONFIG__SERVER_URL=$OCEAN__INTEGRATION__CONFIG__SERVER_URL \
        -e OCEAN__INTEGRATION__CONFIG__IGNORE_SERVER_ERROR=false \
        -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \
        -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \
        -e OCEAN__PORT__BASE_URL='https://api.getport.io' \
        $IMAGE_NAME

  rules: # Run only when changes are made to the main branch
    - if: '$CI_COMMIT_BRANCH == "main"'

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
• If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Capabilities

Configure real-time updates

Currently, the ArgoCD REST API lacks support for programmatic webhook creation. To set up a webhook configuration in ArgoCD for sending notifications to the Ocean integration, follow these steps:

1. Install ArgoCD notifications manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml

2. Install ArgoCD triggers and templates manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

3. Use kubectl to connect to the Kubernetes cluster where your ArgoCD instance is deployed;

kubectl config use-context <your-cluster-context>

4. Set the current namespace to your ArgoCD namespace, use the following command;

kubectl config set-context --current --namespace=<your-namespace>

5. Create a YAML file (e.g. argocd-webhook-config.yaml) that configures the webhook notification service. The example below shows how to set up a webhook to send real-time events whenever ArgoCD applications are updated. The YAML file includes the following components:

   1. Notification service definition;
   2. Template for the webhook message body;
   3. Trigger definitions;
   4. Subscriptions to the notifications.

   Here's an example YAML. Make sure to replace <WEBHOOK_URL> with the actual URL of the ingress or service where the ocean integration will be deployed. By default, incoming webhook events are sent to /integration/webhook path in Ocean so do not replace the path parameter.

   webhook manifest file

   apiVersion: v1
   kind: ConfigMap
   metadata:
   name: argocd-notifications-cm
   data:
   trigger.on-sync-operation-change: |
     - description: Application syncing has updated
     send:
     - app-status-change
     when: app.status.operationState.phase in ['Error', 'Failed', 'Succeeded', 'Running']
   trigger.on-deployed: |
     - description: Application is synced and healthy
     send:
     - app-status-change
     when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
   trigger.on-health-degraded: |
     - description: Application has degraded
     send:
     - app-status-change
     when: app.status.health.status == 'Degraded'
   service.webhook.port-ocean: |
     url: <WEBHOOK_URL>
     headers:
     - name: Content-Type
     value: application/json
   template.app-status-change: |
     webhook:
     port-ocean:
         method: POST
         path: /integration/webhook
         body: |
         {
             "action": "upsert",
             "application_name": "{{.app.metadata.name}}"
         }
   subscriptions: |
     - recipients:
     - port-ocean
     triggers:
     - on-deployed
     - on-health-degraded
     - on-sync-operation-change

6. Use kubectl to apply the YAML file to your cluster. Run the following command, replacing <your-namespace> with your ArgoCD namespace and <path-to-yaml-file> with the actual path to your YAML file:

kubectl apply -n <your-namespace> -f <path-to-yaml-file>

This command deploys the webhook notification configuration to your ArgoCD notification configmap (argocd-notifications-cm), allowing Ocean to receive real-time events.

Examples

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page. Find the integration in the list of data sources and click on it to open the playground.

Examples of blueprints and the relevant integration configurations can be found on the argocd examples page

Relevant Guides

For relevant guides and examples, see the guides section.

Alternative installation via webhook

While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from ArgoCD. If so, use the following instructions:

Webhook installation (click to expand)

In this example you are going to create a webhook integration between ArgoCD and Port, which will ingest application entities and map them to your ArgoCD projects.

Port configuration

Create the following blueprint definition:

Project blueprint

{
  "identifier": "argocdProject",
  "description": "This blueprint represents an ArgoCD Project",
  "title": "ArgoCD Project",
  "icon": "Argo",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "description": "Project description",
        "type": "string",
        "icon": "DefaultProperty"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Application blueprint

{
  "identifier": "argocdApplication",
  "description": "This blueprint represents an ArgoCD Application",
  "title": "ArgoCD Application",
  "icon": "Argo",
  "schema": {
    "properties": {
      "gitRepo": {
        "type": "string",
        "format": "url",
        "icon": "Git",
        "title": "Repository URL",
        "description": "The URL of the Git repository containing the application source code"
      },
      "gitPath": {
        "type": "string",
        "title": "Path",
        "description": "The path within the Git repository where the application manifests are located"
      },
      "destinationServer": {
        "type": "string",
        "title": "Destination Server",
        "format": "url"
      },
      "namespace": {
        "type": "string",
        "title": "Namespace"
      },
      "syncStatus": {
        "type": "string",
        "title": "Sync Status",
        "enum": ["Synced", "OutOfSync", "Unknown"],
        "enumColors": {
          "Synced": "green",
          "OutOfSync": "red",
          "Unknown": "lightGray"
        },
        "description": "The sync status of the application"
      },
      "healthStatus": {
        "type": "string",
        "title": "Health Status",
        "enum": [
          "Healthy",
          "Missing",
          "Suspended",
          "Degraded",
          "Progressing",
          "Unknown"
        ],
        "enumColors": {
          "Healthy": "green",
          "Missing": "yellow",
          "Suspended": "purple",
          "Degraded": "red",
          "Progressing": "blue",
          "Unknown": "lightGray"
        },
        "description": "The health status of the application"
      },
      "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "argocdProject",
      "required": false,
      "many": false
    }
  }
}

Create the following webhook configuration using Port UI

Application webhook configuration

1. Basic details tab - fill the following details:

   1. Title : ArgoCD Application Mapper;
   2. Identifier : argocd_application_mapper;
   3. Description : A webhook configuration to map ArgoCD applications to Port;
   4. Icon : Argo;

2. Integration configuration tab - fill the following JQ mapping:

   [
     {
       "blueprint": "argocdApplication",
       "filter": "true",
       "entity": {
         "identifier": ".body.uid | tostring",
         "title": ".body.name | tostring",
         "properties": {
           "gitRepo": ".body.git_repo",
           "gitPath": ".body.git_path",
           "destinationServer": ".body.destination_server",
           "namespace": ".body.namespace",
           "syncStatus": ".body.sync_status",
           "healthStatus": ".body.health_status",
           "createdAt": ".body.created_at"
         },
         "relations": {
           "project": ".body.project"
         }
       }
     }
   ]

3. Click Save at the bottom of the page.

Create a webhook in ArgoCD

To set up a webhook configuration in ArgoCD for sending notifications to Port, follow these steps:

Prerequisite

1. You have access to a Kubernetes cluster where ArgoCD is deployed.
2. You have kubectl installed and configured to access your cluster.

Steps

1. Install ArgoCD notifications manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml

2. Install ArgoCD triggers and templates manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

3. Use kubectl to connect to the Kubernetes cluster where your ArgoCD instance is deployed;

kubectl config use-context <your-cluster-context>

4. Set the current namespace to your ArgoCD namespace, use the following command;

kubectl config set-context --current --namespace=<your-namespace>

5. Create a YAML file (e.g. argocd-webhook-config.yaml) that configures the webhook notification service. The example below shows how to set up a webhook to send real-time events whenever ArgoCD applications are updated. The YAML file includes the following components:

   1. Notification service definition;
   2. Template for the webhook message body;
   3. Trigger definitions;
   4. Subscriptions to the notifications.

   Here's an example YAML. Make sure to replace <YOUR_WEBHOOK_URL> with the value of url key you received after creating the webhook configuration.

   webhook manifest file

   apiVersion: v1
   kind: ConfigMap
   metadata:
   name: argocd-notifications-cm
   data:
   trigger.on-sync-operation-change: |
     - description: Application syncing has updated
     send:
     - app-status-change
     when: app.status.operationState.phase in ['Error', 'Failed', 'Succeeded', 'Running']
   trigger.on-deployed: |
     - description: Application is synced and healthy
     send:
     - app-status-change
     when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
   trigger.on-health-degraded: |
     - description: Application has degraded
     send:
     - app-status-change
     when: app.status.health.status == 'Degraded'
   service.webhook.port-webhook: |
     url: <YOUR_WEBHOOK_URL>
     headers:
     - name: Content-Type
     value: application/json
   template.app-status-change: |
     webhook:
     port-webhook:
         method: POST
         body: |
         {
             "uid": "{{.app.metadata.uid}}",
             "name": "{{.app.metadata.name}}",
             "namespace": "{{.app.metadata.namespace}}",
             "sync_status": "{{.app.status.sync.status}}",
             "health_status": "{{.app.status.health.status}}",
             "git_repo": "{{.app.spec.source.repoURL}}",
             "git_path": "{{.app.spec.source.path}}",
             "destination_server": "{{.app.spec.destination.server}}",
             "created_at": "{{.app.metadata.creationTimestamp}}",
             "project": "{{.app.spec.project}}"
         }
   subscriptions: |
     - recipients:
     - port-webhook
     triggers:
     - on-deployed
     - on-health-degraded
     - on-sync-operation-change

6. Use kubectl to apply the YAML file to your cluster. Run the following command, replacing <your-namespace> with your ArgoCD namespace and <path-to-yaml-file> with the actual path to your YAML file:

kubectl apply -n <your-namespace> -f <path-to-yaml-file>

This command deploys the webhook notification configuration to your ArgoCD notification configmap (argocd-notifications-cm), allowing Port to receive real-time events.

Done! any change that happens to your applications in ArgoCD will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.

Argocd Events

In this example you are going to create a webhook integration between ArgoCD and Port, which will ingest all events entities and map them to your ArgoCD applications.

Port configuration

Create the following blueprint definition:

Events blueprint

{
  "identifier": "argocdEvent",
  "description": "This blueprint represents ArgoCD events",
  "title": "ArgoCD Events",
  "icon": "Argo",
  "schema": {
    "properties": {
      "event": {
        "type": "string",
        "title": "Event Name"
      },
      "namespace": {
        "type": "string",
        "title": "Namespace"
      },
      "description": {
        "type": "string",
        "title": "Description"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "application": {
      "title": "Application",
      "target": "argocdApplication",
      "required": false,
      "many": false
    }
  }
}

Create the following webhook configuration using Port UI

Application webhook configuration

1. Basic details tab - fill the following details:

   1. Title : ArgoCD Event Mapper;
   2. Identifier : argocd_event_mapper;
   3. Description : A webhook configuration to map ArgoCD events to Port;
   4. Icon : Argo;

2. Integration configuration tab - fill the following JQ mapping:

   [
     {
       "blueprint": "argocdEvent",
       "filter": "true",
       "entity": {
         "identifier": ".body.app_name + \"-\" + .body.event_name | tostring",
         "title": ".body.event_name | tostring",
         "properties": {
           "event": ".body.event_name",
           "namespace": ".body.namespace",
           "description": ".body.description"
         },
         "relations": {
           "application": ".body.uid"
         }
       }
     }
   ]

3. Click Save at the bottom of the page.

Create a webhook in ArgoCD

To set up a webhook configuration in ArgoCD for sending notifications to Port, follow these steps:

Prerequisite

1. You have access to a Kubernetes cluster where ArgoCD is deployed.
2. You have kubectl installed and configured to access your cluster.

Steps

1. Install ArgoCD notifications manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml

2. Install ArgoCD triggers and templates manifest;

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

3. Use kubectl to connect to the Kubernetes cluster where your ArgoCD instance is deployed;

kubectl config use-context <your-cluster-context>

4. Set the current namespace to your ArgoCD namespace, use the following command;

kubectl config set-context --current --namespace=<your-namespace>

5. Create a YAML file (e.g. argocd-events-config.yaml) that configures the webhook notification service. The example below shows how to set up a webhook to send real-time events from ArgoCD. The YAML file includes the following components:

   1. Notification service definition;
   2. Template for the webhook message body;
   3. Trigger definitions;
   4. Subscriptions to the notifications.

   Here's an example YAML. Make sure to replace <YOUR_WEBHOOK_URL> with the value of url key you received after creating the webhook configuration.

   event manifest file

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-notifications-cm
   data:
     trigger.on-created: |
       - description: Application is created
         send:
         - app-created
         when: true
         oncePer: app.metadata.name
     trigger.on-sync-running: |
       - description: Application is being synced
         send:
         - app-sync-running
         when: app.status.operationState.phase in ['Running']
     trigger.on-sync-succeeded: |
       - description: Application syncing has succeeded
         send:
         - app-sync-succeeded
         when: app.status.operationState.phase in ['Succeeded']
     trigger.on-sync-failed: |
       - description: Application syncing has failed
         send:
         - app-sync-failed
         when: app.status.operationState.phase in ['Error', 'Failed']
     trigger.on-sync-status-unknown: |
       - description: Application status is Unknown
         send:
         - app-sync-status-unknown
         when: app.status.sync.status == 'Unknown'
     trigger.on-deployed: |
       - description: Application is synced and healthy
         send:
         - app-deployed
         when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
     trigger.on-health-degraded: |
       - description: Application has degraded
         send:
         - app-health-degraded
         when: app.status.health.status == 'Degraded'
     trigger.on-deleted: |
       - description: Application is deleted
         send:
         - app-deleted
         when: app.metadata.deletionTimestamp != nil
         oncePer: app.metadata.name
     service.webhook.port-webhook: |
       url: YOUR_WEBHOOK_URL
       headers:
       - name: Content-Type
         value: application/json
     template.app-created: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-created",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application is created"
             }
     template.app-sync-succeeded: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-sync-succeeded",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application syncing has succeeded"
             }
     template.app-sync-running: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-sync-running",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application is being synced"
             }
     template.app-sync-failed: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-sync-failed",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application syncing has failed"
             }
     template.app-health-degraded: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-health-degraded",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application has degraded"
             }
     template.app-deployed: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-deployed",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application is synced healthy"
             }
     template.app-sync-status-unknown: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-sync-status-unknown",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application status is Unknown"
             }
     template.app-deleted: |
       webhook:
         port-webhook:
           method: POST
           body: |
             {
               "uid": "{{.app.metadata.uid}}",
               "event_name": "on-deleted",
               "app_name": "{{.app.metadata.name}}",
               "namespace": "{{.app.metadata.namespace}}",
               "description": "Application  deleted"
             }
     subscriptions: |
       - recipients:
           - port-webhook
         triggers:
           - on-created
           - on-deployed
           - on-health-degraded
           - on-sync-failed
           - on-sync-status-unknown
           - on-sync-succeeded
           - on-sync-running
           - on-deleted

6. Use kubectl to apply the YAML file to your cluster. Run the following command, replacing <your-namespace> with your ArgoCD namespace and <path-to-yaml-file> with the actual path to your YAML file:

kubectl apply -n <your-namespace> -f <path-to-yaml-file>

This command deploys the webhook notification configuration to your ArgoCD notification configmap (argocd-notifications-cm), allowing Port to receive real-time events.

Done! any change that happens to your applications in ArgoCD will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.