Create a doc to help people get started on policy development

[andrewdavidmackenzie]

[provide a description of the issue]
People have requested a few pointers to get them started on policy development, and som eresources they can use to accelerate their learning

Expected Result

I have gathered these links from people as a starting point, and categories where more resources would be appreciated:

Writing APIcast Policies

Learning LUA
Focus on lua 5.1/5.2

Learning LUA: read https://www.lua.org/manual/5.1/
Which links to https://www.lua.org/pil/
Learning NGINX and OpenResty
Lean about NGINX config, phases, and OpenResty lua API and what can and can't be done..

https://openresty.org/download/agentzh-nginx-tutorials-en.html

https://github.com/openresty/lua-nginx-module - the full doc on the openresty directives
blog posts
http://openresty.org/en/resources.html
OpenResty Hello World
http://openresty.org/en/getting-started.html
APIcast Policy Framework
Phases for writing apicast policies
Order of Policies & Phases
Writing tests

[nmasse-itix]

Hello,

I would be interested in contributing to this topic, either writing or proofreading !

[andrewdavidmackenzie]

PRs welcome Nicolas.... you can start with above (just notes gathered from Michal and others) and your own experience and get the ball rolling! Maybe @alanmoran and others can then contribute too!
Thanks for the offer of help!

[alanmoran]

👍 for contributing. I took some notes of my journey a while back so will dig that out. Will be good to start fresh and document our path through each of the sections. A good idea might be actually to build a real-world policy as part of the policy and document as we go. I'll have a think about that 🤔

[andrewdavidmackenzie]

Thanks @alanmoran sounds like @nmasse-itix is willing to get the ball rolling with an initial PR< then maybe you can add to it?

[nmasse-itix]

Here is the plan I had in my mind :

1 : setup your development environment and hello world

• install required software
• build apicast
• configure apicast with a mocked backend or with the 3scale backend
• make sure it works
• create an hello world policy
• test it

2 : nginx phases, openresty apis

• what you can do in which phase
• where to get more information about OpenResty
• which APIs you can use from OpenResty and which one have been replaced by an equivalent in APIcast
• common use cases: making an HTTP request, forwarding a request to a backend

3 : Policy design rules

• using the context
• configuration: how to specify the configuration of your policy

4 : Unit testing

• how to use the unit testing framework of Apicast

5 : Packaging your policy

• using external libraries
• building the final Docker image

What do you think ? @alanmoran do you see additional topics you would like to cover ?

Since it's quite a large amount of work, I planned to make a PR per chapter so that we don't have to wait too long for having something.

[andrewdavidmackenzie]

Hi Nicolas, that sounds like a good HOWTO...

the origin o fall of this was more a "things I need to learn first, and where to find resources to help me learn it"

so you might want to consider a section for that also (without scaring people off! :-) )

[nmasse-itix]

Yes, sure ! 😁

[y-tabata]

I think "Integration testing" is necessary after "Unit testing".
And we should do the schema testing using ajv if possible, because s2i-builder checks the schema and sometimes we cannot find the schema errors in the unit testing or the integration testing.

[pimg]

I would also like to be involved, by reviewing/proofreading or testing out the documentation. Been doing a lot of learning lately in the Openresty area, still an ongoing journey for me. But this sounds like a good place to get some participation in.