Annotations API | Scaleway Developers

Scaleway Annotations lets you attach custom key-value metadata to any cloud resource (instance, bucket, database, etc.). Use Annotations to start organizing your Scaleway resources now, setting up your infrastructure for our next-generation FinOps, GreenOps, and governance tools.

This product is currently in Beta.

Concepts

Annotation

An annotation is custom metadata you can attach to any Scaleway resource (instance, bucket, database, etc.). It consists of a key (the category of information for a resource) and a value (the concrete information associated with a category).

Key-Value

An annotation key is a globally-unique identifier 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).

An annotation value is the concrete information (e.g., marketing, production, 83546) associated with a category, i.e., an annotation key. A value cannot exist on its own, it must always be a child of a key.

For example:

Key	Value
team	marketing, finance, sales
environment	staging, production
cost_center	c83546, c32424, c47847

A key-value pair constitutes an annotation.

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.

Scaleway Resource Name

A Scaleway Resource Name (SRN) is a Uniform Resource Identifier (URI) that uniquely identifies a Scaleway resource.

In the context of Annotations, you are required to provide the SRN of the resource when binding a key-value pair to it via the Annotations API.

An SRN usually follows this format:

Code
srn://product-slug.partition/locality-type/{locality}/resource-type/{resource-id}

Examples:

Code
# Key Manager key - an example with locality
srn://key-manager.scw.eu/regions/fr-par/keys/25f6c309-a2c6-4fb2-8d16-57960c3fb9df

# IAM application - an example with no locality
srn://iam.scw.eu/applications/25f6c309-a2c6-4fb2-8d16-57960c3fb9df

For detailed information about how SRNs are composed, see Scaleway Resource NamesOpen in new context.

Quickstart

Requirement

You have your Organization IDOpen in new context
You have created an API keyOpen in new context and the API key has sufficient IAM permissionsOpen in new context to perform the actions described on this page. To start using Annotations, configure 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.
You have installed curlOpen in new context

In the following steps, you are going to create a key-value pair (example: service, payment), bind it to a given resource, then list your organization's bindings.

Configure your environment variables.

Note

This is an optional step to simplify your usage of the Annotations API.

Code
export SCW_ACCESS_KEY="<access-key>"
export SCW_SECRET_KEY="<secret-key>"
export SCW_ORGANIZATION_ID="<your-organization-id>"

Run the following command to create an annotation key. Remember to replace the placeholders with actual values.

Code
curl -X POST \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"description\":\"<description-of-key>\",\"name\":\"<name-of-key>\",\"organization_id\":\"$SCW_ORGANIZATION_ID\"}" \
"https://api.scaleway.com/annotations/v1/keys"

Example response:

Code
{
    "id":"019eac9e-18a7-7bcb-b448-978c36d0a2fc",
    "srn":"srn://annotations.scw.eu/keys/019eac9e-18a7-7bcb-b448-978c36d0a2fc",
    "name":"service",
    "description":"key-for-services"
}

Note the key id returned in the response, you will need it in the next step.

Run the following command to add a value to the key. Remember to replace the placeholders with actual values.

Code
curl -X POST \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"description\":\"<description-of-value>\",\"key_id\":\"<id-of-key>\",\"name\":\"<name-of-value>\"}" \
"https://api.scaleway.com/annotations/v1/values"

Example response:

Code
{
    "id":"019eb0ba-6400-748c-a037-b6b436c0ec41",
    "srn":"srn://annotations.scw.eu/values/019eb0ba-6400-748c-a037-b6b436c0ec41",
    "key_id":"019eac9e-18a7-7bcb-b448-978c36d0a2fc",
    "name":"payments",
    "description":"value-for-payments"
}

Note the value id returned in the response, you will need it in the next step.

Attach a key-value pair to a selected cloud resource. Remember to replace the placeholders with actual values.

Code
curl -X POST \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"target_srn":"<srn-value>","value_id":"<id-of-value>"}' \
"https://api.scaleway.com/annotations/v1/bindings"

Example response:

Code
{
    "id":"019eb0cb-7527-76e6-bc56-63d4d92e319e",
    "srn":"srn://annotations.scw.eu/bindings/019eb0cb-7527-76e6-bc56-63d4d92e319e",
    "target_srn":"srn://k8s.scw.eu/regions/fr-par/clusters/25f6c309-a2c6-4fb2-8d16-57960c3fb9df",
    "key":{
        "id":"019eac9e-18a7-7bcb-b448-978c36d0a2fc",
        "name":"service"
    },
    "value":{
        "id":"019eb0ba-6400-748c-a037-b6b436c0ec41",
        "name":"payments"
    }
}

Run the following command to list bindings (i.e., the annotations attached to your resources). Remember to replace the placeholder with an actual value.

Code
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/annotations/v1/bindings?organization_id=$SCW_ORGANIZATION_ID"

Example response:

Code
{
    "bindings":[
        {
            "id":"019eb0cb-7527-76e6-bc56-63d4d92e319e",
            "srn":"srn://annotations.scw.eu/bindings/019eb0cb-7527-76e6-bc56-63d4d92e319e",
            "target_srn":"srn://k8s.scw.eu/regions/fr-par/clusters/25f6c309-a2c6-4fb2-8d16-57960c3fb9df",
            "key":{
                "id":"019eac9e-18a7-7bcb-b448-978c36d0a2fc",
                "name":"service"
            },
            "value":{
                "id":"019eb0ba-6400-748c-a037-b6b436c0ec41",
                "name":"payments"
            }
        }
    ],
    "total_count":1
}

Technical information

Regions

Scaleway's infrastructure spans different regions and Availability ZonesOpen in new context.

Annotations is a global product that is available in all regions.

Technical limitations

Validation rules

Element	Maximum length	Allowed values
key `name`	128 characters	`^[_\\pL][_\\pL0-9]*$`
value `name`	256 characters	`^[_\\pL][_\\pL0-9]*$`
`description`	1024 characters	No restrictions

All list endpoints return items sorted alphabetically by name (except bindings, which are sorted by ID).

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