Skip to content

Commit a11c094

Browse files
ADubhlaoichjputrinovepateljjngx
authored
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]>
1 parent d826840 commit a11c094

File tree

6 files changed

+130
-111
lines changed

6 files changed

+130
-111
lines changed

‎examples/custom-resources/access-control/README.md

Lines changed: 2 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,3 @@
1-
# Access Control
1+
# Deploy a Policy for access control
22

3-
In this example, we deploy a web application; configure load balancing for it via a VirtualServer; and apply access
4-
control policies to deny and allow traffic from a specific subnet.
5-
6-
## Prerequisites
7-
8-
1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/)
9-
instructions to deploy the Ingress Controller.
10-
1. Save the public IP address of the Ingress Controller into a shell variable:
11-
12-
```console
13-
IC_IP=XXX.YYY.ZZZ.III
14-
```
15-
16-
1. Save the HTTP port of the Ingress Controller into a shell variable:
17-
18-
```console
19-
IC_HTTP_PORT=<port number>
20-
```
21-
22-
## Step 1 - Deploy a Web Application
23-
24-
Create the application deployment and service:
25-
26-
```console
27-
kubectl apply -f webapp.yaml
28-
```
29-
30-
## Step 2 - Deploy an Access Control Policy
31-
32-
In this step, we create a policy with the name `webapp-policy` that denies requests from clients with an IP that belongs
33-
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
34-
the `deny` field of the `access-control-policy-deny.yaml` according to your environment (use the subnet of your
35-
machine).
36-
37-
Create the policy:
38-
39-
```console
40-
kubectl apply -f access-control-policy-deny.yaml
41-
```
42-
43-
## Step 3 - Configure Load Balancing
44-
45-
Create a VirtualServer resource for the web application:
46-
47-
```console
48-
kubectl apply -f virtual-server.yaml
49-
```
50-
51-
Note that the VirtualServer references the policy `webapp-policy` created in Step 2.
52-
53-
## Step 4 - Test the Configuration
54-
55-
Let's access the application:
56-
57-
```console
58-
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
59-
```
60-
61-
```text
62-
<html>
63-
<head><title>403 Forbidden</title></head>
64-
<body>
65-
<center><h1>403 Forbidden</h1></center>
66-
</body>
67-
</html>
68-
```
69-
70-
We got a 403 response from NGINX, which means that our policy successfully blocked our request.
71-
72-
## Step 5 - Update the Policy
73-
74-
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
75-
`allow` field of the `access-control-policy-allow.yaml` according to your environment.
76-
77-
Update the policy:
78-
79-
```console
80-
kubectl apply -f access-control-policy-allow.yaml
81-
```
82-
83-
## Step 6 - Test the Configuration
84-
85-
Let's access the application again:
86-
87-
```console
88-
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
89-
```
90-
91-
```text
92-
Server address: 10.64.0.13:8080
93-
Server name: webapp-5cbbc7bd78-wf85w
94-
```
95-
96-
In contrast with Step 4, we got a 200 response, which means that our updated policy successfully allowed our request.
3+
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.

‎site/content/configuration/access-control.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Deploy a Policy for access control
3+
weight: 900
4+
toc: true
5+
docs: DOCS-000
6+
---
7+
8+
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" >}}).
9+
10+
---
11+
12+
## Before you begin
13+
14+
You should have a [working NGINX Ingress Controller]({{< ref "/installation/installing-nic/installation-with-helm.md" >}}) instance.
15+
16+
For ease of use in shell commands, set two shell variables:
17+
18+
1. The public IP address for your NGINX Ingress Controller instance.
19+
20+
```shell
21+
IC_IP=<ip-address>
22+
```
23+
24+
2. The HTTP port of the same instance.
25+
26+
```shell
27+
IC_HTTP_PORT=<port number>
28+
```
29+
30+
---
31+
32+
## Deploy the example application
33+
34+
Create the file _webapp.yaml_ with the following contents:
35+
36+
{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/webapp.yaml" >}}
37+
38+
Apply it using `kubectl`:
39+
40+
```shell
41+
kubectl apply -f webapp.yaml
42+
```
43+
44+
---
45+
46+
## Deploy a Policy to create a deny rule
47+
48+
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.
49+
50+
{{< 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" >}}
51+
52+
Apply the policy:
53+
54+
```shell
55+
kubectl apply -f access-control-policy-deny.yaml
56+
```
57+
58+
---
59+
60+
## Configure load balancing
61+
62+
Create a file named _virtual-server.yaml_ for the VirtualServer resource. The _policies_ field references the access control Policy created in the previous section.
63+
64+
{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/virtual-server.yaml" "hl_lines=7-8" >}}
65+
66+
Apply the policy:
67+
68+
```shell
69+
kubectl apply -f virtual-server.yaml
70+
```
71+
72+
---
73+
74+
## Test the example application
75+
76+
Use `curl` to attempt to access the application:
77+
78+
```shell
79+
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
80+
```
81+
```text
82+
<html>
83+
<head><title>403 Forbidden</title></head>
84+
<body>
85+
<center><h1>403 Forbidden</h1></center>
86+
</body>
87+
</html>
88+
```
89+
90+
The *403* response is expected, successfully blocking your machine.
91+
92+
---
93+
94+
## Update the Policy to create an allow rule
95+
96+
Update the Policy with the file _access-control-policy-allow.yaml_, setting the _allow_ field to the subnet of your machine.
97+
98+
{{< 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" >}}
99+
100+
Apply the Policy:
101+
102+
```shell
103+
kubectl apply -f access-control-policy-allow.yaml
104+
```
105+
106+
----
107+
108+
## Verify the Policy update
109+
110+
Attempt to access the application again:
111+
112+
```shell
113+
curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
114+
```
115+
```text
116+
Server address: 10.64.0.13:8080
117+
Server name: webapp-5cbbc7bd78-wf85w
118+
```
119+
120+
The successful response demonstrates that the policy has been updated.

‎site/content/configuration/host-and-listener-collisions.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
---
2-
docs: DOCS-590
3-
doctypes:
4-
- ''
52
title: Host and Listener collisions
63
toc: true
7-
weight: 1700
4+
weight: 800
5+
docs: DOCS-590
86
---
97

108
This document explains how F5 NGINX Ingress Controller handles host and listener collisions between resources.

‎site/content/configuration/policy-resource.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
---
2-
docs: DOCS-596
3-
doctypes:
4-
- ''
52
title: Policy resources
63
toc: true
7-
weight: 600
4+
weight: 500
5+
docs: DOCS-596
86
---
97

108
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/).

‎site/content/configuration/transportserver-resource.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
---
2-
docs: DOCS-598
3-
doctypes:
4-
- ''
52
title: TransportServer resources
63
toc: true
7-
weight: 700
4+
weight: 600
5+
docs: DOCS-598
86
---
97

108
This document is reference material for the TransportServer resource used by F5 NGINX Ingress Controller.

‎site/content/configuration/virtualserver-and-virtualserverroute-resources.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
---
2-
docs: DOCS-599
3-
doctypes:
4-
- ''
52
title: VirtualServer and VirtualServerRoute resources
63
toc: true
7-
weight: 1600
4+
weight: 700
5+
docs: DOCS-599
86
---
97

108
This document is reference material for the VirtualServer and VirtualServerRoute resources used by F5 NGINX Ingress Controller.

0 commit comments

Comments
 (0)