# Ephemeral workloads grouping

The PerfectScale grouping configuration is a powerful tool that enables the aggregation of redundant workloads exhibiting similar patterns. By preventing overload through batches of identical information, it enables you to focus on what matters, thereby streamlining analysis processes.

Custom grouping is a rule that aggregates multiple workloads into a single entity (for example, all GitLab runners are aggregated into a single entity—the GitLab workload), merging their data (resource usage, limits, requests, etc.). 

This feature is especially convenient when using Spark, GitLab, Airflow or any other operators that produce short-lived, small workloads that often reflect just a single pod in the cluster, or when automating the ungrouped workloads.

## Grouping by labels

To group the workloads, two predefined labels should be added to this workload:

| Key                                             | Value                | Description                        |
| ----------------------------------------------- | -------------------- | ---------------------------------- |
| perfectscale.io/workload-grouping-workload-name | custom-workload-name | Specifies the target workload name |
| perfectscale.io/workload-grouping-workload-type | custom-workload-type | Specifies the target workload type |

This grouping approach is specifically helpful for **automating dynamic, short-lived workloads**. 

{% hint style="info" %}
Labels `perfectscale.io/workload-grouping-workload-name` and `perfectscale.io/workload-grouping-workload-type` are required to configure automation for ephemeral workloads. After applying the labels, a new workload will appear in PerfectScale. However, automation will only reduce resources after sufficient data has been collected.
{% endhint %}

To ensure PerfectScale considers all revisions, including those not made by Automation, and to drive better results, you can optionally specify the following labels:

<table><thead><tr><th width="193.2890625">Key</th><th width="160.5771484375">Value</th><th>Description</th></tr></thead><tbody><tr><td>perfectscale.io/workload-grouping-honor-spec</td><td><ul><li>true</li><li>false (default)</li></ul></td><td><p>Allows PerfectScale to consider the resource changes in the original spec and changes to current resources.</p><p></p><p><strong>When to use?</strong> Set to <code>true</code> if:</p><ul><li>You are manually changing <code>spec</code> resources (set by the customer in the parent object) and want PerfectScale to respect those changes.<br>❗<strong>Note:</strong> To ensure predictable automation behavior, use this label with the value <code>true</code> only when all workloads in the group have equal resources.</li><li>You want every manual resource change revision to appear in the Revisions Timeline.</li></ul></td></tr><tr><td>perfectscale.io/workload-grouping-honor-image</td><td><ul><li>true</li><li>false (default)</li></ul></td><td><p>Allows PerfectScale to consider the image name in the calculated hash.<br></p><p><strong>When to use?</strong> Set to <code>true</code> if:</p><ul><li>If you want to see the deployment history in the timeline when the application version (image) changes.<br>❗<strong>Note:</strong> Each update will create a new revision in the Revisions Timeline, which may result in a large number of entries.</li></ul></td></tr></tbody></table>

{% hint style="info" %}
If you enable automation for a custom workload type, the [WorkloadLabelsSelector](https://docs.perfectscale.io/customize-workflow/broken-reference) in a cluster or namespace configuration will not be applied. All workloads of that custom type will be automated despite the label's configuration.
{% endhint %}

### Cross-namespace grouping

{% hint style="info" %}
This feature is supported in autoscaler version **1.0.43** and later.
{% endhint %}

In environments with dynamic namespace structure, it can be difficult to apply consistent automation policies across related workloads. PerfectScale addresses this by enabling centralized automation for workloads across multiple namespaces using labels.

To group and automate such workloads, you need to proceed with a few simple steps:

1. Create a target namespace (the grouping destination).
2. Apply grouping labels to relevant workloads, including `perfectscale.io/workload-grouping-workload-namespace` with the target namespace value.
3. In the target namespace, define a [namespace](https://docs.perfectscale.io/enable-automation/including-a-cluster-namespace-or-workload-to-the-automation/configuring-automation-for-a-namespace) or [workload-level](https://docs.perfectscale.io/enable-automation/including-a-cluster-namespace-or-workload-to-the-automation/configuring-automation-for-a-workload) automation configuration.
4. Once done, PerfectScale groups workloads from different namespaces under the target namespace and applies the configured automation.

{% hint style="info" %}
This label is optional. If the label is not set, workloads remain grouped within their original namespace.
{% endhint %}

<table><thead><tr><th>Key</th><th width="226.7880859375">Value</th><th>Description</th></tr></thead><tbody><tr><td>perfectscale.io/workload-grouping-workload-namespace</td><td>custom-namespace-name</td><td>Specifies the target namespace for cross-namespace grouping.</td></tr></tbody></table>

When this label is set, workloads from multiple namespaces are grouped under the specified target namespace. Automation configured in the target namespace is applied to all grouped workloads, regardless of their original namespace.

{% hint style="info" %}
When `perfectscale.io/workload-grouping-workload-namespace` is specified, automation configs from original workload namespaces will not be considered. In order to override the configuration, you need a namespace or workload-level config in the targeted namespace.
{% endhint %}

#### How this works in practice

Pod Example:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: pod-name
  namespace: {original-namespace}
  labels:
    perfectscale.io/workload-grouping-workload-name: {target-name}
    perfectscale.io/workload-grouping-workload-type: {target-type}
    perfectscale.io/workload-grouping-workload-namespace: {target-namespace}
```

Original namespace configuration:

```yaml
apiVersion: perfectscale.io/v1
kind: NamespaceAutomationConfig
metadata:
  name: original-namespace-config
  namespace: {original-namespace}
spec:
  automation:
    operational:
      restrictions:
         ...
```

Target namespace configuration:

```yaml
apiVersion: perfectscale.io/v1
kind: NamespaceAutomationConfig
metadata:
  name: target-namespace-config
  namespace: {target-namespace}
spec:
  automation:
    operational:
      restrictions:
         ...
```

{% hint style="info" %}
When target namespace label\
`perfectscale.io/workload-grouping-workload-namespace: {target-namespace}` is specified, automation configs from the `{original-namespace}` namespace(s) will not be considered. Only the configs from `{target-namespace}` will be applied to such workloads.
{% endhint %}