Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add component yaml configuration definition with connection env renaming guide #1684

Merged
merged 12 commits into from
Jan 28, 2025
Merged

Add component yaml configuration definition with connection env renaming guide #1684

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
a81bf62
Add component yaml configuration definition with connection env renam…
chathuranga95 Jan 8, 2025
0121d32
Merge branch 'dev' of https://github.com/wso2/docs-choreo-dev into co…
chathuranga95 Jan 20, 2025
fe29e02
Improve wording
chathuranga95 Jan 21, 2025
272bce8
Improve wording
chathuranga95 Jan 21, 2025
b09a03f
Improve wording
chathuranga95 Jan 21, 2025
28837ac
Improve wording
chathuranga95 Jan 21, 2025
da89590
Improve wording
chathuranga95 Jan 21, 2025
8dd4a11
Improve wording
chathuranga95 Jan 21, 2025
31851a2
Improve wording
chathuranga95 Jan 21, 2025
5ec4652
Improve wording for the documentation
chathuranga95 Jan 21, 2025
5371696
Update manage-component-source-configurations.md
Nashaath Jan 22, 2025
af06802
Merge branch 'dev' into conn-env-renaming
chathuranga95 Jan 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 64 additions & 32 deletions en/docs/develop-components/manage-component-source-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,15 +59,29 @@ Click the respective tab to view the structure for your current configuration fi
# The path should be relative to the docker context.
schemaFilePath: openapi.yaml

# +optional Outgoing connection details for the component.
dependencies:
# +optional Defines the connection references from the Internal Marketplace.
connectionReferences:
# +required Name of the connection.
- name: hr-connection
# +required service identifer of the dependent component.
resourceRef: service:/HRProject/UserComponent/v1/ad088/PUBLIC

# +optional Outgoing connection details for the component.
dependencies:
# +optional Defines the connection references from the Internal Marketplace.
connectionReferences:
# +required Name of the connection.
- name: hr-connection
# +required service identifer of the dependent component.
resourceRef: service:/HRProject/UserComponent/v1/ad088/PUBLIC
# +optional Defines runtime configurations
configuration:
# +optional List of environment variables to be injected into the component.
env:
# +required Name of the environment variable
- name: HR_SERVICE_URL
# +required value source
# Allowed value sources: connectionRef
valueFrom:
# +required Choreo connection value source
connectionRef:
# +required Choreo connection name to refer the value from
name: hr-connection
# +required Choreo connection configuration key to refer the value from
key: ServiceURL
```

The descriptor-based approach of the `component.yaml` file simplifies and streamlines endpoint and connection configuration management. The use of versioned schemas ensures backward compatibility, providing a seamless transition with future updates.
Expand All @@ -79,6 +93,7 @@ Click the respective tab to view the structure for your current configuration fi
| **schemaVersion** | Required | The version of the `component.yaml` file. Defaults to the latest version.|
| **endpoints** | Optional | The list of endpoint configurations. |
| **dependencies** | Optional | The list of dependency configurations. |
| **configuration** | Optional | The runtime configuration definitions. |

### Endpoint configurations
In the `endpoints` section of the `component.yaml` file, you can define multiple service endpoint configurations. Each endpoint must have a unique name and the required fields specified in the schema overview.
Expand All @@ -91,15 +106,15 @@ Click the respective tab to view the structure for your current configuration fi
| **name** | Required | A unique identifier for the endpoint within the service component. Avoid using excessively long names. |
| **displayName** | Optional | A display name for the endpoint. |
| **service** | Required | Service details for the endpoint. |
|       **.basePath** | Required | The base path of the API exposed via this endpoint. |
|       **.port** | Required | The numeric port value exposed via this endpoint. |
| **.basePath** | Required | The base path of the API exposed via this endpoint. |
| **.port** | Required | The numeric port value exposed via this endpoint. |
| **type** | Required | The type of traffic the endpoint accepts. For example, `REST`, `GraphQL`, `WS`, `gRPC`, `UDP`, or `TCP`.|
| **networkVisibilities** | Required | The network-level visibility of the endpoint. For example, project, organization, or public. |
| **networkVisibilities** | Required | The network-level visibility of the endpoint. For example, project, organization, or public. |
| **schemaFilePath** | Required | The file path to the swagger definition or AsyncAPI 2.0 specification file. Defaults to the wildcard route if not specified. This field should be a relative path to the project path when using **Java**, **Python**, **NodeJS**, **Go**, **PHP**, **Ruby**, or **WSO2 MI** buildpacks. For REST or WebSocket endpoint types, when using the **Ballerina** or **Dockerfile** buildpack, the path should be relative to the component root or Docker context. |

### Dependency configurations

In the `dependencies` section of the `component.yaml` file, you can define multiple connection configurations under `dependencies.connectionReferences`. You can use the connection reference generated in the in-line developer guide when creating a connection. For instructions on copying [connection configurations](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/), see the in-line developer guide displayed during connection creation.
In the `dependencies` section of the `component.yaml` file, you can define multiple connection configurations under `dependencies.connectionReferences`. You can use the connection reference generated in the inline developer guide when creating a connection. For instructions on copying [connection configurations](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/), see the inline developer guide displayed during connection creation.

You must include the following configurations in the `dependencies.connectionReferences` schema:

Expand All @@ -114,6 +129,23 @@ Click the respective tab to view the structure for your current configuration fi

To use custom environment variable names instead of Choreo's default ones, add the dependency as a `serviceReference` in your `component.yaml v1.1` file. You can copy the `serviceReference` section from the `component.yaml v1.0` tab and paste it under `dependencies` in your `component.yaml v1.1` file, which maintains backward compatibility with the v1.0 format.

### Runtime configurations
In the `configuration` section of the `component.yaml` file, you can define runtime configurations for the component. These configurations currently support environment variable injection related to dependencies.

| Configuration | Required | Description |
|-------------------------------|--------------|-----------------------------------------------------------------------------------|
| **env** | Optional | An array of env variable configurations. |
| **name** | Required | A unique name for the environment variable, starting with a letter or an underscore, and containing only letters, numbers, or underscores. |
| **valueFrom** | Required | The source of the environment variable value. |
| **connectionRef** | Required | Connection reference value source definition. |
| **name** | Required | The name of the Choreo connection to reference the value from. |
| **key** | Required | The Choreo connection configuration key to reference the value from. For details on available keys, see [connection configurations](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/) or the inline developer guide. |

!!! note
Runtime configurations are supported starting from `component.yaml v1.1`.

When an environment variable value is specified using `connectionRef`, the connection's environment variable is renamed to the environment variable name defined in the `configuration` section. For example, in the sample `component.yaml` file given above, the `CHOREO_HR_CONNECTION_SERVICEURL` variable in the `hr-connection` is renamed to `HR_SERVICE_URL`.

=== "Version 1.0"

``` yaml
Expand Down Expand Up @@ -178,30 +210,30 @@ Click the respective tab to view the structure for your current configuration fi
!!! tip "Why have a unique name?"
When you define multiple endpoints, the `endpoint.name` is appended to the Choreo-generated URL. A unique name ensures the endpoint is easily recognizable and readable within the URL.

