Skip to content
This repository was archived by the owner on Apr 24, 2024. It is now read-only.

Commit f0a649e

Browse files
ncdcncdc
committed
Add initial widget example
- Use kubebuilder to initialize project - Add Widget API + controller - Update Makefile, readme to describe running on kcp Signed-off-by: Andy Goldstein <andy.goldstein@redhat.com>
1 parent 8e36286 commit f0a649e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1745
-32
lines changed

‎.dockerignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# More info: https://docs.docker.com/engine/reference/builder/#dockerignore-file
2+
# Ignore build and test binaries.
3+
bin/
4+
testbin/

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,5 @@ vendor/
1818
.idea
1919

2020
hack/tools
21+
22+
bin/

‎Dockerfile

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Build the manager binary
2+
FROM golang:1.17 as builder
3+
4+
WORKDIR /workspace
5+
# Copy the Go Modules manifests
6+
COPY go.mod go.mod
7+
COPY go.sum go.sum
8+
# cache deps before building and copying source so that we don't need to re-download as much
9+
# and so that source changes don't invalidate our downloaded layer
10+
RUN go mod download
11+
12+
# Copy the go source
13+
COPY main.go main.go
14+
COPY api/ api/
15+
COPY controllers/ controllers/
16+
17+
# Build
18+
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o manager main.go
19+
20+
# Use distroless as minimal base image to package the manager binary
21+
# Refer to https://github.com/GoogleContainerTools/distroless for more details
22+
FROM gcr.io/distroless/static:nonroot
23+
WORKDIR /
24+
COPY --from=builder /workspace/manager .
25+
USER 65532:65532
26+
27+
ENTRYPOINT ["/manager"]

