documentation icon indicating copy to clipboard operation
documentation copied to clipboard

[Documentation] Connect a Client to a Cluster

Open rachfop opened this issue 2 years ago • 1 comments

The following is suggested content for the SDK app dev guide. I didn't explicitly include code examples for each section, as those examples already exist and have been reviewed. When this plan is approved, I'll create a PR, with the included code examples and tag each SDK maintainer.

Information about Temporal Cloud will be added when this content is merged and approved.

Please review content.

I will need the following information:

  • [ ] Connect with TLS
  • [ ] Connect with TLS code samples
  • [ ] Connect with authorization headers
  • [ ] Connect with authorization headers code samples

Connect a Client to a Cluster

To create and connect a Temporal Client to a Temporal Cluster, configure your connection and set your Namespace Name.

Configure your connection

To configure your connection, choose one of the following options:

  • To connect a Client to the Cloud
  • To connect a Client to Docker

The port number is used to connect to the Temporal Frontend service. Once the Client is defined, you can start interacting with the Temporal Frontend Service.

Connect a Client to the Cloud

  • To connect a Client to the Cloud, use the following pattern: <Namespace-Name>.tmprl.cloud.
    • Replace <Namespace-Name> with the name of your Namespace.

SDK examples

  • [x] [Add SDK examples]

Connect a Client to Docker

  • To connect a Client to Docker, use the following pattern: 127.0.0.1:7233.
    • 127.0.0.1:7233 is the default address and port number for the Docker image and Temporalite.

SDK examples

  • [x] [Add SDK examples]

Manage your Namespace Name

Namespaces are a logical unit of isolation within the Temporal Platform.

The default Namespace name is default.

To set a custom Namespace, register your custom Namespace name with the Temporal Cluster and then call it from the Client Options.

Register your Namespace Name

Register your custom Namespace Name with the tctl register namespace command.

Set your Namespace Name

Replace <Namespace-Name> with the name of your Namespace.

SDK examples

  • [x] [Add SDK examples]

Authenticate connection

You can connect to your Cluster through mTLS or authorization headers by any of the following options or a mixture of the following options:

  • Reading from the file system
  • Secrets manager
  • Environmental variables

Keep in mind that certificates are whitespace sensitive, and some environment variable systems have been known to modify whitespace.

Connect with mTLS

When connecting to the Temporal Cloud with mTLS, you must provide the following configuration details:

  • Client certificate
  • Client private key

For information about generating Client certification, see the temporalio/client-certificate-generation Docker image to generate Client-side certificates along with keys and configuration files. ​ This Docker image is to be used in conjunction with the Temporal SDK. Keys and their configuration files are valid for 365 days from creation.

For more information about mTLS, see How to manage certificates in the Temporal Cloud user guide.

SDK examples

  • [x] [Add SDK examples]

Connect with TLS

For information about configuring TLS to secure network communication with and within Temporal Cluster, see Temporal Customization Samples.

  • [ ] [WIP] - not enough information to complete section.

SDK examples

  • [ ] [Add SDK examples]

Connect with authorization headers

  • [ ] [WIP] - not enough information to complete section.

Inject a low-level authorizer component that can control access to all API calls.

  • Go uses HeadersProvider HeadersProvider returns a map of gRPC headers that should be used on every request.
  • Python uses static_headers Static headers to use for all calls to the server.

SDK examples

  • [ ] [Add SDK examples]

Technical/Editorial stuff

Since these titles have an implicit, How to* the documentation is written as a procedure (each title can clearly be preceded by the words How to). Procedures or How to’s guides, provide a series of steps.

The idea to leave things out.

Changed Namespace_ID to Namespace Name, as defined here.

Wrap inline placeholders in backticks, and use an asterisk before the first backtick and after the second one (*PLACEHOLDER_NAME*). https://developers.google.com/style/placeholders#placeholders-in-inline-text

You can introduce a procedure with an imperative statement. https://developers.google.com/style/procedures?hl=en#introductory-sentences

The phrase, in the following sections as recommend by: https://developers.google.com/style/headings?hl=en#refer-to-subsections

Titles follow the google style guide, bare infinitive: https://developers.google.com/style/headings?hl=en#heading-and-title-text

rachfop avatar Aug 15 '22 15:08 rachfop

bare infinitive

Connecting -> Connect?

lorensr avatar Aug 15 '22 16:08 lorensr