feat(annotations): add new docs MTA-7143

menu/navigation.ts

@@ -3,6 +3,7 @@
 import { accountMenu } from '../pages/account/menu'
 import { appleSiliconMenu } from '../pages/apple-silicon/menu'
 import { auditTrailMenu } from '../pages/audit-trail/menu'
+import { annotationsMenu } from '../pages/annotations/menu'
 import { billingMenu } from '../pages/billing/menu'
 import { blockStorageMenu } from '../pages/block-storage/menu'
 import { classicHostingMenu } from '../pages/classic-hosting/menu'
@@ -78,6 +79,12 @@ export default [
         label: 'Account',
         category: 'console',
       },
+      {
+        icon: 'AnnotationsCategoryIcon',
+        items: [annotationsMenu],
+        label: 'Annotations',
+        category: 'console',
+      },      
       {
         icon: 'CostAndImpactManagementCategoryIcon',
         items: [billingMenu, environmentalFootprintMenu],

pages/annotations/concepts.mdx

@@ -0,0 +1,71 @@
+---
+title: Annotations - Concepts
+description: Learn fundamental concepts of Scaleway's Annotations.
+tags: annotations custom metadata
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+
+## Annotations
+
+Scaleway Annotations lets you attach custom key‑value metadata to any cloud resource. Using Annotations, you can organize and structure your instances, buckets, databases, etc., for use in FinOps, GreenOps, governance, and other applications.
+
+## Annotation
+
+An annotation is custom metadata you can attach to any Scaleway resource (instances, buckets, databases, etc.). It consists of a key (the category of information for a resource) and a value (the concrete information associated with a category).
+
+## Binding
+
+A binding is the explicit association that links an annotation to a specific resource. In other words, a binding records which resource the annotation applies to.
+
+## Key
+
+An annotation key is a globally-unique identifier (typically a plain‑text string) that names the piece of metadata you want to attach to a resource. The key defines the category of information for a resource (e.g., Team, Environment, Cost-center).
+
+For example:
+
+| Key         | Value                      |
+| ----------- | -------------------------- |
+| Team        | Marketing, Finance, Sales |
+| Environment | Staging, Production        |
+| Cost-center | 83546, 32424, 47847        |
+
+
+A key-[value](#value) pair constitutes an [annotation](#annotation).
+
+## Scaleway Resource Name
+
+The Scaleway Resource Name (SRN) is a Uniform Resource Identifier (URI) that uniquely identifies a Scaleway resource. It takes the following format:
+
+```
+srn://product-slug.domain/(locality_type/{locality}/)resource-type/resource-id
+
+```
+
+For example:
+
+```
+srn://k8s.scw.eu/regions/fr-par/clusters/25f6c309-a2c6-4fb2-8d16-57960c3fb9df
+
+```
+
+An SRN must be globally unique, immutable, human-comprehensible, and optimized for programmatic handling (e.g., generating a console URL).
+
+In the context of Annotations, you are required to provide an SRN when attaching a key-value pair to a selected cloud resource via the Annotations API.
+
+## Value
+
+An annotation value is the concrete information (e.g., Marketing, Production, 83546) associated with a category, i.e., an annotation [key](#key).
+
+A value cannot exist on its own, it must always be a child of a key.
+
+For example:
+
+| Key         | Value                      |
+| ----------- | -------------------------- |
+| Team        | Marketing, Finance, Sales |
+| Environment | Staging, Production        |
+| Cost-center | 83546, 32424, 47847        |
+
+A [key](#key)-value pair constitutes an [annotation](#annotation).

pages/annotations/faq.mdx

@@ -0,0 +1,37 @@
+---
+title: Annotations - FAQ
+description: Get answers on using Scaleway's Annotations to manage and organize your resources using custome key-value metadata
+productIcon: AnnotationsProductIcon
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+
+## Overview
+
+### What is Annotations?
+
+Scaleway Annotations lets you attach custom key‑value metadata to any Scaleway resource. Using Annotations, you can organize and structure your instances, buckets, databases, etc., for use in FinOps, GreenOps, governance, and other initiatives.
+
+### Why do I need Annotations?
+
+Annotations gives you a lightweight, flexible way to add structured metadata to any Scaleway resource, making it easier to search, manage, audit, and optimize your resources.  
+
+Using Annotations helps you:
+
+- **Organize and discover resources** – Annotate resources so you can filter and search by environment, team, cost‑center, or any custom attribute.  
+- **Automate workflows** – Trigger scripts, policies, or scaling actions based on specific annotation values (e.g., automatically back‑up all resources with the annotation `environment=prod`).  
+- **Control costs and reporting** – Use annotations for precise budgeting reports, grouping resources by project, department, or product line.  
+- **Enforce governance** – Combine annotations with IAM or policy bindings to restrict actions on resources that carry certain annotations (e.g., only the `security` team can modify resources marked `sensitive=true`).  
+
+## Pricing and billing
+
+### How am I billed for using Annotations?
+
+Annotations is free of charge.
+
+## Compatibility and integration
+
+### Which Scaleway products are integrated with Annotations?
+
+All Scaleway products support Annotations, i.e., you can bind annotations to any of your Scaleway resources.

pages/annotations/how-to/bind-and-detach-annotations.mdx

@@ -0,0 +1,67 @@
+---
+title: Bind and detach annotations
+description: Learn how to bind an annotation to a resource or detach it when it is not needed anymore
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+
+This page shows you how to bind and detach [annotations](/annotations/concepts/#annotation) via the Scaleway console.
+
+<Requirements />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- One of the following permission sets:
+  - `AnnotationsFullAccess`: gives you full access to keys, values, and bindings
+  - `AnnotationsBindingManager`: allows you to create/delete bindings
+
+## Configure the Annotations permission set
+
+To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam).
+
+Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how.
+
+## Bind an annotation to a resource
+
+You can bind an annotation to a resource either while creating the resource or when the resource is already in place.
+
+To bind an annotation to a resource that *already exists*:
+
+1. Navigate to your resource in the [console](https://console.scaleway.com/), and click the **Settings** tab.
+
+2. In the **Annotations** panel, use the dropdown to select the key, then the value. The key and value display under the **Key** and **Value** fields. The annotation is now attached to your resource.
+
+To bind an annotation to a resource *while creating it*, use the creation wizard.
+
+1. When you get to the point in the wizard where you can enter a name and description for your resource, find the **Annotations** section.
+
+2. Use the dropdown to select a key, then a value. The key and value display under the **Key** and **Value** fields. The annotation is now attached to your resource.
+
+## Detach an annotation from a resource
+
+You can detach an annotation from a resource either via the Annotations page or directly from the resource's page.
+
+### Via the Annotations page
+
+1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The **Annotations** product page displays.
+
+2. Use the search fields to find the key and value that you want to detach from your resource.
+
+3. Click the name of the relevant key. The **Keys** page appears.
+
+4. Click the name of the relevant value. The **Values** page appears.
+
+5. Use the search fields to find your resource.
+
+6. Click <Icon name="unlink" /> next to the resource that you wish to detach. In the window that pops up, click **Confirm**.
+
+### Via the resource's page
+
+1. Navigate to your resource in the [console](https://console.scaleway.com/).
+
+2. Once on the resource's dashboard page, click the **Settings** tab.
+
+3. In the **Annotations** panel, click **X** next to the key and value that you want to detach. Both the selected key and value disappear under the **Key** and **Value** fields. The annotation is now detached from your resource.

pages/annotations/how-to/configure-annotations-permissions.mdx

@@ -0,0 +1,32 @@
+---
+title: Configure Annotations permission sets
+description: Learn how to configure IAM permissions for accessing Scaleway's Annotations, enabling the usage of custom metadata across Organizations and Projects.
+tags: annotations custom metadata iam permissions
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+To start using Annotations, you need to configure one of the following permission sets in [IAM](/iam/concepts/#iam):
+  - `AnnotationsFullAccess`: Full access to [annotations](/annotations/concepts/#annotation) ([keys](/annotations/concepts/#key), [values](/annotations/concepts/#value), and [bindings](/annotations/concepts/#binding)).
+  - `AnnotationsReadOnly`: Read-only access to annotations. Typical users are auditors or finance team members (e.g., a FinOps analyst who can view and filter by annotation but cannot modify anything).
+  - `AnnotationsBindingManager`: Allows attaching annotations to resources, but prohibits modifying the annotation dictionary. Typical users are developers (including Terraform) who need the dictionary for autocomplete and must be able to create/delete bindings, but must not add or modify keys/values.
+
+This page shows you how to configure the necessary IAM permission set to access [Annotations](/annotations/concepts/#annotations).
+
+<Requirements />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+
+1. Click **IAM & API keys** on the top-right dropdown selector of the Scaleway console. The **Users** tab of the [Identity and Access Management dashboard](https://console.scaleway.com/iam/users) displays.
+2. Refer to the page on how to [create an IAM policy](/iam/how-to/create-policy/) and follow steps one to five.
+3. Select the **Access to Organization features** scope and click **Validate** to move on to the next step.
+    <Message type="important">
+     The **Access to Organization features** scope allows you to give the [principal](/iam/concepts/#principal) permissions to Organization-level features such as IAM, billing, support and abuse tickets, and project management.
+    </Message>
+4. Click the **Annotations** category in the **Products** section, then choose the appropriate **Annotations** permission set.
+5. Click **Validate**.
+6. Click **Validate** again.
+7. Click **Create policy**.

pages/annotations/how-to/create-annotations.mdx

@@ -0,0 +1,75 @@
+---
+title: Create annotations
+description: Learn how to create an annotation
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+
+This page shows you how to create an [annotation](/annotations/concepts/#annotation) via the Scaleway console.
+
+<Requirements />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings
+
+## Configure the Annotations permission set
+
+To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam).
+
+Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how.
+
+## Create an annotation
+
+You can create an annotation via the Annotations page dedicated to creating and managing annotations, or via the creation wizard of a resource while creating the resource.
+
+### Via the Annotations page
+
+1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The **Annotations** product page displays.
+
+2. Click **Create an annotation**. The creation wizard displays.
+
+3. Enter a name for your key, and optionally a description (to give a brief summary of the purpose or meaning of the key).
+    - **Key name**:
+      - Must be a unique string without spaces
+      - Maximum length: 128 characters
+      - Allowed values: [a-zA-Z0-9+.-_:/@]
+    - **Description**: 
+      - Maximum length: 1024 characters
+      - Allowed values: No restrictions
+
+4. Enter a value, and optionally a description (to give a brief summary of the purpose or meaning of the value).
+    - **Value name**:
+      - Maximum length: 256 characters
+      - Allowed values: [a-zA-Z0-9+.-_:/@]
+    - **Description**: 
+      - Maximum length: 1024 characters
+      - Allowed values: No restrictions
+
+5. Enter more values if needed, using the **Add value** button.
+
+6. Click **Create an annotation**.
+
+Once you have created an annotation, you can [bind it to one or more Scaleway resources](/annotations/how-to/bind-and-detach-annotations).
+
+### Via a resource's creation wizard
+
+When you are creating a resource and get to the point in the wizard where you can enter a name and description for your resource, you have the option to also attach an annotation key-value pair. If none of the existing key-value pairs apply that are available in the dropdown, create a brand new annotation.
+
+1. Click the **Create annotation** button. 
+
+2. In the window that pops up, enter a name for your key.
+
+3. Enter a value, and optionally a description (to give a brief summary of the purpose or meaning of the value).
+
+4. Enter more values if needed.
+
+5. Click **Create**.
+
+    Once you have created an annotation, you can bind it to your resource.
+
+6. Using the dropdown selector, select the key and then the value you have just created. Both the key and value display under the **Key** and **Value** fields. The annotation is now attached to your resource.
+

pages/annotations/how-to/delete-keys-values.mdx

@@ -0,0 +1,71 @@
+---
+title: Delete annotation keys and values
+description: Learn how to delete annotation keys and values
+dates:
+  validation: 2026-06-26
+  posted: 2026-06-26
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+
+This page shows you how to delete annotation [keys](/annotations/concepts/#key) and [values](/annotations/concepts/#value) via the Scaleway console.
+
+<Requirements />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings
+
+## Configure the Annotations permission set
+
+To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam).
+
+Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how.
+
+## Delete a key
+
+1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays.
+
+2. Use the search field to find your key.
+
+3. Click <Icon name="more" /> next to the key you want to delete. Click **Delete key** in the menu.
+
+    Alternatively, click the name of the key that you want to delete. You are taken to the key's dashboard page. Click **Actions** in the top right and select **Delete key**. 
+
+    The **Delete key** window pops up, asking you to confirm the deletion of your key.
+
+4. *If the key has no associated value*, click **Confirm**. Your key has now been deleted.
+
+5. *If the key has some associated values and maybe even resources*, deleting the key will break those associations. You must [remove bindings](#detach-a-resource-from-a-value) and [delete values](#delete-a-value) first. After removing the bindings and values, you can come back and delete the key.
+
+## Delete a value
+
+1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays.
+
+2. Use the search field to find the key whose value you want to delete.
+
+3. Click the relevant key. You are taken to the key's overview page. 
+
+4. Click <Icon name="more" /> next to the value you want to edit. Click **Delete value** in the menu. The **Delete value** window pops up, asking you to confirm the deletion of your value.
+
+    Alternatively, click the value that you want to delete. You are taken to the value's dashboard page. Click **Actions** in the top right and select **Delete value**. The **Delete value** window pops up, asking you to confirm the deletion of your value.
+
+5. *If the value is not bound to any resource*, click **Confirm**. Your value has now been deleted.
+
+6. *If the value is bound to one or more resources*, you must [remove the binding](#detach-a-resource-from-a-value) first. After removing the associated resources, you can come back and delete the value.
+
+## Detach a resource from a value
+
+1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays.
+
+2. Click the key whose value you want to edit. You are taken to the key's overview page. 
+
+3. Click the name of the value that you want to edit. You are taken to the value's overview page. 
+
+    You have the following options at this point:
+      - Bulk detach all resources associated with the value
+      - Detach one or more resources one by one
+
+4. *To bulk detach all resources associated with the value*, click the **Detach all** button. In the window that pops up, click **Confirm**.
+
+5. *To detach a single resource from the value*, click <Icon name="unlink" /> next to the resource that you wish to detach. In the window that pops up, click **Confirm**.