create-sinks.html.md.erb

---
title: Creating Sink Resources
owner: PKS
---

This topic describes how to create a sink resource for a Kubernetes cluster
provisioned with <%= vars.product_full %> or for a namespace within a
cluster.

## <a id='overview'></a>Overview

Sink resources enable <%= vars.product_short %> users to collect
logs and metrics. You can create the following types of sink resources:

<%= partial 'sink-resources' %>

## <a id='prerequisites'></a>Prerequisites

Before creating a sink resource, do the following:

* If you want to create a `ClusterLogSink` or `LogSink` resource, ensure that the **Enable Log Sink Resources** checkbox is selected in the <%= vars.product_tile %> tile.
* If you want to create a `ClusterMetricSink` or `MetricSink` resource, ensure that the **Enable Metric Sink Resources** checkbox is selected in the <%= vars.product_tile %> tile.

For more information, see the <%= vars.product_short %> installation topic
for your IaaS:

* [Installing <%= vars.product_short %> on vSphere](installing-pks-vsphere.html)
* [Installing <%= vars.product_short %> on vSphere with NSX-T Integration](installing-nsx-t.html)
* [Installing <%= vars.product_short %> on GCP](installing-pks-gcp.html)
* [Installing <%= vars.product_short %> on AWS](installing-pks-aws.html)
* [Installing <%= vars.product_short %> on Azure](installing-pks-azure.html)

### <a name='cli-prereqs'></a> CLI Requirements

To create and manage sink resources, you must install the Kubernetes CLI, <code>kubectl</code>. 

Alternately, to manage `ClusterLogSink` resources with the PKS CLI, you must use PKS CLI v1.3 or later.

For installation instructions, see <a href="installing-kubectl-cli.html">Installing the Kubernetes CLI</a> 
and <a href="installing-pks-cli.html">Installing the PKS CLI</a>.

## <a id='define-resource'></a>Create Sinks

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

