Skip to content

Commit c27197b

Browse files
Amulyam24Amulyam24
authored
Updating documentation (#450)
1 parent 937094e commit c27197b

File tree

10 files changed

+288
-70
lines changed

10 files changed

+288
-70
lines changed

‎docs/book/src/developer/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
11
# Developer Guide
2+
3+
- [Rapid iterative development with Tilt](/developer/tilt.html)
4+
- [Release process](/developer/release.html)

‎docs/book/src/getting-started.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,78 @@
11
# Getting Started
2+
3+
For prerequisites, check the respective sections for [VPC](topics/vpc/prerequisites.md) and [PowerVS](topics/powervs/prerequisites.md)
4+
5+
Now that we’ve got all the prerequisites in place, let’s create a Kubernetes cluster and transform
6+
it into a management cluster using `clusterctl`.
7+
8+
### Provision local boostrap management cluster:
9+
10+
1. Create simple, local bootstrap cluster with a control-plane and worker node
11+
12+
Using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/):
13+
14+
```console
15+
~ kind create cluster --name my-bootstrap --config bootstrap.yaml
16+
```
17+
18+
Example bootstrap.yaml:
19+
```yaml
20+
kind: Cluster
21+
apiVersion: kind.x-k8s.io/v1alpha4
22+
nodes:
23+
- role: control-plane
24+
- role: worker
25+
```
26+
27+
Make sure the nodes are in `Ready` state before moving on.
28+
29+
```console
30+
~ kubectl get nodes
31+
NAME STATUS ROLES AGE VERSION
32+
my-bootstrap-control-plane Ready control-plane,master 46h v1.20.2
33+
my-bootstrap-worker Ready <none> 46h v1.20.2
34+
```
35+
36+
2. Set workload cluster environment variables
37+
38+
Make sure these value reflects your API Key for your target VPC environment
39+
or PowerVS environment in IBM Cloud.
40+
41+
```console
42+
export IBMCLOUD_API_KEY=<YOUR_API_KEY>
43+
```
44+
- Additional varibles required for VPC
45+
46+
The sample `IAM_ENDPOINT` below points to Production and the `SERVICE_ENDPOINT` points to the `us-east` VPC region.
47+
48+
```console
49+
export IAM_ENDPOINT=https://iam.cloud.ibm.com/identity/token
50+
export SERVICE_ENDPOINT=https://us-south.iaas.cloud.ibm.com/v1
51+
```
52+
53+
3. Initialize local bootstrap cluter as a management cluster
54+
55+
When executed for the first time, the following command accepts the infrasturcture provider as an input to install. `clusterctl init` automatically adds to the list the cluster-api core provider, and if unspecified, it also adds the kubeadm bootstrap and kubeadm control-plane providers, thereby converting it into a management cluster which will be used to provision a workload cluster in IBM Cloud.
56+
57+
```console
58+
~ clusterctl init --infrastructure ibmcloud:<TAG>
59+
```
60+
61+
Output:
62+
```console
63+
Fetching providers
64+
Installing cert-manager Version="v1.5.3"
65+
Waiting for cert-manager to be available...
66+
Installing Provider="cluster-api" Version="v0.4.4" TargetNamespace="capi-system"
67+
Installing Provider="bootstrap-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-bootstrap-system"
68+
Installing Provider="control-plane-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-control-plane-system"
69+
Installing Provider="infrastructure-ibmcloud" Version="v0.1.0-alpha.2" TargetNamespace="capi-ibmcloud-system"
70+
71+
Your management cluster has been initialized successfully!
72+
73+
You can now create your first workload cluster by running the following:
74+
75+
clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -
76+
```
77+
78+
5. Once the management cluster is ready with the required providers up and running, proceed to provisioning the workload cluster. Check the respective sections for [VPC](/topics/vpc/creating-a-cluster.html) and [PowerVS](/topics/powervs/creating-a-cluster.html) to deploy the cluster.

‎docs/book/src/images/ibm-cloud.svg

Lines changed: 1 addition & 0 deletions
Loading

