Configuring the Venafi for Kubernetes Agent¶

The Venafi Kubernetes Agent monitors various Kubernetes resources and offers the flexibility to exclude them as needed. It ensures that no sensitive information is transmitted to Venafi Control Plane for evaluation.

Please be aware that the resource requirements for running the agent within a Kubernetes cluster may vary depending on the number of resources present in the cluster.

Certificate identification¶

The agent extracts certificate information from the following resources:

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

By default, the agent collects information about pods and pod controller resources to identify where the certificate resources are being used, as well as other metadata for the platform.

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

Ingress identification¶

The 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. Venafi Control Plane provides information on the security of these routes based on the certificates they use.

Issuer identification¶

By default, the agent supports all native cert-manager issuers, as well as the following external issuers:

As external cert-manager issuers come with their unique resource definitions, it's necessary to individually add support for them. If you are using an external issuer that is not yet supported, please reach out to Venafi for assistance.

Configuration¶

You configure the agent using a single YAML file that describes the resources you permit it to monitor. When you add your cluster to the Venafi Control Plane, it already includes all the recommended resources to watch. If you want to exclude any of these, simply remove those lines of configuration from the YAML configuration file.

This configuration is important for handling different Kubernetes distributions. For example, the Route resource is the alternative to the Ingress resource within a Red Hat OpenShift cluster.

Note

Removing monitoring of certain resources could limit your access to the complete range of features offered by Venafi Control Plane.

See the following example configuration file:

server: https://api.venafi.cloud/
venafi-cloud:
  uploader_id: "no"
  upload_path: "/v1/tlspk/upload/clusterdata"
data-gatherers:
# gather resources for cert-manager package
  - 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. The 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 the agent monitors. By default, the agent watches resources in all namespaces within the cluster.

See the following examples that use these values:

data-gatherers:
  # include only the 'prod' namespace from another cluster

  - kind: "k8s-dynamic"
    name: "k8s/secrets"
    config:
      resource-type:
        version: v1
        resource: secrets
    include-namespaces:
      - prod
  # exclude the kube-system namespace
  - kind: "k8s-dynamic"
    name: "k8s/certificates"
    config:
      resource-type:
        group: cert-manager.io
        version: v1
        resource: certificates
    exclude-namespaces:
      - kube-system

Configuring the discovery of metadata¶

Venafi Kubernetes Agent discovers and reports metadata, such as labels and annotations, set on Kubernetes resources like Secrets. In Venafi Kubernetes Agent 1.3.0 and later, you can customize the discovery by excluding specific labels and annotations from being reported to Venafi Control Plane. To configure this, add the following to the Agent's values file during deployment:

venafi-kubernetes-agent-values.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.

Viewing annotations and labels in Venafi Control Plane¶

By default, labels and annotations that are reported to Venafi Control Plane are available for viewing and use in the Next Gen Certificate Inventory. Any labels or annotations you have excluded will not be reported to Venafi Control Plane.

To view the labels and annotations assigned to a certificate, sign in to Venafi Control Plane, and then open the Next Gen Certificate Inventory by clicking Inventory > Certificates Next Gen. From there, you have a couple of options:

You can filter the inventory by specific labels, annotations, or both. Click Filters, and then select Kubernetes Labels or Kubernetes Annotations.
You can add columns for labels and annotations. Click Columns, then enable Kubernetes Labels and Kubernetes Annotations.

Tip

You can quickly view the list of certificates used by a specific cluster by clicking Installations > Kubernetes Clusters. Then, click the name of the cluster, and then click the View Certificates button in the drawer. This will open the Next Gen Certificate Inventory, which will be filtered to show only the certificates for the selected cluster.