Skip to content
This repository was archived by the owner on Aug 12, 2025. It is now read-only.

Commit d475426

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #402 from displague/readme-updates
Readme updates
2 parents 5f821aa + e8c4901 commit d475426

File tree

4 files changed

+107
-79
lines changed

4 files changed

+107
-79
lines changed

‎README.md

Lines changed: 18 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -10,57 +10,6 @@ This is the official [cluster-api](https://github.com/kubernetes-sigs/cluster-ap
1010

1111
![Packetbot works hard to keep Kubernetes cluster in a good shape](./docs/banner.png)
1212

13-
## Ugrading from v0.3.X to v1.1.X
14-
15-
* **IMPORTANT** - Before you upgrade, please note that multi-tenancy support has changed in versions after v0.3.X
16-
* We no longer support running multiple instances of the provider in the same management cluster. Typically this was done to enable multiple credentials for managing devices in more than one project.
17-
* If you currently have a management cluster with multiple instances of the provider, it's recommended you use clusterctl move to migrate them to another cluster before upgrading.
18-
* [See more information about `clusterctl move` here](https://cluster-api.sigs.k8s.io/clusterctl/commands/move.html)
19-
20-
* Upgrade your clusterctl to version 1.1.3 or later.
21-
* Backup your clusterapi objects from your management cluster by using the `clusterctl backup` comamnd.
22-
23-
```bash
24-
clusterctl backup --directory /path/to/backup/directory/
25-
```
26-
27-
* More details are available [here](https://cluster-api.sigs.k8s.io/clusterctl/commands/upgrade.html).
28-
* The next step is to run `clusterctl upgrade plan`, and you should see something like this:
29-
30-
```bash
31-
Latest release available for the v1beta1 API Version of Cluster API (contract):
32-
33-
NAME NAMESPACE TYPE CURRENT VERSION NEXT VERSION
34-
bootstrap-kubeadm capi-kubeadm-bootstrap-system BootstrapProvider v0.3.25 v1.1.2
35-
control-plane-kubeadm capi-kubeadm-control-plane-system ControlPlaneProvider v0.3.25 v1.1.2
36-
cluster-api capi-system CoreProvider v0.3.25 v1.1.2
37-
infrastructure-packet cluster-api-provider-packet-system InfrastructureProvider v0.3.11 v0.5.0
38-
39-
You can now apply the upgrade by executing the following command:
40-
41-
clusterctl upgrade apply --contract v1beta1
42-
```
43-
44-
* Go ahead and run `clusterctl upgrade apply --contract v1beta1`
45-
* After this, if you'd like to co ntinue and upgrade kubernetes, it's a normal upgrade flow where you upgrade the control plane by editing the machinetemplates and kubeadmcontrolplane and the workers by editing the machinesets and machinedeployments. Full details [here](https://cluster-api.sigs.k8s.io/tasks/upgrading-clusters.html). Below is a very basic example upgrade of a small cluster:
46-
47-
```bash
48-
kubectl get PacketMachineTemplate example-control-plane -o yaml > example-control-plane.yaml
49-
# Using a text editor, edit the spec.version field to the new kubernetes version
50-
kubectl apply -f example-control-plane.yaml
51-
kubectl get machineDeployment example-worker-a -o yaml > example-worker-a.yaml
52-
# Using a text editor, edit the spec.template.spec.version to the new kubernetes version
53-
kubectl apply -f example-worker-a.yaml
54-
```
55-
56-
## Using
57-
58-
The following section describes how to use the cluster-api provider for packet (CAPP) as a regular user.
59-
You do _not_ need to clone this repository, or install any special tools, other than the standard
60-
`kubectl` and `clusterctl`; see below.
61-
62-
* To build CAPP and to deploy individual components, see [docs/BUILD.md](./docs/BUILD.md).
63-
* To build CAPP and to cut a proper release, see [docs/RELEASE.md](./docs/RELEASE.md).
6413

6514
### Requirements
6615

@@ -80,32 +29,19 @@ Once you have your cluster, ensure your `KUBECONFIG` environment variable is set
8029

8130
### Getting Started
8231

83-
You can follow the [Cluster API Quick Start Guide](https://cluster-api.sigs.k8s.io/user/quick-start.html), selecting the 'Equinix Metal' tabs.
32+
You should then follow the [Cluster API Quick Start Guide](https://cluster-api.sigs.k8s.io/user/quick-start.html), selecting the 'Equinix Metal' tabs where offered.
8433

8534
#### Defaults
8635

8736
If you do not change the generated `yaml` files, it will use defaults. You can look in the [templates/cluster-template.yaml](./templates/cluster-template.yaml) file for details.
8837

89-
* CLUSTER_NAME (defaults to my-cluster)
90-
* CONTROL_PLANE_MACHINE_COUNT (defaults to 1)
91-
* KUBE_VIP_VERSION (defaults to "v0.4.2")
92-
* NODE_OS (defaults to "ubuntu_18_04")
93-
* POD_CIDR (defaults to "192.168.0.0/16")
94-
* SERVICE_CIDR (defaults to "172.26.0.0/16")
95-
* WORKER_MACHINE_COUNT (defaults to 0)
96-
97-
#### API Server VIP Management Choice
98-
As of v0.6.0 you can choose to use kube-vip to manage the api-server VIP instead of CPEM. By default CPEM will be used to manage the EIP that serves as the VIP for the api-server. To use kube-vip, when generating the template with `clusterctl`, pass in the `--flavor kube-vip` flag. For example, your `clusterctl generate` command might look like the following:
99-
100-
```sh
101-
clusterctl generate cluster capi-quickstart \
102-
--kubernetes-version v1.24.0 \
103-
--control-plane-machine-count=3 \
104-
--worker-machine-count=3 \
105-
--infrastructure packet \
106-
--flavor kube-vip
107-
> capi-quickstart.yaml
108-
```
38+
* `CLUSTER_NAME` (defaults to `my-cluster`)
39+
* `CONTROL_PLANE_MACHINE_COUNT` (defaults to `1`)
40+
* `KUBE_VIP_VERSION` (defaults to `v0.4.2`)
41+
* `NODE_OS` (defaults to `ubuntu_18_04`)
42+
* `POD_CIDR` (defaults to `192.168.0.0/16`)
43+
* `SERVICE_CIDR` (defaults to `172.26.0.0/16`)
44+
* `WORKER_MACHINE_COUNT` (defaults to `0`)
10945

11046
## Community, discussion, contribution, and support
11147

@@ -116,6 +52,16 @@ You can reach the maintainers of this project at:
11652
* Chat with us on [Slack](http://slack.k8s.io/) in the [#cluster-api-provider-packet][#cluster-api-provider-packet slack] channel
11753
* Subscribe to the [SIG Cluster Lifecycle](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle) Google Group for access to documents and calendars
11854

55+
56+
## Development and Customizations
57+
The following section describes how to use the cluster-api provider for packet (CAPP) as a regular user.
58+
You do _not_ need to clone this repository, or install any special tools, other than the standard
59+
`kubectl` and `clusterctl`; see below.
60+
61+
* To build CAPP and to deploy individual components, see [docs/BUILD.md](./docs/BUILD.md).
62+
* To build CAPP and to cut a proper release, see [docs/RELEASE.md](./docs/RELEASE.md).
63+
64+
11965
### Code of conduct
12066

12167
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).

‎docs/MIGRATION.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Migration Notes
2+
3+
## Ugrading from CAPI v0.3.X to v1.1.X
4+
5+
* **IMPORTANT** - Before you upgrade, please note that multi-tenancy support has changed in versions after v0.3.X
6+
* We no longer support running multiple instances of the provider in the same management cluster. Typically this was done to enable multiple credentials for managing devices in more than one project.
7+
* If you currently have a management cluster with multiple instances of the provider, it's recommended you use clusterctl move to migrate them to another cluster before upgrading.
8+
* [See more information about `clusterctl move` here](https://cluster-api.sigs.k8s.io/clusterctl/commands/move.html)
9+
10+
* Upgrade your clusterctl to version 1.1.3 or later.
11+
* Backup your clusterapi objects from your management cluster by using the `clusterctl backup` comamnd.
12+
13+
```bash
14+
clusterctl backup --directory /path/to/backup/directory/
15+
```
16+
17+
* More details are available [here](https://cluster-api.sigs.k8s.io/clusterctl/commands/upgrade.html).
18+
* The next step is to run `clusterctl upgrade plan`, and you should see something like this:
19+
20+
```bash
21+
Latest release available for the v1beta1 API Version of Cluster API (contract):
22+
23+
NAME NAMESPACE TYPE CURRENT VERSION NEXT VERSION
24+
bootstrap-kubeadm capi-kubeadm-bootstrap-system BootstrapProvider v0.3.25 v1.1.2
25+
control-plane-kubeadm capi-kubeadm-control-plane-system ControlPlaneProvider v0.3.25 v1.1.2
26+
cluster-api capi-system CoreProvider v0.3.25 v1.1.2
27+
infrastructure-packet cluster-api-provider-packet-system InfrastructureProvider v0.3.11 v0.5.0
28+
29+
You can now apply the upgrade by executing the following command:
30+
31+
clusterctl upgrade apply --contract v1beta1
32+
```
33+
34+
* Go ahead and run `clusterctl upgrade apply --contract v1beta1`
35+
* After this, if you'd like to co ntinue and upgrade kubernetes, it's a normal upgrade flow where you upgrade the control plane by editing the machinetemplates and kubeadmcontrolplane and the workers by editing the machinesets and machinedeployments. Full details [here](https://cluster-api.sigs.k8s.io/tasks/upgrading-clusters.html). Below is a very basic example upgrade of a small cluster:
36+
37+
```bash
38+
kubectl get PacketMachineTemplate example-control-plane -o yaml > example-control-plane.yaml
39+
# Using a text editor, edit the spec.version field to the new kubernetes version
40+
kubectl apply -f example-control-plane.yaml
41+
kubectl get machineDeployment example-worker-a -o yaml > example-worker-a.yaml
42+
# Using a text editor, edit the spec.template.spec.version to the new kubernetes version
43+
kubectl apply -f example-worker-a.yaml
44+
```

‎docs/experiences/cni.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# CNI Notes
2+
3+
## Calico
4+
5+
### Installing Calico
6+
7+
When using the CAPI quickstart, follow the [Calico install instructions from Tigera](https://projectcalico.docs.tigera.io/getting-started/kubernetes/quickstart).
8+
9+
## Flannel
10+
11+
### Installing Flannel
12+
13+
Follow the instructions at <https://github.com/flannel-io/flannel#deploying-flannel-manually> (ignoring the instruction to create a `flanneld` binary on each node).
14+
15+
When declaring your cluster, set the `POD_CIDR` to `10.244.0.0/16` which is the default `Network` (`net-conf.json`) for Flannel, or update the Flannel manifest to match the desired POD CIDR.

‎docs/experiences/custom-cluster-template.md renamed to ‎docs/experiences/flavors.md

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
1+
# Flavors & Custom Templates
2+
3+
## Kube-VIP
4+
5+
### API Server VIP Management Choice
6+
7+
By default CPEM will be used to manage the EIP that serves as the VIP for the api-server. As of v0.6.0 you can choose to use kube-vip to manage the api-server VIP instead of CPEM.
8+
9+
### Choosing Kube-VIP
10+
11+
To use kube-vip, when generating the template with `clusterctl`, pass in the `--flavor kube-vip` flag. For example, your `clusterctl generate` command might look like the following:
12+
13+
```sh
14+
clusterctl generate cluster capi-quickstart \
15+
--kubernetes-version v1.24.0 \
16+
--control-plane-machine-count=3 \
17+
--worker-machine-count=3 \
18+
--infrastructure packet \
19+
--flavor kube-vip
20+
> capi-quickstart.yaml
21+
```
22+
23+
## Custom Templates
24+
125
When using the `clusterctl` you can generate your own cluster spec from a
226
template.
327

@@ -35,17 +59,16 @@ automation. Here a few examples:
3559
let's suppose you want `flannel` you can add the following line to
3660
`postKubeadmCommands` for the `KubeadmControlPlane` resource:
3761

38-
```sh
39-
kubectl --kubeconfig /etc/kubernetes/admin.conf apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
40-
```
62+
```sh
63+
kubectl --kubeconfig /etc/kubernetes/admin.conf apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
64+
```
4165

42-
2. If you want to use an operating system that is not Ubuntu you can change the
66+
1. If you want to use an operating system that is not Ubuntu you can change the
4367
`preKubeadmCommands` for the `KubeadmControlPlane` and the
4468
`KubeadmConfigTemplate` to use kubernetes binaries or a different package
4569
manager.
4670

47-
3. (2a) If you want to change operating system you have to change the `OS` field
48-
for the `PacketMachineTemplate` resource
49-
71+
If you want to change operating system you have to change the `OS` field
72+
for the `PacketMachineTemplate` resource.
5073

5174
[gh-release-v030]: https://github.com/kubernetes-sigs/cluster-api-provider-packet/releases/tag/v0.3.0

0 commit comments

Comments
 (0)