Add How to start page, update developers guide cd and workflows pages

Lmittie · all4code · web-flow · commit 9d295f61bab9 · 2025-04-15T19:11:44.000+02:00
---------

Co-authored-by: Alexander Ulyanov &lt;ulyanov.alexander@gmail.com&gt;
diff --git a/docs/assets/argocd_applications.png b/docs/assets/argocd_applications.png
diff --git a/docs/assets/argocd_sync.png b/docs/assets/argocd_sync.png
diff --git a/docs/developers_guide/cd/delivery.md b/docs/developers_guide/cd/delivery.md
@@ -1,22 +1,48 @@
-The CG DevX reference implementation provides continuous delivery using a tool called ArgoCD.
+# Continuous Delivery with ArgoCD
+
+The CG DevX reference implementation provides continuous delivery using a tool called ArgoCD. ArgoCD is a declarative, GitOps-based continuous delivery tool for Kubernetes applications. This guide provides a beginner-friendly walkthrough on how to work with ArgoCD to manage application deployments in CG DevX.
+
+## Overview
+
+ArgoCD integrates seamlessly with CG DevX to automate the deployment and synchronization of Kubernetes applications. It continuously monitors the **GitOps Repository** for changes and updates your cluster automatically. This guide will help you:
+
+- Understand ArgoCD's core concepts.
+- Learn how to navigate the ArgoCD UI.
+- Deploy, monitor, and troubleshoot applications using ArgoCD.
+
+## Core Concepts
+
+Before diving in, it’s essential to understand the following concepts:
+
+### **Application**
+An ArgoCD **Application** represents a deployed Kubernetes workload. It maps to a specific directory in your **GitOps Repository**, containing manifests that define the desired state of your application.
+
+### **GitOps Repository**
+The GitOps repository stores Kubernetes manifests, and Terraform setups. These files define your workload and its infrastructure. Please not that ArgoCD application configuration is a part of the platform GitOps repository, not a workload GitOps repository.
+
+### **Sync**
+The process of aligning the desired state (as defined in the GitOps Repository) with the live state in the Kubernetes cluster.
+
+## Setting Up ArgoCD for Your Workload
+
+### 1. **Accessing the ArgoCD Dashboard**
 
-ArgoCD is K8s and GitOps centric, and provides detailed visualization.
 To access ArgoCD, follow the link in the platform GitOps repository readme file (`README.md`),
 or provided by operators (AKA a platform team).
 
 ArgoCD is configured to use Vault as its OIDC provider.
 
 ![argocd_login.png](../../assets/argocd_login.png)
 
-You will need to press the `Log in via Vault` button, which will redirect you to Vault login page,
-which will look like this:
+You will need to press the Log in via Vault button, which will redirect you to Vault login page. Log in using the credentials (username/password or token) given to you by your platform operator.
 
-<!-- All images on this page can probably be re-shot with a tighter viewport so that the text is larger. -->
 ![vault_login.png](../../assets/vault_login_userpass.png)
 
-CG DevX creates one project per workload and applies RBAC to limit access to workload dashboards and management.
+Once logged in, you’ll see a list of existing ArgoCD applications.
+
+![argocd_applications.png](../../assets/argocd_applications.png)
 
-All workload environments will be listed on the ArgoCD project page.
+CG DevX creates one project per workload and applies RBAC to limit access to workload dashboards and management. All workload environments will be listed on the ArgoCD project page.
 
 ![argocd_workload.png](../../assets/argocd_workload.png)
 
@@ -26,3 +52,31 @@ statistics on the pod and node level, and ingress configuration.
 ![argocd_workload_environment_tree.png](../../assets/argocd_workload_environment_tree.png)
 ![argocd_workload_environment_resource.png](../../assets/argocd_workload_environment_resource.png)
 ![argocd_workload_environment_network.png](../../assets/argocd_workload_environment_network.png)
