Skip to content

Commit

Permalink
Merge pull request #840 from RizaFarheen/main
Browse files Browse the repository at this point in the history 
Updates
  • Loading branch information
@RizaFarheen
RizaFarheen authored Jan 15, 2025
2 parents 6c9139d + 9f59578 commit 8b5ecc2
Show file tree
Hide file tree
Showing 7 changed files with 122 additions and 164 deletions.
31 changes: 18 additions & 13 deletions docs/developer-guides/getting-started-with-orkes-template-explorer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,37 +5,42 @@ description: "Get started by using the available templates to build your Conduct

# Getting Started with Orkes Template Explorer

Orkes Template Explorer offers a versatile collection of pre-designed templates. These templates are not only ready to use right out of the box but also highly customizable to align with your specific enterprise needs.
Orkes Template Explorer offers a versatile collection of pre-designed workflows as templates. These templates are ready for immediate use and can be customized to meet specific enterprise needs.

In this guide, we'll walk you through the process of getting started with Orkes Templates.
In this guide, you’ll learn how to get started with Orkes Templates.

## Importing Workflow Using Templates
## Importing Workflow From Templates

Follow these steps to import workflows using the template,
To import workflows from the templates:

1. Navigate to **Template Explorer** from the left menu, on your Orkes Conductor cluster.
2. Browse through the templates and choose the one that fits your use case.
3. Click **Import**. You can also get the template repository link directly from here.
1. Go to **Template Explorer** from the left navigation menu on your Conductor cluster.
2. Browse the templates, choose the one that fits your use case, and select **Import**.

<p align="center"><img src="/content/img/workflow-template-explorer.png" alt="Workflow Template Explorer" width="100%" height="auto"/></p>

4. A pop-up displaying the chosen template's task names and workflow names appears. Append the workflow/task name to avoid any duplication.
A pop-up will display the selected template's task and workflow names.

3. To avoid duplication, append the workflow and task names.

<p align="center"><img src="/content/img/importing-workflows-in-workflow-template-explorer.png" alt="Importing Workflows via Workflow Template Explorer" width="40%" height="auto"/></p>

5. Instantly, the workflow gets created, and you can update the required parameters with your credentials.
4. Select **Save**, and the workflow is created instantly.

<p align="center"><img src="/content/img/imported-workflow.png" alt="Imported Workflows via Workflow Template Explorer" width="100%" height="auto"/></p>

6. Execute the workflow using the **Run Workflow** button from the left menu.
5. Refer to the corresponding [template documentation](/content/category/templates) for the configuration updates required.
6. Go to the **Run** tab, provide the input parameters, and select **Run Workflow** to execute the workflow.

With these simple steps, you can generate and execute the workflow in a few minutes, saving you hours.

With these simple steps, you can generate and execute the workflow within seconds, saving you hours.

