Creating and Managing Sink Resources

Note: As of v1.8, Enterprise PKS has been renamed to VMware Tanzu Kubernetes Grid Integrated Edition. Some screenshots in this documentation do not yet reflect the change.

Page last updated:

This topic describes how to create and manage sink resources for a Kubernetes cluster provisioned with VMware Tanzu Kubernetes Grid Integrated Edition (TKGI), or for a namespace within a cluster.

Overview

Sinks collect logs and metrics about Kubernetes worker nodes in your TKGI deployment and workloads that are running on them.

You can create two types of sinks:

  • Log sinks
  • Metric sinks

For more conceptual information about sinks, see Sink Architecture in Tanzu Kubernetes Grid Integrated Edition.

Prerequisites

Before creating a sink resource:

  1. Review Sink Types in Sink Architecture in Tanzu Kubernetes Grid Integrated Edition.
  2. Configure sink resources in the Tanzu Kubernetes Grid Integrated Edition tile > In-Cluster Monitoring:

  3. Install the Kubernetes CLI, kubectl. For installation instructions, see Installing the Kubernetes CLI.

Create Sinks

You can create log and metric sinks for clusters and namespaces.

ClusterLogSink and LogSink Resources

To create ClusterLogSink or LogSink resources, you can:

Note: Log sinks created in TKGI do not support UDP connections.

Note: TKGI requires a secure connection for log forwarding when using ClusterLogSink and LogSink resources of type syslog or webhook. To forward logs using an unsecured connection, see Unsecured ClusterLogSink and LogSink Log Forwarding below.

Create a Syslog ClusterLogSink or LogSink Resource

ClusterLogSink and LogSink resources of type syslog deliver logs using the TCP-based syslog protocol.

To define a syslog ClusterLogSink or LogSink resource, perform the following steps:

  1. Create a YAML file that specifies your log destination in the following format:

    apiVersion: pksapi.io/v1beta1
    kind: YOUR-SINK-RESOURCE
    metadata:
       name: YOUR-SINK
       namespace: YOUR-NAMESPACE
    spec:
       type: syslog
       host: YOUR-LOG-DESTINATION
       port: YOUR-LOG-DESTINATION-PORT
       enable_tls: true
    

    Where:

    • YOUR-SINK-RESOURCE is the sink resource you want to create. This must be either ClusterLogSink or LogSink. For information about these sink resources, see Overview.
    • YOUR-SINK is a name you choose for your sink.
    • YOUR-NAMESPACE is the name of your namespace. Omit this line if creating ClusterLogSink.
    • YOUR-LOG-DESTINATION is the URL or IP address of your log management service.
    • YOUR-LOG-DESTINATION-PORT is the port number of your log management service.

      Note: enable_tls must be true.

  2. Save the YAML file with an appropriate file name. For example, my-cluster-log-sink.yml.

  3. Apply the ClusterLogSink or LogSink resource to your cluster by running the following command:

    kubectl apply -f YOUR-SINK.yml
    

    Where YOUR-SINK.yml is the name of your YAML file. For example:

    $ kubectl apply -f my-cluster-log-sink.yml
    

Create a Webhook ClusterLogSink or LogSink Resource

ClusterLogSink and LogSink resources of type webhook batch logs into one-second units, wrap the resulting payload in JSON, and use the POST method to deliver the logs to the address of your log management service.

To define a webhook ClusterLogSink or LogSink resource, perform the following steps:

  1. Create a YAML file that specifies your log destination in the following format:

    apiVersion: pksapi.io/v1beta1
    kind: YOUR-SINK-RESOURCE
    metadata:
      name: YOUR-SINK
      namespace: YOUR-NAMESPACE
    spec:
      type: webhook
      url: YOUR-LOG-DESTINATION
    

    Where:

    • YOUR-SINK-RESOURCE is the sink resource you want to create. This must be either ClusterLogSink or LogSink. For information about these sink resources, see Overview.
    • YOUR-SINK is a name you choose for your sink.
    • YOUR-NAMESPACE is the name of your namespace. Omit this line if creating ClusterLogSink.
    • YOUR-LOG-DESTINATION is the URL or IP address of your log management service.
  2. Save the YAML file with an appropriate filename. For example, my-cluster-log-sink.yml.

  3. Apply the ClusterLogSink or LogSink resource to your cluster by running the following command:

    kubectl apply -f YOUR-SINK.yml
    

    Where YOUR-SINK.yml is the name of your YAML file. For example:

    $ kubectl apply -f my-cluster-log-sink.yml
    

Create a ClusterLogSink or LogSink Resource with a Fluent Bit Output Plugin

ClusterLogSink and LogSink resources with a Fluent Bit output plugin deliver logs to the output plugin that you specify in your resource configuration.

