GA: Promote Receiver API to `notification.toolkit.fluxcd.io/v1` by makkes · Pull Request #498 · fluxcd/notification-controller

makkes · 2023-03-22T16:48:49Z

API changes

The Receiver kind was promoted from v1beta2 to v1 (GA). All other kinds of the notification.toolkit.fluxcd.io group stay at version v1beta2.

The receivers.notification.toolkit.fluxcd.io CRD contains the following versions:

v1 (storage version)
v1beta2 (deprecated)
v1beta1 (deprecated)

Upgrade

The Receiver v1 API is backwards compatible with v1beta2.

To upgrade from v1beta2, after deploying the new CRD and controller, set apiVersion: notification.toolkit.fluxcd.io/v1 in the YAML files that contain Receiver definitions. Bumping the API version in manifests can be done gradually. It is advised to not delay this procedure as the beta versions will be removed after 6 months.

refs #436

Tasks tbd before merging:

update SOURCE_VER in Makefile to v1.0.0
squash commits into reasonable groups

stefanprodan · 2023-03-23T13:00:01Z

@makkes please fix the "the object has been modified; please apply your changes to the latest version and try again", we need to reload the objects in tests before an update.

With fluxcd/notification-controller#498 we're graduating the Receiver API group version to v1 and keeping all other kinds' version at v1beta2. Therefore we need to publish API docs for both version. Signed-off-by: Max Jonas Werner <mail@makk.es>

With fluxcd/notification-controller#498 we're graduating the Receiver API group version to v1 and keeping all other kinds' version at v1beta2. Therefore we need to publish API docs for both version. refs fluxcd/notification-controller#436 Signed-off-by: Max Jonas Werner <mail@makk.es>

With fluxcd/notification-controller#498 we're graduating the Receiver API group version to v1 and keeping all other kinds' version at v1beta2. Therefore we need to publish API docs for both version. In addition to that we want the API navigation entry to appear at the bottom of the tree. To accomplish that the import script is now able to parse a weight parameter from imported markdown specs and put it into the front matter of the resulting file. refs fluxcd/notification-controller#436 Signed-off-by: Max Jonas Werner <mail@makk.es>

makkes · 2023-03-28T10:57:18Z

Manual upgrade testing:

Bootstrap Flux 0.41.2
Put a Receiver v1beta2 manifest in Git and wait for it to be reconciled
Build the n-c container image from this PR and make the image available to the cluster
Put the Receiver CRD manifest from this PR into the bootstrap repo and patch the n-c Deployment to refer to the newly built image
Push the changes and wait for the flux-system Kustomization to get ready and the new n-c Pod to be spun up
Verify the Receiver object in the cluster is still ready
Check the managed fields of the Receiver
Update the Receiver manifest in Git to API version v1
Verify the Receiver object in the cluster is still ready
Check the managed fields of the Receiver
Modify receiver object in Git, push and reconcile

Results:

After step 6, Receiver is still ready

Managed fields after CRD and n-c upgrade:

managedFields:
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:labels:
        f:kustomize.toolkit.fluxcd.io/name: {}
        f:kustomize.toolkit.fluxcd.io/namespace: {}
    f:spec:
      f:events: {}
      f:resources: {}
      f:secretRef:
        f:name: {}
      f:type: {}
  manager: kustomize-controller
  operation: Apply
  time: "2023-03-28T10:30:33Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:finalizers:
        .: {}
        v:"finalizers.fluxcd.io": {}
  manager: notification-controller
  operation: Update
  time: "2023-03-28T10:29:40Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:status:
      f:conditions: {}
      f:observedGeneration: {}
      f:url: {}
      f:webhookPath: {}
  manager: notification-controller
  operation: Update
  subresource: status
  time: "2023-03-28T10:30:33Z"

Managed fields after step 10:


managedFields:
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:labels:
        f:kustomize.toolkit.fluxcd.io/name: {}
        f:kustomize.toolkit.fluxcd.io/namespace: {}
    f:spec:
      f:events: {}
      f:resources: {}
      f:secretRef:
        f:name: {}
      f:type: {}
  manager: kustomize-controller
  operation: Apply
  time: "2023-03-28T10:30:33Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:finalizers:
        .: {}
        v:"finalizers.fluxcd.io": {}
  manager: notification-controller
  operation: Update
  time: "2023-03-28T10:29:40Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:status:
      f:conditions: {}
      f:observedGeneration: {}
      f:url: {}
      f:webhookPath: {}
  manager: notification-controller
  operation: Update
  subresource: status
  time: "2023-03-28T10:30:33Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:annotations:
        .: {}
        f:reconcile.fluxcd.io/requestedAt: {}
  manager: flux
  operation: Update
  time: "2023-03-28T10:54:08Z"
