diff --git a/docs/book/src/clusteropenstack/configuration.md b/docs/book/src/clusteropenstack/configuration.md
index c8022efee4..fedb2eec9c 100644
--- a/docs/book/src/clusteropenstack/configuration.md
+++ b/docs/book/src/clusteropenstack/configuration.md
@@ -206,6 +206,30 @@ spec:
        name: <subnet-name>
 ```
 
+## Ports
+
+A server can also be connected to networks by describing what ports to create. Describing a server's connection with `ports` allows for finer and more advanced configuration. For example, you can specify per-port security groups, fixed IPs or VNIC type.
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4
+kind: OpenStackMachine
+metadata:
+  name: <cluster-name>-controlplane
+  namespace: <cluster-name>
+spec:
+  ports:
+  - networkId: <your-network-id>
+    description: <your-custom-port-description>
+    vnicType: normal
+    fixedIPs:
+    - subnetId: <your-subnet-id>
+      ipAddress: <your-fixed-ip>
+    securityGroups:
+    - <your-security-group-id>
+```
+
+Any such ports are created in addition to ports used for connections to networks or subnets.
+
 ## Tagging
 
 If your cluster supports tagging servers, you have the ability to tag all resources created by the cluster in the `cluster.yaml` file. Here is an example how to configure tagging: