Skip to main content

Visualize your services' Kubernetes runtime using ArgoCD

This guide takes 10 minutes to complete, and aims to demonstrate the value of Port's integration with ArgoCD.

  • This guide assumes you have a Port account and that you have finished the onboarding process. We will use the Service blueprint that was created during the onboarding process.
  • You will need an accessible k8s cluster. If you don't have one, here is how to quickly set-up a minikube cluster.
  • Helm - required to install Port's ArgoCD integration.

The goal of this guide

In this guide we will model and visualize our services' Kubernetes resources (via ArgoCD).

After completing it, you will get a sense of how it can benefit different personas in your organization:

  • Developers will be able to easily view the health and status of their services' K8s runtime.
  • Platform engineers will be able to create custom views and visualizations for different stakeholders in the organization.
  • Platform engineers will be able to set, maintain and track standards for K8s resources.
  • R&D managers will be able to track any data about services' K8s resources, using tailor-made views and dashboards.

Install Port's ArgoCD integration

  1. Go to your data sources page, click on + Data source, find the Kubernetes Stack category and select ArgoCD.

  2. Follow the installation command for your preferred installation method:

To install the integration using Helm, run the following command:

Variable replacement

Remember to replace the following placeholders with your own values:

  • YOUR_PORT_CLIENT_ID - Your Port client ID
  • YOUR_PORT_CLIENT_SECRET - Your Port client secret
  • YOUR_ARGOCD_TOKEN - Your ArgoCD API token. Ensure that the token has sufficient permissions to read ArgoCD resources. You can configure the RBAC policy for the token user by following this guide
  • YOUR_ARGOCD_SERVER_URL - The server url of your ArgoCD instance
# The following script will install an Ocean integration in your K8s cluster using helm
helm repo add --force-update port-labs
helm upgrade --install argocd port-labs/port-ocean \
--set port.clientId="YOUR_PORT_CLIENT_ID" \
--set port.clientSecret="YOUR_PORT_CLIENT_SECRET" \
--set port.baseUrl="" \
--set initializePortResources=true \
--set integration.identifier="argocd" \
--set integration.type="argocd" \
--set integration.eventListener.type="POLLING" \
--set integration.secrets.token="YOUR_ARGOCD_TOKEN" \
--set integration.config.serverUrl="YOUR_ARGOCD_SERVER_URL"

What does the integration do?

After installation, the integration will:

  1. Create blueprints in your Builder (as defined here) that represent ArgoCD resources:

  1. Create entities in your Software catalog. You will see a new page for each blueprint containing your resources, filled with data from your Kubernetes cluster (according to the default mapping that is defined here):

  1. Create a dashboard in your software catalog that provides you with some visual views of the data ingested from your K8s cluster.

  2. Listen to changes in your ArgoCD resources and update your entities accordingly.

Define the connection between workloads and services

Now that we have our blueprints set up, we want to model the logical connection between our ArgoCD resources and the Service blueprint that already exists in our builder. This will grant us some helpful context in our software catalog, allowing us to see relevant ArgoCD application/s in a Service's context, and their corresponding data.

In this guide we will create a relation named Service for the Running Service blueprint, which represents the service a workload is running.

  1. Go to your Builder, expand the Running Service blueprint, and click on New relation.

  2. Fill out the form like this, then click Create:

Map your workloads to their services

You may have noticed that the service relation is empty for all of our Running Services. This is because we haven't specified which Running service belongs to which service. This can be done manually, or via mapping by using a convention of your choice.

In this guide we will use the following convention:
An Argo application with a label in the form of portService: <service-identifier> will automatically be assigned to a service with that identifier.

For example, an ArgoCD application with the label portService: awesomeService will be assigned to a service with the identifier awesomeService.

To achieve this, we need to update the ArgoCD integration's mapping configuration:

  1. Go to your data sources page, find the ArgoCD exporter card, click on it and you will see a YAML editor showing the current configuration.
    Add the following block to the mapping configuration and click Resync:
  - kind: application
query: 'true'
identifier: .metadata.labels.portService
blueprint: '"service"'
properties: {}
- kind: application
query: "true"
identifier: .metadata.uid
blueprint: '"argocdApplication"'
properties: {}
service: .metadata.labels.portService

  1. Go to the services page of your software catalog. Click on the Service for which you created the deployment. At the bottom of the page, you will see the Running Services related to this service, along with all of their data:

Visualize data from your Kubernetes environment

We now have a lot of data about our Argo applications, and a dashboard that visualizes it in ways that will benefit the routines of our developers and managers. Since we connected our ArgoCD application(Running service) blueprint to our Service blueprint, we can now access some of the application's data directly in the context of the service.
Let's see an example of how we can add useful visualizations to our dashboard:

Show all "degraded" workloads of AwesomeService service belonging to a specific team

  1. Go to your ArgoCD dashboard, click on the + Add button in the top right corner, then select Table.

  2. Fill the form out like this, then click Save:

  3. In your new table, click on the Filter icon, then on + Add new filter.
    Add three filters by filling out the fields like this:

  4. Your table should now display all services belonging to your specified team, whose Health is Degraded:

Possible daily routine integrations

  • Send a slack message in the R&D channel to let everyone know that a new deployment was created.
  • Notify Devops engineers when a service's availability drops.
  • Send a weekly/monthly report to R&D managers displaying the health of services' production runtime.


Kubernetes is a complex environment that requires high-quality observability. Port's ArgoCD integration allows you to easily model and visualize your ArgoCD & Kubernetes resources, and integrate them into your daily routine.
Customize your views to display the data that matters to you, grouped or filtered by teams, namespaces, or any other criteria.