Skip to content

Commit 038f472

Browse files
mkumatagmkumatag
authored
Include Compatibility matrix and update the readme (#486)
1 parent c2a7919 commit 038f472

File tree

1 file changed

+16
-206
lines changed

1 file changed

+16
-206
lines changed

‎README.md

Lines changed: 16 additions & 206 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,6 @@
22
[![Releases](https://img.shields.io/badge/version-v0.0.1-orange.svg)](https://sigs.k8s.io/cluster-api-provider-ibmcloud/releases "Cluster API provider IBM Cloud latest release")
33
[![Go Report Card](https://goreportcard.com/badge/sigs.k8s.io/cluster-api-provider-ibmcloud)](https://goreportcard.com/report/sigs.k8s.io/cluster-api-provider-ibmcloud)
44

5-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
7-
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
8-
9-
- [Kubernetes Cluster API Provider IBM Cloud](#kubernetes-cluster-api-provider-ibm-cloud)
10-
- [What is the Cluster API Provider IBM Cloud](#what-is-the-cluster-api-provider-ibm-cloud)
11-
- [Getting Started](#getting-started)
12-
- [Prerequisites](#prerequisites)
13-
- [How to provision a simple workload cluster in IBM Cloud VPC Gen2 from local bootstrap cluster](#how-to-provision-a-simple-workload-cluster-in-ibm-cloud-vpc-gen2-from-local-bootstrap-cluster)
14-
- [Build workload cluster image:](#build-workload-cluster-image)
15-
- [Provision local boostrap management cluster:](#provision-local-boostrap-management-cluster)
16-
- [Provision Workload Cluster in IBM Cloud VPC](#provision-workload-cluster-in-ibm-cloud-vpc)
17-
- [Community, discussion, contribution, and support](#community-discussion-contribution-and-support)
18-
- [Code of conduct](#code-of-conduct)
19-
20-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
21-
225
# Kubernetes Cluster API Provider IBM Cloud
236

247
<a href="https://github.com/kubernetes-sigs/cluster-api"><img src="https://github.com/kubernetes/kubernetes/raw/master/logo/logo.png" width="100"></a><a href="https://www.ibm.com/cloud/"><img hspace="90px" src="./docs/images/ibm-cloud.svg" alt="Powered by IBM Cloud" height="100"></a>
@@ -31,204 +14,31 @@ This repository hosts a concrete implementation of an IBM Cloud provider for the
3114

3215
The [Cluster API](https://github.com/kubernetes-sigs/cluster-api) brings declarative, Kubernetes-style APIs to cluster creation, configuration and management. The API itself is shared across multiple cloud providers allowing for true IBM Cloud hybrid deployments of Kubernetes.
3316

34-
## Getting Started
35-
36-
### Prerequisites
37-
38-
1. Install `kubectl` (see [here](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-with-curl-on-linux)). Because `kustomize` was included into `kubectl` and it's used by `cluster-api-provider-ibmcloud` in generating yaml files, so version `1.14.0+` of `kubectl` is required, see [integrate kustomize into kubectl](https://github.com/kubernetes/enhancements/issues/633) for more info.
39-
2. You can use either VM, container or existing Kubernetes cluster act as the bootstrap cluster.
40-
- If you want to use container, install [kind](https://github.com/kubernetes-sigs/kind#installation-and-usage). This is preferred.
41-
- If you want to use VM, install [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/), version 0.30.0 or greater.
42-
- If you want to use existing Kubernetes cluster, prepare your kubeconfig.
43-
3. Install a [driver](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md) **if you are using minikube**. For Linux, we recommend kvm2. For MacOS, we recommend VirtualBox.
44-
4. An appropriately configured [Go development environment](https://golang.org/doc/install)
45-
5. Install `clusterctl` tool (see [here](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl))
46-
47-
## How to provision a simple workload cluster in IBM Cloud VPC Gen2 from local bootstrap cluster
48-
49-
### Build workload cluster image:
50-
51-
1. Build a qcow2 image suitable for use as a Kubernetes cluster machine as detailed in the image builder [book](https://image-builder.sigs.k8s.io/capi/providers/raw.html).
52-
53-
**Note:** Rename the output image to add the `.qcow2` extension. This is required by the next step.
54-
55-
56-
2. Create a VPC Gen2 custom image based on the qcow2 image built in the previous step as detailed in the VPC [documentation](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images).
57-
58-
### Provision local boostrap management cluster:
59-
60-
1. Create simple, local bootstrap cluster with a control-plane and worker node
61-
62-
Using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/):
63-
64-
```console
65-
~ kind create cluster --name my-bootstrap --config bootstrap.yaml
66-
```
67-
68-
Example bootstrap.yaml:
69-
```yaml
70-
kind: Cluster
71-
apiVersion: kind.x-k8s.io/v1alpha4
72-
nodes:
73-
- role: control-plane
74-
- role: worker
75-
```
76-
77-
Make sure the nodes are in `Ready` state before moving on.
78-
79-
```console
80-
~ kubectl get nodes
81-
NAME STATUS ROLES AGE VERSION
82-
my-bootstrap-control-plane Ready control-plane,master 46h v1.20.2
83-
my-bootstrap-worker Ready <none> 46h v1.20.2
84-
```
85-
86-
2. Apply IBM VPC CAPI CRDs
87-
88-
```console
89-
~ kubectl apply -f config/crd/bases
90-
```
91-
92-
Output:
93-
```console
94-
customresourcedefinition.apiextensions.k8s.io/ibmvpcclusters.infrastructure.cluster.x-k8s.io created
95-
customresourcedefinition.apiextensions.k8s.io/ibmvpcmachines.infrastructure.cluster.x-k8s.io created
96-
customresourcedefinition.apiextensions.k8s.io/ibmvpcmachinetemplates.infrastructure.cluster.x-k8s.io created
97-
```
98-
99-
3. Initialize local bootstrap cluter as a management cluster
100-
101-
This cluster will be used to provision a workload cluster in IBM Cloud.
102-
103-
```console
104-
~ clusterctl init
105-
```
106-
107-
Output:
108-
```console
109-
Fetching providers
110-
Installing cert-manager Version="v1.1.0"
111-
Waiting for cert-manager to be available...
112-
Installing Provider="cluster-api" Version="v0.3.16" TargetNamespace="capi-system"
113-
Installing Provider="bootstrap-kubeadm" Version="v0.3.16" TargetNamespace="capi-kubeadm-bootstrap-system"
114-
Installing Provider="control-plane-kubeadm" Version="v0.3.16" TargetNamespace="capi-kubeadm-control-plane-system"
115-
116-
Your management cluster has been initialized successfully!
117-
118-
You can now create your first workload cluster by running the following:
119-
120-
clusterctl config cluster [name] --kubernetes-version [version] | kubectl apply -f -
121-
```
122-
123-
### Provision Workload Cluster in IBM Cloud VPC
124-
125-
1. Set workload cluster environment variables
126-
127-
The sample IAM_ENDPOINT below points to Production and the SERVICE_ENDPOINT points to the `us-east` VPC region. Make sure these values reflect your target VPC environment in IBM Cloud.
128-
129-
```console
130-
export IAM_ENDPOINT=https://iam.cloud.ibm.com/identity/token
131-
export SERVICE_ENDPOINT=https://us-south.iaas.cloud.ibm.com/v1
132-
export API_KEY=<YOUR_API_KEY>
133-
```
134-
135-
2. Run IBM provider controllers
136-
137-
The controllers will run against your local management bootstrap cluster.
138-
139-
```console
140-
~ make run
141-
```
142-
143-
3. Provision workload cluster in IBM Cloud
144-
145-
You can use clusterctl to render the yaml through templates.
146-
147-
**Note:** the `IBMVPC_IMAGE_ID` value below should reflect the ID of the custom qcow2 image
148-
149-
```console
150-
IBMVPC_REGION=us-south \
151-
IBMVPC_ZONE=us-south-1 \
152-
IBMVPC_RESOURCEGROUP=4f15679623607b855b1a27a67f20e1c7 \
153-
IBMVPC_NAME=ibm-vpc-0 \
154-
IBMVPC_IMAGE_ID=r134-ea84bbec-7986-4ff5-8489-d9ec34611dd4 \
155-
IBMVPC_PROFILE=bx2-4x16 \
156-
IBMVPC_SSHKEY_ID=r134-2a82b725-e570-43d3-8b23-9539e8641944 \
157-
clusterctl generate cluster ibm-vpc-0 --kubernetes-version v1.19.9 \
158-
--target-namespace default \
159-
--control-plane-machine-count=1 \
160-
--worker-machine-count=2 \
161-
--from ./templates/cluster-template.yaml | kubectl apply -f -
162-
```
163-
164-
Output:
165-
```console
166-
cluster.cluster.x-k8s.io/ibm-vpc-5 created
167-
ibmvpccluster.infrastructure.cluster.x-k8s.io/ibm-vpc-5 created
168-
kubeadmcontrolplane.controlplane.cluster.x-k8s.io/ibm-vpc-5-control-plane created
169-
ibmvpcmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-vpc-5-control-plane created
170-
machinedeployment.cluster.x-k8s.io/ibm-vpc-5-md-0 created
171-
ibmvpcmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-vpc-5-md-0 created
172-
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/ibm-vpc-5-md-0 created
173-
```
174-
175-
4. Deploy Container Network Interface (CNI)
176-
177-
Example: calico
178-
```console
179-
kubectl apply -f https://docs.projectcalico.org/v3.15/manifests/calico.yaml
180-
```
181-
182-
183-
5. Check the state of the provisioned cluster and machine objects within the local management cluster
184-
185-
Clusters
186-
```console
187-
~ kubectl get clusters
188-
NAME PHASE
189-
ibm-vpc-0 Provisioned
190-
```
17+
## Documentation
19118

192-
Kubeadm Control Plane
193-
```console
194-
~ kubectl get kubeadmcontrolplane
195-
NAME INITIALIZED API SERVER AVAILABLE VERSION REPLICAS READY UPDATED UNAVAILABLE
196-
ibm-vpc-0-control-plane true true v1.19.9 1 1 1
197-
```
19+
Please see our [book](https://cluster-api-ibmcloud.sigs.k8s.io) for in-depth documentation.
19820

199-
Machines
200-
```console
201-
~ kubectl get machines
202-
ibm-vpc-0-control-plane-vzz47 ibmvpc://ibm-vpc-0/ibm-vpc-0-control-plane-rg6xv Running v1.19.9
203-
ibm-vpc-0-md-0-5444cfcbcd-6gg5z ibmvpc://ibm-vpc-0/ibm-vpc-0-md-0-dbxb7 Running v1.19.9
204-
ibm-vpc-0-md-0-5444cfcbcd-7kr9x ibmvpc://ibm-vpc-0/ibm-vpc-0-md-0-k7blr Running v1.19.9
205-
```
21+
## Launching a Kubernetes cluster on IBMCloud
20622

207-
6. Check the state of the newly provisioned cluster within IBM Cloud
23+
Check out the [Cluster API IBMCloud Quick Start](https://cluster-api-ibmcloud.sigs.k8s.io/getting-started.html) for launching a
24+
cluster on IBMCloud.
20825

209-
```console
210-
~ clusterctl get kubeconfig ibm-vpc-0 > ~/.kube/ibm-vpc-0
211-
~ export KUBECONFIG=~/.kube/ibm-vpc-0
212-
~ kubectl get nodes
213-
NAME STATUS ROLES AGE VERSION
214-
ibm-vpc-0-control-plane-rg6xv Ready master 41h v1.18.15
215-
ibm-vpc-0-md-0-4dc5c Ready <none> 41h v1.18.15
216-
ibm-vpc-0-md-0-dbxb7 Ready <none> 20h v1.18.15
217-
```
26+
## Compatibility with Cluster API and Kubernetes Versions
21827

219-
7. Experiment with machinedeployment alterations in your management cluster
28+
This provider's versions are compatible with the following versions of Cluster API:
22029

221-
With your management *(local)* and workload *(IBM Cloud)* clusters successfully provisioned, you can now experiment with altering the number of machine deployment replicas in your management cluster and see the replica counts reconciled in your workload cluster.
30+
| | v1alpha3 (v0.3) | v1alpha4 (v0.4) | v1beta1 (v1.0) |
31+
|-----------------------------------| --------------- | --------------- | -------------- |
32+
| IBMCloud Provider v1alpha4 (v0.1) | ✓ | ✓ | |
33+
| IBMCloud Provider v1beta1 (v0.2) | | | ✓ |
22234

223-
```console
224-
~ kubectl get machinedeployments
225-
NAME PHASE REPLICAS READY UPDATED UNAVAILABLE
226-
ibm-vpc-0-md-0 Running 2 2 2
22735

228-
~ kubectl scale machinedeployment ibm-vpc-0-md-0 --replicas 3
229-
```
36+
This provider's versions are able to install and manage the following versions of Kubernetes:
23037

231-
Increase / decrease the `replicas: 2` count in the spec section to see the machine replicas reconciled within the workload cluster.
38+
| | v1.21 | v1.22 |
39+
|-----------------------------------| ----- | ----- |
40+
| IBMCloud Provider v1alpha4 (v0.1) | ✓ | ✓ |
41+
| IBMCloud Provider v1beta1 (v0.2) | ✓ | ✓ |
23242

23343
<!-- ANCHOR: Community -->
23444

0 commit comments

Comments
 (0)