From 1ab7c109a3634920702378795f1416e1133e84f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Fri, 8 Nov 2024 14:23:02 +0100 Subject: [PATCH] docs: final update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché --- .../policies/demo-policy.example.com.yaml | 1 - website/apis/config.yaml | 1 - website/docs/overrides/home.html | 132 ++---------------- website/docs/policies/authorization-rules.md | 54 ++++--- website/docs/quick-start/authz-server.md | 40 +++--- website/docs/reference/json-schemas.md | 39 ++++-- website/docs/schemas/overview.svg | 1 + website/docs/tutorials/istio/index.md | 40 +++--- 8 files changed, 111 insertions(+), 197 deletions(-) create mode 100644 website/docs/schemas/overview.svg diff --git a/.manifests/policies/demo-policy.example.com.yaml b/.manifests/policies/demo-policy.example.com.yaml index b42b1660..288c998f 100644 --- a/.manifests/policies/demo-policy.example.com.yaml +++ b/.manifests/policies/demo-policy.example.com.yaml @@ -38,4 +38,3 @@ spec: .Denied(403) .WithBody("Unauthorized Request") .Response() - .WithMetadata(variables.metadata) diff --git a/website/apis/config.yaml b/website/apis/config.yaml index 6461d9cf..082bc476 100644 --- a/website/apis/config.yaml +++ b/website/apis/config.yaml @@ -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. diff --git a/website/docs/overrides/home.html b/website/docs/overrides/home.html index b2e7658e..e8043635 100644 --- a/website/docs/overrides/home.html +++ b/website/docs/overrides/home.html @@ -207,17 +207,17 @@

Policy based authorizations... in a mesh !

class="md-button md-button--primary"> Get started - + Learn more
+ style="border-radius: 0.5rem; border: 1px solid #333; filter: drop-shadow(0 0 0.75rem #555);" />
- + @@ -227,132 +227,22 @@

Policy based authorizations... in a mesh !

-
+
-
+

- Everything you would expect - + Overview (Istio) +

-
-
    -
  • -
    - {% include ".icons/fontawesome/solid/gear.svg" %} -
    -
    -

    Easy to install

    -

    - Install locally using a package manager like brew or nix, or simply download the - binary from one of our - releases. - If you want to run using a Docker image, we have that too. -

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/pen.svg" %} -
    -
    -

    Easy to use

    -

    - 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! -

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/flag-checkered.svg" %} -
    -
    -

    Comprehensive reporting

    -

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

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/paint-roller.svg" %} -
    -
    -

    Resource templating

    -

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

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/circle-plus.svg" %} -
    -
    -

    Positive testing

    -

    - Create, update, delete resources and assert your controller reconciles the desired - and observed states in the expected way. -

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/circle-minus.svg" %} -
    -
    -

    Negative testing

    -

    - Try submitting invalid resources, invalid changes, or other disallowed actions and - make sure they are rejected. -

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/arrows-to-dot.svg" %} -
    -
    -

    Stay focused

    -

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

    -
    -
    • -
  • -
    - {% include ".icons/fontawesome/solid/boxes-stacked.svg" %} -
    -
    -

    Multi cluster

    -

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

    -
    -
    • -
+
+
-
{% endblock %} {% block main %}{% endblock %} -{% block content %}{% endblock %} \ No newline at end of file +{% block content %}{% endblock %} diff --git a/website/docs/policies/authorization-rules.md b/website/docs/policies/authorization-rules.md index 3fa4f5c8..7c8d006b 100644 --- a/website/docs/policies/authorization-rules.md +++ b/website/docs/policies/authorization-rules.md @@ -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 @@ -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) @@ -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 @@ -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: @@ -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). \ No newline at end of file diff --git a/website/docs/quick-start/authz-server.md b/website/docs/quick-start/authz-server.md index d2421f86..571535bc 100644 --- a/website/docs/quick-start/authz-server.md +++ b/website/docs/quick-start/authz-server.md @@ -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 @@ -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 [...] @@ -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. diff --git a/website/docs/reference/json-schemas.md b/website/docs/reference/json-schemas.md index be318e2f..413a3804 100644 --- a/website/docs/reference/json-schemas.md +++ b/website/docs/reference/json-schemas.md @@ -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() ``` diff --git a/website/docs/schemas/overview.svg b/website/docs/schemas/overview.svg new file mode 100644 index 00000000..dfd06e4a --- /dev/null +++ b/website/docs/schemas/overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/website/docs/tutorials/istio/index.md b/website/docs/tutorials/istio/index.md index 32e0e503..0aa8725a 100644 --- a/website/docs/tutorials/istio/index.md +++ b/website/docs/tutorials/istio/index.md @@ -8,39 +8,20 @@ This tutorial shows how Istio’s AuthorizationPolicy can be configured to deleg ### 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 @@ -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 [...] @@ -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.