diff --git a/docs/guides/all/visualize-service-argocd-runtime.md b/docs/guides/all/visualize-service-argocd-runtime.md
index 4528db3b3..3a19b87dc 100644
--- a/docs/guides/all/visualize-service-argocd-runtime.md
+++ b/docs/guides/all/visualize-service-argocd-runtime.md
@@ -1,5 +1,4 @@
---
-sidebar_position: 5
displayed_sidebar: null
description: Learn how to visualize ArgoCD service runtime in Port, enhancing monitoring and management of your Kubernetes applications.
---
@@ -8,33 +7,31 @@ import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
import PortTooltip from "/src/components/tooltip/tooltip.jsx"
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# 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.
+Port’s ArgoCD integration allows you to model and visualize your Kubernetes deployments managed by ArgoCD, directly in Port.
+This guide will help you set up the integration and visualize your services' Kubernetes runtime.
-:::info Prerequisites
-- This guide assumes you have a Port account and that you have finished the [onboarding process](/quickstart). 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](https://minikube.sigs.k8s.io/docs/start/).
-- [Helm](https://helm.sh/docs/intro/install/) - required to install Port's ArgoCD integration.
+## Common use cases
-:::
+- Developers can easily view the health and status of their services' K8s runtime.
+- Platform engineers can create custom views and visualizations for different stakeholders in the organization.
+- Platform engineers can set, maintain and track standards for K8s resources.
+- R&D managers can track any data about services' K8s resources, using tailor-made views and dashboards.
-
-
-### The goal of this guide
-
-In this guide we will model and visualize our services' Kubernetes resources (via ArgoCD).
+## Prerequisites
+- The [Git Integration](/build-your-software-catalog/sync-data-to-catalog/git/) that is relevant for you needs to be installed.
+- You will need an accessible k8s cluster. If you don't have one, here is how to quickly set-up a [minikube cluster](https://minikube.sigs.k8s.io/docs/start/).
+- [Helm](https://helm.sh/docs/intro/install/) - required to install Port's ArgoCD integration.
-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.
+## Set up data model
-
+ArgoCD integration creates new **blueprints** (e.g., `argocdApplication`) that reflect ArgoCD resources, and it updates Port with live changes from your ArgoCD server.
### Install Port's ArgoCD integration
@@ -45,33 +42,12 @@ After completing it, you will get a sense of how it can benefit different person
-To install the integration using Helm, run the following command:
-
- :::tip Variable replacement
- Remember to replace the following placeholders with your own values:
- - `YOUR_PORT_CLIENT_ID` - Your [Port client ID](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)
- - `YOUR_PORT_CLIENT_SECRET` - Your [Port client secret](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)
- - `YOUR_ARGOCD_TOKEN` - Your [ArgoCD API token](https://argo-cd.readthedocs.io/en/stable/developer-guide/api-docs/#authorization). 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](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)
- - `YOUR_ARGOCD_SERVER_URL` - The server url of your ArgoCD instance
- :::
-
-```bash showLineNumbers
-# The following script will install an Ocean integration in your K8s cluster using helm
-helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
-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="https://api.getport.io" \
- --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"
-```
+
+
+
@@ -79,83 +55,83 @@ To install the integration using ArgoCD, follow these steps:
1. Create a `values.yaml` file in `argocd/my-ocean-argocd-integration` in your git repository with the content:
-:::tip Variable Replacement
-Remember to replace the placeholders for `TOKEN` and `SERVER_URL`, which represents your ArgoCD API token and server url respectively. 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](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)
-:::
-
-```yaml showLineNumbers
-initializePortResources: true
-scheduledResyncInterval: 120
-integration:
- identifier: my-ocean-argocd-integration
- type: argocd
- eventListener:
- type: POLLING
- config:
- // highlight-next-line
- serverUrl: SERVER_URL
- secrets:
- // highlight-next-line
- token: TOKEN
-```
-
+ :::tip Variable Replacement
+ Remember to replace the placeholders for `TOKEN` and `SERVER_URL`, which represents your ArgoCD API token and server url respectively. 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](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)
+ :::
+
+ ```yaml showLineNumbers
+ initializePortResources: true
+ scheduledResyncInterval: 120
+ integration:
+ identifier: my-ocean-argocd-integration
+ type: argocd
+ eventListener:
+ type: POLLING
+ config:
+ // highlight-next-line
+ serverUrl: SERVER_URL
+ secrets:
+ // highlight-next-line
+ token: TOKEN
+ ```
+
2. Install the `my-ocean-argocd-integration` ArgoCD Application by creating the following `my-ocean-argocd-integration.yaml` manifest:
-:::tip 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](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/#helm-value-files-from-external-git-repository).
-:::
-
-
- ArgoCD Application
-
-```yaml showLineNumbers
-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
- // highlight-start
- 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
- // highlight-end
- targetRevision: main
- ref: values
- syncPolicy:
- automated:
- prune: true
- selfHeal: true
- syncOptions:
- - CreateNamespace=true
-```
-
-
-
-
+ :::tip 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](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/#helm-value-files-from-external-git-repository).
+ :::
+
+
+ ArgoCD Application
+
+ ```yaml showLineNumbers
+ 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
+ // highlight-start
+ 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
+ // highlight-end
+ targetRevision: main
+ ref: values
+ syncPolicy:
+ automated:
+ prune: true
+ selfHeal: true
+ syncOptions:
+ - CreateNamespace=true
+ ```
+
+
+
+
3. Apply your application manifest with `kubectl`:
-```bash
-kubectl apply -f my-ocean-argocd-integration.yaml
-```
+ ```bash
+ kubectl apply -f my-ocean-argocd-integration.yaml
+ ```
@@ -165,21 +141,16 @@ After installation, the integration will:
1. Create blueprints in your [Builder](https://app.getport.io/settings/data-model) (as defined [here](https://github.com/port-labs/ocean/blob/main/integrations/argocd/.port/resources/blueprints.json)) that represent ArgoCD resources:
-
-
-
+
-
2. Create entities in your [Software catalog](https://app.getport.io/services). 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](https://github.com/port-labs/ocean/blob/main/integrations/argocd/.port/resources/port-app-config.yaml)):
-
+
-
+
3. Create a [dashboard](https://app.getport.io/argocdDashboard) in your software catalog that provides you with some visual views of the data ingested from your K8s cluster.
@@ -187,24 +158,12 @@ After installation, the integration will:
-### 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](https://app.getport.io/settings/data-model), expand the `Running Service` blueprint, and click on `New relation`.
-
-2. Fill out the form like this, then click `Create`:
+## Set up automatic discovery
-
+After onboarding, the relationship between the **Workload** blueprint and the **Service** blueprint is established automatically.
+The next step is to configure automatic discovery to ensure that each **Workload** entity is properly related to its respective **Service** entity.
-
-
-
-### 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.
+You may have noticed that the service relation is empty for all of our workload entities. This is because we haven't specified which **Workload** 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: ` will automatically be assigned to a `service` with that identifier.
@@ -213,46 +172,47 @@ For example, an ArgoCD application with the label `portService: awesomeService`
To achieve this, we need to update the ArgoCD integration's mapping configuration:
-1. Go to your [data sources page](https://app.getport.io/settings/data-sources), 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`:
-
-```yaml showLineNumbers
- - kind: application
- selector:
- query: 'true'
- port:
- entity:
- mappings:
- identifier: .metadata.labels.portService
- blueprint: '"service"'
- properties: {}
- - kind: application
- selector:
- query: "true"
- port:
- entity:
- mappings:
- identifier: .metadata.uid
- blueprint: '"argocdApplication"'
- properties: {}
- relations:
- service: .metadata.labels.portService
-```
+1. Go to your [data sources page](https://app.getport.io/settings/data-sources), 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`:
-
+ ```yaml showLineNumbers
+ - kind: application
+ selector:
+ query: 'true'
+ port:
+ entity:
+ mappings:
+ identifier: .metadata.labels.portService
+ blueprint: '"service"'
+ properties: {}
+ - kind: application
+ selector:
+ query: "true"
+ port:
+ entity:
+ mappings:
+ identifier: .metadata.uid
+ blueprint: '"argocdApplication"'
+ properties: {}
+ relations:
+ service: .metadata.labels.portService
+ ```
-2. Go to the [services page](https://app.getport.io/services) 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:
+
-
+2. Go to the [services page](https://app.getport.io/services) of your software catalog. Click on the `Service` for which you created the deployment. At the bottom of the page, you will see the `Workload` related to this service, along with all of their data:
+
+
+
+
-
-### Visualize data from your Kubernetes environment
+## 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.
+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 our ArgoCD application(`Workload`) blueprint is connected 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
+
+### Display all degraded workloads for the `AwesomeService` service by team
1. Go to your [ArgoCD dashboard](https://app.getport.io/argocdDashboard), click on the `+ Add` button in the top right corner, then select `Table`.
@@ -269,13 +229,13 @@ Let's see an example of how we can add useful visualizations to our dashboard:
-### Possible daily routine integrations
+## 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.
-### Conclusion
+## Conclusion
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.
+Customize your views to display the data that matters to you, grouped or filtered by teams, namespaces, or any other criteria.
diff --git a/static/img/guides/argoBlueprintsCreated.png b/static/img/guides/argoBlueprintsCreated.png
index 6fc46ee81..bda719ee9 100644
Binary files a/static/img/guides/argoBlueprintsCreated.png and b/static/img/guides/argoBlueprintsCreated.png differ
diff --git a/static/img/guides/argoEntitiesCreated.png b/static/img/guides/argoEntitiesCreated.png
index 90019815e..4fbc0a55e 100644
Binary files a/static/img/guides/argoEntitiesCreated.png and b/static/img/guides/argoEntitiesCreated.png differ
diff --git a/static/img/guides/argoEntityAfterIngestion.png b/static/img/guides/argoEntityAfterIngestion.png
index c79dc0a32..7d57dc0c6 100644
Binary files a/static/img/guides/argoEntityAfterIngestion.png and b/static/img/guides/argoEntityAfterIngestion.png differ
diff --git a/static/img/guides/argoTableDegradedServicesForm.png b/static/img/guides/argoTableDegradedServicesForm.png
index 5a52053a0..1ab4de149 100644
Binary files a/static/img/guides/argoTableDegradedServicesForm.png and b/static/img/guides/argoTableDegradedServicesForm.png differ