diff --git a/.chloggen/move-operator-crd-install-method.yaml b/.chloggen/move-operator-crd-install-method.yaml index 5a69759ed5..cbe1b87d60 100644 --- a/.chloggen/move-operator-crd-install-method.yaml +++ b/.chloggen/move-operator-crd-install-method.yaml @@ -1,12 +1,15 @@ # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' -change_type: bug_fix +change_type: breaking # The name of the component, or a single word describing the area of concern, (e.g. agent, clusterReceiver, gateway, operator, chart, other) component: operator # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Move operator CRD installation to the crds/ folder via a subchart to resolve Helm install ordering issues # One or more tracking issues related to the change -issues: [1561] +issues: [1561,1619] # (Optional) One or more lines of additional information to render under the primary note. # These lines will be padded with 2 spaces and then inserted directly into the document. # Use pipe (|) for multiline entries. -subtext: +subtext: | + - Users enabling the operator (`.Values.operator.enabled=true`) must now set `operatorcrds.install=true` in Helm values or [manually manage CRD installation](https://github.com/signalfx/splunk-otel-collector-chart/blob/main/docs/auto-instrumentation-install.md#crd-management). + - Previously, CRDs were installed using templates (`operator.crds.create=true`), which could cause race conditions and install failures. + - CRD installation is now handled via Helm's native `crds/` directory for better stability, using a [localized subchart](https://github.com/signalfx/splunk-otel-collector-chart/tree/main/helm-charts/splunk-otel-collector/charts/opentelemetry-operator-crds). diff --git a/docs/auto-instrumentation-install.md b/docs/auto-instrumentation-install.md index 7a07132e4e..4737f9f6c7 100644 --- a/docs/auto-instrumentation-install.md +++ b/docs/auto-instrumentation-install.md @@ -26,6 +26,8 @@ these frameworks often have pre-built instrumentation capabilities already avail ### 1. Deploy the Helm Chart with the Operator enabled - **Operator Deployment (Required)** + - `operatorcrds.install`: Set to `true` to install the CRDs required by the operator. + - **Required**: Must be set unless CRDs are pre-installed manually. - `operator.enabled`: Set to `true` to enable deploying the operator. - **Required**: This configuration is necessary for the operator's deployment within your cluster. @@ -70,7 +72,7 @@ these frameworks often have pre-built instrumentation capabilities already avail kubectl get pods -l app=cert-manager --all-namespaces # If cert-manager is not deployed, make sure to add certmanager.enabled=true to the list of values to set -helm install splunk-otel-collector -f ./my_values.yaml --set operator.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector +helm install splunk-otel-collector -f ./my_values.yaml --set operatorcrds.install=true,operator.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector ``` ### 2. Verify all the OpenTelemetry resources (collector, operator, webhook, instrumentation) are deployed successfully @@ -284,6 +286,11 @@ in a Kubernetes environment. An operator is a method of packaging, deploying, an In the context of setting up observability in a Kubernetes environment, an operator simplifies the management of application auto-instrumentation, making it easier to gain valuable insights into application performance. +The OpenTelemetry operator relies on +[Custom Resource Definitions (CRDs)](https://github.com/signalfx/splunk-otel-collector-chart/tree/main/helm-charts/splunk-otel-collector/charts/opentelemetry-operator-crds) +to manage auto-instrumentation configurations in Kubernetes. +Ensure the required CRDs are deployed before the operator (by configuring `operatorcrds.install=true`). + With this Splunk OTel Collector chart, the [OpenTelemetry Operator](https://github.com/open-telemetry/opentelemetry-operator#opentelemetry-auto-instrumentation-injection) can be deployed (by configuring `operator.enabled=true`) to your cluster and start auto-instrumenting your applications. @@ -403,6 +410,40 @@ provides best effort support with issues related to native OpenTelemetry instrum | apache-httpd | OpenTelemetry | Available | Needs Validation | | [Link](https://github.com/open-telemetry/opentelemetry-apache-httpd-instrumentation) | ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-apache-httpd | | nginx | OpenTelemetry | Available | Needs Validation | | [Link](https://github.com/open-telemetry/opentelemetry-apache-httpd-instrumentation) | ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-apache-httpd | +### CRD Management + +When deploying the operator, the required Custom Resource Definitions (CRDs) must be deployed beforehand. + +#### Recommended Approach: Automated CRD Deployment + +Set the Helm chart value `operatorcrds.install=true` to allow the chart to handle CRD deployment automatically. +_This option deploys the CRDs using a local subchart, available at https://github.com/signalfx/splunk-otel-collector-chart/tree/main/helm-charts/splunk-otel-collector/charts/opentelemetry-operator-crds._ + +#### Alternative Approach: Manual CRD Deployment + +If you prefer to manage CRD deployment manually, apply the CRDs using the commands below before installing the Helm chart: + +```bash +curl -sL https://raw.githubusercontent.com/open-telemetry/opentelemetry-operator/main/config/crd/bases/opentelemetry.io_opentelemetrycollectors.yaml | kubectl apply -f - +curl -sL https://raw.githubusercontent.com/open-telemetry/opentelemetry-operator/main/config/crd/bases/opentelemetry.io_opampbridges.yaml | kubectl apply -f - +curl -sL https://raw.githubusercontent.com/open-telemetry/opentelemetry-operator/main/config/crd/bases/opentelemetry.io_instrumentations.yaml | kubectl apply -f - +``` + +#### CRD Updates + +With Helm v3.0 and later, CRDs created by this chart are not updated automatically. To update CRDs, you must apply the updated CRD definitions manually. +Refer to the [Helm Documentation on CRDs](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/) for more details. + +#### CRD Cleanup + +When uninstalling this chart, the OpenTelemetry CRDs are not removed automatically. To delete them manually, use the following commands: + +```bash +kubectl delete crd opentelemetrycollectors.opentelemetry.io +kubectl delete crd opampbridges.opentelemetry.io +kubectl delete crd instrumentations.opentelemetry.io +``` + ### Documentation Resources - https://developers.redhat.com/devnation/tech-talks/using-opentelemetry-on-kubernetes diff --git a/examples/enable-operator-and-auto-instrumentation/enable-operator-and-auto-instrumentation-values.yaml b/examples/enable-operator-and-auto-instrumentation/enable-operator-and-auto-instrumentation-values.yaml index bad14c1eb6..def8c7d41c 100644 --- a/examples/enable-operator-and-auto-instrumentation/enable-operator-and-auto-instrumentation-values.yaml +++ b/examples/enable-operator-and-auto-instrumentation/enable-operator-and-auto-instrumentation-values.yaml @@ -7,6 +7,8 @@ splunkObservability: clusterName: CHANGEME environment: CHANGEME +operatorcrds: + install: true operator: enabled: true certmanager: diff --git a/examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md b/examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md index 3eb6a695b9..d28b6b2a41 100644 --- a/examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md +++ b/examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md @@ -24,7 +24,7 @@ curl https://raw.githubusercontent.com/signalfx/splunk-otel-collector-chart/main #### 2.1 Deploy the Helm Chart with the Operator enabled To install the chart with operator in an existing cluster, make sure you have cert-manager installed and available. -Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set certmanager.enabled=true,operator.enabled=true`. +Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set operatorcrds.install=true,operator.enabled=true,certmanager.enabled=true`. These helm install commands will deploy the chart to the current namespace for this example. ```bash @@ -32,7 +32,7 @@ These helm install commands will deploy the chart to the current namespace for t kubectl get pods -l app=cert-manager --all-namespaces # If cert-manager is deployed, make sure to remove certmanager.enabled=true to the list of values to set -helm install splunk-otel-collector -f ./my_values.yaml --set operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector +helm install splunk-otel-collector -f ./my_values.yaml --set operatorcrds.install=true,operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector ``` #### 2.2 Verify all the OpenTelemetry resources (collector, operator, webhook, instrumentation) are deployed successfully diff --git a/examples/enable-operator-and-auto-instrumentation/otel-demo-nodejs.md b/examples/enable-operator-and-auto-instrumentation/otel-demo-nodejs.md index 3185e554c2..c835e69d61 100644 --- a/examples/enable-operator-and-auto-instrumentation/otel-demo-nodejs.md +++ b/examples/enable-operator-and-auto-instrumentation/otel-demo-nodejs.md @@ -20,7 +20,7 @@ curl https://raw.githubusercontent.com/signalfx/splunk-otel-collector-chart/main #### 2.1 Deploy the Helm Chart with the Operator enabled To install the chart with operator in an existing cluster, make sure you have cert-manager installed and available. -Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set certmanager.enabled=true,operator.enabled=true`. +Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set operatorcrds.instal=true,operator.enabled=true,certmanager.enabled=true`. These helm install commands will deploy the chart to the current namespace for this example. ```bash @@ -28,7 +28,7 @@ These helm install commands will deploy the chart to the current namespace for t kubectl get pods -l app=cert-manager --all-namespaces # If cert-manager is deployed, make sure to remove certmanager.enabled=true to the list of values to set -helm install splunk-otel-collector -f ./my_values.yaml --set operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector +helm install splunk-otel-collector -f ./my_values.yaml --set operatorcrds.install=true,operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector ``` #### 2.2 Verify all the OpenTelemetry resources (collector, operator, webhook, instrumentation) are deployed successfully diff --git a/examples/enable-operator-and-auto-instrumentation/spring-petclinic-java.md b/examples/enable-operator-and-auto-instrumentation/spring-petclinic-java.md index d918e6be6b..fb5d93b640 100644 --- a/examples/enable-operator-and-auto-instrumentation/spring-petclinic-java.md +++ b/examples/enable-operator-and-auto-instrumentation/spring-petclinic-java.md @@ -20,7 +20,7 @@ curl https://raw.githubusercontent.com/signalfx/splunk-otel-collector-chart/main #### 2.1 Deploy the Helm Chart with the Operator enabled To install the chart with operator in an existing cluster, make sure you have cert-manager installed and available. -Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set certmanager.enabled=true,operator.enabled=true`. +Both the cert-manager and operator are subcharts of this chart and can be enabled with `--set operatorcrds.install=true,operator.enabled=true,certmanager.enabled=true`. These helm install commands will deploy the chart to the current namespace for this example. ```bash @@ -28,7 +28,7 @@ These helm install commands will deploy the chart to the current namespace for t kubectl get pods -l app=cert-manager --all-namespaces # If cert-manager is deployed, make sure to remove certmanager.enabled=true to the list of values to set -helm install splunk-otel-collector -f ./my_values.yaml --set operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector +helm install splunk-otel-collector -f ./my_values.yaml --set operatorcrds.install=true,operator.enabled=true,certmanager.enabled=true,environment=dev splunk-otel-collector-chart/splunk-otel-collector ``` #### 2.2 Verify all the OpenTelemetry resources (collector, operator, webhook, instrumentation) are deployed successfully diff --git a/helm-charts/splunk-otel-collector/Chart.yaml b/helm-charts/splunk-otel-collector/Chart.yaml index 9a9bd97dd3..93a9d37107 100644 --- a/helm-charts/splunk-otel-collector/Chart.yaml +++ b/helm-charts/splunk-otel-collector/Chart.yaml @@ -28,7 +28,7 @@ dependencies: repository: https://charts.jetstack.io condition: certmanager.enabled - name: opentelemetry-operator-crds - version: "0.0.1" + version: 0.0.1 alias: operatorcrds condition: operatorcrds.install - name: opentelemetry-operator diff --git a/helm-charts/splunk-otel-collector/values.schema.json b/helm-charts/splunk-otel-collector/values.schema.json index 9d4c549b86..176736b03d 100644 --- a/helm-charts/splunk-otel-collector/values.schema.json +++ b/helm-charts/splunk-otel-collector/values.schema.json @@ -1424,15 +1424,57 @@ "type": "boolean", "deprecated": true }, + "operatorcrds": { + "description": "Deploys Operator related CRDs from https://github.com/open-telemetry/opentelemetry-operator/tree/main/config/crd via a Helm subchart and using the chart crds/ directory.", + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, + "operator-crds": { + "description": "Configuration for operator-crds (legacy). Prefer using 'operatorcrds' for new installations. Deploys Operator related CRDs from https://github.com/open-telemetry/opentelemetry-operator/tree/main/config/crd via a Helm subchart and using the chart crds/ directory.", + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, "operator": { "description": "OpenTelemetry Operator configuration. A subchart that is used to install the operator, see https://github.com/open-telemetry/opentelemetry-helm-charts/blob/main/charts/opentelemetry-operator/values.schema.json for more info.", "type": "object", - "additionalProperties": true + "additionalProperties": true, + "properties": { + "crds": { + "type": "object", + "properties": { + "create": { + "description": "This value must always be false to avoid race condition errors during Helm deployments.", + "type": "boolean", + "const": false + } + } + } + } }, "opentelemetry-operator": { "description": "OpenTelemetry Operator configuration (legacy). Prefer using 'operator' for new installations. This field is provided for backward compatibility with older Helm versions or custom distributions. A subchart that is used to install the operator, see https://github.com/open-telemetry/opentelemetry-helm-charts/blob/main/charts/opentelemetry-operator/values.schema.json for more info.", "type": "object", - "additionalProperties": true + "additionalProperties": true, + "properties": { + "crds": { + "type": "object", + "properties": { + "create": { + "description": "This value must always be false to avoid race condition errors during Helm deployments.", + "type": "boolean", + "const": false + } + } + } + } }, "instrumentation": { "type": "object", @@ -1684,24 +1726,6 @@ } } }, - "operatorcrds": { - "description": "Deploys Operator related CRDs from https://github.com/open-telemetry/opentelemetry-operator/tree/main/config/crd via a Helm subchart and using the chart crds/ directory.", - "type": "object", - "properties": { - "install": { - "type": "boolean" - } - } - }, - "operator-crds": { - "description": "Configuration for operator-crds (legacy). Prefer using 'operatorcrds' for new installations. Deploys Operator related CRDs from https://github.com/open-telemetry/opentelemetry-operator/tree/main/config/crd via a Helm subchart and using the chart crds/ directory.", - "type": "object", - "properties": { - "install": { - "type": "boolean" - } - } - }, "certmanager": { "description": "cert-manager adds certificates and certificate issuers as resource types in Kubernetes clusters, and simplifies the process of obtaining, renewing and using those certificates.", "type": "object", diff --git a/helm-charts/splunk-otel-collector/values.yaml b/helm-charts/splunk-otel-collector/values.yaml index 97d3d98584..e0500b2bfb 100644 --- a/helm-charts/splunk-otel-collector/values.yaml +++ b/helm-charts/splunk-otel-collector/values.yaml @@ -1174,21 +1174,16 @@ service: # Full list of Helm value configurations: https://artifacthub.io/packages/helm/opentelemetry-helm/opentelemetry-operator?modal=values ################################################################################ -# Should the CRDs be installed by a chart's crd/ directory or by using templates. +# Specify whether the chart should install CRDs automatically. +# Related Documentation: https://github.com/signalfx/splunk-otel-collector-chart/blob/main/docs/auto-instrumentation-install.md#crd-management operatorcrds: - # Should the CRDs be installed + # Set to true to install CRDs automatically, or false to manage them manually. install: false operator: enabled: false - # This is disabled by default in favor of using `operatorcrds.install=true`, as doing so creates - # a race condition with helm. - # See: https://github.com/open-telemetry/opentelemetry-helm-charts/issues/677 - # Users of this chart should _never_ set this to be true. If a user wishes - # to install the CRDs through the opentelemetry-operator chart, it is recommended - # to install the opentelemetry-operator chart separately and prior to the installation - # of this chart. crds: + # This value is set to false and cannot be changed; use `operatorcrds.install` instead. create: false admissionWebhooks: certManager: