Migrate access control example to documentation website #6572
Conversation
This commit migrates the access control example to the documentation website, converting the existing README into a page formatted for the production website. It also cleans up the frontmatter of the surrounding documents so that pages can be more easily re-arranged in the future. The converted page make use of single source embedded code blocks using files in the GitHub repository, as well as a highlighting feature of code blocks that has not been used in previous documentation.
✅ Deploy Preview will be available once build job completes!
|
for more information, see https://pre-commit.ci
…es-ingress into docs/example-migration
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #6572 +/- ##
==========================================
- Coverage 53.08% 53.00% -0.08%
==========================================
Files 87 87
Lines 16200 16223 +23
==========================================
Hits 8599 8599
- Misses 7194 7217 +23
Partials 407 407 ☔ View full report in Codecov by Sentry. |
|
|
||
| --- | ||
|
|
||
| ## Deploy an Access Control policy |
There was a problem hiding this comment.
| ## Deploy an Access Control policy | |
| ## Deploy a Policy to deny access to your app |
There was a problem hiding this comment.
The focus of the document as a whole is to show how to deploy an Access Control policy: the deny and allow steps existence in sequence to demonstrate this, so I don't think it makes sense to make the policy the focus nor is it necessary to be this explicit.
There was a problem hiding this comment.
You're using the same text as the title of the document in a sub-heading, which is confusing for users. If the broad goal of the doc is to deploy an access control policy, and I complete this section, am I now done with the doc? Why are there more sections? It makes more sense to me to have the sub-headings accurately reflect the expected outcome of completing the steps in the section.
|
|
||
| --- | ||
|
|
||
| ## Update the policy |
There was a problem hiding this comment.
| ## Update the policy | |
| ## Deploy a Policy to allow access to your app |
There was a problem hiding this comment.
The focus of the document as a whole is to show how to deploy an Access Control policy: the deny and allow steps existence in sequence to demonstrate this, so I don't think it makes sense to make the policy the focus nor is it necessary to be this explicit.
There was a problem hiding this comment.
@vepatel Within the context of Kubernetes configuration, I have always thought of a Policy as the live configuration being updated by YAML files.
Is it more accurate to describe the YAML files themselves as separate Policies? The YAML files are ephemeral, so it feels odd to me.
There was a problem hiding this comment.
We are not asking the user to apply an update to their policy here; we're asking them to apply a new policy file, with a different name. Just from that standpoint, the heading of "update the policy" is misleading. Aside from that, the subheading should accurately reflect what the user is being instructed to do. In this case, that is deploying a policy to allow traffic.
This also helps with SEO, so people who are searching specifically for how to deploy an allow or deny policy will easily find the section with the right instructions.
There was a problem hiding this comment.
Just to clarify, the Policy here is called webapp-policy so even though the updates are in two separate files, only one Policy is being updated.
Co-authored-by: Jodie Putrino <[email protected]> Signed-off-by: Alan Dooley <[email protected]>
| docs: DOCS-000 | ||
| --- | ||
|
|
||
| This topic describes how to apply and update an Access Control policy with F5 NGINX Ingress Controller. |
There was a problem hiding this comment.
I think we should capitalise Policy, as its a resource type, the same way Ingress is, which tends to be capitalised in our docs, eg here
There was a problem hiding this comment.
I'll think a bit about this - the challenge around it is that policy exists as a general noun, whereas a Policy is a resource in context.
There's technically no such thing as an "Access Control Policy" in terms of specificity, so I might change this to something along the lines of "Managing access control using a Policy".
Proposed changes
This pull request migrates the access control example to the documentation website, converting the existing README into a page formatted for the production website. It also cleans up the frontmatter of the surrounding documents so that pages can be more easily re-arranged in the future.
The converted page makes use of single source embedded code blocks using files in the GitHub repository, as well as a highlighting feature of code blocks that has not been used in previous documentation.
Checklist
Before creating a PR, run through this checklist and mark each as complete.