From ba1be6b1434b8967f67e53230b29b43a0ade6c3f Mon Sep 17 00:00:00 2001 From: Jim Bugwadia Date: Thu, 7 Jan 2021 18:57:33 -0800 Subject: [PATCH] restructure and generate HTML docs --- README.md | 2 +- docs/README.md | 27 + {documentation/api => docs}/config.json | 0 docs/crd/v1/index.html | 1873 +++++++++++++++++ .../api => docs}/template/members.tpl | 0 {documentation/api => docs}/template/pkg.tpl | 0 {documentation/api => docs}/template/type.tpl | 0 .../images => img}/Kyverno_Horizontal.png | Bin 8 files changed, 1901 insertions(+), 1 deletion(-) create mode 100644 docs/README.md rename {documentation/api => docs}/config.json (100%) create mode 100644 docs/crd/v1/index.html rename {documentation/api => docs}/template/members.tpl (100%) rename {documentation/api => docs}/template/pkg.tpl (100%) rename {documentation/api => docs}/template/type.tpl (100%) rename {documentation/images => img}/Kyverno_Horizontal.png (100%) diff --git a/README.md b/README.md index 5966019bd2..f8bf4fb9e8 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![GitHub Repo stars](https://img.shields.io/github/stars/kyverno/kyverno)](https://github.com/kyverno/kyverno/stargazers) -![logo](documentation/images/Kyverno_Horizontal.png) +![logo](img/Kyverno_Horizontal.png)

Kyverno is a policy engine designed for Kubernetes. It can validate, mutate, and generate configurations using admission controls and background scans. Kyverno policies are Kubernetes resources and do not require learning a new language. Kyverno is designed to work nicely with tools you already use like kubectl, kustomize, and Git. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..52e147822b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# docs + +This folder containers the generated CRD documentation in HTML format. It is referenced from the Kyverno website (https://kyverno.io/docs/crds/). + +## Building + +Follow these steps to generate the docs: + +1. Install [gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs) + +```shell +clone https://github.com/ahmetb/gen-crd-api-reference-docs +cd gen-crd-api-reference-docs +go build +mv gen-crd-api-reference-docs $GOPATH/bin +``` + +2. Generate the HTML + +```shell +gen-crd-api-reference-docs -api-dir ./pkg/api/kyverno/v1 \ + -config docs/config.json \ + -template-dir docs/template/ \ + -out-file docs/crd/v1/index.html +``` + +3. If needed, update the [docs site](https://kyverno.io/docs/crds/). \ No newline at end of file diff --git a/documentation/api/config.json b/docs/config.json similarity index 100% rename from documentation/api/config.json rename to docs/config.json diff --git a/docs/crd/v1/index.html b/docs/crd/v1/index.html new file mode 100644 index 0000000000..0ff69db9f3 --- /dev/null +++ b/docs/crd/v1/index.html @@ -0,0 +1,1873 @@ + + + + + + +Kyverno API + + + +

+ +

kyverno.io/v1

+Resource Types: + +
+

CloneFrom +

+

+(Appears on: +Generation) +

+

+

CloneFrom provides the location of the source resource used to generate target resources. +The resource kind is derived from the match criteria.

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+namespace
+ +string + +		 +(Optional) +

Namespace specifies source resource namespace.

+
+name
+ +string + +		 +

Name specifies name of the resource.

+
+
+

ClusterPolicy +

+

+

ClusterPolicy declares validation, mutation, and generation behaviors for matching resources.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +Spec + + +		 +

Spec declares policy behaviors.

+
+
+ + + + + + + + + + + + + +
+rules
+ + +[]Rule + + +		 +

Rules is a list of Rule instances. A Policy contains multiple rules and +each rule can validate, mutate, or generate resources.

+
+validationFailureAction
+ +string + +		 +(Optional) +

ValidationFailureAction controls if a validation policy rule failure should disallow +the admission review request (enforce), or allow (audit) the admission review request +and report an error in a policy report. Optional. The default value is “audit”.

+
+background
+ +bool + +		 +(Optional) +

Background controls if rules are applied to existing resources during a background scan. +Optional. Default value is “true”. The value must be set to “false” if the policy rule +uses variables that are only available in the admission review request (e.g. user name).

+
+
+status
+ + +PolicyStatus + + +		 +(Optional) +

Status contains policy runtime data.

+
+
+

Condition +

+

+(Appears on: +Deny, +Rule) +

+

+

Condition defines variable-based conditional criteria for rule execution.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+key
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +

Key is the context entry (using JMESPath) for conditional rule evaluation.

+
+operator
+ + +ConditionOperator + + +		 +

Operator is the operation to perform.

+
+value
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

Value is the conditional value, or set of values. The values can be fixed set +or can be variables declared using using JMESPath.

+
+
+

ConditionOperator +(string alias)

+

+(Appears on: +Condition) +

+

+

ConditionOperator is the operation performed on condition key and value.

+

+

ConfigMapReference +

+

+(Appears on: +ContextEntry) +

+

+

ConfigMapReference refers to a ConfigMap

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+namespace
+ +string + +		 +
+
+

ContextEntry +

+

+(Appears on: +Rule) +

+

+

ContextEntry adds variables and data sources to a rule Context

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+configMap
+ + +ConfigMapReference + + +		 +
+
+

Deny +

+

+(Appears on: +Validation) +

+

+

Deny specifies a list of conditions. The validation rule fails, if any Condition +evaluates to “false”.

+

+ + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +[]Condition + + +		 +

Specifies set of condition to deny.

+
+
+

ExcludeResources +

+

+(Appears on: +Rule) +

+

+

ExcludeResources specifies resource and admission review request data for +which a policy rule is not applicable.

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+UserInfo
+ + +UserInfo + + +		 +(Optional) +

UserInfo contains information about the user performing the operation.

+
+resources
+ + +ResourceDescription + + +		 +(Optional) +

ResourceDescription contains information about the resource being created or modified.

+
+
+

GenerateRequest +

+

+

GenerateRequest is a request to process generate rule.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +GenerateRequestSpec + + +		 +

Spec is the information to identify the generate request.

+
+
+ + + + + + + + + + + + + +
+policy
+ +string + +		 +

Specifies the name of the policy.

+
+resource
+ + +ResourceSpec + + +		 +

ResourceSpec is the information to identify the generate request.

+
+context
+ + +GenerateRequestContext + + +		 +

Context …

+
+
+status
+ + +GenerateRequestStatus + + +		 +(Optional) +

Status contains statistics related to generate request.

+
+
+

GenerateRequestContext +

+

+(Appears on: +GenerateRequestSpec) +

+

+

GenerateRequestContext stores the context to be shared.

+

+ + + + + + + + + + + + + +
FieldDescription
+userInfo
+ + +RequestInfo + + +		 +(Optional) +
+
+

GenerateRequestSpec +

+

+(Appears on: +GenerateRequest) +

+

+

GenerateRequestSpec stores the request specification.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+policy
+ +string + +		 +

Specifies the name of the policy.

+
+resource
+ + +ResourceSpec + + +		 +

ResourceSpec is the information to identify the generate request.

+
+context
+ + +GenerateRequestContext + + +		 +

Context …

+
+
+

GenerateRequestState +(string alias)

+

+(Appears on: +GenerateRequestStatus) +

+

+

GenerateRequestState defines the state of request.

+

+

GenerateRequestStatus +

+

+(Appears on: +GenerateRequest) +

+

+

GenerateRequestStatus stores the status of generated request.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+state
+ + +GenerateRequestState + + +		 +

State represents state of the generate request.

+
+message
+ +string + +		 +(Optional) +

Specifies request status message.

+
+generatedResources
+ + +[]ResourceSpec + + +		 +

This will track the resources that are generated by the generate Policy. +Will be used during clean up resources.

+
+
+

Generation +

+

+(Appears on: +Rule) +

+

+

Generation defines how new resources should be created and managed.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+ResourceSpec
+ + +ResourceSpec + + +		 +

ResourceSpec contains information to select the resource.

+
+synchronize
+ +bool + +		 +(Optional) +

Synchronize controls if generated resources should be kept in-sync with their source resource. +If Synchronize is set to “true” changes to generated resources will be overwritten with resource +data from Data or the resource specified in the Clone declaration. +Optional. Defaults to “false” if not specified.

+
+data
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

Data provides the resource declaration used to populate each generated resource. +At most one of Data or Clone must be specified. If neither are provided, the generated +resource will be created with default data only.

+
+clone
+ + +CloneFrom + + +		 +(Optional) +

Clone specifies the source resource used to populate each generated resource. +At most one of Data or Clone can be specified. If neither are provided, the generated +resource will be created with default data only.

+
+
+

MatchResources +

+

+(Appears on: +Rule) +

+

+

MatchResources is used to specify resource and admission review request data for +which a policy rule is applicable.

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+UserInfo
+ + +UserInfo + + +		 +(Optional) +

UserInfo contains information about the user performing the operation.

+
+resources
+ + +ResourceDescription + + +		 +

ResourceDescription contains information about the resource being created or modified.

+
+
+

Mutation +

+

+(Appears on: +Rule) +

+

+

Mutation defines how resource are modified.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+overlay
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

Overlay specifies an overlay pattern to modify resources. +DEPRECATED. Use PatchStrategicMerge instead. Scheduled for +removal in release 1.5+.

+
+patches
+ + +[]Patch + + +		 +(Optional) +

Patches specifies a RFC 6902 JSON Patch to modify resources. +DEPRECATED. Use PatchesJSON6902 instead. Scheduled for +removal in release 1.5+.

+
+patchStrategicMerge
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

PatchStrategicMerge is a strategic merge patch used to modify resources. +See https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/ +and https://kubectl.docs.kubernetes.io/references/kustomize/patchesstrategicmerge/.

+
+patchesJson6902
+ +string + +		 +(Optional) +

PatchesJSON6902 is a list of RFC 6902 JSON Patch declarations used to modify resources. +See https://tools.ietf.org/html/rfc6902 and https://kubectl.docs.kubernetes.io/references/kustomize/patchesjson6902/.

+
+
+

Patch +

+

+(Appears on: +Mutation) +

+

+

Patch is a RFC 6902 JSON Patch. +See: https://tools.ietf.org/html/rfc6902

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+path
+ +string + +		 +

Path specifies path of the resource.

+
+op
+ +string + +		 +

Operation specifies operations supported by JSON Patch. +i.e:- add, replace and delete.

+
+value
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

Value specifies the value to be applied.

+
+
+

Policy +

+

+

Policy declares validation, mutation, and generation behaviors for matching resources. +See: https://kyverno.io/docs/writing-policies/ for more information.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +Spec + + +		 +

Spec defines policy behaviors and contains one or rules.

+
+
+ + + + + + + + + + + + + +
+rules
+ + +[]Rule + + +		 +

Rules is a list of Rule instances. A Policy contains multiple rules and +each rule can validate, mutate, or generate resources.

+
+validationFailureAction
+ +string + +		 +(Optional) +

ValidationFailureAction controls if a validation policy rule failure should disallow +the admission review request (enforce), or allow (audit) the admission review request +and report an error in a policy report. Optional. The default value is “audit”.

+
+background
+ +bool + +		 +(Optional) +

Background controls if rules are applied to existing resources during a background scan. +Optional. Default value is “true”. The value must be set to “false” if the policy rule +uses variables that are only available in the admission review request (e.g. user name).

+
+
+status
+ + +PolicyStatus + + +		 +(Optional) +

Status contains policy runtime information.

+
+
+

PolicyStatus +

+

+(Appears on: +ClusterPolicy, +Policy) +

+

+

PolicyStatus mostly contains runtime information related to policy execution.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+averageExecutionTime
+ +string + +		 +(Optional) +

AvgExecutionTime is the average time taken to process the policy rules on a resource.

+
+violationCount
+ +int + +		 +(Optional) +

ViolationCount is the total count of policy failure results for this policy.

+
+rulesFailedCount
+ +int + +		 +(Optional) +

RulesFailedCount is the total count of policy execution errors for this policy.

+
+rulesAppliedCount
+ +int + +		 +(Optional) +

RulesAppliedCount is the total number of times this policy was applied.

+
+resourcesBlockedCount
+ +int + +		 +(Optional) +

ResourcesBlockedCount is the total count of admission review requests that were blocked by this policy.

+
+resourcesMutatedCount
+ +int + +		 +(Optional) +

ResourcesMutatedCount is the total count of resources that were mutated by this policy.

+
+resourcesGeneratedCount
+ +int + +		 +(Optional) +

ResourcesGeneratedCount is the total count of resources that were generated by this policy.

+
+ruleStatus
+ + +[]RuleStats + + +		 +(Optional) +

Rules provides per rule statistics

+
+
+

RequestInfo +

+

+(Appears on: +GenerateRequestContext) +

+

+

RequestInfo contains permission info carried in an admission request.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+roles
+ +[]string + +		 +(Optional) +

Roles is a list of possible role send the request.

+
+clusterRoles
+ +[]string + +		 +(Optional) +

ClusterRoles is a list of possible clusterRoles send the request.

+
+userInfo
+ + +Kubernetes authentication/v1.UserInfo + + +		 +(Optional) +

UserInfo is the userInfo carried in the admission request.

+
+
+

ResourceDescription +

+

+(Appears on: +ExcludeResources, +MatchResources) +

+

+

ResourceDescription contains criteria used to match resources.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+kinds
+ +[]string + +		 +(Optional) +

Kinds is a list of resource kinds.

+
+name
+ +string + +		 +(Optional) +

Name is the name of the resource. The name supports wildcard characters +“*” (matches zero or many characters) and “?” (at least one character).

+
+namespaces
+ +[]string + +		 +(Optional) +

Namespaces is a list of namespaces names. Each name supports wildcard characters +“*” (matches zero or many characters) and “?” (at least one character).

+
+annotations
+ +map[string]string + +		 +(Optional) +

Annotations is a map of annotations (key-value pairs of type string). Annotation keys +and values support the wildcard characters “*” (matches zero or many characters) and +“?” (matches at least one character).

+
+selector
+ + +Kubernetes meta/v1.LabelSelector + + +		 +(Optional) +

Selector is a label selector. Label keys and values in matchLabels support the wildcard +characters * (matches zero or many characters) and ? (matches one character). +Wildcards allows writing label selectors like [“storage.k8s.io/”: “”]. Note that +using [”” : “”] matches any key and value but does not match an empty label set.

+
+
+

ResourceSpec +

+

+(Appears on: +GenerateRequestSpec, +GenerateRequestStatus, +Generation) +

+

+

ResourceSpec contains information to identify a resource.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+ +string + +		 +(Optional) +

APIVersion specifies resource apiVersion.

+
+kind
+ +string + +		 +

Kind specifies resource kind.

+
+namespace
+ +string + +		 +(Optional) +

Namespace specifies resource namespace.

+
+name
+ +string + +		 +

Name specifies the resource name.

+
+
+

Rule +

+

+(Appears on: +Spec) +

+

+

Rule defines a validation, mutation, or generation control for matching resources. +Each rules contains a match declaration to select resources, and an optional exclude +declaration to specify which resources to exclude.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Name is a label to identify the rule, It must be unique within the policy.

+
+context
+ + +[]ContextEntry + + +		 +(Optional) +

Context defines variables and data sources that can be used during rule execution.

+
+match
+ + +MatchResources + + +		 +

MatchResources defines when this policy rule should be applied. The match +criteria can include resource information (e.g. kind, name, namespace, labels) +and admission review request information like the user name or role. +At least one kind is required.

+
+exclude
+ + +ExcludeResources + + +		 +(Optional) +

ExcludeResources defines when this policy rule should not be applied. The exclude +criteria can include resource information (e.g. kind, name, namespace, labels) +and admission review request information like the name or role.

+
+preconditions
+ + +[]Condition + + +		 +(Optional) +

Conditions enable variable-based conditional rule execution. This is useful for +finer control of when an rule is applied. A condition can reference object data +using JMESPath notation.

+
+mutate
+ + +Mutation + + +		 +(Optional) +

Mutation is used to modify matching resources.

+
+validate
+ + +Validation + + +		 +(Optional) +

Validation is used to validate matching resources.

+
+generate
+ + +Generation + + +		 +(Optional) +

Generation is used to create new resources.

+
+
+

RuleStats +

+

+(Appears on: +PolicyStatus) +

+

+

RuleStats provides statistics for an individual rule within a policy.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+ruleName
+ +string + +		 +

Name is the rule name.

+
+averageExecutionTime
+ +string + +		 +(Optional) +

ExecutionTime is the average time taken to execute this rule.

+
+violationCount
+ +int + +		 +(Optional) +

ViolationCount is the total count of policy failure results for this rule.

+
+failedCount
+ +int + +		 +(Optional) +

FailedCount is the total count of policy error results for this rule.

+
+appliedCount
+ +int + +		 +(Optional) +

AppliedCount is the total number of times this rule was applied.

+
+resourcesBlockedCount
+ +int + +		 +(Optional) +

ResourcesBlockedCount is the total count of admission review requests that were blocked by this rule.

+
+resourcesMutatedCount
+ +int + +		 +(Optional) +

ResourcesMutatedCount is the total count of resources that were mutated by this rule.

+
+resourcesGeneratedCount
+ +int + +		 +(Optional) +

ResourcesGeneratedCount is the total count of resources that were generated by this rule.

+
+
+

Spec +

+

+(Appears on: +ClusterPolicy, +Policy) +

+

+

Spec contains a list of Rule instances and other policy controls.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+rules
+ + +[]Rule + + +		 +

Rules is a list of Rule instances. A Policy contains multiple rules and +each rule can validate, mutate, or generate resources.

+
+validationFailureAction
+ +string + +		 +(Optional) +

ValidationFailureAction controls if a validation policy rule failure should disallow +the admission review request (enforce), or allow (audit) the admission review request +and report an error in a policy report. Optional. The default value is “audit”.

+
+background
+ +bool + +		 +(Optional) +

Background controls if rules are applied to existing resources during a background scan. +Optional. Default value is “true”. The value must be set to “false” if the policy rule +uses variables that are only available in the admission review request (e.g. user name).

+
+
+

UserInfo +

+

+(Appears on: +ExcludeResources, +MatchResources) +

+

+

UserInfo contains information about the user performing the operation.

+

+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+roles
+ +[]string + +		 +(Optional) +

Roles is the list of namespaced role names for the user.

+
+clusterRoles
+ +[]string + +		 +(Optional) +

ClusterRoles is the list of cluster-wide role names for the user.

+
+subjects
+ + +[]Kubernetes rbac/v1.Subject + + +		 +(Optional) +

Subjects is the list of subject names like users, user groups, and service accounts.

+
+
+

Validation +

+

+(Appears on: +Rule) +

+

+

Validation defines checks to be performed on matching resources.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+message
+ +string + +		 +(Optional) +

Message specifies a custom message to be displayed on failure.

+
+pattern
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

Pattern specifies an overlay-style pattern used to check resources.

+
+anyPattern
+ +k8s.io/apiextensions-apiserver/pkg/apis/apiextensions.JSON + +		 +(Optional) +

AnyPattern specifies list of validation patterns. At least one of the patterns +must be satisfied for the validation rule to succeed.

+
+deny
+ + +Deny + + +		 +(Optional) +

Deny defines conditions to fail the validation rule.

+
+
+

ViolatedRule +

+

+

ViolatedRule stores the information regarding the rule.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Specifies violated rule name.

+
+type
+ +string + +		 +

Specifies violated rule type.

+
+message
+ +string + +		 +(Optional) +

Specifies violation message.

+
+check
+ +string + +		 +(Optional) +
+
+
+ + + + + diff --git a/documentation/api/template/members.tpl b/docs/template/members.tpl similarity index 100% rename from documentation/api/template/members.tpl rename to docs/template/members.tpl diff --git a/documentation/api/template/pkg.tpl b/docs/template/pkg.tpl similarity index 100% rename from documentation/api/template/pkg.tpl rename to docs/template/pkg.tpl diff --git a/documentation/api/template/type.tpl b/docs/template/type.tpl similarity index 100% rename from documentation/api/template/type.tpl rename to docs/template/type.tpl diff --git a/documentation/images/Kyverno_Horizontal.png b/img/Kyverno_Horizontal.png similarity index 100% rename from documentation/images/Kyverno_Horizontal.png rename to img/Kyverno_Horizontal.png