Skip to content

Commit

Permalink
chore: add reference docs
Browse files Browse the repository at this point in the history
Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>
  • Loading branch information
eddycharly committed Nov 6, 2024
1 parent bf1322d commit 4e06f72
Show file tree
Hide file tree
Showing 11 changed files with 308 additions and 5 deletions.
4 changes: 4 additions & 0 deletions .crds/envoy.kyverno.io_authorizationpolicies.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ spec:
- name: v1alpha1
schema:
openAPIV3Schema:
description: AuthorizationPolicy defines an authorization policy resource
properties:
apiVersion:
description: |-
Expand All @@ -36,11 +37,14 @@ spec:
metadata:
type: object
spec:
description: AuthorizationPolicySpec defines the spec of an authorization
policy
properties:
authorizations:
description: Authorizations contain CEL expressions which is used
to apply the authorization.
items:
description: Authorization defines an authorization policy rule
properties:
expression:
description: |-
Expand Down
26 changes: 21 additions & 5 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ CONTROLLER_GEN ?= $(TOOLS_DIR)/controller-gen
CONTROLLER_GEN_VERSION := latest
REGISTER_GEN ?= $(TOOLS_DIR)/register-gen
REGISTER_GEN_VERSION := v0.28.0
REFERENCE_DOCS := $(TOOLS_DIR)/genref
REFERENCE_DOCS_VERSION := latest
PIP ?= "pip"
ifeq ($(GOOS), darwin)
SED := gsed
Expand All @@ -65,13 +67,18 @@ $(CONTROLLER_GEN):
$(REGISTER_GEN):
@GOBIN=$(TOOLS_DIR) go install k8s.io/code-generator/cmd/register-gen@$(REGISTER_GEN_VERSION)

$(REFERENCE_DOCS):
@echo Install genref... >&2
@GOBIN=$(TOOLS_DIR) go install github.com/kubernetes-sigs/reference-docs/genref@$(REFERENCE_DOCS_VERSION)

.PHONY: install-tools
install-tools: ## Install tools
install-tools: $(HELM)
install-tools: $(KIND)
install-tools: $(KO)
install-tools: $(CONTROLLER_GEN)
install-tools: $(REGISTER_GEN)
install-tools: $(REFERENCE_DOCS)

.PHONY: clean-tools
clean-tools: ## Remove installed tools
Expand Down Expand Up @@ -100,17 +107,17 @@ codegen-crds: $(REGISTER_GEN)
@$(CONTROLLER_GEN) paths=./apis/v1alpha1/... crd:crdVersions=v1,ignoreUnexportedFields=true,generateEmbeddedObjectMeta=false output:dir=$(CRDS_PATH)
@$(REGISTER_GEN) --input-dirs=./apis/v1alpha1 --go-header-file=./.hack/boilerplate.go.txt --output-base=.

.PHONY: codegen-helm-docs
codegen-helm-docs: ## Generate helm docs
@echo Generate helm docs... >&2
@docker run -v ${PWD}/charts:/work -w /work jnorwood/helm-docs:v1.11.0 -s file

.PHONY: codegen-mkdocs
codegen-mkdocs: ## Generate mkdocs website
@echo Generate mkdocs website... >&2
@$(PIP) install -r requirements.txt
@mkdocs build -f ./website/mkdocs.yaml

.PHONY: codegen-helm-docs
codegen-helm-docs: ## Generate helm docs
@echo Generate helm docs... >&2
@docker run -v ${PWD}/charts:/work -w /work jnorwood/helm-docs:v1.11.0 -s file

.PHONY: codegen-helm-crds
codegen-helm-crds: codegen-crds ## Generate helm CRDs
@echo Generate helm crds... >&2
Expand All @@ -127,12 +134,21 @@ codegen-helm-crds: codegen-crds ## Generate helm CRDs
| $(SED) -e '/^ labels:/a \ \ \ \ {{- include "kyverno-authz-server.labels" . | nindent 4 }}' \
> ./charts/kyverno-authz-server/templates/crds.yaml

.PHONY: codegen-api-docs
codegen-api-docs: ## Generate markdown API docs
codegen-api-docs: $(REFERENCE_DOCS)
codegen-api-docs: codegen-crds
@echo Generate api docs... >&2
@rm -rf ./website/docs/reference/apis
@cd ./website/apis && $(REFERENCE_DOCS) -c config.yaml -f markdown -o ../docs/reference/apis

.PHONY: codegen
codegen: ## Rebuild all generated code and docs
codegen: codegen-mkdocs
codegen: codegen-crds
codegen: codegen-helm-crds
codegen: codegen-helm-docs
codegen: codegen-api-docs

.PHONY: verify-codegen
verify-codegen: ## Verify all generated code and docs are up to date
Expand Down
7 changes: 7 additions & 0 deletions apis/v1alpha1/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,20 @@ import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// +genclient
// +genclient:nonNamespaced
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
// +kubebuilder:object:root=true
// +kubebuilder:resource:scope=Cluster

