# JFrog Internal Generic Helm Chart

## Testing new changes and features
On saas-configuration staging environment, there is a jdemo.yaml under jfrogdeployment folder.

Run the local changes before pushing to master.

```
$ jfrog_application chart_deploy jdemo
```

## Default Analysis Templates

The chart provides pre-configured default analysis templates for monitoring critical resource metrics during canary rollouts. These templates are ready to use and help ensure that new deployments don't introduce performance regressions.

**Why Default Templates Are Useful:**

- **Pre-configured:** No need to write custom Prometheus queries or configure analysis templates from scratch
- **Best Practices:** Based on proven monitoring patterns for memory and CPU usage
- **Consistent Monitoring:** Standardized metrics across all rollouts ensure uniform quality gates
- **Quick Enablement:** Simply enable `rolloutAnalysisTemplates.defaultTemplates.basicTemplates.enabled` to start using them

The default templates include:

1. **Memory Usage Template** (`jfrog-memory-usage-analysis`): Monitors memory consumption to detect memory leaks or excessive memory usage
2. **CPU Usage Template** (`jfrog-cpu-usage-analysis`): Monitors CPU utilization to detect performance degradation or resource contention

**Template Parameters:**

Each template (memory and CPU) can be configured with the following parameters:

```yaml
cpuUsageTemplate:
  name: "jfrog-cpu-usage-analysis"
  failureLimit: 3
  count: 0
  interval: 10s
  changeMax: 1.25
```

- **`name`**: The unique identifier for the analysis template. This name is referenced when using the template in rollout steps or background analysis.

- **`failureLimit`**: The maximum number of consecutive failures allowed before the analysis is considered failed and the rollout is aborted. With `failureLimit: 3`, the rollout will continue if there are occasional metric spikes, but will stop if there are 3 consecutive failures, indicating a persistent issue.

- **`count`**: The number of times the analysis should run. When set to `0`, the analysis will run continuously until the end of the Rollout execution, making it ideal for background analysis. For step-based analysis, set this to a specific number (e.g., `5` to run 5 times).

- **`interval`**: The time interval between each analysis run. With `interval: 10s`, the template will check metrics every 10 seconds. Shorter intervals provide more frequent monitoring but increase load on the metrics server.

- **`changeMax`**: The maximum allowed change multiplier compared to the baseline (stable version). With `changeMax: 1.25`, the canary version's metric value can be up to 25% higher than the stable version. If the canary exceeds this threshold, the analysis fails. This provides a safety mechanism to prevent deployments that significantly degrade performance.

These templates query metrics from the configured Prometheus server (`promServerAddress`) and compare canary metrics against the stable version to ensure the new deployment maintains acceptable performance characteristics.

## Canary and stable pod metadata (`stableMetadata` / `canaryMetadata`)

