From 41f9e23ca05ae61534a3dc6ab2b14d61832da0b6 Mon Sep 17 00:00:00 2001
From: John Gardiner Myers <jgmyers@proofpoint.com>
Date: Sat, 30 Oct 2021 15:06:20 -0700
Subject: [PATCH] Add initial IPv6 documentation

---
 docs/networking/ipv6.md | 37 +++++++++++++++++++++++++++++++++++++
 mkdocs.yml              |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 docs/networking/ipv6.md

diff --git a/docs/networking/ipv6.md b/docs/networking/ipv6.md
new file mode 100644
index 0000000000..e40636304e
--- /dev/null
+++ b/docs/networking/ipv6.md
@@ -0,0 +1,37 @@
+# IPv6
+
+{{ kops_feature_table(kops_added_ff='1.22') }}
+
+kOps has experimental support for configuring clusters with IPv6-only pods and dual-stack nodes.
+
+IPv6 mode is specified by setting `nonMasqueradeCIDR: "::/0"` in the cluster spec.
+The `--ipv6` flag of `kops create cluster` sets this field, among others.
+
+## Cloud providers
+
+kOps currently supports IPv6 on AWS only.
+
+IPv6 requires the external Cloud Controller Manager.
+
+## VPC and subnets
+
+The VPC can be either shared or managed by kOps. If shared, it must have an IPv6 pool associated.
+
+Subnet IPv6 CIDR allocations may be specified in the cluster spec using the special syntax `/LEN#N`,
+where "LEN" is the prefix length and "N" is the hexadecimal sequence number of the CIDR within the VPC's IPv6 CIDR.
+For example, if the VPC's CIDR is `2001:db8::/56` then the syntax `/64#a` would mean `2001:db8:0:a/64`.
+
+## CNI
+
+kOps currently supports IPv6 on Calico, Cilium, and bring-your-own CNI only.
+
+CNIs must not masquerade IPv6 addresses.
+
+### Calico
+
+Running IPv6 with Calico requires a Debian 11-based AMI. As of the writing of this document, Ubuntu does not work due to an 
+[issue with systemd's handling of AWS's incorrect DHCP responses](https://github.com/systemd/systemd/issues/20803).
+
+## Future work
+
+* kOps currently does not have a solution for NAT64/DNS64.
diff --git a/mkdocs.yml b/mkdocs.yml
index 0e6e395b5b..24608706cf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -106,6 +106,7 @@ nav:
       - Flannel: "networking/flannel.md"
       - Kube-Router: "networking/kube-router.md"
       - Weave: "networking/weave.md"
+    - IPv6: "networking/ipv6.md"
     - Run kOps in an existing VPC: "run_in_existing_vpc.md"
     - Supported network topologies: "topology.md"
     - Subdomain setup: "creating_subdomain.md"