- apiVersion: notification.toolkit.fluxcd.io/v1
  fieldsType: FieldsV1
  fieldsV1:
    f:status:
      f:lastHandledReconcileAt: {}
  manager: notification-controller
  operation: Update
  subresource: status
  time: "2023-03-28T10:54:08Z"

After step 11:


managedFields:
- apiVersion: notification.toolkit.fluxcd.io/v1
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:labels:
        f:kustomize.toolkit.fluxcd.io/name: {}
        f:kustomize.toolkit.fluxcd.io/namespace: {}
    f:spec:
      f:events: {}
      f:resources: {}
      f:secretRef:
        f:name: {}
      f:type: {}
  manager: kustomize-controller
  operation: Apply
  time: "2023-03-28T10:59:18Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:finalizers:
        .: {}
        v:"finalizers.fluxcd.io": {}
  manager: notification-controller
  operation: Update
  time: "2023-03-28T10:29:40Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:status:
      f:url: {}
      f:webhookPath: {}
  manager: notification-controller
  operation: Update
  subresource: status
  time: "2023-03-28T10:30:33Z"
- apiVersion: notification.toolkit.fluxcd.io/v1beta2
  fieldsType: FieldsV1
  fieldsV1:
    f:metadata:
      f:annotations:
        .: {}
        f:reconcile.fluxcd.io/requestedAt: {}
  manager: flux
  operation: Update
  time: "2023-03-28T10:54:08Z"
- apiVersion: notification.toolkit.fluxcd.io/v1
  fieldsType: FieldsV1
  fieldsV1:
    f:status:
      f:conditions: {}
      f:lastHandledReconcileAt: {}
      f:observedGeneration: {}
  manager: notification-controller
  operation: Update
  subresource: status
  time: "2023-03-28T10:59:18Z"

makkes · 2023-03-29T10:44:59Z

@darkowlzz @somtochiama addressed all of your comments.

darkowlzz

We may need to update https://github.com/fluxcd/notification-controller/blob/main/docs/spec/README.md, similar to how it's updated in SC fluxcd/source-controller@d905985#diff-c0be2b6354cdd4c26a5c58880a73ec4206d21d8e4c67605ddf6c78fb89e56f90 .

makkes · 2023-03-29T12:02:51Z

We may need to update https://github.com/fluxcd/notification-controller/blob/main/docs/spec/README.md, similar to how it's updated in SC fluxcd/source-controller@d905985#diff-c0be2b6354cdd4c26a5c58880a73ec4206d21d8e4c67605ddf6c78fb89e56f90 .

I'm not sure I understand the motivation for removing the paragraphs from the README in s-c and the commit message doesn't mention any. Do we not want this documentation to be available anywhere? I don't really mind but would like to understand how to adapt the README here in n-c accordingly.

darkowlzz · 2023-03-29T13:11:36Z

Do we not want this documentation to be available anywhere?

@makkes I don't know the historic reason for that document but after reading them, it seems like they were initial design docs for the components and now after some maturity and development, most of the specifications of the components are present in the individual API spec docs. So, maybe that document can just link to the spec docs of different versions like in the case of SC.

stefanprodan · 2023-03-29T13:39:11Z

@makkes can you please redo the PR description to document the changes and upgrade procedure? This will help with the changelog.

Examples:

darkowlzz · 2023-03-29T13:54:56Z

internal/server/receiver_server.go is still using the v1beta2 API.

darkowlzz · 2023-03-29T14:04:09Z

v1beta2 CrossNamespaceObjectReference is used by EventServer in internal/server/event_handlers.go. Similar to how in SC all the non-v1 objects refer to the v1 Artifact, I think we can do the same here and use v1 CrossNamespaceObjectReference.

makkes · 2023-03-29T14:09:58Z

v1beta2 CrossNamespaceObjectReference is used by EventServer in internal/server/event_handlers.go. Similar to how in SC all the non-v1 objects refer to the v1 Artifact, I think we can do the same here and use v1 CrossNamespaceObjectReference.

