From 759b25654e35e1de0705357a07d3f0966dcb4272 Mon Sep 17 00:00:00 2001 From: Vanda ILLYES Date: Mon, 22 Jun 2026 18:03:39 +0200 Subject: [PATCH 1/7] 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 2/7] 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 3/7] 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 4/7] 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 5/7] 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 6/7] 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 7/7] 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 |