Skip to content

Commit b2992d9

Browse files
joelanfordjoelanford
committed
cmd: keep openapi with deprecation and instructions for migrating
1 parent 920bd3b commit b2992d9

File tree

6 files changed

+231
-7
lines changed

6 files changed

+231
-7
lines changed

‎CHANGELOG.md

+2-4
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
### Added
44
- Support for vars in top level ansible watches. ([#2147](https://github.com/operator-framework/operator-sdk/pull/2147))
55
- Support for `"ansible.operator-sdk/verbosity"` annotation on Custom Resources watched by Ansible based operators to override verbosity on an individual resource. ([#2102](https://github.com/operator-framework/operator-sdk/pull/2102))
6+
- New `operator-sdk generate crds` subcommand, which generates CRDs from Go types. ([#2276](https://github.com/operator-framework/operator-sdk/pull/2276))
67

78
### Changed
89
- Upgrade minimal Ansible version in the init projects from `2.4` to `2.6`. ([#2107](https://github.com/operator-framework/operator-sdk/pull/2107))
@@ -13,12 +14,9 @@
1314
- Replace in the Ansible based operators module tests `k8s_info` for `k8s_facts` which is deprecated. ([#2168](https://github.com/operator-framework/operator-sdk/issues/2168))
1415
- Upgrade the Ansible version from `2.8` to `2.9` on the Ansible based operators image. ([#2168](https://github.com/operator-framework/operator-sdk/issues/2168))
1516
- Updated CRD generation for non-Go operators to use valid structural schema. ([#2275](https://github.com/operator-framework/operator-sdk/issues/2275))
16-
- **Breaking change:** Renamed `operator-sdk generate openapi` to `operator-sdk generate crds`. ([#2276](https://github.com/operator-framework/operator-sdk/pull/2276))
1717

1818
### Deprecated
19-
20-
### Removed
21-
- Removed generation of `zz_generated.openapi.go` files during `operator-sdk generate openapi`. ([#2276](https://github.com/operator-framework/operator-sdk/pull/2276))
19+
- Deprecated the `operator-sdk generate openapi` command. CRD generation is still supported with `operator-sdk generate crds`. It is now recommended to use [openapi-gen](https://github.com/kubernetes/kube-openapi/tree/master/cmd/openapi-gen) directly for OpenAPI code generation. The `generate openapi` subcommand will be removed in a future release. ([#2276](https://github.com/operator-framework/operator-sdk/pull/2276))
2220

2321
### Bug Fixes
2422
- Fix issue faced in the Ansible based operators when `jmespath` queries are used because it was not installed. ([#2252](https://github.com/operator-framework/operator-sdk/pull/2252))

‎cmd/operator-sdk/generate/cmd.go

+1
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,6 @@ func NewCmd() *cobra.Command {
2626
}
2727
cmd.AddCommand(newGenerateK8SCmd())
2828
cmd.AddCommand(newGenerateCRDsCmd())
29+
cmd.AddCommand(newGenerateOpenAPICmd())
2930
return cmd
3031
}

‎cmd/operator-sdk/generate/openapi.go

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Copyright 2019 The Operator-SDK Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package generate
16+
17+
import (
18+
"fmt"
19+
20+
"github.com/operator-framework/operator-sdk/cmd/operator-sdk/internal/genutil"
21+
"github.com/spf13/cobra"
22+
)
23+
24+
func newGenerateOpenAPICmd() *cobra.Command {
25+
return &cobra.Command{
26+
Hidden: true,
27+
Use: "openapi",
28+
Short: "Generates OpenAPI specs for API's",
29+
Long: `generate openapi generates OpenAPI validation specs in Go from tagged types
30+
in all pkg/apis/<group>/<version> directories. Go code is generated under
31+
pkg/apis/<group>/<version>/zz_generated.openapi.go. CRD's are generated, or
32+
updated if they exist for a particular group + version + kind, under
33+
deploy/crds/<full group>_<resource>_crd.yaml; OpenAPI V3 validation YAML
34+
is generated as a 'validation' object.
35+
36+
Example:
37+
38+
$ operator-sdk generate openapi
39+
$ tree pkg/apis
40+
pkg/apis/
41+
└── app
42+
└── v1alpha1
43+
├── zz_generated.openapi.go
44+
$ tree deploy/crds
45+
├── deploy/crds/app.example.com_v1alpha1_appservice_cr.yaml
46+
├── deploy/crds/app.example.com_appservices_crd.yaml
47+
`,
48+
RunE: openAPIFunc,
49+
}
50+
}
51+
52+
const deprecationTemplate = "\033[1;36m%s\033[0m"
53+
54+
func openAPIFunc(cmd *cobra.Command, args []string) error {
55+
fmt.Printf(deprecationTemplate, `[Deprecation notice] The 'operator-sdk generate openapi' command is deprecated!
56+
57+
- To generate CRDs, use 'operator-sdk generate crds'.
58+
- To generate Go OpenAPI code, use 'openapi-gen'. For example:
59+
60+
# Build the latest openapi-gen from source
61+
which ./bin/openapi-gen > /dev/null || go build -o ./bin/openapi-gen k8s.io/kube-openapi/cmd/openapi-gen
62+
63+
# Run openapi-gen for each of your API group/version packages
64+
./bin/openapi-gen --logtostderr=true -o "" -i ./pkg/apis/<group>/<version> -O zz_generated.openapi -p ./pkg/apis/<group>/<version> -h ./hack/boilerplate.go.txt -r "-"
65+
66+
`)
67+
68+
if len(args) != 0 {
69+
return fmt.Errorf("command %s doesn't accept any arguments", cmd.CommandPath())
70+
}
71+
72+
fs := []func() error{
73+
genutil.OpenAPIGen,
74+
genutil.CRDGen,
75+
}
76+
for _, f := range fs {
77+
if err := f(); err != nil {
78+
return err
79+
}
80+
}
81+
return nil
82+
}

‎cmd/operator-sdk/internal/genutil/openapi.go

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// Copyright 2018 The Operator-SDK Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package genutil
16+
17+
import (
18+
"flag"
19+
"fmt"
20+
"os"
21+
"path/filepath"
22+
"strings"
23+
24+
"github.com/operator-framework/operator-sdk/internal/scaffold"
25+
"github.com/operator-framework/operator-sdk/internal/util/k8sutil"
26+
"github.com/operator-framework/operator-sdk/internal/util/projutil"
27+
28+
"github.com/pkg/errors"
29+
log "github.com/sirupsen/logrus"
30+
generatorargs "k8s.io/kube-openapi/cmd/openapi-gen/args"
31+
"k8s.io/kube-openapi/pkg/generators"
32+
)
33+
34+
// OpenAPIGen generates OpenAPI validation specs for all CRD's in dirs.
35+
func OpenAPIGen() error {
36+
projutil.MustInProjectRoot()
37+
38+
repoPkg := projutil.GetGoPkg()
39+
40+
gvMap, err := k8sutil.ParseGroupSubpackages(scaffold.ApisDir)
41+
if err != nil {
42+
return fmt.Errorf("failed to parse group versions: (%v)", err)
43+
}
44+
gvb := &strings.Builder{}
45+
for g, vs := range gvMap {
46+
gvb.WriteString(fmt.Sprintf("%s:%v, ", g, vs))
47+
}
48+
49+
log.Infof("Running OpenAPI code-generation for Custom Resource group versions: [%v]\n", gvb.String())
50+
51+
apisPkg := filepath.Join(repoPkg, scaffold.ApisDir)
52+
fqApis := k8sutil.CreateFQAPIs(apisPkg, gvMap)
53+
f := func(a string) error { return openAPIGen(a, fqApis) }
54+
if err = generateWithHeaderFile(f); err != nil {
55+
return err
56+
}
57+
58+
log.Info("Code-generation complete.")
59+
return nil
60+
}
61+
62+
func openAPIGen(hf string, fqApis []string) error {
63+
wd, err := os.Getwd()
64+
if err != nil {
65+
return err
66+
}
67+
if err := flag.Set("logtostderr", "true"); err != nil {
68+
return err
69+
}
70+
for _, api := range fqApis {
71+
api = filepath.FromSlash(api)
72+
// Use relative API path so the generator writes to the correct path.
73+
apiPath := "." + string(filepath.Separator) + api[strings.Index(api, scaffold.ApisDir):]
74+
args, cargs := generatorargs.NewDefaults()
75+
// Ignore default output base and set our own output path.
76+
args.OutputBase = ""
77+
// openapi-gen already generates a "do not edit" comment.
78+
args.GeneratedByCommentTemplate = ""
79+
args.InputDirs = []string{apiPath}
80+
args.OutputFileBaseName = "zz_generated.openapi"
81+
args.OutputPackagePath = filepath.Join(wd, apiPath)
82+
args.GoHeaderFilePath = hf
83+
// Print API rule violations to stdout
84+
cargs.ReportFilename = "-"
85+
if err := generatorargs.Validate(args); err != nil {
86+
return errors.Wrap(err, "openapi-gen argument validation error")
87+
}
88+
89+
err := args.Execute(
90+
generators.NameSystems(),
91+
generators.DefaultNameSystem(),
92+
generators.Packages,
93+
)
94+
if err != nil {
95+
return errors.Wrap(err, "openapi-gen generator error")
96+
}
97+
}
98+
return nil
99+
}

‎doc/sdk-cli-reference.md

+46-2
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,49 @@ pkg/apis/app/v1alpha1/
132132
└── zz_generated.deepcopy.go
133133
```
134134

135+
### openapi
136+
137+
> **DEPRECATED**
138+
>
139+
> The `operator-sdk generate openapi` command is deprecated
140+
> - To generate CRDs, use 'operator-sdk generate crds'.
141+
> - To generate Go OpenAPI code, use 'openapi-gen'. For example:
142+
>
143+
> ```console
144+
> # Build the latest openapi-gen from source
145+
> which ./bin/openapi-gen > /dev/null || go build -o ./bin/openapi-gen k8s.io/kube-openapi/cmd/openapi-gen
146+
>
147+
> # Run openapi-gen for each of your API group/version packages
148+
> ./bin/openapi-gen --logtostderr=true -o "" -i ./pkg/apis/<group>/<version> -O zz_generated.openapi -p ./pkg/apis/<group>/<version> -h ./hack/boilerplate.go.txt -r "-"
149+
> ```
150+
151+
152+
Runs the [kube-openapi][openapi-code-generator] OpenAPIv3 code generator for all Custom Resource Definition (CRD) API tagged fields under `pkg/apis/...`.
153+
154+
**Note**: This command must be run every time a tagged API struct or struct field for a custom resource type is updated.
155+
156+
#### Example
157+
158+
```console
159+
$ tree pkg/apis/app/v1alpha1/
160+
pkg/apis/app/v1alpha1/
161+
├── appservice_types.go
162+
├── doc.go
163+
└── register.go
164+
165+
$ operator-sdk generate openapi
166+
INFO[0000] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ]
167+
INFO[0001] Created deploy/crds/app.example.com_appservices_crd.yaml
168+
INFO[0001] Code-generation complete.
169+
170+
$ tree pkg/apis/app/v1alpha1/
171+
pkg/apis/app/v1alpha1/
172+
├── appservice_types.go
173+
├── doc.go
174+
├── register.go
175+
└── zz_generated.openapi.go
176+
```
177+
135178
### crds
136179

137180
Runs CRD generation (based on controller-tools) for APIs under `pkg/apis/...`.
@@ -145,7 +188,7 @@ $ tree pkg/apis/app/v1alpha1/
145188
pkg/apis/app/v1alpha1/
146189
├── appservice_types.go
147190
├── doc.go
148-
├── register.go
191+
└── register.go
149192

150193
$ operator-sdk generate crds
151194
INFO[0000] Running CRD generation for Custom Resource group versions: [app:[v1alpha1], ]
@@ -154,7 +197,7 @@ INFO[0001] CRD generation complete.
154197

155198
$ tree deploy/crds/
156199
deploy/crds
157-
├── app.example.com_appservices_crd.yaml
200+
└── app.example.com_appservices_crd.yaml
158201
```
159202

160203
## olm-catalog
@@ -574,4 +617,5 @@ status of each of those resources as they exist in the cluster.
574617

575618
[utility_link]: https://github.com/operator-framework/operator-sdk/blob/89bf021063d18b6769bdc551ed08fc37027939d5/pkg/util/k8sutil/k8sutil.go#L140
576619
[k8s-code-generator]: https://github.com/kubernetes/code-generator
620+
[openapi-code-generator]: https://github.com/kubernetes/kube-openapi
577621
[helm-user-guide-create-project]: https://github.com/operator-framework/operator-sdk/blob/master/doc/helm/user-guide.md#create-a-new-project

‎go.mod

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ require (
5656
k8s.io/gengo v0.0.0-20191010091904-7fa3014cb28f
5757
k8s.io/helm v2.16.1+incompatible
5858
k8s.io/klog v1.0.0
59-
k8s.io/kube-openapi v0.0.0-20190918143330-0270cf2f1c1d // indirect
59+
k8s.io/kube-openapi v0.0.0-20190918143330-0270cf2f1c1d
6060
k8s.io/kube-state-metrics v1.7.2
6161
k8s.io/kubectl v0.0.0
6262
k8s.io/kubernetes v1.16.2

0 commit comments

Comments
 (0)