From 915284e77dfc19b051dff4972676e66b776ad0ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Wed, 6 Nov 2024 22:51:59 +0100 Subject: [PATCH] chore: add reference docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché --- ...nvoy.kyverno.io_authorizationpolicies.yaml | 4 ++ Makefile | 26 +++++++-- apis/v1alpha1/types.go | 7 +++ website/apis/config.yaml | 46 ++++++++++++++++ website/apis/markdown/members.tpl | 40 ++++++++++++++ website/apis/markdown/pkg.tpl | 53 ++++++++++++++++++ website/apis/markdown/type.tpl | 33 ++++++++++++ .../docs/reference/apis/policy.v1alpha1.md | 54 +++++++++++++++++++ website/docs/reference/index.md | 4 ++ website/docs/reference/json-schemas.md | 41 ++++++++++++++ website/mkdocs.yaml | 5 ++ 11 files changed, 308 insertions(+), 5 deletions(-) create mode 100644 website/apis/config.yaml create mode 100644 website/apis/markdown/members.tpl create mode 100644 website/apis/markdown/pkg.tpl create mode 100644 website/apis/markdown/type.tpl create mode 100644 website/docs/reference/apis/policy.v1alpha1.md create mode 100644 website/docs/reference/index.md create mode 100644 website/docs/reference/json-schemas.md diff --git a/.crds/envoy.kyverno.io_authorizationpolicies.yaml b/.crds/envoy.kyverno.io_authorizationpolicies.yaml index d1a0c9e..ffc35c6 100644 --- a/.crds/envoy.kyverno.io_authorizationpolicies.yaml +++ b/.crds/envoy.kyverno.io_authorizationpolicies.yaml @@ -17,6 +17,7 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: + description: AuthorizationPolicy defines an authorization policy resource properties: apiVersion: description: |- @@ -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: |- diff --git a/Makefile b/Makefile index 60d570c..b2d0ace 100644 --- a/Makefile +++ b/Makefile @@ -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 @@ -65,6 +67,10 @@ $(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) @@ -72,6 +78,7 @@ 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 @@ -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 @@ -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 diff --git a/apis/v1alpha1/types.go b/apis/v1alpha1/types.go index 9cf4f45..0986317 100644 --- a/apis/v1alpha1/types.go +++ b/apis/v1alpha1/types.go @@ -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 @@ -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 @@ -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"` diff --git a/website/apis/config.yaml b/website/apis/config.yaml new file mode 100644 index 0000000..6461d9c --- /dev/null +++ b/website/apis/config.yaml @@ -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 diff --git a/website/apis/markdown/members.tpl b/website/apis/markdown/members.tpl new file mode 100644 index 0000000..6f59cb5 --- /dev/null +++ b/website/apis/markdown/members.tpl @@ -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 -}} +

{{ $comment }}

+ {{- 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 }} diff --git a/website/apis/markdown/pkg.tpl b/website/apis/markdown/pkg.tpl new file mode 100644 index 0000000..52c1471 --- /dev/null +++ b/website/apis/markdown/pkg.tpl @@ -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 }} diff --git a/website/apis/markdown/type.tpl b/website/apis/markdown/type.tpl new file mode 100644 index 0000000..c871b9b --- /dev/null +++ b/website/apis/markdown/type.tpl @@ -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 }} diff --git a/website/docs/reference/apis/policy.v1alpha1.md b/website/docs/reference/apis/policy.v1alpha1.md new file mode 100644 index 0000000..5a7d16d --- /dev/null +++ b/website/docs/reference/apis/policy.v1alpha1.md @@ -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} + +

AuthorizationPolicy defines an authorization policy resource

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

Authorization defines an authorization policy rule

+ + +| Field | Type | Required | Inline | Description | +|---|---|---|---|---| +| `expression` | `string` | :white_check_mark: | |

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).

| + +## AuthorizationPolicySpec {#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec} + +**Appears in:** + +- [AuthorizationPolicy](#envoy-kyverno-io-v1alpha1-AuthorizationPolicy) + +

AuthorizationPolicySpec defines the spec of an authorization policy

+ + +| Field | Type | Required | Inline | Description | +|---|---|---|---|---| +| `failurePolicy` | [`admissionregistration/v1.FailurePolicyType`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#failurepolicytype-v1-admissionregistration) | | |

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.

| +| `variables` | [`[]admissionregistration/v1.Variable`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#variable-v1-admissionregistration) | | |

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.

| +| `authorizations` | [`[]Authorization`](#envoy-kyverno-io-v1alpha1-Authorization) | | |

Authorizations contain CEL expressions which is used to apply the authorization.

| + + \ No newline at end of file diff --git a/website/docs/reference/index.md b/website/docs/reference/index.md new file mode 100644 index 0000000..ace0f0b --- /dev/null +++ b/website/docs/reference/index.md @@ -0,0 +1,4 @@ +# Reference documentation + +!!! info + Select an item in the navigation menu to browse a specific page. diff --git a/website/docs/reference/json-schemas.md b/website/docs/reference/json-schemas.md new file mode 100644 index 0000000..a23f097 --- /dev/null +++ b/website/docs/reference/json-schemas.md @@ -0,0 +1,41 @@ +# JSON schemas + +JSON schemas for the Kyverno Envoy Plugin are available: + +- [AuthorizationPolicy (v1alpha1)](https://github.com/kyverno/kyverno-envoy-plugin/blob/main/.schemas/json/configuration-chainsaw-v1alpha1.json) + +They can be used to enable validation and autocompletion in your IDE. + +## VS code + +In VS code, simply add a comment on top of your YAML resources. + +### AuthorizationPolicy + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/kyverno-envoy-plugin/main/.schemas/json/test-chainsaw-v1alpha1.json +apiVersion: envoy.kyverno.io/v1alpha1 +kind: AuthorizationPolicy +metadata: + name: demo-policy.example.com +spec: + variables: + - name: force_authorized + expression: object.attributes.request.http.headers[?"x-force-authorized"].orValue("") in ["enabled", "true"] + - name: force_unauthenticated + expression: object.attributes.request.http.headers[?"x-force-unauthenticated"].orValue("") in ["enabled", "true"] + authorizations: + - expression: > + variables.force_authorized && !variables.force_unauthenticated + ? envoy + .Allowed() + .WithHeader("x-validated-by", "my-security-checkpoint") + .WithoutHeader("x-force-authorized") + .WithResponseHeader("x-add-custom-response-header", "added") + .Response() + .WithMetadata({"my-new-metadata": "my-new-value"}) + : envoy + .Denied(variables.force_unauthenticated ? 401 : 403) + .WithBody(variables.force_unauthenticated ? "Authentication Failed" : "Unauthorized Request") + .Response() +``` diff --git a/website/mkdocs.yaml b/website/mkdocs.yaml index c9728cb..3b087ef 100644 --- a/website/mkdocs.yaml +++ b/website/mkdocs.yaml @@ -16,6 +16,11 @@ nav: - tutorials/standalone-envoy.md - tutorials/istio.md - tutorials/mtls-istio.md +- Reference: + - reference/index.md + - reference/json-schemas.md + - APIs: + - v1alpha1: reference/apis/policy.v1alpha1.md - Performance: performance.md - Community: - community/index.md