‎docs/book/src/introduction.md

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,92 @@
1-
# Introduction
1+
# Kubernetes Cluster API Provider IBM Cloud
2+
3+
<p align="center">
4+
<img src="https://github.com/kubernetes/kubernetes/raw/master/logo/logo.png" width="100x">
5+
<img src="../images/ibm-cloud.svg" height="100x" width="200x" alt="IBM Cloud">
6+
</p>
7+
8+
------
9+
<p align="center">Kubernetes-native declarative infrastructure for IBM Cloud.</p>
10+
11+
## What is the Cluster API Provider IBM Cloud
12+
13+
14+
The [Cluster API](https://github.com/kubernetes-sigs/cluster-api) brings declarative, Kubernetes-style APIs to cluster creation, configuration and management.
15+
16+
The API itself is shared across multiple cloud providers allowing for true IBM Cloud
17+
hybrid deployments of Kubernetes. It is built atop the lessons learned from
18+
previous cluster managers such as [kops](https://github.com/kubernetes/kops) and
19+
[kubicorn](http://kubicorn.io/).
20+
21+
## Quick Start
22+
23+
Check out the [getting started](./getting-started.html) section to create your first Kubernetes cluster on IBM Cloud using Cluster API.
24+
25+
## Tilt-based development environment
26+
27+
See [developer guide](/developer/tilt.html) section for details.
28+
29+
30+
## Documentation
31+
32+
Please see our [Book](https://cluster-api-ibmcloud.sigs.k8s.io) for in-depth user documentation.
33+
34+
Additional docs can be found in the `/docs` directory, and the [index is here](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/tree/main/docs).
35+
36+
## Getting involved and contributing
37+
38+
Are you interested in contributing to cluster-api-provider-ibmcloud? We, the
39+
maintainers and community, would love your suggestions, contributions, and help!
40+
Also, the maintainers can be contacted at any time to learn more about how to get
41+
involved.
42+
43+
In the interest of getting more new people involved, we tag issues with
44+
[`good first issue`](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues?q=is%3Aissue+label%3A%22good+first+issue%22+is%3Aopen).
45+
These are typically issues that have smaller scope but are good ways to start
46+
to get acquainted with the codebase.
47+
48+
We also encourage all active community participants to act as if they are
49+
maintainers, even if you don't have "official" write permissions. This is a
50+
community effort, we are here to serve the Kubernetes community. If you have an
51+
active interest and you want to get involved, you have real power! Don't assume
52+
that the only people who can get things done around here are the "maintainers".
53+
54+
We also would love to add more "official" maintainers, so show us what you can
55+
do!
56+
57+
This repository uses the Kubernetes bots. See a full list of the commands [here](https://prow.k8s.io/command-help).
58+
59+
### Join us
60+
61+
The community holds a weekly meeting every Friday at 09:00 (IST) / 03:30 (UTC) on [Zoom](https://zoom.us/j/9392903494). Subscribe to the [SIG Cluster Lifecycle](https://groups.google.com/g/kubernetes-sig-cluster-lifecycle) Google Group for access to documents and calendars
62+
63+
64+
### Other ways to communicate with the contributors
65+
66+
Please check in with us in the [#cluster-api-ibmcloud](https://kubernetes.slack.com/archives/C02F4CX3ALF) channel on Slack.
67+
68+
## Github issues
69+
70+
### Bugs
71+
72+
If you think you have found a bug please follow the instructions below.
73+
74+
- Please spend a small amount of time giving due diligence to the issue tracker. Your issue might be a duplicate.
75+
- Get the logs from the cluster controllers. Please paste this into your issue.
76+
- Open a [bug report](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues/new?assignees=&labels=&template=bug_report.md).
77+
- Remember users might be searching for your issue in the future, so please give it a meaningful title to helps others.
78+
79+
### Tracking new features
80+
81+
We also use the issue tracker to track features. If you have an idea for a feature, or think you can help Cluster API Provider IBMCloud become even more awesome, then follow the steps below.
82+
83+
- Open a [feature request](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues/new?assignees=&labels=&template=feature_request.md).
84+
- Remember users might be searching for your issue in the future, so please
85+
give it a meaningful title to helps others.
86+
- Clearly define the use case, using concrete examples. EG: I type `this` and
87+
cluster-api-provider-ibmcloud does `that`.
88+
- Some of our larger features will require some design. If you would like to
89+
include a technical design for your feature please include it in the issue.
90+
- After the new feature is well understood, and the design agreed upon we can
91+
start coding the feature. We would love for you to code it. So please open
92+
up a **WIP** *(work in progress)* pull request, and happy coding.

‎docs/book/src/topics/index.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
# Topics
2+
3+
This section contains information about using IBM Cloud features with Cluster API Provider IBM Cloud.

‎docs/book/src/topics/powervs/creating-a-cluster.md

Lines changed: 8 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,9 @@
1-
# Creating a cluster
1+
### Provision workload cluster in IBM Cloud PowerVS
22

3-
### Provision local boostrap management cluster:
3+
Now that we have a management cluster ready, you can create your workload cluster by
4+
following the steps below.
45

5-
1. Create simple, local bootstrap cluster with a control-plane and worker node
6-
7-
Using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/):
8-
9-
```console
10-
~ kind create cluster --name my-bootstrap --config bootstrap.yaml
11-
```
12-
13-
Example bootstrap.yaml:
14-
```yaml
15-
kind: Cluster
16-
apiVersion: kind.x-k8s.io/v1alpha4
17-
nodes:
18-
- role: control-plane
19-
- role: worker
20-
```
21-
22-
Make sure the nodes are in `Ready` state before moving on.
23-
24-
```console
25-
~ kubectl get nodes
26-
NAME STATUS ROLES AGE VERSION
27-
my-bootstrap-control-plane Ready control-plane,master 46h v1.20.2
28-
my-bootstrap-worker Ready <none> 46h v1.20.2
29-
```
30-
31-
2. Set workload cluster environment variables
32-
33-
Make sure these value reflects your API Key for PowerVS environment in IBM Cloud.
34-
35-
```console
36-
export IBMCLOUD_API_KEY=<YOUR_API_KEY>
37-
```
38-
39-
3. Initialize local bootstrap cluter as a management cluster
40-
41-
This cluster will be used to provision a workload cluster in IBM Cloud.
42-
43-
```console
44-
~ clusterctl init --infrastructure ibmcloud:<TAG>
45-
```
46-
47-
Output:
48-
```console
49-
Fetching providers
50-
Installing cert-manager Version="v1.5.3"
51-
Waiting for cert-manager to be available...
52-
Installing Provider="cluster-api" Version="v0.4.4" TargetNamespace="capi-system"
53-
Installing Provider="bootstrap-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-bootstrap-system"
54-
Installing Provider="control-plane-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-control-plane-system"
55-
Installing Provider="infrastructure-ibmcloud" Version="v0.1.0-alpha.2" TargetNamespace="capi-ibmcloud-system"
56-
57-
Your management cluster has been initialized successfully!
58-
59-
You can now create your first workload cluster by running the following:
60-
61-
clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -
62-
```
63-
64-
4. Create PowerVS network port
6+
1. Create PowerVS network port
657

668
```console
679
~ pvsadm create port --description "capi-port" --network <NETWORK_NAME> --instance-id <SERVICE_INSTANCE_ID>
@@ -90,9 +32,7 @@
9032
+-------------------+-----------------+-----------------+-------------------+--------------------------------------+--------+
9133
```
9234

93-
4. Provision workload cluster in IBM Cloud PowerVS
94-
95-
You can use clusterctl to render the yaml through templates.
35+
2. Use clusterctl to render the yaml through templates and deploy the cluster
9636

9737
**Note:** the `IBMPOWERVS_IMAGE_ID` value below should reflect the ID of the custom qcow2 image, the `kubernetes-version` value below should reflect the kubernetes version of the custom qcow2 image.
9838

@@ -122,15 +62,15 @@
12262
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/ibm-powervs-1-md-0 created
12363
```
12464

125-
5. Deploy Container Network Interface (CNI)
65+
3. Deploy Container Network Interface (CNI)
12666

12767
Example: calico
12868
```console
12969
kubectl apply -f https://docs.projectcalico.org/v3.15/manifests/calico.yaml
13070
```
13171

13272

133-
6. Check the state of the provisioned cluster and machine objects within the local management cluster
73+
4. Check the state of the provisioned cluster and machine objects within the local management cluster
13474

13575
Clusters
13676
```console
@@ -154,7 +94,7 @@
15494
ibm-powervs-1-md-0-5444cfcbcd-7kr9x ibmpowervs://ibm-powervs-1/ibm-powervs-1-md-0-k7blr Running v1.22.4
15595
```
15696

157-
7. Check the state of the newly provisioned cluster within IBM Cloud
97+
5. Check the state of the newly provisioned cluster within IBM Cloud
15898

15999
```console
160100
~ clusterctl get kubeconfig ibm-powervs-1 > ~/.kube/ibm-powervs-1

‎docs/book/src/topics/powervs/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
11
# Power VS Cluster
2+
3+
## Contents
4+
- [Prerequisites](/topics/powervs/prerequisites.html)
5+
- [Creating a cluster](/topics/powervs/creating-a-cluster.html)

0 commit comments

Comments
 (0)