PORT-12428 Visualize your services' Kubernetes runtime using ArgoCD

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.
 ---
@@ -11,30 +10,33 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl
 
 # 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.  
+Once implemented:
 
-:::info Prerequisites
+- 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.
 
-- 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.
 
-:::
 
-<br/>
+## Common use cases
 
-### The goal of this guide
+- ArgoCD and Port Unified View: Manage GitOps workflows in ArgoCD, while seeing real-time resource states in Port.
+- Enhanced Observability: Track multiple clusters or namespaces in a single catalog, with health statuses at a glance.
+- Centralized Dashboards: Build a single dashboard that shows ArgoCD “Running services” alongside your `Service` blueprint.
+- Custom Automation: Extend or combine data from ArgoCD with Slack, Jira, or other external tools, all from Port.
 
-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:
+## Prerequisites
+- This guide assumes you have a Port account and that you have installed any of Port's [Git Integrations](/build-your-software-catalog/sync-data-to-catalog/git/). We will use the `Repository` blueprint that was created during the installation 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.
 
-- 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.
 
-<br/>
+## 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
 
@@ -187,11 +189,11 @@ After installation, the integration will:
 
 <br/>
 
-### Define the connection between workloads and services
+### Define the connection between workloads and repositories
 
-Now that we have our <PortTooltip id="blueprint">blueprints</PortTooltip> 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.
+Now that we have our <PortTooltip id="blueprint">blueprints</PortTooltip> set up, we want to model the logical connection between our ArgoCD resources and the `Repository` 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.
+In this guide we will create a relation named `Repository` 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`.
 
@@ -202,7 +204,7 @@ In this guide we will create a relation named `Service` for the `Running Service
 
 <br/><br/>
 
-### Map your workloads to their services
+## 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.
 
@@ -214,7 +216,7 @@ 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`:
+   Add the following block to the mapping configuration and click `Resync`:
 
 ```yaml showLineNumbers
   - kind: application
@@ -247,12 +249,13 @@ Add the following block to the mapping configuration and click `Resync`:
 
 <br/>
 
-### 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.  
 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
+### Show all "degraded" workloads of `AwesomeService` service belonging to a specific 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 +272,13 @@ Let's see an example of how we can add useful visualizations to our dashboard:
 
     <img src='/img/guides/argoTableDegradedServices.png' width='90%' border='1px' />
 
-### 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.