API for custom checkpoint meta-data¶

https://blueprints.launchpad.net/cinder/+spec/custom-checkpoint-metadata

Problem description¶

Currently when creating a checkpoint. The only place to add custom information apart from the name is in the description field. This means that tools that create checkpoints needs to use this user visible space for their own metadata.

User data can only be set during creation and is read-only from that point on.

Use Cases¶

A tool creates a checkpoint and want’s to add information related to the tools functions. For example a tool that creates checkpoints due to specific external events would like to add the event_id of the event that triggered the checkpoint creation.

Proposed change¶

When creating a checkpoint a new field would be available called extra-info. This field must be a map in the format of:

{
    "key": "value",
}

Keys and values must both be strings. Keys that are officially recognized will be in the format of karbor-<key-name> for example karbor-created-by.

Anything that is not officially defined should use the prefix: x-<application>--<key-name>. For example, x-trigger-master--trigger-id

Alternatives¶

Do nothing, this is not a mission critical feature.

Data model impact¶

New field for a checkpoint called extra-info.

REST API impact¶

New optional body attribute when creating a new checkpoint:

POST/v1/{tenant_id}/checkpoint

{
    ...
    "extra-info": {
            "karbor-created-by": "operation-engine"
    }
}

Security impact¶

We need to make sure the number of entries and their size is within bounds to prevent any attacks.

Notifications impact¶

None

Other end user impact¶

The new API will be exposed to users via the python-karborclient.

Performance Impact¶

Filtering the results might cause a slight performance impact for the REST API.

Other deployer impact¶

None

Developer impact¶

None

Implementation¶

Assignee(s)¶

Work Items¶

Write API
Add to Karbor client
Write tests
Add documentation

Dependencies¶

None

Testing¶

Unit tests in Karbor and the python-karborclient.

Documentation Impact¶

New docs to explain how to use the API.

References¶

None