Merge pull request #509 from PSanetra/add-environment-variables

feat: Support standard environment variables

docs/channels.rst

@@ -6,4 +6,5 @@ Channels
     :name: channels
 
     Quickstart <channels_quickstart>
+    Configuration <channels_configuration>
     Reference <channels_reference>

docs/channels_configuration.rst

@@ -0,0 +1,123 @@
+======================
+Channels Configuration
+======================
+
+This document describes the environment variables and configurations used for establishing different gRPC channel connections to Camunda (Zeebe) instances, either with or without authentication.
+
+Environment Variables
+---------------------
+
+The following environment variables are used to configure channels. The variables are grouped according to their relevance and usage context in each type of channel.
+
+These variables are only considered if a corresponding argument was not passed (Unset) during initialization of a channel.
+
+Common Variables
+----------------
+
+This variables is used across all types of channels:
+
+**ZEEBE_ADDRESS**
+  :Description:  
+    The default address of the Zeebe Gateway.
+
+  :Usage:        
+    Used in both secure and insecure channel configurations.
+    :func:`pyzeebe.create_insecure_channel`
+    :func:`pyzeebe.create_secure_channel`
+
+  :Default:      
+    ``"localhost:26500"``
+
+Common OAuth2 Variables
+-----------------------
+
+These variables are specifically for connecting to generic OAuth2 or Camunda Cloud instances.
+
+**CAMUNDA_CLIENT_ID** / **ZEEBE_CLIENT_ID**
+  :Description:  
+    The client ID required for OAuth2 client credential authentication.
+
+  :Usage:        
+    Required for OAuth2 and Camunda Cloud channels.
+    :func:`pyzeebe.create_oauth2_client_credentials_channel`
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+**CAMUNDA_CLIENT_SECRET** / **ZEEBE_CLIENT_SECRET**
+  :Description:  
+    The client secret for the OAuth2 client.
+
+  :Usage:        
+    Required for OAuth2 and Camunda Cloud channels.
+    :func:`pyzeebe.create_oauth2_client_credentials_channel`
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+OAuth2 Variables (Self-Managed)
+-------------------------------
+
+These variables are primarily used for OAuth2 authentication in self-managed Camunda 8 instances.
+
+**CAMUNDA_OAUTH_URL** / **ZEEBE_AUTHORIZATION_SERVER_URL**
+  :Description:  
+    Specifies the URL of the authorization server issuing access tokens to the client.
+
+  :Usage:        
+    Required if channel initialization argument was not specified.
+    :func:`pyzeebe.create_oauth2_client_credentials_channel`
+
+**CAMUNDA_TOKEN_AUDIENCE** / **ZEEBE_TOKEN_AUDIENCE**
+  :Description:  
+    Specifies the audience for the OAuth2 token.
+
+  :Usage:        
+    Used when creating OAuth2 or Camunda Cloud channels.
+    :func:`pyzeebe.create_oauth2_client_credentials_channel`
+
+  :Default:      
+    ``None`` if not provided.
+
+Camunda Cloud Variables (SaaS)
+------------------------------
+
+These variables are specifically for connecting to Camunda Cloud instances.
+
+**CAMUNDA_OAUTH_URL** / **ZEEBE_AUTHORIZATION_SERVER_URL**
+  :Description:  
+    Specifies the URL of the authorization server issuing access tokens to the client.
+
+  :Usage:        
+    Used in the OAuth2 and Camunda Cloud channel configurations.
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+  :Default:      
+    ``"https://login.cloud.camunda.io/oauth/token"`` if not specified.
+
+**CAMUNDA_CLUSTER_ID**
+  :Description:  
+    The unique identifier for the Camunda Cloud cluster to connect to.
+
+  :Usage:        
+    Required if channel initialization argument was not specified.
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+**CAMUNDA_CLUSTER_REGION**
+  :Description:  
+    The region where the Camunda Cloud cluster is hosted.
+
+  :Usage:        
+    Required for Camunda Cloud channels.
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+  :Default:      
+    ``"bru-2"`` if not provided.
+
+**CAMUNDA_TOKEN_AUDIENCE** / **ZEEBE_TOKEN_AUDIENCE**
+  :Description:  
+    Specifies the audience for the OAuth2 token.
+
+  :Usage:        
+    Used when creating OAuth2 or Camunda Cloud channels.
+    :func:`pyzeebe.create_camunda_cloud_channel`
+
+  :Default:      
+    ``"zeebe.camunda.io"`` if not provided.
+

docs/channels_quickstart.rst

@@ -19,10 +19,6 @@ This Channel can be configured with the parameters `channel_credentials` and `ch
     You can override the default `channel_options` by passing
     e.g. `channel_options = (("grpc.keepalive_time_ms", 60_000),)` - for a keepalive time of 60 seconds.
 
-
-Pyzeebe provides a couple standard ways to achieve this:
-
-
 Insecure
 --------
 
@@ -151,6 +147,12 @@ Example:
 
 This method use the :py:class:`.Oauth2ClientCredentialsMetadataPlugin` under the hood.
 
+Configuration
+-------------
+
+It is possible to omit any arguments to the channel initialization functions and instead provide environment variables.
+See :doc:`Channels Configuration <channels_configuration>` for additional details.
+
 Custom Oauth2 Authorization Flow
 ---------------------------------
 

docs/channels_reference.rst

@@ -26,3 +26,23 @@ Credentials
     :members:
     :special-members:
     :private-members:
+
+
+Utilities (Environment)
+-----------------------
+
+.. autofunction:: pyzeebe.channel.utils.get_zeebe_address
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_oauth_url
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_client_id
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_client_secret
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_cluster_id
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_cluster_region
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_token_audience
+
+.. autofunction:: pyzeebe.channel.utils.get_camunda_address

pyzeebe/channel/insecure_channel.py

@@ -3,12 +3,12 @@
 import grpc
 
 from pyzeebe.channel.channel_options import get_channel_options
-from pyzeebe.channel.utils import create_address
-from pyzeebe.types import ChannelArgumentType
+from pyzeebe.channel.utils import get_zeebe_address
+from pyzeebe.types import ChannelArgumentType, Unset
 
 
 def create_insecure_channel(
-    grpc_address: str | None = None, channel_options: ChannelArgumentType | None = None
+    grpc_address: str = Unset, channel_options: ChannelArgumentType | None = None
 ) -> grpc.aio.Channel:
     """
     Create an insecure channel
@@ -22,5 +22,7 @@ def create_insecure_channel(
     Returns:
         grpc.aio.Channel: A GRPC Channel connected to the Zeebe gateway.
     """
-    grpc_address = create_address(grpc_address=grpc_address)
+    if grpc_address is Unset:
+        grpc_address = get_zeebe_address()
+
     return grpc.aio.insecure_channel(target=grpc_address, options=get_channel_options(channel_options))