Skip to content

Commit 7d53f01

Browse files
rayowangrayowang
committed
feat: add guide for distributing Kubebuilder project
1 parent 5d3e33b commit 7d53f01

File tree

2 files changed

+245
-0
lines changed

2 files changed

+245
-0
lines changed

‎docs/book/src/reference/distributing-projects.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Distributing Your Kubebuilder Project
2+
3+
## Overview
4+
5+
This guide outlines how to distribute your Kubebuilder-based Operator by generating a **bundle** and publishing it either to **OperatorHub.io** or using **OLM (Operator Lifecycle Manager)** for Kubernetes deployments. This process is vital for making your Operator available to a broader audience and ensuring it is easily deployed and managed in Kubernetes clusters.
6+
7+
### Prerequisites
8+
9+
Before proceeding, ensure you have the following installed:
10+
- **Kubebuilder** (for creating the Operator)
11+
- **Operator SDK** (for generating and managing bundles)
12+
- **Kustomize** (for managing Kubernetes configurations)
13+
- **Docker** (for building container images)
14+
15+
### Default Kubebuilder Assumptions for Distribution
16+
17+
Kubebuilder follows a standard project structure and assumes the following when distributing an Operator:
18+
- **Directory Structure**: Your Kubebuilder project should follow this basic structure:
19+
20+
```bash
21+
/config
22+
├── crds/
23+
├── manifests/
24+
└── samples/
25+
/Makefile
26+
/PROJECT
27+
/Dockerfile
28+
...
29+
```
30+
31+
- **Kustomize**: Kubebuilder uses Kustomize to manage Kubernetes manifests, which simplifies the customization and deployment process.
32+
- **Operator Versions**: Each Operator release is versioned (e.g., 0.1.0), and you can use release channels such as alpha and stable to manage versions.
33+
- **Channels**: By default, the alpha channel is used for experimental or preview versions. You can configure this to use other channels based on your needs.
34+
35+
### Step-by-Step Guide: Publishing Kubebuilder Projects to OperatorHub.io
36+
37+
## Step 1: Prepare Your Kubebuilder Project
38+
39+
Ensure that your Kubebuilder project is properly created and contains the necessary Kubernetes manifests and CRD files.
40+
41+
### Step 1: To initialize a basic Kubebuilder project
42+
43+
```
44+
kubebuilder init --domain mydomain.com --repo github.com/myorg/my-operator
45+
```
46+
47+
### Step 2: Create your API resources
48+
49+
```
50+
kubebuilder create api --group app --version v1 --kind MyApp
51+
```
52+
This will create the necessary directories and files under the config/ directory.
53+
54+
### Step 3: Compltete your business and create your crds
55+
56+
```
57+
make manifests
58+
```
59+
60+
## Step 2: Generate the Operator Bundle
61+
62+
### Step 1: operator-sdk generate kustomize manifests
63+
64+
Example output:
65+
```
66+
operator-sdk generate kustomize manifests
67+
Generating kustomize files in config/manifests
68+
69+
Display name for the operator (required):
70+
> my-operator
71+
72+
Description for the operator (required):
73+
> To verify how to generate the bundle
74+
75+
Provider's name for the operator (required):
76+
> zhilongwang
77+
78+
Any relevant URL for the provider name (optional):
79+
> https://github.com/rayowang
80+
81+
Comma-separated list of keywords for your operator (required):
82+
> crd,custom-resource,controller
83+
84+
Comma-separated list of maintainers and their emails (e.g. 'name1:email1, name2:email2') (required):
85+
> rayowang:[email protected]
86+
Kustomize files generated successfully
87+
```
88+
This generates the file: config/manifests/bases/kubebuilderdemo.clusterserviceversion.yaml.
89+
90+
### Step 2: Add the config/manifests/kustomization.yaml
91+
92+
These resources constitute the fully configured set of manifests, used to generate the 'manifests/' directory in a bundle.
93+
94+
```
95+
resources:
96+
- bases/kubebuilderdemo.clusterserviceversion.yaml
97+
- ../default
98+
- ../samples
99+
```
100+
101+
### Step 3: Generate the Operator Bundle
102+
103+
Operator bundles are the standard format for distributing Operators. These bundles include the necessary Kubernetes manifests, CRDs, and metadata required by platforms like OperatorHub.io and OLM.
104+
105+
Note: Due to compatibility issues between the latest Kubebuilder v4 and Operator SDK, we need to disable the cliVersion field before running the command. To do so, execute:
106+
107+
```
108+
# On macOS
109+
sed -i '' '/^cliVersion:/s/^/#/' PROJECT
110+
# On Linux
111+
sed -i '/^cliVersion:/s/^/#/' PROJECT
112+
```
113+
114+
Then, run the bundle generation command:
115+
116+
```
117+
kustomize build config/manifests | \
118+
operator-sdk generate bundle \
119+
--version 0.1.0 \
120+
--package my-operator \
121+
--channels alpha \
122+
--default-channel alpha
123+
124+
```
125+
126+
Breakdown of the Command:
127+
128+
• --version: Specifies the version of the bundle (e.g., 0.1.0).
129+
• --kustomize-dir: Points to the directory containing the Kubernetes manifests.
130+
• --output-dir: Specifies the directory to save the generated bundle.
131+
• --package: The package name, which is usually the same as the project name.
132+
• --channels and --default-channel: The release channel(s) for the bundle (e.g., alpha for preview releases).
133+
134+
## Step 3: Validate the Generated Bundle Files
135+
136+
The generated files must adhere to the expected structure and format. Here’s an overview of the important files:
137+
• annotations.yaml: Contains metadata about the Operator, such as the author’s name, the operator’s source, and description.
138+
• ClusterServiceVersion.yaml (CSV): Defines the installation properties of the Operator, including deployment information and required resources.
139+
• bundle.Dockerfile: A Dockerfile used to build the image containing the Operator.
140+
141+
Example structure:
142+
143+
```
144+
bundle
145+
├── manifests
146+
│   ├── app.mydomain.com_myapps.yaml
147+
│   ├── kubebuilderdemo-controller-manager-metrics-service_v1_service.yaml
148+
│   ├── kubebuilderdemo-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml
149+
│   ├── kubebuilderdemo-myapp-admin-role_rbac.authorization.k8s.io_v1_clusterrole.yaml
150+
│   ├── kubebuilderdemo-myapp-editor-role_rbac.authorization.k8s.io_v1_clusterrole.yaml
151+
│   ├── kubebuilderdemo-myapp-viewer-role_rbac.authorization.k8s.io_v1_clusterrole.yaml
152+
│   └── my-operator.clusterserviceversion.yaml
153+
└── metadata
154+
└── annotations.yaml
155+
```
156+
157+
Use the following command to generate the bundle:
158+
159+
```
160+
operator-sdk bundle validate ./bundle
161+
```
162+
163+
You should see the following log:
164+
165+
```
166+
INFO[0000] All validation tests have completed successfully
167+
```
168+
169+
Note: Ensure the namespace and manager image defined in bundle/manifests/my-operator.clusterserviceversion.yaml are prepared in advance or adjusted according to your actual configuration.
170+
build -t docker.io/raysail/kubebuilderdemo-manager:v1 -f Dockerfile
171+
172+
## Step 4: 验证 Deploying the Operator with OLM
173+
174+
### Step 1: Install OLM (if not installed)
175+
176+
If OLM is not yet installed in your Kubernetes cluster, you can install it with the following command:
177+
178+
```
179+
operator-sdk olm install
180+
```
181+
182+
### Step 2: Build and Push the Bundle Image
183+
184+
Once OLM is installed, build and push the bundle image:
185+
186+
```
187+
docker build -t docker.io/raysail/kubebuilderdemo-operator-bundle:v1 -f bundle.Dockerfile
188+
docker push docker.io/raysail/kubebuilderdemo-operator-bundle:v1
189+
```
190+
191+
### Step 3: Run the Bundle
192+
193+
Run the following command to deploy the bundle:
194+
195+
```
196+
operator-sdk run bundle docker.io/raysail/kubebuilderdemo-operator-bundle:v1
197+
```
198+
199+
You should see logs similar to the following:
200+
201+
```
202+
INFO[0035] Creating a File-Based Catalog of the bundle "docker.io/raysail/kubebuilderdemo-operator-bundle:v1"
203+
INFO[0039] Generated a valid File-Based Catalog
204+
INFO[0042] Created registry pod: docker-io-raysail-kubebuilderdemo-operator-bundle-v1
205+
INFO[0042] Created CatalogSource: my-operator-catalog
206+
INFO[0042] Created Subscription: my-operator-v0-1-0-sub
207+
INFO[0060] Approved InstallPlan install-d7dbw for the Subscription: my-operator-v0-1-0-sub
208+
INFO[0060] Waiting for ClusterServiceVersion "default/my-operator.v0.1.0" to reach 'Succeeded' phase
209+
INFO[0061] Waiting for ClusterServiceVersion "default/my-operator.v0.1.0" to appear
210+
INFO[0062] Found ClusterServiceVersion "default/my-operator.v0.1.0" phase: Pending
211+
INFO[0064] Found ClusterServiceVersion "default/my-operator.v0.1.0" phase: Installing
212+
INFO[0095] Found ClusterServiceVersion "default/my-operator.v0.1.0" phase: Succeeded
213+
INFO[0095] OLM has successfully installed "my-operator.v0.1.0"
214+
215+
```
216+
### Step 3: 进一步 Check Installation Status
217+
218+
To verify if the Operator has been successfully installed, you can run:
219+
220+
```
221+
kubectl get operators
222+
```
223+
224+
You can also check the deployment of the CR to see if there are any errors.
225+
226+
## Step 5: Publishing the Operator to operatorhub.io or olm.operatorframework.io
227+
228+
To make your Operator available to the public and other users, you can publish it to OperatorHub.io. Follow the steps below to submit your Operator.
229+
230+
### Step 1: Login to operatorhub.io or olm.operatorframework.io
231+
232+
Go to OperatorHub.io and create a developer account. Alternatively, if you’re submitting to OLM, log in to olm.operatorframework.io.
233+
234+
### Step 2: Submit Your Operator
235+
236+
Create a new Operator entry on OperatorHub.io or OLM, and provide the necessary metadata (name, description, etc.). Upload the generated bundle files, including annotations.yaml, ClusterServiceVersion.yaml, and bundle.Dockerfile.
237+
238+
### Step 3: Submit for Review
239+
240+
After uploading the files, submit your Operator for review by the OperatorHub.io team. Once approved, your Operator will be publicly available for installation by others directly from OperatorHub.io.
241+
242+
## Conclusion
243+
244+
By following this guide, you can easily distribute your Kubebuilder-based Operator to a wider audience. Whether you choose to publish your Operator on OperatorHub.io or deploy it via OLM, Kubebuilder provides the tools necessary to create a standardized bundle. Automating this process with Makefile further streamlines the deployment process, ensuring that your Operator is ready for production use in Kubernetes environments.

‎docs/book/src/reference/reference.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,4 @@
4141
- [Reference](metrics-reference.md)
4242

4343
- [CLI plugins](../plugins/plugins.md)
44+
- [Distributing Your Project](distributing-projects.md)

0 commit comments

Comments
 (0)