Skip to content

Commit

Permalink
Update docs and values.shema.json for operatorcrds migration
Browse files Browse the repository at this point in the history
  • Loading branch information
jvoravong committed Jan 16, 2025
1 parent ce19b52 commit e7daef4
Show file tree
Hide file tree
Showing 9 changed files with 105 additions and 40 deletions.
9 changes: 6 additions & 3 deletions .chloggen/move-operator-crd-install-method.yaml
Original file line number Diff line number Diff line change
@@ -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).
43 changes: 42 additions & 1 deletion docs/auto-instrumentation-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ splunkObservability:
clusterName: CHANGEME
environment: CHANGEME

operatorcrds:
install: true
operator:
enabled: true
certmanager:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ 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
# Check if a cert-manager is already installed by looking for cert-manager pods.
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ 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
# Check if a cert-manager is already installed by looking for cert-manager pods.
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ 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
# Check if a cert-manager is already installed by looking for cert-manager pods.
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
Expand Down
2 changes: 1 addition & 1 deletion helm-charts/splunk-otel-collector/Chart.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
64 changes: 44 additions & 20 deletions helm-charts/splunk-otel-collector/values.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down
13 changes: 4 additions & 9 deletions helm-charts/splunk-otel-collector/values.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit e7daef4

Please sign in to comment.