Skip to content

Configuring Discovery Agent for Next-Gen Trust Security

Discovery Agent for Next-Gen Trust Security monitors Kubernetes resources and can be configured to exclude them as needed. To protect sensitive data, it strips private keys and non-certificate data from secrets before transmission to Next-Gen Trust Security.

Resource requirements

Resource requirements for running Discovery Agent vary depending on the number of resources in the cluster. Performance and memory use will be notably worse on Kubernetes clusters running v1.31 or older where the Kubernetes WatchList feature flag is not enabled.

Certificate identification

Discovery Agent extracts certificate information from the following resources:

  • Certificate - A custom resource provided by a cert-manager instance that represents a template for a single X.509 certificate.
  • CertificateRequest - A custom Kubernetes resource deployed by cert-manager used as part of issuance. In certain cases, such as with istio-csr, this resource is used to store certificate request data.
  • Secret - A native Kubernetes resource for secrets. cert-manager typically stores X.509 certificates in secrets. Discovery Agent evaluates all secrets, not just those of type kubernetes.io/tls, to find certificates where the tls.crt and tls.key data fields are present.

By default, Discovery Agent collects information about pods and pod controller resources to identify where certificate resources are used.

For information on how to filter resources, see the configuration section.

Ingress identification

Discovery Agent identifies entry points to your workloads from the following:

  • Ingress - The native Kubernetes Ingress resource describes named routes to your Kubernetes services including the X.509 certificates they use to secure communication. Next-Gen Trust Security provides information on the security of these routes based on the certificates they use.

Issuer identification

Discovery Agent supports all in-tree cert-manager issuers:

  • ACME Issuer
  • CA Issuer
  • SelfSigned Issuer
  • Hashicorp Vault Issuer

It also supports the following external issuers:

Configuration

You configure Discovery Agent with a YAML file that describes which resources it monitors. The file is stored in a Kubernetes ConfigMap in the cluster. The default configuration includes all recommended resources.

To stop monitoring a resource, remove it from config.yaml in the ConfigMap. Removing resources from the configuration may limit available features in Next-Gen Trust Security.

Different Kubernetes distributions may require different configurations. For example, Red Hat OpenShift clusters use the Route resource instead of Ingress.

The following example gathers only cert-manager Certificate resources:

cluster_name: "prod-cluster"
cluster_description: "Production Kubernetes cluster"
period: "0h1m0s"
claimable_certs: true
data-gatherers:
# gather cert-manager Certificate resources
  - kind: "k8s-dynamic"
    name: "k8s/certificates"
    config:
      resource-type:
        group: cert-manager.io
        version: v1
        resource: certificates

Each element in the data-gatherers list provides some additional configuration values:

  • config.kubeconfig - Allows you to configure monitoring resources in an external cluster. Discovery Agent doesn't have to monitor resources purely in the cluster that it runs in, it can be run outside clusters and use kubeconfig files for authentication.
  • include-namespaces & exclude-namespaces - These values allow you to filter the namespaces that Discovery Agent monitors. By default, Discovery Agent watches resources in all namespaces within the cluster.

Configuring annotations

Discovery Agent discovers and reports metadata, such as labels and annotations, set on Kubernetes resources like Secrets. To exclude specific labels or annotations, add the following to the configuration file during installation:

config.yaml
config:
  ...
  excludeAnnotationKeysRegex:
    - ^kapp\.k14s\.io/original.*$
  excludeLabelKeysRegex:
    - ^.*\.company\.com/.*$

Annotations and labels are allowed by default. The exclusion mechanism relies on Go's RE2 regular expressions.

By default, the annotation kubectl.kubernetes.io/last-applied-configuration is excluded from discovery for security reasons. This annotation might contain sensitive information, and changing this behavior isn't supported.

Regular expression case sensitivity

Regular expressions are evaluated in a case-sensitive manner. For example, if you want to exclude annotation keys containing "SensitiveKey", match the case exactly.

The following list summarizes notable use-cases:

  • Contains: If you want to match anything that contains word, you can use the regular expression word.
  • Starts With: If you want to match anything that starts with word, you need to start the regular expression with ^. For example, if you would like to exclude all annotations starting with company.com, you can use the regular expression ^company\.com.*.
  • Ends With: If you want to match anything that ends with word, use $. For example, if you would like to match all annotations ending with team, you can use team$.
  • Allow List: If you prefer enforcing a deny-by-default policy on the annotations, you can use the negative lookahead syntax ^(?!...)$. For example, if you want to only allow the annotation pod-security.kubernetes.io/enforce, you can use the regular expression ^(?!pod-security\.kubernetes\.io/enforce)$.

Note about escaping with \

The dot (.) is the only character that needs escaping. The character / doesn't need to be escaped. Example: company\.com/team. In your values.yaml, make sure to use either a single-quoted string ('regex') or an unquoted string (regex) for the config.excludeAnnotationKeysRegex and config.excludeLabelKeysRegex fields. Avoid using double-quoted strings ("regex") for these fields, as YAML interprets escape sequences like \. differently in double quotes, which can lead to unexpected behavior.