| Configuration | Required | Description |
|----------------------|--------------|---------------------------------------------------------------------------------------------------------|
| **name** | Required | A unique identifier for the endpoint within the service component. Avoid using excessively long names. |
| **displayName** | Optional | A display name for the endpoint. |
| **service** | Required | Service details for the endpoint. |
|       **.basePath** | Required | The base path of the API exposed via this endpoint. |
|       **.port** | Required | The numeric port value exposed via this endpoint. |
| **type** | Required | The type of traffic the endpoint accepts. For example, `REST`, `GraphQL`, `gRPC`, `WS`, `UDP`, or `TCP`.|
| **networkVisibilities** | Required | The network-level visibility of the endpoint. For example, project, organization, or public. |
| **schemaFilePath** | Required | The file path to the swagger definition or AsyncAPI 2.0 specification file. Defaults to the wildcard route if not specified. This field should be a relative path to the project path when using **Java**, **Python**, **NodeJS**, **Go**, **PHP**, **Ruby**, or **WSO2 MI** buildpacks. For REST or WebSocket endpoint types, when using the **Ballerina** or **Dockerfile** buildpack, the path should be relative to the component root or Docker context. |
| Configuration | Required | Description |
|-------------------------|--------------|---------------------------------------------------------------------------------------------------------|
| **name** | Required | A unique identifier for the endpoint within the service component. Avoid using excessively long names. |
| **displayName** | Optional | A display name for the endpoint. |
| **service** | Required | Service details for the endpoint. |
| **.basePath** | Required | The base path of the API exposed via this endpoint. |
| **.port** | Required | The numeric port value exposed via this endpoint. |
| **type** | Required | The type of traffic the endpoint accepts. For example, `REST`, `GraphQL`, `gRPC`, `WS`, `UDP`, or `TCP`.|
| **networkVisibilities** | Required | The network-level visibility of the endpoint. For example, project, organization, or public. |
| **schemaFilePath** | Required | The file path to the swagger definition or AsyncAPI 2.0 specification file. Defaults to the wildcard route if not specified. This field should be a relative path to the project path when using **Java**, **Python**, **NodeJS**, **Go**, **PHP**, **Ruby**, or **WSO2 MI** buildpacks. For REST or WebSocket endpoint types, when using the **Ballerina** or **Dockerfile** buildpack, the path should be relative to the component root or Docker context. |

