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 Pivotal Container Service (PKS) or for a namespace within a
cluster.

Sink resources enable PKS users to configure destinations for
logs transported following the Syslog Protocol defined in
[RFC 5424](https://tools.ietf.org/html/rfc5424).

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

Before you can create a sink resource within a PKS-provisioned Kubernetes cluster,
you must ensure that the **Enable Sink Resources** checkbox is selected in the PKS tile.
Selecting this checkbox enables clusters and namespaces to send logs to sinks.

For more information, see the _Logging_ section of the PKS installation topic
for your IaaS:

* [Installing PKS on vSphere](installing-pks-vsphere.html#syslog)
* [Installing PKS on vSphere with NSX-T Integration](installing-nsx-t.html#syslog)
* [Installing PKS on GCP](installing-pks-gcp.html#syslog)
* [Installing PKS on AWS](installing-pks-aws.html#syslog)
* [Installing PKS on Azure](installing-pks-azure.html#syslog)

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

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

Alternately, to manage ClusterSink resources, you can use the 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 sinks for clusters and namespaces. 
A namespace sink filters logs by namespace within a cluster.

* If you want to create a cluster sink, see
[ClusterSink Resource](#define-cluster-sink).
* If you want to create a namespace sink, see
[Sink Resource](#define-namespace-sink).

<p class="note"><strong>Note</strong>: Sinks created in PKS only support TCP connections. 
UDP connections are not currently supported.</p>

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

To create and manage ClusterSink resources, you can use either the PKS CLI, <code>pks</code>,  
or the Kubernetes CLI, <code>kubectl</code>. 

If you use the PKS CLI, you must use PKS CLI v1.3 or later.

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

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

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

* `CLUSTER-NAME` is the name of your cluster.
* `syslog` can be specified for non-TLS communication or `syslog-tls` for TLS-enabled communication.
* `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.

For example:

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

For TLS-enabled communication:

<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 sink resource in the cluster that shares the same name as the cluster.

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

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

* `CLUSTER-NAME` is the name of your cluster.
* `syslog` can be specified for non-TLS communication or `syslog-tls` for TLS-enabled communication.
* `YOUR-SINK` is the name of the sink you wish 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.

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

For TLS-enabled communication:

<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 sink resources in your cluster.

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

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

1. Create a YAML file that specifies your log destination in the following format:
  
    ```
    apiVersion: apps.pivotal.io/v1beta1
    kind: ClusterSink
    metadata:
       name: YOUR-SINK
    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.

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

1. Apply the ClusterSink 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-namespace-sink'></a>Sink Resources

A Sink resource filters logs by namespace within a cluster.

Currently you can only use `kubectl` to create and manage namespace sinks.

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

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

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

    ```
    apiVersion: apps.pivotal.io/v1beta1
    kind: Sink
    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 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.

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

1. Apply the Sink 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 id='list-sinks'></a> List Sinks

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

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

Use the following command to list sinks deployed to your cluster:

```
pks sinks CLUSTER-NAME
```

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

Alternately, you can use `kubectl`:

```
kubectl get clustersinks
``` 

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

Use the following command to list namespace sinks:  

```
kubectl get sinks
``` 

This command lists the Sink resources deployed to a namespace.

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

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

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

Use the following command to delete all sinks deployed to your cluster:

```
pks delete-sink CLUSTER-NAME 
``` 

Where `CLUSTER-NAME` is the name of your cluster.

To delete a specific sink, specify the name of the sink you wish to delete:

```
pks delete-sink CLUSTER-NAME --name YOUR-SINK
``` 
Where `YOUR-SINK` is the name of your sink.  

Alternately, you can use `kubectl`:

```
kubectl delete clustersink YOUR-SINK
``` 

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

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

Use the following command to delete a namespace sink:  

```
kubectl delete sink YOUR-SINK
``` 

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

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

For more information on sinks in PKS, see the following topics:

* For information about using sinks for monitoring, see [Monitoring PKS with Sinks](./monitor-sinks.html).
* For information about sink architecture, see [Sink Architecture in PKS](sink-architecture.html).