‎Makefile

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
2+
# Image URL to use all building/pushing image targets
3+
IMG ?= controller:latest
4+
# ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.
5+
ENVTEST_K8S_VERSION = 1.23
6+
7+
# Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
8+
ifeq (,$(shell go env GOBIN))
9+
GOBIN=$(shell go env GOPATH)/bin
10+
else
11+
GOBIN=$(shell go env GOBIN)
12+
endif
13+
14+
# Setting SHELL to bash allows bash commands to be executed by recipes.
15+
# This is a requirement for 'setup-envtest.sh' in the test target.
16+
# Options are set to exit when a recipe line exits non-zero or a piped command fails.
17+
SHELL = /usr/bin/env bash -o pipefail
18+
.SHELLFLAGS = -ec
19+
20+
.PHONY: all
21+
all: build
22+
23+
# kcp specific
24+
APIEXPORT_PREFIX ?= today
25+
26+
##@ General
27+
28+
# The help target prints out all targets with their descriptions organized
29+
# beneath their categories. The categories are represented by '##@' and the
30+
# target descriptions by '##'. The awk commands is responsible for reading the
31+
# entire set of makefiles included in this invocation, looking for lines of the
32+
# file as xyz: ## something, and then pretty-format the target and help. Then,
33+
# if there's a line with ##@ something, that gets pretty-printed as a category.
34+
# More info on the usage of ANSI control characters for terminal formatting:
35+
# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
36+
# More info on the awk command:
37+
# http://linuxcommand.org/lc3_adv_awk.php
38+
39+
.PHONY: help
40+
help: ## Display this help.
41+
@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
42+
43+
##@ Development
44+
45+
.PHONY: manifests
46+
manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
47+
$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
48+
49+
.PHONY: apiresourceschemas
50+
apiresourceschemas: kustomize ## Convert CRDs from config/crds to APIResourceSchemas. Specify APIEXPORT_PREFIX as needed.
51+
$(KUSTOMIZE) build config/crd | kubectl kcp crd snapshot -f - --prefix $(APIEXPORT_PREFIX) > config/kcp/$(APIEXPORT_PREFIX).apiresourceschemas.yaml
52+
53+
.PHONY: generate
54+
generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
55+
$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
56+
57+
.PHONY: fmt
58+
fmt: ## Run go fmt against code.
59+
go fmt ./...
60+
61+
.PHONY: vet
62+
vet: ## Run go vet against code.
63+
go vet ./...
64+
65+
.PHONY: test
66+
test: manifests generate fmt vet envtest ## Run tests.
67+
KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out
68+
69+
##@ Build
70+
71+
.PHONY: build
72+
build: generate fmt vet ## Build manager binary.
73+
go build -o bin/manager main.go
74+
75+
NAME_PREFIX ?= controller-runtime-example-
76+
APIEXPORT_NAME ?= data.my.domain
77+
78+
.PHONY: run
79+
run: manifests generate fmt vet ## Run a controller from your host.
80+
go run ./main.go $(NAME_PREFIX)$(APIEXPORT_NAME)
81+
82+
.PHONY: docker-build
83+
docker-build: test ## Build docker image with the manager.
84+
docker build -t ${IMG} .
85+
86+
.PHONY: docker-push
87+
docker-push: ## Push docker image with the manager.
88+
docker push ${IMG}
89+
90+
##@ Deployment
91+
92+
ifndef ignore-not-found
93+
ignore-not-found = false
94+
endif
95+
96+
.PHONY: install
97+
install: manifests kustomize ## Install APIResourceSchemas and APIExport into kcp (using $KUBECONFIG or ~/.kube/config).
98+
kustomize build config/kcp | kubectl apply -f -
99+
100+
.PHONY: uninstall
101+
uninstall: manifests kustomize ## Uninstall APIResourceSchemas and APIExport from kcp (using $KUBECONFIG or ~/.kube/config). Call with ignore-not-found=true to ignore resource not found errors during deletion.
102+
kustomize build config/kcp | kubectl delete --ignore-not-found=$(ignore-not-found) -f -
103+
104+
.PHONY: deploy
105+
deploy: manifests kustomize ## Deploy controller
106+
cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG}
107+
$(KUSTOMIZE) build config/default | kubectl apply -f -
108+
109+
.PHONY: undeploy
110+
undeploy: ## Undeploy controller. Call with ignore-not-found=true to ignore resource not found errors during deletion.
111+
$(KUSTOMIZE) build config/default | kubectl delete --ignore-not-found=$(ignore-not-found) -f -
112+
113+
##@ Build Dependencies
114+
115+
## Location to install dependencies to
116+
LOCALBIN ?= $(shell pwd)/bin
117+
$(LOCALBIN):
118+
mkdir -p $(LOCALBIN)
119+
120+
## Tool Binaries
121+
KUSTOMIZE ?= $(LOCALBIN)/kustomize
122+
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
123+
ENVTEST ?= $(LOCALBIN)/setup-envtest
124+
125+
## Tool Versions
126+
KUSTOMIZE_VERSION ?= v3.8.7
127+
CONTROLLER_TOOLS_VERSION ?= v0.8.0
128+
129+
KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
130+
.PHONY: kustomize
131+
kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
132+
$(KUSTOMIZE): $(LOCALBIN)
133+
curl -s $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN)
134+
135+
.PHONY: controller-gen
136+
controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
137+
$(CONTROLLER_GEN): $(LOCALBIN)
138+
GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
139+
140+
.PHONY: envtest
141+
envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
142+
$(ENVTEST): $(LOCALBIN)
143+
GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest

‎PROJECT

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
domain: my.domain
2+
layout:
3+
- go.kubebuilder.io/v3
4+
projectName: controller-runtime-example
5+
repo: github.com/kcp-dev/controller-runtime-example
6+
resources:
7+
- api:
8+
crdVersion: v1
9+
namespaced: true
10+
controller: true
11+
domain: my.domain
12+
group: data
13+
kind: Widget
14+
path: github.com/kcp-dev/controller-runtime-example/api/v1alpha1
15+
version: v1alpha1
16+
version: "3"

