-
Notifications
You must be signed in to change notification settings - Fork 1.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Bug 1830270: cmd: add explain subcommand #3515
Merged
openshift-merge-robot
merged 5 commits into
openshift:master
from
abhinavdahiya:installconfig_explain
May 7, 2020
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
c1dbb13
pkg/types: ensure kubebuilder can build correct documentation
abhinavdahiya a194303
pkg: add explain package
abhinavdahiya 6ae9df0
cmd/openshift-install: add explain subcommand
abhinavdahiya 1656532
docs/dev: add guidelines for maintaining explain
abhinavdahiya 4d03a03
vendor: add controller-tools to vendor
abhinavdahiya File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,3 +14,4 @@ rules: | |
|
|
||
| ignore: | | ||
| vendor/ | ||
| data/data/install.openshift.io_installconfigs.yaml | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "github.com/spf13/cobra" | ||
|
|
||
| "github.com/openshift/installer/pkg/explain" | ||
| ) | ||
|
|
||
| func newExplainCmd() *cobra.Command { | ||
| return explain.NewCmd() | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1,240 changes: 1,240 additions & 0 deletions
1,240
data/data/install.openshift.io_installconfigs.yaml
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| # InstallConfig Explain | ||
|
|
||
| The installer allows it's users to see all the configuration available using the `explain` subcommand. The command works almost like the | ||
| the `oc explain` subcommand. | ||
|
|
||
| ## Generating the documentation | ||
|
|
||
| Like `oc explain` and Custom Resource Definitions, the installer also generates an internal only Custom Resource Definition for the `InstallConfig`. | ||
|
|
||
| ```sh | ||
| go generate ./pkg/types/installconfig.go | ||
| ``` | ||
|
|
||
| The code generation uses the upstream project kubebuilder, which provides tools like controller-tools to [generate][kubebuilder-generate-crd] Custom Resource Definitions. | ||
|
|
||
| ## Descriptions of fields and various types | ||
|
|
||
| The generator uses the Godoc comments on the fields and types to create the descriptions. Therefore, making sure that everything used by the `InstallConfig` definition has user friendly comments will automatically transfer to user friendly explain output. | ||
|
|
||
| ## Kubebuilder markers | ||
|
|
||
| The generator allows use of various markers for fields and types to provide information about the valid inputs. Various available markers are defined [here][kubebuilder-validation-markers] | ||
|
|
||
| ## Additional guidelines on godoc comments | ||
|
|
||
| All definitions in installer codebase already follow and enforce [effective-go] guidelines, but for better explain output for the types these additional guidelines should also be followed | ||
|
|
||
| 1. No external types are allowed to be used in the `InstallConfig`. All the types used should be defined in the installer repository itself. The only exception is the `TypeMeta` and `ObjectMeta`. | ||
|
|
||
| 2. Fields should always have `json` tags that follow [mixedCaps][go-mixed-caps] and should always start with lowercase. | ||
|
|
||
| 3. The comments on the fields must use the `json` tag to reference the field. | ||
|
|
||
| 4. Optional fields must have the `+optional` marker defined. Optional fields must also define the default value. If the values are static, `+kubebuilder:validation=Default` marker should be used, otherwise the comment must clearly define how the default value will be calculated. | ||
|
|
||
| 5. Only string based enum types are allowed. Also such enum type must use `+kubebuilder:validation:Enum` marker. | ||
|
|
||
| [go-effective]: https://golang.org/doc/effective_go.html | ||
| [go-mixed-caps]: https://golang.org/doc/effective_go.html#mixed-caps | ||
| [kubebuilder-generate-crd]: https://book.kubebuilder.io/reference/generating-crd.html | ||
| [kubebuilder-validation-markers]: https://book.kubebuilder.io/reference/markers/crd-validation.html | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| package explain | ||
|
|
||
| import ( | ||
| "io/ioutil" | ||
| "os" | ||
| "strings" | ||
|
|
||
| "github.com/openshift/installer/data" | ||
| "github.com/pkg/errors" | ||
| "github.com/spf13/cobra" | ||
| ) | ||
|
|
||
| // NewCmd returns a subcommand for explain | ||
| func NewCmd() *cobra.Command { | ||
| cmd := &cobra.Command{ | ||
| Use: "explain", | ||
| Short: "List the fields for supported InstallConfig versions", | ||
| Long: `This command describes the fields associated with each supported InstallConfig API. Fields are identified via a simple | ||
| JSONPath identifier: | ||
|
|
||
| installconfig.<fieldName>[.<fieldName>] | ||
| `, | ||
| Example: ` | ||
| # Get the documentation of the resource and its fields | ||
| kubectl explain installconfig | ||
|
|
||
| # Get the documentation of a AWS platform | ||
| kubectl explain installconfig.platform.aws`, | ||
| RunE: runCmd, | ||
| } | ||
|
|
||
| return cmd | ||
| } | ||
|
|
||
| func runCmd(cmd *cobra.Command, args []string) error { | ||
| if len(args) == 0 { | ||
| return errors.Errorf("You must specify the type of resource to explain\n") | ||
| } | ||
| if len(args) > 1 { | ||
| return errors.Errorf("We accept only this format: explain RESOURCE\n") | ||
| } | ||
|
|
||
| file, err := data.Assets.Open(installConfigCRDFileName) | ||
| if err != nil { | ||
| return errors.Wrap(err, "failed to load InstallConfig CRD") | ||
| } | ||
| defer file.Close() | ||
|
|
||
| raw, err := ioutil.ReadAll(file) | ||
| if err != nil { | ||
| return errors.Wrap(err, "failed to read InstallConfig CRD") | ||
| } | ||
|
|
||
| resource, path := splitDotNotation(args[0]) | ||
| if resource != "installconfig" { | ||
| return errors.Errorf("only installconfig resource is supported") | ||
| } | ||
|
|
||
| schema, err := loadSchema(raw) | ||
| if err != nil { | ||
| return errors.Wrap(err, "failed to load schema") | ||
| } | ||
|
|
||
| fschema, err := lookup(schema, path) | ||
| if err != nil { | ||
| return errors.Wrapf(err, "failed to load schema for the field %s", strings.Join(path, ".")) | ||
| } | ||
|
|
||
| p := printer{Writer: os.Stdout} | ||
| p.PrintKindAndVersion() | ||
| p.PrintResource(fschema) | ||
| p.PrintFields(fschema) | ||
| return nil | ||
| } | ||
|
|
||
| func splitDotNotation(model string) (string, []string) { | ||
| var fieldsPath []string | ||
|
|
||
| // ignore trailing period | ||
| model = strings.TrimSuffix(model, ".") | ||
|
|
||
| dotModel := strings.Split(model, ".") | ||
| if len(dotModel) >= 1 { | ||
| fieldsPath = dotModel[1:] | ||
| } | ||
| return dotModel[0], fieldsPath | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| package explain | ||
|
|
||
| import ( | ||
| "io/ioutil" | ||
| "testing" | ||
| ) | ||
|
|
||
| func loadCRD(t *testing.T) []byte { | ||
| crd, err := ioutil.ReadFile("../../data/data/install.openshift.io_installconfigs.yaml") | ||
| if err != nil { | ||
| t.Fatalf("failed to load CRD: %v", err) | ||
| } | ||
| return crd | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| package explain |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| package explain | ||
|
|
||
| const ( | ||
| installConfigCRDFileName = "install.openshift.io_installconfigs.yaml" | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| package explain | ||
|
|
||
| import ( | ||
| "github.com/pkg/errors" | ||
| apiextv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" | ||
| ) | ||
|
|
||
| func lookup(schema *apiextv1.JSONSchemaProps, path []string) (*apiextv1.JSONSchemaProps, error) { | ||
| if len(path) == 0 { | ||
| return schema, nil | ||
| } | ||
|
|
||
| properties := map[string]apiextv1.JSONSchemaProps{} | ||
| if schema.Items != nil && schema.Items.Schema != nil { | ||
| properties = schema.Items.Schema.Properties | ||
| } | ||
| if len(schema.Properties) > 0 { | ||
| properties = schema.Properties | ||
| } | ||
|
|
||
| property, ok := properties[path[0]] | ||
| if !ok { | ||
| return nil, errors.Errorf("invalid field %s, no such property found", path[0]) | ||
| } | ||
| return lookup(&property, path[1:]) | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| package explain | ||
|
|
||
| import ( | ||
| "testing" | ||
|
|
||
| "github.com/stretchr/testify/assert" | ||
| ) | ||
|
|
||
| func Test_lookup(t *testing.T) { | ||
| schema, err := loadSchema(loadCRD(t)) | ||
| assert.NoError(t, err) | ||
|
|
||
| cases := []struct { | ||
| path []string | ||
|
|
||
| desc string | ||
| err string | ||
| }{{ | ||
| desc: `InstallConfig is the configuration for an OpenShift install.`, | ||
| }, { | ||
| path: []string{"publish"}, | ||
| desc: `Publish controls how the user facing endpoints of the cluster like the Kubernetes API, OpenShift routes etc. are exposed. When no strategy is specified, the strategy is "External".`, | ||
| }, { | ||
| path: []string{"publish", "unknown"}, | ||
| err: `invalid field unknown, no such property found`, | ||
| }, { | ||
| path: []string{"platform"}, | ||
| desc: `Platform is the configuration for the specific platform upon which to perform the installation.`, | ||
| }, { | ||
| path: []string{"platform", "aws"}, | ||
| desc: `AWS is the configuration used when installing on AWS.`, | ||
| }, { | ||
| path: []string{"platform", "azure"}, | ||
| desc: `Azure is the configuration used when installing on Azure.`, | ||
| }, { | ||
| path: []string{"platform", "aws", "region"}, | ||
| desc: `Region specifies the AWS region where the cluster will be created.`, | ||
| }, { | ||
| path: []string{"platform", "aws", "subnets"}, | ||
| desc: `Subnets specifies existing subnets (by ID) where cluster resources will be created. Leave unset to have the installer create subnets in a new VPC on your behalf.`, | ||
| }, { | ||
| path: []string{"platform", "aws", "userTags"}, | ||
| desc: `UserTags additional keys and values that the installer will add as tags to all resources that it creates. Resources created by the cluster itself may not include these tags.`, | ||
| }, { | ||
| path: []string{"platform", "aws", "serviceEndpoints"}, | ||
| desc: `ServiceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service.`, | ||
| }, { | ||
| path: []string{"platform", "aws", "serviceEndpoints", "url"}, | ||
| desc: `URL is fully qualified URI with scheme https, that overrides the default generated endpoint for a client. This must be provided and cannot be empty.`, | ||
| }} | ||
| for _, test := range cases { | ||
| t.Run("", func(t *testing.T) { | ||
| got, err := lookup(schema, test.path) | ||
| if test.err == "" { | ||
| assert.NoError(t, err) | ||
| assert.Equal(t, test.desc, got.Description) | ||
| } else { | ||
| assert.Regexp(t, test.err, err) | ||
| } | ||
| }) | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
missing an anchor for
effective-go?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@wking fixed