From 23d261728c7667c3eb716bc72fade41ab995aa6d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 2 Oct 2024 12:13:24 +0100 Subject: [PATCH 1/3] 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/3] [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/3] 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