You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use Helm generated instead of cert-manager generated certs for the operator (#1648)
* initial draft
* Update CI/CD to support self signed cert data
* update functional tests
* more test fixes
* updates to keep support for the certmanager subchart around, updated the functional aks tests to use certmanager for testing coverage
* Update docs/auto-instrumentation-install.md
Co-authored-by: Jina Jain <[email protected]>
* draft migration guide for 0.118.0 to 0.119.0
* Update docs/auto-instrumentation-install.md
Co-authored-by: Jina Jain <[email protected]>
* Update docs after main merge
* split our pre-commit update into a separate PR
* Documentation improvements, mostly just reorganize content for easier reading
* name fix
* remove doc TODOs
* More upgrading step touch ups
* remove functional test values file updates because they are not needed
* regenerate functional_tests/testdata/expected_kind_values/expected_cluster_receiver.yaml for latest changes brought in from main
* dummy commit to get CI/CD run with the "Ignore Tests" PR label
* restore comment that wasn't ment to be removed
* doc update for autoGenerateCert.enabled
* Remove missed cert-manager references in docs
* Update UPGRADING.md
Co-authored-by: Jina Jain <[email protected]>
---------
Co-authored-by: Jina Jain <[email protected]>
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
2
+
change_type: breaking
3
+
# The name of the component, or a single word describing the area of concern, (e.g. agent, clusterReceiver, gateway, operator, chart, other)
4
+
component: operator
5
+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
6
+
note: Migrate the operator to use Helm generated TLS certificates instead of cert-manager by default
7
+
# One or more tracking issues related to the change
8
+
issues: [1648]
9
+
# (Optional) One or more lines of additional information to render under the primary note.
10
+
# These lines will be padded with 2 spaces and then inserted directly into the document.
11
+
# Use pipe (|) for multiline entries.
12
+
subtext: |
13
+
- Previously, certificates were generated by cert-manager by default; now they are generated by Helm templates unless configured otherwise.
14
+
- This change simplifies the setup for new users while still supporting those who prefer using cert-manager or other solutions. For more details, see the [related documentation](https://github.com/signalfx/splunk-otel-collector-chart/tree/main/docs/auto-instrumentation-install.md#tls-certificate-requirement-for-kubernetes-operator-webhooks).
15
+
- If you use `.Values.operator.enabled=true` and `.Values.certmanager.enabled=true`, please review the [upgrade guidelines](https://github.com/signalfx/splunk-otel-collector-chart/blob/main/UPGRADING.md#0119-to-0120).
Copy file name to clipboardExpand all lines: UPGRADING.md
+98Lines changed: 98 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,103 @@
1
1
# Upgrade guidelines
2
2
3
+
## 0.119.0 to 0.120.0
4
+
5
+
This guide provides steps for new users, transitioning users, and those maintaining previously deployed Operator-related TLS certificates and configurations.
6
+
7
+
- New users: No migration is required for Operator TLS certificates.
8
+
- Previous users: Migration may be needed if using `operator.enabled=true` or `certmanager.enabled=true`.
9
+
10
+
To maintain previous functionality and avoid breaking changes, review the following sections.
11
+
12
+
### **Maintaining Previous Functionality via Helm Values Update**
13
+
14
+
#### **Scenario 1: Operator and cert-manager Deployed via This Helm Chart**
15
+
16
+
If you previously deployed both the Operator and cert-manager via this Helm chart (`operator.enabled=true` and `certmanager.enabled=true`), you can preserve functionality by adding the following values:
17
+
18
+
```yaml
19
+
operator:
20
+
enabled: true
21
+
admissionWebhooks:
22
+
certManager:
23
+
enabled: true
24
+
certificateAnnotations:
25
+
"helm.sh/hook": post-install,post-upgrade
26
+
"helm.sh/hook-weight": "1"
27
+
issuerAnnotations:
28
+
"helm.sh/hook": post-install,post-upgrade
29
+
"helm.sh/hook-weight": "1"
30
+
certmanager:
31
+
enabled: true
32
+
installCRDs: true
33
+
```
34
+
35
+
#### **Scenario 2: Operator Deployed with External cert-manager (Not Managed by This Helm Chart)**
36
+
37
+
If you previously deployed the Operator and used an externally managed cert-manager (`operator.enabled=true` and `certmanager.enabled=false`), you can preserve functionality by adding the following values:
38
+
39
+
```yaml
40
+
operator:
41
+
enabled: true
42
+
admissionWebhooks:
43
+
certManager:
44
+
enabled: true
45
+
```
46
+
47
+
### **Adopting New Functionality (Requires Migration Steps)**
48
+
49
+
If you want to migrate from cert-manager managed certificates to the now default Helm-generated certificates, additional steps may be required to avoid conflicts.
Helm delete will not remove CRDs objects created as part of the cert-manager installation. You can find the command to delete cert-manager CRDs in their official documentation [here](https://cert-manager.io/docs/installation/helm/#uninstalling-with-helm).
3
101
## 0.113.0 to 0.116.0
4
102
5
103
This guide provides steps for new users, transitioning users, and those maintaining previous operator CRD configurations:
In Kubernetes, the API server communicates with operator webhook components over HTTPS, which requires a valid TLS certificate that the API server trusts. The operator supports several methods for configuring the required certificate, each with different levels of complexity and security.
472
464
473
-
### Troubleshooting the Operator and Cert Manager
465
+
---
474
466
475
-
#### Check the logs for failures
467
+
#### 1. **Using a Self-Signed Certificate Generated by the Chart**
476
468
477
-
**Operator Logs:**
469
+
This is the default and simplest method for generating a TLS certificate. It automatically creates a self-signed certificate for the webhook, making it suitable for internal environments or testing purposes. However, it may not be trusted by clients outside your cluster.
478
470
479
-
```bash
480
-
kubectl logs -l app.kubernetes.io/name=operator
471
+
**Note**: The following settings reflect the default values starting in **v1.20.0** of this chart. You only need to update them if using a **previous chart version** or if additional customization is required.
472
+
473
+
```yaml
474
+
operator:
475
+
admissionWebhooks:
476
+
autoGenerateCert:
477
+
enabled: true
478
+
certPeriodDays: 3650
479
+
certManager:
480
+
enabled: false
481
481
```
482
482
483
-
**Cert-Manager Logs:**
483
+
- Setting `operator.admissionWebhooks.certManager.enabled` to `false` and `operator.admissionWebhooks.autoGenerateCert.enabled` to `true` ensures that Helm generates a self-signed TLS certificate.
484
+
- Helm generates a self-signed certificate that is valid for 10 years (3650 days) and stores it in a secret for the Operator webhook. The certificate's validity period can be adjusted using `operator.admissionWebhooks.autoGenerateCert.certPeriodDays`.
485
+
- The certificate is **automatically regenerated** on every Helm upgrade. To disable this behavior, set `operator.admissionWebhooks.autoGenerateCert.recreate` to `false`.
484
486
485
-
```bash
486
-
kubectl logs -l app=certmanager
487
-
kubectl logs -l app=cainjector
488
-
kubectl logs -l app=webhook
489
-
```
487
+
---
490
488
491
-
#### Operator Issues
489
+
#### 2. **Using a cert-manager Certificate**
492
490
493
-
##### Networking and Firewall Requirements
491
+
Using `cert-manager` offers more control over certificate management and is more suitable for production environments. However, due to Helm’s install/upgrade order of operations, cert-manager CRDs and certificates cannot be installed within the same Helm operation. To work around this limitation, you can choose one of the following options:
494
492
495
-
Ensure the Mutating Webhook used by the operator for pod auto-instrumentation is not hindered by network policies or firewall rules. Key points to ensure:
493
+
##### Option 1: **Pre-deploy cert-manager**
496
494
497
-
- **Webhook Accessibility**: The webhook must freely communicate with the cluster IP and the Kubernetes API server. Ensure network policies or firewall rules permit operator-related services to interact with these endpoints.
498
-
- **Required Ports**: Policies should explicitly allow traffic to the necessary ports for seamless operation.
495
+
If `cert-manager` is already deployed in your cluster, you can configure the operator to use it without enabling certificate generation by Helm.
499
496
500
-
Use the following command to identify the IP addresses and ports that need to be accessible:
497
+
**Configuration:**
498
+
```yaml
499
+
operator:
500
+
admissionWebhooks:
501
+
certManager:
502
+
enabled: true
503
+
```
501
504
502
-
```bash
503
-
kubectl get svc -n {operator_namespace}
504
-
# Example output indicating necessary IP and port configurations:
##### Option 2: **Deploy cert-manager and the operator together**
506
+
507
+
If you need to install `cert-manager` along with the operator, use a Helm post-install or post-upgrade hook to ensure that the certificate is created after cert-manager CRDs are installed.
508
+
509
+
**Configuration:**
510
+
```yaml
511
+
operator:
512
+
admissionWebhooks:
513
+
certManager:
514
+
enabled: true
515
+
certificateAnnotations:
516
+
"helm.sh/hook": post-install,post-upgrade
517
+
"helm.sh/hook-weight": "1"
518
+
issuerAnnotations:
519
+
"helm.sh/hook": post-install,post-upgrade
520
+
"helm.sh/hook-weight": "1"
521
+
certmanager:
522
+
enabled: true
523
+
installCRDs: true
510
524
```
511
525
512
-
- **Configuration Action**: Adjust your network policies and firewall settings based on the service endpoints and ports listed by the command. This ensures the webhook and operator services can properly communicate within the cluster.
526
+
This method is useful when installing `cert-manager` as a subchart or as part of a larger Helm chart installation.
513
527
514
-
#### Cert-Manager Issues
528
+
---
515
529
516
-
If the operator seems to be hanging, it could be due to the cert-manager not auto-creating the required certificate. To troubleshoot:
530
+
#### 3. **Using a Custom Externally Generated Certificate**
517
531
518
-
- Check the health and logs of the cert-manager pods for potential issues.
519
-
- Consider restarting the cert-manager pods.
520
-
- Ensure that your cluster has only one instance of cert-manager, which should include `certmanager`, `certmanager-cainjector`, and `certmanager-webhook`.
532
+
For full control, you can use an externally generated certificate. This is suitable if you already have a certificate issued by a trusted CA or have specific security requirements.
521
533
522
-
For additional guidance, refer to the official cert-manager documentation:
- Set both `operator.admissionWebhooks.certManager.enabled` and `operator.admissionWebhooks.autoGenerateCert.enabled` to `false`.
536
+
- Provide the paths to your certificate (`certFile`), private key (`keyFile`), and CA certificate (`caFile`) in the values.
525
537
526
-
##### Validate Certificates
538
+
**Example:**
539
+
```yaml
540
+
operator:
541
+
admissionWebhooks:
542
+
certManager:
543
+
enabled: false
544
+
autoGenerateCert:
545
+
enabled: false
546
+
certFile: /path/to/cert.crt
547
+
keyFile: /path/to/cert.key
548
+
caFile: /path/to/ca.crt
549
+
```
550
+
551
+
This method allows you to use a certificate that is trusted by external systems, such as certificates issued by a corporate CA.
527
552
528
-
Ensure that the certificate, which the cert-manager creates and the operator utilizes, is available.
553
+
---
554
+
555
+
For more advanced use cases, refer to the [official Helm chart documentation](https://github.com/open-telemetry/opentelemetry-helm-charts/blob/main/charts/opentelemetry-operator/values.yaml) for detailed configuration options and scenarios.
##### Using a Self-Signed Certificate for the Webhook
567
+
**Cert-Manager Logs:**
537
568
538
-
The operator supports various methods for managing TLS certificates for the webhook. Below are the options available through the operator, with a brief description for each. For detailed configurations and specific use cases, please refer to the operator’s
**Note**: While using a self-signed certificate offers a quicker and simpler setup, it has limitations, such as not being trusted by default by clients.
542
-
This may be acceptable for testing purposes or internal environments. For complete configurations and additional guidance, please refer to the provided link to the Helm chart documentation.
Copy file name to clipboardExpand all lines: examples/enable-operator-and-auto-instrumentation/README.md
+9Lines changed: 9 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -21,6 +21,15 @@ This example demonstrates how to:
21
21
-**Single App Focus:** Explore trace-related performance of a single instrumented NodeJS application in the APM console.
22
22
-**Simplified Use Case:** Although relations between applications will not be showcased in the APM console, this demo offers a simplified setup suitable for understanding basic instrumentation and trace visualization.
- Deploy the chart to the current namespace and the demo to the `dotnet-demo` namespace.
27
+
- Instrument a single .NET application.
28
+
29
+
**Highlights:**
30
+
-**Single App Focus:** Explore trace-related performance of a single instrumented .NET application in the APM console.
31
+
-**Simplified Use Case:** Although relations between applications will not be showcased in the APM console, this demo offers a simplified setup suitable for understanding basic instrumentation and trace visualization.
32
+
24
33
## Exploring Traces and Applications in APM Console
25
34
The examples provide practical insights into using the APM console for exploring application relations and traces.
26
35
Whether dealing with multiple applications interacting with each other or focusing on a single application, you will gain hands-on experience in visualizing trace data using Splunk Observability APM.
0 commit comments