Apicurio 2.0.3 : ccompat/v6 bad version return

[mpumd]

Hi guys,

I have a question about the version management inside the apicurio registry. Inside the "version": field, we are free to set any alphanumeric character. As you can see below, we have the version 1 and 3 which are a string.

curl http://dev.company.com/apis/registry/v2/groups/default/artifacts/com.compagny.movie/versions | jq
{
  "count": 2,
  "versions": [
    {
      "name": "company-movie",
      "description": "super movie avro",
      "createdOn": "2022-09-14T13:29:20+0000",
      "createdBy": "",
      "type": "AVRO",
      "labels": [
        "avro",
        "kafka"
      ],
      "state": "ENABLED",
      "globalId": 56,
      "version": "1",
      "properties": {
        "custom1": "bubu",
        "custom2": "lala"
      },
      "contentId": 16
    },
    {
      "name": "company-movie",
      "description": "super movie avro",
      "createdOn": "2022-09-14T13:36:28+0000",
      "createdBy": "",
      "type": "AVRO",
      "labels": [
        "avro",
        "kafka"
      ],
      "state": "ENABLED",
      "globalId": 57,
      "version": "3",
      "properties": {
        "custom1": "bubu",
        "custom2": "lala"
      },
      "contentId": 20
    }
  ]
}

We found the same versions by the ccompat/v6 so consistent.

curl http://dev.company.com/apis/ccompat/v6/subjects/com.compagny.movie/versions |  jq 
[
	1,
	3
] 

Below, we have a version 2. Where is it from ? With the schema, I recognize the version 3 of above. So how this version is calculate in ccompat/v6 ? Our clients, GUI and other, uses this version 2 which create an ambiguous understanding on schema versionning.

curl http://dev.company.com/apis/ccompat/v6/subjects/com.compagny.movie/versions/latest | jq 
{                                                                                                                                                                                      
  "id": 20,
  "subject": "com.compagny.movie",
  "version": 2, 
  "schema": "{\"namespace\":\"com.company\",\"type\":\"record\",\"name\":\"Movie\",\"fields\":[{\"name\":\"title2\",\"type\":\"string\"},{\"name\":\"year\",\"type\":\"int\"}]}"
}

Can you explain how this version 2 is calculated ?
Thanks in advance.

[apicurio-bot]

Thank you for reporting an issue!

Pinging @EricWittmann to respond or triage.

[EricWittmann]

Oh this is perhaps an interesting bug. I'll have to dig into this to verify what I'm about to tell you is correct, but here's what I think is happening:

Registry supports user-defined versions. So when you create or update an artifact, you can (optionally) provide a version. It doesn't have to be a number. It can be whatever string value you want. So instead of "1" and "2" you could have instead used "1.0.0" and "1.0.1" (as an example). However, for a variety of reasons, we also have a versionId that is automatically calculated for each version. That value is always numeric. And we use that numeric calculated value if you choose to not provide a value.

If you're using our core API, everything should work nicely. If you use the Confluent compatibility API, it appears there may be a bug.

Just checking the code now. For the "Get Versions" endpoint, we are getting back a list of the string versions (the ones optionally provided by the user) and returning those. This is why you see 1, 3 as you expect. However, the implementation of "Get Subject With Version" returns the versionId instead of the version. I would argue this is a simple bug, and it's very easily fixable.

Please note that if you were to use non-numeric versions, you would then no longer be able to use the ccompat API. We would try to convert the version numbers to numeric and it would fail.

[mpumd]

Hi Eric,

Thanks for your answer. You confirm what I've investigated :). I think it's not a technical bug because you must be compliant with confluent api. But my problem is more complex and is out of apicurio. Some kafka registry frontends exist and use the ccompat/v6 api like akhq. We have also a redhat amqstream frontend that use registry/v2.
For a developer, it's confuse de have potentially two differents versions format for a schema.

I resume your example :

label		versionId
1.0.0			1
1.0.1			2
1.1.0			3
2.0.0			4		latest