<h3> Dependency configurations </h3>

In the `dependencies` section of the `component.yaml` file, you can define multiple service connection configurations under `dependencies.serviceReferences`. You can use the service references generated in the in-line developer guide when creating a service connection. For instructions on copying [connection configurations](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/), see the in-line developer guide displayed during connection creation.
In the `dependencies` section of the `component.yaml` file, you can define multiple service connection configurations under `dependencies.serviceReferences`. You can use the service references generated in the inline developer guide when creating a service connection. For instructions on copying [connection configurations](https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/), see the inline developer guide displayed during connection creation.

You must include the following configurations in the `dependencies.serviceReferences` schema:

| Configuration | Required | Description |
|----------------------|--------------|----------------------------------------------------------------------------------|
| **name** | Required | A unique name for the service reference. |
| **connectionConfig** | Required | A unique name for the connection instance. |
| **env** | Required | The list of environment variable mappings to inject into the container. |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**.from** | Required | The key name of the connection configuration. |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**.to** | Required | The environment variable to inject into the container. |
| **env** | Required | The list of environment variable mappings to inject into the container. |
| **.from** | Required | The key name of the connection configuration. |
| **.to** | Required | The environment variable to inject into the container. |

!!! note
Choreo automatically generates connection configurations when you create a connection. The properties such as **name**, **connectionConfig**, and **env.from** are automatically generated. However, you must manually set the **env.to** value.
Expand Down Expand Up @@ -325,14 +357,14 @@ The `endpoints.yaml` configuration file allows you to define configurations for

You can define the following root-level configurations via the `endpoints.yaml` file:

| Configuration | Required | Description |
|----------------------|--------------|----------------------------------------------------------------------------------|
| **version** | Required | The version of the `endpoints.yaml` file. |
| Configuration | Required | Description |
|----------------------|--------------|-----------------------------------------------------------------------------------|
| **version** | Required | The version of the `endpoints.yaml` file. |
| **name** | Required | A unique name for the endpoint, which Choreo will use to generate the managed API.|
| **port** | Required | The numeric port value that gets exposed via this endpoint. |
| **port** | Required | The numeric port value that gets exposed via this endpoint. |
| **type** | Required | The type of traffic this endpoint accepts, such as `REST`, `GraphQL`, `gRPC`, `WS`, `UDP`, or `TCP`. Currently, the MI preset supports only the `REST` type. |
| **networkVisibility**| Required | The network level visibility of this endpoint, which defaults to `Public` if not specified. Accepted values are `Project`, `Organization`, or `Public`.|
| **context** | Required | The context (base path) of the API that Choreo exposes via this endpoint. |
| **context** | Required | The context (base path) of the API that Choreo exposes via this endpoint. |
| **schemaFilePath** | Required | The swagger definition file path. Defaults to the wildcard route if not provided. This field should be a relative path to the project path when using the **Java**, **Python**, **NodeJS**, **Go**, **PHP**, **Ruby**, and **WSO2 MI** buildpacks. For REST endpoint types, when using the **Ballerina** or **Dockerfile** buildpack, this field should be a relative path to the component root or Docker context.|

## Update to the latest source configuration file
Expand Down
16 changes: 14 additions & 2 deletions en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,20 @@ To integrate another service into your application, click the appropriate tab be
| ChoreoAPIKey | CHOREO_<CONNECTION_NAME\>CHOREOAPIKEY |


If you'd like to use custom environment variable names instead of the Choreo-defined ones, add the dependency as a service reference under `dependencies` in the same file. For more details, refer to the instructions under the `component.yaml file (v1.0)` tab.
If you want to use custom environment variable names instead of the Choreo-defined ones, you must define the environment configurations under the `configuration` section in the same file.
The following is a sample snippet:

``` yaml
configuration:
env:
- name: HR_SERVICE_URL
valueFrom:
connectionRef:
name: hr-connection
key: ServiceURL
```

The following table provides details on the configuration keys associated with the connection:
The following table provides details on the configuration keys associated with the connection. These keys can be referenced as `env[i].valueFrom.connectionRef.key`.

| Name | Type | Description |Optional | Sensitive |
|----------------|------------|---------------------------------------|---------------|--------------|
Expand All @@ -61,6 +71,8 @@ To integrate another service into your application, click the appropriate tab be
| TokenURL | string | Token URL of the STS | false | false |
| ChoreoAPIKey | string | API key of the Choreo service | false | true |

For more details, see the instructions under the **component.yaml file (v1.1)** tab.

### Step 2: Read configurations within the application

Once you add the connection configuration snippet, you can proceed to read those configurations within your application. The steps to follow depend on the programming language you are using.
Expand Down