diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/_category_.json b/docs/continuous-delivery/gitops/gitops-entities/service/_category_.json new file mode 100644 index 00000000000..ae2c90d79db --- /dev/null +++ b/docs/continuous-delivery/gitops/gitops-entities/service/_category_.json @@ -0,0 +1,12 @@ +{ + "label": "Service", + "position": "300", + "collapsible": "true", + "collapsed": "true", + "className": "red", + "description": "Learn how to create and use Harness GitOps service", + "link": { + "type": "generated-index", + "title": "Service" + } + } \ No newline at end of file diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/gitops-vs-cd-service.md b/docs/continuous-delivery/gitops/gitops-entities/service/gitops-vs-cd-service.md new file mode 100644 index 00000000000..a171740999c --- /dev/null +++ b/docs/continuous-delivery/gitops/gitops-entities/service/gitops-vs-cd-service.md @@ -0,0 +1,94 @@ +--- +title: GitOps vs CD Services +description: Learn the key differences between GitOps and CD services in Harness. +sidebar_position: 20 +--- + +# GitOps vs CD Services + +This topic explains the key differences between GitOps and CD services in Harness, helping you understand which approach best fits your deployment needs. + +## Overview + +Harness supports two primary approaches for continuous delivery: + +1. **CD Services**: The Harness deployment approach that uses pipelines to define and execute deployment steps explicitly +2. **GitOps Services**: A declarative approach that continuously synchronizes your deployments with Git repository manifests + +While both approaches achieve the goal of deploying applications, they differ significantly in philosophy, workflow, and implementation. + +## Key Differences + +### Deployment Philosophy + +| CD Services | GitOps Services | +|------------------------|-----------------| +| **Push-based**: Changes are actively pushed through the pipeline to target environments | **Pull-based**: The GitOps Agent continuously pulls the desired state from Git | +| **Procedural**: Defines a sequence of steps to perform the deployment | **Declarative**: Defines the desired end-state in Git, letting the system figure out how to achieve it | +| **Event-triggered**: Deployments start when triggered by events (Git changes, webhooks, schedules) | **Continuously reconciled**: Automatically ensures the cluster matches the state defined in Git | + +### Service Definition + +| CD Services | GitOps Services | +|------------------------|-----------------| +| Focused on artifact sources, manifests, and variable definitions | Primarily focused on linking to Git repositories and manifests (Release Repo and Deployment Repo) | +| Requires explicit specification of deployment steps | Uses a GitOps agent to sync with Git repositories automatically | +| Service definition specifies exactly how deployment happens | Service definition points to where the desired state is defined | +| Configuration changes require updating the service or pipeline | Configuration changes are made directly in the Git repository | + +### Service Variables + +| CD Services | GitOps Services | +|------------------------|-----------------| +| Variables defined directly in the service | Variables can reference configuration files stored in Git | +| Variable overrides managed in pipeline executions | Variable overrides can be managed through PR pipelines | +| Fixed variable references | Dynamic variable resolution using expressions like `<+env.name>` and `<+cluster.name>` | +| Variables typically used for single environment deployments | Variables designed to support multi-environment deployments through expressions | + +### Implementation in Harness + +| CD Services | GitOps Services | +|------------------------|-----------------| +| Uses Harness Delegates for deployments | Uses GitOps Agents (based on Argo CD) for deployments | +| Deployment executed through CD pipelines with explicit steps | Deployment continuously reconciled by the GitOps Agent | +| Service variables managed through Harness | Service variables can reference configuration files in Git | +| Dashboard shows deployment executions and pipeline runs | Dashboard shows sync status, health, and resource utilization | + +### Architecture Components + +| CD Services | GitOps Services | +|------------------------|-----------------| +| Harness Delegate handles deployment operations | GitOps Agent (with Application Controller, Repo Server) handles deployments | +| Configuration stored primarily in Harness | Configuration primarily stored in Git repositories | +| Pipelines define deployment flow | Git commits drive deployment changes | +| Direct interaction with target environments | GitOps Agent mediates interaction with target environments | + +## When to Use Each Approach + +### Choose CD Services When You: + +- Need fine-grained control over deployment steps +- Require complex deployment orchestration +- Have approval processes that must gate deployments +- Need to integrate with multiple systems during deployment +- Want explicit control over when deployments occur + +### Choose GitOps Services When You: + +- Want Git to be the single source of truth for your deployments +- Prefer a declarative approach to defining application state +- Need continuous reconciliation between Git and your clusters +- Have multiple teams working on the same deployments +- Want automated drift detection and correction + +## Hybrid Approaches + +You can also combine both approaches in Harness: + +1. **GitOps for application deployments, CD for infrastructure**: Use GitOps for application services while managing infrastructure with CD pipelines +2. **CD pipelines that trigger GitOps synchronization**: Create pipelines that interact with your GitOps services through PR pipelines +3. **Mixed environment strategy**: Use GitOps for some environments (e.g., development) and CD for others (e.g., production) + +## Next Steps + +- [Learn more about GitOps Services](/docs/continuous-delivery/gitops/gitops-entities/service/) \ No newline at end of file diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/service.md b/docs/continuous-delivery/gitops/gitops-entities/service/service.md new file mode 100644 index 00000000000..f432ee4eefb --- /dev/null +++ b/docs/continuous-delivery/gitops/gitops-entities/service/service.md @@ -0,0 +1,260 @@ +--- +title: GitOps Services +description: Learn how to use GitOps services to track deployments and application state. +sidebar_position: 10 +--- + +# GitOps Services + +This topic describes how to use Harness GitOps services to track your GitOps applications and their deployment state. + +## What is a Service in GitOps? + +In the GitOps context, a service represents an application or a group of related applications deployed through the GitOps methodology. GitOps services help you: + +- Track the deployment state of your applications +- Provide a central location to manage and observe all your GitOps PR pipelines and their service, and the environment details. + +Unlike traditional CD services that define deployment artifacts and configurations, GitOps services focus on tracking, monitoring, and visualizing the state of applications synced automatically through GitOps agents. + +## How to Create a GitOps Service + +A Harness service in the GitOps context logically corresponds to a microservice/application template in an ApplicationSet. Together with the environment and cluster entities, Harness resolves application config.json files in a Git repository to update manifest values through PR pipelines. + +### Creating a GitOps Service + +1. Navigate to **Deployments** > **Services** in your Harness project. +2. Click **New Service**. +3. Enter a name for your service. +4. Select **Save**. +5. In the service configuration tab, under the service definition, in the deployment type, select Kubernetes and toggle on **Enable GitOps**. + + ![Enable GitOps Option](./static/enable-gitops-service.png) + +6. Add the Manifests and Artifact details. You have two main options for manifests: + + #### a. Add a Release Repo Manifest + + This manifest points to configuration files (like `config.json`) in your Git repository. It is used by the **Update Release Repo** step in PR pipelines to update configuration files and create pull requests. + + 1. In **Manifests**, select **Add Release Repo Manifest**. + 2. In **Release Repo Store**, select your Harness Git connector to the repository containing your config.json files. + 3. In **Manifest Details**, configure: + - **Manifest Name**: Enter a name like `config.json` + - **Git Fetch Type**: Select **Latest from Branch** + - **Branch**: Enter your main branch name + - **File Path**: Enter the path to your config files, using expressions like: + `examples/git-generator-files-discovery/cluster-config/engineering/<+env.name>/config.json` + + The `<+env.name>` expression resolves to the Harness environment you select when running the pipeline. + + :::info + You can also use cluster-specific paths with expressions: + + ``` + examples/git-generator-files-discovery/cluster-config/engineering/<+env.name>/<+cluster.name>/config.json + ``` + + Your Git directories would then be structured as: + ``` + examples/git-generator-files-discovery/cluster-config/engineering/dev/cluster1/config.json + examples/git-generator-files-discovery/cluster-config/engineering/dev/cluster2/config.json + ``` + + This allows you to update only applications deployed in specific clusters. + ::: + + #### b. Add a Deployment Repo Manifest + + This manifest specifies the path to your ApplicationSet template. It is used by the **Fetch Linked Apps** step in PR pipelines to retrieve information about the GitOps applications associated with your service. + + 1. In **Manifests**, select **Add Deployment Repo Manifest**. + 2. In **Manifest Details**, configure: + - **Manifest Name**: Enter a name like `Application Set` + - **Git Fetch Type**: Select **Latest from Branch** + - **Branch**: Enter your main branch name + - **File Path**: Enter the path to your ApplicationSet template, such as: + `examples/git-generator-files-discovery/git-generator-files.yaml` + + When these manifests are configured in your service and the corresponding pipeline steps are added to your pipeline execution, they fetch the respective manifest YAML and perform the deployment. + +7. You can also reference an App Set by clicking on the **Reference App Set** option and configuring the Agent and the app set reference. + +8. Click **Save** to complete the service configuration. + +### Using App Set Reference + +Another way is to use the App Set Reference field, wherein you provide the agent and the app set reference. This is a more dynamic way to add the service to the pipeline, as the app set and agent are already created and installed. + +Currently, this is behind a feature flag `GITOPS_APPLICATIONSET_FIRST_CLASS_SUPPORT`. Contact [Harness Support](mailto:support@harness.io) to enable the feature. + +![App Set Reference](./static/gitops-service-2.png) + +### Linking Existing Applications to a Service + +Here's another way to create GitOps services by linking existing applications: + +1. Navigate to **Deployments** > **GitOps** > **Applications**. +2. Select the application you want to map to a service. +3. In the **App Details** tab, you can map the application to a service. +4. Choose to either create a new service or map to an existing service. +5. Complete the mapping configuration and click **Apply Changes**. + +This approach is useful when you have already created GitOps applications via the GitOps UI or imported them from Argo CD. + +## Service Variables + +Service variables play a crucial role in managing configurations and deployments in GitOps. These variables help customize your deployments across different environments and clusters. + +![Enable GitOps Option](./static/gitops-service-3.png) + +### How Service Variables Work + +In GitOps, service variables provide the following capabilities: + +1. **Service Variables Definition**: + - Define variables specific to your service, such as `imageTag`, `port`, and other service-specific settings + - These variables can be referenced in your manifests and configurations + +2. **Environment and Cluster-Level Overrides**: + - Variables can be overridden at different levels - environment, cluster, or service level + - This flexibility allows for proper configuration management across environments + +3. **Runtime Inputs**: + - Some service variables can be defined as runtime inputs + - This is useful for variables that change frequently or need to be specified at deployment time + +4. **Precedence and Overrides**: + - The order of precedence typically flows from infrastructure variables (highest priority) to service level variables (lowest priority) + - This ensures that the most specific configurations are applied + +### Using Cluster Name as a Service Variable + +A specific use case is referencing cluster attributes stored in configuration files: + +1. Store the cluster name in a configuration file (like `config.json`) +2. Reference this value as a service variable using expression syntax +3. During deployment, the service can target the correct cluster based on this reference + +By using service variables with expressions, you can create dynamic and configurable deployments that adapt to different environments and requirements. + +## GitOps Service Dashboard + +The GitOps Service Dashboard provides visibility into your GitOps applications and services. It helps you monitor deployment activity, success rates, and service status across your entire environment. + +Note that service instances will only appear on the dashboard if they are associated with a PR pipeline that uses the specific service and environment. + +### Accessing the Service Dashboard + +1. Navigate to **Deployments** > **Services**in your Harness project. +2. You'll see a list of all your services, including traditional CD and GitOps services. + +### Dashboard Features + +The Services Dashboard displays comprehensive information about your services: + +#### Overview Statistics + +At the top of the dashboard, you can see summary statistics including: + +- **Total Services**: The total number of services in your project +- **Service Instances**: The number of active service instances +- **Deployments**: Number of deployments in the selected time period +- **Failure Rate**: Percentage of deployments that have failed +- **Frequency**: Average number of deployments per day + +You can filter the view to see data for the last 7 days, 30 days, or a custom time range. + +#### Environment Distribution + +The dashboard shows how your services are distributed across environments: +- **Production** (Prod): Services deployed to production environments +- **Non-Production** (Non Prod): Services deployed to testing, development, or staging environments + +#### Most Active Services + +This section displays your most frequently deployed services, showing: +- Service names +- Number of deployments per service +- Success/failure status + +#### Services Table + +The main services table provides detailed information about each service: + +| Column | Description | +|--------|-------------| +| SERVICE | Name of the service and its unique ID | +| Code Source | Source of the service configuration (Inline, Git, etc.) | +| TYPE | Type of service | +| ACTIVE INSTANCE COUNT | Number of active instances for each service | +| DEPLOYMENTS | Count of deployments, broken down by environment | +| FAILURE RATE | Percentage of failed deployments | +| FREQUENCY | Average number of deployments per time period | +| LAST PIPELINE EXECUTION | Most recent pipeline that deployed this service and its status | + +#### Service Actions + +From the service dashboard, you can perform several actions: +- Create a new service +- Search for specific services +- Sort services by various attributes +- View service details by clicking on a service name +- Access pipeline execution details by clicking on the last pipeline execution + +### Service-Centric Monitoring + +The Services dashboard provides a service-centric view of your deployments, enabling you to: + +1. **Monitor deployment trends**: Track service deployment frequency and success rates over time +2. **Identify problematic services**: Quickly spot services with high failure rates +3. **Compare environments**: See how services perform across production and non-production environments + +By utilizing the Services dashboard, you gain visibility into all your services, including GitOps applications. This helps you maintain reliable deployments and quickly address issues as they arise. + +## Using GitOps Services with PR Pipelines + +Since GitOps services are closely integrated with PR pipelines, understanding how they work together is crucial. PR pipelines enable you to make environment-specific changes through pull requests that are automatically merged and applied to your deployments. + +### Dynamic Path Configuration with Variables + +When defining manifest paths in your GitOps service (as described in the [Creating a GitOps Service](#creating-a-gitops-service) section), you can use environment variables to dynamically select the correct configuration: + +- Use `<+env.name>` in your paths to dynamically reference environment-specific files. +- Example path: `examples/git-generator-files-discovery/cluster-config/engineering/<+env.name>/config.json` + +This approach allows a single service definition to work with multiple target environments. + +### Pipeline Steps for GitOps Services + +PR pipelines include several steps specifically designed for working with GitOps services: + +1. **Update Release Repo**: Updates configuration files and creates a PR. + - Uses the Release Repo Manifest configured in your service + - Supports hierarchical variables and list updates. + - Overrides service or environment variables with the same name. + +2. **Fetch Linked Apps**: Retrieves information about GitOps applications linked to your service. + - Uses the Deployment Repo Manifest configured in your service + - Displays app name, agent identifier, and URL to the Harness GitOps app. + - Requires a properly configured Deployment Repo manifest. + +3. **GitOps Sync**: Triggers synchronization of your GitOps applications. + - Filters applications by name, regex pattern, or labels. + - Updates the cluster with the latest state from Git. + +4. **Update GitOps App**: Modifies your GitOps application configuration. + - Updates values files or overrides specific parameters. + - Works with both single-source and multi-source applications. + +5. **GitOps Get App Details**: Fetches detailed information about your applications. + - Returns status data as JSON that can be used in subsequent steps. + - Supports hard refresh to get real-time status information. + +By combining these pipeline steps with GitOps services, you can build comprehensive workflows that manage your application configurations and deployments through Git. + +## Next Steps + +- [Learn about PR Pipeline Basics](/docs/continuous-delivery/gitops/pr-pipelines/pr-pipelines-basics) +- [Learn more about GitOps Applications](/docs/continuous-delivery/gitops/application/manage-gitops-applications) +- [Compare GitOps vs CD Services](./gitops-vs-cd-service.md) \ No newline at end of file diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/static/enable-gitops-service.png b/docs/continuous-delivery/gitops/gitops-entities/service/static/enable-gitops-service.png new file mode 100644 index 00000000000..9a6b0d29ece Binary files /dev/null and b/docs/continuous-delivery/gitops/gitops-entities/service/static/enable-gitops-service.png differ diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-1.png b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-1.png new file mode 100644 index 00000000000..bca940a8e45 Binary files /dev/null and b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-1.png differ diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-2.png b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-2.png new file mode 100644 index 00000000000..02a4a32d9eb Binary files /dev/null and b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-2.png differ diff --git a/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-3.png b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-3.png new file mode 100644 index 00000000000..bbfcfe2c591 Binary files /dev/null and b/docs/continuous-delivery/gitops/gitops-entities/service/static/gitops-service-3.png differ