Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs and values.shema.json for operatorcrds migration #1619

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+105 −40
Open

Update docs and values.shema.json for operatorcrds migration #1619

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7daef4
Update docs and values.shema.json for operatorcrds migration
jvoravong Jan 16, 2025
70c1394
Update .chloggen/move-operator-crd-install-method.yaml
jvoravong Jan 17, 2025
cefcf2a
Update docs/auto-instrumentation-install.md
jvoravong Jan 17, 2025
66c23fc
Update docs/auto-instrumentation-install.md
jvoravong Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .chloggen/move-operator-crd-install-method.yaml
View file
Open in desktop
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.
jvoravong marked this conversation as resolved.
Show resolved Hide resolved
- 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
View file
Open in desktop
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`).
jvoravong marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Set the Helm chart value `operatorcrds.install=true` to allow the chart to handle CRD deployment automatically.
Set the Helm chart value `operatorcrds.install=true` to allow the chart to handle CRD installation automatically.

clarifies it is only useful on an install

_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._
jvoravong marked this conversation as resolved.
Show resolved Hide resolved

#### 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How likely is it that these commands get outdated? Is there any way to make this into a test to ensure this doesn't go stale?

This is not a blocker for this PR, just something to consider.


```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 -
```

Copy link
Collaborator

@jinja2 jinja2 Jan 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can also use below helm template command to get the CRD yamls from the helm chart. This method can be helpful in keeping CRDs in-sync with the version bundled with our helm chart.
```bash
helm template helm-charts/splunk-otel-collector/ --include-crds \
--set="splunkObservability.realm=us0,splunkObservability.accessToken=xxxxxx,clusterName=my-cluster,operatorcrds.install=true" \
| yq e '. | select(.kind == "CustomResourceDefinition")' \
| kubectl apply -f -

We can direct users to leverage the our chart to get the crds directly, esp since they can have their CD pipelines just get the correct CRD version from the chart version they want to install

#### 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as previous comment, not blocking: Is there any way to ensure these commands stay up to date and work properly?


```bash
kubectl delete crd opentelemetrycollectors.opentelemetry.io
kubectl delete crd opampbridges.opentelemetry.io
kubectl delete crd instrumentations.opentelemetry.io
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use below combination of helm and kubectl command to delete CRDs.
```bash
helm template helm-charts/splunk-otel-collector/ --include-crds \
--set="splunkObservability.realm=us0,splunkObservability.accessToken=xxxxxx,clusterName=my-cluster,operatorcrds.install=true" \
| yq e '. | select(.kind == "CustomResourceDefinition")' \
| kubectl delete --dry-run=client -f -

### Documentation Resources

- https://developers.redhat.com/devnation/tech-talks/using-opentelemetry-on-kubernetes
Expand Down
2 changes: 2 additions & 0 deletions ...le-operator-and-auto-instrumentation/enable-operator-and-auto-instrumentation-values.yaml
View file
Open in desktop
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
4 changes: 2 additions & 2 deletions examples/enable-operator-and-auto-instrumentation/otel-demo-dotnet.md
View file
Open in desktop
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
4 changes: 2 additions & 2 deletions examples/enable-operator-and-auto-instrumentation/otel-demo-nodejs.md
View file
Open in desktop
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
4 changes: 2 additions & 2 deletions examples/enable-operator-and-auto-instrumentation/spring-petclinic-java.md
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
Loading