Connect to your cluster using the Go client

This example shows how to connect to a cluster through a Go client and use the Go producer and consumer to produce and consume messages to and from a topic. The Go client supports connecting to a Pulsar cluster through either OAuth2 or Token authentication.

Note

This document assumes that you have created a Pulsar cluster and a service account, and have granted the service account produce and consume permissions to the namespace for the target topic.

Prerequisites

Go 1.11 or higher version
Go client 0.1.1+ (without 0.1.1)

For more information, see the installation instructions.

Connect to your cluster through OAuth2 authentication

To connect to a Pulsar cluster through OAuth2 authentication, follow these steps.

Step 1: Get the broker service URL of your cluster

To get the service URL of a Pulsar cluster through the StreamNative Console, follow these steps.

On the left navigation pane, in the Admin area, click Pulsar Clusters.
Select the Details tab, and in the Access Points area, click Copy at the end of the row of the service URL.

Step 2: Get the OAuth2 credential file of your service account

To get an OAuth2 credential file of a service account through the StreamNative Console, follow these steps.

On the left navigation pane, click Service Accounts.
In the row of the service account you want to use, in the Key File column, click the Download icon to download the OAuth2 credential file to your local directory.
The OAuth2 credential file should be something like this:
```
{
  "type": "SN_SERVICE_ACCOUNT",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "client_email": "[email protected]",
  "issuer_url": "https://auth.streamnative.cloud"
}
```

Step 3: Connect to your cluster

For a complete example of how to connect to a cluster through the Pulsar Go client, see Go client examples.

Create a Go consumer to consume messages

You can create and configure a Go consumer to consume messages using the OAuth2 credential file as follows. For more information about the placeholders in the code sample, see parameters for OAuth2 authentication.

package main

import (
	"context"
	"fmt"
	"github.com/apache/pulsar-client-go/pulsar"
	"log"
)

func main() {
    oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
        "type":       "client_credentials",
        "issuerUrl":  "https://auth.streamnative.cloud/",
        "audience":   "urn:sn:pulsar:${orgName}:${instanceName}",
        "privateKey": "file:///YOUR-KEY-FILE-PATH",  // Absolute path of your downloaded key file
    })

    client, err := pulsar.NewClient(pulsar.ClientOptions{
        URL:               "${brokerServiceURL}",
        Authentication:    oauth,
    })

    if err != nil {
        log.Fatalf("Could not instantiate Pulsar client: %v", err)
    }

    defer client.Close()

    consumer, err := client.Subscribe(pulsar.ConsumerOptions{
        Topic:            "persistent://${tenant}/${namespace}/${topic}",
        SubscriptionName: "${subscription}",
        SubscriptionInitialPosition: pulsar.SubscriptionPositionEarliest,
    })

    if err != nil {
        log.Fatal(err)
    }

    defer consumer.Close()

    for i := 0; i < 10; i++ {
        msg, err := consumer.Receive(context.Background())
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("Received message msgId: %v -- content: '%s'\n",
            msg.ID(), string(msg.Payload()))

        consumer.Ack(msg)
    }

    if err := consumer.Unsubscribe(); err != nil {
        log.Fatal(err)
    }
}

Create a Go producer to produce messages

You can create and configure a Go producer to produce messages using the OAuth2 credential file as follows. For more information about the placeholders in the code sample, see parameters for OAuth2 authentication.

package main

import (
	"context"
	"fmt"
	"github.com/apache/pulsar-client-go/pulsar"
	"log"
)

func main() {
    oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
        "type":       "client_credentials",
        "issuerUrl":  "https://auth.streamnative.cloud/",
        "audience":   "urn:sn:pulsar:${orgName}:${instanceName}",
        "privateKey": "file:///YOUR-KEY-FILE-PATH",  // Absolute path of your downloaded key file
    })

    client, err := pulsar.NewClient(pulsar.ClientOptions{
        URL:               "${brokerServiceURL}",
        Authentication:    oauth,
    })

    if err != nil {
        log.Fatalf("Could not instantiate Pulsar client: %v", err)
    }

    defer client.Close()

    producer, err := client.CreateProducer(pulsar.ProducerOptions{
        Topic: "persistent://${tenant}/${namespace}/${topic}",
    })

    if err != nil {
        log.Fatal(err)
    }

    defer producer.Close()

    for i := 0; i < 10; i++ {
        if msgId, err := producer.Send(context.Background(), &pulsar.ProducerMessage{
            Payload: []byte(fmt.Sprintf("hello-%d", i)),
        }); err != nil {
            log.Fatal(err)
        } else {
            fmt.Printf("Published message: %v \n", msgId)
        }
    }
}

Parameters for OAuth2 authentication

privateKey: your downloaded OAuth2 credential. This parameter supports the following two pattern formats:
- file:///path/to/file: the path to your downloaded OAuth2 credential file.
- data:application/json;base64,<base64-encoded value>: the credential file content encoded into Base64 format.
audience: the Uniform Resource Name (URN), which is a combination of the urn:sn:pulsar, your organization name, and your Pulsar instance name.
- ${orgName}: the name of your organization.
- ${instanceName}: the name of your instance.
${brokerServiceURL}: the broker service URL of your Pulsar cluster.
${tenant}/${namespace}/${topic}: the full name of the topic for message production & consumption. It is a combination of the tenant name, the namespace name and the topic name.
${subscription}: the name of the subscription that will determine how messages are delivered.

Connect to your cluster through Token authentication

To connect to a Pulsar cluster through Token authentication, follow these steps.

Step 1: Get the broker service URL of your cluster

To get the service URL of a Pulsar cluster through the StreamNative Console, follow these steps.

On the left navigation pane, in the Admin area, click Pulsar Clusters.
Select the Details tab, and in the Access Points area, click Copy at the end of the row of the service URL.

Step 2: Get the Token of your service account

Note

Before getting the token of a service account, verify that the service account is authorized as a superuser or an admin of the tenants and namespaces.
A token has a system-defined Time-To-Live (TTL) of 7 days. Before a token expires, ensure that you generate a new token for your service account.

To get a token using the StreamNative Console, follow these steps.

On the left navigation pane, click Service Accounts.
In the row of the service account you want to use, in the Token column, click Generate new token, then click the Copy icon to copy the token to your clipboard.

Step 3: Connect to your cluster

For a complete example of how to connect to a cluster through the Pulsar Go client, see Go client examples.

Create a Go consumer to consume messages

You can create and configure a Go consumer to consume messages using Token authentication as follows. For more information about the placeholders in the code sample, see parameters for Token authentication.

package main

import (
	"context"
	"fmt"
	"github.com/apache/pulsar-client-go/pulsar"
	"log"
)

func main() {
    client, err := pulsar.NewClient(pulsar.ClientOptions{
        URL:               "${brokerServiceURL}",
        Authentication:    pulsar.NewAuthenticationToken("${token}"),
    })

    if err != nil {
        log.Fatalf("Could not instantiate Pulsar client: %v", err)
    }

    defer client.Close()

    consumer, err := client.Subscribe(pulsar.ConsumerOptions{
        Topic:            "persistent://${tenant}/${namespace}/${topic}",
        SubscriptionName: "${subscription}",
        SubscriptionInitialPosition: pulsar.SubscriptionPositionEarliest,
    })

    if err != nil {
        log.Fatal(err)
    }

    defer consumer.Close()

    for i := 0; i < 10; i++ {
        msg, err := consumer.Receive(context.Background())
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("Received message msgId: %v -- content: '%s'\n",
            msg.ID(), string(msg.Payload()))

        consumer.Ack(msg)
    }

    if err := consumer.Unsubscribe(); err != nil {
        log.Fatal(err)
    }
}

Create a Go producer to produce messages

You can create and configure a Go producer to produce messages using Token authentication as follows. For more information about the placeholders in the code sample, see parameters for Token authentication.

package main

import (
	"context"
	"fmt"
	"github.com/apache/pulsar-client-go/pulsar"
	"log"
)

func main() {
    client, err := pulsar.NewClient(pulsar.ClientOptions{
        URL:               "${brokerServiceURL}",
        Authentication:    pulsar.NewAuthenticationToken("${token}"),
    })

    if err != nil {
        log.Fatalf("Could not instantiate Pulsar client: %v", err)
    }

    defer client.Close()

    producer, err := client.CreateProducer(pulsar.ProducerOptions{
        Topic: "persistent://${tenant}/${namespace}/${topic}",
    })

    if err != nil {
        log.Fatal(err)
    }

    defer producer.Close()

    for i := 0; i < 10; i++ {
        if msgId, err := producer.Send(context.Background(), &pulsar.ProducerMessage{
            Payload: []byte(fmt.Sprintf("hello-%d", i)),
        }); err != nil {
            log.Fatal(err)
        } else {
            fmt.Printf("Published message: %v \n", msgId)
        }
    }
}

Parameters for Token authentication

${brokerServiceURL}: the broker service URL of your Pulsar cluster.
${token}: the token of your service account.
${tenant}/${namespace}/${topic}: the full name of the topic for message production & consumption. It is a combination of the tenant name, the namespace name and the topic name.
${subscription}: the name of the subscription that will determine how messages are delivered.