forked from k8sgateway/k8sgateway
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into yuval-k/make-it-work-with-discovery
- Loading branch information
Showing
158 changed files
with
690 additions
and
429 deletions.
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
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
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,9 @@ | ||
| changelog: | ||
| - type: NON_USER_FACING | ||
| issueLink: https://github.com/solo-io/gloo/issues/10364 | ||
| resolvesIssue: false | ||
| description: >- | ||
| When setting up our kind cluster for tests, we need to ensure that the correct version of the k8sgateway APIs are loaded, as | ||
| we support multiple versions of Istio that use different versions of the rapidly changing k8sgateway APIs. | ||
| To support this, `k8sgateway_api_version` has been added to the the min/max environment variables for the test matrix | ||
| and the value are set as the `CONFORMANCE_VERSION` environment variable when running the setup-kind script. |
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,10 @@ | ||
| changelog: | ||
| - type: NON_USER_FACING | ||
| issueLink: https://github.com/solo-io/solo-projects/issues/6612 | ||
| resolvesIssue: false | ||
| description: >- | ||
| Generate the documentation using the updated markdown templates to fit new formatting guidelines. | ||
| - type: DEPENDENCY_BUMP | ||
| dependencyOwner: solo-io | ||
| dependencyRepo: solo-kit | ||
| dependencyTag: v0.36.3 |
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,39 @@ | ||
| # CRD Reference Documentation | ||
|
|
||
| ### Background | ||
| We are trying to migrate our APIs and CRDs to be built using Kubebuilder. | ||
|
|
||
| Historically, our docs are generated using Protocol Buffers as the source of truth, and code generation (https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen) to generate the Markdown for these APIs. | ||
|
|
||
| With the migration to Kubebuilder, protos are no longer the source of truth, and we must rely on other means to | ||
| generate documentation. As https://github.com/kubernetes-sigs/controller-tools/issues/240 calls out, there isn't an agreed | ||
| upon approach yet. We chose to use https://github.com/fybrik/crdoc as it allows us to generate the Markdown for our docs, | ||
| which is used by Hugo. Other tools produced HTML, which wouldn't have worked for our current setup. | ||
|
|
||
| ### Which CRDs are documented using this mechanism? | ||
| We opted to only add this to our newer APIs, which do not rely on protos as the source of truth. This means the following CRDs are affected: | ||
| - GatewayParameters | ||
| - DirectReponseAction | ||
|
|
||
| ### How are the reference docs for our proto-based APIs generated? | ||
| We rely on our [solo-kit docgen](https://github.com/solo-io/solo-kit/tree/main/pkg/code-generator/docgen) code. | ||
|
|
||
| ### How do I regenerate the documentation locally? | ||
| 1. Install crdoc locally | ||
| ```bash | ||
| make install-go-gools | ||
| ``` | ||
|
|
||
| 2. Run the generation script. | ||
|
|
||
| This can be done by either using the go script directly: | ||
| ```bash | ||
| go run docs/content/crds/generate.go | ||
| ``` | ||
| or relying on the Make target: | ||
| ```bash | ||
| make generate-crd-reference-docs | ||
| ``` | ||
|
|
||
| ### When is this regenerated in CI? | ||
| When running `make generated-code`. |
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,107 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
| "os" | ||
| "path/filepath" | ||
| "strings" | ||
|
|
||
| "github.com/hashicorp/go-multierror" | ||
| "github.com/rotisserie/eris" | ||
| "github.com/solo-io/gloo/pkg/utils/cmdutils" | ||
| "github.com/solo-io/gloo/projects/gateway2/api/v1alpha1" | ||
| "github.com/solo-io/skv2/codegen/util" | ||
| "github.com/stoewer/go-strcase" | ||
| "k8s.io/apimachinery/pkg/runtime/schema" | ||
| ) | ||
|
|
||
| var ( | ||
| // crdocBinary is assumed to be installed locally to this path | ||
| // see the `install-go-tools` target in the Makefile | ||
| crdocBinary = filepath.Join(util.GetModuleRoot(), "_output", ".bin", "crdoc") | ||
| ) | ||
|
|
||
| func main() { | ||
| err := generateCrdReferenceDocs(context.Background()) | ||
| if err != nil { | ||
| fmt.Println(err) | ||
| os.Exit(1) | ||
| } | ||
| } | ||
|
|
||
| // generateCrdReferenceDocs is the entrypoint to our automation for updating CRD reference markdown files | ||
| func generateCrdReferenceDocs(ctx context.Context) error { | ||
| gvks := []schema.GroupVersionKind{ | ||
| v1alpha1.GatewayParametersGVK, | ||
| v1alpha1.DirectResponseGVK, | ||
| } | ||
|
|
||
| outErr := &multierror.Error{} | ||
| for _, gvk := range gvks { | ||
| err := generateCrdReferenceMarkdown(ctx, gvk) | ||
| outErr = multierror.Append(outErr, err) | ||
| } | ||
|
|
||
| return outErr.ErrorOrNil() | ||
| } | ||
|
|
||
| func generateCrdReferenceMarkdown(ctx context.Context, gvk schema.GroupVersionKind) error { | ||
| // sourceFile is the path to the CRD. This is used as the source of truth for the CRD reference docs | ||
| sourceFile := filepath.Join( | ||
| "install", | ||
| "helm", | ||
| "gloo", | ||
| "crds", | ||
| fmt.Sprintf("%s_%s.yaml", gvk.Group, strings.ToLower(kindPlural(gvk))), | ||
| ) | ||
|
|
||
| // outputFile is the path to the generated reference markdown file. | ||
| // NOTE: For now, this is tightly coupled to the `gateway2` project, since that is where the APIs that we | ||
| // rely on are defined, though that may need to change in the future | ||
| outputFile := filepath.Join( | ||
| "docs", | ||
| "content", | ||
| "reference", | ||
| "api", | ||
| "github.com", | ||
| "solo-io", | ||
| "gloo", | ||
| "projects", | ||
| "gateway2", | ||
| "api", | ||
| gvk.Version, | ||
| fmt.Sprintf("%s.md", strcase.SnakeCase(kindPlural(gvk)))) | ||
|
|
||
| // templateFile is the path to the file used as the template for our docs | ||
| templateFile := filepath.Join( | ||
| "docs", | ||
| "content", | ||
| "crds", | ||
| "templates", | ||
| "markdown.tmpl") | ||
|
|
||
| cmd := cmdutils.Command(ctx, crdocBinary, | ||
| "--resources", | ||
| sourceFile, | ||
| "--output", | ||
| outputFile, | ||
| "--template", | ||
| templateFile, | ||
| ) | ||
| runErr := cmd.Run() | ||
|
|
||
| if runErr.Cause() != nil { | ||
| return eris.Wrapf(runErr.Cause(), "%s produced error %s", runErr.PrettyCommand(), runErr.Error()) | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
| // kindPlural returns the pluralized kind for a given GVK. | ||
| // This is hacky, but is useful because CRD files are named using this format, so we need a way to look up that file name | ||
| // If the name of the file is incorrect, a developer will realize this because the script will fail with a file not found error. | ||
| func kindPlural(gvk schema.GroupVersionKind) string { | ||
| // ensure that kind which ends in s, is not duplicated | ||
| // ie GatewayParameters becomes GatewayParameters, not GatewayParameterss | ||
| return strings.TrimSuffix(gvk.Kind, "s") + "s" | ||
| } |
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,102 @@ | ||
| # API Reference | ||
|
|
||
| Packages: | ||
| {{range .Groups}} | ||
| - [{{.Group}}/{{.Version}}](#{{ anchorize (printf "%s/%s" .Group .Version) }}) | ||
| {{- end -}}{{/* range .Groups */}} | ||
|
|
||
| {{- range .Groups }} | ||
| {{- $group := . }} | ||
|
|
||
| # {{.Group}}/{{.Version}} | ||
|
|
||
| Resource Types: | ||
| {{range .Kinds}} | ||
| - [{{.Name}}](#{{ anchorize .Name }}) | ||
| {{end}}{{/* range .Kinds */}} | ||
|
|
||
| {{range .Kinds}} | ||
| {{$kind := .}} | ||
| ## {{.Name}} | ||
| <sup><sup>[↩ Parent](#{{ anchorize (printf "%s/%s" $group.Group $group.Version) }} )</sup></sup> | ||
|
|
||
| {{range .Types}} | ||
|
|
||
| {{if not .IsTopLevel}} | ||
| ### {{.Name}} | ||
| {{if .ParentKey}}<sup><sup>[↩ Parent](#{{.ParentKey}})</sup></sup>{{end}} | ||
| {{end}} | ||
|
|
||
|
|
||
| {{.Description}} | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| <th>Required</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| {{- if .IsTopLevel -}} | ||
| <tr> | ||
| <td><b>apiVersion</b></td> | ||
| <td>string</td> | ||
| <td>{{$group.Group}}/{{$group.Version}}</td> | ||
| <td>true</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>kind</b></td> | ||
| <td>string</td> | ||
| <td>{{$kind.Name}}</td> | ||
| <td>true</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b><a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta">metadata</a></b></td> | ||
| <td>object</td> | ||
| <td>Refer to the Kubernetes API documentation for the fields of the `metadata` field.</td> | ||
| <td>true</td> | ||
| </tr> | ||
| {{- end -}} | ||
| {{- range .Fields -}} | ||
| <tr> | ||
| <td><b>{{if .TypeKey}}<a href="#{{.TypeKey}}">{{.Name}}</a>{{else}}{{.Name}}{{end}}</b></td> | ||
| <td>{{.Type}}</td> | ||
| <td> | ||
| {{.Description}}<br/> | ||
| {{- if or .Schema.XValidations .Schema.Format .Schema.Enum .Schema.Default .Schema.Minimum .Schema.Maximum }} | ||
| <br/> | ||
| {{- end}} | ||
| {{- if .Schema.XValidations }} | ||
| <i>Validations</i>: | ||
| {{- range .Schema.XValidations -}} | ||
| <li>{{ .Rule }}: {{ .Message }}</li> | ||
| {{- end -}} | ||
| {{- end }} | ||
| {{- if .Schema.Format }} | ||
| <i>Format</i>: {{ .Schema.Format }}<br/> | ||
| {{- end }} | ||
| {{- if .Schema.Enum }} | ||
| <i>Enum</i>: {{ .Schema.Enum | toStrings | join ", " }}<br/> | ||
| {{- end }} | ||
| {{- if .Schema.Default }} | ||
| <i>Default</i>: {{ .Schema.Default }}<br/> | ||
| {{- end }} | ||
| {{- if .Schema.Minimum }} | ||
| <i>Minimum</i>: {{ .Schema.Minimum }}<br/> | ||
| {{- end }} | ||
| {{- if .Schema.Maximum }} | ||
| <i>Maximum</i>: {{ .Schema.Maximum }}<br/> | ||
| {{- end }} | ||
| </td> | ||
| <td>{{.Required}}</td> | ||
| </tr> | ||
| {{- end -}} | ||
| </tbody> | ||
| </table> | ||
|
|
||
| {{- end}}{{/* range .Types */}} | ||
| {{- end}}{{/* range .Kinds */}} | ||
| {{- end}}{{/* range .Groups */}} |
4 changes: 2 additions & 2 deletions
4
docs/content/reference/api/envoy/annotations/deprecation.proto.sk.md
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
6 changes: 3 additions & 3 deletions
6
docs/content/reference/api/envoy/api/v2/route/route.proto.sk.md
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Oops, something went wrong.