Addition Secret Format Support kubernetes.io/tls and type: Opaque

[danielnginx]

#3145

User Story

As a platform engineer using NGINX Ingress Controller, I can reference Kubernetes Secrets regardless of their type, so that certificates, CA bundles, licenses, credentials, and other secret material created by common Kubernetes tooling can be reused without conversion, duplication, or type-specific formatting.

Feature Overview

NGINX Ingress Controller should align with NGINX Gateway Fabric behavior by validating Secrets based on the required Secret keys and data content, rather than restricting support based on the Kubernetes Secret type.

For NIC, the Secret type should not determine whether a Secret is supported. Any Kubernetes Secret type should be accepted if the Secret contains the required keys for the feature that references it and the values pass validation.

This applies consistently across NIC features and policies, including TLS certificates, CA certificates, licenses, authentication credentials, and other Secret-backed configuration.

What

Update NIC Secret handling by:

1. Removing feature-level restrictions based on Kubernetes Secret type.
2. Validating Secrets based on required keys and data content.
3. Supporting any Secret type across NIC features and policies where the expected keys are present.
4. Watching and reconciling Secrets based on relevant keys or references, not Secret type.
5. Preserving backward compatibility with existing supported Secret formats.

Why

Many Kubernetes environments use GitOps tools, cert-manager, external secret operators, vault integrations, and custom secret-management systems. These systems may produce Secrets with different type values even when the underlying data is valid.

NIC should not reject otherwise valid Secret-backed configuration solely because the Secret has a non-preferred or non-standard type.

This provides:

• Better compatibility with Kubernetes-native and third-party secret tooling (Opaque support has been a common request)
• Less operational friction for platform and application teams.
• More flexible policy configuration across NIC.
• Reduced duplication of Secrets just to satisfy type-specific controller validation.

Acceptance Criteria

• NIC accepts a referenced Secret of any Kubernetes Secret type when the required keys are present and valid for the referencing feature.
• NIC does not reject a Secret solely because its type is Opaque, kubernetes.io/tls, or any other Kubernetes Secret type.
• TLS configuration succeeds when a referenced Secret contains valid tls.crt and tls.key, regardless of Secret type.
• CA certificate configuration succeeds when a referenced Secret contains the expected CA certificate key, regardless of Secret type.
• License configuration succeeds when a referenced Secret contains the expected license key, regardless of Secret type.
• Authentication, external authentication, and policy-backed Secret references validate required keys rather than Secret type.
• A Secret missing required keys is rejected and not applied.
• A Secret with invalid data for the referencing feature is rejected and not applied.
• Validation failures are surfaced through clear Kubernetes events and controller logs.
• Existing supported Secret behavior remains backward compatible.

Functional Requirements

• NIC must support referenced Secrets of any Kubernetes Secret type.

• NIC must validate Secret compatibility based on the keys required by the referencing feature or policy.

• NIC must not use Secret type as the primary compatibility check.

• NIC must watch and reconcile Secrets based on references and relevant keys rather than Secret type.

• NIC must apply the same Secret key-based validation model across all NIC features and policies that consume Secrets.

• For TLS termination, NIC must require and validate:

  • tls.crt
  • tls.key

• For CA certificate use cases, NIC must require and validate the configured CA certificate key.

• For license use cases, NIC must require and validate the configured license key.

• For credential-based features, NIC must require and validate the expected credential keys for that feature.

• NIC must reject a Secret if required keys are missing.

• NIC must reject a Secret if the referenced data is malformed, invalid, or unusable for the feature.

• NIC must reject TLS Secrets where the certificate and private key do not match.

• NIC must preserve backward compatibility with all currently supported Secret formats.

• NIC must emit clear events and logs that identify:

  • the affected Secret,
  • the referencing resource,
  • the missing or invalid key,
  • and the reason validation failed.

Non-Functional Requirements

• Secret validation should not introduce meaningful reconciliation latency.
• Secret handling should be consistent across NIC features and policies.
• The implementation should avoid feature-specific Secret type allowlists.
• The behavior should be predictable for GitOps, cert-manager, external secret operators, and other secret-management workflows.
• Error messages should be actionable and avoid implying that changing the Secret type is required when the real issue is missing or invalid data.

Out of Scope

• Creating, renewing, or managing Secret data.
• Automatically converting Secrets from one type to another.
• Supporting missing, malformed, or incomplete Secret data.
• Supporting arbitrary key names unless the referencing feature explicitly allows the key name to be configured.
• Changing Kubernetes Secret semantics or validation behavior outside NIC.

Documentation Requirements

• Secret Handling Guide: Explain that NIC validates Secrets by required keys and data content, not by Secret type.
• Feature Key Reference: Document required Secret keys for TLS, CA certificates, licenses, credentials, and policy-backed Secret references.
• Examples: Show valid configurations using different Secret types with the same required keys.
• Migration Notes: Explain the change from type-based support to key-based validation.
• Troubleshooting Guide: Cover missing keys, invalid values, mismatched TLS certificate/private key pairs, and unsupported key names.

Example TLS Secrets

Both examples should be supported because they contain the required tls.crt and tls.key keys.

apiVersion: v1
kind: Secret
metadata:
  name: example-tls
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

apiVersion: v1
kind: Secret
metadata:
  name: example-tls-opaque
type: Opaque
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

Definition of Done

• NIC no longer restricts supported Secrets by Kubernetes Secret type.
• NIC validates Secrets based on required keys and feature-specific data validation.
• All NIC features and policies that reference Secrets support any Secret type when required keys are present and valid.
• Secret watches and reconciliation are based on references and keys rather than Secret type.
• TLS, CA certificate, license, credential, and policy-backed Secret use cases are covered by tests.
• Invalid, incomplete, or mismatched Secret data is rejected safely.
• Validation failures are visible in Kubernetes events and controller logs.
• Existing Secret behavior remains backward compatible.
• Documentation is updated with the key-based Secret validation model, examples, and troubleshooting guidance.

[github-actions]

Hi @danielnginx thanks for reporting!

Be sure to check out the docs and the Contributing Guidelines while you wait for a human to take a look at this 🙂

If your issue concerns any of the enterprise features please open a ticket with F5 directly (For NGINX Plus customers NGINX Ingress Controller (when used with NGINX Plus) is covered by the support contract.)

Cheers!