[WiP] Documentation changes for egress separation

docs/cmd-coil-egress-controller.md

@@ -0,0 +1,27 @@
+coil-egress-controller
+===============
+
+`coil-egress-controller` is a Kubernetes controller for Coil custom resources related to on-demand NAT egress.
+It is intended to be run as a Pod in `kube-system` namespace.
+
+
+## Egress
+
+`coil-egress-controller` creates **Deployment** and **Service** for each Egress.
+
+It also creates `coil-egress` **ServiceAccount** in the namespace of Egress,
+and binds it to the **ClusterRoles** for `coil-egress`.
+
+## Command-line flags
+
+```
+Flags:
+      --cert-dir string        directory to locate TLS certs for webhook (default "/certs")
+      --egress-port int32      UDP port number used by coil-egress (default 5555)
+      --gc-interval duration   garbage collection interval (default 1h0m0s)
+      --health-addr string     bind address of health/readiness probes (default ":9387")
+  -h, --help                   help for coil-egress-controller
+      --metrics-addr string    bind address of metrics endpoint (default ":9386")
+  -v, --version                version for coil-egress-controller
+      --webhook-addr string    bind address of admission webhook (default ":9443")
+```

docs/cmd-coil-controller.md → docs/cmd-coil-ipam-controller.md

@@ -1,41 +1,33 @@
-coil-controller
+coil-ipam-controller
 ===============
 
-`coil-controller` is a Kubernetes controller for Coil custom resources.
+`coil-ipam-controller` is a Kubernetes controller for Coil IPAM related custom resources.
 It is intended to be run as a Pod in `kube-system` namespace.
 
 ## AddressPool and AddressBlock
 
-`coil-controller` has an in-memory database of address pools and
+`coil-ipam-controller` has an in-memory database of address pools and
 address blocks to allocate address blocks quickly.
 
 ## BlockRequest
 
-`coil-controller` watches newly created block requests and carve out
+`coil-ipam-controller` watches newly created block requests and carve out
 address blocks from the requested pool.
 
-## Egress
-
-`coil-controller` creates **Deployment** and **Service** for each Egress.
-
-It also creates `coil-egress` **ServiceAccount** in the namespace of Egress,
-and binds it to the **ClusterRoles** for `coil-egress`.
-
 ## Garbage collection
 
-`coil-controller` periodically checks orphaned address blocks and deletes them.
+`coil-ipam-controller` periodically checks orphaned address blocks and deletes them.
 
 ## Command-line flags
 
 ```
 Flags:
       --cert-dir string        directory to locate TLS certs for webhook (default "/certs")
-      --egress-port int32      UDP port number used by coil-egress (default 5555)
       --gc-interval duration   garbage collection interval (default 1h0m0s)
       --health-addr string     bind address of health/readiness probes (default ":9387")
-  -h, --help                   help for coil-controller
+  -h, --help                   help for coil-ipam-controller
       --metrics-addr string    bind address of metrics endpoint (default ":9386")
-  -v, --version                version for coil-controller
+  -v, --version                version for coil-ipam-controller
       --webhook-addr string    bind address of admission webhook (default ":9443")
 ```
 

docs/design.md

@@ -73,7 +73,8 @@ Now that we have learned how to do these things, and want to add rich features s
 
 Coil v2 will consist of the following programs:
 
-- `coil-controller`: Kubernetes controller managing custom resources.
+- `coil-ipam-controller`: Kubernetes controller managing IPAM related custom resources.
+- `coil-egress-controller`: Kubernetes controller managing on-demand NAT egress related custom resources.
 - `coild`: Daemon program running on nodes.
 - `coil`: CNI interface that delegates requests from `kubelet` to `coild`.
 - `coil-egress`: Administration program running in Egress pods.
@@ -102,11 +103,11 @@ To make things simple, the default pool is the pool whose name is `default`.
 To reduce the number of advertised routes, addresses in an address pool are divided into fixed-size blocks.
 These blocks are called _address blocks_, and assigned to nodes.  Since all IP addresses in an address block are routed to the same node, only one route per address block need to be advertised.
 
