Add document that explains the new policies system #512
Conversation
davidor
force-pushed
the
policies-doc
branch
2 times, most recently
from
7497017 to
ce0cdec
Compare
|
@nmasse-itix this might be interesting to you, review/suggestion much welcomed |
| `init_worker`, `rewrite`, `access`, `balancer`, `header_filter`, `body_filter`, | ||
| `post_action`, and `log`. | ||
|
|
||
| Policies can share data between them. They do that through what we call the |
There was a problem hiding this comment.
maybe say "share data between phases" to be even more explicit (or people could understand sharing between policies)
There was a problem hiding this comment.
Both things are possible.
There was a problem hiding this comment.
To clarify, whatever you write in the context will be available in later phases of the same policy and in other policies as well. Do you think that's clear in the document?
| that describes what to run in `access` and `header_filter`. Assume also that | ||
| when describing the chain, we indicate that policy A should be run before | ||
| policy B. When APIcast receives a request, it will check the policy chain | ||
| described to see what it should run on each phase: |
There was a problem hiding this comment.
what would the term/name to use here? "policy chain definition" (sustantivo)
There was a problem hiding this comment.
Not sure what you mean here @andrewdavidmackenzie
doc/policies.md
Outdated
| when describing the chain, we indicate that policy A should be run before | ||
| policy B. When APIcast receives a request, it will check the policy chain | ||
| described to see what it should run on each phase: | ||
| - rewrite: execute what policy A specifies for this phase. |
There was a problem hiding this comment.
"execute the method/function policy A provides for this phase" or similar?
| - post_action: do nothing. Neither policy A nor B describe what to do. | ||
| - log: do nothing. Neither policy A nor B describe what to do. | ||
|
|
||
| Notice that we did not indicate what APIcast does in the `init` and the |
There was a problem hiding this comment.
Instead of describing "in the negative", explain this as part of APIcast start-up before this, then move onto the description of handling requests?
| for a given service. This means that we can apply different policies to our | ||
| services, or the same policies but configured differently, or in a different | ||
| order. On the other hand, there's only one global chain, and the behavior it | ||
| defines applies to all the services. |
There was a problem hiding this comment.
so, policies defined by both chains will be run?
How is order defined between policies in the global chain and policies in the service chain....
There was a problem hiding this comment.
Yes, per-service are included as part of the global one.
There was a problem hiding this comment.
The order of policies in the global chain is configurable. The order of policies in per-service chains is also configurable.
doc/policies.md
Outdated
| [Policy](../gateway/src/apicast/policy.lua) and defines a method for each of | ||
| the phases where it needs to execute something. | ||
|
|
||
| Suppose that we wanted to run a policy that logged some message in the |
There was a problem hiding this comment.
"logged a message"
doc/policies.md
Outdated
| -- Read something from the context. | ||
| local smth = context.something | ||
|
|
||
| -- Write 'b' in the context so other policies or later phases can read it. |
| local _M = policy.new('My custom policy') | ||
| local new = _M.new | ||
|
|
||
| function _M.new(config) |
There was a problem hiding this comment.
Maybe explain when new() is called?
How to store values from the config it receives for use in the per-request methods later?
There was a problem hiding this comment.
I think that documenting when it's instantiated it's too much detail for this document.
Your second question is exactly what I wanted to show with this example. See self.option_a and self.option_b below.
| ``` | ||
|
|
||
| In the [policy folder](../gateway/src/apicast/policy) you can find several | ||
| policies. These ones are quite simple and can be used as examples to write your |
There was a problem hiding this comment.
"They are quite..."
There was a problem hiding this comment.
I don't think that's correct, because I'm not listing all of them, just some examples.
doc/policies.md
Outdated
|
|
||
| ## Integrate your policies | ||
|
|
||
| At some point, it will be possible to configure policies through the 3scale UI, |
There was a problem hiding this comment.
"configure policies and policy chains" ?
doc/policies.md
Outdated
| ## Integrate your policies | ||
|
|
||
| At some point, it will be possible to configure policies through the 3scale UI, | ||
| but you can also integrate them in APIcast using a configuration file. Remember |
There was a problem hiding this comment.
use the same verb: "configure"?
doc/policies.md
Outdated
| Here's an example that shows how to define a policy chain with the CORS policy | ||
| and the APIcast one. Please note that the configuration of services is more | ||
| complex than shown here. This is a very simplified version to illustrate how | ||
| policies can be integrated: |
doc/policies.md
Outdated
| } | ||
| ``` | ||
|
|
||
| If instead of configuring the policy chain of a specific service, you need to |
doc/policies.md
Outdated
|
|
||
| If instead of configuring the policy chain of a specific service, you need to | ||
| customize the global policy chain, you can take a look at | ||
| [this example](../examples/policy_chain/README.md). |
There was a problem hiding this comment.
Good job David and Michal! We're on our way to vast improvements......
davidor
force-pushed
the
policies-doc
branch
2 times, most recently
from
d2f1e29 to
4f96811
Compare
|
Thanks for the review @andrewdavidmackenzie . I addressed all your comments. |
davidor
force-pushed
the
policies-doc
branch
from
4f96811 to
defc79b
Compare
Closes #509
/cc @3scale/documentation