From 23d261728c7667c3eb716bc72fade41ab995aa6d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 2 Oct 2024 12:13:24 +0100 Subject: [PATCH 1/6] Migrate access control example to documentation website 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. --- .../custom-resources/access-control/README.md | 97 +------------- site/content/configuration/access-control.md | 122 ++++++++++++++++++ .../host-and-listener-collisions.md | 6 +- site/content/configuration/policy-resource.md | 6 +- .../configuration/transportserver-resource.md | 6 +- ...server-and-virtualserverroute-resources.md | 6 +- 6 files changed, 132 insertions(+), 111 deletions(-) create mode 100644 site/content/configuration/access-control.md diff --git a/examples/custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md index 88fbee9f7b..57d68551f7 100644 --- a/examples/custom-resources/access-control/README.md +++ b/examples/custom-resources/access-control/README.md @@ -1,96 +1,3 @@ -# Access Control +## Deploy an Access Control policy -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= - ``` - -## 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 - -403 Forbidden - -

403 Forbidden

- - -``` - -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 an Access Control policy](https://docs.nginx.com/nginx-ingress-controller/configuration/access-control/) documentation. \ No newline at end of file diff --git a/site/content/configuration/access-control.md b/site/content/configuration/access-control.md new file mode 100644 index 0000000000..b1cffba3ba --- /dev/null +++ b/site/content/configuration/access-control.md @@ -0,0 +1,122 @@ +--- +title: Deploy an Access Control policy +weight: 900 +toc: true +docs: DOCS-000 +--- + +This topic describes how to apply and update an Access Control policy with F5 NGINX Ingress Controller. + +It demonstrates this 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= +``` + +2. The HTTP port of the same instance + +```shell +IC_HTTP_PORT= +``` + +--- + +## 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 an Access Control policy + +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 example application. + +{{< 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 + +403 Forbidden + +

403 Forbidden

