From 03f99fa7d744d483729e68cec8c6cd6517a1d2c9 Mon Sep 17 00:00:00 2001 From: ci-bot Date: Mon, 6 Jan 2025 11:09:57 +0000 Subject: [PATCH] Deployed 0f48276 to main with MkDocs 1.6.1 and mike 2.1.3 --- main/search/search_index.json | 2 +- main/sitemap.xml | 52 ++++++++++++------------ main/sitemap.xml.gz | Bin 449 -> 449 bytes main/tutorials/envoy-gateway/index.html | 35 ++++++++++++++-- main/tutorials/istio/index.html | 32 +++++++++++++-- 5 files changed, 86 insertions(+), 35 deletions(-) diff --git a/main/search/search_index.json b/main/search/search_index.json index a758230..403b4fd 100644 --- a/main/search/search_index.json +++ b/main/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"cel-extensions/","title":"CEL extensions","text":"

The CEL engine used to evaluate variables and authorization rules has been extended with libraries to help processing the input CheckRequest and forge the corresponding OkResponse and/or DeniedResponse.

"},{"location":"cel-extensions/#envoy-plugin-libraries","title":"Envoy plugin libraries","text":""},{"location":"cel-extensions/#common-libraries","title":"Common libraries","text":"

The libraries below are common CEL extensions enabled in the Kyverno Authz Server CEL engine:

"},{"location":"cel-extensions/#kubernetes-libraries","title":"Kubernetes libraries","text":"

The libraries below are imported from Kubernetes:

"},{"location":"cel-extensions/envoy/","title":"Envoy library","text":"

The envoy library adds some types and function to simplify the creation of OkResponse and DeniedResponse objects.

"},{"location":"cel-extensions/envoy/#types","title":"Types","text":""},{"location":"cel-extensions/envoy/#checkrequest","title":"<CheckRequest>","text":"

CEL Type / Proto: envoy.service.auth.v3.CheckRequest

"},{"location":"cel-extensions/envoy/#okresponse","title":"<OkResponse>","text":"

CEL Type / Proto: envoy.OkResponse

Field CEL Type / Proto Docs status google.rpc.Status Docs http_response envoy.service.auth.v3.OkHttpResponse Docs dynamic_metadata google.protobuf.Struct Docs"},{"location":"cel-extensions/envoy/#deniedresponse","title":"<DeniedResponse>","text":"

CEL Type / Proto: envoy.DeniedResponse

Field CEL Type / Proto Docs status google.rpc.Status Docs http_response envoy.service.auth.v3.DeniedHttpResponse Docs dynamic_metadata google.protobuf.Struct Docs"},{"location":"cel-extensions/envoy/#okhttpresponse","title":"<OkHttpResponse>","text":"

CEL Type / Proto: envoy.service.auth.v3.OkHttpResponse

"},{"location":"cel-extensions/envoy/#deniedhttpresponse","title":"<DeniedHttpResponse>","text":"

CEL Type / Proto: envoy.service.auth.v3.DeniedHttpResponse

"},{"location":"cel-extensions/envoy/#metadata","title":"<Metadata>","text":"

CEL Type / Proto: google.protobuf.Struct

"},{"location":"cel-extensions/envoy/#headervalueoption","title":"<HeaderValueOption>","text":"

CEL Type / Proto: envoy.config.core.v3.HeaderValueOption

"},{"location":"cel-extensions/envoy/#queryparameter","title":"<QueryParameter>","text":"

CEL Type / Proto: envoy.config.core.v3.QueryParameter

"},{"location":"cel-extensions/envoy/#status","title":"<Status>","text":"

CEL Type / Proto: google.rpc.Status

"},{"location":"cel-extensions/envoy/#functions","title":"Functions","text":""},{"location":"cel-extensions/envoy/#envoyallowed","title":"envoy.Allowed","text":"

This function creates an <OkHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads","title":"Signature and overloads","text":"
envoy.Allowed() -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example","title":"Example","text":"
envoy.Allowed()\n
"},{"location":"cel-extensions/envoy/#envoydenied","title":"envoy.Denied","text":"

This function creates a <DeniedHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_1","title":"Signature and overloads","text":"
envoy.Denied(<int> code) -> <DeniedHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_1","title":"Example","text":"
envoy.Denied(401)\n
"},{"location":"cel-extensions/envoy/#envoyheader","title":"envoy.Header","text":"

This function creates an <HeaderValueOption> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_2","title":"Signature and overloads","text":"
envoy.Header(<string> key, <string> value) -> <HeaderValueOption>\n
"},{"location":"cel-extensions/envoy/#example_2","title":"Example","text":"
envoy.Header(\"foo\", \"bar\")\n
"},{"location":"cel-extensions/envoy/#envoyqueryparam","title":"envoy.QueryParam","text":"

This function creates a <QueryParameter> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_3","title":"Signature and overloads","text":"
envoy.QueryParam(<string> key, <string> value) -> <QueryParameter>\n
"},{"location":"cel-extensions/envoy/#example_3","title":"Example","text":"
envoy.QueryParam(\"foo\", \"bar\")\n
"},{"location":"cel-extensions/envoy/#withbody","title":"WithBody","text":"

This function sets the body of a <DeniedHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_4","title":"Signature and overloads","text":"
<DeniedHttpResponse>.WithBody(<string> body) -> <DeniedHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_4","title":"Example","text":"
envoy.Denied(401).WithBody(\"Unauthorized Request\")\n
"},{"location":"cel-extensions/envoy/#withheader","title":"WithHeader","text":"

This function adds a <HeaderValueOption>:

"},{"location":"cel-extensions/envoy/#signature-and-overloads_5","title":"Signature and overloads","text":"

<OkHttpResponse>.WithHeader(<HeaderValueOption> header) -> <OkHttpResponse>\n
<OkHttpResponse>.WithHeader(<string> key, <string> value) -> <OkHttpResponse>\n
<DeniedHttpResponse>.WithHeader(<HeaderValueOption> header) -> <DeniedHttpResponse>\n
<DeniedHttpResponse>.WithHeader(<string> key, <string> value) -> <DeniedHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_5","title":"Example","text":"

envoy.Allowed().WithHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Allowed().WithHeader(\"foo\", \"bar\")\n
envoy.Denied(401).WithHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Denied(401).WithHeader(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withoutheader","title":"WithoutHeader","text":"

This function marks a header to be removed when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_6","title":"Signature and overloads","text":"
<OkHttpResponse>.WithoutHeader(<string> header) -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_6","title":"Example","text":"
envoy.Allowed().WithoutHeader(\"foo\")\n
"},{"location":"cel-extensions/envoy/#withresponseheader","title":"WithResponseHeader","text":"

This function adds a <HeaderValueOption> when the response is sent downstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_7","title":"Signature and overloads","text":"

<OkHttpResponse>.WithResponseHeader(<HeaderValueOption> header) -> <OkHttpResponse>\n
<OkHttpResponse>.WithResponseHeader(<string> key, <string> value) -> <OkHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_7","title":"Example","text":"

envoy.Allowed().WithResponseHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Allowed().WithResponseHeader(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withqueryparam","title":"WithQueryParam","text":"

This function adds a <QueryParameter> to be added when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_8","title":"Signature and overloads","text":"

<OkHttpResponse>.WithQueryParam(<QueryParameter> param) -> <OkHttpResponse>\n
<OkHttpResponse>.WithQueryParam(<string> key, <string> value) -> <OkHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_8","title":"Example","text":"

envoy.Allowed().WithQueryParam(envoy.QueryParam(\"foo\", \"bar\"))\n
envoy.Allowed().WithQueryParam(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withoutqueryparam","title":"WithoutQueryParam","text":"

This function marks a query parameter to be removed when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_9","title":"Signature and overloads","text":"
<OkHttpResponse>.WithoutQueryParam(<string> param) -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_9","title":"Example","text":"
envoy.Allowed().WithoutQueryParam(\"foo\")\n
"},{"location":"cel-extensions/envoy/#keepemptyvalue","title":"KeepEmptyValue","text":"

This function sets the keep_empty_value field of an <HeaderValueOption> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_10","title":"Signature and overloads","text":"

<HeaderValueOption>.KeepEmptyValue() -> <HeaderValueOption>\n
<HeaderValueOption>.KeepEmptyValue(<bool> keep) -> <HeaderValueOption>\n

"},{"location":"cel-extensions/envoy/#example_10","title":"Example","text":"

envoy.Header(\"foo\", \"bar\").KeepEmptyValue()\n
envoy.Header(\"foo\", \"bar\").KeepEmptyValue(true)\n

"},{"location":"cel-extensions/envoy/#response","title":"Response","text":"

This function creates a <OkResponse> / DeniedResponse object from an <OkHttpResponse> / <DeniedHttpResponse>.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_11","title":"Signature and overloads","text":"

<OkHttpResponse>.Response() -> <OkResponse>\n
<DeniedHttpResponse>.Response() -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_11","title":"Example","text":"

envoy.Allowed().Response()\n
envoy.Denied(401).Response()\n

"},{"location":"cel-extensions/envoy/#withmessage","title":"WithMessage","text":"

This function sets the status.message field of an <OkResponse> / DeniedResponse object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_12","title":"Signature and overloads","text":"

<OkResponse>.WithMessage(<string> message) -> <OkResponse>\n
<DeniedResponse>.WithMessage(<string> message) -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_12","title":"Example","text":"

envoy.Allowed().Response().WithMessage(\"hello world!\")\n
envoy.Denied(401).Response().WithMessage(\"hello world!\")\n

"},{"location":"cel-extensions/envoy/#withmetadata","title":"WithMetadata","text":"

This function sets the dynamic_metadata field of an <OkResponse> / DeniedResponse object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_13","title":"Signature and overloads","text":"

<OkResponse>.WithMetadata(<Metadata> metadata) -> <OkResponse>\n
<DeniedResponse>.WithMetadata(<Metadata> metadata) -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_13","title":"Example","text":"

envoy.Allowed().Response().WithMetadata({ \"foo\": \"bar\" })\n
envoy.Denied(401).Response().WithMetadata({ \"foo\": \"bar\" })\n

"},{"location":"cel-extensions/jwt/","title":"Jwt library","text":"

Policies have native functionality to decode and verify the contents of JWT tokens in order to enforce additional authorization logic on requests.

"},{"location":"cel-extensions/jwt/#types","title":"Types","text":""},{"location":"cel-extensions/jwt/#token","title":"<Token>","text":"

CEL Type / Proto jwt.Token

Field CEL Type / Proto Docs Valid bool Header google.protobuf.Struct Docs Claims google.protobuf.Struct Docs"},{"location":"cel-extensions/jwt/#functions","title":"Functions","text":""},{"location":"cel-extensions/jwt/#jwtdecode","title":"jwt.Decode","text":"

The jwt.Decode function decodes and validates a JWT token. It accepts two arguments: the token and the secret to verify the signature.

"},{"location":"cel-extensions/jwt/#signature-and-overloads","title":"Signature and overloads","text":"
jwt.Decode(<string> token, <string> key) -> <Token>\n
"},{"location":"cel-extensions/jwt/#example","title":"Example","text":"
jwt.Decode(\"eyJhbGciOiJIUzI1NiI....\", \"secret\")\n
"},{"location":"community/","title":"Community","text":"

The Kyverno Envoy Plugin has a growing community and we would definitely love to see you join and contribute.

Everyone is welcome to make suggestions, report bugs, open feature requests, contribute code or docs, participate in discussions, write blogs or anything that can benefit the project.

The Kyverno Envoy Plugin is built and maintained under the Kyverno umbrella but decisions are Community driven Everyone's voice matters

"},{"location":"community/#slack-channel","title":"Slack channel","text":"

Join our slack channel #kyverno to meet with users, contributors and maintainers.

"},{"location":"community/#roadmap","title":"RoadMap","text":"

For detailed information on our planned features and upcoming updates, please view our Roadmap.

"},{"location":"community/#contributing","title":"Contributing","text":"

Please read the contributing guide for details around:

  1. Code of Conduct
  2. Code Culture
  3. Details on how to contribute
"},{"location":"community/#adopters","title":"Adopters","text":"

If you are using the Kyverno Envoy Plugin and want to share it publicly we always appreciate a bit of support. Pull requests to the ADOPTERS LIST will put a smile on our faces

"},{"location":"community/contribute/","title":"Contributing","text":"

Kyverno Envoy Plugin, developed by Kyverno, is an advanced end-to-end testing tool for Kubernetes. Our community plays a crucial role in shaping the project by reporting bugs, suggesting features, and improving documentation.

We aim to make our issue tracker, discussion board, and documentation well-structured and easy to navigate. By following our guidelines, you can help us address your requests efficiently.

"},{"location":"community/contribute/#how-you-can-contribute","title":"How you can contribute","text":"

We appreciate your efforts in reporting bugs, requesting features, and engaging in discussions. Here's how you can contribute:

"},{"location":"community/contribute/#creating-an-issue","title":"Creating an issue","text":""},{"location":"community/contribute/#contributing_1","title":"Contributing","text":""},{"location":"community/contribute/#checklist","title":"Checklist","text":"

Before interacting within the project, please consider the following questions to ensure you're using the correct issue template and providing all necessary information.

Issues, discussions, and comments are forever

Please note that everything you write is permanent and will remain for everyone to read \u2013 forever. Therefore, please always be nice and constructive, follow our contribution guidelines, and comply with our Code of Conduct.

"},{"location":"community/contribute/#before-creating-an-issue","title":"Before creating an issue","text":""},{"location":"community/contribute/#before-asking-a-question","title":"Before asking a question","text":""},{"location":"community/contribute/#before-commenting","title":"Before commenting","text":""},{"location":"community/contribute/#rights-and-responsibilities","title":"Rights and responsibilities","text":"

As maintainers, we are entrusted with the responsibility to moderate communication within our community, including the authority to close, remove, reject, or edit issues, discussions, comments, commits, and to block users who do not align with our contribution guidelines and our Code of Conduct. This role requires us to be actively involved in maintaining the integrity and positive atmosphere of our community. Upholding these standards decisively ensures a respectful and inclusive environment for all members.

"},{"location":"community/contribute/#code-of-conduct","title":"Code of Conduct","text":"

Our Code of Conduct outlines the expectation for all community members to treat one another with respect, employing inclusive and welcoming language. Our commitment is to foster a positive and supportive environment, free of inappropriate, offensive, or harmful behavior.

We take any violations seriously and will take appropriate action in response to uphold these values.1

"},{"location":"community/contribute/#incomplete-issues-and-duplicates","title":"Incomplete issues and duplicates","text":"

We have invested significant time and effort in the setup of our contribution process, ensuring that we assess the essential requirements for reviewing and responding to issues effectively. Each field in our issue templates is thoughtfully designed to help us fully understand your concerns and the nature of your matter. We encourage all members to utilize the search function before submitting new issues or starting discussions to help avoid duplicates. Your cooperation is crucial in keeping our community's discussions constructive and organized.

  1. Warning and blocking policy: Given the increasing popularity of our project and our commitment to a healthy community, we've defined clear guidelines on how we proceed with violations:

    1.1. First warning: Users displaying repeated inappropriate, offensive, or harmful behavior will receive a first warning. This warning serves as a formal notice that their behavior is not in alignment with our community standards and Code of Conduct. The first warning is permanent.

    1.2. Second warning and opportunity for resolution: If the behavior persists, a second warning will be issued. Upon receiving the second warning, the user will be given a 5-day period for reflection, during which they are encouraged to publicly explain or apologize for their actions. This period is designed to offer an opportunity for openly clearing out any misunderstanding.

    1.3. Blocking: Should there be no response or improvement in behavior following the second warning, we reserve the right to block the user from the community and repository. Blocking is considered a last resort, used only when absolutely necessary to protect the community's integrity and positive atmosphere.

    Blocking has been an exceptionally rare necessity in our overwhelmingly positive community, highlighting our preference for constructive dialogue and mutual respect. It aims to protect our community members and team.\u00a0\u21a9

"},{"location":"community/making-a-pull-request/","title":"Pull Requests","text":"

You can contribute by making a pull request that will be reviewed by maintainers and integrated into the main repository when the changes made are approved. You can contribute bug fixes, documentation changes, or new functionalities.

Considering a pull request

Before deciding to spend effort on making changes and creating a pull request, please discuss what you intend to do. If you are responding to what you think might be a bug, please issue a bug report first. If you intend to work on documentation, create a documentation issue. If you want to work on a new feature, please create a change request.

Keep in mind the guidance given and let people advise you. It might be that there are easier solutions to the problem you perceive and want to address. It might be that what you want to achieve can already be done by configuration or [customization].

"},{"location":"community/making-a-pull-request/#learning-about-pull-requests","title":"Learning about pull requests","text":"

Pull requests are a concept layered on top of Git by services that provide Git hosting. Before you consider making a pull request, you should familiarize yourself with the documentation on GitHub, the service we are using. The following articles are of particular importance:

  1. Forking a repository
  2. Creating a pull request from a fork
  3. Creating a pull request

Note that they provide tailored documentation for different operating systems and different ways of interacting with GitHub. We do our best in the documentation here to describe the process as it applies but cannot cover all possible combinations of tools and ways of doing things. It is also important that you understand the concept of a pull-request in general before continuing.

"},{"location":"community/making-a-pull-request/#pull-request-process","title":"Pull request process","text":"

In the following, we describe the general process for making pull requests. The aim here is to provide the 30k ft overview before describing details later on.

"},{"location":"community/making-a-pull-request/#preparing-changes-and-draft-pr","title":"Preparing changes and draft PR","text":"

The diagram below describes what typically happens to repositories in the process or preparing a pull request. We will be discussing the review-revise process below. It is important that you understand the overall process first before you worry about specific commands. This is why we cover this first before providing instructions below.

sequenceDiagram\n  autonumber\n\n  participant upstream\n  participant PR\n  participant fork\n  participant local\n\n  upstream ->> fork: fork on GitHub\n  fork ->> local: clone to local\n  local ->> local: branch\n  loop prepare\n    loop push\n      loop edit\n        local ->> local: commit\n      end\n      local ->> fork: push\n    end\n    upstream ->> fork: merge in any changes\n    fork ->>+ PR: create draft PR\n    PR ->> PR: review your changes\n  end
  1. Fork the Repository: Fork the upstream repository on GitHub to create your own copy.
  2. Clone to Local: Clone your fork to your local machine.
  3. Create a Branch: Create a topic branch for your changes.
  4. Set Up Development Environment: Follow the instructions to set up a development environment.
  5. Iterate and Commit: Make incremental changes and commit them with meaningful messages.
  6. Push Regularly: Push your commits to your fork regularly.
  7. Merge Changes from Upstream: Regularly merge changes from the original upstream repository to avoid conflicts.
  8. Create a Draft Pull Request: Once satisfied with your changes, create a draft pull request for early feedback.
  9. Review and Revise: Review your work critically, address feedback, and refine your changes.
"},{"location":"community/making-a-pull-request/#finalizing","title":"Finalizing","text":"

Once you are happy with your changes, you can move to the next step, finalizing your pull request and asking for a more formal and detailed review. The diagram below shows the process:

sequenceDiagram\n  autonumber\n  participant upstream\n  participant PR\n  participant fork\n  participant local\n\n  activate PR\n  PR ->> PR: finalize PR\n  loop review\n    loop discuss\n      PR ->> PR: request review\n      PR ->> PR: discussion\n      local ->> fork: push further changes\n    end\n    PR ->> upstream: merge (and squash)\n    deactivate PR\n    fork ->> fork: delete branch\n    upstream ->> fork: pull\n    local ->> local: delete branch\n    fork ->> local: pull\n  end\n
  1. Finalize PR: Signal that your changes are ready for review.
  2. Request Review: Ask the maintainer to review your changes.
  3. Discuss and Revise: Engage in discussions, make necessary revisions, and iterate.
  4. Merge and Squash: Once approved, the maintainer will merge and possibly squash your commits.
  5. Clean Up: Delete the branch used for the PR from both your fork and local clone.
"},{"location":"community/reporting-a-bug/","title":"Bug Reports","text":"

If you think you have discovered a bug, you can help us by submitting an issue in our public issue tracker, following this guide.

"},{"location":"community/reporting-a-bug/#before-creating-an-issue","title":"Before Creating an Issue","text":"

With numerous users, issues are created regularly. The maintainers of this project strive to address bugs promptly. By following this guide, you will know exactly what information we need to help you quickly.

Please do the following before creating an issue:

"},{"location":"community/reporting-a-bug/#upgrade-to-latest-version","title":"Upgrade to Latest Version","text":"

Chances are that the bug you discovered was already fixed in a subsequent version. Before reporting an issue, ensure that you're running the latest version.

Bug fixes are not backported

Please understand that only bugs that occur in the latest version will be addressed. Also, to reduce duplicate efforts, fixes cannot always be backported to earlier versions.

"},{"location":"community/reporting-a-bug/#remove-customizations","title":"Remove Customizations","text":"

If you're using customizations like additional configurations, remove them before reporting a bug. We can't offer official support for bugs that might hide in your overrides, so make sure to omit custom settings from your configuration files.

Don't be shy to ask on our discussion board for help if you run into problems.

"},{"location":"community/reporting-a-bug/#search-for-solutions","title":"Search for Solutions","text":"

At this stage, we know that the problem persists in the latest version and is not caused by any of your customizations. However, the problem might result from a small typo or a syntactical error in a configuration file.

Before creating a bug report, save time for us and yourself by doing some research:

  1. Search our documentation for relevant sections related to your problem. Ensure everything is configured correctly.
  2. [Search our issue tracker] as another user might have already reported the same problem.
  3. [Search our discussion board] to see if other users are facing similar issues and find possible solutions.

Keep track of all search terms and relevant links; you'll need them in the bug report.

If you still haven't found a solution to your problem, create an issue. It's now likely that you've encountered something new. Read the following section to learn how to create a complete and helpful bug report.

"},{"location":"community/reporting-a-bug/#issue-template","title":"Issue Template","text":"

We have created a new issue template to make the bug reporting process as simple as possible and more efficient for our community and us. It consists of the following parts:

"},{"location":"community/reporting-a-bug/#title","title":"Title","text":"

A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug can be inferred from the title.

Example Clear apply command fails with specific CRD Wordy The apply command fails when used with a certain Custom Resource Definition Unclear Command does not work Useless Help"},{"location":"community/reporting-a-bug/#context","title":"Context optional","text":"

Before describing the bug, you can provide additional context to help us understand what you were trying to achieve. Explain the circumstances under which the bug happens, and what you think might be relevant. Don't describe the bug here.

"},{"location":"community/reporting-a-bug/#bug-description","title":"Bug Description","text":"

Provide a clear, focused, specific, and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported, and not to one of its dependencies. Follow these principles:

"},{"location":"community/reporting-a-bug/#related-links","title":"Related Links","text":"

Share links to relevant sections of our documentation and any related issues or discussions. This helps us improve our documentation and understand the problem better.

"},{"location":"community/reporting-a-bug/#reproduction","title":"Reproduction","text":"

A minimal reproduction is essential for a well-written bug report, as it allows us to recreate the conditions necessary to inspect the bug. Follow the guide to create a reproduction:

[ Create reproduction][Create reproduction]{ .md-button .md-button--primary }

After creating the reproduction, you should have a .zip file, ideally not larger than 1 MB. Drag and drop the .zip file into the issue field, which will automatically upload it to GitHub.

Don't share links to repositories

While linking to a repository is a common practice, we currently don't support this. The reproduction, created using the built-in info plugin, contains all necessary environment information.

"},{"location":"community/reporting-a-bug/#steps-to-reproduce","title":"Steps to Reproduce","text":"

List specific steps to follow when running your reproduction to observe the bug. Keep the steps concise and ensure nothing is left out. Use simple language and focus on continuity.

"},{"location":"community/reporting-a-bug/#browser","title":"Browser optional","text":"

If the bug only occurs in specific browsers, let us know which ones are affected. This field is optional, as it is only relevant for bugs that do not involve a crash when previewing or building your site.

Incognito Mode

Verify that the bug is not caused by a browser extension by switching to incognito mode. If the bug disappears, it is likely caused by an extension.

"},{"location":"community/reporting-a-bug/#checklist","title":"Checklist","text":"

Before submitting, ensure you have:

Thanks for following the guide and creating a high-quality bug report. We will take it from here.

"},{"location":"community/reporting-a-docs-issue/","title":"Documentation Issues","text":"

The documentation includes extensive information on features, configurations, customizations, and more. If you have found an inconsistency or see room for improvement, please follow this guide to submit an issue on our issue tracker.

"},{"location":"community/reporting-a-docs-issue/#issue-template","title":"Issue Template","text":"

Reporting a documentation issue is usually less involved than reporting a bug, as we don't need a [reproduction]. Please thoroughly read this guide before creating a new documentation issue, and provide the following information as part of the issue:

"},{"location":"community/reporting-a-docs-issue/#title","title":"Title","text":"

A good title should be a short, one-sentence description of the issue, containing all relevant information and keywords to simplify the search in our issue tracker.

Example Clear Clarify resource templating setup Unclear Missing information in the docs Useless Help"},{"location":"community/reporting-a-docs-issue/#description","title":"Description","text":"

Provide a clear and concise summary of the inconsistency or issue you encountered in the documentation or the documentation section that needs improvement. Explain why you think the documentation should be adjusted and describe the severity of the issue:

Why we need this: describing the problem clearly and concisely is a prerequisite for improving our documentation \u2013 we need to understand what's wrong so we can fix it.

"},{"location":"community/reporting-a-docs-issue/#related-links","title":"Related Links","text":"

After you describe the documentation section that needs to be adjusted, share the link to this specific documentation section and other possibly related sections. Use anchor links (permanent links) where possible, as it simplifies discovery.

Why we need this: providing the links to the documentation helps us understand which sections of our documentation need to be adjusted, extended, or overhauled.

"},{"location":"community/reporting-a-docs-issue/#proposed-change","title":"Proposed Change optional","text":"

Now that you have provided us with the description and links to the documentation sections, you can help us, maintainers, and the community by proposing an improvement. You can sketch out rough ideas or write a concrete proposal. This field is optional but very helpful.

Why we need this: an improvement proposal can be beneficial for other users who encounter the same issue, as they offer solutions before we maintainers can update the documentation.

"},{"location":"community/reporting-a-docs-issue/#checklist","title":"Checklist","text":"

Thanks for following the guide and providing valuable feedback for our documentation \u2013 you are almost done. The checklist ensures that you have read this guide and have worked to your best knowledge to provide us with every piece of information we need to improve it.

We'll take it from here.

"},{"location":"community/requesting-a-change/","title":"Change Requests","text":"

We value every idea or contribution from our community. Please follow this guide before submitting your change request in our public issue tracker. This helps us better understand the proposed change and how it will benefit our community.

"},{"location":"community/requesting-a-change/#before-creating-an-issue","title":"Before Creating an Issue","text":"

Before you invest time in submitting a change request, answer these questions to determine if your idea is a good fit and matches the project's philosophy and tone.

"},{"location":"community/requesting-a-change/#its-not-a-bug-its-a-feature","title":"It's Not a Bug, It's a Feature","text":"

Change requests suggest minor adjustments, new features, or influence the project's direction. They are not intended for reporting bugs. Refer to our bug reporting guide for that.

"},{"location":"community/requesting-a-change/#look-for-sources-of-inspiration","title":"Look for Sources of Inspiration","text":"

If your idea is implemented in another tool or framework, collect information on its implementation. This helps us evaluate its fit more quickly.

"},{"location":"community/requesting-a-change/#connect-with-our-community","title":"Connect with Our Community","text":"

Our discussion board is the best place to connect with our community. Seeking input from other users helps implement features that benefit a larger number of users.

Start a discussion

"},{"location":"community/requesting-a-change/#issue-template","title":"Issue Template","text":"

After doing the preliminary work, create a change request. Follow these steps:

"},{"location":"community/requesting-a-change/#title","title":"Title","text":"

A good title is short and descriptive, summarizing the idea so the potential impact and benefit can be inferred.

Example Clear Support for resource templating Wordy Add support for templating resources for easier testing Unclear Improve templating Useless Help"},{"location":"community/requesting-a-change/#context","title":"Context optional","text":"

Provide additional context to help us understand what you are trying to achieve. Explain the circumstances and relevant settings without describing the change request itself.

"},{"location":"community/requesting-a-change/#description","title":"Description","text":"

Provide a detailed and clear description of your idea. Explain why your idea is relevant and should be implemented here, not in one of its dependencies.

"},{"location":"community/requesting-a-change/#related-links","title":"Related Links","text":"

Provide any relevant links to issues, discussions, or documentation sections related to your change request. This helps us gain additional context.

"},{"location":"community/requesting-a-change/#use-cases","title":"Use Cases","text":"

Explain how your change request would work from an author's and user's perspective. What is the expected impact, and why does it benefit other users? Would it potentially break existing functionality?

"},{"location":"community/requesting-a-change/#visuals","title":"Visuals optional","text":"

If you have any visuals, such as sketches, screenshots, mockups, or external assets, present them in this section. If you have seen this change used in other tools, showcase and describe its implementation.

"},{"location":"community/requesting-a-change/#checklist","title":"Checklist","text":"

Thanks for following the guide and creating a high-quality change request. The checklist ensures that you have read this guide and provided all necessary information for us to review your idea.

We'll take it from here.

"},{"location":"community/requesting-a-change/#rejected-requests","title":"Rejected Requests","text":"

Your change request got rejected? We're sorry for that. We understand it can be frustrating, but we always need to consider the needs of our entire community. If you're unsure why your change request was rejected, please ask for clarification.

We consider the following principles when evaluating change requests:

If your idea was rejected, you can always implement it via [customization]. If you're unsure how or want to know if someone has already done it, get in touch with our community on the discussion board.

"},{"location":"performance/","title":"Performance","text":"

This page offers guidance and best practices for benchmarking the performance of the Kyverno Authz Server, helping users understand the associated overhead. It outlines an example setup for conducting benchmarks, various benchmarking scenarios, and key metrics to capture for assessing the impact of the Kyverno Authz Server.

"},{"location":"performance/#benchmark-setup","title":"Benchmark Setup","text":"

The benchmark setup consists of the following components:

"},{"location":"performance/#sample-application","title":"Sample Application","text":"

The first component is a simple Go application that provides information of books in the library books collection and exposes APIs to get, create and delete books collection. Check this out for more information about the Go test application .

"},{"location":"performance/#envoy","title":"Envoy","text":"

The second component is the Envoy proxy, which runs alongside the example application. The Envoy configuration defines an external authorization filter envoy.ext_authz for a gRPC authorization server.

The config uses Envoy's in-built gRPC client to make external gRPC calls.

static_resources:\n  listeners:\n  - address:\n      socket_address:\n        address: 0.0.0.0\n        port_value: 8000\n    filter_chains:\n    - filters:\n      - name: envoy.filters.network.http_connection_manager\n        typed_config:\n          \"@type\": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\n          codec_type: auto\n          stat_prefix: ingress_http\n          route_config:\n            name: local_route\n            virtual_hosts:\n            - name: backend\n              domains:\n              - \"*\"\n              routes:\n              - match:\n                  prefix: \"/\"\n                route:\n                  cluster: service\n          http_filters:\n          - name: envoy.ext_authz\n            typed_config:\n              \"@type\": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz\n              transport_api_version: V3\n              with_request_body:\n                max_request_bytes: 8192\n                allow_partial_message: true\n              failure_mode_allow: false\n              grpc_service:\n                google_grpc:\n                  target_uri: 127.0.0.1:9191\n                  stat_prefix: ext_authz\n                timeout: 0.5s\n          - name: envoy.filters.http.router\n            typed_config:\n              \"@type\": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router\n  clusters:\n  - name: service\n    connect_timeout: 0.25s\n    type: strict_dns\n    lb_policy: round_robin\n    load_assignment:\n      cluster_name: service\n      endpoints:\n      - lb_endpoints:\n        - endpoint:\n            address:\n              socket_address:\n                address: 127.0.0.1\n                port_value: 8080\nadmin:\n  access_log_path: \"/dev/null\"\n  address:\n    socket_address:\n      address: 0.0.0.0\n      port_value: 8001\nlayered_runtime:\n  layers:\n    - name: static_layer_0\n      static_layer:\n        envoy:\n          resource_limits:\n            listener:\n              example_listener_name:\n                connection_limit: 10000\n        overload:\n          global_downstream_max_connections: 50000\n
"},{"location":"performance/#kyverno-authz-server","title":"Kyverno Authz Server","text":"

The third component is the Kyverno Authz Server itself, which is configured to load and enforce Kyverno policies on incoming requests.

"},{"location":"performance/#benchmark-scenarios","title":"Benchmark Scenarios","text":"

The following scenarios should be tested to compare the performance of the Kyverno Authz Server under different conditions:

  1. App Only: Requests are sent directly to the application, without Envoy or the Kyverno Authz Server.
  2. App and Envoy: Envoy is included in the request path, but the Kyverno Authz Server is not (i.e., Envoy External Authorization API is disabled).
  3. App, Envoy, and Kyverno: Envoy External Authorization API is enabled, and a sample real-world policy is loaded into the Kyverno Authz Server.
"},{"location":"performance/#load-testing-with-k6","title":"Load Testing with k6","text":"

To perform load testing, we'll use the k6 tool. Follow these steps:

  1. Install k6: Install k6 on your machine by following the instructions on the official website.

  2. Write the k6 script: Below is the example k6 script. 

import http from 'k6/http';\nimport { check, group, sleep } from 'k6';\n\nexport const options = {\n  stages: [\n    { duration: '30s', target: 100 }, // Ramp-up to 100 virtual users over 30 seconds\n    { duration: '1m', target: 100 }, // Stay at 100 virtual users for 1 minute\n    { duration: '30s', target: 0 }, // Ramp-down to 0 virtual users over 30 seconds\n  ],\n};\n\n/*\nReplace ip for every scenerio\nexport SERVICE_PORT=$(kubectl -n demo get service testapp -o jsonpath='{.spec.ports[?(@.port==8080)].nodePort}')\nexport SERVICE_HOST=$(minikube ip)\nexport SERVICE_URL=$SERVICE_HOST:$SERVICE_PORT\necho $SERVICE_URL\n\nhttp://192.168.49.2:31541\n\n*/\nconst BASE_URL = 'http://192.168.49.2:31541'; \n\nexport default function () {\n  group('GET /book with guest token', () => {\n    const res = http.get(`${BASE_URL}/book`, {\n      headers: { 'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk' },\n    });\n    check(res, {\n      'is status 200': (r) => r.status === 200,\n    });\n  });\n\n  sleep(1); // Sleep for 1 second between iterations\n}\n
  1. Run the k6 test: Run the load test with the following command:
$ k6 run -f - <<EOF\nimport http from 'k6/http';\nimport { check, group, sleep } from 'k6';\n\nexport const options = {\n  stages: [\n    { duration: '30s', target: 100 }, // Ramp-up to 100 virtual users over 30 seconds\n    { duration: '1m', target: 100 }, // Stay at 100 virtual users for 1 minute\n    { duration: '30s', target: 0 }, // Ramp-down to 0 virtual users over 30 seconds\n  ],\n};\n\n\nconst BASE_URL = 'http://192.168.49.2:31700'; // Replace with your application URL \n\nexport default function () {\n  group('GET /book with guest token', () => {\n    const res = http.get(`${BASE_URL}/book`, {\n      headers: { 'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk' },\n    });\n    check(res, {\n      'is status 200': (r) => r.status === 200,\n    });\n  });\n\n  sleep(1); // Sleep for 1 second between iterations\n}\nEOF\n
  1. Analyze the results: Generate an json report with detailed insight by running:

k6 run --out json=report.json k6-script.js\n
5. Repeat for different scenarios:

"},{"location":"performance/#measuring-performance","title":"Measuring Performance","text":"

The following metrics should be measured to evaluate the performance impact of the Kyverno Authz Server:

Observations:

Correlation with k6 results:

"},{"location":"policies/","title":"Policies","text":"

A Kyverno AuthorizationPolicy is a custom Kubernetes resources and can be easily managed via Kubernetes APIs, GitOps workflows, and other existing tools.

"},{"location":"policies/#resource-scope","title":"Resource Scope","text":"

A Kyverno AuthorizationPolicy is a cluster-wide resource.

"},{"location":"policies/#api-group-and-kind","title":"API Group and Kind","text":"

An AuthorizationPolicy belongs to the envoy.kyverno.io/v1alpha1 group and can only be of kind AuthorizationPolicy.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the request will be denied\n  failurePolicy: Fail\n  variables:\n    # `force_authorized` references the 'x-force-authorized' header\n    # from the envoy check request (or '' if not present)\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n    # `allowed` will be `true` if `variables.force_authorized` has the\n    # value 'enabled' or 'true'\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n    # make an authorisation decision based on the value of `variables.allowed`\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n  - response: >\n      envoy.Allowed().Response()\n
"},{"location":"policies/#envoy-external-authorization","title":"Envoy External Authorization","text":"

The Kyverno Authz Server implements the Envoy External Authorization API.

A Kyverno AuthorizationPolicy analyses an Envoy CheckRequest and can make a decision by returning an OkResponse or DeniedResponse.

"},{"location":"policies/#cel-language","title":"CEL language","text":"

An AuthorizationPolicy uses the CEL language to process the CheckRequest sent by Envoy.

CEL is an expression language that\u2019s fast, portable, and safe to execute in performance-critical applications.

"},{"location":"policies/#policy-structure","title":"Policy structure","text":"

A Kyverno AuthorizationPolicy is made of:

"},{"location":"policies/authorization-rules/","title":"Authorization rules","text":"

An AuthorizationPolicy main concern is to define authorization rules to deny or allow requests.

Every authorization rule is made of an optional match statement and a required response statement. Both statements are written in CEL.

If the match statement is present and evaluates to true, the response statement is used to create the response payload returned to the envoy proxy. Depending on the rule type, the response is expected to be an envoy.OkResponse or envoy.DeniedResponse.

Creating an OkResponse or DeniedResponse 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 responses easier. Browse the available libraries documentation for details.

"},{"location":"policies/authorization-rules/#evaluation-order","title":"Evaluation order","text":"
  1. All deny rules are evaluated first, the first matching rule is used to send the deny response to the envoy proxy.
  2. If no deny rule matched, allow rules are evaluated and the first matching rule is used to send the response to the envoy proxy.
  3. If no rule matched, the request is allowed by default.

Info

When multiple policies are present, deny and allow rules are concatenated together in policy name alphabetical order.

"},{"location":"policies/authorization-rules/#authorization-rules_1","title":"Authorization rules","text":"

The policy below will allow requests if they contain the header x-force-authorized with the value enabled or true. If the header is not present or has a different value, the request will be denied.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  # make an authorisation decision based on the value of `variables.allowed`\n  # - deny the request with 403 status code if it is `false`\n  # - else allow the request\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n  - response: >\n      envoy.Allowed().Response()\n

In this simple rule:

However, we can do a lot more. Envoy can add or remove headers, query parameters, register dynamic metadata passed along the filters chain, and even change the response body.

"},{"location":"policies/authorization-rules/#the-hard-way","title":"The hard way","text":"

Below is the same policy, creating the envoy.OkResponse and envoy.DeniedResponse manually.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.DeniedResponse{\n        status: google.rpc.Status{\n          code: 7\n        },\n        http_response: envoy.service.auth.v3.DeniedHttpResponse{\n          status: envoy.type.v3.HttpStatus{\n            code: 403\n          }\n        }\n      }\n  allow:\n  - response: >\n      envoy.OkResponse{\n        status: google.rpc.Status{\n          code: 0\n        },\n        http_response: envoy.service.auth.v3.OkHttpResponse{}\n      }\n
"},{"location":"policies/authorization-rules/#advanced-example","title":"Advanced example","text":"

This second policy showcases a more advanced example.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: force_unauthenticated\n    expression: object.attributes.request.http.headers[?\"x-force-unauthenticated\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: metadata\n    expression: '{\"my-new-metadata\": \"my-new-value\"}'\n  deny:\n    # if force_unauthenticated -> 401\n  - match: >\n      variables.force_unauthenticated\n    response: >\n      envoy\n        .Denied(401)\n        .WithBody(\"Authentication Failed\")\n        .Response()\n    # if not force_authorized -> 403\n  - match: >\n      !variables.force_authorized\n    response: >\n      envoy\n        .Denied(403)\n        .WithBody(\"Unauthorized Request\")\n        .Response()\n  allow:\n    # else -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\n        .WithMetadata(variables.metadata)\n

Notice this policy uses helper functions:

Info

The full documentation of the CEL Envoy library is available here.

"},{"location":"policies/failure-policy/","title":"Failure policy","text":"

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.

Allowed values are:

If not set, the failure policy defaults to Fail.

Info

FailurePolicy does not define how validations that evaluate to false are handled.

"},{"location":"policies/failure-policy/#fail","title":"Fail","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the request will be denied\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"policies/failure-policy/#ignore","title":"Ignore","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the failure will be ignored and the request will be allowed\n  failurePolicy: Ignore\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"policies/match-conditions/","title":"Match conditions","text":"

You can define match conditions if you need fine-grained request filtering.

Match conditions are CEL expressions. All match conditions must evaluate to true for the request to be evaluated.

Info

Match conditions have access to the same CEL variables as validation expressions.

"},{"location":"policies/match-conditions/#example","title":"Example","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  matchConditions:\n  - name: has-header\n    expression: object.attributes.request.http.headers[?\"x-force-deny\"].hasValue()\n  deny:\n  - response: >\n      envoy.Denied(403).Response()\n

In the policy above, the matchConditions will be used to deny all requests having the x-force-deny header.

"},{"location":"policies/match-conditions/#error-handling","title":"Error handling","text":"

In the event of an error evaluating a match condition the policy is not evaluated. Whether to reject the request is determined as follows:

  1. If any match condition evaluated to false (regardless of other errors), then the policy is skipped.
  2. Otherwise:
    • for failurePolicy: Fail, reject the request (without evaluating the policy).
    • for failurePolicy: Ignore, proceed with the request but skip the policy.
"},{"location":"policies/variables/","title":"Variables","text":"

A Kyverno AuthorizationPolicy can define variables that will be made available to all authorization rules.

Variables can be used in composition of other expressions. Each variable is defined as a named CEL expression. The will be available under variables in other expressions 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.

Info

The incoming CheckRequest from Envoy is made available to the policy under the object identifier.

"},{"location":"policies/variables/#variables_1","title":"Variables","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n    # `force_authorized` references the 'x-force-authorized' header\n    # from the envoy check request (or '' if not present)\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n    # `allowed` will be `true` if `variables.force_authorized` has the\n    # value 'enabled' or 'true'\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n    # make an authorisation decision based on the value of `variables.allowed`\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"quick-start/","title":"Quick start","text":"

The Kyverno Envoy Plugin is a powerful tool that integrates with the Envoy proxy.

It allows you to enforce Kyverno policies on incoming and outgoing traffic in a service mesh environment, providing an additional layer of security and control over your applications.

"},{"location":"quick-start/#overview","title":"Overview","text":"

Envoy is a Layer 7 proxy and communication bus tailored for large-scale, modern service-oriented architectures. Starting from version 1.7.0, Envoy includes an External Authorization filter that interfaces with an authorization service to determine the legitimacy of incoming requests.

This functionality allows authorization decisions to be offloaded to an external service, which can access the request context. The request context includes details such as the origin and destination of the network activity, as well as specifics of the network request (e.g., HTTP request). This information enables the external service to make a well-informed decision regarding the authorization of the incoming request processed by Envoy.

"},{"location":"quick-start/#what-is-the-kyverno-envoy-plugin","title":"What is the Kyverno Envoy Plugin?","text":"

The Kyverno Envoy Plugin is gRPC server that implements Envoy External Authorization API.

This allows you to enforce Kyverno policies on incoming and outgoing traffic in a service mesh environment, providing an additional layer of security and control over your applications. You can use this version of Kyverno to enforce fine-grained, context-aware access control policies with Envoy without modifying your microservice.

"},{"location":"quick-start/#how-does-this-work","title":"How does this work?","text":"

In addition to the Envoy sidecar, your application pods will include a Kyverno Authz Server component, either as a sidecar or as a separate pod. When Envoy receives an API request intended for your microservice, it consults the Kyverno Authz Server to determine whether the request should be permitted or not.

Performing policy evaluations locally with Envoy is advantageous, as it eliminates the need for an additional network hop for authorization checks, thus enhancing both performance and availability.

Info

The Kyverno Envoy Plugin is frequently deployed in Kubernetes environments as a sidecar container or as a separate pod. Additionally, it can be used in other environments as a standalone process running alongside Envoy.

"},{"location":"quick-start/#additional-resources","title":"Additional Resources","text":"

See the following pages on envoyproxy.io for more information on external authorization:

"},{"location":"quick-start/authz-server/","title":"Authz server","text":""},{"location":"quick-start/authz-server/#setup","title":"Setup","text":"

In this quick start guide we will deploy the Kyverno Authz Server inside a cluster.

Then you will interface Istio, an open source service mesh with the Kyverno Authz Server to delegate the request authorisation based on policies installed in the cluster.

"},{"location":"quick-start/authz-server/#prerequisites","title":"Prerequisites","text":""},{"location":"quick-start/authz-server/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"quick-start/authz-server/#configure-the-mesh","title":"Configure the mesh","text":"

We need to register the Kyverno Authz Server with Istio.

# configure the mesh\nistioctl install -y -f - <<EOF\napiVersion: install.istio.io/v1alpha1\nkind: IstioOperator\nspec:\n  meshConfig:\n    accessLogFile: /dev/stdout\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\nEOF\n

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

[...]\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\n[...]\n
"},{"location":"quick-start/authz-server/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

The first step is to deploy the Kyverno Authz Server.

# create the kyverno namespace\nkubectl create ns kyverno\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace kyverno istio-injection=enabled\n\n# deploy the kyverno authz server\nhelm install kyverno-authz-server --namespace kyverno --wait  \\\n  --repo https://kyverno.github.io/kyverno-envoy-plugin       \\\n  kyverno-authz-server\n
"},{"location":"quick-start/authz-server/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace demo istio-injection=enabled\n\n# deploy the httpbin application\nkubectl apply -n demo -f \\\n  https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml\n
"},{"location":"quick-start/authz-server/#deploy-an-istio-authorizationpolicy","title":"Deploy an Istio AuthorizationPolicy","text":"

An AuthorizationPolicy is the custom Istio resource that defines the services that will be protected by the Kyverno Authz Server.

# deploy istio authorization policy\nkubectl apply -f - <<EOF\napiVersion: security.istio.io/v1\nkind: AuthorizationPolicy\nmetadata:\n  name: kyverno-authz-server\n  namespace: demo\nspec:\n  action: CUSTOM\n  provider:\n    name: kyverno-authz-server.local\n  rules:\n  - {} # empty rules, it will apply to all requests\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server extensionProvider you set in the Istio configuration:

[...]\n  provider:\n    name: kyverno-authz-server.local\n[...]\n
"},{"location":"quick-start/authz-server/#deploy-a-kyverno-authorizationpolicy","title":"Deploy a Kyverno AuthorizationPolicy","text":"

A Kyverno AuthorizationPolicy defines the rules used by the Kyverno authz server to make a decision based on a given Envoy CheckRequest.

It uses the CEL language to analyse the incoming CheckRequest and is expected to produce an OkResponse or DeniedResponse in return.

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\nEOF\n

This simple policy will deny requests if they don't contain the header x-force-authorized with the value enabled or true.

"},{"location":"quick-start/authz-server/#testing","title":"Testing","text":"

At this we have deployed and configured Istio, the Kyverno Authz Server, a sample application, and the authorization policies.

"},{"location":"quick-start/authz-server/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"quick-start/authz-server/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"quick-start/authz-server/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send requests to the sample application and verify the result.

The following request will return 403 (denied by our policy):

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get\n

The following request will return 200 (allowed by our policy):

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"x-force-authorized: true\"\n
"},{"location":"quick-start/authz-server/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the quick start guide!

This tutorial demonstrated how to configure Istio\u2019s EnvoyFilter to utilize the Kyverno Authz Server as an external authorization service.

"},{"location":"quick-start/next-steps/","title":"Next steps","text":"

We covered the main components of the Kyverno Envoy Plugin.

Tip

If there's anything you would like to be improved, please reach out, we will be happy to discuss and improve as much as we can.

To continue exploring and learn more about the Kyverno Envoy Plugin:

"},{"location":"quick-start/sidecar-injector/","title":"Sidecar injector","text":"

This is not ready yet, hopefully it will be available soon!

"},{"location":"reference/","title":"Reference documentation","text":"

Info

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

"},{"location":"reference/json-schemas/","title":"JSON schemas","text":"

JSON schemas for the Kyverno Envoy Plugin are available:

They can be used to enable validation and autocompletion in your IDE.

"},{"location":"reference/json-schemas/#vs-code","title":"VS code","text":"

In VS code, simply add a comment on top of your YAML resources.

"},{"location":"reference/json-schemas/#authorizationpolicy","title":"AuthorizationPolicy","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/kyverno-envoy-plugin/main/.schemas/json/authorizationpolicy-envoy-v1alpha1.json\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: force_unauthenticated\n    expression: object.attributes.request.http.headers[?\"x-force-unauthenticated\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: metadata\n    expression: '{\"my-new-metadata\": \"my-new-value\"}'\n  deny:\n    # if force_unauthenticated -> 401\n  - match: >\n      variables.force_unauthenticated\n    response: >\n      envoy\n        .Denied(401)\n        .WithBody(\"Authentication Failed\")\n        .Response()\n        .WithMetadata(variables.metadata)\n    # if not force_authorized -> 403\n  - match: >\n      !variables.force_authorized\n    response: >\n      envoy\n        .Denied(403)\n        .WithBody(\"Unauthorized Request\")\n        .Response()\n  allow:\n    # else -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\n        .WithMetadata(variables.metadata)\n
"},{"location":"reference/apis/policy.v1alpha1/","title":"policy (v1alpha1)","text":""},{"location":"reference/apis/policy.v1alpha1/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-AuthorizationPolicy","title":"AuthorizationPolicy","text":"

AuthorizationPolicy defines an authorization policy resource

Field Type Required Inline Description apiVersion string envoy.kyverno.io/v1alpha1 kind string AuthorizationPolicy metadata meta/v1.ObjectMeta No description provided. spec AuthorizationPolicySpec No description provided."},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-Authorization","title":"Authorization","text":"

Appears in:

Authorization defines an authorization policy rule

Field Type Required Inline Description match string

Match represents the match condition which will be evaluated by CEL. Must evaluate to bool.

response string

Response represents the response 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).

"},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec","title":"AuthorizationPolicySpec","text":"

Appears in:

AuthorizationPolicySpec defines the spec of an authorization policy

Field Type Required Inline Description failurePolicy admissionregistration/v1.FailurePolicyType

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.

matchConditions []admissionregistration/v1.MatchCondition

MatchConditions is a list of conditions that must be met for a request to be validated. An empty list of matchConditions matches all requests. The exact matching logic is (in order): 1. If ANY matchCondition evaluates to FALSE, the policy is skipped. 2. If ALL matchConditions evaluate to TRUE, the policy is evaluated. 3. If any matchCondition evaluates to an error (but none are FALSE): - If failurePolicy=Fail, reject the request - If failurePolicy=Ignore, the policy is skipped

variables []admissionregistration/v1.Variable

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.

deny []Authorization

Deny contain CEL expressions which is used to deny a request.

allow []Authorization

Allow contain CEL expressions which is used to allow a request.

"},{"location":"tutorials/","title":"Tutorials","text":"

If you didn't read the Quick start section yet, we really recommend giving it a try to discover and familiarise with the Kyverno Envoy Plugin components first.

"},{"location":"tutorials/envoy-gateway/","title":"Envoy Gateway","text":"

Envoy Gateway is an open source project for managing Envoy Proxy as a standalone or Kubernetes-based application gateway. Gateway API resources are used to dynamically provision and configure the managed Envoy Proxies.

This tutorial shows how Envoy Gateway can be configured to delegate authorization decisions to the Kyverno Authz Server.

"},{"location":"tutorials/envoy-gateway/#setup","title":"Setup","text":""},{"location":"tutorials/envoy-gateway/#prerequisites","title":"Prerequisites","text":""},{"location":"tutorials/envoy-gateway/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"tutorials/envoy-gateway/#install-envoy-gateway","title":"Install Envoy Gateway","text":"

First we need to install Envoy Gateway in the cluster.

# install envoy gateway\nhelm install envoy-gateway -n envoy-gateway-system --create-namespace --wait --version v1.2.2 oci://docker.io/envoyproxy/gateway-helm\n
"},{"location":"tutorials/envoy-gateway/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# deploy the httpbin application\nkubectl apply -n demo -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml\n
"},{"location":"tutorials/envoy-gateway/#create-a-gatewayclass-and-a-gateway","title":"Create a GatewayClass and a Gateway","text":"

With Envoy Gateway installed we can now create a Gateway. To do so we will also create a dedicated GatewayClass.

Depending on your setup you will potentially need to create an EnvoyProxy resource to customize the way Envoy Gateway will create the underlying Service. The script below creates one to set the name and type of the service because the kind cluster created in the first step doesn't come with load balancer support.

# create a gateway\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.envoyproxy.io/v1alpha1\nkind: EnvoyProxy\nmetadata:\n  name: demo\nspec:\n  provider:\n    type: Kubernetes\n    kubernetes:\n      envoyService:\n        name: internet   # use a known name for the created service\n        type: ClusterIP  # because a kind cluster has no support for LB\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: GatewayClass\nmetadata:\n  name: demo\nspec:\n  controllerName: gateway.envoyproxy.io/gatewayclass-controller\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: Gateway\nmetadata:\n  name: demo\nspec:\n  gatewayClassName: demo\n  infrastructure:\n    parametersRef:\n      group: gateway.envoyproxy.io\n      kind: EnvoyProxy\n      name: demo\n  listeners:\n  - name: http\n    protocol: HTTP\n    port: 80\nEOF\n
"},{"location":"tutorials/envoy-gateway/#create-an-httproute-to-the-sample-application","title":"Create an HTTPRoute to the sample application","text":"

Next, we need to link the Gateway to our sample applicate with an HTTPRoute.

# create an http route to the sample app\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.networking.k8s.io/v1\nkind: HTTPRoute\nmetadata:\n  name: demo\nspec:\n  parentRefs:\n  - name: demo\n  rules:\n  - matches:\n    - path:\n        type: PathPrefix\n        value: /\n    backendRefs:\n    - group: ''\n      kind: Service\n      name: httpbin\n      port: 8000\n      weight: 1\nEOF\n
"},{"location":"tutorials/envoy-gateway/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

Now deploy the Kyverno Authz Server.

# deploy the kyverno authz server\nhelm install kyverno-authz-server --namespace kyverno --create-namespace --wait --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server\n
"},{"location":"tutorials/envoy-gateway/#create-a-kyverno-authorizationpolicy","title":"Create a Kyverno AuthorizationPolicy","text":"

In summary the policy below does the following:

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: authorization\n    expression: object.attributes.request.http.headers[?\"authorization\"].orValue(\"\").split(\" \")\n  - name: token\n    expression: >\n      size(variables.authorization) == 2 && variables.authorization[0].lowerAscii() == \"bearer\"\n        ? jwt.Decode(variables.authorization[1], \"secret\")\n        : null\n  deny:\n    # request not authenticated -> 401\n  - match: >\n      variables.token == null || !variables.token.Valid\n    response: >\n      envoy.Denied(401).Response()\n    # request authenticated but not admin role -> 403\n  - match: >\n      variables.token.Claims.?role.orValue(\"\") != \"admin\"\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n    # request authenticated and admin role -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\nEOF\n
"},{"location":"tutorials/envoy-gateway/#deploy-an-envoy-gateway-securitypolicy","title":"Deploy an Envoy Gateway SecurityPolicy","text":"

A SecurityPolicy is the custom Envoy Gateway resource to configure underlying Envoy Proxy to use an external auth server (the Kyverno Authz Server we installed in a prior step).

# deploy envoy gateway security policy\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.envoyproxy.io/v1alpha1\nkind: SecurityPolicy\nmetadata:\n  name: demo\nspec:\n  targetRefs:\n  - group: gateway.networking.k8s.io\n    kind: HTTPRoute\n    name: demo\n  extAuth:\n    grpc:\n      backendRef:\n        group: ''\n        kind: Service\n        name: kyverno-authz-server\n        namespace: kyverno\n        port: 9081\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server service as the GRPC backend:

[...]\n  extAuth:\n    grpc:\n      backendRef:\n        group: ''\n        kind: Service\n        name: kyverno-authz-server\n        namespace: kyverno\n        port: 9081\n[...]\n

Also notice that the security policy applies to the demo HTTPRoute:

[...]\n  targetRefs:\n    - group: gateway.networking.k8s.io\n      kind: HTTPRoute\n      name: demo\n[...]\n
"},{"location":"tutorials/envoy-gateway/#grant-access-to-the-kyverno-authz-server-service","title":"Grant access to the Kyverno Authz Server service","text":"

Last thing we need to configure is to grant access to the Kyverno Authz Server service for our SecurityPolicy to take effect.

# grant access\nkubectl apply -n kyverno -f - <<EOF\napiVersion: gateway.networking.k8s.io/v1beta1\nkind: ReferenceGrant\nmetadata:\n  name: demo\nspec:\n  from:\n  - group: gateway.envoyproxy.io\n    kind: SecurityPolicy\n    namespace: demo\n  to:\n  - group: ''\n    kind: Service\nEOF\n
"},{"location":"tutorials/envoy-gateway/#testing","title":"Testing","text":"

At this we have deployed and configured Envoy Gateway, the Kyverno Authz Server, a sample application, and the authorization and security policies.

"},{"location":"tutorials/envoy-gateway/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"tutorials/envoy-gateway/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"tutorials/envoy-gateway/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send request to the sample application and verify the result.

For convenience, we will store Alice\u2019s and Bob\u2019s tokens in environment variables.

Here Bob is assigned the admin role and Alice is assigned the guest role.

export ALICE_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk\"\nexport BOB_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6ImFkbWluIiwic3ViIjoiWVd4cFkyVT0ifQ.veMeVDYlulTdieeX-jxFZ_tCmqQ_K8rwx2OktUHv5Z0\"\n

Calling without a JWT token will return 401:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get\n

Calling with Alice\u2019s JWT token will return 403:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get -H \"authorization: Bearer $ALICE_TOKEN\"\n

Calling with Bob\u2019s JWT token will return 200:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get -H \"authorization: Bearer $BOB_TOKEN\"\n
"},{"location":"tutorials/envoy-gateway/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the tutorial!

This tutorial demonstrated how to configure Envoy Gateway to utilize the Kyverno Authz Server as an external authorization service.

Additionally, the tutorial provided an example policy to decode a JWT token and make a decision based on it.

"},{"location":"tutorials/istio/","title":"Istio","text":"

Istio is an open source service mesh for managing the different microservices that make up a cloud-native application. Istio provides a mechanism to use a service as an external authorizer with the AuthorizationPolicy API.

This tutorial shows how Istio\u2019s AuthorizationPolicy can be configured to delegate authorization decisions to the Kyverno Authz Server.

"},{"location":"tutorials/istio/#setup","title":"Setup","text":""},{"location":"tutorials/istio/#prerequisites","title":"Prerequisites","text":""},{"location":"tutorials/istio/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"tutorials/istio/#configure-the-mesh","title":"Configure the mesh","text":"

We need to register the Kyverno Authz Server with Istio.

# configure the mesh\nistioctl install -y -f - <<EOF\napiVersion: install.istio.io/v1alpha1\nkind: IstioOperator\nspec:\n  meshConfig:\n    accessLogFile: /dev/stdout\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\nEOF\n

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

[...]\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\n[...]\n
"},{"location":"tutorials/istio/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

The first step is to deploy the Kyverno Authz Server.

# create the kyverno namespace\nkubectl create ns kyverno\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace kyverno istio-injection=enabled\n\n# deploy the kyverno authz server\nhelm install kyverno-authz-server --namespace kyverno --wait --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server\n
"},{"location":"tutorials/istio/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace demo istio-injection=enabled\n\n# deploy the httpbin application\nkubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml -n demo\n
"},{"location":"tutorials/istio/#deploy-an-istio-authorizationpolicy","title":"Deploy an Istio AuthorizationPolicy","text":"

An AuthorizationPolicy is the custom Istio resource that defines the services that will be protected by the Kyverno Authz Server.

# deploy istio authorization policy\nkubectl apply -f - <<EOF\napiVersion: security.istio.io/v1\nkind: AuthorizationPolicy\nmetadata:\n  name: kyverno-authz-server\n  namespace: demo\nspec:\n  action: CUSTOM\n  provider:\n    name: kyverno-authz-server.local\n  rules:\n  - {} # empty rules, it will apply to all requests\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server extensionProvider you set in the Istio configuration:

[...]\n  provider:\n    name: kyverno-authz-server.local\n[...]\n
"},{"location":"tutorials/istio/#create-a-kyverno-authorizationpolicy","title":"Create a Kyverno AuthorizationPolicy","text":"

In summary the policy below does the following:

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: authorization\n    expression: object.attributes.request.http.headers[?\"authorization\"].orValue(\"\").split(\" \")\n  - name: token\n    expression: >\n      size(variables.authorization) == 2 && variables.authorization[0].lowerAscii() == \"bearer\"\n        ? jwt.Decode(variables.authorization[1], \"secret\")\n        : null\n  deny:\n    # request not authenticated -> 401\n  - match: >\n      variables.token == null || !variables.token.Valid\n    response: >\n      envoy.Denied(401).Response()\n    # request authenticated but not admin role -> 403\n  - match: >\n      variables.token.Claims.?role.orValue(\"\") != \"admin\"\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n    # request authenticated and admin role -> 200\n  - response: >\n      envoy.Allowed().Response()\nEOF\n
"},{"location":"tutorials/istio/#testing","title":"Testing","text":"

At this we have deployed and configured Istio, the Kyverno Authz Server, a sample application, and the authorization policies.

"},{"location":"tutorials/istio/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"tutorials/istio/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"tutorials/istio/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send request to the sample application and verify the result.

For convenience, we will store Alice\u2019s and Bob\u2019s tokens in environment variables.

Here Bob is assigned the admin role and Alice is assigned the guest role.

export ALICE_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk\"\nexport BOB_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6ImFkbWluIiwic3ViIjoiWVd4cFkyVT0ifQ.veMeVDYlulTdieeX-jxFZ_tCmqQ_K8rwx2OktUHv5Z0\"\n

Calling without a JWT token will return 401:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get\n

Calling with Alice\u2019s JWT token will return 403:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"authorization: Bearer $ALICE_TOKEN\"\n

Calling with Bob\u2019s JWT token will return 200:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"authorization: Bearer $BOB_TOKEN\"\n
"},{"location":"tutorials/istio/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the tutorial!

This tutorial demonstrated how to configure Istio\u2019s EnvoyFilter to utilize the Kyverno Authz Server as an external authorization service.

Additionally, the tutorial provided an example policy to decode a JWT token and make a decision based on it.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"cel-extensions/","title":"CEL extensions","text":"

The CEL engine used to evaluate variables and authorization rules has been extended with libraries to help processing the input CheckRequest and forge the corresponding OkResponse and/or DeniedResponse.

"},{"location":"cel-extensions/#envoy-plugin-libraries","title":"Envoy plugin libraries","text":""},{"location":"cel-extensions/#common-libraries","title":"Common libraries","text":"

The libraries below are common CEL extensions enabled in the Kyverno Authz Server CEL engine:

"},{"location":"cel-extensions/#kubernetes-libraries","title":"Kubernetes libraries","text":"

The libraries below are imported from Kubernetes:

"},{"location":"cel-extensions/envoy/","title":"Envoy library","text":"

The envoy library adds some types and function to simplify the creation of OkResponse and DeniedResponse objects.

"},{"location":"cel-extensions/envoy/#types","title":"Types","text":""},{"location":"cel-extensions/envoy/#checkrequest","title":"<CheckRequest>","text":"

CEL Type / Proto: envoy.service.auth.v3.CheckRequest

"},{"location":"cel-extensions/envoy/#okresponse","title":"<OkResponse>","text":"

CEL Type / Proto: envoy.OkResponse

Field CEL Type / Proto Docs status google.rpc.Status Docs http_response envoy.service.auth.v3.OkHttpResponse Docs dynamic_metadata google.protobuf.Struct Docs"},{"location":"cel-extensions/envoy/#deniedresponse","title":"<DeniedResponse>","text":"

CEL Type / Proto: envoy.DeniedResponse

Field CEL Type / Proto Docs status google.rpc.Status Docs http_response envoy.service.auth.v3.DeniedHttpResponse Docs dynamic_metadata google.protobuf.Struct Docs"},{"location":"cel-extensions/envoy/#okhttpresponse","title":"<OkHttpResponse>","text":"

CEL Type / Proto: envoy.service.auth.v3.OkHttpResponse

"},{"location":"cel-extensions/envoy/#deniedhttpresponse","title":"<DeniedHttpResponse>","text":"

CEL Type / Proto: envoy.service.auth.v3.DeniedHttpResponse

"},{"location":"cel-extensions/envoy/#metadata","title":"<Metadata>","text":"

CEL Type / Proto: google.protobuf.Struct

"},{"location":"cel-extensions/envoy/#headervalueoption","title":"<HeaderValueOption>","text":"

CEL Type / Proto: envoy.config.core.v3.HeaderValueOption

"},{"location":"cel-extensions/envoy/#queryparameter","title":"<QueryParameter>","text":"

CEL Type / Proto: envoy.config.core.v3.QueryParameter

"},{"location":"cel-extensions/envoy/#status","title":"<Status>","text":"

CEL Type / Proto: google.rpc.Status

"},{"location":"cel-extensions/envoy/#functions","title":"Functions","text":""},{"location":"cel-extensions/envoy/#envoyallowed","title":"envoy.Allowed","text":"

This function creates an <OkHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads","title":"Signature and overloads","text":"
envoy.Allowed() -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example","title":"Example","text":"
envoy.Allowed()\n
"},{"location":"cel-extensions/envoy/#envoydenied","title":"envoy.Denied","text":"

This function creates a <DeniedHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_1","title":"Signature and overloads","text":"
envoy.Denied(<int> code) -> <DeniedHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_1","title":"Example","text":"
envoy.Denied(401)\n
"},{"location":"cel-extensions/envoy/#envoyheader","title":"envoy.Header","text":"

This function creates an <HeaderValueOption> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_2","title":"Signature and overloads","text":"
envoy.Header(<string> key, <string> value) -> <HeaderValueOption>\n
"},{"location":"cel-extensions/envoy/#example_2","title":"Example","text":"
envoy.Header(\"foo\", \"bar\")\n
"},{"location":"cel-extensions/envoy/#envoyqueryparam","title":"envoy.QueryParam","text":"

This function creates a <QueryParameter> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_3","title":"Signature and overloads","text":"
envoy.QueryParam(<string> key, <string> value) -> <QueryParameter>\n
"},{"location":"cel-extensions/envoy/#example_3","title":"Example","text":"
envoy.QueryParam(\"foo\", \"bar\")\n
"},{"location":"cel-extensions/envoy/#withbody","title":"WithBody","text":"

This function sets the body of a <DeniedHttpResponse> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_4","title":"Signature and overloads","text":"
<DeniedHttpResponse>.WithBody(<string> body) -> <DeniedHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_4","title":"Example","text":"
envoy.Denied(401).WithBody(\"Unauthorized Request\")\n
"},{"location":"cel-extensions/envoy/#withheader","title":"WithHeader","text":"

This function adds a <HeaderValueOption>:

"},{"location":"cel-extensions/envoy/#signature-and-overloads_5","title":"Signature and overloads","text":"

<OkHttpResponse>.WithHeader(<HeaderValueOption> header) -> <OkHttpResponse>\n
<OkHttpResponse>.WithHeader(<string> key, <string> value) -> <OkHttpResponse>\n
<DeniedHttpResponse>.WithHeader(<HeaderValueOption> header) -> <DeniedHttpResponse>\n
<DeniedHttpResponse>.WithHeader(<string> key, <string> value) -> <DeniedHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_5","title":"Example","text":"

envoy.Allowed().WithHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Allowed().WithHeader(\"foo\", \"bar\")\n
envoy.Denied(401).WithHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Denied(401).WithHeader(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withoutheader","title":"WithoutHeader","text":"

This function marks a header to be removed when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_6","title":"Signature and overloads","text":"
<OkHttpResponse>.WithoutHeader(<string> header) -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_6","title":"Example","text":"
envoy.Allowed().WithoutHeader(\"foo\")\n
"},{"location":"cel-extensions/envoy/#withresponseheader","title":"WithResponseHeader","text":"

This function adds a <HeaderValueOption> when the response is sent downstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_7","title":"Signature and overloads","text":"

<OkHttpResponse>.WithResponseHeader(<HeaderValueOption> header) -> <OkHttpResponse>\n
<OkHttpResponse>.WithResponseHeader(<string> key, <string> value) -> <OkHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_7","title":"Example","text":"

envoy.Allowed().WithResponseHeader(envoy.Header(\"foo\", \"bar\"))\n
envoy.Allowed().WithResponseHeader(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withqueryparam","title":"WithQueryParam","text":"

This function adds a <QueryParameter> to be added when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_8","title":"Signature and overloads","text":"

<OkHttpResponse>.WithQueryParam(<QueryParameter> param) -> <OkHttpResponse>\n
<OkHttpResponse>.WithQueryParam(<string> key, <string> value) -> <OkHttpResponse>\n

"},{"location":"cel-extensions/envoy/#example_8","title":"Example","text":"

envoy.Allowed().WithQueryParam(envoy.QueryParam(\"foo\", \"bar\"))\n
envoy.Allowed().WithQueryParam(\"foo\", \"bar\")\n

"},{"location":"cel-extensions/envoy/#withoutqueryparam","title":"WithoutQueryParam","text":"

This function marks a query parameter to be removed when the request is sent upstream by Envoy.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_9","title":"Signature and overloads","text":"
<OkHttpResponse>.WithoutQueryParam(<string> param) -> <OkHttpResponse>\n
"},{"location":"cel-extensions/envoy/#example_9","title":"Example","text":"
envoy.Allowed().WithoutQueryParam(\"foo\")\n
"},{"location":"cel-extensions/envoy/#keepemptyvalue","title":"KeepEmptyValue","text":"

This function sets the keep_empty_value field of an <HeaderValueOption> object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_10","title":"Signature and overloads","text":"

<HeaderValueOption>.KeepEmptyValue() -> <HeaderValueOption>\n
<HeaderValueOption>.KeepEmptyValue(<bool> keep) -> <HeaderValueOption>\n

"},{"location":"cel-extensions/envoy/#example_10","title":"Example","text":"

envoy.Header(\"foo\", \"bar\").KeepEmptyValue()\n
envoy.Header(\"foo\", \"bar\").KeepEmptyValue(true)\n

"},{"location":"cel-extensions/envoy/#response","title":"Response","text":"

This function creates a <OkResponse> / DeniedResponse object from an <OkHttpResponse> / <DeniedHttpResponse>.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_11","title":"Signature and overloads","text":"

<OkHttpResponse>.Response() -> <OkResponse>\n
<DeniedHttpResponse>.Response() -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_11","title":"Example","text":"

envoy.Allowed().Response()\n
envoy.Denied(401).Response()\n

"},{"location":"cel-extensions/envoy/#withmessage","title":"WithMessage","text":"

This function sets the status.message field of an <OkResponse> / DeniedResponse object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_12","title":"Signature and overloads","text":"

<OkResponse>.WithMessage(<string> message) -> <OkResponse>\n
<DeniedResponse>.WithMessage(<string> message) -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_12","title":"Example","text":"

envoy.Allowed().Response().WithMessage(\"hello world!\")\n
envoy.Denied(401).Response().WithMessage(\"hello world!\")\n

"},{"location":"cel-extensions/envoy/#withmetadata","title":"WithMetadata","text":"

This function sets the dynamic_metadata field of an <OkResponse> / DeniedResponse object.

"},{"location":"cel-extensions/envoy/#signature-and-overloads_13","title":"Signature and overloads","text":"

<OkResponse>.WithMetadata(<Metadata> metadata) -> <OkResponse>\n
<DeniedResponse>.WithMetadata(<Metadata> metadata) -> <DeniedResponse>\n

"},{"location":"cel-extensions/envoy/#example_13","title":"Example","text":"

envoy.Allowed().Response().WithMetadata({ \"foo\": \"bar\" })\n
envoy.Denied(401).Response().WithMetadata({ \"foo\": \"bar\" })\n

"},{"location":"cel-extensions/jwt/","title":"Jwt library","text":"

Policies have native functionality to decode and verify the contents of JWT tokens in order to enforce additional authorization logic on requests.

"},{"location":"cel-extensions/jwt/#types","title":"Types","text":""},{"location":"cel-extensions/jwt/#token","title":"<Token>","text":"

CEL Type / Proto jwt.Token

Field CEL Type / Proto Docs Valid bool Header google.protobuf.Struct Docs Claims google.protobuf.Struct Docs"},{"location":"cel-extensions/jwt/#functions","title":"Functions","text":""},{"location":"cel-extensions/jwt/#jwtdecode","title":"jwt.Decode","text":"

The jwt.Decode function decodes and validates a JWT token. It accepts two arguments: the token and the secret to verify the signature.

"},{"location":"cel-extensions/jwt/#signature-and-overloads","title":"Signature and overloads","text":"
jwt.Decode(<string> token, <string> key) -> <Token>\n
"},{"location":"cel-extensions/jwt/#example","title":"Example","text":"
jwt.Decode(\"eyJhbGciOiJIUzI1NiI....\", \"secret\")\n
"},{"location":"community/","title":"Community","text":"

The Kyverno Envoy Plugin has a growing community and we would definitely love to see you join and contribute.

Everyone is welcome to make suggestions, report bugs, open feature requests, contribute code or docs, participate in discussions, write blogs or anything that can benefit the project.

The Kyverno Envoy Plugin is built and maintained under the Kyverno umbrella but decisions are Community driven Everyone's voice matters

"},{"location":"community/#slack-channel","title":"Slack channel","text":"

Join our slack channel #kyverno to meet with users, contributors and maintainers.

"},{"location":"community/#roadmap","title":"RoadMap","text":"

For detailed information on our planned features and upcoming updates, please view our Roadmap.

"},{"location":"community/#contributing","title":"Contributing","text":"

Please read the contributing guide for details around:

  1. Code of Conduct
  2. Code Culture
  3. Details on how to contribute
"},{"location":"community/#adopters","title":"Adopters","text":"

If you are using the Kyverno Envoy Plugin and want to share it publicly we always appreciate a bit of support. Pull requests to the ADOPTERS LIST will put a smile on our faces

"},{"location":"community/contribute/","title":"Contributing","text":"

Kyverno Envoy Plugin, developed by Kyverno, is an advanced end-to-end testing tool for Kubernetes. Our community plays a crucial role in shaping the project by reporting bugs, suggesting features, and improving documentation.

We aim to make our issue tracker, discussion board, and documentation well-structured and easy to navigate. By following our guidelines, you can help us address your requests efficiently.

"},{"location":"community/contribute/#how-you-can-contribute","title":"How you can contribute","text":"

We appreciate your efforts in reporting bugs, requesting features, and engaging in discussions. Here's how you can contribute:

"},{"location":"community/contribute/#creating-an-issue","title":"Creating an issue","text":""},{"location":"community/contribute/#contributing_1","title":"Contributing","text":""},{"location":"community/contribute/#checklist","title":"Checklist","text":"

Before interacting within the project, please consider the following questions to ensure you're using the correct issue template and providing all necessary information.

Issues, discussions, and comments are forever

Please note that everything you write is permanent and will remain for everyone to read \u2013 forever. Therefore, please always be nice and constructive, follow our contribution guidelines, and comply with our Code of Conduct.

"},{"location":"community/contribute/#before-creating-an-issue","title":"Before creating an issue","text":""},{"location":"community/contribute/#before-asking-a-question","title":"Before asking a question","text":""},{"location":"community/contribute/#before-commenting","title":"Before commenting","text":""},{"location":"community/contribute/#rights-and-responsibilities","title":"Rights and responsibilities","text":"

As maintainers, we are entrusted with the responsibility to moderate communication within our community, including the authority to close, remove, reject, or edit issues, discussions, comments, commits, and to block users who do not align with our contribution guidelines and our Code of Conduct. This role requires us to be actively involved in maintaining the integrity and positive atmosphere of our community. Upholding these standards decisively ensures a respectful and inclusive environment for all members.

"},{"location":"community/contribute/#code-of-conduct","title":"Code of Conduct","text":"

Our Code of Conduct outlines the expectation for all community members to treat one another with respect, employing inclusive and welcoming language. Our commitment is to foster a positive and supportive environment, free of inappropriate, offensive, or harmful behavior.

We take any violations seriously and will take appropriate action in response to uphold these values.1

"},{"location":"community/contribute/#incomplete-issues-and-duplicates","title":"Incomplete issues and duplicates","text":"

We have invested significant time and effort in the setup of our contribution process, ensuring that we assess the essential requirements for reviewing and responding to issues effectively. Each field in our issue templates is thoughtfully designed to help us fully understand your concerns and the nature of your matter. We encourage all members to utilize the search function before submitting new issues or starting discussions to help avoid duplicates. Your cooperation is crucial in keeping our community's discussions constructive and organized.

  1. Warning and blocking policy: Given the increasing popularity of our project and our commitment to a healthy community, we've defined clear guidelines on how we proceed with violations:

    1.1. First warning: Users displaying repeated inappropriate, offensive, or harmful behavior will receive a first warning. This warning serves as a formal notice that their behavior is not in alignment with our community standards and Code of Conduct. The first warning is permanent.

    1.2. Second warning and opportunity for resolution: If the behavior persists, a second warning will be issued. Upon receiving the second warning, the user will be given a 5-day period for reflection, during which they are encouraged to publicly explain or apologize for their actions. This period is designed to offer an opportunity for openly clearing out any misunderstanding.

    1.3. Blocking: Should there be no response or improvement in behavior following the second warning, we reserve the right to block the user from the community and repository. Blocking is considered a last resort, used only when absolutely necessary to protect the community's integrity and positive atmosphere.

    Blocking has been an exceptionally rare necessity in our overwhelmingly positive community, highlighting our preference for constructive dialogue and mutual respect. It aims to protect our community members and team.\u00a0\u21a9

"},{"location":"community/making-a-pull-request/","title":"Pull Requests","text":"

You can contribute by making a pull request that will be reviewed by maintainers and integrated into the main repository when the changes made are approved. You can contribute bug fixes, documentation changes, or new functionalities.

Considering a pull request

Before deciding to spend effort on making changes and creating a pull request, please discuss what you intend to do. If you are responding to what you think might be a bug, please issue a bug report first. If you intend to work on documentation, create a documentation issue. If you want to work on a new feature, please create a change request.

Keep in mind the guidance given and let people advise you. It might be that there are easier solutions to the problem you perceive and want to address. It might be that what you want to achieve can already be done by configuration or [customization].

"},{"location":"community/making-a-pull-request/#learning-about-pull-requests","title":"Learning about pull requests","text":"

Pull requests are a concept layered on top of Git by services that provide Git hosting. Before you consider making a pull request, you should familiarize yourself with the documentation on GitHub, the service we are using. The following articles are of particular importance:

  1. Forking a repository
  2. Creating a pull request from a fork
  3. Creating a pull request

Note that they provide tailored documentation for different operating systems and different ways of interacting with GitHub. We do our best in the documentation here to describe the process as it applies but cannot cover all possible combinations of tools and ways of doing things. It is also important that you understand the concept of a pull-request in general before continuing.

"},{"location":"community/making-a-pull-request/#pull-request-process","title":"Pull request process","text":"

In the following, we describe the general process for making pull requests. The aim here is to provide the 30k ft overview before describing details later on.

"},{"location":"community/making-a-pull-request/#preparing-changes-and-draft-pr","title":"Preparing changes and draft PR","text":"

The diagram below describes what typically happens to repositories in the process or preparing a pull request. We will be discussing the review-revise process below. It is important that you understand the overall process first before you worry about specific commands. This is why we cover this first before providing instructions below.

sequenceDiagram\n  autonumber\n\n  participant upstream\n  participant PR\n  participant fork\n  participant local\n\n  upstream ->> fork: fork on GitHub\n  fork ->> local: clone to local\n  local ->> local: branch\n  loop prepare\n    loop push\n      loop edit\n        local ->> local: commit\n      end\n      local ->> fork: push\n    end\n    upstream ->> fork: merge in any changes\n    fork ->>+ PR: create draft PR\n    PR ->> PR: review your changes\n  end
  1. Fork the Repository: Fork the upstream repository on GitHub to create your own copy.
  2. Clone to Local: Clone your fork to your local machine.
  3. Create a Branch: Create a topic branch for your changes.
  4. Set Up Development Environment: Follow the instructions to set up a development environment.
  5. Iterate and Commit: Make incremental changes and commit them with meaningful messages.
  6. Push Regularly: Push your commits to your fork regularly.
  7. Merge Changes from Upstream: Regularly merge changes from the original upstream repository to avoid conflicts.
  8. Create a Draft Pull Request: Once satisfied with your changes, create a draft pull request for early feedback.
  9. Review and Revise: Review your work critically, address feedback, and refine your changes.
"},{"location":"community/making-a-pull-request/#finalizing","title":"Finalizing","text":"

Once you are happy with your changes, you can move to the next step, finalizing your pull request and asking for a more formal and detailed review. The diagram below shows the process:

sequenceDiagram\n  autonumber\n  participant upstream\n  participant PR\n  participant fork\n  participant local\n\n  activate PR\n  PR ->> PR: finalize PR\n  loop review\n    loop discuss\n      PR ->> PR: request review\n      PR ->> PR: discussion\n      local ->> fork: push further changes\n    end\n    PR ->> upstream: merge (and squash)\n    deactivate PR\n    fork ->> fork: delete branch\n    upstream ->> fork: pull\n    local ->> local: delete branch\n    fork ->> local: pull\n  end\n
  1. Finalize PR: Signal that your changes are ready for review.
  2. Request Review: Ask the maintainer to review your changes.
  3. Discuss and Revise: Engage in discussions, make necessary revisions, and iterate.
  4. Merge and Squash: Once approved, the maintainer will merge and possibly squash your commits.
  5. Clean Up: Delete the branch used for the PR from both your fork and local clone.
"},{"location":"community/reporting-a-bug/","title":"Bug Reports","text":"

If you think you have discovered a bug, you can help us by submitting an issue in our public issue tracker, following this guide.

"},{"location":"community/reporting-a-bug/#before-creating-an-issue","title":"Before Creating an Issue","text":"

With numerous users, issues are created regularly. The maintainers of this project strive to address bugs promptly. By following this guide, you will know exactly what information we need to help you quickly.

Please do the following before creating an issue:

"},{"location":"community/reporting-a-bug/#upgrade-to-latest-version","title":"Upgrade to Latest Version","text":"

Chances are that the bug you discovered was already fixed in a subsequent version. Before reporting an issue, ensure that you're running the latest version.

Bug fixes are not backported

Please understand that only bugs that occur in the latest version will be addressed. Also, to reduce duplicate efforts, fixes cannot always be backported to earlier versions.

"},{"location":"community/reporting-a-bug/#remove-customizations","title":"Remove Customizations","text":"

If you're using customizations like additional configurations, remove them before reporting a bug. We can't offer official support for bugs that might hide in your overrides, so make sure to omit custom settings from your configuration files.

Don't be shy to ask on our discussion board for help if you run into problems.

"},{"location":"community/reporting-a-bug/#search-for-solutions","title":"Search for Solutions","text":"

At this stage, we know that the problem persists in the latest version and is not caused by any of your customizations. However, the problem might result from a small typo or a syntactical error in a configuration file.

Before creating a bug report, save time for us and yourself by doing some research:

  1. Search our documentation for relevant sections related to your problem. Ensure everything is configured correctly.
  2. [Search our issue tracker] as another user might have already reported the same problem.
  3. [Search our discussion board] to see if other users are facing similar issues and find possible solutions.

Keep track of all search terms and relevant links; you'll need them in the bug report.

If you still haven't found a solution to your problem, create an issue. It's now likely that you've encountered something new. Read the following section to learn how to create a complete and helpful bug report.

"},{"location":"community/reporting-a-bug/#issue-template","title":"Issue Template","text":"

We have created a new issue template to make the bug reporting process as simple as possible and more efficient for our community and us. It consists of the following parts:

"},{"location":"community/reporting-a-bug/#title","title":"Title","text":"

A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug can be inferred from the title.

Example Clear apply command fails with specific CRD Wordy The apply command fails when used with a certain Custom Resource Definition Unclear Command does not work Useless Help"},{"location":"community/reporting-a-bug/#context","title":"Context optional","text":"

Before describing the bug, you can provide additional context to help us understand what you were trying to achieve. Explain the circumstances under which the bug happens, and what you think might be relevant. Don't describe the bug here.

"},{"location":"community/reporting-a-bug/#bug-description","title":"Bug Description","text":"

Provide a clear, focused, specific, and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported, and not to one of its dependencies. Follow these principles:

"},{"location":"community/reporting-a-bug/#related-links","title":"Related Links","text":"

Share links to relevant sections of our documentation and any related issues or discussions. This helps us improve our documentation and understand the problem better.

"},{"location":"community/reporting-a-bug/#reproduction","title":"Reproduction","text":"

A minimal reproduction is essential for a well-written bug report, as it allows us to recreate the conditions necessary to inspect the bug. Follow the guide to create a reproduction:

[ Create reproduction][Create reproduction]{ .md-button .md-button--primary }

After creating the reproduction, you should have a .zip file, ideally not larger than 1 MB. Drag and drop the .zip file into the issue field, which will automatically upload it to GitHub.

Don't share links to repositories

While linking to a repository is a common practice, we currently don't support this. The reproduction, created using the built-in info plugin, contains all necessary environment information.

"},{"location":"community/reporting-a-bug/#steps-to-reproduce","title":"Steps to Reproduce","text":"

List specific steps to follow when running your reproduction to observe the bug. Keep the steps concise and ensure nothing is left out. Use simple language and focus on continuity.

"},{"location":"community/reporting-a-bug/#browser","title":"Browser optional","text":"

If the bug only occurs in specific browsers, let us know which ones are affected. This field is optional, as it is only relevant for bugs that do not involve a crash when previewing or building your site.

Incognito Mode

Verify that the bug is not caused by a browser extension by switching to incognito mode. If the bug disappears, it is likely caused by an extension.

"},{"location":"community/reporting-a-bug/#checklist","title":"Checklist","text":"

Before submitting, ensure you have:

Thanks for following the guide and creating a high-quality bug report. We will take it from here.

"},{"location":"community/reporting-a-docs-issue/","title":"Documentation Issues","text":"

The documentation includes extensive information on features, configurations, customizations, and more. If you have found an inconsistency or see room for improvement, please follow this guide to submit an issue on our issue tracker.

"},{"location":"community/reporting-a-docs-issue/#issue-template","title":"Issue Template","text":"

Reporting a documentation issue is usually less involved than reporting a bug, as we don't need a [reproduction]. Please thoroughly read this guide before creating a new documentation issue, and provide the following information as part of the issue:

"},{"location":"community/reporting-a-docs-issue/#title","title":"Title","text":"

A good title should be a short, one-sentence description of the issue, containing all relevant information and keywords to simplify the search in our issue tracker.

Example Clear Clarify resource templating setup Unclear Missing information in the docs Useless Help"},{"location":"community/reporting-a-docs-issue/#description","title":"Description","text":"

Provide a clear and concise summary of the inconsistency or issue you encountered in the documentation or the documentation section that needs improvement. Explain why you think the documentation should be adjusted and describe the severity of the issue:

Why we need this: describing the problem clearly and concisely is a prerequisite for improving our documentation \u2013 we need to understand what's wrong so we can fix it.

"},{"location":"community/reporting-a-docs-issue/#related-links","title":"Related Links","text":"

After you describe the documentation section that needs to be adjusted, share the link to this specific documentation section and other possibly related sections. Use anchor links (permanent links) where possible, as it simplifies discovery.

Why we need this: providing the links to the documentation helps us understand which sections of our documentation need to be adjusted, extended, or overhauled.

"},{"location":"community/reporting-a-docs-issue/#proposed-change","title":"Proposed Change optional","text":"

Now that you have provided us with the description and links to the documentation sections, you can help us, maintainers, and the community by proposing an improvement. You can sketch out rough ideas or write a concrete proposal. This field is optional but very helpful.

Why we need this: an improvement proposal can be beneficial for other users who encounter the same issue, as they offer solutions before we maintainers can update the documentation.

"},{"location":"community/reporting-a-docs-issue/#checklist","title":"Checklist","text":"

Thanks for following the guide and providing valuable feedback for our documentation \u2013 you are almost done. The checklist ensures that you have read this guide and have worked to your best knowledge to provide us with every piece of information we need to improve it.

We'll take it from here.

"},{"location":"community/requesting-a-change/","title":"Change Requests","text":"

We value every idea or contribution from our community. Please follow this guide before submitting your change request in our public issue tracker. This helps us better understand the proposed change and how it will benefit our community.

"},{"location":"community/requesting-a-change/#before-creating-an-issue","title":"Before Creating an Issue","text":"

Before you invest time in submitting a change request, answer these questions to determine if your idea is a good fit and matches the project's philosophy and tone.

"},{"location":"community/requesting-a-change/#its-not-a-bug-its-a-feature","title":"It's Not a Bug, It's a Feature","text":"

Change requests suggest minor adjustments, new features, or influence the project's direction. They are not intended for reporting bugs. Refer to our bug reporting guide for that.

"},{"location":"community/requesting-a-change/#look-for-sources-of-inspiration","title":"Look for Sources of Inspiration","text":"

If your idea is implemented in another tool or framework, collect information on its implementation. This helps us evaluate its fit more quickly.

"},{"location":"community/requesting-a-change/#connect-with-our-community","title":"Connect with Our Community","text":"

Our discussion board is the best place to connect with our community. Seeking input from other users helps implement features that benefit a larger number of users.

Start a discussion

"},{"location":"community/requesting-a-change/#issue-template","title":"Issue Template","text":"

After doing the preliminary work, create a change request. Follow these steps:

"},{"location":"community/requesting-a-change/#title","title":"Title","text":"

A good title is short and descriptive, summarizing the idea so the potential impact and benefit can be inferred.

Example Clear Support for resource templating Wordy Add support for templating resources for easier testing Unclear Improve templating Useless Help"},{"location":"community/requesting-a-change/#context","title":"Context optional","text":"

Provide additional context to help us understand what you are trying to achieve. Explain the circumstances and relevant settings without describing the change request itself.

"},{"location":"community/requesting-a-change/#description","title":"Description","text":"

Provide a detailed and clear description of your idea. Explain why your idea is relevant and should be implemented here, not in one of its dependencies.

"},{"location":"community/requesting-a-change/#related-links","title":"Related Links","text":"

Provide any relevant links to issues, discussions, or documentation sections related to your change request. This helps us gain additional context.

"},{"location":"community/requesting-a-change/#use-cases","title":"Use Cases","text":"

Explain how your change request would work from an author's and user's perspective. What is the expected impact, and why does it benefit other users? Would it potentially break existing functionality?

"},{"location":"community/requesting-a-change/#visuals","title":"Visuals optional","text":"

If you have any visuals, such as sketches, screenshots, mockups, or external assets, present them in this section. If you have seen this change used in other tools, showcase and describe its implementation.

"},{"location":"community/requesting-a-change/#checklist","title":"Checklist","text":"

Thanks for following the guide and creating a high-quality change request. The checklist ensures that you have read this guide and provided all necessary information for us to review your idea.

We'll take it from here.

"},{"location":"community/requesting-a-change/#rejected-requests","title":"Rejected Requests","text":"

Your change request got rejected? We're sorry for that. We understand it can be frustrating, but we always need to consider the needs of our entire community. If you're unsure why your change request was rejected, please ask for clarification.

We consider the following principles when evaluating change requests:

If your idea was rejected, you can always implement it via [customization]. If you're unsure how or want to know if someone has already done it, get in touch with our community on the discussion board.

"},{"location":"performance/","title":"Performance","text":"

This page offers guidance and best practices for benchmarking the performance of the Kyverno Authz Server, helping users understand the associated overhead. It outlines an example setup for conducting benchmarks, various benchmarking scenarios, and key metrics to capture for assessing the impact of the Kyverno Authz Server.

"},{"location":"performance/#benchmark-setup","title":"Benchmark Setup","text":"

The benchmark setup consists of the following components:

"},{"location":"performance/#sample-application","title":"Sample Application","text":"

The first component is a simple Go application that provides information of books in the library books collection and exposes APIs to get, create and delete books collection. Check this out for more information about the Go test application .

"},{"location":"performance/#envoy","title":"Envoy","text":"

The second component is the Envoy proxy, which runs alongside the example application. The Envoy configuration defines an external authorization filter envoy.ext_authz for a gRPC authorization server.

The config uses Envoy's in-built gRPC client to make external gRPC calls.

static_resources:\n  listeners:\n  - address:\n      socket_address:\n        address: 0.0.0.0\n        port_value: 8000\n    filter_chains:\n    - filters:\n      - name: envoy.filters.network.http_connection_manager\n        typed_config:\n          \"@type\": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\n          codec_type: auto\n          stat_prefix: ingress_http\n          route_config:\n            name: local_route\n            virtual_hosts:\n            - name: backend\n              domains:\n              - \"*\"\n              routes:\n              - match:\n                  prefix: \"/\"\n                route:\n                  cluster: service\n          http_filters:\n          - name: envoy.ext_authz\n            typed_config:\n              \"@type\": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz\n              transport_api_version: V3\n              with_request_body:\n                max_request_bytes: 8192\n                allow_partial_message: true\n              failure_mode_allow: false\n              grpc_service:\n                google_grpc:\n                  target_uri: 127.0.0.1:9191\n                  stat_prefix: ext_authz\n                timeout: 0.5s\n          - name: envoy.filters.http.router\n            typed_config:\n              \"@type\": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router\n  clusters:\n  - name: service\n    connect_timeout: 0.25s\n    type: strict_dns\n    lb_policy: round_robin\n    load_assignment:\n      cluster_name: service\n      endpoints:\n      - lb_endpoints:\n        - endpoint:\n            address:\n              socket_address:\n                address: 127.0.0.1\n                port_value: 8080\nadmin:\n  access_log_path: \"/dev/null\"\n  address:\n    socket_address:\n      address: 0.0.0.0\n      port_value: 8001\nlayered_runtime:\n  layers:\n    - name: static_layer_0\n      static_layer:\n        envoy:\n          resource_limits:\n            listener:\n              example_listener_name:\n                connection_limit: 10000\n        overload:\n          global_downstream_max_connections: 50000\n
"},{"location":"performance/#kyverno-authz-server","title":"Kyverno Authz Server","text":"

The third component is the Kyverno Authz Server itself, which is configured to load and enforce Kyverno policies on incoming requests.

"},{"location":"performance/#benchmark-scenarios","title":"Benchmark Scenarios","text":"

The following scenarios should be tested to compare the performance of the Kyverno Authz Server under different conditions:

  1. App Only: Requests are sent directly to the application, without Envoy or the Kyverno Authz Server.
  2. App and Envoy: Envoy is included in the request path, but the Kyverno Authz Server is not (i.e., Envoy External Authorization API is disabled).
  3. App, Envoy, and Kyverno: Envoy External Authorization API is enabled, and a sample real-world policy is loaded into the Kyverno Authz Server.
"},{"location":"performance/#load-testing-with-k6","title":"Load Testing with k6","text":"

To perform load testing, we'll use the k6 tool. Follow these steps:

  1. Install k6: Install k6 on your machine by following the instructions on the official website.

  2. Write the k6 script: Below is the example k6 script. 

import http from 'k6/http';\nimport { check, group, sleep } from 'k6';\n\nexport const options = {\n  stages: [\n    { duration: '30s', target: 100 }, // Ramp-up to 100 virtual users over 30 seconds\n    { duration: '1m', target: 100 }, // Stay at 100 virtual users for 1 minute\n    { duration: '30s', target: 0 }, // Ramp-down to 0 virtual users over 30 seconds\n  ],\n};\n\n/*\nReplace ip for every scenerio\nexport SERVICE_PORT=$(kubectl -n demo get service testapp -o jsonpath='{.spec.ports[?(@.port==8080)].nodePort}')\nexport SERVICE_HOST=$(minikube ip)\nexport SERVICE_URL=$SERVICE_HOST:$SERVICE_PORT\necho $SERVICE_URL\n\nhttp://192.168.49.2:31541\n\n*/\nconst BASE_URL = 'http://192.168.49.2:31541'; \n\nexport default function () {\n  group('GET /book with guest token', () => {\n    const res = http.get(`${BASE_URL}/book`, {\n      headers: { 'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk' },\n    });\n    check(res, {\n      'is status 200': (r) => r.status === 200,\n    });\n  });\n\n  sleep(1); // Sleep for 1 second between iterations\n}\n
  1. Run the k6 test: Run the load test with the following command:
$ k6 run -f - <<EOF\nimport http from 'k6/http';\nimport { check, group, sleep } from 'k6';\n\nexport const options = {\n  stages: [\n    { duration: '30s', target: 100 }, // Ramp-up to 100 virtual users over 30 seconds\n    { duration: '1m', target: 100 }, // Stay at 100 virtual users for 1 minute\n    { duration: '30s', target: 0 }, // Ramp-down to 0 virtual users over 30 seconds\n  ],\n};\n\n\nconst BASE_URL = 'http://192.168.49.2:31700'; // Replace with your application URL \n\nexport default function () {\n  group('GET /book with guest token', () => {\n    const res = http.get(`${BASE_URL}/book`, {\n      headers: { 'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk' },\n    });\n    check(res, {\n      'is status 200': (r) => r.status === 200,\n    });\n  });\n\n  sleep(1); // Sleep for 1 second between iterations\n}\nEOF\n
  1. Analyze the results: Generate an json report with detailed insight by running:

k6 run --out json=report.json k6-script.js\n
5. Repeat for different scenarios:

"},{"location":"performance/#measuring-performance","title":"Measuring Performance","text":"

The following metrics should be measured to evaluate the performance impact of the Kyverno Authz Server:

Observations:

Correlation with k6 results:

"},{"location":"policies/","title":"Policies","text":"

A Kyverno AuthorizationPolicy is a custom Kubernetes resources and can be easily managed via Kubernetes APIs, GitOps workflows, and other existing tools.

"},{"location":"policies/#resource-scope","title":"Resource Scope","text":"

A Kyverno AuthorizationPolicy is a cluster-wide resource.

"},{"location":"policies/#api-group-and-kind","title":"API Group and Kind","text":"

An AuthorizationPolicy belongs to the envoy.kyverno.io/v1alpha1 group and can only be of kind AuthorizationPolicy.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the request will be denied\n  failurePolicy: Fail\n  variables:\n    # `force_authorized` references the 'x-force-authorized' header\n    # from the envoy check request (or '' if not present)\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n    # `allowed` will be `true` if `variables.force_authorized` has the\n    # value 'enabled' or 'true'\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n    # make an authorisation decision based on the value of `variables.allowed`\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n  - response: >\n      envoy.Allowed().Response()\n
"},{"location":"policies/#envoy-external-authorization","title":"Envoy External Authorization","text":"

The Kyverno Authz Server implements the Envoy External Authorization API.

A Kyverno AuthorizationPolicy analyses an Envoy CheckRequest and can make a decision by returning an OkResponse or DeniedResponse.

"},{"location":"policies/#cel-language","title":"CEL language","text":"

An AuthorizationPolicy uses the CEL language to process the CheckRequest sent by Envoy.

CEL is an expression language that\u2019s fast, portable, and safe to execute in performance-critical applications.

"},{"location":"policies/#policy-structure","title":"Policy structure","text":"

A Kyverno AuthorizationPolicy is made of:

"},{"location":"policies/authorization-rules/","title":"Authorization rules","text":"

An AuthorizationPolicy main concern is to define authorization rules to deny or allow requests.

Every authorization rule is made of an optional match statement and a required response statement. Both statements are written in CEL.

If the match statement is present and evaluates to true, the response statement is used to create the response payload returned to the envoy proxy. Depending on the rule type, the response is expected to be an envoy.OkResponse or envoy.DeniedResponse.

Creating an OkResponse or DeniedResponse 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 responses easier. Browse the available libraries documentation for details.

"},{"location":"policies/authorization-rules/#evaluation-order","title":"Evaluation order","text":"
  1. All deny rules are evaluated first, the first matching rule is used to send the deny response to the envoy proxy.
  2. If no deny rule matched, allow rules are evaluated and the first matching rule is used to send the response to the envoy proxy.
  3. If no rule matched, the request is allowed by default.

Info

When multiple policies are present, deny and allow rules are concatenated together in policy name alphabetical order.

"},{"location":"policies/authorization-rules/#authorization-rules_1","title":"Authorization rules","text":"

The policy below will allow requests if they contain the header x-force-authorized with the value enabled or true. If the header is not present or has a different value, the request will be denied.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  # make an authorisation decision based on the value of `variables.allowed`\n  # - deny the request with 403 status code if it is `false`\n  # - else allow the request\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n  - response: >\n      envoy.Allowed().Response()\n

In this simple rule:

However, we can do a lot more. Envoy can add or remove headers, query parameters, register dynamic metadata passed along the filters chain, and even change the response body.

"},{"location":"policies/authorization-rules/#the-hard-way","title":"The hard way","text":"

Below is the same policy, creating the envoy.OkResponse and envoy.DeniedResponse manually.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.DeniedResponse{\n        status: google.rpc.Status{\n          code: 7\n        },\n        http_response: envoy.service.auth.v3.DeniedHttpResponse{\n          status: envoy.type.v3.HttpStatus{\n            code: 403\n          }\n        }\n      }\n  allow:\n  - response: >\n      envoy.OkResponse{\n        status: google.rpc.Status{\n          code: 0\n        },\n        http_response: envoy.service.auth.v3.OkHttpResponse{}\n      }\n
"},{"location":"policies/authorization-rules/#advanced-example","title":"Advanced example","text":"

This second policy showcases a more advanced example.

apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: force_unauthenticated\n    expression: object.attributes.request.http.headers[?\"x-force-unauthenticated\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: metadata\n    expression: '{\"my-new-metadata\": \"my-new-value\"}'\n  deny:\n    # if force_unauthenticated -> 401\n  - match: >\n      variables.force_unauthenticated\n    response: >\n      envoy\n        .Denied(401)\n        .WithBody(\"Authentication Failed\")\n        .Response()\n    # if not force_authorized -> 403\n  - match: >\n      !variables.force_authorized\n    response: >\n      envoy\n        .Denied(403)\n        .WithBody(\"Unauthorized Request\")\n        .Response()\n  allow:\n    # else -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\n        .WithMetadata(variables.metadata)\n

Notice this policy uses helper functions:

Info

The full documentation of the CEL Envoy library is available here.

"},{"location":"policies/failure-policy/","title":"Failure policy","text":"

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.

Allowed values are:

If not set, the failure policy defaults to Fail.

Info

FailurePolicy does not define how validations that evaluate to false are handled.

"},{"location":"policies/failure-policy/#fail","title":"Fail","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the request will be denied\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"policies/failure-policy/#ignore","title":"Ignore","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  # if something fails the failure will be ignored and the request will be allowed\n  failurePolicy: Ignore\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"policies/match-conditions/","title":"Match conditions","text":"

You can define match conditions if you need fine-grained request filtering.

Match conditions are CEL expressions. All match conditions must evaluate to true for the request to be evaluated.

Info

Match conditions have access to the same CEL variables as validation expressions.

"},{"location":"policies/match-conditions/#example","title":"Example","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  matchConditions:\n  - name: has-header\n    expression: object.attributes.request.http.headers[?\"x-force-deny\"].hasValue()\n  deny:\n  - response: >\n      envoy.Denied(403).Response()\n

In the policy above, the matchConditions will be used to deny all requests having the x-force-deny header.

"},{"location":"policies/match-conditions/#error-handling","title":"Error handling","text":"

In the event of an error evaluating a match condition the policy is not evaluated. Whether to reject the request is determined as follows:

  1. If any match condition evaluated to false (regardless of other errors), then the policy is skipped.
  2. Otherwise:
    • for failurePolicy: Fail, reject the request (without evaluating the policy).
    • for failurePolicy: Ignore, proceed with the request but skip the policy.
"},{"location":"policies/variables/","title":"Variables","text":"

A Kyverno AuthorizationPolicy can define variables that will be made available to all authorization rules.

Variables can be used in composition of other expressions. Each variable is defined as a named CEL expression. The will be available under variables in other expressions 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.

Info

The incoming CheckRequest from Envoy is made available to the policy under the object identifier.

"},{"location":"policies/variables/#variables_1","title":"Variables","text":"
apiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n    # `force_authorized` references the 'x-force-authorized' header\n    # from the envoy check request (or '' if not present)\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n    # `allowed` will be `true` if `variables.force_authorized` has the\n    # value 'enabled' or 'true'\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n    # make an authorisation decision based on the value of `variables.allowed`\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\n
"},{"location":"quick-start/","title":"Quick start","text":"

The Kyverno Envoy Plugin is a powerful tool that integrates with the Envoy proxy.

It allows you to enforce Kyverno policies on incoming and outgoing traffic in a service mesh environment, providing an additional layer of security and control over your applications.

"},{"location":"quick-start/#overview","title":"Overview","text":"

Envoy is a Layer 7 proxy and communication bus tailored for large-scale, modern service-oriented architectures. Starting from version 1.7.0, Envoy includes an External Authorization filter that interfaces with an authorization service to determine the legitimacy of incoming requests.

This functionality allows authorization decisions to be offloaded to an external service, which can access the request context. The request context includes details such as the origin and destination of the network activity, as well as specifics of the network request (e.g., HTTP request). This information enables the external service to make a well-informed decision regarding the authorization of the incoming request processed by Envoy.

"},{"location":"quick-start/#what-is-the-kyverno-envoy-plugin","title":"What is the Kyverno Envoy Plugin?","text":"

The Kyverno Envoy Plugin is gRPC server that implements Envoy External Authorization API.

This allows you to enforce Kyverno policies on incoming and outgoing traffic in a service mesh environment, providing an additional layer of security and control over your applications. You can use this version of Kyverno to enforce fine-grained, context-aware access control policies with Envoy without modifying your microservice.

"},{"location":"quick-start/#how-does-this-work","title":"How does this work?","text":"

In addition to the Envoy sidecar, your application pods will include a Kyverno Authz Server component, either as a sidecar or as a separate pod. When Envoy receives an API request intended for your microservice, it consults the Kyverno Authz Server to determine whether the request should be permitted or not.

Performing policy evaluations locally with Envoy is advantageous, as it eliminates the need for an additional network hop for authorization checks, thus enhancing both performance and availability.

Info

The Kyverno Envoy Plugin is frequently deployed in Kubernetes environments as a sidecar container or as a separate pod. Additionally, it can be used in other environments as a standalone process running alongside Envoy.

"},{"location":"quick-start/#additional-resources","title":"Additional Resources","text":"

See the following pages on envoyproxy.io for more information on external authorization:

"},{"location":"quick-start/authz-server/","title":"Authz server","text":""},{"location":"quick-start/authz-server/#setup","title":"Setup","text":"

In this quick start guide we will deploy the Kyverno Authz Server inside a cluster.

Then you will interface Istio, an open source service mesh with the Kyverno Authz Server to delegate the request authorisation based on policies installed in the cluster.

"},{"location":"quick-start/authz-server/#prerequisites","title":"Prerequisites","text":""},{"location":"quick-start/authz-server/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"quick-start/authz-server/#configure-the-mesh","title":"Configure the mesh","text":"

We need to register the Kyverno Authz Server with Istio.

# configure the mesh\nistioctl install -y -f - <<EOF\napiVersion: install.istio.io/v1alpha1\nkind: IstioOperator\nspec:\n  meshConfig:\n    accessLogFile: /dev/stdout\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\nEOF\n

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

[...]\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\n[...]\n
"},{"location":"quick-start/authz-server/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

The first step is to deploy the Kyverno Authz Server.

# create the kyverno namespace\nkubectl create ns kyverno\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace kyverno istio-injection=enabled\n\n# deploy the kyverno authz server\nhelm install kyverno-authz-server --namespace kyverno --wait  \\\n  --repo https://kyverno.github.io/kyverno-envoy-plugin       \\\n  kyverno-authz-server\n
"},{"location":"quick-start/authz-server/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace demo istio-injection=enabled\n\n# deploy the httpbin application\nkubectl apply -n demo -f \\\n  https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml\n
"},{"location":"quick-start/authz-server/#deploy-an-istio-authorizationpolicy","title":"Deploy an Istio AuthorizationPolicy","text":"

An AuthorizationPolicy is the custom Istio resource that defines the services that will be protected by the Kyverno Authz Server.

# deploy istio authorization policy\nkubectl apply -f - <<EOF\napiVersion: security.istio.io/v1\nkind: AuthorizationPolicy\nmetadata:\n  name: kyverno-authz-server\n  namespace: demo\nspec:\n  action: CUSTOM\n  provider:\n    name: kyverno-authz-server.local\n  rules:\n  - {} # empty rules, it will apply to all requests\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server extensionProvider you set in the Istio configuration:

[...]\n  provider:\n    name: kyverno-authz-server.local\n[...]\n
"},{"location":"quick-start/authz-server/#deploy-a-kyverno-authorizationpolicy","title":"Deploy a Kyverno AuthorizationPolicy","text":"

A Kyverno AuthorizationPolicy defines the rules used by the Kyverno authz server to make a decision based on a given Envoy CheckRequest.

It uses the CEL language to analyse the incoming CheckRequest and is expected to produce an OkResponse or DeniedResponse in return.

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\")\n  - name: allowed\n    expression: variables.force_authorized in [\"enabled\", \"true\"]\n  deny:\n  - match: >\n      !variables.allowed\n    response: >\n      envoy.Denied(403).Response()\nEOF\n

This simple policy will deny requests if they don't contain the header x-force-authorized with the value enabled or true.

"},{"location":"quick-start/authz-server/#testing","title":"Testing","text":"

At this we have deployed and configured Istio, the Kyverno Authz Server, a sample application, and the authorization policies.

"},{"location":"quick-start/authz-server/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"quick-start/authz-server/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"quick-start/authz-server/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send requests to the sample application and verify the result.

The following request will return 403 (denied by our policy):

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get\n

The following request will return 200 (allowed by our policy):

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"x-force-authorized: true\"\n
"},{"location":"quick-start/authz-server/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the quick start guide!

This tutorial demonstrated how to configure Istio\u2019s EnvoyFilter to utilize the Kyverno Authz Server as an external authorization service.

"},{"location":"quick-start/next-steps/","title":"Next steps","text":"

We covered the main components of the Kyverno Envoy Plugin.

Tip

If there's anything you would like to be improved, please reach out, we will be happy to discuss and improve as much as we can.

To continue exploring and learn more about the Kyverno Envoy Plugin:

"},{"location":"quick-start/sidecar-injector/","title":"Sidecar injector","text":"

This is not ready yet, hopefully it will be available soon!

"},{"location":"reference/","title":"Reference documentation","text":"

Info

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

"},{"location":"reference/json-schemas/","title":"JSON schemas","text":"

JSON schemas for the Kyverno Envoy Plugin are available:

They can be used to enable validation and autocompletion in your IDE.

"},{"location":"reference/json-schemas/#vs-code","title":"VS code","text":"

In VS code, simply add a comment on top of your YAML resources.

"},{"location":"reference/json-schemas/#authorizationpolicy","title":"AuthorizationPolicy","text":"
# yaml-language-server: $schema=https://raw.githubusercontent.com/kyverno/kyverno-envoy-plugin/main/.schemas/json/authorizationpolicy-envoy-v1alpha1.json\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  variables:\n  - name: force_authorized\n    expression: object.attributes.request.http.headers[?\"x-force-authorized\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: force_unauthenticated\n    expression: object.attributes.request.http.headers[?\"x-force-unauthenticated\"].orValue(\"\") in [\"enabled\", \"true\"]\n  - name: metadata\n    expression: '{\"my-new-metadata\": \"my-new-value\"}'\n  deny:\n    # if force_unauthenticated -> 401\n  - match: >\n      variables.force_unauthenticated\n    response: >\n      envoy\n        .Denied(401)\n        .WithBody(\"Authentication Failed\")\n        .Response()\n        .WithMetadata(variables.metadata)\n    # if not force_authorized -> 403\n  - match: >\n      !variables.force_authorized\n    response: >\n      envoy\n        .Denied(403)\n        .WithBody(\"Unauthorized Request\")\n        .Response()\n  allow:\n    # else -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\n        .WithMetadata(variables.metadata)\n
"},{"location":"reference/apis/policy.v1alpha1/","title":"policy (v1alpha1)","text":""},{"location":"reference/apis/policy.v1alpha1/#resource-types","title":"Resource Types","text":""},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-AuthorizationPolicy","title":"AuthorizationPolicy","text":"

AuthorizationPolicy defines an authorization policy resource

Field Type Required Inline Description apiVersion string envoy.kyverno.io/v1alpha1 kind string AuthorizationPolicy metadata meta/v1.ObjectMeta No description provided. spec AuthorizationPolicySpec No description provided."},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-Authorization","title":"Authorization","text":"

Appears in:

Authorization defines an authorization policy rule

Field Type Required Inline Description match string

Match represents the match condition which will be evaluated by CEL. Must evaluate to bool.

response string

Response represents the response 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).

"},{"location":"reference/apis/policy.v1alpha1/#envoy-kyverno-io-v1alpha1-AuthorizationPolicySpec","title":"AuthorizationPolicySpec","text":"

Appears in:

AuthorizationPolicySpec defines the spec of an authorization policy

Field Type Required Inline Description failurePolicy admissionregistration/v1.FailurePolicyType

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.

matchConditions []admissionregistration/v1.MatchCondition

MatchConditions is a list of conditions that must be met for a request to be validated. An empty list of matchConditions matches all requests. The exact matching logic is (in order): 1. If ANY matchCondition evaluates to FALSE, the policy is skipped. 2. If ALL matchConditions evaluate to TRUE, the policy is evaluated. 3. If any matchCondition evaluates to an error (but none are FALSE): - If failurePolicy=Fail, reject the request - If failurePolicy=Ignore, the policy is skipped

variables []admissionregistration/v1.Variable

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.

deny []Authorization

Deny contain CEL expressions which is used to deny a request.

allow []Authorization

Allow contain CEL expressions which is used to allow a request.

"},{"location":"tutorials/","title":"Tutorials","text":"

If you didn't read the Quick start section yet, we really recommend giving it a try to discover and familiarise with the Kyverno Envoy Plugin components first.

"},{"location":"tutorials/envoy-gateway/","title":"Envoy Gateway","text":"

Envoy Gateway is an open source project for managing Envoy Proxy as a standalone or Kubernetes-based application gateway. Gateway API resources are used to dynamically provision and configure the managed Envoy Proxies.

This tutorial shows how Envoy Gateway can be configured to delegate authorization decisions to the Kyverno Authz Server.

"},{"location":"tutorials/envoy-gateway/#setup","title":"Setup","text":""},{"location":"tutorials/envoy-gateway/#prerequisites","title":"Prerequisites","text":""},{"location":"tutorials/envoy-gateway/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"tutorials/envoy-gateway/#install-envoy-gateway","title":"Install Envoy Gateway","text":"

First we need to install Envoy Gateway in the cluster.

# install envoy gateway\nhelm install envoy-gateway \\\n  --namespace envoy-gateway-system --create-namespace \\\n  --wait \\\n  --version v1.2.2 oci://docker.io/envoyproxy/gateway-helm\n
"},{"location":"tutorials/envoy-gateway/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# deploy the httpbin application\nkubectl apply \\\n  -n demo \\\n  -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml\n
"},{"location":"tutorials/envoy-gateway/#create-a-gatewayclass-and-a-gateway","title":"Create a GatewayClass and a Gateway","text":"

With Envoy Gateway installed we can now create a Gateway. To do so we will also create a dedicated GatewayClass.

Depending on your setup you will potentially need to create an EnvoyProxy resource to customize the way Envoy Gateway will create the underlying Service. The script below creates one to set the name and type of the service because the kind cluster created in the first step doesn't come with load balancer support.

# create a gateway\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.envoyproxy.io/v1alpha1\nkind: EnvoyProxy\nmetadata:\n  name: demo\nspec:\n  provider:\n    type: Kubernetes\n    kubernetes:\n      envoyService:\n        name: internet   # use a known name for the created service\n        type: ClusterIP  # because a kind cluster has no support for LB\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: GatewayClass\nmetadata:\n  name: demo\nspec:\n  controllerName: gateway.envoyproxy.io/gatewayclass-controller\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: Gateway\nmetadata:\n  name: demo\nspec:\n  gatewayClassName: demo\n  infrastructure:\n    parametersRef:\n      group: gateway.envoyproxy.io\n      kind: EnvoyProxy\n      name: demo\n  listeners:\n  - name: http\n    protocol: HTTP\n    port: 80\nEOF\n
"},{"location":"tutorials/envoy-gateway/#create-an-httproute-to-the-sample-application","title":"Create an HTTPRoute to the sample application","text":"

Next, we need to link the Gateway to our sample applicate with an HTTPRoute.

# create an http route to the sample app\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.networking.k8s.io/v1\nkind: HTTPRoute\nmetadata:\n  name: demo\nspec:\n  parentRefs:\n  - name: demo\n  rules:\n  - matches:\n    - path:\n        type: PathPrefix\n        value: /\n    backendRefs:\n    - group: ''\n      kind: Service\n      name: httpbin\n      port: 8000\n      weight: 1\nEOF\n
"},{"location":"tutorials/envoy-gateway/#deploy-cert-manager","title":"Deploy cert-manager","text":"

The Kyverno Authz Server comes with a validation webhook and needs a certificate to let the api server call into it.

Let's deploy cert-manager to manage the certificate we need.

# install cert-manager\nhelm install cert-manager \\\n  --namespace cert-manager --create-namespace \\\n  --wait \\\n  --repo https://charts.jetstack.io cert-manager \\\n  --set crds.enabled=true\n\n# create a self-signed cluster issuer\nkubectl apply -f - <<EOF\napiVersion: cert-manager.io/v1\nkind: ClusterIssuer\nmetadata:\n  name: selfsigned-issuer\nspec:\n  selfSigned: {}\nEOF\n
"},{"location":"tutorials/envoy-gateway/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

Now deploy the Kyverno Authz Server.

# deploy the kyverno authz server\nhelm install kyverno-authz-server \\\n  --namespace kyverno --create-namespace \\\n  --wait \\\n  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \\\n  --set certificates.certManager.issuerRef.group=cert-manager.io \\\n  --set certificates.certManager.issuerRef.kind=ClusterIssuer \\\n  --set certificates.certManager.issuerRef.name=selfsigned-issuer\n
"},{"location":"tutorials/envoy-gateway/#create-a-kyverno-authorizationpolicy","title":"Create a Kyverno AuthorizationPolicy","text":"

In summary the policy below does the following:

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: authorization\n    expression: object.attributes.request.http.headers[?\"authorization\"].orValue(\"\").split(\" \")\n  - name: token\n    expression: >\n      size(variables.authorization) == 2 && variables.authorization[0].lowerAscii() == \"bearer\"\n        ? jwt.Decode(variables.authorization[1], \"secret\")\n        : null\n  deny:\n    # request not authenticated -> 401\n  - match: >\n      variables.token == null || !variables.token.Valid\n    response: >\n      envoy.Denied(401).Response()\n    # request authenticated but not admin role -> 403\n  - match: >\n      variables.token.Claims.?role.orValue(\"\") != \"admin\"\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n    # request authenticated and admin role -> 200\n  - response: >\n      envoy\n        .Allowed()\n        .WithHeader(\"x-validated-by\", \"my-security-checkpoint\")\n        .WithoutHeader(\"x-force-authorized\")\n        .WithResponseHeader(\"x-add-custom-response-header\", \"added\")\n        .Response()\nEOF\n
"},{"location":"tutorials/envoy-gateway/#deploy-an-envoy-gateway-securitypolicy","title":"Deploy an Envoy Gateway SecurityPolicy","text":"

A SecurityPolicy is the custom Envoy Gateway resource to configure underlying Envoy Proxy to use an external auth server (the Kyverno Authz Server we installed in a prior step).

# deploy envoy gateway security policy\nkubectl apply -n demo -f - <<EOF\napiVersion: gateway.envoyproxy.io/v1alpha1\nkind: SecurityPolicy\nmetadata:\n  name: demo\nspec:\n  targetRefs:\n  - group: gateway.networking.k8s.io\n    kind: HTTPRoute\n    name: demo\n  extAuth:\n    grpc:\n      backendRef:\n        group: ''\n        kind: Service\n        name: kyverno-authz-server\n        namespace: kyverno\n        port: 9081\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server service as the GRPC backend:

[...]\n  extAuth:\n    grpc:\n      backendRef:\n        group: ''\n        kind: Service\n        name: kyverno-authz-server\n        namespace: kyverno\n        port: 9081\n[...]\n

Also notice that the security policy applies to the demo HTTPRoute:

[...]\n  targetRefs:\n    - group: gateway.networking.k8s.io\n      kind: HTTPRoute\n      name: demo\n[...]\n
"},{"location":"tutorials/envoy-gateway/#grant-access-to-the-kyverno-authz-server-service","title":"Grant access to the Kyverno Authz Server service","text":"

Last thing we need to configure is to grant access to the Kyverno Authz Server service for our SecurityPolicy to take effect.

# grant access\nkubectl apply -n kyverno -f - <<EOF\napiVersion: gateway.networking.k8s.io/v1beta1\nkind: ReferenceGrant\nmetadata:\n  name: demo\nspec:\n  from:\n  - group: gateway.envoyproxy.io\n    kind: SecurityPolicy\n    namespace: demo\n  to:\n  - group: ''\n    kind: Service\nEOF\n
"},{"location":"tutorials/envoy-gateway/#testing","title":"Testing","text":"

At this we have deployed and configured Envoy Gateway, the Kyverno Authz Server, a sample application, and the authorization and security policies.

"},{"location":"tutorials/envoy-gateway/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"tutorials/envoy-gateway/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"tutorials/envoy-gateway/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send request to the sample application and verify the result.

For convenience, we will store Alice\u2019s and Bob\u2019s tokens in environment variables.

Here Bob is assigned the admin role and Alice is assigned the guest role.

export ALICE_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk\"\nexport BOB_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6ImFkbWluIiwic3ViIjoiWVd4cFkyVT0ifQ.veMeVDYlulTdieeX-jxFZ_tCmqQ_K8rwx2OktUHv5Z0\"\n

Calling without a JWT token will return 401:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get\n

Calling with Alice\u2019s JWT token will return 403:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get -H \"authorization: Bearer $ALICE_TOKEN\"\n

Calling with Bob\u2019s JWT token will return 200:

curl -s -w \"\\nhttp_code=%{http_code}\" internet.envoy-gateway-system/get -H \"authorization: Bearer $BOB_TOKEN\"\n
"},{"location":"tutorials/envoy-gateway/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the tutorial!

This tutorial demonstrated how to configure Envoy Gateway to utilize the Kyverno Authz Server as an external authorization service.

Additionally, the tutorial provided an example policy to decode a JWT token and make a decision based on it.

"},{"location":"tutorials/istio/","title":"Istio","text":"

Istio is an open source service mesh for managing the different microservices that make up a cloud-native application. Istio provides a mechanism to use a service as an external authorizer with the AuthorizationPolicy API.

This tutorial shows how Istio\u2019s AuthorizationPolicy can be configured to delegate authorization decisions to the Kyverno Authz Server.

"},{"location":"tutorials/istio/#setup","title":"Setup","text":""},{"location":"tutorials/istio/#prerequisites","title":"Prerequisites","text":""},{"location":"tutorials/istio/#setup-a-cluster-optional","title":"Setup a cluster (optional)","text":"

If you don't have a cluster at hand, you can create a local one with kind.

KIND_IMAGE=kindest/node:v1.31.1\n\n# create cluster\nkind create cluster --image $KIND_IMAGE --wait 1m\n
"},{"location":"tutorials/istio/#configure-the-mesh","title":"Configure the mesh","text":"

We need to register the Kyverno Authz Server with Istio.

# configure the mesh\nistioctl install -y -f - <<EOF\napiVersion: install.istio.io/v1alpha1\nkind: IstioOperator\nspec:\n  meshConfig:\n    accessLogFile: /dev/stdout\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\nEOF\n

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

[...]\n    extensionProviders:\n    - name: kyverno-authz-server.local\n      envoyExtAuthzGrpc:\n        service: kyverno-authz-server.kyverno.svc.cluster.local\n        port: '9081'\n[...]\n
"},{"location":"tutorials/istio/#deploy-cert-manager","title":"Deploy cert-manager","text":"

The Kyverno Authz Server comes with a validation webhook and needs a certificate to let the api server call into it.

Let's deploy cert-manager to manage the certificate we need.

# install cert-manager\nhelm install cert-manager \\\n  --namespace cert-manager --create-namespace \\\n  --wait \\\n  --repo https://charts.jetstack.io cert-manager \\\n  --set crds.enabled=true\n\n# create a self-signed cluster issuer\nkubectl apply -f - <<EOF\napiVersion: cert-manager.io/v1\nkind: ClusterIssuer\nmetadata:\n  name: selfsigned-issuer\nspec:\n  selfSigned: {}\nEOF\n
"},{"location":"tutorials/istio/#deploy-the-kyverno-authz-server","title":"Deploy the Kyverno Authz Server","text":"

Now we can deploy the Kyverno Authz Server.

# create the kyverno namespace\nkubectl create ns kyverno\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace kyverno istio-injection=enabled\n\n# deploy the kyverno authz server\nhelm install kyverno-authz-server \\\n  --namespace kyverno \\\n  --wait \\\n  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \\\n  --set certificates.certManager.issuerRef.group=cert-manager.io \\\n  --set certificates.certManager.issuerRef.kind=ClusterIssuer \\\n  --set certificates.certManager.issuerRef.name=selfsigned-issuer\n
"},{"location":"tutorials/istio/#deploy-a-sample-application","title":"Deploy a sample application","text":"

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.

# create the demo namespace\nkubectl create ns demo\n\n# label the namespace to inject the envoy proxy\nkubectl label namespace demo istio-injection=enabled\n\n# deploy the httpbin application\nkubectl apply \\\n   -n demo \\\n   -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml\n
"},{"location":"tutorials/istio/#deploy-an-istio-authorizationpolicy","title":"Deploy an Istio AuthorizationPolicy","text":"

An AuthorizationPolicy is the custom Istio resource that defines the services that will be protected by the Kyverno Authz Server.

# deploy istio authorization policy\nkubectl apply -f - <<EOF\napiVersion: security.istio.io/v1\nkind: AuthorizationPolicy\nmetadata:\n  name: kyverno-authz-server\n  namespace: demo\nspec:\n  action: CUSTOM\n  provider:\n    name: kyverno-authz-server.local\n  rules:\n  - {} # empty rules, it will apply to all requests\nEOF\n

Notice that in this resource, we define the Kyverno Authz Server extensionProvider you set in the Istio configuration:

[...]\n  provider:\n    name: kyverno-authz-server.local\n[...]\n
"},{"location":"tutorials/istio/#create-a-kyverno-authorizationpolicy","title":"Create a Kyverno AuthorizationPolicy","text":"

In summary the policy below does the following:

# deploy kyverno authorization policy\nkubectl apply -f - <<EOF\napiVersion: envoy.kyverno.io/v1alpha1\nkind: AuthorizationPolicy\nmetadata:\n  name: demo\nspec:\n  failurePolicy: Fail\n  variables:\n  - name: authorization\n    expression: object.attributes.request.http.headers[?\"authorization\"].orValue(\"\").split(\" \")\n  - name: token\n    expression: >\n      size(variables.authorization) == 2 && variables.authorization[0].lowerAscii() == \"bearer\"\n        ? jwt.Decode(variables.authorization[1], \"secret\")\n        : null\n  deny:\n    # request not authenticated -> 401\n  - match: >\n      variables.token == null || !variables.token.Valid\n    response: >\n      envoy.Denied(401).Response()\n    # request authenticated but not admin role -> 403\n  - match: >\n      variables.token.Claims.?role.orValue(\"\") != \"admin\"\n    response: >\n      envoy.Denied(403).Response()\n  allow:\n    # request authenticated and admin role -> 200\n  - response: >\n      envoy.Allowed().Response()\nEOF\n
"},{"location":"tutorials/istio/#testing","title":"Testing","text":"

At this we have deployed and configured Istio, the Kyverno Authz Server, a sample application, and the authorization policies.

"},{"location":"tutorials/istio/#start-an-in-cluster-shell","title":"Start an in-cluster shell","text":"

Let's start a pod in the cluster with a shell to call into the sample application.

# run an in-cluster shell\nkubectl run -i -t busybox --image=alpine --restart=Never -n demo\n
"},{"location":"tutorials/istio/#install-curl","title":"Install curl","text":"

We will use curl to call into the sample application but it's not installed in our shell, let's install it in the pod.

# install curl\napk add curl\n
"},{"location":"tutorials/istio/#call-into-the-sample-application","title":"Call into the sample application","text":"

Now we can send request to the sample application and verify the result.

For convenience, we will store Alice\u2019s and Bob\u2019s tokens in environment variables.

Here Bob is assigned the admin role and Alice is assigned the guest role.

export ALICE_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6Imd1ZXN0Iiwic3ViIjoiWVd4cFkyVT0ifQ.ja1bgvIt47393ba_WbSBm35NrUhdxM4mOVQN8iXz8lk\"\nexport BOB_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyNDEwODE1MzksIm5iZiI6MTUxNDg1MTEzOSwicm9sZSI6ImFkbWluIiwic3ViIjoiWVd4cFkyVT0ifQ.veMeVDYlulTdieeX-jxFZ_tCmqQ_K8rwx2OktUHv5Z0\"\n

Calling without a JWT token will return 401:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get\n

Calling with Alice\u2019s JWT token will return 403:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"authorization: Bearer $ALICE_TOKEN\"\n

Calling with Bob\u2019s JWT token will return 200:

curl -s -w \"\\nhttp_code=%{http_code}\" httpbin:8000/get -H \"authorization: Bearer $BOB_TOKEN\"\n
"},{"location":"tutorials/istio/#wrap-up","title":"Wrap Up","text":"

Congratulations on completing the tutorial!

This tutorial demonstrated how to configure Istio\u2019s EnvoyFilter to utilize the Kyverno Authz Server as an external authorization service.

Additionally, the tutorial provided an example policy to decode a JWT token and make a decision based on it.

"}]} \ No newline at end of file diff --git a/main/sitemap.xml b/main/sitemap.xml index 60c2a19..57008b6 100644 --- a/main/sitemap.xml +++ b/main/sitemap.xml @@ -2,106 +2,106 @@ https://kyverno.github.io/kyverno-envoy-plugin/main/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/cel-extensions/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/cel-extensions/envoy/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/cel-extensions/jwt/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/contribute/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/making-a-pull-request/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/reporting-a-bug/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/reporting-a-docs-issue/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/community/requesting-a-change/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/performance/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/policies/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/policies/authorization-rules/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/policies/failure-policy/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/policies/match-conditions/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/policies/variables/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/quick-start/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/quick-start/authz-server/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/quick-start/next-steps/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/quick-start/sidecar-injector/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/reference/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/reference/json-schemas/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/reference/apis/policy.v1alpha1/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/tutorials/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/tutorials/envoy-gateway/ - 2025-01-03 + 2025-01-06 https://kyverno.github.io/kyverno-envoy-plugin/main/tutorials/istio/ - 2025-01-03 + 2025-01-06 \ No newline at end of file diff --git a/main/sitemap.xml.gz b/main/sitemap.xml.gz index c6ab7e08a8bb7e18644ea72e22f14dd0c5050e33..3dc7d72728e09e96324979833ab269f96975f469 100644 GIT binary patch delta 40 ycmV+@0N4M)1Hl6aABzYG03Cag2Oa{)28XHlrv90c$?yn|6ryba5C8xtTMs4x delta 40 ycmV+@0N4M)1Hl6aABzYGfGBs72Oa{>&XFga2B)d_rv8zU$?ymvi_%X35C8x-G!Mc6 diff --git a/main/tutorials/envoy-gateway/index.html b/main/tutorials/envoy-gateway/index.html index 1566cca..ef97a59 100644 --- a/main/tutorials/envoy-gateway/index.html +++ b/main/tutorials/envoy-gateway/index.html @@ -1,14 +1,19 @@ - Envoy Gateway - Kyverno Envoy Plugin
Skip to content

Envoy Gateway

Envoy Gateway is an open source project for managing Envoy Proxy as a standalone or Kubernetes-based application gateway. Gateway API resources are used to dynamically provision and configure the managed Envoy Proxies.

This tutorial shows how Envoy Gateway can be configured to delegate authorization decisions to the Kyverno Authz Server.

Setup

Prerequisites

  • A Kubernetes cluster
  • Helm to install Envoy Gateway the Kyverno Authz Server
  • 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.

KIND_IMAGE=kindest/node:v1.31.1
+ Envoy Gateway - Kyverno Envoy Plugin      
 
  
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Envoy Gateway
 
Envoy Gateway is an open source project for managing Envoy Proxy as a standalone or Kubernetes-based application gateway. Gateway API resources are used to dynamically provision and configure the managed Envoy Proxies.
 
This tutorial shows how Envoy Gateway can be configured to delegate authorization decisions to the Kyverno Authz Server.
 
Setup
 
Prerequisites
 
     
  • A Kubernetes cluster
    •  
  • Helm to install Envoy Gateway the Kyverno Authz Server
    •  
  • 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.
 
KIND_IMAGE=kindest/node:v1.31.1
 
 # create cluster
 kind create cluster --image $KIND_IMAGE --wait 1m
 
 
Install Envoy Gateway
 
First we need to install Envoy Gateway in the cluster.
 
# install envoy gateway
-helm install envoy-gateway -n envoy-gateway-system --create-namespace --wait --version v1.2.2 oci://docker.io/envoyproxy/gateway-helm
+helm install envoy-gateway \
+  --namespace envoy-gateway-system --create-namespace \
+  --wait \
+  --version v1.2.2 oci://docker.io/envoyproxy/gateway-helm
 
 
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.
 
# create the demo namespace
 kubectl create ns demo
 
 # deploy the httpbin application
-kubectl apply -n demo -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml
+kubectl apply \
+  -n demo \
+  -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml
 
 
Create a GatewayClass and a Gateway
 
With Envoy Gateway installed we can now create a Gateway. To do so we will also create a dedicated GatewayClass.
 
Depending on your setup you will potentially need to create an EnvoyProxy resource to customize the way Envoy Gateway will create the underlying Service. The script below creates one to set the name and type of the service because the kind cluster created in the first step doesn't come with load balancer support.
 
# create a gateway
 kubectl apply -n demo -f - <<EOF
 apiVersion: gateway.envoyproxy.io/v1alpha1
@@ -67,8 +72,30 @@
       port: 8000
       weight: 1
 EOF
+
 
Deploy cert-manager
 
The Kyverno Authz Server comes with a validation webhook and needs a certificate to let the api server call into it.
 
Let's deploy cert-manager to manage the certificate we need.
 
# install cert-manager
+helm install cert-manager \
+  --namespace cert-manager --create-namespace \
+  --wait \
+  --repo https://charts.jetstack.io cert-manager \
+  --set crds.enabled=true
+
+# create a self-signed cluster issuer
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: selfsigned-issuer
+spec:
+  selfSigned: {}
+EOF
 
 
Deploy the Kyverno Authz Server
 
Now deploy the Kyverno Authz Server.
 
# deploy the kyverno authz server
-helm install kyverno-authz-server --namespace kyverno --create-namespace --wait --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server
+helm install kyverno-authz-server \
+  --namespace kyverno --create-namespace \
+  --wait \
+  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \
+  --set certificates.certManager.issuerRef.group=cert-manager.io \
+  --set certificates.certManager.issuerRef.kind=ClusterIssuer \
+  --set certificates.certManager.issuerRef.name=selfsigned-issuer
 
 
Create a Kyverno AuthorizationPolicy
 
In summary the policy below does the following:
 
     
  • Checks that the JWT token is valid
    •  
  • Checks that the action is allowed based on the token payload role and the request path
    •  
 
# deploy kyverno authorization policy
 kubectl apply -f - <<EOF
 apiVersion: envoy.kyverno.io/v1alpha1
diff --git a/main/tutorials/istio/index.html b/main/tutorials/istio/index.html
index 15d57a5..1e91a74 100644
--- a/main/tutorials/istio/index.html
+++ b/main/tutorials/istio/index.html
@@ -1,4 +1,4 @@
- Istio - Kyverno Envoy Plugin      
 
  
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Istio
 
Istio is an open source service mesh for managing the different microservices that make up a cloud-native application. Istio provides a mechanism to use a service as an external authorizer with the AuthorizationPolicy API.
 
This tutorial shows how Istio’s AuthorizationPolicy can be configured to delegate authorization decisions to the Kyverno Authz Server.
 
Setup
 
Prerequisites
 
     
  • A Kubernetes cluster
    •  
  • Helm to install the Kyverno Authz Server
    •  
  • istioctl to configure the mesh
    •  
  • 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.
 
KIND_IMAGE=kindest/node:v1.31.1
+ Istio - Kyverno Envoy Plugin      
 
  
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Istio
 
Istio is an open source service mesh for managing the different microservices that make up a cloud-native application. Istio provides a mechanism to use a service as an external authorizer with the AuthorizationPolicy API.
 
This tutorial shows how Istio’s AuthorizationPolicy can be configured to delegate authorization decisions to the Kyverno Authz Server.
 
Setup
 
Prerequisites
 
     
  • A Kubernetes cluster
    •  
  • Helm to install the Kyverno Authz Server
    •  
  • istioctl to configure the mesh
    •  
  • 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.
 
KIND_IMAGE=kindest/node:v1.31.1
 
 # create cluster
 kind create cluster --image $KIND_IMAGE --wait 1m
@@ -22,14 +22,36 @@
         service: kyverno-authz-server.kyverno.svc.cluster.local
         port: '9081'
 [...]
-
 
Deploy the Kyverno Authz Server
 
The first step is to deploy the Kyverno Authz Server.
 
# create the kyverno namespace
+
 
Deploy cert-manager
 
The Kyverno Authz Server comes with a validation webhook and needs a certificate to let the api server call into it.
 
Let's deploy cert-manager to manage the certificate we need.
 
# install cert-manager
+helm install cert-manager \
+  --namespace cert-manager --create-namespace \
+  --wait \
+  --repo https://charts.jetstack.io cert-manager \
+  --set crds.enabled=true
+
+# create a self-signed cluster issuer
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: selfsigned-issuer
+spec:
+  selfSigned: {}
+EOF
+
 
Deploy the Kyverno Authz Server
 
Now we can deploy the Kyverno Authz Server.
 
# 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
+helm install kyverno-authz-server \
+  --namespace kyverno \
+  --wait \
+  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \
+  --set certificates.certManager.issuerRef.group=cert-manager.io \
+  --set certificates.certManager.issuerRef.kind=ClusterIssuer \
+  --set certificates.certManager.issuerRef.name=selfsigned-issuer
 
 
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.
 
# create the demo namespace
 kubectl create ns demo
 
@@ -37,7 +59,9 @@
 kubectl label namespace demo istio-injection=enabled
 
 # deploy the httpbin application
-kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml -n demo
+kubectl apply \
+   -n demo \
+   -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml
 
 
Deploy an Istio AuthorizationPolicy
 
An AuthorizationPolicy is the custom Istio resource that defines the services that will be protected by the Kyverno Authz Server.
 
# deploy istio authorization policy
 kubectl apply -f - <<EOF
 apiVersion: security.istio.io/v1