<commit_before>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    http://docs.cilium.io

*******************
Envoy Go Extensions
*******************

.. note:: This feature is currently in beta phase.

This is a guide for developers who are interested in writing a Go extension to the 
Envoy proxy as part of Cilium.   

.. image:: images/proxylib_logical_flow.png

As depicted above, this framework allows a developer to write a small amount of Go
code (green box) focused on parsing a new API protocol, and this Go code is able to  
full advantage of Cilium features including high-performance redirection to/from Envoy, 
rich L7-aware policy language
and access logging, and visibility into encrypted traffic traffic via kTLS (coming soon!).  
In sum, you as the developer need only worry about the logic of parsing the protocol, 
and Cilium + Envoy + BPF do the heavy-lifting.  

This guide uses simple examples based on a hypothetical "r2d2" protocol 
(see `proxylib/r2d2/r2d2parser.go <https://github.com/cilium/cilium/blob/master/proxylib/r2d2/r2d2parser.go>`_) 
that might be used to talk to a simple protocol droid a long time ago in a galaxy far, far away.   
But it also points to other real protocols like Memcached and Cassandra that already exist in the cilium/proxylib 
directory.  

Step 1: Decide on a Basic Policy Model
======================================

To get started, take some time to think about what it means to provide protocol-aware security
in the context of your chosen protocol.   Most protocols follow a common pattern of a client 
who performs an ''operation'' on a ''resource''.   For example: 

- A standard RESTful HTTP request has a GET/POST/PUT/DELETE methods (operation) and URLs (resource).
- A database protocol like MySQL has SELECT/INSERT/UPDATE/DELETE actions (operation) on a combined database + table name (resource).   
- A queueing protocol like Kafka has produce/consume (operation) on a particular queue (resource).    

A common policy model is to allow the user to whitelist certain operations on one or more resources.   
In some cases, the resources need to support regexes to avoid explicit matching on variable content 
like ids (e.g., /users/<uuid> would match /users/.*) 

In our examples, the ''r2d2'' example, we'll use a basic set of operations (READ/WRITE/HALT/RESET). 
The READ and WRITE commands also support a 'filename' resource, while HALT and RESET have no resource.  

Step 2: Understand Protocol, Encoding, Framing and Types<commit_msg>Update extensions.rst<commit_after>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    http://docs.cilium.io

*******************
Envoy Go Extensions
*******************

.. note:: This feature is currently in beta phase.

This is a guide for developers who are interested in writing a Go extension to the 
Envoy proxy as part of Cilium.   

.. image:: images/proxylib_logical_flow.png

As depicted above, this framework allows a developer to write a small amount of Go
code (green box) focused on parsing a new API protocol, and this Go code is able to  
take full advantage of Cilium features including high-performance redirection to/from Envoy, 
rich L7-aware policy language
and access logging, and visibility into encrypted traffic traffic via kTLS (coming soon!).  
In sum, you as the developer need only worry about the logic of parsing the protocol, 
and Cilium + Envoy + BPF do the heavy-lifting.  

This guide uses simple examples based on a hypothetical "r2d2" protocol 
(see `proxylib/r2d2/r2d2parser.go <https://github.com/cilium/cilium/blob/master/proxylib/r2d2/r2d2parser.go>`_) 
that might be used to talk to a simple protocol droid a long time ago in a galaxy far, far away.   
But it also points to other real protocols like Memcached and Cassandra that already exist in the cilium/proxylib 
directory.  

Step 1: Decide on a Basic Policy Model
======================================

To get started, take some time to think about what it means to provide protocol-aware security
in the context of your chosen protocol.   Most protocols follow a common pattern of a client 
who performs an ''operation'' on a ''resource''.   For example: 

- A standard RESTful HTTP request has a GET/POST/PUT/DELETE methods (operation) and URLs (resource).
- A database protocol like MySQL has SELECT/INSERT/UPDATE/DELETE actions (operation) on a combined database + table name (resource).   
- A queueing protocol like Kafka has produce/consume (operation) on a particular queue (resource).    

A common policy model is to allow the user to whitelist certain operations on one or more resources.   
In some cases, the resources need to support regexes to avoid explicit matching on variable content 
like ids (e.g., /users/<uuid> would match /users/.*) 

In our examples, the ''r2d2'' example, we'll use a basic set of operations (READ/WRITE/HALT/RESET). 
The READ and WRITE commands also support a 'filename' resource, while HALT and RESET have no resource.  

Step 2: Understand Protocol, Encoding, Framing and Types
{'fraction_non_alphanumeric': 0.08603988603988603, 'fraction_numerical': 0.005698005698005698, 'mean_word_length': 4.142578125, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6519997', 'n_tokens_mistral': 1434, 'n_tokens_neox': 1380, 'n_words': 735}