The CrossNamespaceObjectReference used in EventServer is directly consumed from the Alert spec, that's why it's a v1beta2 reference, not a v1 one.

darkowlzz · 2023-03-29T14:11:34Z

Based on the last comment, all the API definitions in api/v1beta2 that have reference to CrossNamespaceObjectReference should import v1 API and refer to it, similar to how it's done for all the Artifact references in SC v1beta2 API.

makkes · 2023-03-29T14:25:13Z

Based on the last comment, all the API definitions in api/v1beta2 that have reference to CrossNamespaceObjectReference should import v1 API and refer to it, similar to how it's done for all the Artifact references in SC v1beta2 API.

I must admit I find it strange to not confine all v1beta2 types to their respective Go package but rather reach out to definitions in another API version. This puts a lot of cognitive burden on developers that are working with the v1 types because they might be used in older versions of the API.

stefanprodan · 2023-03-29T17:17:37Z

I must admit I find it strange to not confine all v1beta2 types to their respective Go package but rather reach out to definitions in another API version. This puts a lot of cognitive burden on developers that are working with the v1 types because they might be used in older versions of the API.

It's only one package github.com/notification-controller/api. So the moment you update the package, all the API versions get imported, the same way it works for Kubernetes apimachinery. What we are doing is similar to Kubernetes Deployments back when Pod Spec was at v1 and Deployments were beta, the beta structs were using the v1 types.

darkowlzz · 2023-03-30T08:37:43Z

make api-docs shows the following warnings:

W0330 13:36:30.098587 3756196 main.go:445] not found external link source for type github.com/fluxcd/notification-controller/api/v1.CrossNamespaceObjectReference
W0330 13:36:30.099848 3756196 main.go:445] not found external link source for type github.com/fluxcd/notification-controller/api/v1.CrossNamespaceObjectReference
W0330 13:36:30.100374 3756196 main.go:445] not found external link source for type github.com/fluxcd/notification-controller/api/v1.CrossNamespaceObjectReference
W0330 13:36:30.102066 3756196 main.go:445] not found external link source for type github.com/fluxcd/notification-controller/api/v1.CrossNamespaceObjectReference

Let's update hack/api-docs/config.json and regenerate docs similar to what's done in SC fluxcd/source-controller@8fcfde9#diff-739b83c5f1e9b3281f7174a89731ce41944600811270b18f67e5a7d97289d262 .

darkowlzz

LGTM!

stefanprodan

LGTM

Thanks @makkes and @darkowlzz

PS. We need to wait for SC release, update the API refs in here, then merge.

