API Group Name Discussion

[Adam Kaplan]

Since I won't be able to make it to the community meeting tomorrow, I want to weigh in on the topic of API group names for Konflux. The tl;dr:

- I recommend `konflux-ci.dev` as the official API group.

- Any change to an object's API group name requires a migration strategy, and should be documented in an ADR.

----

For context, our current Kubernetes APIs use the following group identifiers:

- appstudio.redhat.com (the default)

- projctl.konflux.dev (Project and related APIs)

These are the API groups I was able to find on konflux-ci.dev [1]. If you maintain a Konflux CRD whose API group is not present, please add it to our reference documentation [2].

The Kubernetes project recommends the following for API group names [3]:

When choosing a group name, we recommend selecting a subdomain your group or organization owns, such as "widget.mycompany.com".

A secondary recommendation is that any object Kind placed next to its API group name should not repeat words ("stutter"). This ensures a positive command line experience using `kubectl`, where using the form "kubectl get <kind>.<api-group>/<version>" may be necessary.

In practice open source projects tend to use the same domain as their website for their CRD API group, and avoid using subdomains for their core APIs. Examples:

- Tekton: tekton.dev

- Shipwright: shipwright.io

- Kyverno: kyverno.io

In light of these examples, I recommend we use `konflux-ci.dev` as the API group name for all Konflux CRDs. Avoid subdomains unless their scope falls outside of the core Konflux user experience (ex: a dedicated API group name for operator CRDs).

Note that changing an existing CRD's API group name is not trivial. A new API group name creates net new custom resource definitions on Kubernetes. I recommend that any existing CRDs wishing to adopt our standard API group name document their migration strategy in an ADR.

Regards,

Adam

[1] https://konflux-ci.dev/docs/reference/kube-apis/

[2] https://github.com/konflux-ci/docs/blob/main/CONTRIBUTING.md#generating-api-docs

[3] https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md

--

Adam Kaplan

He/Him

Senior Principal Software Engineer

Red Hat

100 E. Davie Street

adam....@redhat.com    

[Mykola Morhun]

I agree with what Adam said above.

We need to stay aligned and use the same API Group across all Konflux CRDs.

`konflux-ci.dev` looks good to me.

--

Mykola Morhun

Konflux Build

[Erik Skultety]

On Wed, May 27, 2026 at 03:21:31PM -0400, 'Adam Kaplan' via Konflux CI wrote:
> Since I won't be able to make it to the community meeting tomorrow, I want
> to weigh in on the topic of API group names for Konflux. The tl;dr:
>
> - I recommend `konflux-ci.dev` as the official API group.
> - Any change to an object's API group name requires a migration strategy,
> and should be documented in an ADR.

[...]

> In practice open source projects tend to use the same domain as their
> website for their CRD API group, and avoid using subdomains for their core
> APIs. Examples:
>
> - Tekton: tekton.dev
> - Shipwright: shipwright.io
> - Kyverno: kyverno.io

FWIW ^this suggestion IMO makes sense from the long term perspective.

Regards,
Erik

[Gal Ben Haim]

On Wed, May 27, 2026 at 10:22 PM 'Adam Kaplan' via Konflux CI <kon...@googlegroups.com> wrote:

Since I won't be able to make it to the community meeting tomorrow, I want to weigh in on the topic of API group names for Konflux. The tl;dr:

- I recommend `konflux-ci.dev` as the official API group.

- Any change to an object's API group name requires a migration strategy, and should be documented in an ADR.

+1 

--
You received this message because you are subscribed to the Google Groups "Konflux CI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to konflux+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/konflux/CADmLb%2Bn%3Dj%2B%3DJi2tZVpvBZxv5zw1KLqF_zEvitVfeKWdt7MFLCw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

GAL bEN HAIM

KoNFLUX ARCHITECTURE

[Simon Baird]

We might choose `conforma.dev` for the EnterpriseContractPolicy CRD API group name, since I think that could be used outside of Konflux.

(We're also planning to rename it at some point, perhaps to `ConformaPolicy`, but that's a separate discussion.)

-Simon

To view this discussion visit https://groups.google.com/d/msgid/konflux/CADpdQO7F9vS4w0uZ%2BsR_ddKP-Spu8hydm5L4VipLNAB5qr_QUA%40mail.gmail.com.

[Andrew McNamara]

I generally support this as well. Simon, that makes sense for Conforma as it is separate from Konflux.

Andrew McNamara

He / Him / His

Grab some time to chat: Office hours

To view this discussion visit https://groups.google.com/d/msgid/konflux/CAD0_soS_3A0NDpdwtawyAWhQnHdMTKxJueCGAK%2BZu%3D1Dj018kQ%40mail.gmail.com.