Our workaround consists to force an incremental number inserted in order.

label		versionId
"1"			1
"2"			2
"3"			3
"4"			4		latest

Moreover, latest version is confuse too. For a developer, latest is the bigger number that identify a version. In apicurio it's the last inserted version. Below, 3 is the latest version.

label		versionId
"1"			1
"4"			2
"2"			3
"3"			4		latest

So we must create each versions in ascending order like the second example when you considered error recovery like flushing apicurio db by production crash for example. It's very unyielding.
Finally we have an ergonomic problem which is to have same number identifier for a schema version on ccompat/v6 and registry/v2.

So like you said, we have a choice of no use the label version ?
This api /apis/registry/v2/groups/default/artifacts/com.compagny.movie/versions could return a same version numbers of ccompat/v6 like "version": 1 ?

Thanks for your investigations.

[EricWittmann]

I understand and agree with everything you've said here. We definitely have challenges with versions. Part of the challenge is with ccompat, but that's not all (as you've observed). We're discussing now how to support GitOps workflows, and the ordering of versions is of particular interest in that use case. It's something we'll need to solve, but we're not quite sure yet.

I would also add that if you use the core v2 API and simply don't provide a version string (e.g. do not send the X-Registry-Version header), then the version will simply be a string conversion of the versionId. In that case, the list of versions you get back from the core v2 endpoint you referenced would be the same as what you get back from the ccompat api (except formatted as string rather than numbers, but with the same values).

[vsevel]

Hello @EricWittmann
Your last comment relates also to Apicurio/apicurio-registry-content-sync-operator#101
Our intention is to use the operator and a pure gitops approach. So I would rather not use the core API directly, and be explicit about the versions in the CR, rather than trusting that the order of apply will do the right thing.

During normal operations (today I create a version, and next month another version) this may be livable. But it won't be as soon as you start dealing with unexpected situations:

• versions 1, 2 and 3 get created
• CR mapping to version 2 gets deleted (accidentally)
• argo attempts to re-synch it => will it create a new version 4?

I should be able to apply CRs in any order. and any suite of actions leading to a certain state from the CR perspective should lead to the same corresponding state in apicurio.
for instance I should end up with the same result in apicurio if I do any one of these 3 scenarios:

• create v1, create v2, create v3
• create v2, create v1, create v3
• create v1, create v2, delete v1, create v3, create v1

If an action is invalid, then the operation (e.g. delete v1) should be immediately vetoed, or (for create/update) operations the status should be in error.

let's summarize this by saying that I would rather by explicit about the version number.

[EricWittmann]

Yes understood. I don't have a viable solution right now, but we're in agreement about the problem.

@andreaTP @carlesarnal @jsenko anything to add to this conversation?

[vsevel]

any news on this?

[EricWittmann]

Not yet. We think the right way to handle this type of scenario is by adding semver support. However, that has all sorts of complicated consequences. For example, it would be nice to have the Compatibility rule configured differently if the patch version changes vs. if the major version changes.

But we could start with just using semver for ordering purposes.

Also note that we likely will have some gitops requirements coming soon, which will make us feel your pain and perhaps bump the priority of this.

[rmarting]

I would like to visualize an issue related to the different version types in the integration of Apicurio Registry with a ccompat compliant application, like Kafka-UI. Basically, as soon the schemas in Apicurio use a SemVer approach (or anything with a dot .) then the ccompac api fails.

Totally agree with all the comments of this issue, and it is an not easy way to fix it, however, I am thinking about a workaround to avoid breaking the ccompact api. An idea could be check the conversion of the version of the artifact, and in the case of failure because it is not an integer, use the internal versionId of the artifact, that always is an integer. I know that idea will not change the behavior described in the comment, but at least the api will not break with an exception because the version is not an integer.

What do you think?

References:

• Kafka-UI issue example: Apicurio Registry support provectus/kafka-ui#1786 (comment)
• Kafka-UI issue: SR: Expand schema versioning pattern to support Apicurio provectus/kafka-ui#3841