* If you want to create a `ClusterLogSink`, see
[ClusterLogSink Resources](#define-cluster-log-sink) below.
* If you want to create a `LogSink`, see
[LogSink Resources](#define-log-sink) below.
* If you want to create a `ClusterMetricSink`, see
[ClusterMetricSink Resources](#define-cluster-metric-sink) below.
* If you want to create a `MetricSink`, see
[MetricSink Resources](#define-metric-sink) below.

<p class="note"><strong>Note:</strong> Log sinks created in <%= vars.product_short %> do not support UDP connections.</p>

### <a id='define-cluster-log-sink'></a>ClusterLogSink Resources

`ClusterLogSink` resources enable you to capture logs from your clusters.

To create and manage `ClusterLogSink` resources, you can:

* [Create ClusterLogSink Resource with the PKS CLI](#cluster-sink-pks)
* [Create a Syslog ClusterLogSink Resource with YAML and kubectl](#syslog-cluster-sink)
* [Create a Webhook ClusterLogSink Resource with YAML and kubectl](#webhook-cluster-sink)

<p class="note"><strong>Note:</strong> <%= vars.product_short %> requires a secure connection
for log forwarding. To forward logs using an unsecured connection, see
<a href="#unsecured-sink-configuration">Unsecured ClusterLogSink and LogSink Log Forwarding</a> below.</p>

#### <a id='cluster-sink-pks'></a> Create ClusterLogSink Resource with the PKS CLI

To create and apply a log sink to a cluster, run the following command:

```
pks create-sink CLUSTER-NAME \
syslog-tls://YOUR-LOG-DESTINATION:YOUR-LOG-DESTINATION-PORT
```
Where:

* `CLUSTER-NAME` is the name of your cluster.
* `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.

<p class="note"><strong>Note:</strong> The sink commands, such as <code>pks create-sink</code> and <code>pks delete-sink</code>,
are deprecated in the PKS CLI. <%= vars.product_short %> will remove these commands in a future release.</p>

For example:

<pre class="terminal">
$ pks create-sink my-cluster syslog-tls://example.com:12345
</pre>

If you do not specify a name, the command creates 
a log sink resource in the cluster that shares the same name as the cluster.

To provide a name for the log sink resources in your cluster, run the following command. 

```
pks create-sink CLUSTER-NAME --name YOUR-SINK \
syslog-tls://YOUR-LOG-DESTINATION:YOUR-LOG-DESTINATION-PORT
```
Where:

* `CLUSTER-NAME` is the name of your cluster.
* `YOUR-SINK` is the name of the log sink you want to create.
* `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.

For example:

<pre class="terminal">
$ pks create-sink my-cluster --name second-sink syslog-tls://example.org:54321
</pre>

Specifying a name is useful if you need to manage multiple log sink resources in your cluster.

#### <a id='syslog-cluster-sink'></a> Create a Syslog ClusterLogSink Resource with YAML and kubectl

A syslog `ClusterLogSink` resource delivers logs using the TCP-based syslog protocol.

To define a syslog `ClusterLogSink` resource with YAML and `kubectl`, perform the following steps:

1. Create a YAML file that specifies your log destination in the following format:
  
    ```
    apiVersion: pksapi.io/v1beta1
    kind: ClusterLogSink
    metadata:
       name: YOUR-SINK-NAME
    spec:
       type: syslog
       host: YOUR-LOG-DESTINATION
       port: YOUR-LOG-DESTINATION-PORT
       enable_tls: true
    ```
  Where:
    * `YOUR-SINK` is a name you choose for your sink.
    * `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.
    <p class="note"><strong>Note:</strong> <code>enable_tls</code> must be <code>true</code>.</p>

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

1. Apply the `ClusterLogSink` resource to your cluster by running the following command:

    ```
    kubectl apply -f MY-SINK.yml
    ```
    Where `MY-SINK.yml` is the name of your YAML file.
    For example:
    <pre class='terminal'>
    $ kubectl apply -f my-cluster-sink.yml
    </pre>

#### <a id='webhook-cluster-sink'></a> Create a Webhook ClusterLogSink Resource with YAML and kubectl

A webhook `ClusterLogSink` resource batches logs into 1 second units, wraps the resulting payload in JSON, and uses the POST method to deliver the logs to the address of your log management service.  

To define a webhook `ClusterLogSink` resource with YAML and `kubectl`, perform the following steps:

1. Create a YAML file that specifies your log destination in the following format:
  
    ```
    apiVersion: pksapi.io/v1beta1
    kind: ClusterLogSink
    metadata:
      name: YOUR-SINK-NAME
    spec:
      type: webhook
      url: YOUR-LOG-DESTINATION
    ```
  Where:
    * `YOUR-SINK-NAME` is a name you choose for your sink.
    * `YOUR-LOG-DESTINATION` is the URL or IP address of your log management service.

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

1. Apply the `ClusterLogSink` resource to your cluster by running the following command:

    ```
    kubectl apply -f MY-SINK.yml
    ```
    Where `MY-SINK.yml` is the name of your YAML file.
    For example:
    <pre class='terminal'>
    $ kubectl apply -f my-cluster-sink.yml
    </pre>

### <a id='define-log-sink'></a> LogSink Resources

A `LogSink` resource filters logs by namespace within a cluster.

You can use only `kubectl` to create and manage log sinks for namespaces.

#### <a id='sink-kubectl'></a> Create a LogSink Resource with YAML and kubectl

To define a `LogSink` resource with YAML and `kubectl`, perform the following steps:

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

    ```
    apiVersion: pksapi.io/v1beta1
    kind: LogSink
    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` is a name you choose for your log sink.
    * `YOUR-NAMESPACE` is the name of your namespace.
    * `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.
    <p class="note"><strong>Note:</strong> <code>enable_tls</code> must be <code>true</code>.</p>
  
1. Save the YAML file with an appropriate file name. For example, `my-namespace-sink.yml`.

1. Apply the `LogSink` resource to your cluster by running the following command:

    ```
    kubectl apply -f MY-SINK.yml
    ```
   Where `MY-SINK.yml` is the name of your YAML file.
   For example:
  <pre class='terminal'>
  $ kubectl apply -f my-namespace-sink.yml
  </pre>

### <a name='unsecured-sink-configuration'></a>Unsecured ClusterLogSink and LogSink Log Forwarding

By default, <%= vars.product_short %> requires a secure connection for `ClusterLogSink` and `LogSink` log forwarding.
To forward `ClusterLogSink` and `LogSink` logs using an unsecured connection, you must first disable log forwarding validation.

1. To disable sink forwarding validation, run the following command:

    ```
    kubectl delete validatingwebhookconfigurations validator.pksapi.io
    ```
<p class="note warning"><strong>Warning:</strong> Disabling secure log forwarding is not recommended.</p>

### <a id='define-cluster-metric-sink'></a> ClusterMetricSink Resources

A `ClusterMetricSink` resource collects metrics from a cluster using the [Kubernetes Input Plugin]
(https://github.com/influxdata/telegraf/tree/master/plugins/inputs/kubernetes) and writes them to one or more outputs
that you specify in the configuration of your `ClusterMetricSink`.
For a list of supported metrics and output plugins,
see [Metrics](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/kubernetes#metrics)
and [Output Plugins](https://github.com/influxdata/telegraf#output-plugins) in the telegraf GitHub repository.

You can use only `kubectl` to create and manage metric sinks for clusters.

#### <a id='default'></a> Create a ClusterMetricSink Resource with YAML and kubectl

To define a `ClusterMetricSink` resource with YAML and `kubectl`, perform the following steps:

1. Create a YAML file in the following format:

    ```
    apiVersion: pksapi.io/v1beta1
    kind: ClusterMetricSink
    metadata:
      name: YOUR-SINK
    spec:
      inputs:
      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.
    <p class="note"><strong>Note:</strong> You can leave the <code>inputs</code> field blank.
    This field is configured to include metrics from the Kubelet by default.</p>

    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
    ```

1. Save the YAML file with an appropriate filename. For example, `my-cluster-metric-sink.yml`.

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

    ```
    kubectl apply -f MY-SINK.yml
    ```
  Where `MY-SINK.yml` is the name of your YAML file.
  For example:
  <pre class='terminal'>
  $ kubectl apply -f my-cluster-metric-sink.yml
  </pre>

### <a id='define-metric-sink'></a> MetricSink Resources

A `MetricSink` resource collects metrics from a namespace within a cluster.

You can use only `kubectl` to create and manage metric sinks for namespaces.

#### <a id='metric-sink'></a> Create a MetricSink Resource with YAML and kubectl

To define a `MetricSink` resource with YAML and `kubectl`, perform the following steps:

1. Create a YAML file in the following format:

    ```
    apiVersion: pksapi.io/v1beta1
    kind: MetricSink
    metadata:
      name: YOUR-SINK
      namespace: YOUR-NAMESPACE
    spec:
      inputs:
      outputs:
      - type: YOUR-OUTPUT-PLUGIN
    ```
  Where:
    * `YOUR-SINK` is a name you choose for your sink.
    * `YOUR-NAMESPACE` is the name of your namespace.
    * `YOUR-OUTPUT-PLUGIN` is the name of the output plugin you want to use for your metrics.
    <p class="note"><strong>Note:</strong> You can leave the <code>inputs</code> field blank.
    This field is configured to include all <code>prometheus.io/scrape</code> annotations set to <code>true</code> by default.</p>

    For example:

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

1. Save the YAML file with an appropriate filename. For example, `my-metric-sink.yml`.

1. Apply the `MetricSink` resource to your cluster by running the following command:

    ```
    kubectl apply -f MY-SINK.yml
    ```
  Where `MY-SINK.yml` is the name of your YAML file.
  For example:
  <pre class='terminal'>
  $ kubectl apply -f my-metric-sink.yml
  </pre>

## <a id='list-sinks'></a> List Sinks

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

###<a id="cluster-log-sink-list"></a> ClusterLogSink Resources

To list log sinks deployed to your cluster, run the following command:

```
pks sinks CLUSTER-NAME
```

Where `CLUSTER-NAME` corresponds to the name of your cluster.

Alternately, you can use `kubectl`:

```
kubectl get clusterlogsinks
``` 

### <a id="log-sink-list"></a> LogSink Resources

To list namespace log sinks, run the following command:

```
kubectl get logsinks
``` 

### <a id="cluster-metric-sink-list"></a> ClusterMetricSink Resources

To list metric sinks deployed to your cluster, run the following command:

```
kubectl get clustermetricsinks
```

### <a id="metric-sink-list"></a> MetricSink Resources

To list namespace metric sinks, run the following command:

```
kubectl get metricsinks
```

## <a id='delete-sinks'></a> Delete Sinks

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

### <a id='cluster-log-sink-delete'></a> ClusterLogSink Resources

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

```
pks delete-sink CLUSTER-NAME --name YOUR-SINK
``` 
Where:

* `CLUSTER-NAME` is the name of your cluster.
* `YOUR-SINK` is the name of your sink.

Alternately, you can use `kubectl`:

```
kubectl delete clusterlogsink YOUR-SINK
``` 

Where `YOUR-SINK` is the name of your sink.

### <a id='log-sink-delete'></a> LogSink Resources

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

```
kubectl delete logsink YOUR-SINK
``` 

Where `YOUR-SINK` is the name of your logsink.

### <a id="cluster-metric-sink-delete"></a> ClusterMetricSink Resources

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

```
kubectl delete clustermetricsink YOUR-SINK
```

Where `YOUR-SINK` is the name of your sink.

### <a id="metric-sink-delete"></a> MetricSink Resources

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

```
kubectl delete metricsink YOUR-SINK
```

Where `YOUR-SINK` is the name of your sink.

## <a id="related-links"></a> Related Links

For more information about sinks in <%= vars.product_short %>, see the following topics:

* For information about using sinks for monitoring, see [Monitoring <%= vars.product_short %> with Sinks](./monitor-sinks.html).
* For information about sink architecture, see [Sink Architecture in <%= vars.product_short %>](sink-architecture.html).