From 759b25654e35e1de0705357a07d3f0966dcb4272 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Mon, 22 Jun 2026 18:03:39 +0200 Subject: [PATCH 01/10] feat(annotations): add menu, index, concepts, placeholder docs MTA-7143 --- menu/navigation.ts | 7 ++++ pages/annotations/concepts.mdx | 65 ++++++++++++++++++++++++++++++++ pages/annotations/faq.mdx | 40 ++++++++++++++++++++ pages/annotations/index.mdx | 60 +++++++++++++++++++++++++++++ pages/annotations/menu.ts | 60 +++++++++++++++++++++++++++++ pages/annotations/quickstart.mdx | 31 +++++++++++++++ 6 files changed, 263 insertions(+) create mode 100644 pages/annotations/concepts.mdx create mode 100644 pages/annotations/faq.mdx create mode 100644 pages/annotations/index.mdx create mode 100644 pages/annotations/menu.ts create mode 100644 pages/annotations/quickstart.mdx diff --git a/menu/navigation.ts b/menu/navigation.ts index 953e8c5365..06d9eaea1e 100644 --- a/menu/navigation.ts +++ b/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], diff --git a/pages/annotations/concepts.mdx b/pages/annotations/concepts.mdx new file mode 100644 index 0000000000..6355ae9c1e --- /dev/null +++ b/pages/annotations/concepts.mdx @@ -0,0 +1,65 @@ +--- +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, security, and other applications. + +## Annotation + +An annotation is a user‑defined piece of metadata that can be attached to any Scaleway resource (instances, buckets, databases, etc.). It consists of a key (the name of the attribute) and a value (the data associated with that key). + +## 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. Bindings enable you to trigger actions (e.g., ???) or ??? based on those attached annotations. {/* Need examples. */} + +## Key + +An annotation key is a user‑defined identifier (typically a plain‑text string) that names the piece of metadata you want to attach to a resource. The key conveys the type or purpose of the information (e.g., team, environment, owner, cost-center). + +For example: + +| Key | Value | +| ----------- | --------------------- | +| Team | Admin, Billing, Sales | +| Environment | Staging, Production | + + +Together with a [value](#value), they form 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. {/* Is the SRN relevant for the console? */} + +## Value + +An annotation value is the data associated with an annotation [key](#key). It holds the actual information you want to store (e.g., sales, production, alice@example.com, 12345). + +For example: + +| Key | Value | +| ----------- | --------------------- | +| Team | Admin, Billing, Sales | +| Environment | Staging, Production | \ No newline at end of file diff --git a/pages/annotations/faq.mdx b/pages/annotations/faq.mdx new file mode 100644 index 0000000000..f700d36c69 --- /dev/null +++ b/pages/annotations/faq.mdx @@ -0,0 +1,40 @@ +--- +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 cloud resource. Using Annotations, you can organize and structure your instances, buckets, databases, etc., for use in FinOps, GreenOps, security, and other applications. + +### Why do I need Annotations? + +placeholder + +## Specifications + +### Placeholder + +placeholder + +## Pricing and billing + +### How am I billed for using Annotations? + +Annotations is free of charge. + +### Placeholder? + +placeholder + +## Compatibility and integration + +### Which Scaleway products are integrated with Annotations? + +placeholder \ No newline at end of file diff --git a/pages/annotations/index.mdx b/pages/annotations/index.mdx new file mode 100644 index 0000000000..300c872350 --- /dev/null +++ b/pages/annotations/index.mdx @@ -0,0 +1,60 @@ +--- +title: Annotations Documentation +description: Dive into Scaleway Annotations with our quickstart guides, how-tos, and more. +--- + + + +## Getting Started + + + + + + + + + + +## Changelog + + diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts new file mode 100644 index 0000000000..1e70083d2b --- /dev/null +++ b/pages/annotations/menu.ts @@ -0,0 +1,60 @@ +export const annotationsMenu = { + items: [ + { + label: 'Overview', + slug: '../annotations', + }, + { + label: 'Concepts', + slug: 'concepts', + }, + { + label: 'Quickstart', + slug: 'quickstart', + }, + { + label: 'FAQ', + slug: 'faq', + }, + { + items: [ + { + label: 'XXX', + slug: 'xxx', + }, + { + label: 'YYY', + slug: 'yyy', + }, + { + label: 'ZZZ', + slug: 'zzz', + }, + ], + label: 'How to', + slug: 'how-to', + }, + { + items: [ + { + label: 'Annotations API Reference', + slug: 'https://www.scaleway.com/en/developers/api/annotations/', + }, + ], + label: 'API/CLI', + slug: 'api-cli', + }, + { + items: [ + { + label: 'Scaleway Resource Names', + slug: 'scaleway-resource-names', + }, + ], + label: 'Additional Content', + slug: 'reference-content', + }, + ], + label: 'Annotations', + slug: 'annotations', +} diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx new file mode 100644 index 0000000000..977d3dfda6 --- /dev/null +++ b/pages/annotations/quickstart.mdx @@ -0,0 +1,31 @@ +--- +title: Annotations - Quickstart +description: Quickly set up and start using Scaleway’s Annotations. Follow steps to configure custom key-value metadata for your resources. +dates: + validation: 2026-06-26 + posted: 2026-06-26 +--- +import Requirements from '@macros/iam/requirements.mdx' + + +In this quickstart, we show you how to start using [Annotations](/annotations/concepts/#annotations). + + + +- 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`: Full access to annotations (keys, values, and bindings). + - `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. + + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to use Annotations + +placeholder \ No newline at end of file From b98770c5f42bcd0687923c25864002ca59ed7a7b Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Tue, 23 Jun 2026 18:00:27 +0200 Subject: [PATCH 02/10] feat(annotations): refined concepts, FAQ, quickstart, added how-tos MTA-7143 --- pages/annotations/concepts.mdx | 32 ++++--- pages/annotations/faq.mdx | 19 ++-- .../configure-annotations-permissions.mdx | 26 ++++++ .../how-to/how-to-create-annotations.mdx | 52 +++++++++++ pages/annotations/menu.ts | 12 +-- pages/annotations/quickstart.mdx | 93 ++++++++++++++++++- 6 files changed, 199 insertions(+), 35 deletions(-) create mode 100644 pages/annotations/how-to/configure-annotations-permissions.mdx create mode 100644 pages/annotations/how-to/how-to-create-annotations.mdx diff --git a/pages/annotations/concepts.mdx b/pages/annotations/concepts.mdx index 6355ae9c1e..d364aa6cda 100644 --- a/pages/annotations/concepts.mdx +++ b/pages/annotations/concepts.mdx @@ -13,25 +13,26 @@ Scaleway Annotations lets you attach custom key‑value metadata to any cloud re ## Annotation -An annotation is a user‑defined piece of metadata that can be attached to any Scaleway resource (instances, buckets, databases, etc.). It consists of a key (the name of the attribute) and a value (the data associated with that key). +An annotation is metadata you can be attach to any Scaleway resource (instances, buckets, databases, etc.). It consists of a key (the name of the attribute) and a value (the data associated with that key). ## 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. Bindings enable you to trigger actions (e.g., ???) or ??? based on those attached annotations. {/* Need examples. */} +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 user‑defined identifier (typically a plain‑text string) that names the piece of metadata you want to attach to a resource. The key conveys the type or purpose of the information (e.g., team, environment, owner, cost-center). +An annotation key is a unique identifier (typically a plain‑text string) that names the piece of metadata you want to attach to a resource. The key conveys the type or purpose of the information (e.g., team, environment, cost-center). For example: -| Key | Value | -| ----------- | --------------------- | -| Team | Admin, Billing, Sales | -| Environment | Staging, Production | +| Key | Value | +| ----------- | -------------------------- | +| Team | Operations, Finance, Sales | +| Environment | Staging, Production | +| Cost-center | 83546, 32424, 47847 | -Together with a [value](#value), they form an [annotation](#annotation). +A key-[value](#value) pair constitutes an [annotation](#annotation). ## Scaleway Resource Name @@ -51,15 +52,18 @@ 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. {/* Is the SRN relevant for the console? */} +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.{/* Is the SRN relevant for the console? */} ## Value -An annotation value is the data associated with an annotation [key](#key). It holds the actual information you want to store (e.g., sales, production, alice@example.com, 12345). +An annotation value is the data associated with an annotation [key](#key). It holds the actual information you want to store (e.g., sales, production, 83546). For example: -| Key | Value | -| ----------- | --------------------- | -| Team | Admin, Billing, Sales | -| Environment | Staging, Production | \ No newline at end of file +| Key | Value | +| ----------- | -------------------------- | +| Team | Operations, Finance, Sales | +| Environment | Staging, Production | +| Cost-center | 83546, 32424, 47847 | + +A [key](#key)-value pair constitutes an [annotation](#annotation). \ No newline at end of file diff --git a/pages/annotations/faq.mdx b/pages/annotations/faq.mdx index f700d36c69..2ea278918b 100644 --- a/pages/annotations/faq.mdx +++ b/pages/annotations/faq.mdx @@ -1,5 +1,5 @@ --- -title: Annotations FAQ +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: @@ -15,13 +15,14 @@ Scaleway Annotations lets you attach custom key‑value metadata to any cloud re ### Why do I need Annotations? -placeholder +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. -## Specifications +Using Annotations helps you: -### Placeholder - -placeholder +- **Organize and discover resources** – Annotate instances, buckets, databases, etc., 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 @@ -29,12 +30,8 @@ placeholder Annotations is free of charge. -### Placeholder? - -placeholder - ## Compatibility and integration ### Which Scaleway products are integrated with Annotations? -placeholder \ No newline at end of file +All Scaleway products support Annotations, i.e., you can bind annotations to any of your Scaleway resources. \ No newline at end of file diff --git a/pages/annotations/how-to/configure-annotations-permissions.mdx b/pages/annotations/how-to/configure-annotations-permissions.mdx new file mode 100644 index 0000000000..90e5156fe9 --- /dev/null +++ b/pages/annotations/how-to/configure-annotations-permissions.mdx @@ -0,0 +1,26 @@ +--- +title: How to configure the Annotations permission set +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 +--- + +This page teaches you how to configure the necessary IAM permission set to access [Annotations](/annotations/concepts/#annotations). + +To start using Annotations, you need to configure one of the following permission sets in [IAM](/iam/concepts/#iam): + - `AnnotationsFullAccess`: Full access to annotations (keys, values, and bindings). + - `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. + +1. Click **IAM & API keys** on the top-right drop-down menu 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. + + The **Access to Organization features** scope allows you to give the [principal](/iam/concepts/#principal) permissions to Organization-level features such as IAM, Annotations, billing, support tickets, and project management. + +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**. diff --git a/pages/annotations/how-to/how-to-create-annotations.mdx b/pages/annotations/how-to/how-to-create-annotations.mdx new file mode 100644 index 0000000000..74c43a1c9d --- /dev/null +++ b/pages/annotations/how-to/how-to-create-annotations.mdx @@ -0,0 +1,52 @@ +--- +title: How to create Annotations +description: Learn how to create an annotation that you can then bind to your Scaleway resources. +dates: + validation: 2026-06-26 + posted: 2026-06-26 +--- +import Requirements from '@macros/iam/requirements.mdx' + + +In this quickstart, we show you how to start using [Annotations](/annotations/concepts/#annotations). + + + +- 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`: Full access to annotations (keys, values, and bindings). + - `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. + + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to create an annotation + +1. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. + +2. Click **Create 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 for it (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. Click **Create Annotation**. The list of your current annotations is displayed. \ No newline at end of file diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts index 1e70083d2b..f568ddf429 100644 --- a/pages/annotations/menu.ts +++ b/pages/annotations/menu.ts @@ -19,16 +19,12 @@ export const annotationsMenu = { { items: [ { - label: 'XXX', - slug: 'xxx', + label: 'Configure the Annotations permission sets', + slug: 'configure-annotations-permissions', }, { - label: 'YYY', - slug: 'yyy', - }, - { - label: 'ZZZ', - slug: 'zzz', + label: 'Create annotations', + slug: 'how-to-create-annotations', }, ], label: 'How to', diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 977d3dfda6..2568ee6f10 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -26,6 +26,95 @@ To start using Annotations, you need to configure permission sets in [IAM](/iam/ Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to use Annotations +## How to create an annotation + +1. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. + +2. Click **Create Annotation**. The creation wizard displays. + +3. Enter a unique name for your key, and optionally a description (to give a brief summary of the purpose or meaning of the key). + +4. Enter a value, and optionally a description for it (to give a brief summary of the purpose or meaning of the value). + +5. Click **Create annotation**. The list of your current annotations is displayed. + +## How to 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. + +Here, you are going to bind the annotation that you have just created to a resource that already exists. + +1. Navigate to the **Settings** tab of your resource in the [console](https://console.scaleway.com/). + +2. In the **Annotations** panel, select the key and then the value from the drop-down list. Both the selected key and value display under the **Key** and **Value** fields. + +The annotation is now attached to your resource. + +## How to manage a key + +### How to edit a key + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** window pops up. + + Alternatively, click the key that you want to edit. You are taken to the key's dashboard page. Click **Actions** in the top right and select **Edit key**. The **Edit key** window pops up. + +3. Make your changes, then click **Update**. + +### How to delete a key + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Click 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. + +3. Click **Confirm**. + +## How to manage a value + +### How to edit a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. 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 next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** window pops up. + + Alternatively, click the name of the value that you want to edit. You are taken to the value's dashboard page. Click **Actions** in the top right and select **Edit value**. The **Edit value** window pops up. + +4. Make your changes, then click **Update**. + +### How to delete a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Click the key whose value you want to delete. You are taken to the key's overview page. + +3. Click 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. + +4. If the value is not bound to any resource, click **Confirm**. If the value is bound to one or more resources, you must [remove the binding](#how-to-detach-resources-from-a-value) first. Once the value is deleted, you are taken back to the key's dashboard page. + +### How to detach a resource from a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. 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**. You are taken back to the value's overview page. + +5. **To detach a single resource from the value**, click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the value's overview page. + + -placeholder \ No newline at end of file From 0cab55d713748cb0f37e8b17b8945d1dc9ee45a3 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Wed, 24 Jun 2026 09:17:42 +0200 Subject: [PATCH 03/10] feat(annotations): refined concepts, FAQ, quickstart, added how-tos MTA-7143 --- .../configure-annotations-permissions.mdx | 2 +- ...tations.mdx => how-to-use-annotations.mdx} | 33 +++++++++++++------ pages/annotations/menu.ts | 6 ++-- pages/annotations/quickstart.mdx | 11 +++---- 4 files changed, 31 insertions(+), 21 deletions(-) rename pages/annotations/how-to/{how-to-create-annotations.mdx => how-to-use-annotations.mdx} (55%) diff --git a/pages/annotations/how-to/configure-annotations-permissions.mdx b/pages/annotations/how-to/configure-annotations-permissions.mdx index 90e5156fe9..a27420fd42 100644 --- a/pages/annotations/how-to/configure-annotations-permissions.mdx +++ b/pages/annotations/how-to/configure-annotations-permissions.mdx @@ -1,5 +1,5 @@ --- -title: How to configure the Annotations permission set +title: How to 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: diff --git a/pages/annotations/how-to/how-to-create-annotations.mdx b/pages/annotations/how-to/how-to-use-annotations.mdx similarity index 55% rename from pages/annotations/how-to/how-to-create-annotations.mdx rename to pages/annotations/how-to/how-to-use-annotations.mdx index 74c43a1c9d..cb7fffb45b 100644 --- a/pages/annotations/how-to/how-to-create-annotations.mdx +++ b/pages/annotations/how-to/how-to-use-annotations.mdx @@ -1,6 +1,6 @@ --- -title: How to create Annotations -description: Learn how to create an annotation that you can then bind to your Scaleway resources. +title: How to use annotations +description: Learn how to create an annotation and bind to your Scaleway resources. dates: validation: 2026-06-26 posted: 2026-06-26 @@ -8,23 +8,19 @@ dates: import Requirements from '@macros/iam/requirements.mdx' -In this quickstart, we show you how to start using [Annotations](/annotations/concepts/#annotations). +This page shows you how to create an [annotation](/annotations/concepts/#annotation) and bind it to a resource via the Scaleway console. - 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`: Full access to annotations (keys, values, and bindings). - - `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. - +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings. ## How to configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). -Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. +Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. ## How to create an annotation @@ -49,4 +45,21 @@ Refer to the [dedicated documentation page](/annotations/how-to/configure-annota - Maximum length: 1024 characters - Allowed values: No restrictions -5. Click **Create Annotation**. The list of your current annotations is displayed. \ No newline at end of file +5. Click **Create Annotation**. The list of your current annotations is displayed. + +Once you have created an annotation, bind it to one or more Scaleway resources. + +## How to 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, select the key and then the value from the drop-down list. Both the selected 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**: + diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts index f568ddf429..772d21dfbd 100644 --- a/pages/annotations/menu.ts +++ b/pages/annotations/menu.ts @@ -19,12 +19,12 @@ export const annotationsMenu = { { items: [ { - label: 'Configure the Annotations permission sets', + label: 'Configure Annotations permission sets', slug: 'configure-annotations-permissions', }, { - label: 'Create annotations', - slug: 'how-to-create-annotations', + label: 'Use annotations', + slug: 'how-to-use-annotations', }, ], label: 'How to', diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 2568ee6f10..5f71e8a531 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -14,10 +14,7 @@ In this quickstart, we show you how to start using [Annotations](/annotations/co - 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`: Full access to annotations (keys, values, and bindings). - - `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. +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings. ## How to configure the Annotations permission set @@ -32,9 +29,9 @@ Refer to the [dedicated documentation page](/annotations/how-to/configure-annota 2. Click **Create Annotation**. The creation wizard displays. -3. Enter a unique name for your key, and optionally a description (to give a brief summary of the purpose or meaning of the key). +3. Enter a unique name for your key, and optionally a description. -4. Enter a value, and optionally a description for it (to give a brief summary of the purpose or meaning of the value). +4. Enter a value, and optionally a description for it. 5. Click **Create annotation**. The list of your current annotations is displayed. @@ -44,7 +41,7 @@ You can bind an annotation to a resource either while creating the resource or w Here, you are going to bind the annotation that you have just created to a resource that already exists. -1. Navigate to the **Settings** tab of your resource in the [console](https://console.scaleway.com/). +1. Navigate to your resource in the [console](https://console.scaleway.com/), and click the **Settings** tab. 2. In the **Annotations** panel, select the key and then the value from the drop-down list. Both the selected key and value display under the **Key** and **Value** fields. From fbdf6572d0cfdd9ea438aa5162a1acb7c72dfae1 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Thu, 25 Jun 2026 08:53:47 +0200 Subject: [PATCH 04/10] feat(annotations): refinements MTA-7143 --- .../how-to/how-to-use-annotations.mdx | 16 +++++++++++++++- pages/annotations/quickstart.mdx | 2 ++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/pages/annotations/how-to/how-to-use-annotations.mdx b/pages/annotations/how-to/how-to-use-annotations.mdx index cb7fffb45b..8303eb52cd 100644 --- a/pages/annotations/how-to/how-to-use-annotations.mdx +++ b/pages/annotations/how-to/how-to-use-annotations.mdx @@ -24,6 +24,10 @@ Refer to [How to configure Annotations permission sets](/annotations/how-to/conf ## How to 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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. 2. Click **Create Annotation**. The creation wizard displays. @@ -49,6 +53,10 @@ Refer to [How to configure Annotations permission sets](/annotations/how-to/conf Once you have created an annotation, bind it to one or more Scaleway resources. +### Via a resource's creation wizard + + + ## How to 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. @@ -61,5 +69,11 @@ To bind an annotation to a resource that **already exists**: The annotation is now attached to your resource. -To bind an annotation to a resource while **creating it**: +To bind an annotation to a resource while **creating it**, use the creation wizard. + +When you get to the point in the wizard where you can enter a name and description for your resource, you have the option to also select an existing annotation key-value pair. + +## How to 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. diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 5f71e8a531..8f6290b545 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -35,6 +35,8 @@ Refer to the [dedicated documentation page](/annotations/how-to/configure-annota 5. Click **Create annotation**. The list of your current annotations is displayed. +Alternatively, you can create an annotation directly via a resource's creation wizard and the **Create annotation** button. + ## How to 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. From 73893e604633c79bb6049c231115ddcf1e4d2fbf Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Thu, 25 Jun 2026 18:30:20 +0200 Subject: [PATCH 05/10] feat(annotations): refinements + new sections MTA-7143 --- .../how-to/bind-and-detach-annotations.mdx | 65 +++++++++++ .../annotations/how-to/create-annotations.mdx | 77 +++++++++++++ .../annotations/how-to/delete-keys-values.mdx | 73 ++++++++++++ .../how-to/how-to-use-annotations.mdx | 79 ------------- .../annotations/how-to/manage-keys-values.mdx | 108 ++++++++++++++++++ pages/annotations/menu.ts | 16 ++- pages/annotations/quickstart.mdx | 10 +- .../scaleway-resource-names.mdx | 26 +++++ 8 files changed, 366 insertions(+), 88 deletions(-) create mode 100644 pages/annotations/how-to/bind-and-detach-annotations.mdx create mode 100644 pages/annotations/how-to/create-annotations.mdx create mode 100644 pages/annotations/how-to/delete-keys-values.mdx delete mode 100644 pages/annotations/how-to/how-to-use-annotations.mdx create mode 100644 pages/annotations/how-to/manage-keys-values.mdx create mode 100644 pages/annotations/reference-content/scaleway-resource-names.mdx diff --git a/pages/annotations/how-to/bind-and-detach-annotations.mdx b/pages/annotations/how-to/bind-and-detach-annotations.mdx new file mode 100644 index 0000000000..10800c3767 --- /dev/null +++ b/pages/annotations/how-to/bind-and-detach-annotations.mdx @@ -0,0 +1,65 @@ +--- +title: How to bind and detach an 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. + + + +- 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` (gives you full access to keys, values, and bindings) or `AnnotationsBindingManager` (allows you to create/delete bindings) permission set. + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to 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, select the key and then the value from the drop-down list. Both the selected 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. + +When you get to the point in the wizard where you can enter a name and description for your resource, select an existing annotation key-value pair. + +## How to 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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. 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 next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the **Values** page. + +### Via the resource's page + +1. Navigate to your resource in the [console](https://console.scaleway.com/), and click the **Settings** tab. + +2. 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. \ No newline at end of file diff --git a/pages/annotations/how-to/create-annotations.mdx b/pages/annotations/how-to/create-annotations.mdx new file mode 100644 index 0000000000..66dd461e36 --- /dev/null +++ b/pages/annotations/how-to/create-annotations.mdx @@ -0,0 +1,77 @@ +--- +title: How to 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. + + + +- 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. + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to 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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. + +2. Click **Create 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**. The list of your current annotations is displayed. + +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 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, 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. + diff --git a/pages/annotations/how-to/delete-keys-values.mdx b/pages/annotations/how-to/delete-keys-values.mdx new file mode 100644 index 0000000000..a858f1156e --- /dev/null +++ b/pages/annotations/how-to/delete-keys-values.mdx @@ -0,0 +1,73 @@ +--- +title: How to 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. + + + +- 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. + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to delete a key + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Use the search field to find your key. + +3. Click 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 potentially even resources, deleting the key will break those associations. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. + + For details on how to detach resources from the associated values, see PLACEHOLDER. + +## How to delete a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Use the search field to find your key. + +3. Click the key whose value you want to delete. You are taken to the key's overview page. + +4. Click 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](#how-to-detach-resources-from-a-value) first. After removing the associated resources, you can come back and delete the value. + +## How to detach a resource from a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. 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**. You are taken back to the value's overview page. + +5. **To detach a single resource from the value**, click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the value's overview page. \ No newline at end of file diff --git a/pages/annotations/how-to/how-to-use-annotations.mdx b/pages/annotations/how-to/how-to-use-annotations.mdx deleted file mode 100644 index 8303eb52cd..0000000000 --- a/pages/annotations/how-to/how-to-use-annotations.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: How to use annotations -description: Learn how to create an annotation and bind to your Scaleway resources. -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) and bind it to a resource via the Scaleway console. - - - -- 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. - -## How to configure the Annotations permission set - -To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). - -Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. - -## How to 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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. - -2. Click **Create 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 for it (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. Click **Create Annotation**. The list of your current annotations is displayed. - -Once you have created an annotation, bind it to one or more Scaleway resources. - -### Via a resource's creation wizard - - - -## How to 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, select the key and then the value from the drop-down list. Both the selected 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. - -When you get to the point in the wizard where you can enter a name and description for your resource, you have the option to also select an existing annotation key-value pair. - -## How to 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. - diff --git a/pages/annotations/how-to/manage-keys-values.mdx b/pages/annotations/how-to/manage-keys-values.mdx new file mode 100644 index 0000000000..cea1330429 --- /dev/null +++ b/pages/annotations/how-to/manage-keys-values.mdx @@ -0,0 +1,108 @@ +--- +title: How to manage annotation keys and values +description: Learn how to manage 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 manage annotation [keys](/annotations/concepts/#key) and values(/annotations/concepts/#value) via the Scaleway console. + + + +- 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. + +## How to configure the Annotations permission set + +To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). + +Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. + +## How to manage keys + +### How to create a new key + +Once you already have some annotations in place, you may want to create a new key. + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Click the **Create key** button. The **Create annotation** window pops up. + +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**. The list of your current annotations is displayed. + +### How to edit a key + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Use the search field to find your key. + +3. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** window pops up. + + Alternatively, click the key that you want to edit. You are taken to the key's dashboard page. Click **Actions** in the top right and select **Edit key**. The **Edit key** window pops up. + +4. Make your changes, then click **Save**. + +## How to manage values + +### How to create a new value + +Once you already have some annotations in place, you may want to create a new value. + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Use the search field to find your key. + +3. Click the key whose value you want to edit. You are taken to the key's overview page. + +4. Click the **Create value** button. The **Create value** window pops up. + +5. Enter a name for the value and optionally a description too (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 + +6. Click **Create value**. Your value has been deleted and you are taken to the key's overview page. + +### How to edit a value + +1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. + +2. Use the search field to find your key. + +3. Click the key whose value you want to edit. You are taken to the key's overview page. + +4. Click next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** window pops up. + + Alternatively, click the name of the value that you want to edit. You are taken to the value's dashboard page. Click **Actions** in the top right and select **Edit value**. The **Edit value** window pops up. + +5. Make your changes, then click **Save**. + + + + diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts index 772d21dfbd..df46a3fbc0 100644 --- a/pages/annotations/menu.ts +++ b/pages/annotations/menu.ts @@ -23,8 +23,20 @@ export const annotationsMenu = { slug: 'configure-annotations-permissions', }, { - label: 'Use annotations', - slug: 'how-to-use-annotations', + label: 'Create annotations', + slug: 'create-annotations', + }, + { + label: 'Bind and detach annotations', + slug: 'bind-and-detach-annotations', + }, + { + label: 'Manage keys and values', + slug: 'manage-keys-values', + }, + { + label: 'Delete keys and values', + slug: 'delete-keys-values', }, ], label: 'How to', diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 8f6290b545..7df8283fde 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -33,7 +33,7 @@ Refer to the [dedicated documentation page](/annotations/how-to/configure-annota 4. Enter a value, and optionally a description for it. -5. Click **Create annotation**. The list of your current annotations is displayed. +5. Click **Create annotation**. Alternatively, you can create an annotation directly via a resource's creation wizard and the **Create annotation** button. @@ -57,9 +57,7 @@ The annotation is now attached to your resource. 2. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** window pops up. - Alternatively, click the key that you want to edit. You are taken to the key's dashboard page. Click **Actions** in the top right and select **Edit key**. The **Edit key** window pops up. - -3. Make your changes, then click **Update**. +3. Make your changes, then click **Save**. ### How to delete a key @@ -83,9 +81,7 @@ The annotation is now attached to your resource. 3. Click next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** window pops up. - Alternatively, click the name of the value that you want to edit. You are taken to the value's dashboard page. Click **Actions** in the top right and select **Edit value**. The **Edit value** window pops up. - -4. Make your changes, then click **Update**. +4. Make your changes, then click **Save**. ### How to delete a value diff --git a/pages/annotations/reference-content/scaleway-resource-names.mdx b/pages/annotations/reference-content/scaleway-resource-names.mdx new file mode 100644 index 0000000000..f72ca455fc --- /dev/null +++ b/pages/annotations/reference-content/scaleway-resource-names.mdx @@ -0,0 +1,26 @@ +--- +title: What is a Scaleway Resource Name (SRN)? +description: Learn more about Scaleway Resource Name (SRN). +tags: annotations custom metadata scaleway resource name +dates: + validation: 2026-06-26 + posted: 2026-06-26 +--- + +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.{/* Is the SRN relevant for the console? */} From d55e6aece529f907ebfba8303d54966daec44919 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Fri, 26 Jun 2026 07:55:25 +0200 Subject: [PATCH 06/10] feat(annotations): editorial refinements MTA-7143 --- pages/annotations/concepts.mdx | 16 ++--- pages/annotations/faq.mdx | 4 +- .../how-to/bind-and-detach-annotations.mdx | 34 +++++----- .../configure-annotations-permissions.mdx | 18 ++++-- .../annotations/how-to/create-annotations.mdx | 24 ++++--- .../annotations/how-to/delete-keys-values.mdx | 40 ++++++------ .../annotations/how-to/manage-keys-values.mdx | 46 +++++++------- pages/annotations/index.mdx | 4 +- pages/annotations/quickstart.mdx | 62 ++++++++++--------- 9 files changed, 129 insertions(+), 119 deletions(-) diff --git a/pages/annotations/concepts.mdx b/pages/annotations/concepts.mdx index d364aa6cda..5b56a27a79 100644 --- a/pages/annotations/concepts.mdx +++ b/pages/annotations/concepts.mdx @@ -9,11 +9,11 @@ dates: ## 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, security, and other applications. +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 metadata you can be attach to any Scaleway resource (instances, buckets, databases, etc.). It consists of a key (the name of the attribute) and a value (the data associated with that key). +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 @@ -21,13 +21,13 @@ A binding is the explicit association that links an annotation to a specific res ## Key -An annotation key is a unique identifier (typically a plain‑text string) that names the piece of metadata you want to attach to a resource. The key conveys the type or purpose of the information (e.g., team, environment, cost-center). +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 | Operations, Finance, Sales | +| Team | Marketing, Finance, Sales | | Environment | Staging, Production | | Cost-center | 83546, 32424, 47847 | @@ -52,17 +52,19 @@ 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.{/* Is the SRN relevant for the console? */} +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 data associated with an annotation [key](#key). It holds the actual information you want to store (e.g., sales, production, 83546). +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 | Operations, Finance, Sales | +| Team | Marketing, Finance, Sales | | Environment | Staging, Production | | Cost-center | 83546, 32424, 47847 | diff --git a/pages/annotations/faq.mdx b/pages/annotations/faq.mdx index 2ea278918b..5ae4125741 100644 --- a/pages/annotations/faq.mdx +++ b/pages/annotations/faq.mdx @@ -11,7 +11,7 @@ dates: ### What is 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, security, and other applications. +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? @@ -19,7 +19,7 @@ Annotations gives you a lightweight, flexible way to add structured metadata to Using Annotations helps you: -- **Organize and discover resources** – Annotate instances, buckets, databases, etc., so you can filter and search by environment, team, cost‑center, or any custom attribute. +- **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`). diff --git a/pages/annotations/how-to/bind-and-detach-annotations.mdx b/pages/annotations/how-to/bind-and-detach-annotations.mdx index 10800c3767..2c77732d0b 100644 --- a/pages/annotations/how-to/bind-and-detach-annotations.mdx +++ b/pages/annotations/how-to/bind-and-detach-annotations.mdx @@ -1,5 +1,5 @@ --- -title: How to bind and detach an annotations +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 @@ -14,37 +14,39 @@ This page shows you how to bind and detach [annotations](/annotations/concepts/# - 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` (gives you full access to keys, values, and bindings) or `AnnotationsBindingManager` (allows you to create/delete bindings) permission set. +- One of the following permission sets: + - `AnnotationsFullAccess`: gives you full access to keys, values, and bindings + - `AnnotationsBindingManager`: allows you to create/delete bindings -## How to configure the Annotations permission set +## Configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). -Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. +Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to bind an annotation to a resource +## 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**: +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, select the key and then the value from the drop-down list. Both the selected key and value display under the **Key** and **Value** fields. +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. -The annotation is now attached to your resource. +To bind an annotation to a resource *while creating it*, use the creation wizard. -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. -When you get to the point in the wizard where you can enter a name and description for your resource, select an existing annotation key-value pair. +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. -## How to detach an annotation from a 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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. +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. @@ -54,12 +56,12 @@ You can detach an annotation from a resource either via the Annotations page or 5. Use the search fields to find your resource. -6. Click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the **Values** page. +6. Click 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/), and click the **Settings** tab. +1. Navigate to your resource in the [console](https://console.scaleway.com/). -2. 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. +2. Once on the resource's dashboard page, click the **Settings** tab. -The annotation is now detached from your resource. \ No newline at end of file +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. \ No newline at end of file diff --git a/pages/annotations/how-to/configure-annotations-permissions.mdx b/pages/annotations/how-to/configure-annotations-permissions.mdx index a27420fd42..99eae237df 100644 --- a/pages/annotations/how-to/configure-annotations-permissions.mdx +++ b/pages/annotations/how-to/configure-annotations-permissions.mdx @@ -1,24 +1,30 @@ --- -title: How to configure Annotations permission sets +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 --- - -This page teaches you how to configure the necessary IAM permission set to access [Annotations](/annotations/concepts/#annotations). +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 (keys, values, and bindings). + - `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. -1. Click **IAM & API keys** on the top-right drop-down menu of the Scaleway console. The **Users** tab of the [Identity and Access Management dashboard](https://console.scaleway.com/iam/users) displays. +This page shows you how to configure the necessary IAM permission set to access [Annotations](/annotations/concepts/#annotations). + + + +- 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. - The **Access to Organization features** scope allows you to give the [principal](/iam/concepts/#principal) permissions to Organization-level features such as IAM, Annotations, billing, support tickets, and project management. + 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. 4. Click the **Annotations** category in the **Products** section, then choose the appropriate **Annotations** permission set. 5. Click **Validate**. diff --git a/pages/annotations/how-to/create-annotations.mdx b/pages/annotations/how-to/create-annotations.mdx index 66dd461e36..fcc875701b 100644 --- a/pages/annotations/how-to/create-annotations.mdx +++ b/pages/annotations/how-to/create-annotations.mdx @@ -1,5 +1,5 @@ --- -title: How to create annotations +title: Create annotations description: Learn how to create an annotation dates: validation: 2026-06-26 @@ -14,23 +14,23 @@ This page shows you how to create an [annotation](/annotations/concepts/#annotat - 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. +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings -## How to configure the Annotations permission set +## Configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). -Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. +Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to create an annotation +## 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. +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. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The **Annotations** product page displays. -2. Click **Create annotation**. The creation wizard 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**: @@ -51,13 +51,13 @@ You can create an annotation via the Annotations page dedicated to creating and 5. Enter more values if needed, using the **Add value** button. -6. Click **Create an annotation**. The list of your current annotations is displayed. +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 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. +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. @@ -71,7 +71,5 @@ When you get to the point in the wizard where you can enter a name and descripti Once you have created an annotation, you can bind it to your resource. -6. Using the dropdown, 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. +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. diff --git a/pages/annotations/how-to/delete-keys-values.mdx b/pages/annotations/how-to/delete-keys-values.mdx index a858f1156e..a2cc500ebf 100644 --- a/pages/annotations/how-to/delete-keys-values.mdx +++ b/pages/annotations/how-to/delete-keys-values.mdx @@ -1,5 +1,5 @@ --- -title: How to delete annotation keys and values +title: Delete annotation keys and values description: Learn how to delete annotation keys and values dates: validation: 2026-06-26 @@ -8,23 +8,23 @@ dates: 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. +This page shows you how to delete annotation [keys](/annotations/concepts/#key) and [values](/annotations/concepts/#value) via the Scaleway console. - 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. +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings -## How to configure the Annotations permission set +## Configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). -Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. +Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to delete a key +## Delete a key -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. @@ -34,31 +34,31 @@ Refer to [How to configure Annotations permission sets](/annotations/how-to/conf 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. +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 potentially even resources, deleting the key will break those associations. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. +5. *If the key has some associated values and maybe even resources*, deleting the key will break those associations. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. - For details on how to detach resources from the associated values, see PLACEHOLDER. + For details on how to detach resources from the associated values, see [Detach a resource from a value](/annotations/how-to/delete-keys-values/#detach-a-resource-from-a-value). -## How to delete a value +## Delete a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. +2. Use the search field to find the key whose value you want to delete. -3. Click the key whose value you want to delete. You are taken to the key's overview page. +3. Click the relevant key. You are taken to the key's overview page. 4. Click 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. +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](#how-to-detach-resources-from-a-value) first. After removing the associated resources, you can come back and delete the value. +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. -## How to detach a resource from a value +## Detach a resource from a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. @@ -68,6 +68,6 @@ Refer to [How to configure Annotations permission sets](/annotations/how-to/conf - 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**. You are taken back to the value's overview page. +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 next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the value's overview page. \ No newline at end of file +5. *To detach a single resource from the value*, click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. \ No newline at end of file diff --git a/pages/annotations/how-to/manage-keys-values.mdx b/pages/annotations/how-to/manage-keys-values.mdx index cea1330429..4740d43dde 100644 --- a/pages/annotations/how-to/manage-keys-values.mdx +++ b/pages/annotations/how-to/manage-keys-values.mdx @@ -1,5 +1,5 @@ --- -title: How to manage annotation keys and values +title: Manage annotation keys and values description: Learn how to manage annotation keys and values dates: validation: 2026-06-26 @@ -8,27 +8,27 @@ dates: import Requirements from '@macros/iam/requirements.mdx' -This page shows you how to manage annotation [keys](/annotations/concepts/#key) and values(/annotations/concepts/#value) via the Scaleway console. +This page shows you how to manage annotation [keys](/annotations/concepts/#key) and [values](/annotations/concepts/#value) via the Scaleway console. - 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. +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings -## How to configure the Annotations permission set +## Configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). -Refer to [How to configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. +Refer to [Configure Annotations permission sets](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to manage keys +## Manage keys -### How to create a new key +### Create a new key -Once you already have some annotations in place, you may want to create a new key. +Once you already have some [annotations](/annotations/concepts/#annotation) in place, you may have to create a new key. -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. 2. Click the **Create key** button. The **Create annotation** window pops up. @@ -51,11 +51,11 @@ Once you already have some annotations in place, you may want to create a new ke 5. Enter more values if needed, using the **Add value** button. -6. Click **Create an annotation**. The list of your current annotations is displayed. +6. Click **Create an annotation**. -### How to edit a key +### Edit a key -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. @@ -65,17 +65,17 @@ Once you already have some annotations in place, you may want to create a new ke 4. Make your changes, then click **Save**. -## How to manage values +## Manage values -### How to create a new value +### Create a new value -Once you already have some annotations in place, you may want to create a new value. +Once you already have some annotations in place, you may have to create a new value for an existing key. -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. +2. Use the search field to find the key to which you want to add a new value. -3. Click the key whose value you want to edit. You are taken to the key's overview page. +3. Click the relevant key. You are taken to the key's overview page. 4. Click the **Create value** button. The **Create value** window pops up. @@ -87,15 +87,15 @@ Once you already have some annotations in place, you may want to create a new va - Maximum length: 1024 characters - Allowed values: No restrictions -6. Click **Create value**. Your value has been deleted and you are taken to the key's overview page. +6. Click **Create value**. -### How to edit a value +### Edit a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. +2. Use the search field to find the key whose value you want to edit. -3. Click the key whose value you want to edit. You are taken to the key's overview page. +3. Click the relevant key. You are taken to the key's overview page. 4. Click next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** window pops up. diff --git a/pages/annotations/index.mdx b/pages/annotations/index.mdx index 300c872350..971c7bd23c 100644 --- a/pages/annotations/index.mdx +++ b/pages/annotations/index.mdx @@ -6,7 +6,7 @@ description: Dive into Scaleway Annotations with our quickstart guides, how-tos, @@ -17,7 +17,7 @@ description: Dive into Scaleway Annotations with our quickstart guides, how-tos, diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 7df8283fde..9c87914f70 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -14,68 +14,70 @@ In this quickstart, we show you how to start using [Annotations](/annotations/co - 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. +- The `AnnotationsFullAccess` permission set, which gives you full access to keys, values, and bindings -## How to configure the Annotations permission set +## Configure the Annotations permission set To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. -## How to create an annotation +## Create an annotation -1. Click **Annotations** in the **Management & Governance** section of the [console](https://console.scaleway.com/) side menu. The **Annotations** product page displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The **Annotations** product page displays. -2. Click **Create Annotation**. The creation wizard displays. +2. Click **Create an annotation**. The creation wizard displays. 3. Enter a unique name for your key, and optionally a description. 4. Enter a value, and optionally a description for it. -5. Click **Create annotation**. +5. Click **Create an annotation**. -Alternatively, you can create an annotation directly via a resource's creation wizard and the **Create annotation** button. +Alternatively, you can create an annotation [directly via a resource's creation wizard and the **Create annotation** button](/annotations/how-to/create-annotations/#via-a-resources-creation-wizard). -## How to bind an annotation to a resource +## 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. Here, you are going to bind the annotation that you have just created to a resource that already exists. -1. Navigate to your resource in the [console](https://console.scaleway.com/), and click the **Settings** tab. +1. Navigate to your chosen resource (e.g., a bucket) in the [console](https://console.scaleway.com/), and click the **Settings** tab. -2. In the **Annotations** panel, select the key and then the value from the drop-down list. Both the selected key and value display under the **Key** and **Value** fields. +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. + The annotation is now attached to your resource. -## How to manage a key +## Manage a key -### How to edit a key +### Edit a key -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. 2. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** window pops up. 3. Make your changes, then click **Save**. -### How to delete a key +### Delete a key -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. 2. Click 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. -3. Click **Confirm**. +3. *If the key has no associated value*, click **Confirm**. + +4. *If the key has some one or more associated values and maybe even resources*, deleting the key will break those associations. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. + + For details on how to detach resources from the associated values, see [Detach a resource from a value](#detach-a-resource-from-a-value). -## How to manage a value +## Manage a value -### How to edit a value +### Edit a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. @@ -83,21 +85,21 @@ The annotation is now attached to your resource. 4. Make your changes, then click **Save**. -### How to delete a value +### Delete a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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 delete. You are taken to the key's overview page. 3. Click 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. +4. *If the value is not bound to any resource*, click **Confirm**. -4. If the value is not bound to any resource, click **Confirm**. If the value is bound to one or more resources, you must [remove the binding](#how-to-detach-resources-from-a-value) first. Once the value is deleted, you are taken back to the key's dashboard page. +5. *If the value is bound to one or more resources*, you must [remove the binding](#detach-a-resource-from-a-value) first. -### How to detach a resource from a value +### Detach a resource from a value -1. Go to **Management & Governance** > **Annotations** in the [console](https://console.scaleway.com/) side menu. The list of your annotations displays. +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. @@ -107,9 +109,9 @@ The annotation is now attached to your resource. - 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**. You are taken back to the value's overview page. +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 next to the resource that you wish to detach. In the window that pops up, click **Confirm**. You are taken back to the value's overview page. +5. *To detach a single resource from the value*, click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. From 4cc39ef6b29f5820dd69d00f7c9596f14e7c63f9 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Fri, 26 Jun 2026 09:01:33 +0200 Subject: [PATCH 07/10] feat(annotations): add rules and limits MTA-7143 --- .../annotations/how-to/delete-keys-values.mdx | 4 +-- pages/annotations/menu.ts | 8 +++-- pages/annotations/quickstart.mdx | 4 +-- ...e-names.mdx => scaleway-resource-name.mdx} | 2 +- .../technical-rules-limits.mdx | 34 +++++++++++++++++++ 5 files changed, 43 insertions(+), 9 deletions(-) rename pages/annotations/reference-content/{scaleway-resource-names.mdx => scaleway-resource-name.mdx} (92%) create mode 100644 pages/annotations/reference-content/technical-rules-limits.mdx diff --git a/pages/annotations/how-to/delete-keys-values.mdx b/pages/annotations/how-to/delete-keys-values.mdx index a2cc500ebf..0314e67ed1 100644 --- a/pages/annotations/how-to/delete-keys-values.mdx +++ b/pages/annotations/how-to/delete-keys-values.mdx @@ -36,9 +36,7 @@ Refer to [Configure Annotations permission sets](/annotations/how-to/configure-a 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. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. - - For details on how to detach resources from the associated values, see [Detach a resource from a value](/annotations/how-to/delete-keys-values/#detach-a-resource-from-a-value). +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 diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts index df46a3fbc0..229c584105 100644 --- a/pages/annotations/menu.ts +++ b/pages/annotations/menu.ts @@ -55,8 +55,12 @@ export const annotationsMenu = { { items: [ { - label: 'Scaleway Resource Names', - slug: 'scaleway-resource-names', + label: 'Scaleway Resource Name', + slug: 'scaleway-resource-name', + }, + { + label: 'Technical rules and limits', + slug: 'technical-rules-limits', }, ], label: 'Additional Content', diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 9c87914f70..1af5622a59 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -69,9 +69,7 @@ Here, you are going to bind the annotation that you have just created to a resou 3. *If the key has no associated value*, click **Confirm**. -4. *If the key has some one or more associated values and maybe even resources*, deleting the key will break those associations. Click **Cancel** to abort the operation or **Confirm** to go ahead with the deletion of the key. - - For details on how to detach resources from the associated values, see [Detach a resource from a value](#detach-a-resource-from-a-value). +4. *If the key has some one or more 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 delete the key. ## Manage a value diff --git a/pages/annotations/reference-content/scaleway-resource-names.mdx b/pages/annotations/reference-content/scaleway-resource-name.mdx similarity index 92% rename from pages/annotations/reference-content/scaleway-resource-names.mdx rename to pages/annotations/reference-content/scaleway-resource-name.mdx index f72ca455fc..2f6c3b3673 100644 --- a/pages/annotations/reference-content/scaleway-resource-names.mdx +++ b/pages/annotations/reference-content/scaleway-resource-name.mdx @@ -23,4 +23,4 @@ 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.{/* Is the SRN relevant for the console? */} +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. diff --git a/pages/annotations/reference-content/technical-rules-limits.mdx b/pages/annotations/reference-content/technical-rules-limits.mdx new file mode 100644 index 0000000000..2c23d0bdf6 --- /dev/null +++ b/pages/annotations/reference-content/technical-rules-limits.mdx @@ -0,0 +1,34 @@ +--- +title: Technical rules and limits +description: Learn more about the validation rules and limits that apply to key, values, and bindings. +tags: annotations custom metadata limitations constraints rules +dates: + validation: 2026-06-26 + posted: 2026-06-26 +--- + +When creating or managing annotation keys, values, and bindings, specific validation rules and limits apply. + +## Validation rules + +| Element | Maximum length | Allowed values | +| ------------- | --------------- | -------------------- | +| Key name | 128 characters | `[a-zA-Z0-9+.-_:/@]` | +| Value name | 256 characters | `[a-zA-Z0-9+.-_:/@]` | +| Description | 1024 characters | No restrictions | + +## Integrity rules + +- Strict binding: A resource can only have one value per key. +- No orphans: + - You cannot delete a key if it has values. + - You cannot delete a value if it has bindings. + +## Consumption limits + +| Element | Limit | +| --------------------------------- | ------ | +| Number of keys per Organization | 100 | +| Number of values per key | 200 | +| Number of values per Organization | 5,000 | +| Number of bindings per resource | 50 | From f7f6cd2ca10db01817ad82d7d6e38121c8a2b72a Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Wed, 23 Sep 2026 09:03:49 +0200 Subject: [PATCH 08/10] feat(annotations): add SRN content --- .../scaleway-resource-name.mdx | 184 +++++++++++++++++- 1 file changed, 178 insertions(+), 6 deletions(-) diff --git a/pages/annotations/reference-content/scaleway-resource-name.mdx b/pages/annotations/reference-content/scaleway-resource-name.mdx index 2f6c3b3673..5e4f02b4fe 100644 --- a/pages/annotations/reference-content/scaleway-resource-name.mdx +++ b/pages/annotations/reference-content/scaleway-resource-name.mdx @@ -7,20 +7,192 @@ dates: posted: 2026-06-26 --- -The Scaleway Resource Name (SRN) is a Uniform Resource Identifier (URI) that uniquely identifies a Scaleway resource. It takes the following format: +A Scaleway Resource Name (SRN) is a Uniform Resource Identifier (URI) that uniquely identifies a Scaleway resource. + +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. + +An SRN follows this format: + +``` +srn://product-slug.partition/locality-type/{locality}/resource-type/{resource-id} +``` + +Examples: ``` -srn://product-slug.domain/(locality_type/{locality}/)resource-type/resource-id +# Key Manager key - an example with locality +srn://key-manager.scw.eu/regions/fr-par/keys/25f6c309-a2c6-4fb2-8d16-57960c3fb9df +# IAM application - an example with no locality +srn://iam.scw.eu/applications/25f6c309-a2c6-4fb2-8d16-57960c3fb9df ``` -For example: +The following table explains how to compose an SRN: + +| SRN segment | Details | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| srn:// | Specifies that the string that follows is a Scaleway Resource Name (SRN). | +| product-slug | An identifier for the product.
Examples: `block` for Block Storage, `secret-manager` for Secret Manager | +| partition | The identifier of the Scaleway partition represented as a domain.
Possible values (exhaustive list): `scw.eu` | +| locality-type | The locality type.
Possible values (exhaustive list): `regions`, `zones` | +| locality | The Scaleway region code or zone code.
Resources with locality will include the locality in a parent segment.
Resources without locality have no locality-type nor locality segment.
Examples for region: `fr-par`, `nl-ams`, `pl-waw`, `it-mil`
Examples for zone: `fr-par-1`, `nl-ams-2`, `pl-waw-3`, `it-mil-1` | +| resource-type | The resource type in its plural form, similar to a REST segment for a resource.
Examples: `routes` for VPC routes, `volumes` for Block volumes | +| resource-id | The unique identifier of the resource.
You can retrieve this information from the resource's page in the Scaleway console or via the product's API. | + +For a complete list of SRNs, see [Resource types and their SRNs](#resource-types-and-their-srns). + +For a complete list of product-slugs, see [Product slugs](#product-slugs). + +Note that **Object Storage resources are special**: + +- The bucket and object resource IDs are user-set and unique by partition. +- The object resource ID is a path inside the bucket. + +As a result, the path will be split in two segments: the bucket and the object. ``` -srn://k8s.scw.eu/regions/fr-par/clusters/25f6c309-a2c6-4fb2-8d16-57960c3fb9df +srn://object.scw.eu/buckets/bucket-name +srn://object.scw.eu/buckets/bucket-name/objects/path/to/my/object +``` + +Note that some **nested resources** rely on a parent UUID and a user-set ID in order to be addressed (e.g., a secret version). In this scenario, the nearest parent with a UUID will be included in the SRN. +Example: + +``` +srn://secret-manager.scw.eu/regions/fr-par/secrets/25f6c309-a2c6-4fb2-8d16-57960c3fb9df/versions/5 ``` -An SRN must be globally unique, immutable, human-comprehensible, and optimized for programmatic handling (e.g., generating a console URL). +### Resource types and their SRNs -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. +Some products, such as Annotations, require you to provide an SRN when executing certain operations via the API. + +The following table provides a list of resource types and corresponding Scaleway Resource Names. + +The list is intended to be comprehensive; however, it is still a work in progress. It is updated continuously with new items. + +To use an SRN, replace the ALL-CAPS segments with your resource-specific information. + +| Resource type | SRN | +| -------------------------- | -------------------------------------------------------------------------------- | +| BlockSnapshot | `srn://block.scw.eu/zones/ZONE/snapshots/RESOURCE-ID` | +| BlockVolume | `srn://block.scw.eu/zones/ZONE/volumes/RESOURCE-ID` | +| BlockVolumeType | `srn://block.scw.eu/zones/ZONE/volume-types/TYPE` | +| DatawarehouseDatabase | `srn://datawarehouse.scw.eu/regions/REGION/deployments/DEPLOYMENT-ID/databases/NAME` | +| DatawarehouseDeployment | `srn://datawarehouse.scw.eu/regions/REGION/deployments/ID` | +| DatawarehouseEndpoint | `srn://datawarehouse.scw.eu/regions/REGION/endpoints/ID` | +| DatawarehouseUser | `srn://datawarehouse.scw.eu/regions/REGION/deployments/DEPLOYMENT-ID/users/NAME` | +| FileAttachment | `srn://file.scw.eu/regions/REGION/attachments/RESOURCE-ID` | +| FileFileSystem | `srn://file.scw.eu/regions/REGION/file-systems/RESOURCE-ID` | +| FlexibleIpFlexibleIp | `srn://flexible-ip.scw.eu/zones/ZONE/flexible-ips/ID` | +| IamApplication | `srn://iam.scw.eu/applications/RESOURCE-ID` | +| IamApiKey | `srn://iam.scw.eu/api-keys/ACCESS-KEY` | +| IamGroup | `srn://iam.scw.eu/groups/ID` | +| IamJwt | `srn://iam.scw.eu/jwts/JTI` | +| IamLog | `srn://iam.scw.eu/logs/ID` | +| IamPolicy | `srn://iam.scw.eu/policies/ID` | +| IamQuotum | `srn://iam.scw.eu/quota/NAME` | +| IamRule | `srn://iam.scw.eu/rules/ID` | +| IamSaml | `srn://iam.scw.eu/saml/ID` | +| IamSamlCertificate | `srn://iam.scw.eu/saml-certificates/ID` | +| IamSshKey | `srn://iam.scw.eu/ssh-keys/ID` | +| IamUser | `srn://iam.scw.eu/users/ID` | +| InstancePlacementGroup | `srn://instance.scw.eu/zones/ZONE/placement-groups/ID` | +| InstancePrivateNetworkInterface | `srn://instance.scw.eu/zones/ZONE/private-network-interfaces/ID` | +| InstanceSecurityGroup | `srn://instance.scw.eu/zones/ZONE/security-groups/ID` | +| InstanceSnapshot | `srn://instance.scw.eu/zones/ZONE/snapshots/ID` | +| InstanceTemplate | `srn://instance.scw.eu/zones/ZONE/templates/ID` | +| InstanceVolume | `srn://instance.scw.eu/zones/ZONE/volumes/ID` | +| InstanceServer | `srn://instance.scw.eu/zones/ZONE/servers/ID` | +| InterlinkDedicatedConnection | `srn://interlink.scw.eu/regions/REGION/dedicated-connections/ID` | +| InterlinkLink | `srn://interlink.scw.eu/regions/REGION/links/ID` | +| InterlinkPartner | `srn://interlink.scw.eu/regions/REGION/partners/ID` | +| InterlinkPop | `srn://interlink.scw.eu/regions/REGION/pops/ID` | +| InterlinkRoutingPolicy | `srn://interlink.scw.eu/regions/REGION/routing-policies/ID` | +| ipamIpPattern | `srn://ipam.scw.eu/regions/REGION/ips/ID` | +| ipamIpPattern | `srn://ipam.scw.eu/zones/ZONE/ips/ID` | +| K8SAclRule | `srn://k8s.scw.eu/regions/REGION/acl-rules/ID` | +| K8SCluster | `srn://k8s.scw.eu/regions/REGION/clusters/ID` | +| K8SClusterType | `srn://k8s.scw.eu/regions/REGION/cluster-types/NAME` | +| K8SNode | `srn://k8s.scw.eu/regions/REGION/nodes/ID` | +| K8SPool | `srn://k8s.scw.eu/regions/REGION/pools/ID` | +| K8SVersion | `srn://k8s.scw.eu/regions/REGION/versions/NAME` | +| KeyManagerKey | `srn://key-manager.scw.eu/regions/REGION/keys/RESOURCE-ID` | +| PublicGatewayGateway | `srn://public-gateway.scw.eu/zones/ZONE/gateways/ID` | +| PublicGatewayGatewayNetwork | `srn://public-gateway.scw.eu/zones/ZONE/gateway-networks/ID` | +| PublicGatewayIp | `srn://public-gateway.scw.eu/zones/ZONE/ips/ID` | +| PublicGatewayPatRule | `srn://public-gateway.scw.eu/zones/ZONE/pat-rules/ID` | +| S2SVpnConnection | `srn://s2s-vpn.scw.eu/regions/REGION/connections/ID` | +| S2SVpnCustomerGateway | `srn://s2s-vpn.scw.eu/regions/REGION/customer-gateways/ID` | +| S2SVpnRoutingPolicy | `srn://s2s-vpn.scw.eu/regions/REGION/routing-policies/ID` | +| S2SVpnVpnGateway | `srn://s2s-vpn.scw.eu/zones/ZONE/vpn-gateways/ID` | +| SecretManagerSecret | `srn://secret-manager.scw.eu/regions/REGION/secrets/RESOURCE-ID` | +| SecretManagerSecretVersion | `srn://secret-manager.scw.eu/regions/REGION/secrets/SECRET-ID/versions/REVISION` | +| ServerlessDbBackup | `srn://serverless-db.scw.eu/regions/REGION/backups/ID` | +| ServerlessDbDatabase | `srn://serverless-db.scw.eu/regions/REGION/databases/ID` | +| ServerlessDbVersion | `srn://serverless-db.scw.eu/regions/REGION/versions/NAME` | +| VpcIngressRule | `srn://vpc.scw.eu/regions/REGION/ingress-rules/RESOURCE-ID` | +| VpcPrivateNetwork | `srn://vpc.scw.eu/regions/REGION/private-networks/RESOURCE-ID` | +| VpcRoute | `srn://vpc.scw.eu/regions/REGION/routes/RESOURCE-ID` | +| VpcSubnet | `srn://vpc.scw.eu/regions/REGION/subnets/RESOURCE-ID` | +| VpcVPC | `srn://vpc.scw.eu/regions/REGION/vpcs/RESOURCE-ID` | +| VpcVPCConnector | `srn://vpc.scw.eu/regions/REGION/vpc-connectors/RESOURCE-ID` | + +### Product slugs + +The following table provides a list of products and corresponding product-slugs. + +The list is intended to be comprehensive; however, it is still a work in progress. It is updated continuously with new items. + +| Product | product-slug | +| ------------------------------------------ | ------------------------- | +| Account | `account` | +| Annotations | `annotations` | +| Apple silicon | `apple-silicon` | +| Audit Trail | `audit-trail` | +| Billing | `billing` | +| Block Storage | `block` | +| Cockpit | `cockpit` | +| Container Registry | `registry` | +| Cloud Essentials for OpenSearch | `searchdb` | +| Cloud Essentials for RabbitMQ | `messageq` | +| Clusters for Apache Kafka® | `kafka` | +| Clusters for Apache Spark™ | `datalab` | +| Data Orchestrator | `data-orchestrator` | +| Data Warehouse for ClickHouse® | `datawarehouse` | +| Domains & DNS | `domain` | +| Edge Services | `edge-services` | +| Elastic Metal | `elastic-metal` | +| Elastic Metal - Flexible IP | `flexible-ip` | +| Environmental Footprint | `environmental-footprint` | +| File Storage | `file` | +| IAM | `iam` | +| Generative APIs | `inference` | +| Instances | `instance` | +| InterLink | `interlink` | +| IoT Hub | `iot-hub` | +| IPAM | `ipam` | +| Kubernetes | `k8s` | +| Key Manager | `key-manager` | +| Load Balancer | `lb` | +| Mailbox | `mailbox` | +| Managed Databases for PostgreSQL and MySQL | `rdb` | +| Managed Database for Redis™ | `redis` | +| Managed MongoDB® | `mongodb` | +| NATS | `nats` | +| Notification Manager | `notification-center` | +| Object Storage | `object` | +| Product Catalog | `product-catalog` | +| Public Gateways | `public-gateway` | +| Quantum | `quantum` | +| Queues | `queues` | +| Site-to-Site VPN | `s2s-vpn` | +| Secret Manager | `secret-manager` | +| Serverless Containers | `containers` | +| Serverless Functions | `functions` | +| Serverless Jobs | `jobs` | +| Serverless SQL Databases | `serverless-db` | +| Topics & Events | `topics-events` | +| Transactional Emails | `transactional-email` | +| VPC | `vpc` | +| Web Hosting | `webhosting` | From a6164bf1d11a974c4db9bec1b41eea2a9de0cad0 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Fri, 30 Oct 2026 17:51:28 +0100 Subject: [PATCH 09/10] feat(annotations): refine structure and content --- menu/navigation.ts | 51 ++++++++--------- .../{concepts.mdx => concepts/glossary.mdx} | 4 +- pages/annotations/concepts/index.mdx | 4 ++ pages/annotations/faq.mdx | 8 ++- pages/annotations/menu.ts | 8 ++- pages/annotations/quickstart.mdx | 56 ++++++++----------- 6 files changed, 65 insertions(+), 66 deletions(-) rename pages/annotations/{concepts.mdx => concepts/glossary.mdx} (96%) create mode 100644 pages/annotations/concepts/index.mdx diff --git a/menu/navigation.ts b/menu/navigation.ts index 06d9eaea1e..ae4a5f52cb 100644 --- a/menu/navigation.ts +++ b/menu/navigation.ts @@ -2,8 +2,8 @@ // for its associated menu naming, to avoid breaking tooling 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 { auditTrailMenu } from '../pages/audit-trail/menu' import { billingMenu } from '../pages/billing/menu' import { blockStorageMenu } from '../pages/block-storage/menu' import { classicHostingMenu } from '../pages/classic-hosting/menu' @@ -75,16 +75,10 @@ export default [ items: [ { icon: 'OrganizationDashboardCategoryIcon', - items: [accountMenu], - label: 'Account', + items: [accountMenu, organizationsAndProjectsMenu, annotationsMenu], + label: 'Account & Organization', category: 'console', }, - { - icon: 'AnnotationsCategoryIcon', - items: [annotationsMenu], - label: 'Annotations', - category: 'console', - }, { icon: 'CostAndImpactManagementCategoryIcon', items: [billingMenu, environmentalFootprintMenu], @@ -96,7 +90,6 @@ export default [ items: [ iamMenu, keyManagerMenu, - organizationsAndProjectsMenu, secretManagerMenu, ], label: 'Security & Identity', @@ -131,18 +124,6 @@ export default [ label: 'Containers', category: 'containers', }, - { - icon: 'DatabaseCategoryIcon', - items: [ - managedDatabasesForPostgresqlAndMysqlMenu, - managedDatabasesForRedisMenu, - managedMongodbDatabasesMenu, - openSearchMenu, - serverlessSqlDatabasesMenu, - ], - label: 'Databases', - category: 'databases', - }, { icon: 'DataAndAnalyticsCategoryIcon', items: [ @@ -155,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], @@ -199,6 +192,12 @@ export default [ label: 'Network', category: 'network', }, + { + icon: 'LabsCategoryIcon', + items: [quantumComputingMenu], + label: 'Quantum', + category: 'quantum', + }, { icon: 'ServerlessComputeCategoryIcon', items: [ @@ -209,12 +208,6 @@ export default [ label: 'Serverless', category: 'serverless', }, - { - icon: 'LabsCategoryIcon', - items: [quantumComputingMenu], - label: 'Quantum', - category: 'quantum', - }, { icon: 'StorageCategoryIcon', items: [ @@ -275,4 +268,4 @@ export default [ ], label: 'Additional Services', }, -] +] \ No newline at end of file diff --git a/pages/annotations/concepts.mdx b/pages/annotations/concepts/glossary.mdx similarity index 96% rename from pages/annotations/concepts.mdx rename to pages/annotations/concepts/glossary.mdx index 5b56a27a79..b8848c1164 100644 --- a/pages/annotations/concepts.mdx +++ b/pages/annotations/concepts/glossary.mdx @@ -1,6 +1,6 @@ --- -title: Annotations - Concepts -description: Learn fundamental concepts of Scaleway's Annotations. +title: Annotations - Glossary +description: Learn fundamental concepts of Scaleway Annotations. tags: annotations custom metadata dates: validation: 2026-06-26 diff --git a/pages/annotations/concepts/index.mdx b/pages/annotations/concepts/index.mdx new file mode 100644 index 0000000000..134a6d0ce9 --- /dev/null +++ b/pages/annotations/concepts/index.mdx @@ -0,0 +1,4 @@ +--- +title: Annotations - Concepts +description: Understand key concepts related to Scaleway Annotations. +--- diff --git a/pages/annotations/faq.mdx b/pages/annotations/faq.mdx index 5ae4125741..ae54cfadfd 100644 --- a/pages/annotations/faq.mdx +++ b/pages/annotations/faq.mdx @@ -1,6 +1,6 @@ --- title: Annotations - FAQ -description: Get answers on using Scaleway's Annotations to manage and organize your resources using custome key-value metadata +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 @@ -22,7 +22,11 @@ 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`). +- **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? + +placeholder ## Pricing and billing diff --git a/pages/annotations/menu.ts b/pages/annotations/menu.ts index 229c584105..516d2b005a 100644 --- a/pages/annotations/menu.ts +++ b/pages/annotations/menu.ts @@ -5,9 +5,15 @@ export const annotationsMenu = { slug: '../annotations', }, { + items: [ + { + label: 'Glossary', + slug: 'glossary', + }, + ], label: 'Concepts', slug: 'concepts', - }, + }, { label: 'Quickstart', slug: 'quickstart', diff --git a/pages/annotations/quickstart.mdx b/pages/annotations/quickstart.mdx index 1af5622a59..caaf608f3b 100644 --- a/pages/annotations/quickstart.mdx +++ b/pages/annotations/quickstart.mdx @@ -1,6 +1,6 @@ --- title: Annotations - Quickstart -description: Quickly set up and start using Scaleway’s Annotations. Follow steps to configure custom key-value metadata for your resources. +description: Quickly set up and start using Scaleway Annotations. Follow steps to configure custom key-value metadata for your resources. dates: validation: 2026-06-26 posted: 2026-06-26 @@ -19,23 +19,15 @@ In this quickstart, we show you how to start using [Annotations](/annotations/co ## Configure the Annotations permission set -To start using Annotations, you need to configure permission sets in [IAM](/iam/concepts/#iam). - -Refer to the [dedicated documentation page](/annotations/how-to/configure-annotations-permissions/) to find out how. +To start using Annotations, [configure an Annotation permission set in IAM](/annotations/how-to/configure-annotations-permissions/). ## Create an annotation -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. - +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The **Annotations** product page opens. +2. Click **Create key**. The creation wizard opens. 3. Enter a unique name for your key, and optionally a description. - 4. Enter a value, and optionally a description for it. - -5. Click **Create an annotation**. - -Alternatively, you can create an annotation [directly via a resource's creation wizard and the **Create annotation** button](/annotations/how-to/create-annotations/#via-a-resources-creation-wizard). +5. Click **Create annotation**. ## Bind an annotation to a resource @@ -53,63 +45,63 @@ Here, you are going to bind the annotation that you have just created to a resou ### Edit a key -1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your keys appears. -2. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** window pops up. +2. Click next to the key you want to edit. Click **Edit key** in the menu. The **Edit key** dialog box appears. -3. Make your changes, then click **Save**. +3. Change the key name and/or description, then click **Update**. ### Delete a key -1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your keys appears. 2. Click next to the key you want to delete. Click **Delete key** in the menu. - The **Delete key** window pops up, asking you to confirm the deletion of your key. + The **Delete key** confirmation dialog box appears. 3. *If the key has no associated value*, click **Confirm**. -4. *If the key has some one or more 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 delete the key. +4. *If the key has one or more 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 delete the key. ## Manage a value ### Edit a value -1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your keys appears. -2. Click the key whose value you want to edit. You are taken to the key's overview page. +2. Click the key whose value you want to edit. The overview page of the key opens. -3. Click next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** window pops up. +3. Click next to the value you want to edit. Click **Edit value** in the menu. The **Edit value** dialog box appears. -4. Make your changes, then click **Save**. +4. Change the value name and/or description, then click **Update**. ### Delete a value -1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your annotations displays. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your keys appears. -2. Click the key whose value you want to delete. You are taken to the key's overview page. +2. Click the key whose value you want to delete. The overview page of the key opens. -3. Click 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. +3. Click next to the value you want to delete. Click **Delete value** in the menu. The **Delete value** confirmation dialog box appears. -4. *If the value is not bound to any resource*, click **Confirm**. +4. *If the value is not bound to any resource*, click **Delete**. 5. *If the value is bound to one or more resources*, you must [remove the binding](#detach-a-resource-from-a-value) first. ### 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. +1. In the [console](https://console.scaleway.com/) side menu, go to **Management & Governance** > **Annotations**. The list of your keys appears. -2. Click the key whose value you want to edit. You are taken to the key's overview page. +2. Click the key whose value you want to edit. The overview page of the key opens. -3. Click the name of the value that you want to edit. You are taken to the value's overview page. +3. Click the name of the value that you want to edit. The overview page of the value opens. 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**. +4. *To bulk detach all resources associated with the value*, click the **Detach all** button. In the dialog box that appears, click **Confirm**. -5. *To detach a single resource from the value*, click next to the resource that you wish to detach. In the window that pops up, click **Confirm**. +5. *To detach a single resource from the value*, click next to the resource that you wish to detach. In the dialog box that appears, click **Confirm**. From 870e88654aed0a2e7ae24c29de97db4891c7904b Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Fri, 30 Oct 2026 18:06:39 +0100 Subject: [PATCH 10/10] feat(annotations): add question about tags vs annotations --- pages/annotations/faq.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/pages/annotations/faq.mdx b/pages/annotations/faq.mdx index ae54cfadfd..a35acf8b56 100644 --- a/pages/annotations/faq.mdx +++ b/pages/annotations/faq.mdx @@ -26,7 +26,14 @@ Using Annotations helps you: ### What is the difference between tags and annotations? -placeholder +**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