This commit bumps the Receiver API version to v1 in preparation of the Flux GitOps GA milestone (https://fluxcd.io/roadmap/#flux-gitops-ga-q1-2023). We are now actively maintaining two versions of the notification API group in parallel: v1 which currently only holds the Receiver kind and v1beta2 for all other kinds. Since we haven't run into this situation before, I had to change the way we expose the API docs in ./docs/api: The directory now has sub-directories for each active API version. Therefore we need to change our scripts in the website repository to take this change into account so that we expose both API group version at https://fluxcd.io/flux/components/notification/api/. This change is implemented in fluxcd/website#1427. refs #436 Signed-off-by: Max Jonas Werner <mail@makk.es>

This functionality has been implemented in #482 but we only want to expose it in v1 of the API. Signed-off-by: Max Jonas Werner <mail@makk.es>

Signed-off-by: Max Jonas Werner <mail@makk.es>

v1 will be the default version in the upcoming version of n-c. Signed-off-by: Max Jonas Werner <mail@makk.es>

makkes force-pushed the receiver-v1 branch 2 times, most recently from 8611b77 to 1e6bd1e Compare March 23, 2023 12:29

stefanprodan changed the title ~~Introduce v1 API and bump Receiver version to v1~~ GA: Promote Receiver API to notification.toolkit.fluxcd.io/v1 Mar 23, 2023

makkes mentioned this pull request Mar 23, 2023

GA: Publish v1 docs for GitRepository, Receiver & Kustomization fluxcd/website#1427

Merged

makkes force-pushed the receiver-v1 branch from 1e6bd1e to 83e946f Compare March 23, 2023 15:12

makkes marked this pull request as ready for review March 23, 2023 16:34

makkes requested review from a team and stefanprodan March 23, 2023 16:35

stefanprodan reviewed Mar 23, 2023

View reviewed changes

Comment thread api/v1/doc.go Outdated

makkes added this to the Bootstrap GA milestone Mar 23, 2023

stefanprodan reviewed Mar 23, 2023

View reviewed changes

Comment thread config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml Outdated

makkes force-pushed the receiver-v1 branch from a0f7b23 to 24b8f92 Compare March 24, 2023 13:15

makkes requested a review from stefanprodan March 24, 2023 13:16

makkes force-pushed the receiver-v1 branch 2 times, most recently from 11adbe7 to 45cdae1 Compare March 27, 2023 16:32

somtochiama reviewed Mar 28, 2023

View reviewed changes

Comment thread docs/spec/v1beta2/events.md

darkowlzz reviewed Mar 28, 2023

View reviewed changes

makkes force-pushed the receiver-v1 branch from dc9a28c to 70dd010 Compare March 29, 2023 10:44

makkes requested review from darkowlzz and somtochiama March 29, 2023 10:44

darkowlzz reviewed Mar 29, 2023

View reviewed changes

Comment thread api/v1/receiver_types.go Outdated

makkes force-pushed the receiver-v1 branch 2 times, most recently from 2259c84 to 249f0d1 Compare March 29, 2023 12:30

makkes force-pushed the receiver-v1 branch 3 times, most recently from 08b1ae2 to af686a3 Compare March 30, 2023 09:23

darkowlzz reviewed Mar 30, 2023

View reviewed changes

Comment thread api/v1/condition_types.go

darkowlzz reviewed Mar 30, 2023

View reviewed changes

Comment thread docs/spec/v1/README.md Outdated

makkes force-pushed the receiver-v1 branch from 28a3ab1 to f45cf83 Compare March 30, 2023 10:41

darkowlzz approved these changes Mar 30, 2023

View reviewed changes

stefanprodan added the hold Issues and pull requests put on hold label Mar 30, 2023

stefanprodan approved these changes Mar 30, 2023

View reviewed changes

Max Jonas Werner added 4 commits March 30, 2023 15:40

document receivers.spec.resources.matchLabels in v1 API

dbeb5a3

This functionality has been implemented in #482 but we only want to expose it in v1 of the API. Signed-off-by: Max Jonas Werner <mail@makk.es>

bump github.com/fluxcd/pkg/ dependencies

a5fe4c1

Signed-off-by: Max Jonas Werner <mail@makk.es>

Use GitRepository v1 as default version in receiver handler

75b1cc1

v1 will be the default version in the upcoming version of n-c. Signed-off-by: Max Jonas Werner <mail@makk.es>

makkes force-pushed the receiver-v1 branch from f45cf83 to 75b1cc1 Compare March 30, 2023 13:51

makkes removed the hold Issues and pull requests put on hold label Mar 30, 2023

makkes merged commit 0af806c into main Mar 30, 2023

makkes deleted the receiver-v1 branch March 30, 2023 14:22

Conversation

makkes commented Mar 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API changes

Upgrade

Uh oh!

stefanprodan commented Mar 23, 2023

Uh oh!

Uh oh!

Uh oh!

makkes commented Mar 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

makkes commented Mar 29, 2023

Uh oh!

darkowlzz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

makkes commented Mar 29, 2023

Uh oh!

darkowlzz commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanprodan commented Mar 29, 2023

Uh oh!

darkowlzz commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

darkowlzz commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

makkes commented Mar 29, 2023

Uh oh!

darkowlzz commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

makkes commented Mar 29, 2023

Uh oh!

stefanprodan commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

darkowlzz commented Mar 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

darkowlzz left a comment

Choose a reason for hiding this comment

Uh oh!

stefanprodan left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

makkes commented Mar 22, 2023 •

edited

Loading

makkes commented Mar 28, 2023 •

edited

Loading

darkowlzz commented Mar 29, 2023 •

edited

Loading

darkowlzz commented Mar 29, 2023 •

edited

Loading

darkowlzz commented Mar 29, 2023 •

edited

Loading

darkowlzz commented Mar 29, 2023 •

edited

Loading

stefanprodan commented Mar 29, 2023 •

edited

Loading

darkowlzz commented Mar 30, 2023 •

edited

Loading