Merge pull request #199 from kubernetes-sigs/update-readme

📖 Update readme

Author: k8s-ci-robot

CODEOWNERS

@@ -3,8 +3,3 @@ Copyright (c) 2023 The Kubernetes Authors.
 
 This project is licensed under Apache License, Version 2.0;
 you may not use them except in compliance with the License.
-
-Contributors:
--------------
-
-Jakob Schrettenbrunner [schrej], Deutsche Telekom AG

NOTICE

@@ -1,10 +1,21 @@
 # Cluster API IPAM Provider In Cluster
 
-This is a IPAM provider for Cluster API that manages pools of IP addresses using Kubernetes resources. It serves as a reference implementation for IPAM providers, but can also be used as a simple replacement for DHCP.
+This is an [IPAM provider](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20220125-ipam-integration.md#ipam-provider) for [Cluster API](https://github.com/kubernetes-sigs/cluster-api) that manages pools of IP addresses using Kubernetes resources. It serves as a reference implementation for IPAM providers, but can also be used as a simple replacement for DHCP.
+
+IPAM providers allow to control how IP addresses are assigned to Cluster API Machines. It is usually only useful for non-cloud deployments. The infrastructure provider in use must support IPAM providers in order to use this provider.
+
+## Features
+
+- Manages IP Addresses in-cluster using custom Kubernetes resources
+- Address pools can be cluster-wide or namespaced
+- Pools can consist of subnets, arbitrary address ranges and/or individual addresses
+- Both IPv4 and IPv6 are supported
+- Individual addresses, ranges and subnets can be excluded from a pool
+- Well-known reserved addresses are excluded by default, which can be configured per pool
 
 ## Setup via clusterctl
 
-This release comes with clusterctl support. Since it's not added to the list of built-in providers yet, you'll need to add the following to your `~/.cluster-api/clusterctl.yaml` if you want to install it using `clusterctl init --ipam in-cluster`:
+This provider comes with clusterctl support. Since it's not added to the built-in list of providers yet, you'll need to add the following to your `~/.cluster-api/clusterctl.yaml` if you want to install it using `clusterctl init --ipam in-cluster`:
 
 ```yaml
 providers:
@@ -15,7 +26,9 @@ providers:
 
 ## Usage
 
-This provider comes with a `InClusterIPPool` resource to specify the pools from which addresses should be assigned. You can provide an address range using start and end addresses, as well as a prefix length, or a set of addresses with the prefix and gateway.
+This provider comes with two resources to specify pools from which addresses can be allocated: the `InClusterIPPool` and the `GlobalInClusterIPPool`. As the names suggest, the former is namespaced, the latter is cluster-wide. Otherwise they are identical. The following examples will all use the `InClusterIPPool`, but all examples work with the `GlobalInClusterIPPool` as well.
+
+A simple pool that covers an entire /24 IPv4 network could look like this:
 
 ```yaml
 apiVersion: ipam.cluster.x-k8s.io/v1alpha2
@@ -24,32 +37,62 @@ metadata:
   name: inclusterippool-sample
 spec:
   addresses:
-    - 10.0.0.10
-    - 10.0.0.24-10.0.0.32
-    - 10.0.0.128/28
+    - 10.0.0.0/24
   prefix: 24
   gateway: 10.0.0.1
 ```
 
-## Community, discussion, contribution, and support
+IPv6 is also supported, but a single pool can only consist of v4 **or** v6 addresses, not both. For simplicity we'll stick to IPv4 in the examples.
+
+The `addresses` field supports CIDR notation, as well as arbitrary ranges and individual addresses. Using the `excludedAddresses` field, addresses, ranges or subnets can be excluded from the pool.
+
+```yaml
+apiVersion: ipam.cluster.x-k8s.io/v1alpha2
+kind: InClusterIPPool
+metadata:
+  name: inclusterippool-sample
+spec:
+  addresses:
+    - 10.0.0.0/24
+    - 10.0.1.10-10.0.1.100
+    - 10.0.2.1
+    - 10.0.2.2
+  exclude:
+    - 10.10.0.16/28
+    - 10.10.0.242
+    - 10.0.1.25-10.0.1.30
+  prefix: 22
+  gateway: 10.0.0.1
+```
 
-Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
+Be aware that the prefix needs to cover all addresses that are part of the pool. The first network in the `addresses` list and the `prefix` field, which specifies the length of the prefix, is used to determine the prefix. In this case, `10.1.0.0/24` in the `addresses` list would lead to a validation error.
 
-You can reach the maintainers of this project at:
+The `gateway` will never be allocated. By default, addresses that are usually reserved will not be allocated either. For v4 networks this is the first (network) and last (broadcast) address within the prefix. In the example above that would be `10.0.0.0` and `10.0.3.255` (the latter not being in the network anyway). For v6 networks the first address is excluded.
 
-- [Slack](https://slack.k8s.io/)
-- [Mailing List](https://groups.google.com/a/kubernetes.io/g/dev)
+If you want to use all networks that are part of the prefix, you can set `allocateReservedIPAddresses` to `true`. In the example below, both `10.0.0.0` and `10.0.0.255` will be allocated. The gateway will still be excluded.
+
+```yaml
+apiVersion: ipam.cluster.x-k8s.io/v1alpha2
+kind: InClusterIPPool
+metadata:
+  name: inclusterippool-sample
+spec:
+  addresses:
+    - 10.0.0.0/24
+  prefix: 24
+  gateway: 10.0.0.1
+  allocateReservedIPAddresses: true
+```
 
-## Licensing
 
-Copyright (c) 2022 Deutsche Telekom AG.
+## Community, discussion, contribution, and support
 
-Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this file except in compliance with the License.
+The in-cluster IPAM provider is part of the cluster-api project. Please refer to it's [readme](https://github.com/kubernetes-sigs/cluster-api?tab=readme-ov-file#-community-discussion-contribution-and-support) for information on how to connect with the project.
 
-You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.
+The best way to reach the maintainers of this sub-project is the [#cluster-api](https://kubernetes.slack.com/archives/C8TSNPY4T) channel on the [Kubernetes Slack](https://slack.k8s.io).
 
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the [LICENSE](./LICENSE) for the specific language governing permissions and limitations under the License.
+Pull Requests and feedback on issues are very welcome! See the [issue tracker](https://github.com/kubernetes-sigs/cluster-api-ipam-provider-in-cluster/issues) if you're unsure where to start, especially the [Good first issue](https://github.com/kubernetes-sigs/cluster-api-ipam-provider-in-cluster/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) and [Help wanted](https://github.com/kubernetes-sigs/cluster-api-ipam-provider-in-cluster/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+) tags, and also feel free to reach out to discuss.
 
-### Dependency Licenses
+## Code of conduct
 
-You can find the licenses of used Go dependencies as a `licenses.tar.gz` archive as part of our [releases](https://github.com/kubernetes-sigs/cluster-api-ipam-provider-in-cluster/releases) and in the `/license` directory contained in our container images available at [ghcr.io/telekom/cluster-api-ipam-provider-in-cluster](https://ghcr.io/telekom/cluster-api-ipam-provider-in-cluster).
+Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](https://github.com/kubernetes-sigs/cluster-api-ipam-provider-in-cluster/blob/main/code-of-conduct.md).