‎README.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# controller-runtime-example
2+
An example project that is multi-cluster aware and works with [kcp](https://github.com/kcp-dev/kcp)
3+
4+
## Description
5+
This repository contains an example project that works with APIExports and multiple kcp workspaces. It demonstrates
6+
two reconcilers:
7+
8+
1. ConfigMap
9+
1. Get a ConfigMap for the key from the queue, from the correct logical cluster
10+
2. If the ConfigMap has labels["name"], set labels["response"] = "hello-$name" and save the changes
11+
3. List all ConfigMaps in the logical cluster and log each one's namespace and name
12+
4. If the ConfigMap from step 1 has data["namespace"] set, create a namespace whose name is the data value.
13+
5. If the ConfigMap from step 1 has data["secretData"] set, create a secret in the same namespace as the ConfigMap,
14+
with an owner reference to the ConfigMap, and data["dataFromCM"] set to the data value.
15+
16+
2. Widget
17+
1. Show how to list all Widget instances across all logical clusters
18+
2. Get a Widget for the key from the queue, from the correct logical cluster
19+
3. List all Widgets in the same logical cluster
20+
4. Count the number of Widgets (list length)
21+
5. Make sure `.status.total` matches the current count (via a `patch`)
22+
23+
## Getting Started
24+
25+
### Running on kcp
26+
27+
1. Build and push your image to the location specified by `IMG`:
28+
29+
```sh
30+
make docker-build docker-push IMG=<some-registry>/controller-runtime-example:tag
31+
```
32+
33+
1. Deploy the controller to kcp with the image specified by `IMG`:
34+
35+
```sh
36+
make deploy IMG=<some-registry>/controller-runtime-example:tag
37+
```
38+
39+
### Uninstall resources
40+
To delete the resources from kcp:
41+
42+
```sh
43+
make uninstall
44+
```
45+
46+
### Undeploy controller
47+
Undeploy the controller from kcp:
48+
49+
```sh
50+
make undeploy
51+
```
52+
53+
## Contributing
54+
See [CONTRIBUTING.md](CONTRIBUTING.md)
55+
56+
### How it works
57+
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
58+
59+
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
60+
which provides a reconcile function responsible for synchronizing resources until the desired state is reached.
61+
62+
### Test It Out
63+
1. Install the required resources into kcp:
64+
65+
```sh
66+
make install
67+
```
68+
69+
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
70+
71+
```sh
72+
make run
73+
```
74+
75+
**NOTE:** You can also run this in one step by running: `make install run`
76+
77+
### Modifying the API definitions
78+
If you are editing the API definitions, regenerate the manifests using:
79+
80+
```sh
81+
make manifests apiresourceschemas
82+
```
83+
84+
**NOTE:** Run `make --help` for more information on all potential `make` targets
85+
86+
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
87+
88+
## License
89+
90+
Copyright 2022.
91+
92+
Licensed under the Apache License, Version 2.0 (the "License");
93+
you may not use this file except in compliance with the License.
94+
You may obtain a copy of the License at
95+
96+
http://www.apache.org/licenses/LICENSE-2.0
97+
98+
Unless required by applicable law or agreed to in writing, software
99+
distributed under the License is distributed on an "AS IS" BASIS,
100+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
101+
See the License for the specific language governing permissions and
102+
limitations under the License.
103+

‎api/v1alpha1/groupversion_info.go

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
Copyright 2022.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package v1alpha1 contains API Schema definitions for the data v1alpha1 API group
18+
//+kubebuilder:object:generate=true
19+
//+groupName=data.my.domain
20+
package v1alpha1
21+
22+
import (
23+
"k8s.io/apimachinery/pkg/runtime/schema"
24+
"sigs.k8s.io/controller-runtime/pkg/scheme"
25+
)
26+
27+
var (
28+
// GroupVersion is group version used to register these objects
29+
GroupVersion = schema.GroupVersion{Group: "data.my.domain", Version: "v1alpha1"}
30+
31+
// SchemeBuilder is used to add go types to the GroupVersionKind scheme
32+
SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
33+
34+
// AddToScheme adds the types in this group-version to the given scheme.
35+
AddToScheme = SchemeBuilder.AddToScheme
36+
)

‎api/v1alpha1/widget_types.go

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/*
2+
Copyright 2022.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
import (
20+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
21+
)
22+
23+
// WidgetSpec defines the desired state of Widget
24+
type WidgetSpec struct {
25+
Foo string `json:"foo,omitempty"`
26+
}
27+
28+
// WidgetStatus defines the observed state of Widget
29+
type WidgetStatus struct {
30+
Total int `json:"total,omitempty"`
31+
}
32+
33+
// +kubebuilder:object:root=true
34+
// +kubebuilder:subresource:status
35+
36+
// Widget is the Schema for the widgets API
37+
type Widget struct {
38+
metav1.TypeMeta `json:",inline"`
39+
metav1.ObjectMeta `json:"metadata,omitempty"`
40+
41+
Spec WidgetSpec `json:"spec,omitempty"`
42+
Status WidgetStatus `json:"status,omitempty"`
43+
}
44+
45+
// +kubebuilder:object:root=true
46+
47+
// WidgetList contains a list of Widget
48+
type WidgetList struct {
49+
metav1.TypeMeta `json:",inline"`
50+
metav1.ListMeta `json:"metadata,omitempty"`
51+
Items []Widget `json:"items"`
52+
}
53+
54+
func init() {
55+
SchemeBuilder.Register(&Widget{}, &WidgetList{})
56+
}

0 commit comments

Comments
 (0)