feat(annotations): add new docs MTA-7143

menu/navigation.ts

@@ -2,6 +2,7 @@
 // for its associated menu naming, to avoid breaking tooling
 import { accountMenu } from '../pages/account/menu'
 import { appleSiliconMenu } from '../pages/apple-silicon/menu'
+import { annotationsMenu } from '../pages/annotations/menu'
 import { auditTrailMenu } from '../pages/audit-trail/menu'
 import { billingMenu } from '../pages/billing/menu'
 import { blockStorageMenu } from '../pages/block-storage/menu'
@@ -74,8 +75,8 @@ export default [
     items: [
       {
         icon: 'OrganizationDashboardCategoryIcon',
-        items: [accountMenu],
-        label: 'Account',
+        items: [accountMenu, organizationsAndProjectsMenu, annotationsMenu],
+        label: 'Account & Organization',
         category: 'console',
       },
       {
@@ -89,7 +90,6 @@ export default [
         items: [
           iamMenu,
           keyManagerMenu,
-          organizationsAndProjectsMenu,
           secretManagerMenu,
         ],
         label: 'Security & Identity',
@@ -124,18 +124,6 @@ export default [
         label: 'Containers',
         category: 'containers',
       },
-      {
-        icon: 'DatabaseCategoryIcon',
-        items: [
-          managedDatabasesForPostgresqlAndMysqlMenu,
-          managedDatabasesForRedisMenu,
-          managedMongodbDatabasesMenu,
-          openSearchMenu,
-          serverlessSqlDatabasesMenu,
-        ],
-        label: 'Databases',
-        category: 'databases',
-      },
       {
         icon: 'DataAndAnalyticsCategoryIcon',
         items: [
@@ -148,6 +136,18 @@ export default [
         label: 'Data & Analytics',
         category: 'data-and-analytics',
       },
+      {
+        icon: 'DatabaseCategoryIcon',
+        items: [
+          managedDatabasesForPostgresqlAndMysqlMenu,
+          managedDatabasesForRedisMenu,
+          managedMongodbDatabasesMenu,
+          openSearchMenu,
+          serverlessSqlDatabasesMenu,
+        ],
+        label: 'Databases',
+        category: 'databases',
+      },
       {
         icon: 'DevToolsCategoryIcon',
         items: [scalewayCliMenu, scalewaySdkMenu, terraformMenu],
@@ -192,6 +192,12 @@ export default [
         label: 'Network',
         category: 'network',
       },
+      {
+        icon: 'LabsCategoryIcon',
+        items: [quantumComputingMenu],
+        label: 'Quantum',
+        category: 'quantum',
+      },
       {
         icon: 'ServerlessComputeCategoryIcon',
         items: [
@@ -202,12 +208,6 @@ export default [
         label: 'Serverless',
         category: 'serverless',
       },
-      {
-        icon: 'LabsCategoryIcon',
-        items: [quantumComputingMenu],
-        label: 'Quantum',
-        category: 'quantum',
-      },
       {
         icon: 'StorageCategoryIcon',
         items: [
@@ -268,4 +268,4 @@ export default [
     ],
     label: 'Additional Services',
   },
-]
+]

pages/annotations/concepts/glossary.mdx

@@ -0,0 +1,71 @@
+---
+title: Annotations - Glossary
+description: Learn fundamental concepts of Scaleway 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/concepts/index.mdx

@@ -0,0 +1,4 @@
+---
+title: Annotations - Concepts
+description: Understand key concepts related to Scaleway Annotations.
+---

pages/annotations/faq.mdx

@@ -0,0 +1,48 @@
+---
+title: Annotations - FAQ
+description: Get answers on using Scaleway 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`).
+
+### What is the difference between tags and annotations?
+
+**Tags** are free-form labels that you can attach to individual resources to help organize, sort, filter, and monitor them. Each Scaleway product (e.g., [Instances](/instances/concepts/#tags), [Elastic Metal](/elastic-metal/concepts/#tags)) manages its own tags. They are simple strings with no predefined structure, and they are not shared across products or across the Organization as a whole.
+
+**Annotations** are structured key-value metadata that you can attach to a Scaleway resource. An annotation consists of a **key** (e.g., `Team`, `Environment`, `Cost-center`) and a **value** (e.g., `Marketing`, `Production`, `83546`), which are stored in a centralized dictionary. Once created, keys and values can be bound to your resources using their [Scaleway Resource Name (SRN)](/annotations/reference-content/scaleway-resource-name/). This centralized, structured approach makes annotations suitable for FinOps, GreenOps, and governance use cases such as cost allocation, reporting, auditing, and automation, and it comes with dedicated [IAM permission sets](/annotations/how-to/configure-annotations-permissions/) to control who can manage keys, values, and bindings.
+
+In short:
+
+- **Tags** are quick, informal labels scoped to a single product, ideal for simple sorting and filtering.
+- **Annotations** are formal, governed, Organization-wide key-value metadata, ideal for cross-product organization, cost management, and governance.
+
+## 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**.