To define a ClusterLogSink or LogSink resource with a Fluent Bit output plugin, perform the following steps:

  1. Create a YAML file that specifies your log destination in the following format:

    apiVersion: pksapi.io/v1beta1
    kind: YOUR-SINK-RESOURCE
    metadata:
      name: YOUR-SINK
      namespace: YOUR-NAMESPACE
    spec:
      type: http
      output_properties:
        Host: example.com
        Format: json
        Port: 443
        tls: on
        tls.verify: off
    

    Where:

    • YOUR-SINK-RESOURCE is the sink resource you want to create. This must be either ClusterLogSink or LogSink. For information about these sink resources, see Overview.
    • YOUR-SINK is a name you choose for your log sink.
    • YOUR-NAMESPACE is the name of your namespace. Omit this line if creating ClusterLogSink.

    Note: This is a sample plugin configuration for http. For a full list of supported plugins, see the Fluent Bit documentation.

  2. Save the YAML file with an appropriate filename. For example, my-cluster-log-sink.yml.

  3. Apply the ClusterLogSink or LogSink resource to your cluster by running the following command:

    kubectl apply -f YOUR-SINK.yml
    

    Where YOUR-SINK.yml is the name of your YAML file. For example:

    $ kubectl apply -f my-cluster-log-sink.yml
    

Unsecured ClusterLogSink and LogSink Log Forwarding

By default, TKGI requires a secure connection for log forwarding when using ClusterLogSink and LogSink resources of type syslog or webhook.

For debugging purposes on a local machine, you may want to temporarily forward logs using an unsecured connection. To do this, you must:

  1. Disable sink forwarding validation by running the following command:

    kubectl delete validatingwebhookconfigurations validator.pksapi.io
    
  2. Set enable_tls to false in your log destination YAML file.

Warning: Disabling secure log forwarding is not recommended.

ClusterMetricSink and MetricSink Resources

How It Works

By default, a ClusterMetricSink resource collects metrics from a cluster using the Kubernetes Input Plugin and writes them to one or more outputs that you specify in your ClusterMetricSink configuration. Alternatively, you can use Node Exporter as your input plugin. To create a ClusterMetricSink resource, see:

A MetricSink resource collects metrics from a namespace within a cluster using prometheus.io/scrape annotations set to true and writes them to one or more outputs that you specify in your MetricSink configuration. To create a MetricSink resource, follow the instructions in Create a ClusterMetricSink or MetricSink Resource.

For a list of supported output plugins, see Output Plugins in the telegraf GitHub repository.

When to Use MetricSink vs. ClusterMetricSink

Case 1. Isolating Output => MetricSink

If you want to isolate a certain workload’s metrics to its own output, you have to use a namespaced MetricSink. A MetricSink creates a unique telegraf agent pod and ConfigMap in the namespace.

ClusterMetricSinks cannot isolate one input from all the others because all ClusterMetricSinks’ configurations are located in a shared ConfigMap. This means that each ClusterMetricSink’s inputs will also go to all other ClusterMetricSinks’ outputs.

Note that MetricSinks do not have access to pod usage metrics, as the source of those metrics does not filter by namespace and gives usage for all pods on a node.

Case 2. Pod Usage Metrics (CPU, Memory) => ClusterMetricSink

If you want to get pod usage metrics, you have to use a ClusterMetricSink.

To get pod usage metrics, Telegraf agents need to run on every node in a cluster, and this is what the ClusterMetricSink DaemonSet does.

Pod metrics come from the underlying container runtime, which does not isolate metrics based on namespace, so only ClusterMetricSink is able to fetch pod metrics.

ClusterMetricSinks use the Kubernetes input plugin, which gives access to pod usage metrics for each kubernetes node. MetricSinks only run in a single node, so they do not have access to pod usage metrics.

Create a ClusterMetricSink or MetricSink Resource

To define a ClusterMetricSink or MetricSink resource, perform the following steps:

  1. Create a YAML file in the following format:

    apiVersion: pksapi.io/v1beta1
    kind: YOUR-SINK-RESOURCE
    metadata:
      name: YOUR-SINK
      namespace: YOUR-NAMESPACE
    spec:
      inputs:
      outputs:
      - type: YOUR-OUTPUT-PLUGIN
    

    Where:

    • YOUR-SINK-RESOURCE is the sink resource you want to create. This must be either ClusterMetricSink or MetricSink. For information about these sink resources, see Overview.
    • YOUR-SINK is a name you choose for your sink.
    • YOUR-NAMESPACE is the name of your namespace. Omit this line if creating ClusterMetricSink.
    • YOUR-OUTPUT-PLUGIN is the name of the output plugin you want to use for your metrics.

      Note: You can leave the inputs field blank. For ClusterMetricSink, this field is configured to include metrics from the kubelet by default. For MetricSink, the field includes all prometheus.io/scrape annotations set to true by default.

    For example:

    apiVersion: pksapi.io/v1beta1
    kind: ClusterMetricSink
    metadata:
      name: http
    spec:
      inputs:
      outputs:
      - type: http
        url: https://example.com
        method: POST
        data_format: json
    

    This will send all cluster metrics provided by the kubernetes input plugin via json POST to https://example.com