-For example, if an address pool defines that the size of an address block is 2<sup>5</sup>, `coil-controller` will carve an address block for IPv4 with `/27` subnet mask out of the pool, and assigns it to a node.
+For example, if an address pool defines that the size of an address block is 2<sup>5</sup>, `coil-ipam-controller` will carve an address block for IPv4 with `/27` subnet mask out of the pool, and assigns it to a node.
 
 
 In general, avoiding immediate reuse of IP addresses is better not to confuse other software or components.
-To avoid such immediate reuse, `coil-controller` remembers the last used address, and it assigns the address from the next address.
+To avoid such immediate reuse, `coil-ipam-controller` remembers the last used address, and it assigns the address from the next address.
 
 The same problem may occur when we use address blocks of the size `/32`.
 In this case, there is a high chance of reusing the same address immediately.
@@ -333,7 +334,7 @@ Therefore, when the deletion of the owning `AddressPool` is directed, all `Addre
 That said, an `AddressBlock` should not be deleted until there are no more Pods with an address in the block.
 For this purpose, Coil adds a finalizer to each `AddressBlock`.  **`coild` checks the usage of addresses in the block**, and once there are no more Pods using the addresses, it removes the finalizer to delete the `AddressBlock`.
 
-`AddressBlock` should also be deleted when `Node` that acquired the block is deleted.  Since `coild` running as a DaemonSet pod cannot do this, **`coil-controller` watches Node deletions and removes `AddressBlocks`**.  `coil-controller` periodically checks dangling `AddressBlocks` and removes them.
+`AddressBlock` should also be deleted when `Node` that acquired the block is deleted.  Since `coild` running as a DaemonSet pod cannot do this, **`coil-ipam-controller` watches Node deletions and removes `AddressBlocks`**.  `coil-ipam-controller` periodically checks dangling `AddressBlocks` and removes them.
 
 `coild` also deletes `AddressBlock` when it frees the last IP address used in the block.  At startup, `coild` also checks each `AddressBlock` for the Node, and if no Pod is using the addresses in the block, it deletes the `AddressBlock`.
 
@@ -342,7 +343,7 @@ Note that Coil does not include `Node` in the list of owner references of an `Ad
 ### AddressPool
 
 Similar to an `AddressBlock` and its addresses, an `AddressPool` should not be deleted until there are no more `AddressBlock`s derived from the pool.
-For this purpose, Coil adds a finalizer to each `AddressPool`.  `coil-controller` checks the usage of blocks in the pool.
+For this purpose, Coil adds a finalizer to each `AddressPool`.  `coil-ipam-controller` checks the usage of blocks in the pool.
 
 Note that `blockOwnerDeletion: true` in `AddressBlock`'s `ownerReferences` does not always block the deletion of the owning `AddressPool`.
 This directive has effect only when foreground cascading deletion is adopted.
@@ -397,7 +398,7 @@ skinparam rectangle {
 together {
 actor User
 package Deployment {
-    [coil-controller] as controller
+    [coil-ipam-controller] as controller
 }
 database kube-apiserver as apiserver #lightblue {
     [AddressPool] as pool1

docs/setup.md

@@ -57,7 +57,7 @@ $ vi kustomization.yaml
 (actually, the example is a network configuration list).
 
 You may edit the file to, say, add Cilium for network policies or to tune MTU.
-Note that `coil` must be the first in the plugin list.
+Note that `coil` must be the first in the plugin list if IPAM is enabled.
 
 ```console
 vi netconf.json
@@ -76,7 +76,9 @@ The following example adds `tuning` and `bandwidth` plugins.
   "plugins": [
     {
       "type": "coil",
-      "socket": "/run/coild.sock"
+      "socket": "/run/coild.sock",
+      "ipam": true,
+      "egress": true
     },
     {
       "type": "tuning",

v2/kustomization.yaml

@@ -5,7 +5,7 @@ images:
 
 resources:
 - config/default
-# If you are using CKE (github.com/cybozu-go/cke) and wwant to use
+# If you are using CKE (github.com/cybozu-go/cke) and want to use
 # its webhook installation feature, comment the above line and
 # uncomment the below line.
 #- config/cke