diff --git a/Makefile b/Makefile index 03a0680..6d600db 100644 --- a/Makefile +++ b/Makefile @@ -7,12 +7,10 @@ help: ## Display this help. ## VERSION: Semantic version for release, use -dev for development pre-release versions. VERSION?=0.1.8-dev -## REGISTRY: Name of image registry -REGISTRY?=quay.io -## REGISTRY_ORG: Name of registry organization. -REGISTRY_ORG?=$(error Set REGISTRY_ORG to push or pull images) +## REGISTRY_BASE: registry/org-name for images. +REGISTRY_BASE?=$(error Set REGISTRY_BASE to push or pull images) ## KORREL8R_VERSION: Version of korrel8r operand. -KORREL8R_VERSION=0.6.6 +KORREL8R_VERSION=0.7.2 ## KORREL8R_IMAGE: Operand image containing the korrel8r executable. KORREL8R_IMAGE?=quay.io/korrel8r/korrel8r:$(KORREL8R_VERSION) ## NAMESPACE: Operator namespace used by `make deploy` and `make bundle-run` @@ -23,7 +21,7 @@ IMGTOOL?=$(shell which podman || which docker) ENVTEST_K8S_VERSION=1.29.x # Names of image and bundle images. -IMG?=$(REGISTRY)/$(REGISTRY_ORG)/operator +IMG?=$(REGISTRY_BASE)/operator IMAGE=$(IMG):$(VERSION) BUNDLE_IMAGE ?= $(IMG)-bundle:$(VERSION) @@ -153,18 +151,18 @@ resource: ## Create the default korrel8r resource OPHUB?=$(error Set OPHUB to the path to your local community-operators-prod clone) OPHUB_VERSION=$(OPHUB)/operators/korrel8r/$(VERSION) -operatorhub: bundle ## Generate manifest for operator hub. Set OPHUB and REGISTRY_ORG. - @[ "$(origin REGISTRY_ORG)" = "command line" ] || { echo "REGISTRY_ORG must be set on the command line"; exit 1; } +operatorhub: bundle ## Generate manifest for operator hub. Set OPHUB and REGISTRY_BASE. + @[ "$(origin REGISTRY_BASE)" = "command line" ] || { echo "REGISTRY_BASE must be set on the command line"; exit 1; } @[ "$$(git status -s)" = "" ] || { git status; echo "working directory not clean"; exit 1; } mkdir -p $(OPHUB_VERSION) cp -aT bundle $(OPHUB_VERSION) echo -e '\n # Annotations for OperatorHub\n com.redhat.openshift.versions: "v4.10"' >> $(OPHUB_VERSION)/metadata/annotations.yaml pre-release: ## Prepare a release commit. - @[ "$(origin REGISTRY_ORG)" = "command line" ] || { echo "REGISTRY_ORG must be set on the command line"; exit 1; } + @[ "$(origin REGISTRY_BASE)" = "command line" ] || { echo "REGISTRY_BASE must be set on the command line"; exit 1; } $(MAKE) test-bundle -release: pre-release ## Set VERISON and REGISTRY_ORG to push release tags and images. +release: pre-release ## Set VERISON and REGISTRY_BASE to push release tags and images. hack/tag-release.sh $(VERSION) $(TAG_FLAGS) $(IMGTOOL) push $(IMAGE) $(IMG):latest $(IMGTOOL) push $(BUNDLE_IMAGE) $(IMG)-bundle:latest diff --git a/README.md b/README.md index 36e5039..ccd7ef7 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ This operator deploys [Korrel8r](https://github.com/korrel8r/korrel8r#readme) as - [Installing](doc/install.adoc) - [Custom resource API Reference](doc/zz_api-ref.adoc) + - [Contributing to the operator code](doc/HACKING.adoc) diff --git a/api/v1alpha1/korrel8r_types.go b/api/v1alpha1/korrel8r_types.go index 1ba5e6a..802eeb5 100644 --- a/api/v1alpha1/korrel8r_types.go +++ b/api/v1alpha1/korrel8r_types.go @@ -11,7 +11,7 @@ import ( // Korrel8rSpec defines the desired state of Korrel8r type Korrel8rSpec struct { - // ServiceAccountName for the korrel8r deployment. Use namespace default if missing. + // ServiceAccountName for the korrel8r deployment, use 'default' if missing. ServiceAccountName string `json:"serviceAccountName,omitempty"` // ConfigMap containing optional custom configuration for Korrel8r. diff --git a/config/crd/bases/korrel8r.openshift.io_korrel8rs.yaml b/config/crd/bases/korrel8r.openshift.io_korrel8rs.yaml index 286f066..d6d5de3 100644 --- a/config/crd/bases/korrel8r.openshift.io_korrel8rs.yaml +++ b/config/crd/bases/korrel8r.openshift.io_korrel8rs.yaml @@ -77,8 +77,8 @@ spec: type: integer type: object serviceAccountName: - description: ServiceAccountName for the korrel8r deployment. Use namespace - default if missing. + description: ServiceAccountName for the korrel8r deployment, use 'default' + if missing. type: string type: object status: diff --git a/config/default/manager_image_patch.yaml b/config/default/manager_image_patch.yaml index 8a6f51e..87b01fb 100644 --- a/config/default/manager_image_patch.yaml +++ b/config/default/manager_image_patch.yaml @@ -10,4 +10,4 @@ spec: - name: manager env: - name: KORREL8R_IMAGE - value: quay.io/korrel8r/korrel8r:0.6.6 + value: quay.io/korrel8r/korrel8r:0.7.2 diff --git a/config/rbac/engine_view_binding.yaml b/config/rbac/engine_view_binding.yaml deleted file mode 100644 index 50bd9dc..0000000 --- a/config/rbac/engine_view_binding.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: engine-view -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: view -subjects: -- kind: ServiceAccount - name: default - namespace: system diff --git a/config/rbac/engine_view_role.yaml b/config/rbac/engine_view_role.yaml deleted file mode 100644 index c4b00bb..0000000 --- a/config/rbac/engine_view_role.yaml +++ /dev/null @@ -1,17 +0,0 @@ -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - # Extra permissions added to the standard clusterrole/view for the korrel8r engine. - name: engine-view -rules: -- apiGroups: - - '*' - resources: - - '*' - verbs: - - '*' -- nonResourceURLs: - - '*' - verbs: - - get - - list diff --git a/config/rbac/kustomization.yaml b/config/rbac/kustomization.yaml index 3df5b61..c9bd4d4 100644 --- a/config/rbac/kustomization.yaml +++ b/config/rbac/kustomization.yaml @@ -6,8 +6,6 @@ resources: - auth_proxy_role.yaml - auth_proxy_role_binding.yaml - auth_proxy_service.yaml - - engine_view_binding.yaml - - engine_view_role.yaml - korrel8r_editor_role.yaml - korrel8r_viewer_role.yaml - role.yaml diff --git a/doc/HACKING.adoc b/doc/HACKING.adoc index 36a023d..6b6c3f0 100644 --- a/doc/HACKING.adoc +++ b/doc/HACKING.adoc @@ -1,30 +1,24 @@ -== Hacking on the Korrel8r Operator - -=== Getting Started += Hacking on the Korrel8r Operator +include::attributes.adoc[] +== Getting Started This project follows the Kubernetes -https://kubernetes.io/docs/concepts/extend-kubernetes/operator/[Operator -pattern]. +https://kubernetes.io/docs/concepts/extend-kubernetes/operator/[Operator pattern]. -It uses -https://kubernetes.io/docs/concepts/architecture/controller/[Controllers], -which provide a reconcile function responsible for synchronizing -resources until the desired state is reached on the cluster. +It uses https://kubernetes.io/docs/concepts/architecture/controller/[Controllers], which provide a +reconcile function responsible for synchronizing resources until the desired state is reached on the +cluster. -You’ll need a Kubernetes cluster to run against. You can use -https://sigs.k8s.io/kind[KIND] to get a local cluster for testing, or -run against a remote cluster. See the -https://korrel8r.github.io/korrel8r/[Korrel8r Documentation] for more -about setting up your cluster. +You’ll need a Kubernetes cluster to run against. You can use https://sigs.k8s.io/kind[KIND] to get a +local cluster for testing, or run against a remote cluster. See the +https://korrel8r.github.io/korrel8r/[Korrel8r Documentation] for more about setting up your cluster. -*Note:* Your controller will automatically use the current context in -your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` -shows). +*Note:* Your controller will automatically use the current context in your kubeconfig file +(i.e. whatever cluster `kubectl cluster-info` shows). -=== Testing the operator +== Testing the operator -Start the operator using one of the methods below, then use this script -to verify it is working: +Start the operator using one of the methods below, then use this script to verify it is working: [source,sh] ---- @@ -38,12 +32,10 @@ some messages ending with ``Success.'' You can customize your own korrel8r resource, and use a browser or REST tools to query it. -==== Running as a local process. +=== Running as a local process. You can run the controller on your own development machine, outside the cluster. This is ideal for debugging. - -[arabic] . Install the CRDs into the cluster: [source,sh] @@ -51,7 +43,6 @@ cluster. This is ideal for debugging. make install ---- -[arabic] . Run the controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): @@ -62,9 +53,8 @@ make run *NOTE:* You can also run this in one step by running: `make install run` -==== Deploying via kustomize +=== Deploying via kustomize -[arabic] . Build and push your image to the location specified by `IMAGE`, which should be a base image name with no tag: @@ -73,29 +63,23 @@ should be a base image name with no tag: make image-build image-push IMAGE= ---- -[arabic] -. Deploy the controller to the cluster with the image specified by -`IMAGE`: +. Deploy the controller to the cluster with the image specified by `IMAGE`: [source,sh] ---- -make deploy IMG= +make deploy IMAGE= ---- -==== Deploy as a bundle image +=== Deploy as a bundle image -[arabic] -. Build and push your image to the location specified by `IMAGE`, which -should be a base image name with no tag. This will create images -latexmath:[$(IMAGE):$](VERSION) and -latexmath:[$(IMAGE)-bundle:$](VERSION) +. Build and push your image to the location specified by `IMAGE`, which should be a base image name with no tag. +This will create images `$(IMAGE):$(VERSION)` and `$(IMAGE)-bundle:$(VERSION)` [source,sh] ---- make push-all IMAGE= ---- -[arabic] . Run the bundle image on your cluster. [source,sh] @@ -103,9 +87,9 @@ make push-all IMAGE= make bundle-run IMAGE= ---- -=== Cleaning up +== Cleaning up -==== Uninstall CRDs +=== Uninstall CRDs To delete the CRDs from the cluster: @@ -114,25 +98,24 @@ To delete the CRDs from the cluster: make uninstall ---- -==== Undeploy the controller +=== Undeploy the controller [source,sh] ---- make undeploy ---- -=== Debugging +== Debugging The `KORREL8R_VERBOSE` environment variable to a numeric value to enable debug logs for the operator: -[arabic, start=0] . The default - some start-up messages, and a single suceess/fail message per reconcile. . Also list the objects modified during reconciliation. . Also print a diff of each object modified during reconciliation. -=== Modifying the API definitions +== Modifying the API definitions If you are editing the API definitions, generate the manifests such as CRs or CRDs using: @@ -142,12 +125,11 @@ CRs or CRDs using: make manifests ---- -*NOTE:* Run `make --help` for more information on all potential `make` -targets +*NOTE:* Run `make --help` for more information on all potential `make` targets More information can be found via the https://book.kubebuilder.io/introduction.html[Kubebuilder Documentation] -=== License +== License See: https://github.com/korrel8r/korrel8r/blob/main/LICENSE diff --git a/doc/RELEASE.adoc b/doc/RELEASE.adoc index e11d827..318ef36 100644 --- a/doc/RELEASE.adoc +++ b/doc/RELEASE.adoc @@ -5,10 +5,10 @@ Steps to release a new version X.Y.Z, for maintainers. On branch `main`: 1. Edit Makefile and set 'VERSION=X.Y.Z' -2. `make pre-release REGISTRY_ORG=korrel8r` +2. `make pre-release REGISTRY_BASE=quay.io/korrel8r` 3. Verify all changes are version related, commit with message 'Release X.Y.Z' + **NOTE:** Normally the only changes in a release commit are `Makefile` and `version.txt` -5. `make release REGISTRY_ORG=korrel8r` +5. `make release REGISTRY_BASE=quay.io/korrel8r` - Re-runs 'make pre-release', verifies the working tree is clean. - Creates and pushes the git tag 'vX.Y.Z' - Pushes ':latest' tag for images. diff --git a/doc/attributes.adoc b/doc/attributes.adoc new file mode 100644 index 0000000..8f02ae5 --- /dev/null +++ b/doc/attributes.adoc @@ -0,0 +1,10 @@ +:copyright: This file is part of korrel8r, released under https://github.com/korrel8r/korrel8r/blob/main/LICENSE +:icons: font +:keywords: correlation, observability, resource, signal, kubernetes +:github: https://github.com/korrel8r/ +:project: {github}/operator#readme +:red-hat: Red{nbsp}Hat +:rh-ocp: {red-hat} OpenShift Container Platform +:rh-console: https://docs.openshift.com/container-platform/latest/web_console/web-console-overview.html[{rh-ocp} web console] +:rh-coo: https://docs.openshift.com/container-platform/latest/observability/cluster_observability_operator/cluster-observability-operator-overview.html[{red-hat} Cluster Observability Operator] +:prewrap!: diff --git a/doc/install.adoc b/doc/install.adoc index 8b1d9ac..e6bba10 100644 --- a/doc/install.adoc +++ b/doc/install.adoc @@ -1,43 +1,28 @@ = Installing the operator -:copyright: This file is part of korrel8r, released under https://github.com/korrel8r/korrel8r/blob/main/LICENSE -:icons: font -// Metadata -:keywords: correlation, observability, resource, signal, kubernetes -:description: Correlation of observability signal data -// URLs -:github: https://github.com/korrel8r/ -:project: {github}/operator#readme -// abbreviations -:red-hat: Red{nbsp}Hat -:rh-ocp: {red-hat} OpenShift Container Platform -:rh-console: link:https://docs.openshift.com/container-platform/latest/web_console/web-console-overview.html[{rh-ocp} web console] -:logging: logging subsystem for {red-hat} OpenShift -:operator: Korrel8r Community Operator - -== From latest release bundle -Install the https://sdk.operatorframework.io/docs/installation/[Operator SDK] tool. - -[source,terminal,subs=attributes+] ----- -kubectl create namespace korrel8r -operator-sdk -n korrel8r run bundle quay.io/korrel8r/operator-bundle:latest --security-context-config restricted ----- +include::attributes.adoc[] + +== {rh-coo} + -= From OperatorHub +NOTE: This is the recommended way to install Korrel8r on {rh-ocp} -There is a community operator for Korrel8r on OperatorHub. -It has been tested with {rh-ocp}, it may or may not work with other k8s clusters. +Installing the {rh-coo} automatically creates a Korrel8r resource, configured for use by the {rh-console}. -.Prerequisites -* You have administrator permissions on an {rh-ocp} cluster version 4.12 or newer. -* You have installed the https://docs.openshift.com/container-platform/latest/logging/cluster-logging-deploying.html[Red Hat OpenShift Logging Operator] version 5.8.1 or newer provided by {red-hat}. -* You have installed the https://docs.openshift.com/container-platform/latest/logging/log_storage/installing-log-storage.html#logging-loki-gui-install_installing-log-storage[Loki Operator] version 5.8.1 or newer provided by {red-hat}, and have created a `LokiStack` custom resource (CR). -* You have https://docs.openshift.com/container-platform/latest/logging/cluster-logging-deploying.html#configuring-log-storage-cr_cluster-logging-deploying[created a `ClusterLogging` CR] that configures LokiStack as the log store. +== OLM bundle .Procedure +. Install the https://sdk.operatorframework.io/docs/installation/[Operator SDK] tool. +. Create the namespace and run the bundle: + +---- +kubectl create namespace korrel8r +operator-sdk -n korrel8r run bundle quay.io/korrel8r/operator-bundle:latest --security-context-config restricted +---- + +== OperatorHub +.Procedure . In the {rh-console} go to `Home > Console > Operators > OperatorHub` . Type "korrel8r" in the filter box and select the Korrel8r Community tile + image:images/operatorhub-tile.png[Korrel8r Community Tile] -. Click Install, Install again, and you are done! +. Follow the installation instructions. diff --git a/doc/korrel8r-resource.adoc b/doc/korrel8r-resource.adoc deleted file mode 100644 index 1d6ade0..0000000 --- a/doc/korrel8r-resource.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= The Korrel8r Resource -:instance-ns: korrel8r -:instance-name: korrel8r-instance -:instance-role: view -:instance-sa: system:serviceaccount: -:user-facing-roles: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles -include::attributes.adoc[] - -== Default korrel8r-instance - -NOTE: These examples assume the operator is installed in the namespace `{instance-ns}`. -Modify the example accordingly if it is installed in a different namespace. - -The simplest way to run Korrel8r is to create the special _default instance_ -in namespace `{instance-ns}` with name `{instance-name}`. - -[source,yaml,subs=attributes+] -.Example of a default Korrel8r instance. ----- -apiVersion: korrel8r.openshift.io/v1alpha1 -kind: Korrel8r -metadata: - name: korrel8r-instance <1> - namespace: {instance-ns} <2> - spec: <3> ----- - -<1> Required name `{instance-name}` for the default instance. -<2> Required namespace `{instance-ns}` for the default instance. -<3> If `spec` is absent or empty, Korrel8r uses a default configuration - that connects to the default signal stores for {rh-ocp}, and integrates with the {rh-console}. + - You can customize the behaviour of the default instance by adding `spec` fields. - -[NOTE] -==== -A `ClusterRoleBinding` for the _default instance_ is installed as part of the operator. -It binds the standard kubernetes `clusterrole/{instance-role}` to the default instance `ServiceAccount`. -You do not need to create this binding or service account. - -This allows the default instance to read most cluster resources and connect to observability stores like Prometheus and Loki. -See the link:{user-facing-roles}[Kubernetes RBAC documentation] for details of the `view` role. - -[source,yaml,subs=attributes+] -.Default instance ClusterRoleBinding installed with the operator. You do not need to create this binding. ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - labels: - app.kubernetes.io/name: korrel8r - name: korrel8r-instance -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: view -subjects: -- kind: ServiceAccount - name: korrel8r-instance - namespace: korrel8r ----- -==== - -== Other Korrel8r resources - -You can create other instances of Korrel8r in any namespace, with any name. -You need to create your own `ClusterRoleBinding` or `RoleBinding` for non-default instances. -You do not need to create `ServiceAccount`, the operator will do that automatically. - -[soure,yaml,subs="attributes+"] -.Example ClusterRoleBinding for Korrel8r my-name in my-namespace. ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding <1> -metadata: - name: my-cluster-role-binding -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: view <2> -subjects: -- kind: ServiceAccount <3> - name: my-name - namespace: my-namespace ----- - -<1> You can also create a `RoleBinding` to restrict Korrel8r to a single namespace. - This will limit correlation results to resources in that namespace. -<2> You can modify the role to restrict what your Korrel8r instance can read. - Korrel8r's functionality will be limited to resources and stores it can access. -<3> The operator creates a `ServiceAccount` with the same namespace and name as the `Korrel8r` instance. - Your `ClusterRoleBinding` or `RoleBinding` should use this as its subject. - You do not need to create this `ServiceAccount`. - diff --git a/doc/zz_api-ref.adoc b/doc/zz_api-ref.adoc index 45f3dc0..16ae60b 100644 --- a/doc/zz_api-ref.adoc +++ b/doc/zz_api-ref.adoc @@ -63,7 +63,7 @@ Korrel8rSpec defines the desired state of Korrel8r [cols="25a,75a", options="header"] |=== | Field | Description -| *`serviceAccountName`* __string__ | ServiceAccountName for the korrel8r deployment. Use namespace default if missing. + +| *`serviceAccountName`* __string__ | ServiceAccountName for the korrel8r deployment, use 'default' if missing. + | *`configMap`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | ConfigMap containing optional custom configuration for Korrel8r. + diff --git a/hack/init-project.sh b/hack/init-project.sh index 85eea25..a052607 100755 --- a/hack/init-project.sh +++ b/hack/init-project.sh @@ -4,5 +4,5 @@ set -ex operator-sdk init --domain openshift.io --owner "Alan Conway" --project-name korrel8r -operator-sdk create api --group korrel8r --version v1alpha1 --kind Korrel8r --resource --controller +operator-sdk create api --group korrel8r --version v1alpha1 --kind Korrel8r --resourceb --controller make