Create a ClusterMetricSink Resource for Node Exporter Metrics

To define a ClusterMetricSink resource for collecting Node Exporter metrics, perform the following steps:

  1. Enable Node Exporter on your cluster workers by selecting the Enable node exporter on workers checkbox in the Tanzu Kubernetes Grid Integrated Edition tile > In-Cluster Monitoring.
  2. Create a YAML file in the following format:

    apiVersion: pksapi.io/v1beta1
    kind: ClusterMetricSink
    metadata:
      name: YOUR-SINK
    spec:
      inputs:
      - monitor_kubernetes_pods: true
        type: prometheus
      outputs:
      - type: YOUR-OUTPUT-PLUGIN
    

    Where:

    • YOUR-SINK is a name you choose for your sink.
    • YOUR-OUTPUT-PLUGIN is the name of the output plugin you want to use for your metrics.

    For example:

    apiVersion: pksapi.io/v1beta1
    kind: ClusterMetricSink
    metadata:
      name: http
    spec:
      inputs:
      - monitor_kubernetes_pods: true
        type: prometheus
      outputs:
      - type: http
        url: https:example.com
        method: POST
        data_format: json
    
  3. Save the YAML file with an appropriate filename. For example, my-cluster-metric-sink.yml.

  4. Apply the ClusterMetricSink resource to your cluster by running the following command:

    kubectl apply -f YOUR-SINK.yml
    

    Where YOUR-SINK.yml is the name of your YAML file. For example:

    $ kubectl apply -f my-cluster-metric-sink.yml
    

Filter Sinks

The LogSink and ClusterLogSink resources allow users to set filters to include or exclude logs or events. For more information, see Monitoring Clusters with Log Sinks.

To filter log sinks, add a filter properties section to the YAML file that specifies your log destination in the following format:

apiVersion: pksapi.io/v1beta1
kind: YOUR-SINK-RESOURCE
metadata:
   name: YOUR-SINK
   namespace: YOUR-NAMESPACE
spec:
   type: syslog
   host: YOUR-LOG-DESTINATION
   port: YOUR-LOG-DESTINATION-PORT
   enable_tls: true
   filters:
    include-events: true
    include-logs: false

Where:

  • YOUR-SINK-RESOURCE is the sink resource type that you created. This must be either ClusterLogSink or LogSink.
  • YOUR-SINK is the name you chose for your sink.
  • YOUR-NAMESPACE is the name of your namespace. Omit this line for ClusterLogSink.
  • YOUR-LOG-DESTINATION is the URL or IP address of your log management service.
  • YOUR-LOG-DESTINATION-PORT is the port number of your log management service.

The default values for these filter properties is true. If you do not specify filter properties, both logs and events are included.

List Sinks

To list sinks for clusters and namespaces, use the commands in the following sections.

ClusterLogSink and LogSink Resources

To list cluster log sinks, run the following command:

kubectl get clusterlogsinks

To list namespace log sinks, run the following command:

kubectl -n YOUR-NAMESPACE get logsinks

Where YOUR-NAMESPACE is the name of your namespace.

ClusterMetricSink and MetricSink Resources

To list cluster metric sinks, run the following command:

kubectl get clustermetricsinks

To list namespace metric sinks, run the following command:

kubectl -n YOUR-NAMESPACE get metricsinks

Where YOUR-NAMESPACE is the name of your namespace.

Delete Sinks

To delete sinks for clusters and namespaces, use the commands in the following sections.

ClusterLogSink and LogSink Resources

To delete a cluster log sink, run the following command:

kubectl delete clusterlogsink YOUR-SINK

Where YOUR-SINK is the name of your sink.

To delete a namespace log sink, run the following command:

kubectl -n YOUR-NAMESPACE delete logsink YOUR-SINK

Where:

  • YOUR-NAMESPACE is the name of your namespace.
  • YOUR-SINK is the name of your log sink.

ClusterMetricSink and MetricSink Resources

To delete a cluster metric sink, use the following command:

kubectl delete clustermetricsink YOUR-SINK

Where YOUR-SINK is the name of your sink.

To delete a namespace metric sink, use the following command:

kubectl -n YOUR-NAMESPACE delete metricsink YOUR-SINK

Where:

  • YOUR-NAMESPACE is the name of your namespace.
  • YOUR-SINK is the name of your metric sink.

Please send any feedback you have to pks-feedback@pivotal.io.