:::note
To execute certain templates, configuring workers may be necessary. The [Orkes Template](https://github.com/orkes-io/orkes-templates) repository includes these workers, and all you need to do is update the worker with your required credentials. Detailed instructions for updating the repository specific to your template can be found in the corresponding documentation.
Some templates may require setting up workers. These workers are included in the [Orkes Template](https://github.com/orkes-io/orkes-templates) repository and can be updated with your credentials. Refer to the corresponding documentation for detailed instructions.
:::

Refer to the corresponsing documentation for running the templates:
## Template Documentations

For details on running each template, refer to the corresponding documentation:
* [Automatic Subtitle Generator](https://orkes.io/content/templates/automatic-subtitle-generator)
* [StandUp Bot](https://orkes.io/blog/create-standup-bot-using-conductor-slack-integration/)
* [Availability Monitoring for HTTP(S) Endpoints](https://orkes.io/content/templates/availability-monitoring-for-http-endpoints)
Expand Down
191 changes: 73 additions & 118 deletions docs/developer-guides/secrets-in-conductor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,159 +3,114 @@ slug: "/developer-guides/secrets-in-conductor"
description: "Learn how to securely pass sensitive variables using secrets or masked inputs."
---

# Using Secrets

Sensitive information such as usernames, passwords, API keys, and authorization tokens is often required in workflows. To protect this sensitive data, secrets can be used to hide these values on the user interface. Secrets allow you to securely manage and use sensitive information within workflows without exposing it directly.

Watch how we can manage secrets in Orkes Conductor.

<center><iframe width="510" height="300" src="https://www.youtube.com/embed/6qxq7OmzdGI?si=W4QZ4HJy96UKKt7c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen"
mozallowfullscreen="mozallowfullscreen"
msallowfullscreen="msallowfullscreen"
oallowfullscreen="oallowfullscreen"
webkitallowfullscreen="webkitallowfullscreen"></iframe></center>
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Creating Secrets
# Using Secrets

To create and store secrets in Conductor:
Secrets in Conductor allows you to store and use sensitive data, such as usernames, passwords, API keys, and authorization tokens, without exposing it directly in workflow definitions. After storing them as secrets in Conductor, you can reference them by their secret names in the workflows.

1. Navigate to **Definitions > Secrets** from the left menu on your Orkes Conductor cluster. The Secrets page will display all the secrets associated with your account.
2. Click **+ Add secret** button in the top-right corner.
3. Enter the following values:
## Configuring secrets

<p align="center"><img src="/content/img/creating-secret.png" alt="Creating secret in Orkes Conductor" width="50%" height="auto"></img></p>
**To create a secret:**

* **Secret name**: A descriptive name for your secret.
* **Secret value**: The actual value to be stored as a secret.
1. Go to **Definitions** > **Secrets** from the left navigation menu on your Conductor cluster.
2. Select **+ Add secret**.
3. Enter the following details:

4. Click **Add** to save the secret.
| Parameter | Description | Required/Optional |
| --------- | ----------- | ----------------- |
| Secret name | A unique name for the secret. This will be used to refer to the secret in the workflow definitions. | Required. |
| Secret value | The value to be stored as secret. | Required. |

### Using Secrets in Workflow​
4. Select **Add** to save the secret.

Once a secret is created, you can use it in your workflow by referencing it as a variable **${workflow.secrets.secret_name}**, where **secret_name** is the actual name of the secret. This expression retrieves the secret value dynamically during workflow execution, ensuring it is not exposed directly in the workflow definitions.
### Using secrets in workflow​​

Here is an example workflow definition using a secret:
To use a secret in a workflow, use the following expression:

```json
{
"name": "workflow-with-a-secret",
"version": 1,
"tasks": [
{
"name": "sample_task_http",
"taskReferenceName": "sample_task_http",
"inputParameters": {
"http_request": {
"uri": "https://orkes-api-tester.orkesconductor.com/api",
"method": "GET",
"connectionTimeOut": 3000,
"readTimeOut": 3000,
"accept": "application/json",
"contentType": "application/json",
"headers": {
"Authorization": "Bearer: ${workflow.secrets.sampletask-api-token}"
}
}
},
"type": "HTTP"
}
],
"schemaVersion": 2
}
```
${workflow.secrets.secret_name}
```

When this workflow runs, **${workflow.secrets.sampletask-api-token}** will be replaced with the actual secret value, provided the necessary permissions are in place.

### Adding Tags to Secrets​

To add tags to a secret:

1. From the **Definitions > Secrets** page, select the secret to add the tag and click on the tag icon.

<p align="center"><img src="/content/img/adding-tags-to-secret.png" alt="Adding tags to secret in Orkes Conductor" width="100%" height="auto"></img></p>

2. Add the tag in the format **key:value** and click **Save**.

<p align="center"><img src="/content/img/tag-format-secret.png" alt="Tag format for secrets" width="60%" height="auto"></img></p>

Tag-based access control allows you to grant permissions to entities based on the tags. For more information on tag-based permissions, refer to the documentation on [using tags for permissions](https://orkes.io/content/access-control-and-security/tags).


### Updating Secrets

Secrets can be updated in the following ways:
Here, _secret_name_ is the name of the secret saved in Conductor. This expression dynamically retrieves the secret value during workflow execution, ensuring it is not exposed directly in the workflow definition.

#### Using UI
## Updating secrets​

Users with access to the secret can update it directly through the UI.
Secrets can be updated directly from the Conductor UI or using the Update Secret task in a workflow.

1. Navigate to **Definitions > Secrets**, and click on the secret name to be updated.
2. Enter the new value in the **Secret value** field, and click Edit to confirm.
<Tabs>
<TabItem label="Using Conductor UI" value="Using Conductor UI">

The secret value gets instantly updated in the UI.
**To update the secret:**

#### Using Update Secret Task
1. Go to **Definitions** > **Secrets**, and click on the secret you want to update.
2. In **Secret value**, enter the updated value, then click **Edit** to confirm.

Tokens that expire (such as access tokens) require periodic refreshes, which can be managed using a system task to update the secret. The update secret task is used to update the secret value, provided the user has permission to update the secret. Learn more about the configuration of the [update secret task](https://orkes.io/content/reference-docs/system-tasks/update-secret).
<p align="center"><img src="/content/img/updating-secrets.png" alt="Updating secrets via Conductor UI" width="80%" height="auto"></img></p>

## Masking Secret Values
</TabItem>
<TabItem label="Using Update Secret task" value="Using Update Secret task">

When using secret values as inputs/outputs in tasks/workflows, you can manage these values securely by using either **_secrets** or **_masked**.
Updating secrets can be challenging for expiring tokens that need periodic updates. Use the [Update Secret](https://orkes.io/content/reference-docs/system-tasks/update-secret) task in Conductor to replace such secrets within a workflow.

* **Using _secrets:**
</TabItem>
</Tabs>

All values stored in the output object with key name: **_secrets** will be hidden.
## Examples

```json
{
"_secrets" : {
"my-secret-key" : "my-secret-value"
}
}
```
### Using secrets in a workflow

The users with the ability to execute the task will be able to read the task and see its inputs and outputs.
<details><summary>Using secrets in a workflow</summary>

Let’s take an example where you want to hide sensitive data when passing information from one task's output to the input of the next task in a workflow. So, you need to ensure that the input parameters of the subsequent task within the workflow definition are structured in the following manner:
Suppose you have a secret saved with the name _sampletask-api-token_. Here is an example of how to use this secret in a workflow definition:

```json
{
"_secrets":
{ "parameter":"${previousTask.output._secrets.someOutputParameter}"
}
}
// workflow definition
{
"name": "sample_task_http",
"taskReferenceName": "sample_task_http",
"inputParameters": {
"http_request": {
"uri": "https://orkes-api-tester.orkesconductor.com/api",
"method": "GET",
"connectionTimeOut": 3000,
"readTimeOut": 3000,
"accept": "application/json",
"contentType": "application/json",
"headers": {
"Authorization": "Bearer: ${workflow.secrets.sampletask-api-token}"
}
}
},
"type": "HTTP"
}
```

This structure mandates that any input parameter to be hidden must be nested within the **_secrets** object. This approach ensures that sensitive data is masked adequately during the workflow's execution within the designated **_secrets** section of the input parameters.

* **Using _masked:**
When this workflow runs, the expression `${workflow.secrets.sampletask-api-token}` will be dynamically replaced with the actual secret value, provided the user running the workflow has permission to access the secret.

Values stored under the **_masked** key will be automatically masked in the UI and will appear as __***__. For example:
</details>

```json
{
"_masked":{"some":"data"}
}
```
## Use cases

This will be displayed as:
### Storing environment-specific variables as secrets

```json
{
"_masked":"***"
}
```
Secrets in Conductor can store values that vary across different environments, such as development, testing, and production. This allows workflows to seamlessly adapt to the environment in which they are executed without requiring hardcoded changes.
For example, you might have different API keys or database connection strings for testing and production environments. Instead of manually updating the workflow for each environment, you can store these values as secrets and reference them dynamically.

:::note
While **_masked** hides the data in the UI, the original data remains intact and is saved during archiving. Should you restart the workflow, the original data will still be accessible.
**Example:**
* For a testing environment, you can store a secret with the name _testing-api-key_, and reference it in the workflow as `${workflow.secrets.testing-api-key}`.
* For a production environment, store a secret named _production-api-key_, and reference it as `${workflow.secrets.production-api-key}`.
This approach ensures workflows can automatically adapt to the appropriate configuration based on the environment.

However, if you opt for **_secrets** instead of **_masked**, there's a different behavior during archiving. Once the workflow reaches a terminal state and is removed from the primary execution store, any data labeled as _secrets will be permanently replaced with ***. Subsequently, attempting to retry the workflow might lead to failures in tasks reliant on that particular data.
:::
### Token rotation

## Advanced Applications of Secrets
Regular rotation is essential for time-sensitive secrets, such as access tokens. Implementing effective token rotation strategies ensures that tokens remain valid and secure. For more detailed instructions, refer to the guide on [rotating secrets](https://orkes.io/content/templates/examples/rotating-secrets-that-expire).

Secrets in Conductor are versatile and can be used beyond just handling sensitive information. Here are some advanced scenarios for leveraging secrets:
## Video guide

* **Environment-Specific Variables**: Secrets can manage environment-specific configurations, such as different variables between development, testing, and production environments. For example, **${workflow.secrets.env-variable-1}** can be used to define values specific to UAT, production, or any other environment.
* **Dynamic Configuration**: Use secrets to manage dynamic configurations that change based on the execution context or environment. This ensures that workflows can adapt to varying conditions without hardcoding sensitive or environment-specific data directly in the workflow definitions.
* **Token Rotation**: Regular rotation of time-sensitive secrets, such as access tokens, is essential for maintaining security. Implement a strategy to rotate these tokens periodically to ensure they remain valid and secure. For detailed guidance on rotating secrets that expire, refer to the guide on [rotating secrets that expire](https://orkes.io/content/templates/examples/rotating-secrets-that-expire).
<center><iframe width="510" height="300" src="https://www.youtube.com/embed/6qxq7OmzdGI?si=W4QZ4HJy96UKKt7c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen"
mozallowfullscreen="mozallowfullscreen"
msallowfullscreen="msallowfullscreen"
oallowfullscreen="oallowfullscreen"
webkitallowfullscreen="webkitallowfullscreen"></iframe></center>
Loading

0 comments on commit 8b5ecc2

Please sign in to comment.