Migrate access control example to documentation website (#6572)

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. Co-authored-by: Jodie Putrino <[email protected]> Co-authored-by: Venktesh Shivam Patel <[email protected]> Co-authored-by: Jakub Jarosz <[email protected]>
nginxinc · Oct 21, 2024 · a11c094 · a11c094
1 parent d826840
commit a11c094
Show file tree

Hide file tree

Showing 6 changed files with 130 additions and 111 deletions.
diff --git a/examples/custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md
@@ -1,96 +1,3 @@
-# Access Control
+# Deploy a Policy for access control
 
-In this example, we deploy a web application; configure load balancing for it via a VirtualServer; and apply access
-control policies to deny and allow traffic from a specific subnet.
-
-## Prerequisites
-
-1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/)
-   instructions to deploy the Ingress Controller.
-1. Save the public IP address of the Ingress Controller into a shell variable:
-
-    ```console
-    IC_IP=XXX.YYY.ZZZ.III
-    ```
-
-1. Save the HTTP port of the Ingress Controller into a shell variable:
-
-    ```console
-    IC_HTTP_PORT=<port number>
-    ```
-
-## Step 1 - Deploy a Web Application
-
-Create the application deployment and service:
-
-```console
-kubectl apply -f webapp.yaml
-```
-
-## Step 2 - Deploy an Access Control Policy
-
-In this step, we create a policy with the name `webapp-policy` that denies requests from clients with an IP that belongs
-to the subnet `10.0.0.0/8`. This is the subnet that our test client in Steps 4 and 6 will belong to. Make sure to change
-the `deny` field of the `access-control-policy-deny.yaml` according to your environment (use the subnet of your
-machine).
-
-Create the policy:
-
-```console
-kubectl apply -f access-control-policy-deny.yaml
-```
-
-## Step 3 - Configure Load Balancing
-
-Create a VirtualServer resource for the web application:
-
-```console
-kubectl apply -f virtual-server.yaml
-```
-
-Note that the VirtualServer references the policy `webapp-policy` created in Step 2.
-
-## Step 4 - Test the Configuration
-
-Let's access the application:
-
-```console
-curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
-```
-
-```text
-<html>
-<head><title>403 Forbidden</title></head>
-<body>
-<center><h1>403 Forbidden</h1></center>
-</body>
-</html>
-```
-
-We got a 403 response from NGINX, which means that our policy successfully blocked our request.
-
-## Step 5 - Update the Policy
-
-In this step, we update the policy to allow requests from clients from the subnet `10.0.0.0/8`. Make sure to change the
-`allow` field of the `access-control-policy-allow.yaml` according to your environment.
-
-Update the policy:
-
-```console
-kubectl apply -f access-control-policy-allow.yaml
-```
-
-## Step 6 - Test the Configuration
-
-Let's access the application again:
-
-```console
-curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
-```
-
-```text
-Server address: 10.64.0.13:8080
-Server name: webapp-5cbbc7bd78-wf85w
-```
-
-In contrast with Step 4, we got a 200 response, which means that our updated policy successfully allowed our request.
+This is the example code used in the [Deploy a Policy for access control](https://docs.nginx.com/nginx-ingress-controller/configuration/access-control/) documentation.
diff --git a/site/content/configuration/access-control.md b/site/content/configuration/access-control.md
@@ -0,0 +1,120 @@
+---
+title: Deploy a Policy for access control
+weight: 900
+toc: true
+docs: DOCS-000
+---
+
+This topic describes how to use F5 NGINX Ingress Controller to apply and update a Policy for access control. It demonstrates it using an example application and a [VirtualServer custom resource]({{< ref "/configuration/virtualserver-and-virtualserverroute-resources.md" >}}).
+
+---
+
+## Before you begin
+
+You should have a [working NGINX Ingress Controller]({{< ref "/installation/installing-nic/installation-with-helm.md" >}}) instance.
+
+For ease of use in shell commands, set two shell variables:
+
+1. The public IP address for your NGINX Ingress Controller instance.
+
+```shell
+IC_IP=<ip-address>
+```
+
+2. The HTTP port of the same instance.
+
+```shell
+IC_HTTP_PORT=<port number>
+```
+
+---
+
+## Deploy the example application
+
+Create the file _webapp.yaml_ with the following contents:
+
+{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/webapp.yaml" >}}
+
+Apply it using `kubectl`:
+
+```shell
+kubectl apply -f webapp.yaml
+```
+
+---
+
+## Deploy a Policy to create a deny rule
+
+Create a file named _access-control-policy-deny.yaml_. The highlighted _deny_ field will be used by the example application, and should be changed to the subnet of your machine.
+
+{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/access-control-policy-deny.yaml" "hl_lines=7-8" >}}
+
+Apply the policy:
+
+```shell
+kubectl apply -f access-control-policy-deny.yaml
+```
+
+---
+
+## Configure load balancing
+
+Create a file named _virtual-server.yaml_ for the VirtualServer resource. The _policies_ field references the access control Policy created in the previous section.
+
+{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/virtual-server.yaml" "hl_lines=7-8" >}}
+
+Apply the policy:
+
+```shell
+kubectl apply -f virtual-server.yaml
+```
+
+---
+
+## Test the example application
+
+Use `curl` to attempt to access the application:
+
+```shell
+curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
+```
+```text
+<html>
+<head><title>403 Forbidden</title></head>
+<body>
+<center><h1>403 Forbidden</h1></center>
+</body>
+</html>
+```
+
+The *403* response is expected, successfully blocking your machine.
+
+---
+
+## Update the Policy to create an allow rule
+
+Update the Policy with the file _access-control-policy-allow.yaml_, setting the _allow_ field to the subnet of your machine.
+
+{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/access-control-policy-allow.yaml" "hl_lines=7-8" >}}
+
+Apply the Policy:
+
+```shell
+kubectl apply -f access-control-policy-allow.yaml
+```
+
+----
+
+## Verify the Policy update
+
+Attempt to access the application again:
+
+```shell
+curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
+```
+```text
+Server address: 10.64.0.13:8080
+Server name: webapp-5cbbc7bd78-wf85w
+```
+
+The successful response demonstrates that the policy has been updated.
diff --git a/site/content/configuration/host-and-listener-collisions.md b/site/content/configuration/host-and-listener-collisions.md
@@ -1,10 +1,8 @@
 ---
-docs: DOCS-590
-doctypes:
-- ''
 title: Host and Listener collisions
 toc: true
-weight: 1700
+weight: 800
+docs: DOCS-590
 ---
 
 This document explains how F5 NGINX Ingress Controller handles host and listener collisions between resources.

diff --git a/site/content/configuration/policy-resource.md b/site/content/configuration/policy-resource.md
@@ -1,10 +1,8 @@
 ---
-docs: DOCS-596
-doctypes:
-- ''
 title: Policy resources
 toc: true
-weight: 600
+weight: 500
+docs: DOCS-596
 ---
 
 The Policy resource allows you to configure features like access control and rate-limiting, which you can add to your [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/).

diff --git a/site/content/configuration/transportserver-resource.md b/site/content/configuration/transportserver-resource.md
@@ -1,10 +1,8 @@
 ---
-docs: DOCS-598
-doctypes:
-- ''
 title: TransportServer resources
 toc: true
-weight: 700
+weight: 600
+docs: DOCS-598
 ---
 
 This document is reference material for the TransportServer resource used by F5 NGINX Ingress Controller. 

diff --git a/site/content/configuration/virtualserver-and-virtualserverroute-resources.md b/site/content/configuration/virtualserver-and-virtualserverroute-resources.md
@@ -1,10 +1,8 @@
 ---
-docs: DOCS-599
-doctypes:
-- ''
 title: VirtualServer and VirtualServerRoute resources
 toc: true
-weight: 1600
+weight: 700
+docs: DOCS-599
 ---
 
 This document is reference material for the VirtualServer and VirtualServerRoute resources used by F5 NGINX Ingress Controller.