Environment Annotations

Important

Please note that the "Environment Annotations" feature will be deprecated as of end of 2024 and will no longer be supported or available.

We recommend transitioning to our new "Environment Labels" solution, which offers enhanced capabilities and improved integration.

Thank you for your understanding and support.

Environment Annotations: What They Are and How you can leverage them to optimize processes

Environment annotations are labels or metadata that can be added to environments to provide additional information about them. Annotations can be used to define the purpose, status, or configuration of an environment, as well as to track changes or updates.

Annotations in Torque are key-value pairs that can be added to an environment or resource using a specific syntax or format. They can be used to add descriptive information, such as the description of an environment, or to provide dynamic updates, such as the current status of an environment or the results of a test.

Annotations can help teams manage and organize environments in Torque by providing an easy way to track and communicate important information about them. For example, annotations can be used to indicate the power-state status of virtual machines in the environment.

Environment annotations are a powerful tool for managing and organizing environments, and can help teams streamline their software development and testing processes by providing clear and concise information about the resources they are working with.

To create an environment annotation:

Since environment annotations are dynamic attributes of the environments, Torque uses rego files and the policy engine to evaluate the annotation upon any change in the environment.

Step 1: Create a rego file

1. In your git repository, create a rego file with torque.annotation package name.
2. The input to the rego evaluation is the introspection data from the environment. i.e a list of all the environment resources and their attributes, as a json object. The object will vary depending on the exact environment resources, but its overall structure will be as follows:

   {
     "introspection_resources": [
       {
         "attributes": {
           "att1": "att1",
           "att2":  "{\"key\": \"value\"}"
           ...
         }
       },
       {
         "attributes": {
           ...
         }
       },
       {
         // more resources
       }
     ]
   }

3. Using the introspection input, create your rule for the annotation and return an object named "set_annotations" with the following structure:

   "set_annotations" = ["key" : "key1", "value" : "value1"]

Let's take a look at a full example of how this rego file would look. In this evaluation file, we are evaluating the power state of virtual machines inside the environment. If there is even one virtual machine which is running, we will annotate the environment with "Power:On" annotation. If all of the virtual machines are stopped, the annotation will be "Power:Off".

package torque.annotations  // Use this as the first line to signal to Torque that this file is for evaluating environment annotations.

default set_annotations = [{"key": "power", "value": "off"}] // Unless we will find at least one running VM, we will return this default annotation of "Power:Off". 

set_annotations = [{"key": "power", "value": "on"}] { 

  resources_with_power_state_running = {r | r = input.introspection_resources[_]; r.attributes.power_state == "running"} 
  // In this case, every virtual machine has an attribute named "power_state" which can be either "running" or "stopped". We are iterating through all the power_state attribute values which are equal to "running".

  count(resources_with_power_state_running) > 0 // If there is at least 1, we return "Power:On".
}

Note

Currently the only supported annotations are "power:on", "power:off" and "power:torque.remove". We will add more annotations and open it for custom annotations soon. "torque.remove" is a general annotation value which may be used with any key. It signals to Torque to remove the annotation completely from the environment. A good example of when to use it is when the environment is ended.

Step 2: Import the rego file into Torque

1. If the git repository where the relevant rego file resides was not yet connected to Torque, perform the following :

   1. Go to Governance > Policy Repositories and click Add Repository.
   2. In the Select a Repository Provider step, choose your git provider and click Next.
   3. In the Connection step, enter the repository's URL, name, and branch, provide credentials if the repository is private, and click Connect. For details, see repository onboarding.

   

   A green checkmark in the repository's Status column indicates that the repository has been added successfully.

   

2. Go to Governance > Policies and click Add Policy.

3. Under Select a repository for policies discovery, click the tile of the repository where the file resides.

4. In Repository Folders, select the rego file you want to import into Torque, and click Generate Policies.

   

   The generated policy is displayed in the Policies page.

   

5. Click the ⋮ (3-dot) menu at the end of the policy's row and select Edit.

   a. Optionally change the Name, and provide a Description.

   b. In Spaces, set the scope of the policy - All spaces or specific ones.

6. Click Save.

7. Turn on the policy's Enable toggle in the Policies list.