https://github.com/okd-project/okd-sample-operator
https://github.com/okd-project/okd-sample-operator
Last synced: 12 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/okd-project/okd-sample-operator
- Owner: okd-project
- Archived: true
- Created: 2023-06-16T08:37:44.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-07-25T16:28:26.000Z (almost 2 years ago)
- Last Synced: 2025-03-13T03:41:27.284Z (2 months ago)
- Language: Go
- Size: 78.1 KB
- Stars: 0
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Overview
A simple quick-start introduction on how to build an operator from scratch
This project assumes you have knowledge of golang and at least some level of understanding of operators
### What is the Operator SDK?
The Operator SDK is a framework that uses the controller-runtime library to make writing Operators easier by providing:
High level APIs and abstractions to write the operational logic more intuitively.
Tools for scaffolding and code generation to bootstrap a new project fast.
Extensions to cover common Operator use cases.
### How do I use it?
The following is the workflow for a new Go-based Operator with the Operator SDK:
1. Create a new Operator project using the SDK CLI.
2. Create a new Custom Resource Definition API Type using the SDK CLI.
3. Add your Custom Resource Definition (CRD) to your live Kubernetes cluster.
4. Define your Custom Resource Spec and Status.
5. Create a new Controller for your Custom Resource Definition API.
6. Write the reconciling logic for your Controller.
7. Run the Operator locally to test your code against your live Kubernetes cluster.
8. Add your Custom Resource (CR) to your live Kubernetes cluster and watch your Operator in action!
9. After you are satisifed with your work, run some Makefile commands to build and generate the Operator Deployment manifests.
10. Optionally add additional APIs and Controllers using the SDK CLI.
11. Use the okd-operator-pipeline to build, bundle and create a catalog for you new operator
### Prerequisites
To start you will neeed the following software packages
- golang
- golangci-lint
- operator-sdk
- opm
- kustomize
- go tools (controller-gen,setup-envtest)
There is a script in this repo to assist in getting the packages for
linux only, please contribute to get brew install etc for mac
Clone the repo
```
git clone https://github.com/okd-project/okd-sample-operator
cd okd-sample-operator
```
Execute the script
```
sudo ./operator-software-util.sh
```
Once all the packages have been installed we are ready to start with the scaffolding of the operator
**NB** A complete solution is provided in this repository as a reference.
Create a new directory in your main projects folder.
as an example
```
mkdir mysample-operator
cd mysample-operator
```
We have provided an opinionated **Makefile** (it's been tailored to use in the okd-operator-pipeline).
### Step 1
Create and initialize the project
**N.B.** The operator-sdk init expects the base directory to be empty (i.e no files etc).
```
operator-sdk init --domain okd.io --repo github.com//mysample-operator
```
### Step 2
Create a simple SampleOperator API
```
operator-sdk create api --group=app --version=v1alpha1 --kind=SampleOperator --resource --controller
```
### Step 3
In the file sampleoperator_types.go inside of operator/api/v1aplpha1 change the following code:
```
// SampleOperatorSpec defines the desired state of SampleOperator
type SampleOperatorSpec struct {
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=5
Replicas int32 `json:"replicas,omitempty"`
}
// SampleOperatorStatus defines the observed state of SampleOperator
type SampleOperatorStatus struct {
PodNames []string `json:"podNames"`
AvailableReplicas int32 `json:"availableReplicas"`
}
```
### Step 4
If you are editing the API definitions (as in Step 3), generate the manifests such
as CustomResource's or CustomResourceDefinition's by executing the following
**N.B.** Make a backup of the current **Makefile**
```
# we are in mysample-operator directory
mv Makefile Makefile-bak
```
Copy the *Makefile* (from the solution we provided) to your working directory (mysample-operator)
```
cp ../Makefile .
```
**N.B.** Change the variables at the top of the Makefile
```
PROJECT ?= mysample-operator
REGISTRY ?=
NAMESPACE ?=
```
Execute ther following commands
```
make generate
make manifests
```
### Step 5
Edit the controllers/sampleoperator_controller.go file
Refer to the solution folder (to copy the sampleoperator_controler.go worked out example)
*For more detailed information in what is being done in the controller
please read the inline comments in the code*
### Step 6
As we have updated the sampleoperator_controller.go file and added dependencies execute the following
```
go mod tidy
```
### Step 7
To deploy and execute the controller (run locally so that we can verify/debug)
execute the following
```
export KUBECONFIG=
make deploy
# scale down the manager (so we can run locally)
kubectl scale deployment.apps/operator-controller-manager -n operator-system --replicas=0
make run
```
### Step 8
Edit the file config/samples/app_v1alpha1_sampleoperator.yaml to show the following
```
apiVersion: app.okd.io/v1alpha1
kind: SampleOperator
metadata:
labels:
app.kubernetes.io/name: sampleoperator
app.kubernetes.io/instance: sampleoperator-instance
app.kubernetes.io/part-of: operator
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: operator
name: sampleoperator-instance
spec:
replicas: 2
```
Apply the changes
Open a new terminal to execute the following commands
```
kubectl apply -f config/samples/app_v1alpha1_sampleoperator.yaml
kubectl get pods
```
### Step 9
Check the status of the controller
```
kubectl get sampleoperators.app.okd.io sample-instance -n operator-system -o yaml
```
You can also see the ouptut of the terminal (where you launched *make run*)
### Step 10
Once you are satisfied with all your changes you can go ahead and create a bundle
(this will be used in the pipeline)
```
# a command line prompt is used to input relevant info
make bundle
```
### Conclusion
This is an extremely simple solution, you may want to add other types of objects to watch/deploy
Use the makefile to build and push your specific version to a registry.
Commit your final changes to git.
The project **okd-operator-pipeline** can now be utilized to build, deploy and create a catalog for this operator.
using your git repo.
For the **okd-operator-pipeline** to work on this repo consider using the makefile we have provided)
as it has the correct recipes for the pipeline.
For more information on how to use and deploy the **okd-operator-pipeline** refer to the repository here
[okd-operator-pipeline](https://github.com/okd-project/okd-operator-pipeline)
For more information about developing an operator please refer to the documentation for
[Operator SDK](https://sdk.operatorframework.io/docs/building-operators/golang/quickstart/)