feat: kustomize rollout: add openapi to doc and examples

[huikang]

• openAPI schema for kustomize rollout

Signed-off-by: Hui Kang [email protected]

close #1210

Checklist:

• Either (a) I've created an enhancement proposal and discussed it with the community, (b) this is a bug fix, or (c) this is a chore.
• The title of the PR is (a) conventional, (b) states what changed, and (c) suffixes the related issues number. E.g. "fix(controller): Updates such and such. Fixes #1234".
• I've signed my commits with DCO
• I have written unit and/or e2e tests for my change. PRs without these are unlikely to be merged.
• My builds are green. Try syncing with master if they are not.
• My organization is added to USERS.md.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.9% Duplication

[codecov]

Codecov Report

Merging #1371 (9273141) into master (1353526) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1371   +/-   ##
=======================================
  Coverage   81.35%   81.35%           
=======================================
  Files         108      108           
  Lines       14505    14505           
=======================================
  Hits        11801    11801           
  Misses       2089     2089           
  Partials      615      615           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1353526...9273141. Read the comment docs.

[jessesuen]

@huikang - did you hand code the rollout_cr_schema.json file? Is there not a way to auto-generate it?

[huikang]

Hi, @jessesuen , yeah, I handcoded rollout_cr_schema.json by adapting from this example. It seems to me the openapi data is flexible to customize different use case; I have not found any way to auto-generate the content from the k8s type. Please let me know if you are aware of any approach.

[jessesuen]

This file:
https://github.com/argoproj/argo-rollouts/blob/master/pkg/apiclient/rollout/rollout.swagger.json

is autogenerated. I thought something similar would need to be done for Rollouts but with the SMP keys

[huikang]

This file:
https://github.com/argoproj/argo-rollouts/blob/master/pkg/apiclient/rollout/rollout.swagger.json

is autogenerated. I thought something similar would need to be done for Rollouts but with the SMP keys

Thanks. Let me look into the options of the open-api tool.

[huikang]

Hi, @jessesuen , just want to make sure I understand the problem correctly: the problem is that the content in https://github.com/argoproj/argo-rollouts/blob/master/pkg/apiclient/rollout/rollout.swagger.json misses some x-kubernetes-patch-merge-key and x-kubernetes-patch-strategy for certain properties. For example, in the definition of

type PodSpec struct {
  Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" ...`

the containers has the patchStrategy and patchMergeKey, however, the generated rollout.swagger.json misses x-kubernetes-patch-merge-key and x-kubernetes-patch-strategy.

So we need to figure our how to let

argo-rollouts/Makefile

Line 50 in e3dc6af

PATH=${DIST_DIR}:$$PATH protoc \

attach these annotations in the generated json file.

Is my understanding correct? Thanks.

[jessesuen]

Yes, that is correct. The goal is for kustomize 4 to be able to patch rollouts in the same way as deployments. If we can achieve this via automation that would be ideal, but not sure if that is possible.

[huikang]

Yes, that is correct. The goal is for kustomize 4 to be able to patch rollouts in the same way as deployments. If we can achieve this via automation that would be ideal, but not sure if that is possible.

Following is my findings:

1. This is how k8s api is exposed as a json file:

https://github.com/kubernetes/kubernetes/blob/ea0764452222146c47ec826977f49d7001b0ea8c/hack/update-openapi-spec.sh#L101

2. In addition, I found that the kustomize openapi fetch returns

    "io.argoproj.v1alpha1.Rollout": {
      "properties": {
        "apiVersion": {
          "type": "string"
        },
        "kind": {
          "type": "string"
        },
        "metadata": {
          "$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta",
          "description": "Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata"
        },
        "spec": {
            "template": {
              "properties": {
                "metadata": {
                  "properties": {
                    "annotations": {
                      "additionalProperties": {
                        "type": "string"

If I change the key "template" to

"template": {
              "$ref": "#/definitions/io.k8s.api.core.v1.PodTemplateSpec"
            }

The SMP would work. Not sure why the original one does not use the reference definition.

[alexmt]

@huikang , I think I found a way to generate schema. There is no out of the box generator unfortunatelly so I had to write more go code in gen-crd-spec/main.go.

We need tests and documentation changes from your PR so I've sent PR to your fork: huikang#1 . Once it is merged this PR should be complete. Can you please take a look?

[huikang]

@huikang , I think I found a way to generate schema. There is no out of the box generator unfortunatelly so I had to write more go code in gen-crd-spec/main.go.

We tests and documentation changes from your PR so I've sent PR to your fork: huikang#1 . Once it is merged this PR should be complete. Can you please take a look?

Sounds good. Thanks, @alexmt !

[huikang]

Hi, @alexmt , I have merged your commit and cleaned up the PR a bit. However, when the new command failed due to the following error

go run ./hack/gen-crd-spec/main.go
panic: Version string empty

goroutine 1 [running]:
main.checkErr(...)
	/Users/hui.kang/go/src/github.com/huikang/argo-rollouts-backup2/hack/gen-crd-spec/main.go:287
main.main()
	/Users/hui.kang/go/src/github.com/huikang/argo-rollouts-backup2/hack/gen-crd-spec/main.go:467 +0x5d3
exit status 2

Could you take a look? Thanks.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
0.0% Duplication

[alexmt]

LGTM!