+
+### 2. **Deploying an Application**
+
+ArgoCD automatically detects and deploys applications defined in the GitOps Repository. To deploy a workload:
+
+1. Add the necessary Kubernetes manifests for your application to the GitOps Repository.
+2. Commit and push the changes.
+
+ArgoCD will automatically sync the changes and deploy the application to your cluster.  
+
+![argocd_workload.png](../../assets/argocd_workload.png)
+
+### 3. **Syncing Your Application**
+
+ArgoCD will continuously monitor the GitOps Repository, but you can also trigger a manual sync:
+
+1. In the ArgoCD dashboard, find your application.
+2. Click **Sync** to align the live state with the desired state from the GitOps Repository.
+3. Monitor the sync process and confirm successful deployment.  
+
+   ![argocd_sync.png](../../assets/argocd_sync.png)
+
+## Additional Resources
+
+- [Official ArgoCD Documentation](https://argo-cd.readthedocs.io/)
+- [Kubernetes Getting Started Guide](https://kubernetes.io/docs/tutorials/kubernetes-basics/)
+- [Debugging Kubernetes Deployments](https://kubernetes.io/docs/tasks/debug/)
+
diff --git a/docs/developers_guide/ci/argo_workflows.md b/docs/developers_guide/ci/argo_workflows.md
@@ -1,37 +1,64 @@
 # Argo workflows: basic flows and templates
 
-CG DEVX's argo workflows approach implements following execution scheme:
+CG DevX leverages **Argo Workflows** to streamline CI/CD processes. Workflows defined in the `.argo` directory of your workload repository.
+These workflows rely on pre-configured **Cluster Workflow Templates (CWFTs)** to perform specific actions, ensuring efficiency and consistency across all workloads.
+
+CG DevX's argo workflows approach implements following execution scheme:
 
 ```mermaid
 flowchart TD
-    node_A["GitHub Action Job Step"] --> node_B["argo workflow in .argo/"]
-    node_B --> node_C["cwft"]
+    node_A["GitHub Action Job Step"]
+    node_A --> node_B["Argo Workflow in .argo/"]
+    node_B --> node_C["CWFT"]
     node_C --> node_D["DAG steps"]
     linkStyle 1 stroke:#000000
 ```
 
 &nbsp;
 
-## Basic workflows
-
-- **build**, which includes *build*, *lint* and *check* steps
-- **registry_put** places successfully builded image into the Harbor image repository
-- **crane_img_tag** tags images for unchanged services in the same *apps* structure
-- **version_change** promotes version in the version.yaml file in workload's gitops-repo.
-
-## Cluster workflow templates
-
-For every action workflows use cluster workflow templates consist of one or several steps to perform.
-In case of a list of parameters to process templates from clusterworkflow templates can be called iteratively.
-Cluster workflow templates are used to implement atomic phases of services images build process,
-except  `build_chain_p_cwft`, which have a DAG inside and called in a special way: inside so-called
-workflow-of-workflows structure in `.argo/build-wow-wf.yaml`.
-
-- build_chain_p_cwft
-    - megalinter-cwft — lints service code using Megalinter
-    - trivy-fs-s3-cwft — checks service fs with Trivy
-    - kaniko-s3-p-cwft — builds tar-image with Kaniko
-- crane-s3-p-cwft — tags and puts image into the Harbor image repo
-- crane-img-tag-cwft — tags unchanged (if any) services latest images and tag it with the same tag as changed
-- version-changer-cwft — change version in version.yaml in gitops-repo
-     
+## How It Works
+
+1. **GitHub Actions Job**: When triggered, a step from your GitHub Actions job submits an Argo Workflow.
+
+2. **Argo Workflow Submission**: The Argo Workflow acts as orchestrator, submitting tasks to CWFTs.
+
+3. **Cluster Workflow Templates (CWFTs)**  
+   Cluster Workflow Templates (CWFTs) are reusable building blocks that execute individual tasks, such as building images or scanning code. They are centrally defined and shared across workloads.
+
+4. **DAG Steps**  
+   Some CWFTs, like _build_chain_p_cwft_, use a Directed Acyclic Graph (DAG) to handle tasks with dependencies, allowing for parallel execution wherever possible.
+
+## Basic Workflows
+
+The `.argo` directory in your workload repository contains workflows for common CI/CD tasks:
+
+- **build-wow-wf**  
+   Handles building, linting, and running quality checks to prepare your workload for deployment.
+
+- **crane-p-wf**  
+   Pushes successfully built Docker images to the Harbor container registry.
+
+- **crane-img-tag-wf**  
+   Updates tags for unchanged services to keep their versions aligned with the new ones.
+
+- **version_changer-wf**  
+   Updates the `version.yaml` file in the GitOps repository with the latest versions for deployment.
+
+## Key Cluster Workflow Templates
+
+- **build_chain_p_cwft**  
+   Orchestrates the build process through a series of steps:
+   - **megalinter-cwft**: Lints the code to ensure it meets quality standards.
+   - **trivy-fs-s3-cwft**: Scans the filesystem for vulnerabilities.
+   - **kaniko-s3-p-cwft**: Builds container tar-images with Kaniko.
+
+- **crane-s3-p-cwft**  
+   Pushes built tar-image to the Harbor container registry.
+
+- **crane-img-tag-cwft**  
+   Updates tags for unchanged services to keep them consistent with updated ones.
+
+- **version-changer-cwft**  
+   Updates the `version.yaml` file in the GitOps repository for the dev environment to reference the latest image versions.
+
+ 
diff --git a/docs/developers_guide/ci/github_action_workflow.md b/docs/developers_guide/ci/github_action_workflow.md
@@ -1,36 +1,74 @@
 # Github Action Workflow Structure
 
-CI Github Action start is triggered by push new tag to the workload repo.
-All the CI chain elements run from the steps of job `multi_service_parallel_build` described
-in `multi_service_parallel_build.yml`. If one of the steps fails, the Github action fails completely. Some steps are
-simple bash executed on the runner, another are submissions of relatively complex argo workflows. The workflow structure
-is linear:  steps are executed one after another.
+The **multi_service_parallel_build** GA workflow in CG DevX automates the process of building, testing, and pushing container images for your workload. It is designed to handle multiple services efficiently, making it ideal for microservices architectures.
+
+## What Does This Workflow Do?
+
+The workflow focuses on the following tasks:
+
+1. **Build Container Images**: Builds Docker images for all changed services in your repository.
+2. **Push to Container Registry**: Uploads the built images to the Harbor container registry for deployment.
+3. **Update GitOps Repository**: Updates deployment manifests in the GitOps repository to reflect new image versions.
+
+## How Is It Triggered?
+
+The workflow starts automatically when a tag is pushed. For example, pushing a tag like `v1.0.0` to your workload repository triggers the workflow.
+
+## Key Steps
+
+All the CI chain elements run as part of the job `multi_service_parallel_build`, described in the `multi_service_parallel_build.yml` file located in the `.github/workflows` directory of your workload repository.
+
+If any step fails, the entire GitHub Action fails. Some steps are simple bash scripts executed on the runner, while others involve submitting more complex workflows to Argo Workflows. You can find these workflows in `.argo` directory of your workload repository.
+
+The workflow follows a linear structure: steps are executed sequentially, one after another.
 
 ```mermaid
 ---
-title: multi_service_parallel_build  workflow chart
+title: multi_service_parallel_build workflow chart
 ---
 flowchart 
 n1["`**semver_chk**`"
-cheks if tag matchs SEMVER format
+Validates SEMVER tag format
 ]--if not SEMVER tag, exit-->
 n2["`**actions/checkout@v4**`"
+Checks out the workload repository
 ]-->
 n3["`**argo_cli_install**
-installs _argo cli_  on runner`"]-->
+Installs the Argo CLI for workflow submission
+`"]-->
 n4["`**build**`"
-checks build conditions, detects repo changes and submits workflow of services build workflows 
+Detects modified services and submits the _build-wow-wf_ argo workflow to build Docker images for them using Kaniko
 ]-- if any build fails, exit -->
-n41["`**trivy_libs**
-    if _#quot;apps#quot;_ structure, submits _trivy-libs-wf_ workflow to scan shared libs source code in _libs_ directory. 
+n5["`**trivy_libs**
+Submits _trivy-libs-wf_ argo workflow to scan shared libraries with Trivy (if workload follows _#quot;apps#quot;_ structure)
 `"]-->
-n5["`**registry_put**
-submits _crane_ workflow to tag and put images to Harbor`"
-]-- if any put fails, exit -->
-n6["`**up_tags**
-submits _crane-img-tag_ workflow to up the tag for unchanged services (if any)
+n6["`**registry_put**
+Submits _crane-p-wf_ argo workflow to tag and push built images to Harbor
+`"]-- if any push fails, exit -->
+n7["`**up_tags**
+Submits _crane-img-tag-wf_ argo workflow to update tags for unchanged services in apps structure
 `"]-->
-n7["`**version_change**
-submits _version_change_ workflow to change version in gitops repo
+n8["`**version_change**
+Submits _version_changer-wf_ argo workflow to update GitOps manifests with new image tags
 `"]
 ```
+
+## Core Tools
+
+- **Kaniko**: Used for building container images directly in the CI environment without requiring a local Docker daemon. Learn more about Kaniko workflow [here](kaniko_build.md).
+- **Trivy**: A security scanner that detects vulnerabilities in shared libraries. Learn more about Trivy workflow [here](trivy.md).
+- **Harbor**: A container image registry where built images are stored for deployment. Learn more about Harbor registry [here](../artifacts/registry.md).
+
+## Monitoring the Workflow
+
+You can monitor the status of builds and workflows:
+
+1. **GitHub Actions UI**: Provides logs for each step in the workflow.
+2. **Argo Workflows Dashboard**: Displays the status of submitted workflows and provides detailed logs.
+
+## Example Flow
+
+1. A developer pushes the tag `1.0.0` to the repository.
+2. The workflow detects changes in `wl-service-name/src/` directory.
+3. Docker image for `wl-service-name:1.0.0` is built and pushed to the registry.
+4. The GitOps repository `version.yaml` manifest is updated to reference the new image version.
diff --git a/docs/developers_guide/getting_started.md b/docs/developers_guide/getting_started.md
@@ -0,0 +1,80 @@
+# How to Start
+
+This guide walks you through the initial steps to start working with your workload in CG DevX. By following these instructions, you'll learn how to prepare your workload repository, build your application, and deploy it to Kubernetes.
+
+## Overview
+
+CG DevX simplifies the adoption of modern development practices by integrating open-source tools into a cohesive platform. Getting started involves these key steps:
+
+- Requesting repository setup.
+- Preparing your workload repository.
+- Building and deploying your workload.
+- Monitoring your deployment.
+
+Each step is designed to minimize manual intervention, allowing you to focus on application development.
+
+## Step 1: Request Repository Setup
+
+Before starting, request your platform operator to provision the necessary repositories for you. By default, you'll receive:
+
+- **Workload Repository**:  
+  Stores your application's source code and the `Dockerfile` for containerization. Learn more about workload concepts in the [Workloads Guide](workloads/concept.md).
+
+- **GitOps Repository**:  
+  Contains Kubernetes manifests, Terraform configurations, and environment-specific values for managing deployments. Learn more about GitOps structure and environments in the [How to Model Your Environments](workloads/gitops_environments.md).
+
+> **Why it matters**: These repositories separate application logic from infrastructure, ensuring clear boundaries and maintainability.
+
+For more details on the structure of these repositories, refer to the [Bootstrap Templates Guide](../operators_guide/workload_management/bootstrap_templates.md).
+
+## Step 2: Prepare Your Workload Repository
+
+Once you have access to the **Workload Repository**, add your application’s source code and customize the provided `Dockerfile` to match your workload’s requirements.
+
+- Use the [CG DevX Workload Template](https://github.com/CloudGeometry/cg-devx-wl-template) as a basic starting point for your repository setup.
+- As a real-world example, check out [CG DevX CNASK Workload](https://github.com/CloudGeometry/cg-devx-wl-cnask) for a working implementation.
+
+## Step 3: Build and Deploy Your Workload
+
+The next step is to build and deploy your application. This process is automated via CG DevX’s CI/CD pipelines.
+
+### Trigger the Build
+
+Push a tag to your Workload Repository to trigger the build process:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+### Behind the Scenes
+
+When you push a tag to your **Workload Repository**:
+
+1. **GitHub Actions** submits an **Argo Workflow** with the required parameters.
+2. **Argo Workflow** builds the container image, pushes it to the registry, and updates the **GitOps Repository**.
+3. **ArgoCD** syncs the updated configurations and deploys your application.
+
+This automated pipeline streamlines building, deploying, and syncing your workload.
+
+## Step 4: Monitor Your Deployment
+
+Once deployed, you can verify your application and monitor its performance:
+
+### Access Your Application
+
+- Navigate to the **Ingress URL** listed in the ArgoCD dashboard to access your application.
+
+### Monitor Logs and Metrics
+
+- **Metrics**: Use [Grafana](observability/monitoring.md) to track application performance and resource usage.
+- **Dashboards**: Explore the [pre-configured Grafana dashboards](observability/dashboards.md) to visualize metrics and monitor workload health.
+- **Logs**: Use [Loki](observability/log_management.md) for centralized log aggregation and troubleshooting.
+
+## Step 5: Troubleshoot Issues
+
+If the deployment encounters any issues, use the following tools to diagnose and resolve them:
+
+- **Argo Workflows**: Review the [Argo Workflows dashboard](ci/integration.md) for details on pipeline execution.
+- **ArgoCD Dashboard**: Check deployment logs directly in the ArgoCD dashboard for insights into application issues.
+- **Loki Logs**: Use [Loki](observability/log_management.md) to analyze application and Kubernetes logs for potential errors.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -51,6 +51,7 @@ nav:
           - operators_guide/delivery_pipelines/core_services_delivery.md
 
   - 'Developers Guide':
+      - developers_guide/getting_started.md
       - developers_guide/concept.md
       - 'Workloads':
           - developers_guide/workloads/concept.md
