Skip to main content

Check out Port for yourself ➜ 

Argo CD

Loading version...

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

Supported resources clusternamespaceprojectapplicationdeployment-historykubernetes-resourcemanaged-resource

Prerequisites​

ArgoCD API token​

To generate a 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, get, */*, allow
          p, role:read-only-role, clusters, get, *, allow
          p, role:read-only-role, projects, get, *, allow
          p, role:read-only-role, repositories, 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: Not sure which method is right for your use case? Check the available installation methods.

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.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: cluster
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .name
          title: .name
          blueprint: '"argocdCluster"'
          properties:
            applicationsCount: .info.applicationsCount
            serverVersion: .serverVersion
            labels: .labels
            updatedAt: .connectionState.attemptedAt
            server: .server
  - kind: cluster
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .name + "-" + .item | tostring
          title: .name + "-" + .item
          blueprint: '"argocdNamespace"'
          relations:
            cluster: .name
      itemsToParse: .namespaces
  - kind: project
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .metadata.name
          title: .metadata.name
          blueprint: '"argocdProject"'
          properties:
            createdAt: .metadata.creationTimestamp
            description: .spec.description
  - kind: application
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .metadata.uid
          title: .metadata.name
          blueprint: '"argocdApplication"'
          properties:
            gitRepo: .spec.source.repoURL
            gitPath: .spec.source.path
            destinationServer: .spec.destination.server
            revision: .status.sync.revision
            targetRevision: .spec.source.targetRevision
            syncStatus: .status.sync.status
            healthStatus: .status.health.status
            createdAt: .metadata.creationTimestamp
            labels: .metadata.labels
            annotations: .metadata.annotations
          relations:
            project: .spec.project
            namespace: .metadata.namespace
            environment:
              combinator: '"and"'
              rules:
              - operator: '"="'
                property: '"argoCluster"'
                value: .spec.destination.server
            cluster:
              combinator: '"and"'
              rules:
              - operator: '"="'
                property: '"server"'
                value: .spec.destination.server
  - kind: application
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .metadata.uid + "-" + (.item.id | tostring)
          title: .metadata.name + "-" + (.item.id | tostring)
          blueprint: '"argocdDeploymentHistory"'
          properties:
            deployedAt: .item.deployedAt
            deployStartedAt: .item.deployStartedAt
            revision: .item.source.repoURL + "/commit/" + .item.revision
            initiatedBy: .item.initiatedBy.username
            repoURL: .item.source.repoURL
            sourcePath: .item.source.path
          relations:
            application: .metadata.uid
            anotherRelation: .item.source.repoURL
      itemsToParse: .status.history // []

Mapping & examples per resource​

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.

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

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 (click to expand)
    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.

Ocean streaming​

The ArgoCD API does not support pagination. This can lead to high memory consumption in large environments when fetching all resources in a single request. To prevent this, you can enable streaming. When enabled, the integration saves the API response to disk and processes it in chunks, which significantly reduces memory usage.

Enable streaming​

Add the streamingEnabled parameter to the helm upgrade command:

--set streamingEnabled=true

Configure streaming​

The streaming process uses a buffer to hold data chunks in memory. A larger buffer can speed up synchronization but also increases memory consumption. By default, the buffer size is 20MB and the chunk size is 64KB.

You can customize these values using the following environment variables:

# Example: set chunk size to 64KB (65536 bytes)
OCEAN__STREAMING__CHUNK_SIZE=65536

# Example: set max buffer size to 10MB (1024 * 1024 * 10)
OCEAN__STREAMING__MAX_BUFFER_SIZE_MB=10485760

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.