From e19a2c63a1ff6b0d4c8f8a7e6cb108bb86b3e539 Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Mon, 17 Feb 2025 15:26:55 +0100 Subject: [PATCH 1/5] TEST --- gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst index f59199680..d6bff5258 100644 --- a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst +++ b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst @@ -8,7 +8,7 @@ Upgrade the Collector for Kubernetes and other updates .. meta:: :description: Upgrade the Splunk Distribution of OpenTelemetry Collector for Kubernetes. - +TEST TEST .. raw:: html From c87d15638a023b87d1df4b0e6322d7fca8ea3f9d Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Mon, 17 Feb 2025 16:06:27 +0100 Subject: [PATCH 2/5] WIP --- _includes/collector-upgrade.rst | 11 +-- .../kubernetes-upgrade.rst | 85 +++++++++++++++---- 2 files changed, 71 insertions(+), 25 deletions(-) diff --git a/_includes/collector-upgrade.rst b/_includes/collector-upgrade.rst index 8c6b48476..914f6dc24 100644 --- a/_includes/collector-upgrade.rst +++ b/_includes/collector-upgrade.rst @@ -5,17 +5,15 @@ When you update the Collector using the official packages, configuration files a General guidelines ================================= -Apply the following changes to the Collector configuration files for specific version upgrades. - -.. :important:: +.. :note:: For every configuration update use the default agent config as a reference. +Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to :new-page:`Upgrade guidelines ` in GitHub. + From 0.96.1 to 0.97.0 ------------------------------------ - - .. raw:: html
@@ -26,9 +24,6 @@ From 0.96.1 to 0.97.0
- - - From 0.68.0 to 0.69.0 ------------------------------------ diff --git a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst index d6bff5258..a15842138 100644 --- a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst +++ b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst @@ -6,22 +6,7 @@ Upgrade the Collector for Kubernetes and other updates ********************************************************************************* .. meta:: - :description: Upgrade the Splunk Distribution of OpenTelemetry Collector for Kubernetes. - -TEST TEST - -.. raw:: html - -
- -.. include:: /_includes/collector-upgrade.rst - -.. raw:: html - -
- - - + :description: Upgrade the Splunk Distribution of the OpenTelemetry Collector for Kubernetes. .. _otel-upgrade-k8s: @@ -43,7 +28,73 @@ To upgrade the Collector for Kubernetes run the following commands: helm upgrade splunk-otel-collector --values config.yaml splunk-otel-collector-chart/splunk-otel-collector --reuse-values -Read more in the official Helm upgrade options documentation at :new-page:`https://helm.sh/docs/helm/helm_upgrade/#options `. +Read more in the official :new-page:`Helm upgrade options ` documentation. + +.. _otel-upgrade-k8s-guidelines: + +Upgrade guidelines +================================= + +.. :note:: + + For every configuration update use the default agent config as a reference. + +Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to :new-page:`Upgrade guidelines ` in GitHub. + +From 0.113.0 to 0.116.0 +--------------------------------------- + +This guide provides steps for new users, transitioning users, and those maintaining previous operator CRD configurations: + +New users: No migration for CRDs is required. +Previous users: Migration may be needed if using operator.enabled=true. +CRD deployment has evolved over chart versions: + +Before 0.110.0: CRDs were deployed via a crds/ directory (upstream default). +0.110.0 to 1.113.0: CRDs were deployed using Helm templates (upstream default), which had reported issues. +0.116.0 and later: Users must now explicitly configure their preferred CRD deployment method or deploy the CRDs manually to avoid potential issues. Users can deploy CRDs via a crds/ directory again by enabling a newly added value. + +New users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +New users are advised to deploy CRDs via the crds/ directory. For a fresh installation, use the following Helm values: + +operatorcrds: + install: true +operator: + enabled: true +To install the chart: + +helm install splunk-otel-collector-chart/splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true +Current Users (Recommended Migration to crds/ Directory) +If you're using chart versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm templates. To migrate to the recommended crds/ directory deployment: + +Step 1: Delete the Existing Chart +Remove the chart to prepare for a fresh installation: + +helm delete +Step 2: Verify or Remove Existing CRDs +Check if the following CRDs are present and delete them if necessary: + +kubectl get crds | grep opentelemetry +kubectl delete crd opentelemetrycollectors.opentelemetry.io +kubectl delete crd opampbridges.opentelemetry.io +kubectl delete crd instrumentations.opentelemetry.io +Step 3: Reinstall with Recommended Values +Reinstall the chart with the updated configuration: + +helm install splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true +Previous Users (Maintaining Legacy Helm Templates) +If you're using chart versions 0.110.0 to 1.113.0 and prefer to continue deploying CRDs via Helm templates (not recommended), you can do so with the following values: + +operator: + enabled: true +operator: + crds: + create: true +Warning: This method may cause race conditions during installation or upgrades + + .. _otel-upgrade-k8s-access-token: From 9004d0852a564fe77ea756aa7bf2089ba8bfdb0d Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Mon, 17 Feb 2025 16:37:28 +0100 Subject: [PATCH 3/5] WIP --- _includes/collector-upgrade.rst | 6 +- .../kubernetes-upgrade.rst | 78 ++++++++++++++++--- .../collector-linux/linux-upgrade.rst | 2 + .../collector-windows/windows-upgrade.rst | 2 + 4 files changed, 71 insertions(+), 17 deletions(-) diff --git a/_includes/collector-upgrade.rst b/_includes/collector-upgrade.rst index 914f6dc24..d27680912 100644 --- a/_includes/collector-upgrade.rst +++ b/_includes/collector-upgrade.rst @@ -1,7 +1,3 @@ -The installer script uses one of the supported package managers to install the Collector. - -When you update the Collector using the official packages, configuration files are never overridden. If you need to update the configuration after an update, edit them manually before backward compatibility is dropped. - General guidelines ================================= @@ -9,7 +5,7 @@ General guidelines For every configuration update use the default agent config as a reference. -Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to :new-page:`Upgrade guidelines ` in GitHub. +Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to the :new-page:`Upgrade guidelines ` in GitHub. From 0.96.1 to 0.97.0 ------------------------------------ diff --git a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst index a15842138..ab1ef3efd 100644 --- a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst +++ b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst @@ -35,11 +35,15 @@ Read more in the official :new-page:`Helm upgrade options ` in GitHub. +Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to :new-page:`Helm chart upgrade guidelines ` in GitHub. For generic guidelines see :ref:`otel-upgrade-k8s-guidelines-generic`. From 0.113.0 to 0.116.0 --------------------------------------- @@ -59,14 +63,20 @@ New users New users are advised to deploy CRDs via the crds/ directory. For a fresh installation, use the following Helm values: -operatorcrds: - install: true -operator: - enabled: true + .. code-block:: yaml + + operatorcrds: + install: true + operator: + enabled: true + To install the chart: helm install splunk-otel-collector-chart/splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true -Current Users (Recommended Migration to crds/ Directory) + +Current users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + If you're using chart versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm templates. To migrate to the recommended crds/ directory deployment: Step 1: Delete the Existing Chart @@ -87,14 +97,58 @@ helm install splunk-otel-collector --set operatorcrds.install=tru Previous Users (Maintaining Legacy Helm Templates) If you're using chart versions 0.110.0 to 1.113.0 and prefer to continue deploying CRDs via Helm templates (not recommended), you can do so with the following values: -operator: - enabled: true -operator: - crds: - create: true -Warning: This method may cause race conditions during installation or upgrades +.. code-block:: yaml + + operator: + enabled: true + operator: + crds: + create: true + +.. caution:: This method may cause race conditions during installation or upgrades + +From 0.105.5 to 0.108.0 +--------------------------------------- + +We've simplified the Helm chart configuration for operator auto-instrumentation. The values previously under .Values.operator.instrumentation.spec.* have been moved to .Values.instrumentation.*. + +No Action Needed: If you have no customizations under .Values.operator.instrumentation.spec.*, no migration is required. +Action Required: Continuing to use the old values path will result in a Helm install or upgrade error, blocking the process. +Migration Steps: + +Find any references to .Values.operator.instrumentation.spec.* in your Helm values with custom values. +Migrate them from .Values.operator.instrumentation.spec.* to .Values.instrumentation.*. +Example Migration: + +The updated path looks like this: + +.. code-block:: yaml + + instrumentation: + endpoint: XXX + ... + +The deprecated path was: + +.. code-block:: yaml + + operator: + instrumentation: + spec: + endpoint: XXX + ... + +.. _otel-upgrade-k8s-guidelines-generic: + +.. raw:: html + +
+ +.. include:: /_includes/collector-upgrade.rst +.. raw:: html +
.. _otel-upgrade-k8s-access-token: diff --git a/gdi/opentelemetry/collector-linux/linux-upgrade.rst b/gdi/opentelemetry/collector-linux/linux-upgrade.rst index e27434dc5..3100aeaea 100644 --- a/gdi/opentelemetry/collector-linux/linux-upgrade.rst +++ b/gdi/opentelemetry/collector-linux/linux-upgrade.rst @@ -8,7 +8,9 @@ Upgrade the Collector for Linux .. meta:: :description: Upgrade the Splunk Distribution of OpenTelemetry Collector for Linux. +The installer script uses one of the supported package managers to install the Collector. +When you update the Collector using the official packages, configuration files are never overridden. If you need to update the configuration after an update, edit them manually before backward compatibility is dropped. .. raw:: html diff --git a/gdi/opentelemetry/collector-windows/windows-upgrade.rst b/gdi/opentelemetry/collector-windows/windows-upgrade.rst index c943fe488..132699241 100644 --- a/gdi/opentelemetry/collector-windows/windows-upgrade.rst +++ b/gdi/opentelemetry/collector-windows/windows-upgrade.rst @@ -8,7 +8,9 @@ Upgrade the Collector for Windows .. meta:: :description: Upgrade the Splunk Distribution of OpenTelemetry Collector. +The installer script uses one of the supported package managers to install the Collector. +When you update the Collector using the official packages, configuration files are never overridden. If you need to update the configuration after an update, edit them manually before backward compatibility is dropped. .. raw:: html From e6b739853f7d8e749aad5f9a2c27a6f5c5f803b5 Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Tue, 18 Feb 2025 07:05:41 +0100 Subject: [PATCH 4/5] Draft --- .../kubernetes-upgrade.rst | 90 +++++++++---------- 1 file changed, 43 insertions(+), 47 deletions(-) diff --git a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst index ab1ef3efd..c695b23ee 100644 --- a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst +++ b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst @@ -13,6 +13,10 @@ Upgrade the Collector for Kubernetes and other updates Upgrade the Collector for Kubernetes ======================================= +The installer script uses one of the supported package managers to install the Collector. When you update the Collector using the official packages, configuration files are never overridden. If you need to update the configuration after an update, edit them manually before backward compatibility is dropped. + +.. :note:: For every configuration update use the default agent config as a reference. + To upgrade the Collector for Kubernetes run the following commands: - Use the flag ``--reuse-values`` to keep the config values you'd already set while installing or using the Collector: @@ -35,67 +39,67 @@ Read more in the official :new-page:`Helm upgrade options ` in GitHub. For generic guidelines see :ref:`otel-upgrade-k8s-guidelines-generic`. +Apply the following changes to the Collector configuration files for specific version upgrades. For more details refer to :new-page:`Helm chart upgrade guidelines ` in GitHub. From 0.113.0 to 0.116.0 --------------------------------------- -This guide provides steps for new users, transitioning users, and those maintaining previous operator CRD configurations: +Custom resource definition (CRD) configuration has been modified. -New users: No migration for CRDs is required. -Previous users: Migration may be needed if using operator.enabled=true. -CRD deployment has evolved over chart versions: - -Before 0.110.0: CRDs were deployed via a crds/ directory (upstream default). -0.110.0 to 1.113.0: CRDs were deployed using Helm templates (upstream default), which had reported issues. -0.116.0 and later: Users must now explicitly configure their preferred CRD deployment method or deploy the CRDs manually to avoid potential issues. Users can deploy CRDs via a crds/ directory again by enabling a newly added value. +* Before v0.110.0 CRDs were deployed via a ``crds/`` directory (upstream default). +* From v0.110.0 to v1.113.0 CRDs were deployed using Helm templates (upstream default), which had reported issues. +* From v0.116.0 and higher, you must explicitly configure your preferred CRD deployment method or deploy the CRDs manually to avoid potential issues. You can deploy CRDs via a ``crds/`` directory again by enabling a newly added value. New users ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -New users are advised to deploy CRDs via the crds/ directory. For a fresh installation, use the following Helm values: +If you're a new user deploy CRDs via the ``crds/`` directory. For a fresh installation use the following Helm values: - .. code-block:: yaml +.. code-block:: yaml operatorcrds: install: true operator: enabled: true -To install the chart: +To install the chart run: + +.. code-block:: bash -helm install splunk-otel-collector-chart/splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true + helm install splunk-otel-collector-chart/splunk-otel-collector --set operatorcrds.install=true,operator. enabled=true Current users ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you're using chart versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm templates. To migrate to the recommended crds/ directory deployment: +You might need to migrate if using ``operator.enabled=true``. + +If you're using versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm templates. To migrate to the recommended ``crds/`` directory deployment: + +#. Delete the existing chart running -Step 1: Delete the Existing Chart -Remove the chart to prepare for a fresh installation: + .. code-block:: bash + + helm delete + +#. Verify if the following CRDs are present and delete them if necessary: + + .. code-block:: bash + + kubectl get crds | grep opentelemetry + kubectl delete crd opentelemetrycollectors.opentelemetry.io + kubectl delete crd opampbridges.opentelemetry.io + kubectl delete crd instrumentations.opentelemetry.io -helm delete -Step 2: Verify or Remove Existing CRDs -Check if the following CRDs are present and delete them if necessary: +#. Reinstall the chart with the updated configuration: -kubectl get crds | grep opentelemetry -kubectl delete crd opentelemetrycollectors.opentelemetry.io -kubectl delete crd opampbridges.opentelemetry.io -kubectl delete crd instrumentations.opentelemetry.io -Step 3: Reinstall with Recommended Values -Reinstall the chart with the updated configuration: + .. code-block:: bash + + helm install splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true + +Current users maintaining legacy templates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -helm install splunk-otel-collector --set operatorcrds.install=true,operator.enabled=true -Previous Users (Maintaining Legacy Helm Templates) -If you're using chart versions 0.110.0 to 1.113.0 and prefer to continue deploying CRDs via Helm templates (not recommended), you can do so with the following values: +If you're using chart versions 0.110.0 to 1.113.0 and prefer to continue deploying CRDs via Helm templates (not recommended), use the following values: .. code-block:: yaml @@ -105,20 +109,14 @@ If you're using chart versions 0.110.0 to 1.113.0 and prefer to continue deployi crds: create: true -.. caution:: This method may cause race conditions during installation or upgrades +.. caution:: This method might cause race conditions during installation or upgrades. From 0.105.5 to 0.108.0 --------------------------------------- -We've simplified the Helm chart configuration for operator auto-instrumentation. The values previously under .Values.operator.instrumentation.spec.* have been moved to .Values.instrumentation.*. - -No Action Needed: If you have no customizations under .Values.operator.instrumentation.spec.*, no migration is required. -Action Required: Continuing to use the old values path will result in a Helm install or upgrade error, blocking the process. -Migration Steps: +.. note:: If you have no customizations under ``.Values.operator.instrumentation.spec.*`` no migration is required. -Find any references to .Values.operator.instrumentation.spec.* in your Helm values with custom values. -Migrate them from .Values.operator.instrumentation.spec.* to .Values.instrumentation.*. -Example Migration: +The Helm chart configuration for operator auto-instrumentation has been simplified, and the values previously under ``.Values.operator.instrumentation.spec.*`` have been moved to ``.Values.instrumentation.*``. The updated path looks like this: @@ -138,8 +136,6 @@ The deprecated path was: endpoint: XXX ... -.. _otel-upgrade-k8s-guidelines-generic: - .. raw:: html
From 301f9748eb68713cf1878578f688055d351c868c Mon Sep 17 00:00:00 2001 From: Anna Urbiztondo Date: Tue, 18 Feb 2025 08:44:39 +0100 Subject: [PATCH 5/5] Fix --- .../collector-kubernetes/kubernetes-upgrade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst index c695b23ee..7bc343908 100644 --- a/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst +++ b/gdi/opentelemetry/collector-kubernetes/kubernetes-upgrade.rst @@ -75,13 +75,13 @@ You might need to migrate if using ``operator.enabled=true``. If you're using versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm templates. To migrate to the recommended ``crds/`` directory deployment: -#. Delete the existing chart running +1. Delete the existing chart running .. code-block:: bash helm delete -#. Verify if the following CRDs are present and delete them if necessary: +2. Verify if the following CRDs are present and delete them if necessary: .. code-block:: bash @@ -90,7 +90,7 @@ If you're using versions 0.110.0 to 1.113.0, CRDs are likely deployed via Helm t kubectl delete crd opampbridges.opentelemetry.io kubectl delete crd instrumentations.opentelemetry.io -#. Reinstall the chart with the updated configuration: +3. Reinstall the chart with the updated configuration: .. code-block:: bash