Bug 1830270: cmd: add explain subcommand #3515

abhinavdahiya · 2020-04-28T04:48:01Z

$ ./bin/openshift-install explain installconfig
KIND:     InstallConfig
VERSION:  v1

RESOURCE: <object>
  InstallConfig is the configuration for an OpenShift install.

FIELDS:
    additionalTrustBundle <string>
      AdditionalTrustBundle is a PEM-encoded X.509 certificate bundle that will be added to the nodes' trusted certificate store.

    apiVersion <string>
      APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

    baseDomain <string> -required-
      BaseDomain is the base domain to which the cluster should belong.

    compute <[]object>
      Compute is the configuration for the machines that comprise the compute nodes.
      MachinePool is a pool of machines to be installed.

    controlPlane <object>
      ControlPlane is the configuration for the machines that comprise the control plane.

    fips <boolean>
      Default: false
      FIPS configures https://www.nist.gov/itl/fips-general-information

    imageContentSources <[]object>
      ImageContentSources lists sources/repositories for the release-image content.
      ImageContentSource defines a list of sources/repositories that can be used to pull content.

    kind <string>
      Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

    metadata <object> -required-
      <empty>

    networking <object>
      Networking is the configuration for the pod network provider in the cluster.

    platform <object> -required-
      Platform is the configuration for the specific platform upon which to perform the installation.

    proxy <object>
      Proxy defines the proxy settings for the cluster. If unset, the cluster will not be configured to use a proxy.

    publish <string>
      Default: "External"
      Valid Values: "","External","Internal"
      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`.

    pullSecret <string> -required-
      PullSecret is the secret to use when pulling images.

    sshKey <string>
      SSHKey is the public Secure Shell (SSH) key to provide access to instances.

$ ./bin/openshift-install explain installconfig.platform.aws
KIND:     InstallConfig
VERSION:  v1

RESOURCE: <object>
  AWS is the configuration used when installing on AWS.

FIELDS:
    amiID <string>
      AMIID is the AMI that should be used to boot machines for the cluster. If set, the AMI should belong to the same region as the cluster.

    defaultMachinePlatform <object>
      DefaultMachinePlatform is the default configuration used when installing on AWS for machine pools which do not define their own platform configuration.

    region <string> -required-
      Region specifies the AWS region where the cluster will be created.

    serviceEndpoints <[]object>
      ServiceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service.
      ServiceEndpoint store the configuration for services to override existing defaults of AWS Services.

    subnets <[]string>
      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.

    userTags <object>
      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.

$ ./bin/openshift-install explain installconfig.platform.libvirt
KIND:     InstallConfig
VERSION:  v1

RESOURCE: <object>
  Libvirt is the configuration used when installing on libvirt.

FIELDS:
    URI <string>
      Default: "qemu+tcp://192.168.122.1/system"
      URI is the identifier for the libvirtd connection.  It must be reachable from both the host (where the installer is run) and the cluster (where the cluster-API controller pod will be running). Default is qemu+tcp://192.168.122.1/system

    defaultMachinePlatform <object>
      DefaultMachinePlatform is the default configuration used when installing on libvirt for machine pools which do not define their own platform configuration. Default will set the image field to the latest RHCOS image.

    network <object>
      Network

$ ./bin/openshift-install explain installconfig.platform.aws.serviceEndpoints
KIND:     InstallConfig
VERSION:  v1

RESOURCE: <[]object>
  ServiceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service.

FIELDS:
    name <string>
      Name is the name of the AWS service. This must be provided and cannot be empty.

    url <string>
      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.

abhinavdahiya · 2020-04-28T05:59:14Z

f036749
has a replace directive to local fork, because of kubernetes-sigs/controller-tools#427

otherwise the pkg.IPNet prevents the creation of the CRD object...
/wip

wking · 2020-05-01T02:02:27Z

docs/dev/explain.md

+
+## 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


missing an anchor for effective-go?

@wking fixed

wking · 2020-05-01T02:04:04Z

docs/dev/explain.md

+
+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 is static, `+kubebuilder:validation=Default` marker should be used, otherwise the comment must clearly define how the default value will be calculated.


nit: "values is" -> "value is" or "values are"

@wking fixed

sdodson · 2020-05-01T12:15:37Z

/retitle Bug 1830270: cmd: add explain subcommand

openshift-ci-robot · 2020-05-01T12:15:56Z

@abhinavdahiya: This pull request references Bugzilla bug 1830270, which is valid. The bug has been moved to the POST state. The bug has been updated to refer to the pull request using the external bug tracker.

3 validation(s) were run on this bug

bug is open, matching expected state (open)
bug target release (4.5.0) matches configured target release for branch (4.5.0)
bug is in the state NEW, which is one of the valid states (NEW, ASSIGNED, ON_DEV, POST, POST)

In response to this:

Bug 1830270: cmd: add explain subcommand

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

sdodson · 2020-05-01T12:16:52Z

/approve

openshift-ci-robot · 2020-05-01T12:17:07Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sdodson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [sdodson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

patrickdillon

Noted a couple of typos.

patrickdillon · 2020-05-01T13:07:04Z

pkg/explain/cmd.go

+		Long: `This command describes the fields associated with each supported InstallConfig API. Fields are identified via a simple
+JSONPath identifier:
+
+isntallconfig.<fieldName>[.<fieldName>]


isntallconfig -> installconfig

@patrickdillon fixed

patrickdillon · 2020-05-01T13:08:12Z

pkg/explain/cmd.go

+
+	raw, err := ioutil.ReadAll(file)
+	if err != nil {
+		return errors.Wrap(err, "faield to read InstallConfig CRD")


faield -> failed

@patrickdillon fixed

abhinavdahiya · 2020-05-01T17:37:59Z

/skip

patrickdillon · 2020-05-07T12:53:08Z

LGTM
Needs rebase but there is no label. Ping me for lgtm when resolved.

go generate ./pkg/types/installconfig.go

The explain package provides an `explain` cobra command that can use used to add it as subcommand. The package includes 2 major functions, - fields_lookup Given a list of paths, this finds the schema for the path from the install config schema. - printer The printer printers the schema provided to the function The printer always prints the InstallConfig apiVersion, kind to the provided io.Writer It prints the description of the field using the schema provided, and for object type, it also prints all the properties of the object and their descriptions.

abhinavdahiya · 2020-05-07T16:23:41Z

@patrickdillon rebased the PR on master

patrickdillon · 2020-05-07T16:52:07Z

/lgtm

openshift-bot · 2020-05-07T17:29:28Z

/retest

Please review the full test history for this PR and help us cut down flakes.

openshift-bot · 2020-05-07T17:55:27Z

/retest

Please review the full test history for this PR and help us cut down flakes.

openshift-ci-robot · 2020-05-07T18:02:21Z

@abhinavdahiya: The following tests failed, say /retest to rerun all failed tests:

Test name	Commit	Details	Rerun command
ci/prow/e2e-metal-ipi	`2b02482`	link	`/test e2e-metal-ipi`
ci/prow/e2e-aws-fips	`4d03a03`	link	`/test e2e-aws-fips`
ci/prow/e2e-aws-scaleup-rhel7	`4d03a03`	link	`/test e2e-aws-scaleup-rhel7`
ci/prow/e2e-libvirt	`4d03a03`	link	`/test e2e-libvirt`

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

openshift-ci-robot · 2020-05-07T18:06:52Z

@abhinavdahiya: All pull requests linked via external trackers have merged: openshift/installer#3515. Bugzilla bug 1830270 has been moved to the MODIFIED state.

In response to this:

Bug 1830270: cmd: add explain subcommand

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

openshift-ci-robot requested review from markmc and mtnbikenc April 28, 2020 04:48

abhinavdahiya requested review from a team and removed request for markmc and mtnbikenc April 28, 2020 05:59

abhinavdahiya force-pushed the installconfig_explain branch 2 times, most recently from 65b203b to cda31e0 Compare April 28, 2020 06:20

openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 30, 2020

abhinavdahiya force-pushed the installconfig_explain branch from cda31e0 to 1f77e5c Compare April 30, 2020 22:52

openshift-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 30, 2020

abhinavdahiya force-pushed the installconfig_explain branch 2 times, most recently from 1c6a05b to cbbf437 Compare April 30, 2020 23:59

wking reviewed May 1, 2020

View reviewed changes

openshift-ci-robot changed the title ~~cmd: add explain subcommand~~ Bug 1830270: cmd: add explain subcommand May 1, 2020

openshift-ci-robot added the bugzilla/severity-medium Referenced Bugzilla bug's severity is medium for the branch this PR is targeting. label May 1, 2020

openshift-ci-robot added the bugzilla/valid-bug Indicates that a referenced Bugzilla bug is valid for the branch this PR is targeting. label May 1, 2020

openshift-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 1, 2020

patrickdillon reviewed May 1, 2020

View reviewed changes

abhinavdahiya force-pushed the installconfig_explain branch from cbbf437 to 2b02482 Compare May 1, 2020 16:11

abhinavdahiya added 3 commits May 7, 2020 09:22

pkg/types: ensure kubebuilder can build correct documentation

c1dbb13

go generate ./pkg/types/installconfig.go

cmd/openshift-install: add explain subcommand

6ae9df0

abhinavdahiya added 2 commits May 7, 2020 09:22

docs/dev: add guidelines for maintaining explain

1656532

vendor: add controller-tools to vendor

4d03a03

abhinavdahiya force-pushed the installconfig_explain branch from 2b02482 to 4d03a03 Compare May 7, 2020 16:22

openshift-ci-robot assigned patrickdillon May 7, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label May 7, 2020

openshift-merge-robot merged commit ca754a3 into openshift:master May 7, 2020

This was referenced May 8, 2020

Bug 1833425: pkg/explain/cmd.go: fix help text #3570

Merged

Bug 1820300: Extend oVirt's MachinePool #3399

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bug 1830270: cmd: add explain subcommand #3515

Bug 1830270: cmd: add explain subcommand #3515

abhinavdahiya commented Apr 28, 2020

abhinavdahiya commented Apr 28, 2020

wking May 1, 2020

abhinavdahiya May 1, 2020

wking May 1, 2020

abhinavdahiya May 1, 2020

sdodson commented May 1, 2020

openshift-ci-robot commented May 1, 2020

sdodson commented May 1, 2020

openshift-ci-robot commented May 1, 2020

patrickdillon left a comment

patrickdillon May 1, 2020

abhinavdahiya May 1, 2020

patrickdillon May 1, 2020

abhinavdahiya May 1, 2020

abhinavdahiya commented May 1, 2020

patrickdillon commented May 7, 2020

abhinavdahiya commented May 7, 2020

patrickdillon commented May 7, 2020

openshift-bot commented May 7, 2020

openshift-bot commented May 7, 2020

openshift-ci-robot commented May 7, 2020

openshift-ci-robot commented May 7, 2020


		## 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


		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 is static, `+kubebuilder:validation=Default` marker should be used, otherwise the comment must clearly define how the default value will be calculated.

Bug 1830270: cmd: add explain subcommand #3515

Bug 1830270: cmd: add explain subcommand #3515

Conversation

abhinavdahiya commented Apr 28, 2020

abhinavdahiya commented Apr 28, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdodson commented May 1, 2020

openshift-ci-robot commented May 1, 2020

sdodson commented May 1, 2020

openshift-ci-robot commented May 1, 2020

patrickdillon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abhinavdahiya commented May 1, 2020

patrickdillon commented May 7, 2020

abhinavdahiya commented May 7, 2020

patrickdillon commented May 7, 2020

openshift-bot commented May 7, 2020

openshift-bot commented May 7, 2020

openshift-ci-robot commented May 7, 2020

openshift-ci-robot commented May 7, 2020