+ + +``` + +The *403* response is expected, successfully blocking your machine. + +--- + +## Update the policy + +Create a new policy with the file *access-control-policy-allow.yaml*, updating 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. \ No newline at end of file diff --git a/site/content/configuration/host-and-listener-collisions.md b/site/content/configuration/host-and-listener-collisions.md index 6ff29cbeb3..53485d3062 100644 --- 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 index 9a66d819c6..f5e4005432 100644 --- 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 index d49588006c..f39648a482 100644 --- 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 index bfc316385a..f7695fb3a3 100644 --- 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. From fabb85041aeb90b1492c1b7f97d56b0c274f6e2b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 2 Oct 2024 11:19:09 +0000 Subject: [PATCH 2/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- examples/custom-resources/access-control/README.md | 2 +- site/content/configuration/access-control.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md index 57d68551f7..7d07945ac7 100644 --- a/examples/custom-resources/access-control/README.md +++ b/examples/custom-resources/access-control/README.md @@ -1,3 +1,3 @@ ## Deploy an Access Control policy -This is the example code used in the [Deploy an Access Control policy](https://docs.nginx.com/nginx-ingress-controller/configuration/access-control/) documentation. \ No newline at end of file +This is the example code used in the [Deploy an Access Control policy](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 index b1cffba3ba..1b0004a70b 100644 --- a/site/content/configuration/access-control.md +++ b/site/content/configuration/access-control.md @@ -119,4 +119,4 @@ Server address: 10.64.0.13:8080 Server name: webapp-5cbbc7bd78-wf85w ``` -The successful response demonstrates that the policy has been updated. \ No newline at end of file +The successful response demonstrates that the policy has been updated. From 03da540bcc29a783c68ae902ac88d81a6403c798 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 2 Oct 2024 12:25:29 +0100 Subject: [PATCH 3/6] Update Markdown heading for linter compliance --- examples/custom-resources/access-control/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md index 57d68551f7..2bf3674dcc 100644 --- a/examples/custom-resources/access-control/README.md +++ b/examples/custom-resources/access-control/README.md @@ -1,3 +1,3 @@ -## Deploy an Access Control policy +# Deploy an Access Control policy This is the example code used in the [Deploy an Access Control policy](https://docs.nginx.com/nginx-ingress-controller/configuration/access-control/) documentation. \ No newline at end of file From d74164cdb5db2e9d99a2e78537d3dbcb8cf1bcf4 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 10 Oct 2024 12:33:16 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Jodie Putrino Signed-off-by: Alan Dooley --- site/content/configuration/access-control.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/configuration/access-control.md b/site/content/configuration/access-control.md index 1b0004a70b..d68b5ccfb4 100644 --- a/site/content/configuration/access-control.md +++ b/site/content/configuration/access-control.md @@ -23,7 +23,7 @@ For ease of use in shell commands, set two shell variables: IC_IP= ``` -2. The HTTP port of the same instance +2. The HTTP port of the same instance. ```shell IC_HTTP_PORT= @@ -61,7 +61,7 @@ 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 example application. +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" >}} From f4484febe977db138d2dbd0e794403f475d39bde Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 10 Oct 2024 12:40:14 +0100 Subject: [PATCH 5/6] Update formatting --- site/content/configuration/access-control.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/site/content/configuration/access-control.md b/site/content/configuration/access-control.md index d68b5ccfb4..cc5bcc6b87 100644 --- a/site/content/configuration/access-control.md +++ b/site/content/configuration/access-control.md @@ -33,11 +33,11 @@ IC_HTTP_PORT= ## Deploy the example application -Create the file *webapp.yaml* with the following contents: +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*: +Apply it using `kubectl`: ```shell kubectl apply -f webapp.yaml @@ -47,7 +47,7 @@ kubectl apply -f webapp.yaml ## Deploy an Access Control policy -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. +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" >}} @@ -61,7 +61,7 @@ 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. +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" >}} @@ -75,7 +75,7 @@ kubectl apply -f virtual-server.yaml ## Test the example application -Use *curl* to attempt to access the 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 @@ -95,7 +95,7 @@ The *403* response is expected, successfully blocking your machine. ## Update the policy -Create a new policy with the file *access-control-policy-allow.yaml*, updating the *allow* field to the subnet of your machine. +Create a new policy with the file _access-control-policy-allow.yaml_, updating 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" >}} From 0825f18f7732b5b975eb7d297763b2b5387b8b39 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Oct 2024 15:42:03 +0100 Subject: [PATCH 6/6] Update document to shift the subject focus the Policy object --- .../custom-resources/access-control/README.md | 4 ++-- site/content/configuration/access-control.md | 16 +++++++--------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/examples/custom-resources/access-control/README.md b/examples/custom-resources/access-control/README.md index 9f4dd25618..30e5709c5e 100644 --- a/examples/custom-resources/access-control/README.md +++ b/examples/custom-resources/access-control/README.md @@ -1,3 +1,3 @@ -# Deploy an Access Control policy +# Deploy a Policy for access control -This is the example code used in the [Deploy an Access Control policy](https://docs.nginx.com/nginx-ingress-controller/configuration/access-control/) documentation. +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 index cc5bcc6b87..2ff06fabc3 100644 --- a/site/content/configuration/access-control.md +++ b/site/content/configuration/access-control.md @@ -1,13 +1,11 @@ --- -title: Deploy an Access Control policy +title: Deploy a Policy for access control weight: 900 toc: true docs: DOCS-000 --- -This topic describes how to apply and update an Access Control policy with F5 NGINX Ingress Controller. - -It demonstrates this using an example application and a [VirtualServer custom resource]({{< ref "/configuration/virtualserver-and-virtualserverroute-resources.md" >}}) +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" >}}). --- @@ -45,7 +43,7 @@ kubectl apply -f webapp.yaml --- -## Deploy an Access Control policy +## 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. @@ -93,13 +91,13 @@ The *403* response is expected, successfully blocking your machine. --- -## Update the policy +## Update the Policy to create an allow rule -Create a new policy with the file _access-control-policy-allow.yaml_, updating the _allow_ field to the subnet of your machine. +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: +Apply the Policy: ```shell kubectl apply -f access-control-policy-allow.yaml @@ -107,7 +105,7 @@ kubectl apply -f access-control-policy-allow.yaml ---- -## Verify the policy update +## Verify the Policy update Attempt to access the application again: