documentation
documentation copied to clipboard
[Documentation] Connect a Client to a Cluster
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.
- Replace
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
bare infinitive
Connecting -> Connect?