Skip to content

Commit

Permalink
docs: final update
Browse files Browse the repository at this point in the history 
Signed-off-by: Charles-Edouard Brétéché <[email protected]>
  • Loading branch information
@eddycharly
eddycharly committed Nov 8, 2024
1 parent 4ed9714 commit 1ab7c10
Show file tree
Hide file tree
Showing 8 changed files with 111 additions and 197 deletions.
1 change: 0 additions & 1 deletion .manifests/policies/demo-policy.example.com.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,3 @@ spec:
.Denied(403)
.WithBody("Unauthorized Request")
.Response()
.WithMetadata(variables.metadata)
1 change: 0 additions & 1 deletion website/apis/config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ 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.
Expand Down
132 changes: 11 additions & 121 deletions website/docs/overrides/home.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,17 +207,17 @@ <h2>Policy based authorizations... in a mesh !</h2>
class="md-button md-button--primary">
Get started
</a>
<a href="#everything-you-would-expect" class="md-button md-button--secondary">
<a href="#istio-use-case" class="md-button md-button--secondary">
Learn more
</a>
</div>
<div class="tx-hero__image">
<img src="static/logo.png" alt="" draggable="false"
style="border-radius: 0.5rem; border: 1px solid #333; filter: drop-shadow(0 0 0.75rem #555);">
style="border-radius: 0.5rem; border: 1px solid #333; filter: drop-shadow(0 0 0.75rem #555);" />
</div>
</div>
<div class="mdx-hero__more" style="text-align: center;">
<a href="#everything-you-would-expect">
<a href="#istio-use-case">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
style="height: 1.5rem; fill: currentColor;">
<path d="M11 4h2v12l5.5-5.5 1.42 1.42L12 19.84l-7.92-7.92L5.5 10.5 11 16V4Z"></path>
Expand All @@ -227,132 +227,22 @@ <h2>Policy based authorizations... in a mesh !</h2>
</div>
</div>
</section>
<section id="everything-you-would-expect" class="md-container tx-container" data-md-color-scheme="slate"
style="min-height: 100vh;">
<section id="istio-use-case" class="tx-container" style="min-height: 100vh;">
<div class="md-content md-grid" data-md-component="content">
<div class="md-content__inner">
<div class="md-content__inner md-typeset">
<header class="md-typeset">
<h1>
Everything you would expect
<a href="#everything-you-would-expect" class="headerlink" title="Permanent link"></a>
Overview (Istio)
<a href="#istio-use-case" class="headerlink" title="Permanent link"></a>
</h1>
</header>
<div class="mdx-expect">
<ul class="mdx-expect__list">
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/gear.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Easy to install</h2>
<p>
Install locally using a package manager like brew or nix, or simply download the
binary from one of our
<a href="https://github.com/kyverno/chainsaw/releases">releases</a>.
If you want to run using a Docker image, we have that too.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/pen.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Easy to use</h2>
<p>
Write tests in minutes, not hours. All it takes is a YAML file to define the steps
of a
test. Chainsaw will do the rest, no need to learn a programing language or write a
single line of code!
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/flag-checkered.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Comprehensive reporting</h2>
<p>
Understand and diagnose failures easily, thanks to a comprehensive output showing
precisely what failed and why.
Generate JUnit compatible reports to integrate with other test reporting tools.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/paint-roller.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Resource templating</h2>
<p>
Kubernetes is all about resouces and tests need to work with resources.
Chainsaw has built-in support for bindings, operation outputs and resource
templating to
describe complex test scenarios.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/circle-plus.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Positive testing</h2>
<p>
Create, update, delete resources and assert your controller reconciles the desired
and observed states in the expected way.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/circle-minus.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Negative testing</h2>
<p>
Try submitting invalid resources, invalid changes, or other disallowed actions and
make sure they are rejected.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/arrows-to-dot.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Stay focused</h2>
<p>
Focus on the software you are building, write test scenarios using YAML and let
Chainsaw
tell you what passes or not. Integrate in your CI pipeline to prevent regressions
and
release with better confidence.
</p>
</div>
</li>
<li class="mdx-expect__item md-typeset">
<div class="mdx-expect__icon">
{% include ".icons/fontawesome/solid/boxes-stacked.svg" %}
</div>
<div class="mdx-expect__description">
<h2>Multi cluster</h2>
<p>
Native support for tests involving multiple clusters, either static or dynamically
created ones, make Chainsaw an excellent tool for testing highly complex
environments
and architectures.
</p>
</div>
</li>
</ul>
<div style="display: flex; justify-content: center; margin-top: 2rem;">
<img src="schemas/overview.svg" alt="" draggable="false"
style="border-radius: 0.5rem; border: 1px solid #333; filter: drop-shadow(0 0 0.75rem #555);" />
</div>
</div>
</div>
</section>
</div>
{% endblock %}
{% block main %}{% endblock %}
{% block content %}{% endblock %}
{% block content %}{% endblock %}
54 changes: 36 additions & 18 deletions website/docs/policies/authorization-rules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Every authorization rule must contain a [CEL](https://github.com/google/cel-spec

Creating the Envoy [CheckResponse](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkresponse) can be a tedious task, you need to remember the different types names and format.

The CEL engine used to evaluate the authorization rules has been extended with a library to make the creation of `CheckResponse` easier. (TODO)
The CEL engine used to evaluate the authorization rules has been extended with a library to make the creation of `CheckResponse` easier. Browse the [available libraries documentation](../cel-extensions/index.md) for details.

## Authorization rules

Expand Down Expand Up @@ -46,7 +46,7 @@ In this simple rule:
Creates a `CheckResponse` to deny the request with status code `403`

However, we can do a lot more with Envoy's `CheckResponse`.
Envoy can add or remove headers, query parameters, register dynamic metadata passed along the filters chain, and even change the response body. (TODO)
Envoy can add or remove headers, query parameters, register dynamic metadata passed along the filters chain, and even change the response body.

![dynamic metadata](../schemas/dynamic-metadata.png)

Expand Down Expand Up @@ -81,7 +81,7 @@ spec:
### The hard way
Below is the same policy, creating the `CheckResponses` manually:
Below is the same policy, creating the `CheckResponses` manually.

```yaml
apiVersion: envoy.kyverno.io/v1alpha1
Expand Down Expand Up @@ -124,29 +124,43 @@ This second policy showcases a more advanced example.
apiVersion: envoy.kyverno.io/v1alpha1
kind: AuthorizationPolicy
metadata:
name: demo
name: demo-policy.example.com
spec:
failurePolicy: Fail
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"]
- name: metadata
expression: '{"my-new-metadata": "my-new-value"}'
authorizations:
# if force_unauthenticated -> 401
- expression: >
variables.force_unauthenticated
? envoy
.Denied(401)
.WithBody("Authentication Failed")
.Response()
.WithMetadata(variables.metadata)
: null
# if force_authorized -> 200
- 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()
EOF
variables.force_authorized
? envoy
.Allowed()
.WithHeader("x-validated-by", "my-security-checkpoint")
.WithoutHeader("x-force-authorized")
.WithResponseHeader("x-add-custom-response-header", "added")
.Response()
.WithMetadata(variables.metadata)
: null
# else -> 403
- expression: >
envoy
.Denied(403)
.WithBody("Unauthorized Request")
.Response()
.WithMetadata(variables.metadata)
```

Notice this policy uses helper functions:
Expand All @@ -170,3 +184,7 @@ Notice this policy uses helper functions:
- `WithMetadata`

To add dynamic metadata in the envoy filter chain (this is useful when you want to pass data to another filter in the chain or you want to print it in the application logs)

!!!info

The full documentation of the CEL Envoy library is available [here](../cel-extensions/envoy.md).
40 changes: 18 additions & 22 deletions website/docs/quick-start/authz-server.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,39 +8,20 @@ Then you will interface [Istio](https://istio.io/latest/), an open source servic

### Prerequisites

- A Kubernetes cluster with Istio installed
- A Kubernetes cluster
- [Helm](https://helm.sh/) to install the Kyverno Authz Server
- [istioctl](https://istio.io/latest/docs/setup/getting-started/#download) to configure the mesh
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to interact with the cluster

### Setup a cluster (optional)

If you don't have a cluster at hand, you can create a local one with [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) and istall Istio with Helm.
If you don't have a cluster at hand, you can create a local one with [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation).

```bash
KIND_IMAGE=kindest/node:v1.31.1

# create cluster
kind create cluster --image $KIND_IMAGE --wait 1m

# install istio
helm install istio-base --namespace istio-system --create-namespace --wait --repo https://istio-release.storage.googleapis.com/charts base
helm install istiod --namespace istio-system --create-namespace --wait --repo https://istio-release.storage.googleapis.com/charts istiod
```

### Deploy the Kyverno Authz Server

The first step is to deploy the Kyverno Authz Server.

```bash
# create the kyverno namespace
kubectl create ns kyverno

# label the namespace to inject the envoy proxy
kubectl label namespace kyverno istio-injection=enabled

# deploy the kyverno authz server
helm install kyverno-authz-server --namespace kyverno --wait --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server
```

### Configure the mesh
Expand All @@ -63,7 +44,7 @@ spec:
EOF
```

Notice that in the configuration, we define an `extensionProviders` section that points to the Kyverno Authz Server installation:
Notice that in the configuration, we define an `extensionProviders` section that points to the Kyverno Authz Server we will install in the next step:

```yaml
[...]
Expand All @@ -75,6 +56,21 @@ Notice that in the configuration, we define an `extensionProviders` section that
[...]
```

### Deploy the Kyverno Authz Server

The first step is to deploy the Kyverno Authz Server.

```bash
# create the kyverno namespace
kubectl create ns kyverno

# label the namespace to inject the envoy proxy
kubectl label namespace kyverno istio-injection=enabled

# deploy the kyverno authz server
helm install kyverno-authz-server --namespace kyverno --wait --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server
```

### Deploy a sample application

Httpbin is a well-known application that can be used to test HTTP requests and helps to show quickly how we can play with the request and response attributes.
Expand Down
39 changes: 27 additions & 12 deletions website/docs/reference/json-schemas.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,33 @@ spec:
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"]
- name: metadata
expression: '{"my-new-metadata": "my-new-value"}'
authorizations:
# if force_unauthenticated -> 401
- 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()
variables.force_unauthenticated
? envoy
.Denied(401)
.WithBody("Authentication Failed")
.Response()
.WithMetadata(variables.metadata)
: null
# if force_authorized -> 200
- expression: >
variables.force_authorized
? envoy
.Allowed()
.WithHeader("x-validated-by", "my-security-checkpoint")
.WithoutHeader("x-force-authorized")
.WithResponseHeader("x-add-custom-response-header", "added")
.Response()
.WithMetadata(variables.metadata)
: null
# else -> 403
- expression: >
envoy
.Denied(403)
.WithBody("Unauthorized Request")
.Response()
```
1 change: 1 addition & 0 deletions website/docs/schemas/overview.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 1ab7c10

Please sign in to comment.