When `rolloutStrategy.enabled` is true, the chart renders Argo Rollouts [`stableMetadata`](https://argoproj.github.io/argo-rollouts/features/specification/#rolloutspec) and `canaryMetadata` under `spec.strategy.canary`. Each block always includes `labels` and `annotations` in the generated Rollout manifest.

You can add extra labels and annotations via values under `rolloutStrategy.canary`:

- **`stableMetadata`** — merged into stable-replica pod template metadata.
- **`canaryMetadata`** — merged into canary-replica pod template metadata.

**Merge behavior:** Helm merges your `labels` and `annotations` first, then the chart applies `role: stable` or `role: canary` **last** on both maps. A `role` key in your values cannot override the chart; the chart always wins on `role`.

**Defaults:** `stableMetadata` and `canaryMetadata` default to empty `labels` and `annotations`; the rendered Rollout still contains both sub-keys with at least the enforced `role` entry on labels and annotations.

Example:

```yaml
rolloutStrategy:
  canary:
    stableMetadata:
      labels:
        team: platform
      annotations:
        example.com/env: prod
    canaryMetadata:
      labels:
        team: platform
```

## Enabling and Using the Canary Request Job Analysis Template

The canary request job analysis template allows you to gradually increase the number of users exposed to a new canary version by updating router with a valid canary header.

### How to Enable

**Configure your rollout strategy to gradually increase canary traffic:**

    ```yaml
    rolloutStrategy:
      canary:
        steps:
          - setCanaryScale:
              weight: 100
          - setAccountWeight:
              weight: 20
              type: enterprise_trial
          - pause:
              duration: 10m
          - setAccountWeight:
              weight: 40
              type: enterprise_trial
          - pause:
              duration: 10m
          - setAccountWeight:
              weight: 100
              type: enterprise_trial
          - pause:
              duration: 10m
    ```

**Note:** The `setCanaryScale` step with `weight: 100` sets the canary deployment to scale to 100% of the desired replica count, ensuring the canary version has sufficient capacity before traffic routing begins.
   
Each `setAccountWeight` step in your canary rollout strategy defines how much customers (by percentage) is routed to the canary version for a specific account type and region. Here's what happens at each step:

- **Helm Rendering:**  
  The `setAccountWeight` step calls a helper in `_helpers.tpl` during Helm rendering. This helper generates the canary request job template using the provided `weight` and `type`.
  > Advanced:  
  > You can also optionally specify `interval` and `timeout` for each step.
  > - `interval` (the interval at which the job checks the status of the canary header change): defaults to **10** seconds if omitted.
  > - `timeout` (the wait time for the canary header change): defaults to **7200** seconds (2 hours) if omitted.

- **Additional Arguments:**  
  When `saas-deployer` executes the `helm upgrade` command, it injects two additional arguments:
  - `region` (the deployment region)
  - `mt-service` (the microservice name)  
  These are used in `_helpers.tpl` to generate the correct canary request job.

- **Job Creation:**  
  At each `setAccountWeight` step, a new canary request job is created with the specified parameters. This job updates canary manager service and in the end the router service is updated with the correct canary header.

- **Pause:**  
  This step shows that the user can inject more steps between weight changes if needed.
  After each weight change, a `pause` step allows time for monitoring and analysis before proceeding to the next increment.

This mechanism ensures a controlled and observable rollout, gradually increasing canary exposure and collecting data at each stage.

### Canary Request Job Pod Behavior

The pods spawned by the canary request job have the following characteristics:

- **Log routing:** The pod template carries the annotation `logging_index: devops-infra`, which routes the canary-job pod logs to the `devops-infra` logging index.

- **Context labels:** The pod template carries the labels `rollout-name` (from `rolloutStrategy.deploymentName`) and `canary-region` (from `canaryRegion`), so canary-job pods can be filtered by rollout and region (e.g. `kubectl get pods -l rollout-name=<name>`).

- **Pod naming:** The job metric is named after `canaryServiceName` (falling back to `canary-job` when unset), so the resulting pods are recognizable — e.g. `<analysis-run-uid>.<service>.<n>-<random>`. Underscores in the service name are replaced with hyphens (e.g. `mt_event` → `mt-event`) so the name stays DNS-1123 valid. The leading UID is the Argo Rollouts `AnalysisRun` UID and is assigned by Argo; it cannot be changed or shortened from the chart. Argo also truncates the service-name segment to keep the name within the 63-character limit, which affects readability only — names remain unique.

- **Job tuning (`rolloutAnalysisTemplates.canaryRequestJobTemplate`):**
  - `backoffLimit`: number of retries before the Job is marked failed (default `0` = fail fast, no retries).
  - `ttlSecondsAfterFinished` (optional): seconds Kubernetes keeps the finished Job/pod before deleting it. When unset, the pod is **not** cleaned up on a timer — it persists until Argo Rollouts evicts the owning `AnalysisRun` via its run-history limit (default 5 successful / 5 unsuccessful per rollout).
  - Both fields are rendered into the Job spec **only when present in values**, so omitting a key leaves it out of the spec entirely (a value of `0` is still rendered).

### Canary Manager Configuration Keys

The following keys are used to configure the canary request job and are required for integration with the canary manager service. These values are injected automatically by the `saas-deployer` service during the Helm upgrade process. **Users should not set these values manually in their own values files.**

- **canaryServiceName**: The name of the microservice being deployed.
- **canaryRegion**: The deployment region for the canary rollout.
- **canaryManagerEndpoint**: The endpoint URL of the canary manager service.
- **canaryManagerUsername**: The username used to authenticate with the canary manager service.
- **canaryManagerPassword**: The password used to authenticate with the canary manager service.
- **canaryRequestJobImage**: The container image used for the canary request job.
- **rolloutStrategy.canary.canaryByHeader.canaryByHeaderValue**: Canary header value taken from the cell config.

### Background Analysis Feature

The `backgroundAnalysis` configuration in `values.yaml` is set to an empty object `{}` and the `analysis` section is commented out.

If implemented, background analysis would allow you to run analysis templates continuously in the background during the entire rollout process, rather than only at specific steps. This would enable:

- **Continuous Monitoring:** Analysis templates (such as `jfrog-memory-usage-analysis` and `jfrog-cpu-usage-analysis`) would run continuously throughout the rollout
- **Starting Step Control:** You could specify a `startingStep` to delay when background analysis begins
- **Template Configuration:** Multiple analysis templates could be configured to run simultaneously in the background

```yaml
rolloutStrategy:
  canary:
    backgroundAnalysis:
      analysis:
        templates:
          - templateName: "jfrog-memory-usage-analysis"
          - templateName: "jfrog-cpu-usage-analysis"
        startingStep: 1 # delay starting analysis run until step 1
        args: [ { name: service-name } ]
```