# 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="warning" %}
For label-grouped workloads, PerfectScale ignores Automation CRD settings that limit recommendations based on the current resource spec. In this case, these fields under `automation.containers.<name>.operational.restrictions` are not applied:&#x20;

```bash
cpuManagement.request.increaseEnabled: false
cpuManagement.request.decreaseEnabled: false 
memoryManagement.request.increaseEnabled: false 
memoryManagement.request.decreaseEnabled: false 
memoryManagement.limit.increaseEnabled: false
memoryManagement.limit.decreaseEnabled: false
```

These fields are not applied because label-grouped workloads often run multiple revisions with different specs. Having a single spec for such workloads would may lead to inaccurate recommendations. Instead, PerfectScale derives recommendations from **aggregated usage data** across all revisions.

**What still works:**

Absolute bounds are always respected, regardless of grouping:

* `cpuManagement.request.minimumCores` / `maximumCores`
* `memoryManagement.request.minimumGiB` / `maximumGiB`
* `memoryManagement.limit.minimumGiB` / `maximumGiB`

**How to restore spec-relative behavior:**

If you need spec-relative restrictions for a specific grouped workload, add this label:

```bash
perfectscale.io/workload-grouping-honor-spec: true
```

{% endhint %}

{% hint style="info" %}
If you enable automation for a custom workload type, the WorkloadLabelsSelector 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](/enable-automation/configuring-automation-with-crd/including-a-cluster-namespace-or-workload-to-the-automation/configuring-automation-for-a-namespace-with-crd.md) or [workload-level](/enable-automation/configuring-automation-with-crd/including-a-cluster-namespace-or-workload-to-the-automation/configuring-automation-for-a-workload-with-crd.md) 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.perfectscale.io/customize-workflow/ephemeral-workloads-grouping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.