Update externally-managed-infrastructure docs (#122) (#123)

Added a callout and link to more documentation with more networking
examples to better help users locate the more in-depth docs.

fixes #121

Author: joekr

docs/src/SUMMARY.md

@@ -19,7 +19,7 @@
   - [Install Cluster API for Oracle Cloud Infrastructure](./gs/install-cluster-api.md)
   - [Create Workload Cluster](./gs/create-workload-cluster.md)
   - [Create Workload Templates](./gs/create-workload-templates.md)
-  - [Using externally managed infrastructure](./gs/externally-managed-infrastructure.md)
+  - [Using externally managed infrastructure](./gs/externally-managed-cluster-infrastructure.md)
   - [Install Oracle Cloud Infrastructure Cloud Controller Manager](./gs/install-oci-ccm.md)
   - [Install Container Storage Interface (CSI)](./gs/install-csi.md)
     - [Provision a PVC on the Block Volume Service](./gs/pvc-bv.md)

docs/src/gs/externally-managed-infrastructure.md renamed to docs/src/gs/externally-managed-cluster-infrastructure.md

@@ -1,19 +1,62 @@
-# Externally managed infrastructure
+# Externally managed Cluster infrastructure
 
 By default, Cluster API will create resources on Oracle Cloud Infrastructure (OCI) when instantiating a new workload cluster. However, it is possible to have Cluster API re-use an existing OCI infrastructure instead of creating a new one. The existing infrastructure could include:
 
  1. Virtual cloud networks (VCNs)
  1. Network load balancers used as Kubernetes API Endpoint
 
+## Example spec for externally managed VCN infrastructure
+
+CAPOCI can be used to create a cluster using existing VCN infrastructure. In this case, only the
+API Server Load Balancer will be managed by CAPOCI.
+
+Example spec is given below
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: OCICluster
+metadata:
+  name: "${CLUSTER_NAME}"
+spec:
+  compartmentId: "${OCI_COMPARTMENT_ID}"
+  networkSpec:
+    skipNetworkManagement: true
+    vcn:
+      id: <Insert VCN OCID Here>
+      networkSecurityGroups:
+        - id: <Insert Control Plane Endpoint NSG OCID Here>
+          role: control-plane-endpoint
+          name: control-plane-endpoint
+        - id: <Insert Worker NSG OCID Here>
+          role: worker
+          name: worker
+        - id: <Insert Control Plane NSG OCID Here>
+          role: control-plane
+          name: control-plane
+      subnets:
+        - id: <Insert Control Plane Endpoint Subnet OCID Here>
+          role: control-plane-endpoint
+          name: control-plane-endpoint
+        - id: <Insert Worker Subnet OCID Here>
+          role: worker
+          name: worker
+        - id: <Insert control Plane Subnet OCID Here>
+          role: control-plane
+          name: control-plane
+```
+
+In the above spec, note that name has to be mentioned for Subnet/NSG. This is so that Kubernetes
+can merge the list properly when there is an update.
+
+## Example `OCICluster` Spec with external infrastructure
+
 CAPOCI supports [externally managed cluster infrastructure](https://github.com/kubernetes-sigs/cluster-api/blob/10d89ceca938e4d3d94a1d1c2b60515bcdf39829/docs/proposals/20210203-externally-managed-cluster-infrastructure.md).
 
 If the `OCICluster` resource includes a `cluster.x-k8s.io/managed-by` annotation, then the [controller will skip any reconciliation](https://cluster-api.sigs.k8s.io/developer/providers/cluster-infrastructure.html#normal-resource).
 
 This is useful for scenarios where a different persona is managing the cluster infrastructure out-of-band while still wanting to use CAPOCI for automated machine management.
 
-## Example `OCICluster` Spec with external infrastructure
-
-The following `OCICluster` Spec includes the mandatory fields to be specified for externally managed infrastructure to work properly.
+The following `OCICluster` Spec includes the mandatory fields to be specified for externally managed infrastructure to work properly. In this example neither the VCN nor the network load balancer will be managed by CAPOCI.
 
 ```yaml
 apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
@@ -87,3 +130,4 @@ curl -o  -s -X PATCH -H "Accept: application/json, */*" \
 https://<management-plane-api-endpoint>/apis/infrastructure.cluster.x-k8s.io/v1beta1/namespaces/<cluster-namespace>/ociclusters/<cluster-name>/status \
 --data '{"status":{"ready":true,"failureDomains":{"1":{"attributes":{"AvailabilityDomain":"zkJl:US-ASHBURN-1-AD-1"},"controlPlane":true},"2":{"attributes":{"AvailabilityDomain":"zkJl:US-ASHBURN-1-AD-2"},"controlPlane":true},"3":{"attributes":{"AvailabilityDomain":"zkJl:US-ASHBURN-1-AD-3"}}}}}'
 ```
+

docs/src/networking/custom-networking.md

@@ -275,45 +275,10 @@ Related documentation: [comparison of Security Lists and Network Security Groups
 
 ## Example spec for externally managed VCN infrastructure
 
-CAPOCI can be used to create a cluster using existing VCN infrastructure. In this case, only the
-API Server Load Balancer will be managed by CAPOCI.
-
-Example spec is given below
-
-```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
-kind: OCICluster
-metadata:
-  name: "${CLUSTER_NAME}"
-spec:
-  compartmentId: "${OCI_COMPARTMENT_ID}"
-  networkSpec:
-    skipNetworkManagement: true
-    vcn:
-      id: <Insert VCN OCID Here>
-      networkSecurityGroups:
-        - id: <Insert Control Plane Endpoint NSG OCID Here>
-          role: control-plane-endpoint
-          name: control-plane-endpoint
-        - id: <Insert Worker NSG OCID Here>
-          role: worker
-          name: worker
-        - id: <Insert Control Plane NSG OCID Here>
-          role: control-plane
-          name: control-plane
-      subnets:
-        - id: <Insert Control Plane Endpoint Subnet OCID Here>
-          role: control-plane-endpoint
-          name: control-plane-endpoint
-        - id: <Insert Worker Subnet OCID Here>
-          role: worker
-          name: worker
-        - id: <Insert control Plane Subnet OCID Here>
-          role: control-plane
-          name: control-plane
+```admonish info
+See [externally managed infrastructure][externally-managed-cluster-infrastructure] for how to create a cluster
+using existing VCN infrastructure.
 ```
 
-In the above spec, note that name has to be mentioned for Subnet/NSG. This is so that Kubernetes
-can merge the list properly when there is an update.
-
 [sl-vs-nsg]: https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/securityrules.htm#comparison
+[externally-managed-cluster-infrastructure]: ../gs/externally-managed-cluster-infrastructure.md#example-spec-for-externally-managed-vcn-infrastructure