// AuthorizationPolicy defines an authorization policy resource
type AuthorizationPolicy struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec AuthorizationPolicySpec `json:"spec"`
}

// AuthorizationPolicySpec defines the spec of an authorization policy
type AuthorizationPolicySpec struct {
// FailurePolicy defines how to handle failures for the policy. Failures can
// occur from CEL expression parse errors, type check errors, runtime errors and invalid
Expand Down Expand Up @@ -52,6 +57,7 @@ func (s *AuthorizationPolicySpec) GetFailurePolicy() admissionregistrationv1.Fai
return *s.FailurePolicy
}

// Authorization defines an authorization policy rule
type Authorization struct {
// Expression represents the expression which will be evaluated by CEL.
// ref: https://github.com/google/cel-spec
Expand All @@ -66,6 +72,7 @@ type Authorization struct {

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// AuthorizationPolicyList defines a list of authorization policies
type AuthorizationPolicyList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata"`
Expand Down
46 changes: 46 additions & 0 deletions website/apis/config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
hiddenMemberFields:
- TypeMeta

hideTypePatterns:
- ParseError$
- List$

externalPackages:
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.Duration$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionKind$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionKind
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionResource$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionResource
- match: ^k8s\.io/apimachinery/pkg/types\.UID$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID
- match: ^k8s\.io/apimachinery/pkg/runtime\.RawExtension$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension
- match: ^k8s\.io/apimachinery/pkg/api/resource\.QuantityValue$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue
- match: ^k8s\.io/apimachinery/pkg/api/resource\.Quantity$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity
- match: ^k8s\.io/apimachinery/pkg/runtime\.Unknown$
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown
- match: ^time\.Duration$
target: https://pkg.go.dev/time#Duration
- match: ^io.Writer$
target: https://pkg.go.dev/io#Writer
- match: ^k8s\.io/(api|apimachinery/pkg/apis)/
target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}}

markdownDisabled: false

stripPrefix:
- k8s.io/api/
- k8s.io/apimachinery/pkg/apis/
- github.com/kyverno/kyverno-json/pkg/apis/
- github.com/tengqm/kubeconfig/config/kubeadm/v1beta2.
- github.com/tengqm/kubeconfig/config/kubeadm/v1beta3.
- github.com/tengqm/kubeconfig/config/bootstraptoken/v1.

apis:
- name: policy
title: policy (v1alpha1)
package: github.com/kyverno/kyverno-envoy-plugin
path: apis/v1alpha1
40 changes: 40 additions & 0 deletions website/apis/markdown/members.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{{- define "comment" -}}
{{- $comment := "" -}}
{{- range . -}}
{{- if . -}}
{{- if not (eq (index . 0) '+') -}}
{{- if $comment -}}
{{- $comment = print $comment " " . -}}
{{- else -}}
{{- $comment = . -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- if $comment -}}
<p>{{ $comment }}</p>
{{- else -}}
*No description provided.*
{{- end -}}
{{- end -}}

{{- define "typ" -}}
{{- if .Link -}}
[`{{ .DisplayName }}`]({{ .Link }})
{{- else -}}
`{{ .DisplayName }}`
{{- end -}}
{{- end -}}

{{- define "members" }}
{{- range .GetMembers }}
{{- if not .Hidden }}
{{- $name := .FieldName }}
{{- $optional := .IsOptional }}
{{- $type := .GetType }}
{{- $inline := .IsInline }}
{{- $comment := .GetComment }}
| `{{ $name }}` | {{ template "typ" $type }} | {{ if not $optional }}:white_check_mark:{{ end }} | {{ if $inline }}:white_check_mark:{{ end }} | {{ template "comment" .CommentLines }} |
{{- end }}
{{- end }}
{{- end }}
53 changes: 53 additions & 0 deletions website/apis/markdown/pkg.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
{{ define "packages" -}}

{{- range $idx, $val := .packages -}}
{{/* Special handling for kubeconfig */}}
{{- if eq .Title "kubeconfig (v1)" -}}
---
title: {{ .Title }}
content_type: tool-reference
package: v1
auto_generated: true
---
{{- else -}}
{{- if and .IsMain (ne .GroupName "") -}}
---
title: {{ .Title }}
content_type: tool-reference
package: {{ .DisplayName }}
auto_generated: true
---
{{ .GetComment -}}
{{- end -}}
{{- end -}}
{{- end }}

## Resource Types

{{ range .packages -}}
{{- range .VisibleTypes -}}
{{- if .IsExported }}
- [{{ .DisplayName }}]({{ .Link }})
{{- end -}}
{{- end -}}
{{- end -}}

{{ range .packages }}
{{ if ne .GroupName "" -}}
{{/* For package with a group name, list all type definitions in it. */}}
{{- range .VisibleTypes }}
{{- if or .Referenced .IsExported -}}
{{ template "type" . }}
{{- end -}}
{{ end }}
{{ else }}
{{/* For package w/o group name, list only types referenced. */}}
{{ $pkgTitle := .Title }}
{{- range .VisibleTypes -}}
{{- if or .Referenced (eq $pkgTitle "kubeconfig (v1)") -}}
{{ template "type" . }}
{{- end -}}
{{- end }}
{{- end }}
{{- end }}
{{- end }}
33 changes: 33 additions & 0 deletions website/apis/markdown/type.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
{{- define "type" }}
## {{ .Name.Name }} {#{{ .Anchor }}}
{{- if eq .Kind "Alias" }}

(Alias of `{{ .Underlying }}`)
{{- end }}
{{- with .References }}

**Appears in:**
{{ range . }}
{{- if or .Referenced .IsExported }}
- [{{ .DisplayName }}]({{ .Link }})
{{- end }}
{{- end }}
{{- end }}
{{- if .GetComment }}

{{ .GetComment }}
{{- end }}
{{- if .GetMembers }}

| Field | Type | Required | Inline | Description |
|---|---|---|---|---|
{{- /* . is a apiType */}}
{{- if .IsExported }}
{{- /* Add apiVersion and kind rows if deemed necessary */}}
| `apiVersion` | `string` | :white_check_mark: | | `{{- .APIGroup -}}` |
| `kind` | `string` | :white_check_mark: | | `{{- .Name.Name -}}` |
{{- end }}
{{- /* The actual list of members is in the following template */}}
{{- template "members" . }}
{{- end }}
{{ end }}
54 changes: 54 additions & 0 deletions website/docs/reference/apis/policy.v1alpha1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: policy (v1alpha1)
content_type: tool-reference
package: envoy.kyverno.io/v1alpha1
auto_generated: true
---


## Resource Types


- [AuthorizationPolicy](#envoy-kyverno-io-v1alpha1-AuthorizationPolicy)

## AuthorizationPolicy {#envoy-kyverno-io-v1alpha1-AuthorizationPolicy}

<p>AuthorizationPolicy defines an authorization policy resource</p>


| Field | Type | Required | Inline | Description |
|---|---|---|---|---|
| `apiVersion` | `string` | :white_check_mark: | | `envoy.kyverno.io/v1alpha1` |
| `kind` | `string` | :white_check_mark: | | `AuthorizationPolicy` |
| `metadata` | [`meta/v1.ObjectMeta`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta) | :white_check_mark: | | *No description provided.* |
| `spec` | [`AuthorizationPolicySpec`](#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec) | :white_check_mark: | | *No description provided.* |

## Authorization {#envoy-kyverno-io-v1alpha1-Authorization}

**Appears in:**

- [AuthorizationPolicySpec](#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec)

<p>Authorization defines an authorization policy rule</p>


| Field | Type | Required | Inline | Description |
|---|---|---|---|---|
| `expression` | `string` | :white_check_mark: | | <p>Expression represents the expression which will be evaluated by CEL. ref: https://github.com/google/cel-spec CEL expressions have access to CEL variables as well as some other useful variables: - 'object' - The object from the incoming request. (https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkrequest) CEL expressions are expected to return an envoy CheckResponse (https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkresponse).</p> |

## AuthorizationPolicySpec {#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec}

**Appears in:**

- [AuthorizationPolicy](#envoy-kyverno-io-v1alpha1-AuthorizationPolicy)

<p>AuthorizationPolicySpec defines the spec of an authorization policy</p>


| Field | Type | Required | Inline | Description |
|---|---|---|---|---|
| `failurePolicy` | [`admissionregistration/v1.FailurePolicyType`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#failurepolicytype-v1-admissionregistration) | | | <p>FailurePolicy defines how to handle failures for the policy. Failures can occur from CEL expression parse errors, type check errors, runtime errors and invalid or mis-configured policy definitions. FailurePolicy does not define how validations that evaluate to false are handled. Allowed values are Ignore or Fail. Defaults to Fail.</p> |
| `variables` | [`[]admissionregistration/v1.Variable`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#variable-v1-admissionregistration) | | | <p>Variables contain definitions of variables that can be used in composition of other expressions. Each variable is defined as a named CEL expression. The variables defined here will be available under `variables` in other expressions of the policy except MatchConditions because MatchConditions are evaluated before the rest of the policy. The expression of a variable can refer to other variables defined earlier in the list but not those after. Thus, Variables must be sorted by the order of first appearance and acyclic.</p> |
| `authorizations` | [`[]Authorization`](#envoy-kyverno-io-v1alpha1-Authorization) | | | <p>Authorizations contain CEL expressions which is used to apply the authorization.</p> |


4 changes: 4 additions & 0 deletions website/docs/reference/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Reference documentation

!!! info
Select an item in the navigation menu to browse a specific page.
Loading

0 comments on commit 4e06f72

Please sign in to comment.